Files
crank/scripts/validate-capability-inventory.py
bsodfather 54ce770682
CI / Rust Checks (pull_request) Failing after 13m41s
CI / UI Checks (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Deploy (pull_request) Skipped
Community Release / release (push) Failing after 13m33s
feat(epic3): deliver the accepted Epic 3 scope through Story 3.17
Recovery delivery of the accumulated, TL-accepted Epic 3 work that had never been
committed to Git (stories 3.6-3.17, see the crank board). Story 3.18 is not accepted
yet and is deliberately excluded: its logging surface, its capability registration,
its oracle projections and its tests are not part of this tree.

Accepted scope
- 3.6 typed static Resource Drafts; 3.7 publication and exact binding of static
  Resource Versions; 3.8 MCP discovery/read and revocation of static Resources;
- 3.9 Resource import/export in API and UI plus TLS dependency maintenance;
  3.10 REST-backed Resource templates; 3.11 shared REST read runtime and the MCP
  revision/capability foundation;
- 3.12 parameterised Prompt Drafts with preview; 3.13 Prompt publication and exact
  version binding to Agents; 3.14 MCP prompts; 3.15 Prompt import/export;
- 3.16 composite Prompts with published Resources (dependency content scan plus
  dynamic read through the accepted 3.11 runtime, admin preview and MCP prompts/get);
- 3.17 bounded MCP completion suggestions from typed published schemas and the
  resources/list admission fix for bound template publications.

Accepted evidence being reused (unchanged code paths)
- 3.16 candidate: core 7, admin-api 22, registry 4, mcp-server 4, UI 6; one final
  `just verify` run 1651 passed / 0 failed / 2 ignored.
- 3.17 candidate: full run 1672 passed / 0 failed / 2 ignored, QA targeted reruns and
  a real MCP Inspector 2.12.0 client smoke.

Delivery engineering in this commit
- CI: one event per change (feature branches are gated by their pull request, push
  runs only on main), story events run the changed packages, the full workspace suite
  stays the feature/release gate; no cache/sharding without a measured runner check.
- Release: the packaged archives, checksums and SBOM are now uploaded to the Gitea
  release entry of the tag instead of dying with the runner workspace.

Not included on purpose: Story 3.18 work, build caches, runtime databases, local
credentials and scratch evidence.

Refs: crank kanban t_e39d7263; baseline 1b6db09bd1.
2026-10-25 09:08:22 +00:00

2405 lines
106 KiB
Python

#!/usr/bin/env python3
"""Validate the versioned Crank Community Capability Inventory contract.
Two separated gates over one canonical artifact (accepted SPEC `remaining-ac-spec.md` section 5):
* `--mode validity` (default) - Gate A: structural contract, revision provenance, per-surface identity
and completeness against the reviewed source-backed accounting, per-revision override resolution and
advertisement truthfulness. A truthful `deferred` passes.
* `--mode feature-complete` - Gate B: evaluated **only** after steps 0 and 1 passed; it blocks when an
applicable stable `deferred` surface remains and is never part of the routine `just verify`.
The flow vocabulary (`implemented|planned|gap|blocked`) is unchanged and never mapped into the protocol
vocabulary (`supported|not_applicable|experimental|deferred`). `schema_version: 1` documents (flow-only)
keep validating exactly as before.
"""
from __future__ import annotations
import argparse
import heapq
import json
import re
import sys
from dataclasses import dataclass
from pathlib import Path, PurePosixPath
from typing import Any, Iterable, Iterator
SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"
MAX_DOCUMENT_BYTES = 4_194_304
MAX_FLOWS = 10_000
MAX_REQUIREMENTS_PER_FLOW = 64
MAX_CAPABILITIES_PER_FLOW = 16
MAX_EVIDENCE_LINKS_PER_KIND = 64
MAX_ID_LENGTH = 128
MAX_REQUIREMENT_LENGTH = 128
MAX_CAPABILITY_LENGTH = 128
MAX_OWNER_LENGTH = 256
MAX_SUBFEATURE_ITEMS = 64
MAX_SUBFEATURE_LENGTH = 256
MAX_OUTCOME_LENGTH = 4_096
MAX_NOTES_LENGTH = 4_096
MAX_EVIDENCE_PATH_LENGTH = 1_024
MAX_PROTOCOL_CAPABILITIES = 256
MAX_DIAGNOSTICS = 1_000
MAX_REPORT_BYTES = 65_536
FLOW_TYPES = ("ui", "api", "mcp")
FLOW_STATUSES = ("implemented", "planned", "gap", "blocked")
ALLOWED_CAPABILITIES = ("tools", "resources", "prompts", "tasks", "load_runs")
FORBIDDEN_CAPABILITIES = (
"multi_workspace", # community-scope: allow=multi-workspace
"enterprise_rbac", # community-scope: allow=enterprise
"sso", # community-scope: allow=sso
"non_rest_upstream", # community-scope: allow=non-rest-upstream
"arbitrary_distributed_load_targets", # community-scope: allow=distributed-load-targets
)
PROTOCOL_STATUSES = ("supported", "not_applicable", "experimental", "deferred")
PROTOCOL_KINDS = ("capability", "method", "notification", "extension")
PROTOCOL_ROLES = ("server", "client", "both")
PROTOCOL_APPLICABILITIES = ("stable", "deprecated", "extension")
PROTOCOL_REVISION_ORDER = ("2026-07-28", "2025-11-25")
PROTOCOL_WITHDRAWN = ("2025-06-18", "2025-03-26")
# The single canonical product identity of this inventory (schema `product: const`). A foreign
# identity is not part of the accepted v1 flow-only compatibility: documenting another product in
# this artifact is a structural error, not a legacy shape.
PRODUCT_ID = "crank-community"
PROTOCOL_FIELDS = frozenset(
{"selected_on", "source_basis", "revisions", "withdrawn", "capabilities"}
)
REVISION_FIELDS = frozenset(
{"revision", "role", "lifecycle", "session", "required_methods", "provenance"}
)
PROVENANCE_FIELDS = ("locator", "sha256", "captured_on")
CAPABILITY_FIELDS = frozenset(
{
"surface",
"kind",
"role",
"status",
"applicability",
"revisions",
"subfeatures",
"open_subfeatures",
"advertised",
"owner",
"fallback",
"evidence_target",
"reason",
"requirement",
"per_revision",
}
)
ADVERTISABLE_KINDS = frozenset({"capability", "extension"})
# The enum-valued fields a `per_revision[rev]` override may redeclare; every other key is rejected.
OVERRIDE_ENUM_FIELDS: dict[str, tuple[str, ...]] = {
"status": PROTOCOL_STATUSES,
"role": PROTOCOL_ROLES,
"kind": PROTOCOL_KINDS,
"applicability": PROTOCOL_APPLICABILITIES,
}
# Rule O1 (accepted SPEC section 5): exactly these fields may be redeclared per revision.
OVERRIDE_ALLOWED_FIELDS = frozenset(
{
"status",
"applicability",
"role",
"reason",
"fallback",
"evidence_target",
"owner",
"requirement",
"subfeatures",
"open_subfeatures",
"advertised",
}
)
# The non-overridable structural fields of a capability entry: identity and applicability scope.
# A per-revision override that narrows/widens `revisions[]` (or renames the identity) used to move a
# truthfully deferred document from B3 to a false `complete` (F1), so it is a Gate A error and the
# effective entry always resolves those fields from the default.
OVERRIDE_FORBIDDEN_FIELDS = CAPABILITY_FIELDS - OVERRIDE_ALLOWED_FIELDS - {"per_revision"}
# The pinned structural fields of one revision-ledger entry (accepted SPEC section 5): the two
# approved revisions declare an exact role/lifecycle/required-method contract. Deleting any of them
# used to leave a syntactically valid ledger that no longer describes a reviewed revision (F3).
REVISION_CONTRACT: dict[str, dict[str, Any]] = {
"2026-07-28": {
"role": "modern-stateless",
"lifecycle": "stateless",
"required_methods": ("server/discover",),
},
"2025-11-25": {
"role": "legacy-session",
"lifecycle": "initialize+session",
"required_methods": ("initialize", "notifications/initialized"),
},
}
PROTOCOL_CAPABILITY_REQUIRED = frozenset(
{
"surface",
"kind",
"role",
"status",
"applicability",
"revisions",
"subfeatures",
"open_subfeatures",
"advertised",
"owner",
"fallback",
"evidence_target",
"requirement",
}
)
# Reviewed source-backed accounting (the completeness basis agreed with the accepted SPEC section 5).
# `surface-inventory.md` fixes the `(role, kind, surface)` triple set read out of the two pinned
# revision schemas; the reviewed status column of the owner-approved two-revision window is part of the
# same reviewed basis. Matching is by the exact triple; a `both` row satisfies both reviewed sender
# roles. The reviewed *deferral* accounting is also the truthfulness boundary of Gate A: a surface the
# review recorded as applicable, scheduled work must not be relabelled `not_applicable` (forward
# progress, e.g. a hypothetical `supported` completion, is not a validity error - that is Gate B).
REVIEWED_SURFACE_STATUS: dict[tuple[str, str, str], str] = {
("server", "capability", "experimental"): "not_applicable",
("server", "capability", "logging"): "deferred",
("server", "capability", "completions"): "deferred",
("server", "capability", "prompts"): "deferred",
("server", "capability", "resources"): "deferred",
("server", "capability", "tools"): "supported",
("server", "capability", "extensions"): "not_applicable",
("server", "capability", "tasks"): "deferred",
("client", "capability", "experimental"): "not_applicable",
("client", "capability", "roots"): "not_applicable",
("client", "capability", "sampling"): "not_applicable",
("client", "capability", "elicitation"): "supported",
("client", "capability", "extensions"): "not_applicable",
("client", "capability", "tasks"): "deferred",
("client", "method", "tools/list"): "supported",
("client", "method", "tools/call"): "supported",
("client", "method", "resources/list"): "deferred",
("client", "method", "resources/read"): "deferred",
("client", "method", "resources/templates/list"): "deferred",
("client", "method", "resources/subscribe"): "deferred",
("client", "method", "resources/unsubscribe"): "deferred",
("client", "method", "prompts/list"): "deferred",
("client", "method", "prompts/get"): "deferred",
("client", "method", "completion/complete"): "deferred",
("client", "method", "logging/setLevel"): "deferred",
("client", "method", "initialize"): "supported",
("both", "method", "ping"): "supported",
("client", "method", "server/discover"): "supported",
("client", "method", "subscriptions/listen"): "not_applicable",
("server", "method", "roots/list"): "not_applicable",
("server", "method", "sampling/createMessage"): "not_applicable",
("server", "method", "elicitation/create"): "not_applicable",
("both", "method", "tasks/get"): "deferred",
("both", "method", "tasks/list"): "deferred",
("both", "method", "tasks/result"): "deferred",
("both", "method", "tasks/cancel"): "deferred",
("server", "notification", "notifications/tools/list_changed"): "deferred",
("server", "notification", "notifications/resources/list_changed"): "deferred",
("server", "notification", "notifications/prompts/list_changed"): "deferred",
("server", "notification", "notifications/resources/updated"): "deferred",
("server", "notification", "notifications/progress"): "deferred",
("server", "notification", "notifications/message"): "deferred",
("server", "notification", "notifications/subscriptions/acknowledged"): "not_applicable",
("both", "notification", "notifications/cancelled"): "not_applicable",
("client", "notification", "notifications/initialized"): "supported",
("client", "notification", "notifications/roots/list_changed"): "not_applicable",
("both", "notification", "notifications/tasks/status"): "deferred",
("server", "notification", "notifications/elicitation/complete"): "not_applicable",
("server", "extension", "io.modelcontextprotocol/tasks"): "deferred",
("client", "extension", "io.modelcontextprotocol/oauth-client-credentials"): "not_applicable",
}
# Reviewed per-era absence basis (`surface-inventory.md` sections 3-7, "absent" cells). Rule O2 makes a
# surface whose `revisions[]` does not contain the era *absent* in that era (never `not_applicable`), so
# the applicable set of an era is the reviewed default union minus these rows - never the 50-identity
# union.
REVIEWED_ABSENT_MODERN: frozenset[tuple[str, str, str]] = frozenset(
{
("server", "capability", "tasks"),
("client", "capability", "tasks"),
("client", "method", "resources/subscribe"),
("client", "method", "resources/unsubscribe"),
("client", "method", "logging/setLevel"),
("client", "method", "initialize"),
("both", "method", "ping"),
("both", "method", "tasks/get"),
("both", "method", "tasks/list"),
("both", "method", "tasks/result"),
("both", "method", "tasks/cancel"),
("client", "notification", "notifications/initialized"),
("client", "notification", "notifications/roots/list_changed"),
("both", "notification", "notifications/tasks/status"),
("server", "notification", "notifications/elicitation/complete"),
}
)
REVIEWED_ABSENT_LEGACY: frozenset[tuple[str, str, str]] = frozenset(
{
("server", "capability", "extensions"),
("client", "capability", "extensions"),
("client", "method", "server/discover"),
("client", "method", "subscriptions/listen"),
("server", "notification", "notifications/subscriptions/acknowledged"),
("server", "extension", "io.modelcontextprotocol/tasks"),
("client", "extension", "io.modelcontextprotocol/oauth-client-credentials"),
}
)
# The single reviewed per-era identity substitution (`notifications/progress`: sender `server` in the
# modern window, `both` in the legacy window; `surface-inventory.md` sections 2.1/6).
REVIEWED_PROGRESS_DEFAULT = ("server", "notification", "notifications/progress")
REVIEWED_PROGRESS_PER_ERA: dict[str, tuple[str, str, str]] = {
"2026-07-28": ("server", "notification", "notifications/progress"),
"2025-11-25": ("both", "notification", "notifications/progress"),
}
# Reviewed session/lifecycle contract of the two approved revisions: the modern window is stateless, the
# legacy window negotiates a session.
REVIEWED_SESSION_BY_REVISION: dict[str, bool] = {"2026-07-28": False, "2025-11-25": True}
# The reviewed `@deprecated` tags of the pinned revision schemas (`surface-inventory.md` section 8):
# exactly six modern-window markers (SEP-2577) and none in the legacy window. Applicability is a
# reviewed statement about those pinned bytes, not a free label: a per-era applicability that
# contradicts this basis used to remove truthfully deferred work from the Gate B accounting (G1).
REVIEWED_DEPRECATED_PER_ERA: dict[str, frozenset[tuple[str, str, str]]] = {
"2026-07-28": frozenset(
{
("server", "capability", "logging"),
("server", "notification", "notifications/message"),
("client", "capability", "roots"),
("server", "method", "roots/list"),
("client", "capability", "sampling"),
("server", "method", "sampling/createMessage"),
}
),
"2025-11-25": frozenset(),
}
# The exact `advertised` leaf types of the pinned revision schemas that this ledger actually declares
# (`reviewed-inputs/2026-07-28-schema.ts`: `ServerCapabilities.tools.listChanged?: boolean`). The
# fragment oracle is exact, so a leaf of another JSON type is not the pinned advertisement (G4).
PINNED_ADVERTISEMENT_LEAVES: dict[str, type] = {
"tools.listChanged": bool,
}
# The reviewed `subfeatures`/`open` accounting of the two pinned revision schemas
# (`surface-inventory.md` sections 3-4, rule U3): the named sub-keys the pinned schema declares for a
# capability row (in declaration order) and whether the pinned value is typed as an open map. The
# *declared* `subfeatures`/`open_subfeatures` of a capability record is compared with this basis per
# era, because a self-declared key used to legitimize an advertised leaf the pinned schema does not
# declare (`tools.subfeatures = ["invented"]` + `advertised = {"tools": {"invented": true}}`) for both
# eras. Only the reviewed capability rows are pinned here: the open maps (`experimental`, server/client
# `extensions`) stay open, the modern `roots` object stays empty while legacy declares `listChanged`, and
# the two `tasks` rows keep their own per-side sub-keys.
REVIEWED_SUBFEATURE_BASIS: dict[tuple[str, str, str], tuple[tuple[str, ...], bool]] = {
("2026-07-28", "server", "experimental"): ((), True),
("2026-07-28", "server", "logging"): ((), False),
("2026-07-28", "server", "completions"): ((), False),
("2026-07-28", "server", "prompts"): (("listChanged",), False),
("2026-07-28", "server", "resources"): (("subscribe", "listChanged"), False),
("2026-07-28", "server", "tools"): (("listChanged",), False),
("2026-07-28", "server", "extensions"): ((), True),
("2026-07-28", "client", "experimental"): ((), True),
("2026-07-28", "client", "roots"): ((), False),
("2026-07-28", "client", "sampling"): (("context", "tools"), False),
("2026-07-28", "client", "elicitation"): (("form", "url"), False),
("2026-07-28", "client", "extensions"): ((), True),
("2025-11-25", "server", "experimental"): ((), True),
("2025-11-25", "server", "logging"): ((), False),
("2025-11-25", "server", "completions"): ((), False),
("2025-11-25", "server", "prompts"): (("listChanged",), False),
("2025-11-25", "server", "resources"): (("subscribe", "listChanged"), False),
("2025-11-25", "server", "tools"): (("listChanged",), False),
("2025-11-25", "server", "tasks"): (("list", "cancel", "requests.tools.call"), False),
("2025-11-25", "client", "experimental"): ((), True),
("2025-11-25", "client", "roots"): (("listChanged",), False),
("2025-11-25", "client", "sampling"): (("context", "tools"), False),
("2025-11-25", "client", "elicitation"): (("form", "url"), False),
("2025-11-25", "client", "tasks"): (
("list", "cancel", "requests.sampling.createMessage", "requests.elicitation.create"),
False,
),
}
def reviewed_applicability(triple: tuple[str, str, str], revision: str) -> str:
"""The applicability the pinned revision bytes state for one reviewed applicable identity (G1)."""
if triple in REVIEWED_DEPRECATED_PER_ERA.get(revision, frozenset()):
return "deprecated"
if triple[1] == "extension":
return "extension"
return "stable"
def reviewed_applicable_identities(revision: str) -> frozenset[tuple[str, str, str]]:
"""The reviewed applicable `(role, kind, surface)` basis of one era (eligibility first, then O2)."""
absent = REVIEWED_ABSENT_MODERN if revision == "2026-07-28" else REVIEWED_ABSENT_LEGACY
base = frozenset(REVIEWED_SURFACE_STATUS) - absent - {REVIEWED_PROGRESS_DEFAULT}
return base | {REVIEWED_PROGRESS_PER_ERA[revision]}
def advertisement_key(kind: Any, surface: Any) -> Any:
"""The top-level `capabilities` key an advertisable surface declares its fragment under (spec 5/A1)."""
if kind == "extension":
return "extensions"
return surface
TOP_LEVEL_FIELDS = frozenset({"schema_version", "product", "flows", "protocol"})
FLOW_FIELDS = frozenset(
{
"id",
"type",
"requirements",
"user_outcome",
"owner",
"status",
"capabilities",
"evidence",
"notes",
}
)
EVIDENCE_FIELDS = frozenset({"automated", "manual"})
SCHEMA_ALLOWED_KEYS: dict[tuple[str, ...], frozenset[str]] = {
(): frozenset(
{
"$schema",
"$id",
"title",
"type",
"additionalProperties",
"required",
"properties",
"$defs",
}
),
("properties",): frozenset({"schema_version", "product", "flows", "protocol"}),
("properties", "schema_version"): frozenset({"const"}),
("properties", "product"): frozenset({"const"}),
("properties", "flows"): frozenset({"type", "minItems", "maxItems", "items"}),
("properties", "flows", "items"): frozenset({"$ref"}),
("properties", "protocol"): frozenset({"$ref"}),
("$defs",): frozenset(
{"flow", "evidence", "evidencePaths", "protocol", "revision", "revisionProvenance", "protocolCapability"}
),
("$defs", "flow"): frozenset(
{"type", "additionalProperties", "required", "properties"}
),
("$defs", "flow", "properties"): FLOW_FIELDS,
("$defs", "flow", "properties", "id"): frozenset(
{"type", "minLength", "maxLength", "pattern"}
),
("$defs", "flow", "properties", "type"): frozenset({"enum"}),
("$defs", "flow", "properties", "requirements"): frozenset(
{"type", "minItems", "maxItems", "uniqueItems", "items"}
),
("$defs", "flow", "properties", "requirements", "items"): frozenset(
{"type", "minLength", "maxLength", "pattern"}
),
("$defs", "flow", "properties", "user_outcome"): frozenset(
{"type", "minLength", "maxLength", "pattern"}
),
("$defs", "flow", "properties", "owner"): frozenset(
{"type", "minLength", "maxLength", "pattern"}
),
("$defs", "flow", "properties", "status"): frozenset({"enum"}),
("$defs", "flow", "properties", "capabilities"): frozenset(
{"type", "minItems", "maxItems", "uniqueItems", "items"}
),
("$defs", "flow", "properties", "capabilities", "items"): frozenset({"enum"}),
("$defs", "flow", "properties", "evidence"): frozenset({"$ref"}),
("$defs", "flow", "properties", "notes"): frozenset({"type", "maxLength"}),
("$defs", "evidence"): frozenset(
{"type", "additionalProperties", "required", "properties"}
),
("$defs", "evidence", "properties"): EVIDENCE_FIELDS,
("$defs", "evidence", "properties", "automated"): frozenset({"$ref"}),
("$defs", "evidence", "properties", "manual"): frozenset({"$ref"}),
("$defs", "evidencePaths"): frozenset(
{"type", "minItems", "maxItems", "uniqueItems", "items"}
),
("$defs", "evidencePaths", "items"): frozenset(
{"type", "minLength", "maxLength", "pattern"}
),
("$defs", "protocol"): frozenset(
{"type", "additionalProperties", "required", "properties"}
),
("$defs", "protocol", "properties"): PROTOCOL_FIELDS,
("$defs", "protocol", "properties", "selected_on"): frozenset(
{"type", "minLength", "maxLength", "pattern"}
),
("$defs", "protocol", "properties", "source_basis"): frozenset(
{"type", "minLength", "maxLength", "pattern"}
),
("$defs", "protocol", "properties", "revisions"): frozenset(
{"type", "minItems", "maxItems", "items"}
),
("$defs", "protocol", "properties", "revisions", "items"): frozenset({"$ref"}),
("$defs", "protocol", "properties", "withdrawn"): frozenset(
{"type", "minItems", "maxItems", "uniqueItems", "items"}
),
("$defs", "protocol", "properties", "withdrawn", "items"): frozenset(
{"type", "minLength", "maxLength"}
),
("$defs", "protocol", "properties", "capabilities"): frozenset(
{"type", "minItems", "maxItems", "items"}
),
("$defs", "protocol", "properties", "capabilities", "items"): frozenset({"$ref"}),
("$defs", "revision"): frozenset({"type", "additionalProperties", "required", "properties"}),
("$defs", "revision", "properties"): REVISION_FIELDS,
("$defs", "revision", "properties", "revision"): frozenset(
{"type", "minLength", "maxLength", "pattern"}
),
("$defs", "revision", "properties", "role"): frozenset({"type", "minLength", "maxLength"}),
("$defs", "revision", "properties", "lifecycle"): frozenset(
{"type", "minLength", "maxLength"}
),
("$defs", "revision", "properties", "session"): frozenset({"type"}),
("$defs", "revision", "properties", "required_methods"): frozenset(
{"type", "minItems", "maxItems", "uniqueItems", "items"}
),
("$defs", "revision", "properties", "required_methods", "items"): frozenset(
{"type", "minLength", "maxLength"}
),
("$defs", "revision", "properties", "provenance"): frozenset({"$ref"}),
("$defs", "revisionProvenance"): frozenset(
{"type", "additionalProperties", "required", "properties"}
),
("$defs", "revisionProvenance", "properties"): frozenset(PROVENANCE_FIELDS),
("$defs", "revisionProvenance", "properties", "locator"): frozenset(
{"type", "minLength", "maxLength", "pattern"}
),
("$defs", "revisionProvenance", "properties", "sha256"): frozenset({"type", "pattern"}),
("$defs", "revisionProvenance", "properties", "captured_on"): frozenset(
{"type", "pattern"}
),
("$defs", "protocolCapability"): frozenset(
{"type", "additionalProperties", "required", "properties"}
),
("$defs", "protocolCapability", "properties"): CAPABILITY_FIELDS,
("$defs", "protocolCapability", "properties", "surface"): frozenset(
{"type", "minLength", "maxLength"}
),
("$defs", "protocolCapability", "properties", "kind"): frozenset({"enum"}),
("$defs", "protocolCapability", "properties", "role"): frozenset({"enum"}),
("$defs", "protocolCapability", "properties", "status"): frozenset({"enum"}),
("$defs", "protocolCapability", "properties", "applicability"): frozenset({"enum"}),
("$defs", "protocolCapability", "properties", "revisions"): frozenset(
{"type", "minItems", "maxItems", "uniqueItems", "items"}
),
("$defs", "protocolCapability", "properties", "revisions", "items"): frozenset(
{"type", "minLength", "maxLength"}
),
("$defs", "protocolCapability", "properties", "subfeatures"): frozenset(
{"type", "maxItems", "uniqueItems", "items"}
),
("$defs", "protocolCapability", "properties", "subfeatures", "items"): frozenset(
{"type", "minLength", "maxLength"}
),
("$defs", "protocolCapability", "properties", "open_subfeatures"): frozenset({"type"}),
("$defs", "protocolCapability", "properties", "advertised"): frozenset({"type"}),
("$defs", "protocolCapability", "properties", "owner"): frozenset(
{"type", "minLength", "maxLength", "pattern"}
),
("$defs", "protocolCapability", "properties", "fallback"): frozenset(
{"type", "minLength", "maxLength"}
),
("$defs", "protocolCapability", "properties", "evidence_target"): frozenset(
{"type", "minLength", "maxLength"}
),
("$defs", "protocolCapability", "properties", "reason"): frozenset(
{"type", "minLength", "maxLength"}
),
("$defs", "protocolCapability", "properties", "requirement"): frozenset(
{"type", "pattern"}
),
("$defs", "protocolCapability", "properties", "per_revision"): frozenset({"type"}),
}
FLOW_ID = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
REQUIREMENT_ID = re.compile(r"^FR-[1-9][0-9]*$")
REVISION_DATE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
SHA256_HEX = re.compile(r"^[0-9a-f]{64}$")
NON_WHITESPACE_PATTERN = r"[\s\S]*\S[\s\S]*"
EVIDENCE_PATH_PATTERN = r"^(?!/)(?!.*//)(?!.*(?:^|/)\.\.?($|/))(?!.*\\).+$"
@dataclass(frozen=True, order=True)
class Diagnostic:
code: str
pointer: str
message: str
@dataclass(frozen=True)
class _ReverseDiagnostic:
diagnostic: Diagnostic
def __lt__(self, other: "_ReverseDiagnostic") -> bool:
return self.diagnostic > other.diagnostic
class DiagnosticCollector:
"""Retain only the lexicographically first diagnostics with an exact omitted count."""
def __init__(self) -> None:
self._heap: list[_ReverseDiagnostic] = []
self.total = 0
def append(self, diagnostic: Diagnostic) -> None:
self.total += 1
wrapped = _ReverseDiagnostic(diagnostic)
if len(self._heap) < MAX_DIAGNOSTICS:
heapq.heappush(self._heap, wrapped)
elif diagnostic < self._heap[0].diagnostic:
heapq.heapreplace(self._heap, wrapped)
def extend(self, diagnostics: Iterable[Diagnostic] | "DiagnosticCollector") -> None:
if isinstance(diagnostics, DiagnosticCollector):
for diagnostic in diagnostics.ordered():
self.append(diagnostic)
self.total += diagnostics.omitted
return
for diagnostic in diagnostics:
self.append(diagnostic)
@property
def omitted(self) -> int:
return self.total - len(self._heap)
def ordered(self) -> list[Diagnostic]:
return sorted(item.diagnostic for item in self._heap)
def __bool__(self) -> bool:
return self.total > 0
class DuplicateJsonMemberError(ValueError):
pass
def reject_duplicate_json_members(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
value: dict[str, Any] = {}
for key, item in pairs:
if key in value:
raise DuplicateJsonMemberError("duplicate JSON object member")
value[key] = item
return value
def reject_nonstandard_json_constant(_: str) -> None:
raise ValueError("non-standard JSON numeric constant")
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--root", type=Path, default=Path.cwd())
parser.add_argument("--inventory", required=True)
parser.add_argument("--schema", required=True)
parser.add_argument("--required-fr", action="append", default=[])
parser.add_argument(
"--mode",
choices=("validity", "feature-complete"),
default="validity",
help=(
"validity (default, Gate A: accepts a truthful deferred) or feature-complete "
"(Gate B: blocks an applicable stable deferred; not part of the routine verify)"
),
)
parser.add_argument(
"--report",
default=None,
help="optional bounded JSON report path for the selected mode",
)
return parser.parse_args()
def path_has_symlink(root: Path, logical: PurePosixPath) -> bool:
current = root
for part in logical.parts:
current = current / part
if current.is_symlink():
return True
return False
def resolve_regular_file(root: Path, raw: str) -> Path | None:
if not raw or len(raw) > MAX_EVIDENCE_PATH_LENGTH or "\\" in raw:
return None
logical = PurePosixPath(raw)
if logical.is_absolute() or any(part in {"", ".", ".."} for part in logical.parts):
return None
if str(logical) != raw or path_has_symlink(root, logical):
return None
candidate = root.joinpath(*logical.parts)
try:
resolved = candidate.resolve(strict=True)
resolved.relative_to(root)
except (FileNotFoundError, OSError, RuntimeError, ValueError):
return None
if not resolved.is_file():
return None
return resolved
def read_json_document(
root: Path,
raw_path: str,
invalid_code: str,
) -> tuple[Any | None, Diagnostic | None]:
path = resolve_regular_file(root, raw_path)
pointer = "/schema" if invalid_code == "INVALID_SCHEMA" else "/inventory"
if path is None:
return None, Diagnostic(invalid_code, pointer, "document path is unavailable")
try:
if path.stat().st_size > MAX_DOCUMENT_BYTES:
return None, Diagnostic("INPUT_TOO_LARGE", pointer, "document exceeds limit")
data = path.read_bytes()
if len(data) > MAX_DOCUMENT_BYTES:
return None, Diagnostic("INPUT_TOO_LARGE", pointer, "document exceeds limit")
text = data.decode("utf-8")
return (
json.loads(
text,
object_pairs_hook=reject_duplicate_json_members,
parse_constant=reject_nonstandard_json_constant,
),
None,
)
except (OSError, UnicodeDecodeError, ValueError, RecursionError, json.JSONDecodeError):
return None, Diagnostic(invalid_code, pointer, "document is not valid UTF-8 JSON")
def nested(document: Any, *parts: str) -> Any:
current = document
for part in parts:
if not isinstance(current, dict) or part not in current:
return None
current = current[part]
return current
def contract_values_equal(actual: Any, expected: Any) -> bool:
if isinstance(expected, list):
return (
isinstance(actual, list)
and all(isinstance(item, str) for item in actual)
and len(actual) == len(set(actual))
and set(actual) == set(expected)
)
return type(actual) is type(expected) and actual == expected
def validate_required_keyword(
schema: dict[str, Any], parts: tuple[str, ...], expected: frozenset[str]
) -> list[Diagnostic]:
raw = nested(schema, *parts)
valid = (
isinstance(raw, list)
and all(isinstance(item, str) for item in raw)
and len(raw) == len(set(raw))
and set(raw) == expected
)
if valid:
return []
return [
Diagnostic(
"INVALID_SCHEMA_CONTRACT",
"/schema/" + "/".join(parts),
"required fields differ from validator",
)
]
def validate_schema_contract(schema: Any) -> list[Diagnostic]:
expected: list[tuple[tuple[str, ...], Any]] = [
(("$schema",), SCHEMA_DIALECT),
(("$id",), "https://crank.local/schemas/capability-inventory.schema.json"),
(("title",), "Crank Community Capability Inventory"),
(("type",), "object"),
(("additionalProperties",), False),
(("properties", "schema_version", "const"), 2),
(("properties", "product", "const"), "crank-community"),
(("properties", "flows", "type"), "array"),
(("properties", "flows", "maxItems"), MAX_FLOWS),
(("properties", "flows", "minItems"), 1),
(("properties", "flows", "items", "$ref"), "#/$defs/flow"),
(("properties", "protocol", "$ref"), "#/$defs/protocol"),
(("$defs", "flow", "type"), "object"),
(("$defs", "flow", "additionalProperties"), False),
(("$defs", "flow", "properties", "id", "type"), "string"),
(("$defs", "flow", "properties", "id", "minLength"), 1),
(("$defs", "flow", "properties", "id", "maxLength"), MAX_ID_LENGTH),
(("$defs", "flow", "properties", "id", "pattern"), FLOW_ID.pattern),
(("$defs", "flow", "properties", "type", "enum"), list(FLOW_TYPES)),
(("$defs", "flow", "properties", "status", "enum"), list(FLOW_STATUSES)),
(
("$defs", "flow", "properties", "requirements", "maxItems"),
MAX_REQUIREMENTS_PER_FLOW,
),
(("$defs", "flow", "properties", "requirements", "type"), "array"),
(("$defs", "flow", "properties", "requirements", "minItems"), 1),
(("$defs", "flow", "properties", "requirements", "uniqueItems"), True),
(
("$defs", "flow", "properties", "requirements", "items", "type"),
"string",
),
(("$defs", "flow", "properties", "requirements", "items", "minLength"), 1),
(
("$defs", "flow", "properties", "requirements", "items", "maxLength"),
MAX_REQUIREMENT_LENGTH,
),
(
("$defs", "flow", "properties", "requirements", "items", "pattern"),
REQUIREMENT_ID.pattern,
),
(
("$defs", "flow", "properties", "capabilities", "maxItems"),
MAX_CAPABILITIES_PER_FLOW,
),
(("$defs", "flow", "properties", "capabilities", "type"), "array"),
(("$defs", "flow", "properties", "capabilities", "minItems"), 1),
(("$defs", "flow", "properties", "capabilities", "uniqueItems"), True),
(
("$defs", "flow", "properties", "capabilities", "items", "enum"),
list(ALLOWED_CAPABILITIES),
),
(("$defs", "flow", "properties", "owner", "type"), "string"),
(("$defs", "flow", "properties", "owner", "minLength"), 1),
(("$defs", "flow", "properties", "owner", "maxLength"), MAX_OWNER_LENGTH),
(("$defs", "flow", "properties", "owner", "pattern"), NON_WHITESPACE_PATTERN),
(("$defs", "flow", "properties", "user_outcome", "type"), "string"),
(("$defs", "flow", "properties", "user_outcome", "minLength"), 1),
(
("$defs", "flow", "properties", "user_outcome", "maxLength"),
MAX_OUTCOME_LENGTH,
),
(
("$defs", "flow", "properties", "user_outcome", "pattern"),
NON_WHITESPACE_PATTERN,
),
(("$defs", "flow", "properties", "evidence", "$ref"), "#/$defs/evidence"),
(("$defs", "flow", "properties", "notes", "type"), "string"),
(("$defs", "flow", "properties", "notes", "maxLength"), MAX_NOTES_LENGTH),
(("$defs", "evidence", "type"), "object"),
(("$defs", "evidence", "additionalProperties"), False),
(
("$defs", "evidence", "properties", "automated", "$ref"),
"#/$defs/evidencePaths",
),
(
("$defs", "evidence", "properties", "manual", "$ref"),
"#/$defs/evidencePaths",
),
(("$defs", "evidencePaths", "type"), "array"),
(("$defs", "evidencePaths", "minItems"), 1),
(("$defs", "evidencePaths", "maxItems"), MAX_EVIDENCE_LINKS_PER_KIND),
(("$defs", "evidencePaths", "uniqueItems"), True),
(("$defs", "evidencePaths", "items", "type"), "string"),
(("$defs", "evidencePaths", "items", "minLength"), 1),
(("$defs", "evidencePaths", "items", "maxLength"), MAX_EVIDENCE_PATH_LENGTH),
(("$defs", "evidencePaths", "items", "pattern"), EVIDENCE_PATH_PATTERN),
# --- v2 protocol block contract (`schema_version: 2`) --------------------------------------
(("$defs", "protocol", "type"), "object"),
(("$defs", "protocol", "additionalProperties"), False),
(("$defs", "protocol", "properties", "selected_on", "type"), "string"),
(("$defs", "protocol", "properties", "selected_on", "pattern"), REVISION_DATE.pattern),
(("$defs", "protocol", "properties", "source_basis", "type"), "string"),
(("$defs", "protocol", "properties", "source_basis", "pattern"), NON_WHITESPACE_PATTERN),
(("$defs", "protocol", "properties", "revisions", "type"), "array"),
(("$defs", "protocol", "properties", "revisions", "minItems"), 2),
(("$defs", "protocol", "properties", "revisions", "maxItems"), 2),
(("$defs", "protocol", "properties", "revisions", "items", "$ref"), "#/$defs/revision"),
(("$defs", "protocol", "properties", "withdrawn", "type"), "array"),
(("$defs", "protocol", "properties", "withdrawn", "minItems"), 1),
(("$defs", "protocol", "properties", "withdrawn", "maxItems"), 16),
(("$defs", "protocol", "properties", "withdrawn", "uniqueItems"), True),
(("$defs", "protocol", "properties", "withdrawn", "items", "type"), "string"),
(
("$defs", "protocol", "properties", "capabilities", "items", "$ref"),
"#/$defs/protocolCapability",
),
(("$defs", "protocol", "properties", "capabilities", "maxItems"), MAX_PROTOCOL_CAPABILITIES),
(("$defs", "revision", "type"), "object"),
(("$defs", "revision", "additionalProperties"), False),
(("$defs", "revision", "properties", "session", "type"), "boolean"),
(("$defs", "revision", "properties", "provenance", "$ref"), "#/$defs/revisionProvenance"),
(("$defs", "revision", "properties", "revision", "pattern"), REVISION_DATE.pattern),
(("$defs", "revisionProvenance", "type"), "object"),
(("$defs", "revisionProvenance", "additionalProperties"), False),
(("$defs", "revisionProvenance", "properties", "sha256", "pattern"), SHA256_HEX.pattern),
(
("$defs", "revisionProvenance", "properties", "captured_on", "pattern"),
REVISION_DATE.pattern,
),
(("$defs", "protocolCapability", "type"), "object"),
(("$defs", "protocolCapability", "additionalProperties"), False),
(("$defs", "protocolCapability", "properties", "kind", "enum"), list(PROTOCOL_KINDS)),
(("$defs", "protocolCapability", "properties", "role", "enum"), list(PROTOCOL_ROLES)),
(("$defs", "protocolCapability", "properties", "status", "enum"), list(PROTOCOL_STATUSES)),
(
("$defs", "protocolCapability", "properties", "applicability", "enum"),
list(PROTOCOL_APPLICABILITIES),
),
(("$defs", "protocolCapability", "properties", "open_subfeatures", "type"), "boolean"),
(("$defs", "protocolCapability", "properties", "advertised", "type"), ["object", "null"]),
(("$defs", "protocolCapability", "properties", "per_revision", "type"), "object"),
(("$defs", "protocolCapability", "properties", "owner", "pattern"), NON_WHITESPACE_PATTERN),
(("$defs", "protocolCapability", "properties", "requirement", "pattern"), REQUIREMENT_ID.pattern),
]
if not isinstance(schema, dict):
return [Diagnostic("INVALID_SCHEMA_CONTRACT", "/schema", "schema must be an object")]
diagnostics = []
for parts, allowed_keys in SCHEMA_ALLOWED_KEYS.items():
node = schema if not parts else nested(schema, *parts)
if not isinstance(node, dict):
continue
if any(key not in allowed_keys for key in node):
pointer = "/schema" + ("/" + "/".join(parts) if parts else "")
diagnostics.append(
Diagnostic(
"INVALID_SCHEMA_CONTRACT",
f"{pointer}/<unsupported>",
"schema contains an unsupported keyword",
)
)
for parts, value in expected:
if not contract_values_equal(nested(schema, *parts), value):
diagnostics.append(
Diagnostic(
"INVALID_SCHEMA_CONTRACT",
"/schema/" + "/".join(parts),
"schema contract differs from validator",
)
)
diagnostics.extend(
validate_required_keyword(
schema,
("required",),
frozenset({"schema_version", "product", "flows", "protocol"}),
)
)
diagnostics.extend(
validate_required_keyword(
schema,
("$defs", "flow", "required"),
frozenset(FLOW_FIELDS - {"notes"}),
)
)
diagnostics.extend(
validate_required_keyword(
schema,
("$defs", "evidence", "required"),
EVIDENCE_FIELDS,
)
)
diagnostics.extend(
validate_required_keyword(
schema,
("$defs", "protocol", "required"),
PROTOCOL_FIELDS,
)
)
diagnostics.extend(
validate_required_keyword(
schema,
("$defs", "revision", "required"),
REVISION_FIELDS,
)
)
diagnostics.extend(
validate_required_keyword(
schema,
("$defs", "revisionProvenance", "required"),
frozenset(PROVENANCE_FIELDS),
)
)
diagnostics.extend(
validate_required_keyword(
schema,
("$defs", "protocolCapability", "required"),
PROTOCOL_CAPABILITY_REQUIRED,
)
)
return diagnostics
def is_nonempty_string(value: Any, maximum: int) -> bool:
return isinstance(value, str) and bool(value.strip()) and len(value) <= maximum
def validate_string_list(
value: Any,
pointer: str,
maximum_items: int,
maximum_length: int,
pattern: re.Pattern[str] | None = None,
) -> list[Diagnostic]:
if not isinstance(value, list) or not value:
return [Diagnostic("MISSING_REQUIRED_FIELD", pointer, "non-empty list is required")]
diagnostics: list[Diagnostic] = []
if len(value) > maximum_items:
diagnostics.append(Diagnostic("LIMIT_EXCEEDED", pointer, "collection exceeds limit"))
seen: set[str] = set()
for index, item in enumerate(value[: maximum_items + 1]):
if not is_nonempty_string(item, maximum_length):
diagnostics.append(
Diagnostic(
"LIMIT_EXCEEDED",
f"{pointer}/{index}",
"string is empty, invalid, or exceeds limit",
)
)
continue
if pattern is not None and pattern.fullmatch(item) is None:
diagnostics.append(
Diagnostic("INVALID_FORMAT", f"{pointer}/{index}", "string format is invalid")
)
if item in seen:
diagnostics.append(
Diagnostic(
"DUPLICATE_LIST_ITEM",
f"{pointer}/{index}",
"collection item is duplicated",
)
)
seen.add(item)
return diagnostics
def reject_unknown_fields(
value: dict[str, Any], allowed: frozenset[str], pointer: str
) -> Iterator[Diagnostic]:
for field in value:
if field not in allowed:
yield Diagnostic("UNKNOWN_FIELD", f"{pointer}/<unknown>", "field is not allowed")
def validate_evidence(root: Path, value: Any, pointer: str) -> Iterator[Diagnostic]:
if not isinstance(value, dict):
yield Diagnostic("MISSING_REQUIRED_FIELD", pointer, "evidence object is required")
return
yield from reject_unknown_fields(value, EVIDENCE_FIELDS, pointer)
for kind in ("automated", "manual"):
paths = value.get(kind)
path_pointer = f"{pointer}/{kind}"
yield from validate_string_list(
paths,
path_pointer,
MAX_EVIDENCE_LINKS_PER_KIND,
MAX_EVIDENCE_PATH_LENGTH,
)
if not isinstance(paths, list):
continue
for index, raw_path in enumerate(paths[: MAX_EVIDENCE_LINKS_PER_KIND + 1]):
if not isinstance(raw_path, str) or resolve_regular_file(root, raw_path) is None:
yield Diagnostic(
"BROKEN_EVIDENCE_LINK",
f"{path_pointer}/{index}",
"evidence path is unavailable",
)
def validate_inventory(
root: Path,
inventory: Any,
required_frs: list[str],
) -> tuple[DiagnosticCollector, dict[str, int]]:
counts = {status: 0 for status in FLOW_STATUSES}
diagnostics = DiagnosticCollector()
if not isinstance(inventory, dict):
diagnostics.append(Diagnostic("MISSING_REQUIRED_FIELD", "/", "inventory must be an object"))
return diagnostics, counts
diagnostics.extend(reject_unknown_fields(inventory, TOP_LEVEL_FIELDS, ""))
product = inventory.get("product")
if not is_nonempty_string(product, MAX_OWNER_LENGTH):
diagnostics.append(
Diagnostic("MISSING_REQUIRED_FIELD", "/product", "the product identity is required")
)
elif product != PRODUCT_ID:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
"/product",
f"the product identity must be {PRODUCT_ID!r}, observed {product!r}",
)
)
schema_version = inventory.get("schema_version")
if type(schema_version) is not int or schema_version not in (1, 2):
diagnostics.append(
Diagnostic("MISSING_REQUIRED_FIELD", "/schema_version", "schema_version 1 or 2 is required")
)
flows = inventory.get("flows")
if not isinstance(flows, list) or not flows:
diagnostics.append(Diagnostic("MISSING_REQUIRED_FIELD", "/flows", "non-empty flows are required"))
return diagnostics, counts
if len(flows) > MAX_FLOWS:
diagnostics.append(Diagnostic("LIMIT_EXCEEDED", "/flows", "flow collection exceeds limit"))
seen_ids: set[str] = set()
observed_frs: set[str] = set()
required_fields = (
"id",
"type",
"requirements",
"user_outcome",
"owner",
"status",
"capabilities",
"evidence",
)
for index, flow in enumerate(flows[: MAX_FLOWS + 1]):
pointer = f"/flows/{index}"
if not isinstance(flow, dict):
diagnostics.append(Diagnostic("MISSING_REQUIRED_FIELD", pointer, "flow must be an object"))
continue
diagnostics.extend(reject_unknown_fields(flow, FLOW_FIELDS, pointer))
for field in required_fields:
if field not in flow:
code = "MISSING_OWNER" if field == "owner" else "MISSING_REQUIRED_FIELD"
diagnostics.append(Diagnostic(code, f"{pointer}/{field}", "field is required"))
flow_id = flow.get("id")
if not is_nonempty_string(flow_id, MAX_ID_LENGTH) or not FLOW_ID.fullmatch(flow_id):
diagnostics.append(Diagnostic("LIMIT_EXCEEDED", f"{pointer}/id", "flow id is invalid"))
elif flow_id in seen_ids:
diagnostics.append(Diagnostic("DUPLICATE_FLOW_ID", f"{pointer}/id", "flow id is duplicated"))
else:
seen_ids.add(flow_id)
flow_type = flow.get("type")
if flow_type not in FLOW_TYPES:
diagnostics.append(Diagnostic("UNKNOWN_FLOW_TYPE", f"{pointer}/type", "flow type is unknown"))
owner = flow.get("owner")
if "owner" in flow:
if not isinstance(owner, str) or not owner.strip():
diagnostics.append(
Diagnostic("MISSING_OWNER", f"{pointer}/owner", "owner is required")
)
elif len(owner) > MAX_OWNER_LENGTH:
diagnostics.append(
Diagnostic("LIMIT_EXCEEDED", f"{pointer}/owner", "owner exceeds limit")
)
outcome = flow.get("user_outcome")
if "user_outcome" in flow and not is_nonempty_string(outcome, MAX_OUTCOME_LENGTH):
diagnostics.append(
Diagnostic("LIMIT_EXCEEDED", f"{pointer}/user_outcome", "user outcome is invalid")
)
notes = flow.get("notes")
if notes is not None and (not isinstance(notes, str) or len(notes) > MAX_NOTES_LENGTH):
diagnostics.append(Diagnostic("LIMIT_EXCEEDED", f"{pointer}/notes", "notes exceed limit"))
status = flow.get("status")
if status not in FLOW_STATUSES:
diagnostics.append(Diagnostic("UNKNOWN_STATUS", f"{pointer}/status", "status is unknown"))
else:
counts[status] += 1
requirements = flow.get("requirements")
diagnostics.extend(
validate_string_list(
requirements,
f"{pointer}/requirements",
MAX_REQUIREMENTS_PER_FLOW,
MAX_REQUIREMENT_LENGTH,
REQUIREMENT_ID,
)
)
if isinstance(requirements, list):
for requirement in requirements[: MAX_REQUIREMENTS_PER_FLOW + 1]:
if isinstance(requirement, str) and REQUIREMENT_ID.fullmatch(requirement):
observed_frs.add(requirement)
capabilities = flow.get("capabilities")
diagnostics.extend(
validate_string_list(
capabilities,
f"{pointer}/capabilities",
MAX_CAPABILITIES_PER_FLOW,
MAX_CAPABILITY_LENGTH,
)
)
if isinstance(capabilities, list):
for cap_index, capability in enumerate(capabilities[: MAX_CAPABILITIES_PER_FLOW + 1]):
cap_pointer = f"{pointer}/capabilities/{cap_index}"
if capability in FORBIDDEN_CAPABILITIES:
diagnostics.append(
Diagnostic(
"FORBIDDEN_COMMUNITY_CAPABILITY",
cap_pointer,
f"forbidden capability: {capability}",
)
)
elif isinstance(capability, str) and capability not in ALLOWED_CAPABILITIES:
diagnostics.append(
Diagnostic("LIMIT_EXCEEDED", cap_pointer, "capability is not allowed")
)
diagnostics.extend(validate_evidence(root, flow.get("evidence"), f"{pointer}/evidence"))
for required_fr in sorted(set(required_frs)):
if not REQUIREMENT_ID.fullmatch(required_fr) or len(required_fr) > MAX_REQUIREMENT_LENGTH:
diagnostics.append(
Diagnostic("LIMIT_EXCEEDED", "/required-fr", "required FR identifier is invalid")
)
elif required_fr not in observed_frs:
diagnostics.append(
Diagnostic(
"MISSING_REQUIRED_FR",
"/requirements",
f"mandatory requirement is missing: {required_fr}",
)
)
return diagnostics, counts
def effective_entry(entry: dict[str, Any], revision: str) -> dict[str, Any]:
"""Shallow per-field merge `default` + `per_revision[revision]` (accepted SPEC rule O2).
Only the fields rule O1 lets an override redeclare are merged: identity (`role`/`kind`/
`surface`) and the eligibility scope (`revisions`) always come from the default, so an override
can never narrow the applicability of a surface and no effective entry is evaluated with a
scope the default did not declare.
"""
merged = {key: value for key, value in entry.items() if key != "per_revision"}
overrides = entry.get("per_revision")
if isinstance(overrides, dict):
override = overrides.get(revision)
if isinstance(override, dict):
merged.update(
{
key: value
for key, value in override.items()
if key in OVERRIDE_ALLOWED_FIELDS
}
)
return merged
def effective_scope(entry: dict[str, Any], revision: str) -> bool:
"""Eligibility-first applicability (rule O2): the default `revisions[]` owns the era scope."""
revisions = entry.get("revisions")
return isinstance(revisions, list) and revision in revisions
def fragment_leaf_items(node: dict[str, Any], prefix: str = "") -> list[tuple[str, Any]]:
"""Leaf paths of an advertisement fragment with the value that terminates each path (G4)."""
items: list[tuple[str, Any]] = []
for key, value in node.items():
path = f"{prefix}.{key}" if prefix else key
if isinstance(value, dict) and value:
items.extend(fragment_leaf_items(value, path))
else:
items.append((path, value))
return items
def capability_structural_diagnostics(resolved: dict[str, Any], pointer: str) -> list[Diagnostic]:
"""G3: the schema-shaped type/bound contract of one record, advertised or not.
The same helper validates the default record and every effective per-era record: applicability of
an advertisement never suspends the type contract of the document itself, so a malformed
`subfeatures`/`open_subfeatures`/`revisions` list or a duplicated revision is a Gate A error even
when the record is not advertised in any revision.
"""
diagnostics: list[Diagnostic] = []
surface = resolved.get("surface")
# Membership, never truthiness: an explicit `null` is a type error of its own, not an absent field.
if "subfeatures" in resolved:
subfeatures = resolved.get("subfeatures")
if not isinstance(subfeatures, list) or not all(
isinstance(item, str) for item in subfeatures
):
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/subfeatures",
f"subfeatures of {surface!r} must be an array of strings",
)
)
else:
if len(subfeatures) > MAX_SUBFEATURE_ITEMS:
diagnostics.append(
Diagnostic(
"LIMIT_EXCEEDED",
f"{pointer}/subfeatures",
f"subfeatures of {surface!r} exceed the pinned {MAX_SUBFEATURE_ITEMS}-item bound",
)
)
if len(set(subfeatures)) != len(subfeatures):
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/subfeatures",
f"subfeatures of {surface!r} must be unique",
)
)
for item in subfeatures:
if not is_nonempty_string(item, MAX_SUBFEATURE_LENGTH):
diagnostics.append(
Diagnostic(
"LIMIT_EXCEEDED",
f"{pointer}/subfeatures",
f"subfeature name {item!r} of {surface!r} exceeds the pinned "
f"{MAX_SUBFEATURE_LENGTH}-character bound",
)
)
open_flag = resolved.get("open_subfeatures")
if "open_subfeatures" in resolved and not isinstance(open_flag, bool):
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/open_subfeatures",
f"open_subfeatures of {surface!r} must be a boolean, observed {type(open_flag).__name__}",
)
)
if "per_revision" in resolved and not isinstance(resolved.get("per_revision"), dict):
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/per_revision",
f"per_revision of {surface!r} must be an object, observed "
f"{type(resolved.get('per_revision')).__name__}",
)
)
revisions = resolved.get("revisions")
if "revisions" in resolved and not isinstance(revisions, list):
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/revisions",
f"revisions of {surface!r} must be an array of revision strings",
)
)
elif isinstance(revisions, list):
# H1/J1: the member type is checked BEFORE any set/hash/membership use and over the *whole*
# array - a prefix window leaves a malformed member in the tail unchecked, so `set(revisions)`
# crashed the whole CLI with a `TypeError` instead of a bounded diagnostic (the J1 reproduction:
# 257 valid members followed by `{}`). Both the named diagnostics and the retained members stay
# bounded, while the scan itself must not: a malformed member at any index is named by the same
# diagnostic, independently of the duplicate/order diagnostics below.
malformed_members: list[tuple[int, Any]] = []
malformed_count = 0
for index, member in enumerate(revisions):
if is_nonempty_string(member, 32):
continue
malformed_count += 1
if len(malformed_members) < MAX_PROTOCOL_CAPABILITIES + 1:
malformed_members.append((index, member))
for index, member in malformed_members:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/revisions/{index}",
f"revision identity {member!r} of {surface!r} must be a string of at most "
"32 characters",
)
)
if not malformed_count:
if len(set(revisions)) != len(revisions):
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/revisions",
f"revisions of {surface!r} must be unique, observed {revisions!r}",
)
)
else:
# H1/O3: the order of `revisions[]` is pinned to the approved window, not free. A
# reversed pair keeps the same member set, so only this diagnostic catches it, while a
# legal one-era scope keeps the pinned relative order (the member is a subsequence).
expected_order = [
revision for revision in PROTOCOL_REVISION_ORDER if revision in set(revisions)
]
if revisions != expected_order:
diagnostics.append(
Diagnostic(
"INVALID_REVISION_ORDER",
f"{pointer}/revisions",
f"the revisions of {surface!r} must follow the pinned window order "
f"{list(PROTOCOL_REVISION_ORDER)!r}, observed {revisions!r}",
)
)
for field in ("owner", "evidence_target"):
value = resolved.get(field)
if isinstance(value, str) and len(value) > MAX_OWNER_LENGTH:
diagnostics.append(
Diagnostic(
"LIMIT_EXCEEDED",
f"{pointer}/{field}",
f"{field} of {surface!r} exceeds the pinned {MAX_OWNER_LENGTH}-character bound "
f"({len(value)} characters)",
)
)
return diagnostics
def applicability_basis_diagnostics(
resolved: dict[str, Any], revision: str, pointer: str
) -> list[Diagnostic]:
"""G1: the effective applicability of a reviewed applicable identity is a reviewed statement.
The pinned revision bytes fix which surfaces carry an `@deprecated` marker
([`REVIEWED_DEPRECATED_PER_ERA`]); every other reviewed applicable identity is `stable` (an
extension is `extension`). An override to another value used to remove truthfully deferred work
from Gate B (`status=complete blockers=0`) while the reviewed window still had 40 blockers.
"""
triple = identity_triple(resolved)
if triple not in reviewed_applicable_identities(revision):
return []
applicability = resolved.get("applicability")
if applicability not in PROTOCOL_APPLICABILITIES:
# An unknown enum value is already named by the effective-field check; do not double-report.
return []
expected = reviewed_applicability(triple, revision)
if applicability == expected:
return []
return [
Diagnostic(
"FALSE_APPLICABILITY",
f"{pointer}/applicability",
f"effective applicability {applicability!r} of {(triple[2])!r} contradicts the reviewed "
f"{revision} basis ({expected!r})",
)
]
def subfeature_basis_diagnostics(
resolved: dict[str, Any], revision: str, pointer: str
) -> list[Diagnostic]:
"""H2/U3: the declared `subfeatures`/`open_subfeatures` are the reviewed pinned accounting.
`subfeatures` records the sub-keys the pinned revision schema declares for a capability and
`open_subfeatures=true` records an open map (`surface-inventory.md` sections 3-4). A record that
declares its own keys is self-certification: `subfeatures = ["invented"]` together with
`advertised = {"tools": {"invented": true}}` was accepted for both eras, so every advertised leaf
looked declared. The effective per-era record is compared with the reviewed basis of the pinned
window, while the reviewed open maps stay open and the pinned era differences (modern `roots`
empty vs legacy `listChanged`, the two `tasks` rows) stay exact.
"""
triple = identity_triple(resolved)
if resolved.get("kind") != "capability":
return []
expected = REVIEWED_SUBFEATURE_BASIS.get((revision, triple[0], triple[2]))
if expected is None:
return []
expected_keys, expected_open = expected
declared = resolved.get("subfeatures")
if not isinstance(declared, list) or not all(isinstance(item, str) for item in declared):
# The type contract of the record is already reported by capability_structural_diagnostics.
return []
diagnostics: list[Diagnostic] = []
unexpected = sorted(set(declared) - set(expected_keys))
if unexpected:
diagnostics.append(
Diagnostic(
"UNREVIEWED_SUBFEATURE",
f"{pointer}/subfeatures",
f"the declared subfeatures of {triple[2]!r} in {revision} are not part of the reviewed "
f"pinned basis: {unexpected} (reviewed {list(expected_keys)})",
)
)
missing = sorted(set(expected_keys) - set(declared))
if missing:
diagnostics.append(
Diagnostic(
"MISSING_SUBFEATURE",
f"{pointer}/subfeatures",
f"the reviewed pinned basis of {triple[2]!r} in {revision} declares "
f"{list(expected_keys)}; missing from subfeatures: {missing}",
)
)
open_flag = resolved.get("open_subfeatures")
if isinstance(open_flag, bool) and open_flag is not expected_open:
diagnostics.append(
Diagnostic(
"FALSE_OPEN_MAP",
f"{pointer}/open_subfeatures",
f"open_subfeatures of {triple[2]!r} in {revision} must be "
f"{str(expected_open).lower()} in the pinned revision",
)
)
return diagnostics
def identity_triple(entry: dict[str, Any]) -> tuple[str, str, str]:
return (str(entry.get("role")), str(entry.get("kind")), str(entry.get("surface")))
def validate_advertisement_fragment(resolved: dict[str, Any], pointer: str) -> list[Diagnostic]:
"""Rules A1a-A1c on one (default or effective) entry: presence, ownership and declared leaves.
The same helper validates the default record and every effective per-era record, so an
advertisement that only becomes wrong after the O2 merge is a Gate A error too (F2).
"""
diagnostics: list[Diagnostic] = []
surface = resolved.get("surface")
kind = resolved.get("kind")
role = resolved.get("role")
status = resolved.get("status")
advertised = resolved.get("advertised")
advertisable = (
isinstance(kind, str)
and kind in ADVERTISABLE_KINDS
and role == "server"
and status == "supported"
)
if advertisable:
if not isinstance(advertised, dict) or not advertised:
diagnostics.append(
Diagnostic(
"ADVERTISED_MISSING",
f"{pointer}/advertised",
f"supported server {kind} {surface!r} must carry an advertised fragment",
)
)
return diagnostics
declared = resolved.get("subfeatures")
declared_keys: set[str] = set()
if isinstance(declared, list) and all(isinstance(item, str) for item in declared):
declared_keys = set(declared)
else:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/subfeatures",
f"subfeatures of {surface!r} must be an array of strings",
)
)
open_flag = resolved.get("open_subfeatures")
if not isinstance(open_flag, bool):
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/open_subfeatures",
f"open_subfeatures of {surface!r} must be a boolean",
)
)
open_map = open_flag is True
expected_key = advertisement_key(kind, surface)
for top_key, value in advertised.items():
if top_key != expected_key:
diagnostics.append(
Diagnostic(
"ADVERTISED_FOREIGN_KEY",
f"{pointer}/advertised/{top_key}",
f"advertised top-level key {top_key!r} does not belong to the declaring "
f"surface {surface!r} (expected {expected_key!r})",
)
)
continue
if not isinstance(value, dict):
diagnostics.append(
Diagnostic(
"ADVERTISED_INVALID_FRAGMENT",
f"{pointer}/advertised/{top_key}",
f"advertised fragment {top_key!r} of {surface!r} must be an object",
)
)
continue
for leaf, leaf_value in fragment_leaf_items(value):
if not open_map and leaf not in declared_keys:
diagnostics.append(
Diagnostic(
"ADVERTISED_UNDECLARED_SUBFEATURE",
f"{pointer}/advertised/{top_key}",
f"advertised leaf {leaf!r} of {surface!r} is not declared by subfeatures",
)
)
pinned = PINNED_ADVERTISEMENT_LEAVES.get(f"{top_key}.{leaf}")
if pinned is not None and type(leaf_value) is not pinned:
diagnostics.append(
Diagnostic(
"ADVERTISED_INVALID_LEAF_TYPE",
f"{pointer}/advertised/{top_key}",
f"advertised leaf {leaf!r} of {surface!r} must be a {pinned.__name__} "
f"in the pinned revision, observed {type(leaf_value).__name__}",
)
)
elif advertised is not None:
diagnostics.append(
Diagnostic(
"ADVERTISED_ON_NON_ADVERTISABLE",
f"{pointer}/advertised",
f"surface {surface!r} (role={role}, kind={kind}, status={status}) is not advertisable",
)
)
return diagnostics
def effective_field_diagnostics(
resolved: dict[str, Any], revision: str, pointer: str
) -> list[Diagnostic]:
"""F1/F2: the mandatory fields of one effective per-era record, read after the O2 merge.
An override that redeclares `status`/`applicability`/`owner`/`reason`/... must satisfy the same
required-field and enum contract as the default record; otherwise the effective document silently
documents a state the accepted schema does not allow.
"""
diagnostics: list[Diagnostic] = []
role = resolved.get("role")
if role not in PROTOCOL_ROLES:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/role",
f"effective role for revision {revision} is unknown: {role!r}",
)
)
kind = resolved.get("kind")
if kind not in PROTOCOL_KINDS:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/kind",
f"effective kind for revision {revision} is unknown: {kind!r}",
)
)
status = resolved.get("status")
if status not in PROTOCOL_STATUSES:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/status",
f"effective status for revision {revision} is unknown: {status!r}",
)
)
applicability = resolved.get("applicability")
if applicability not in PROTOCOL_APPLICABILITIES:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/applicability",
f"effective applicability for revision {revision} is unknown: {applicability!r}",
)
)
for field in ("owner", "fallback", "evidence_target"):
if not is_nonempty_string(resolved.get(field), 2_048):
diagnostics.append(
Diagnostic(
"MISSING_REQUIRED_FIELD",
f"{pointer}/{field}",
f"effective {field} for revision {revision} is required",
)
)
requirement = resolved.get("requirement")
if not isinstance(requirement, str) or REQUIREMENT_ID.fullmatch(requirement) is None:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/requirement",
f"effective requirement for revision {revision} must be an FR identifier",
)
)
reason = resolved.get("reason")
if status != "supported":
if not is_nonempty_string(reason, 2_048):
diagnostics.append(
Diagnostic(
"MISSING_REASON",
f"{pointer}/reason",
f"a reason is required for the effective status {status} in revision {revision}",
)
)
elif "reason" in resolved and not is_nonempty_string(reason, 2_048):
# H1: the same present-but-wrong `reason` rule after the O2 merge (a `per_revision[rev].reason`
# override is a rule O1 candidate, so the effective record must satisfy the field contract too).
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/reason",
f"the effective reason of {resolved.get('surface')!r} in revision {revision} must be a "
"non-empty string of at most 2048 characters when present",
)
)
return diagnostics
def validate_protocol(inventory: dict[str, Any]) -> tuple[list[Diagnostic], dict[str, int]]:
"""Gate A protocol-block checks; returns named diagnostics and the protocol summary counts."""
diagnostics: list[Diagnostic] = []
schema_version = inventory.get("schema_version")
protocol = inventory.get("protocol")
if schema_version != 2:
if "protocol" in inventory:
diagnostics.append(
Diagnostic(
"UNKNOWN_FIELD",
"/protocol",
"the protocol block requires schema_version 2",
)
)
return diagnostics, {"items": 0, "revisions": 0}
if not isinstance(protocol, dict):
diagnostics.append(
Diagnostic("MISSING_REQUIRED_FIELD", "/protocol", "the protocol block is required")
)
return diagnostics, {"items": 0, "revisions": 0}
diagnostics.extend(reject_unknown_fields(protocol, PROTOCOL_FIELDS, "/protocol"))
selected_on = protocol.get("selected_on")
if not isinstance(selected_on, str) or REVISION_DATE.fullmatch(selected_on) is None:
diagnostics.append(
Diagnostic("INVALID_FORMAT", "/protocol/selected_on", "a YYYY-MM-DD selection date is required")
)
source_basis = protocol.get("source_basis")
if not is_nonempty_string(source_basis, 1_024):
diagnostics.append(
Diagnostic("MISSING_REQUIRED_FIELD", "/protocol/source_basis", "a reviewed source basis is required")
)
# --- revision ledger: exactly the approved two-revision window, in order, with provenance ------
revisions = protocol.get("revisions")
ledger_revisions: list[str] = []
if not isinstance(revisions, list):
diagnostics.append(
Diagnostic("MISSING_REQUIRED_FIELD", "/protocol/revisions", "the revision ledger is required")
)
else:
for index, entry in enumerate(revisions[:8]):
pointer = f"/protocol/revisions/{index}"
if not isinstance(entry, dict):
diagnostics.append(Diagnostic("MISSING_REQUIRED_FIELD", pointer, "revision entry must be an object"))
continue
diagnostics.extend(reject_unknown_fields(entry, REVISION_FIELDS, pointer))
revision = entry.get("revision")
if is_nonempty_string(revision, 32):
ledger_revisions.append(str(revision))
else:
diagnostics.append(
Diagnostic("MISSING_REQUIRED_FIELD", f"{pointer}/revision", "a revision identity is required")
)
provenance = entry.get("provenance")
if not isinstance(provenance, dict):
diagnostics.append(
Diagnostic("MISSING_REQUIRED_FIELD", f"{pointer}/provenance", "revision provenance is required")
)
else:
# H1: the provenance object is closed (`additionalProperties: false`), so an unknown
# nested key is a structural error named by the diagnostic, exactly like an unknown
# top-level key of the ledger entry.
for field in sorted(set(provenance) - set(PROVENANCE_FIELDS)):
diagnostics.append(
Diagnostic(
"UNKNOWN_FIELD",
f"{pointer}/provenance/{field}",
f"provenance field {field!r} is not part of the pinned revision provenance",
)
)
for field in PROVENANCE_FIELDS:
value = provenance.get(field)
if not isinstance(value, str) or not is_nonempty_string(value, 2_048):
diagnostics.append(
Diagnostic(
"MISSING_PROVENANCE_FIELD",
f"{pointer}/provenance/{field}",
f"provenance field is missing for revision {revision}: {field}",
)
)
continue
if field == "sha256" and SHA256_HEX.fullmatch(value) is None:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/provenance/{field}",
f"provenance sha256 for revision {revision} is not a 64-character "
"lowercase hex digest",
)
)
elif field == "captured_on" and REVISION_DATE.fullmatch(value) is None:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/provenance/{field}",
f"provenance captured_on for revision {revision} is not a YYYY-MM-DD date",
)
)
# The pinned lifecycle contract of the two approved revisions: the modern window is
# stateless, the legacy window negotiates a session. A feature-complete modern document
# that declares a session is not the reviewed revision at all.
if is_nonempty_string(revision, 32) and revision in REVIEWED_SESSION_BY_REVISION:
session = entry.get("session")
if not isinstance(session, bool) or session is not REVIEWED_SESSION_BY_REVISION[revision]:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/session",
f"revision {revision} must declare session="
f"{str(REVIEWED_SESSION_BY_REVISION[revision]).lower()}",
)
)
# F3: the reviewed role/lifecycle/required-method contract of each approved revision is
# part of the ledger, not optional metadata. A missing or foreign value no longer leaves a
# syntactically valid ledger that describes no reviewed revision.
if is_nonempty_string(revision, 32) and revision in REVISION_CONTRACT:
contract = REVISION_CONTRACT[revision]
role_value = entry.get("role")
if not is_nonempty_string(role_value, 64) or role_value != contract["role"]:
diagnostics.append(
Diagnostic(
"MISSING_REQUIRED_FIELD",
f"{pointer}/role",
f"revision {revision} must declare role={contract['role']!r}",
)
)
lifecycle_value = entry.get("lifecycle")
if (
not is_nonempty_string(lifecycle_value, 64)
or lifecycle_value != contract["lifecycle"]
):
diagnostics.append(
Diagnostic(
"MISSING_REQUIRED_FIELD",
f"{pointer}/lifecycle",
f"revision {revision} must declare lifecycle={contract['lifecycle']!r}",
)
)
required_methods = entry.get("required_methods")
if (
not isinstance(required_methods, list)
or not required_methods
or not all(is_nonempty_string(method, 128) for method in required_methods)
):
diagnostics.append(
Diagnostic(
"MISSING_REQUIRED_FIELD",
f"{pointer}/required_methods",
f"revision {revision} must declare its reviewed required methods "
f"{list(contract['required_methods'])!r}",
)
)
elif tuple(required_methods) != tuple(contract["required_methods"]):
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/required_methods",
f"revision {revision} must declare exactly "
f"{list(contract['required_methods'])!r}, observed {required_methods!r}",
)
)
# The ledger is the exact approved two-revision window in order: neither reversed, duplicated nor
# extended. The per-member diagnostics below name an out-of-window/missing revision; this one
# covers an order/duplication defect that leaves the member set unchanged (AT-01).
if tuple(ledger_revisions) != PROTOCOL_REVISION_ORDER:
duplicates = sorted(
revision for revision in set(ledger_revisions) if ledger_revisions.count(revision) > 1
)
detail = (
f"the revision ledger must be exactly the ordered approved window "
f"({' then '.join(PROTOCOL_REVISION_ORDER)}); observed {ledger_revisions}"
)
if duplicates:
detail += f" with duplicated revision(s) {duplicates}"
diagnostics.append(Diagnostic("INVALID_REVISION_LEDGER", "/protocol/revisions", detail))
if tuple(ledger_revisions) != PROTOCOL_REVISION_ORDER:
for index, revision in enumerate(ledger_revisions):
if revision not in PROTOCOL_REVISION_ORDER:
diagnostics.append(
Diagnostic(
"UNEXPECTED_REVISION",
f"/protocol/revisions/{index}",
f"revision {revision} is outside the approved two-revision window",
)
)
for expected_revision in PROTOCOL_REVISION_ORDER:
if expected_revision not in ledger_revisions:
diagnostics.append(
Diagnostic(
"MISSING_REVISION",
"/protocol/revisions",
f"the approved revision {expected_revision} is missing from the ledger",
)
)
withdrawn = protocol.get("withdrawn")
if not isinstance(withdrawn, list) or tuple(withdrawn) != PROTOCOL_WITHDRAWN:
diagnostics.append(
Diagnostic(
"INVALID_WITHDRAWN_SET",
"/protocol/withdrawn",
"the withdrawn revision set must be exactly " + ", ".join(PROTOCOL_WITHDRAWN),
)
)
# Name the offending members so the diagnostic remains actionable.
if isinstance(withdrawn, list):
for index, revision in enumerate(withdrawn[:16]):
if revision not in PROTOCOL_WITHDRAWN:
diagnostics.append(
Diagnostic(
"INVALID_WITHDRAWN_SET",
f"/protocol/withdrawn/{index}",
f"withdrawn revision {revision} is not part of the approved set",
)
)
# --- capability ledger: identity, per-revision overrides, truthfulness, completeness ----------
capabilities = protocol.get("capabilities")
if not isinstance(capabilities, list) or not capabilities:
diagnostics.append(
Diagnostic("MISSING_REQUIRED_FIELD", "/protocol/capabilities", "the capability ledger is required")
)
return diagnostics, {"items": 0, "revisions": len(ledger_revisions)}
if len(capabilities) > MAX_PROTOCOL_CAPABILITIES:
diagnostics.append(
Diagnostic("LIMIT_EXCEEDED", "/protocol/capabilities", "capability ledger exceeds limit")
)
seen: dict[tuple[str, str, str], int] = {}
observed: set[tuple[str, str, str]] = set()
for index, entry in enumerate(capabilities[: MAX_PROTOCOL_CAPABILITIES + 1]):
pointer = f"/protocol/capabilities/{index}"
if not isinstance(entry, dict):
diagnostics.append(Diagnostic("MISSING_REQUIRED_FIELD", pointer, "capability entry must be an object"))
continue
diagnostics.extend(reject_unknown_fields(entry, CAPABILITY_FIELDS, pointer))
for field in sorted(PROTOCOL_CAPABILITY_REQUIRED):
if field not in entry:
diagnostics.append(
Diagnostic("MISSING_REQUIRED_FIELD", f"{pointer}/{field}", "field is required")
)
role = entry.get("role")
kind = entry.get("kind")
surface = entry.get("surface")
if not isinstance(role, str) or role not in PROTOCOL_ROLES:
diagnostics.append(Diagnostic("INVALID_FORMAT", f"{pointer}/role", "role is unknown"))
if not isinstance(kind, str) or kind not in PROTOCOL_KINDS:
diagnostics.append(Diagnostic("INVALID_FORMAT", f"{pointer}/kind", "kind is unknown"))
if not is_nonempty_string(surface, 256):
diagnostics.append(Diagnostic("INVALID_FORMAT", f"{pointer}/surface", "a surface name is required"))
triple = identity_triple(entry)
if triple in seen:
diagnostics.append(
Diagnostic(
"DUPLICATE_SURFACE_IDENTITY",
f"{pointer}/surface",
f"duplicate surface identity (role={triple[0]}, kind={triple[1]}, surface={triple[2]})",
)
)
else:
seen[triple] = index
observed.add(triple)
status = entry.get("status")
if status not in PROTOCOL_STATUSES:
diagnostics.append(Diagnostic("INVALID_FORMAT", f"{pointer}/status", "status is unknown"))
applicability = entry.get("applicability")
if applicability not in PROTOCOL_APPLICABILITIES:
diagnostics.append(
Diagnostic("INVALID_FORMAT", f"{pointer}/applicability", "applicability is unknown")
)
revisions_field = entry.get("revisions")
if not isinstance(revisions_field, list) or not revisions_field:
diagnostics.append(
Diagnostic("MISSING_REQUIRED_FIELD", f"{pointer}/revisions", "an applicable revision list is required")
)
else:
for revision_index, revision in enumerate(revisions_field[:8]):
if revision not in PROTOCOL_REVISION_ORDER:
diagnostics.append(
Diagnostic(
"UNEXPECTED_REVISION",
f"{pointer}/revisions/{revision_index}",
f"revision {revision} is outside the approved two-revision window",
)
)
# G3: the schema-shaped type/bound contract of the record itself, independent of whether any
# revision advertises it.
diagnostics.extend(capability_structural_diagnostics(entry, pointer))
for field in ("owner", "fallback", "evidence_target"):
if not is_nonempty_string(entry.get(field), 2_048):
diagnostics.append(
Diagnostic("MISSING_REQUIRED_FIELD", f"{pointer}/{field}", f"{field} is required")
)
requirement = entry.get("requirement")
if not isinstance(requirement, str) or REQUIREMENT_ID.fullmatch(requirement) is None:
diagnostics.append(
Diagnostic("INVALID_FORMAT", f"{pointer}/requirement", "an FR requirement id is required")
)
reason = entry.get("reason")
if status != "supported":
if not is_nonempty_string(reason, 2_048):
diagnostics.append(
Diagnostic(
"MISSING_REASON",
f"{pointer}/reason",
f"a reason is required for status {status}",
)
)
elif "reason" in entry and not is_nonempty_string(reason, 2_048):
# H1: `reason` is optional in *presence*, never in type. A present wrong-typed or over-long
# reason (e.g. `[]` or a 2049-character string on a supported record) used to be accepted.
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
f"{pointer}/reason",
f"the reason of {surface!r} must be a non-empty string of at most 2048 characters "
"when present",
)
)
# O1/O2/O3: per-revision override resolution.
overrides = entry.get("per_revision")
if overrides is not None:
if not isinstance(overrides, dict):
diagnostics.append(
Diagnostic("INVALID_FORMAT", f"{pointer}/per_revision", "per_revision must be an object")
)
else:
revisions_scope = revisions_field if isinstance(revisions_field, list) else []
for revision, override in overrides.items():
if revision not in revisions_scope:
diagnostics.append(
Diagnostic(
"OVERRIDE_OUTSIDE_REVISIONS",
f"{pointer}/per_revision/{revision}",
f"override for revision {revision} outside revisions[]",
)
)
if not isinstance(override, dict) or not override:
diagnostics.append(
Diagnostic(
"REDUNDANT_OVERRIDE",
f"{pointer}/per_revision/{revision}",
f"override for revision {revision} changes no field",
)
)
continue
if all(entry.get(key) == value for key, value in override.items()):
diagnostics.append(
Diagnostic(
"REDUNDANT_OVERRIDE",
f"{pointer}/per_revision/{revision}",
f"override for revision {revision} repeats the default value",
)
)
for override_key, override_value in override.items():
override_pointer = f"{pointer}/per_revision/{revision}/{override_key}"
if override_key in OVERRIDE_FORBIDDEN_FIELDS:
diagnostics.append(
Diagnostic(
"OVERRIDE_NOT_ALLOWED_FIELD",
override_pointer,
f"per-revision override may not redeclare the structural field "
f"{override_key!r} of {surface!r} (rule O1)",
)
)
continue
if override_key not in OVERRIDE_ALLOWED_FIELDS:
diagnostics.append(
Diagnostic(
"UNKNOWN_OVERRIDE_FIELD",
override_pointer,
f"unknown per-revision override field {override_key!r}",
)
)
continue
allowed = OVERRIDE_ENUM_FIELDS.get(override_key)
if allowed is None:
continue
if not isinstance(override_value, str) or override_value not in allowed:
diagnostics.append(
Diagnostic(
"INVALID_FORMAT",
override_pointer,
f"effective {override_key} for revision {revision} is invalid: "
f"{override_value!r}",
)
)
# F1/F2: the effective per-era record is a document of its own — its mandatory
# fields and its advertisement are validated after the O2 merge, not only the
# default record the override is derived from.
if revision in PROTOCOL_REVISION_ORDER:
era_pointer = f"{pointer}/per_revision/{revision}"
resolved = effective_entry(entry, revision)
diagnostics.extend(
effective_field_diagnostics(resolved, revision, era_pointer)
)
diagnostics.extend(
capability_structural_diagnostics(resolved, era_pointer)
)
diagnostics.extend(
validate_advertisement_fragment(resolved, era_pointer)
)
# A1: advertisement truthfulness of the default record (rules A1a-A1c, shared helper).
diagnostics.extend(validate_advertisement_fragment(entry, pointer))
# A1d: the same top-level capabilities key must not come from two entries (default view).
advertised_keys: dict[str, int] = {}
for index, entry in enumerate(capabilities[: MAX_PROTOCOL_CAPABILITIES + 1]):
if not isinstance(entry, dict):
continue
advertised = entry.get("advertised")
if isinstance(advertised, dict):
for top_key in advertised:
if top_key in advertised_keys:
diagnostics.append(
Diagnostic(
"ADVERTISED_CONFLICT",
f"/protocol/capabilities/{index}/advertised/{top_key}",
f"top-level advertised key {top_key!r} is claimed by two entries",
)
)
else:
advertised_keys[top_key] = index
# A1d (F2, effective view): the merged advertisement of *one era* must not lose a fragment
# either. Revisions scope each entry, so two entries can conflict in one era and not the other.
for revision in PROTOCOL_REVISION_ORDER:
era_keys: dict[str, int] = {}
for index, entry in enumerate(capabilities[: MAX_PROTOCOL_CAPABILITIES + 1]):
if not isinstance(entry, dict) or not effective_scope(entry, revision):
continue
advertised = effective_entry(entry, revision).get("advertised")
if not isinstance(advertised, dict):
continue
for top_key in advertised:
if top_key in era_keys:
diagnostics.append(
Diagnostic(
"ADVERTISED_CONFLICT",
f"/protocol/capabilities/{index}/per_revision/{revision}/advertised/{top_key}",
f"top-level advertised key {top_key!r} is claimed by two entries "
f"in {revision}",
)
)
else:
era_keys[top_key] = index
# U2: completeness against the reviewed source-backed accounting (exact triple).
reviewed = set(REVIEWED_SURFACE_STATUS)
for triple in sorted(reviewed - observed):
diagnostics.append(
Diagnostic(
"OMISSION",
"/protocol/capabilities",
f"reviewed surface is missing (role={triple[0]}, kind={triple[1]}, surface={triple[2]})",
)
)
for triple in sorted(observed - reviewed):
diagnostics.append(
Diagnostic(
"UNDOCUMENTED_SURFACE",
"/protocol/capabilities",
f"surface is not in the reviewed accounting (role={triple[0]}, kind={triple[1]}, surface={triple[2]})",
)
)
# Truthfulness of the reviewed deferral accounting: applicable scheduled work is not inapplicable.
for entry in capabilities[: MAX_PROTOCOL_CAPABILITIES + 1]:
if not isinstance(entry, dict):
continue
triple = identity_triple(entry)
if entry.get("status") == "not_applicable" and REVIEWED_SURFACE_STATUS.get(triple) == "deferred":
diagnostics.append(
Diagnostic(
"FALSE_NOT_APPLICABLE",
f"/protocol/capabilities/{seen.get(triple, 0)}/status",
f"surface {triple[2]!r} is applicable scheduled work and must not be declared not_applicable",
)
)
# O2/U2: the reviewed applicable basis is per era, and the *effective* entry - not the default
# union - decides both completeness and the truthfulness of a `not_applicable` relabel.
observed_per_era: dict[str, set[tuple[str, str, str]]] = {
revision: set() for revision in PROTOCOL_REVISION_ORDER
}
for entry in capabilities[: MAX_PROTOCOL_CAPABILITIES + 1]:
if not isinstance(entry, dict):
continue
triple = identity_triple(entry)
revisions_field = entry.get("revisions")
scoped = revisions_field if isinstance(revisions_field, list) else []
for revision in PROTOCOL_REVISION_ORDER:
if revision not in scoped:
continue
resolved = effective_entry(entry, revision)
observed_per_era[revision].add(identity_triple(resolved))
# G1: the effective applicability of a reviewed applicable identity is a reviewed
# statement, so an override or a default value that contradicts the pinned revision
# cannot remove truthfully deferred work from Gate B.
diagnostics.extend(
applicability_basis_diagnostics(
resolved,
revision,
f"/protocol/capabilities/{seen.get(triple, 0)}/per_revision/{revision}",
)
)
# H2: the declared per-era `subfeatures`/`open_subfeatures` of the effective record are the
# reviewed pinned accounting, not a self-declaration.
diagnostics.extend(
subfeature_basis_diagnostics(
resolved,
revision,
f"/protocol/capabilities/{seen.get(triple, 0)}/per_revision/{revision}",
)
)
if (
resolved.get("status") == "not_applicable"
and REVIEWED_SURFACE_STATUS.get(triple) == "deferred"
):
diagnostics.append(
Diagnostic(
"FALSE_NOT_APPLICABLE",
f"/protocol/capabilities/{seen.get(triple, 0)}/per_revision/{revision}",
f"surface {resolved.get('surface')!r} is applicable scheduled work in "
f"{revision} and must not be declared not_applicable",
)
)
for revision in PROTOCOL_REVISION_ORDER:
applicable = reviewed_applicable_identities(revision)
for triple in sorted(applicable - observed_per_era[revision]):
diagnostics.append(
Diagnostic(
"OMISSION",
"/protocol/capabilities",
f"reviewed surface is absent for revision {revision} "
f"(role={triple[0]}, kind={triple[1]}, surface={triple[2]})",
)
)
for triple in sorted(observed_per_era[revision] - applicable):
diagnostics.append(
Diagnostic(
"UNDOCUMENTED_SURFACE",
"/protocol/capabilities",
f"surface is not part of the reviewed {revision} basis "
f"(role={triple[0]}, kind={triple[1]}, surface={triple[2]})",
)
)
return diagnostics, {"items": len(observed), "revisions": len(ledger_revisions)}
def feature_complete_blockers(inventory: dict[str, Any]) -> list[dict[str, str]]:
"""Gate B: applicable stable `deferred` surfaces, one named blocker per (surface, revision)."""
protocol = inventory.get("protocol")
if not isinstance(protocol, dict):
return []
capabilities = protocol.get("capabilities")
if not isinstance(capabilities, list):
return []
blockers: list[dict[str, str]] = []
for entry in capabilities[: MAX_PROTOCOL_CAPABILITIES + 1]:
if not isinstance(entry, dict):
continue
for revision in PROTOCOL_REVISION_ORDER:
resolved = effective_entry(entry, revision)
revisions = resolved.get("revisions")
if not isinstance(revisions, list) or revision not in revisions:
continue
if resolved.get("status") != "deferred":
continue
if resolved.get("applicability") != "stable":
continue
blockers.append(
{
"capability": str(resolved.get("surface")),
"revision": revision,
"reason": str(resolved.get("reason") or "applicable stable deferred surface"),
"owner": str(resolved.get("owner") or "unassigned"),
}
)
blockers.sort(key=lambda item: (item["capability"], item["revision"], item["reason"], item["owner"]))
return blockers
def render_report(diagnostics: DiagnosticCollector) -> str:
selected = diagnostics.ordered()
lines = [f"error[{item.code}] {item.pointer}: {item.message}" for item in selected]
if diagnostics.omitted:
lines.append(f"error[TRUNCATED] /: diagnostics omitted={diagnostics.omitted}")
report = "\n".join(lines) + "\n"
encoded = report.encode("utf-8")
if len(encoded) <= MAX_REPORT_BYTES:
return report
marker = "error[TRUNCATED] /: report byte limit reached\n"
marker_bytes = marker.encode("utf-8")
budget = MAX_REPORT_BYTES - len(marker_bytes)
kept: list[str] = []
used = 0
for line in lines:
line_bytes = (line + "\n").encode("utf-8")
if used + len(line_bytes) > budget:
break
kept.append(line)
used += len(line_bytes)
return "\n".join(kept) + ("\n" if kept else "") + marker
def write_report(path: str, payload: dict[str, Any]) -> None:
"""Write a deterministic, byte-capped report that always stays valid JSON.
A blind byte truncation produces an unparseable document, so the cap is respected by *dropping
whole entries* of the largest list (`blockers` or `diagnostics`) and disclosing the omission
explicitly (never by cutting the serialized JSON).
"""
def serialized(candidate: dict[str, Any]) -> bytes:
return (json.dumps(candidate, indent=2, sort_keys=True) + "\n").encode("utf-8")
def write_bounded(candidate: dict[str, Any]) -> None:
Path(path).write_bytes(serialized(candidate))
encoded = serialized(payload)
if len(encoded) <= MAX_REPORT_BYTES:
write_bounded(payload)
return
bounded = dict(payload)
# Trim each list-valued payload member to the largest whole prefix that fits the byte cap, with a
# named omission count and the distinct codes of what was dropped (F4: a bounded report must
# disclose *what* is missing, not only the byte overflow of the full array).
for key, omitted_key, codes_key in (
("diagnostics", "omitted_diagnostics", "omitted_diagnostic_codes"),
("blockers", "omitted_blockers", None),
):
items = bounded.get(key)
if not isinstance(items, list) or not items:
continue
kept: list[Any] = []
for index in range(1, len(items) + 1):
candidate = dict(bounded)
candidate[key] = items[:index]
candidate["truncated"] = True
candidate[omitted_key] = len(items) - index
if codes_key is not None:
candidate[codes_key] = sorted(
{
str(item.get("code"))
for item in items[index:]
if isinstance(item, dict) and item.get("code") is not None
}
)
if len(serialized(candidate)) > MAX_REPORT_BYTES:
break
kept = items[:index]
bounded[key] = kept
bounded["truncated"] = True
bounded[omitted_key] = len(items) - len(kept)
if codes_key is not None:
bounded[codes_key] = sorted(
{
str(item.get("code"))
for item in items[len(kept):]
if isinstance(item, dict) and item.get("code") is not None
}
)
if len(serialized(bounded)) <= MAX_REPORT_BYTES:
write_bounded(bounded)
return
# Even the empty-list disclosure does not fit: keep the honest disclosure without the list.
bounded[key] = []
bounded["truncated"] = True
if len(serialized(bounded)) <= MAX_REPORT_BYTES:
write_bounded(bounded)
return
# Last bounded fallback: the verdict itself, with no unbounded member left in the payload.
write_bounded(
{
"mode": bounded.get("mode"),
"status": bounded.get("status"),
"truncated": True,
}
)
def main() -> int:
args = parse_args()
root = args.root.resolve()
schema, schema_error = read_json_document(root, args.schema, "INVALID_SCHEMA")
inventory, inventory_error = read_json_document(root, args.inventory, "INVALID_JSON")
diagnostics = DiagnosticCollector()
diagnostics.extend(error for error in (schema_error, inventory_error) if error is not None)
if schema_error is None:
diagnostics.extend(validate_schema_contract(schema))
counts = {status: 0 for status in FLOW_STATUSES}
protocol_stats = {"items": 0, "revisions": 0}
parsed_inventory: dict[str, Any] | None = None
if inventory_error is None:
inventory_diagnostics, counts = validate_inventory(root, inventory, args.required_fr)
diagnostics.extend(inventory_diagnostics)
if isinstance(inventory, dict):
parsed_inventory = inventory
protocol_diagnostics, protocol_stats = validate_protocol(inventory)
diagnostics.extend(protocol_diagnostics)
# Gate B is a v2 protocol-scope gate: a document without a protocol block has nothing that
# could be feature-complete, so `complete`/0 blockers would be a false claim. Validity mode
# keeps its accepted v1 flow-only compatibility.
if args.mode == "feature-complete" and not isinstance(inventory.get("protocol"), dict):
diagnostics.append(
Diagnostic(
"MISSING_REQUIRED_FIELD",
"/protocol",
"the feature-complete gate requires a v2 protocol block",
)
)
if diagnostics:
sys.stderr.write(render_report(diagnostics))
print("status=invalid")
if args.report is not None:
write_report(
args.report,
{"mode": args.mode, "status": "invalid", "diagnostics": [
{"code": item.code, "pointer": item.pointer, "message": item.message}
for item in diagnostics.ordered()
]},
)
return 1
if args.mode == "validity":
total = sum(counts.values())
print(
"Capability inventory validation passed "
f"total={total} implemented={counts['implemented']} "
f"planned={counts['planned']} gap={counts['gap']} "
f"blocked={counts['blocked']} pass={counts['implemented']} "
f"protocol_items={protocol_stats['items']} revisions={protocol_stats['revisions']}"
)
print("status=valid")
if args.report is not None:
write_report(
args.report,
{"mode": args.mode, "status": "valid", "window": PROTOCOL_REVISION_ORDER, "blockers": []},
)
return 0
blockers = feature_complete_blockers(parsed_inventory) if parsed_inventory is not None else []
status = "blocked" if blockers else "complete"
print(f"Capability feature-complete: status={status} blockers={len(blockers)}")
if args.report is not None:
write_report(
args.report,
{
"mode": args.mode,
"status": status,
"window": list(PROTOCOL_REVISION_ORDER),
"blockers": blockers,
},
)
return 3 if blockers else 0
if __name__ == "__main__":
raise SystemExit(main())