#!/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}/", "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}/", "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())