[skip ci] wip: preserve Hermes crank development checkpoint
Owner-authorized recovery of accumulated source changes.
Includes accepted work and in-progress changes; NOT a release or acceptance.
Parent baseline 1b6db09bd1. Runtime data, build caches and local credentials excluded.
This commit is contained in:
1 parent
1b6db09bd1
commit
75fe5a123c
357 files changed
+118831
-5113
No files matched your search
Executable
+439
@@ -0,0 +1,439 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Project the server-only advertised capabilities of one MCP revision from the canonical inventory.
|
||||
|
||||
Story 3.1 AT-13 artifact step. The expectation for a revision is derived **only** from the `protocol`
|
||||
block of `docs/capability-inventory.json` (accepted SPEC `remaining-ac-spec.md` section 5, rules 1-4):
|
||||
|
||||
1. take the effective entry for the era (`default` merged with `per_revision[era]`, rule O2);
|
||||
2. include it only when `kind in {capability, extension}` AND `role = server` AND `status = supported`
|
||||
AND the era is listed in the entry's `revisions[]`; client/both/method/notification entries are
|
||||
neutral completeness inputs and are never projected;
|
||||
3. deep-merge the `advertised` fragments of every included entry; a conflicting top-level
|
||||
capabilities key is rejected;
|
||||
4. the result is exactly the era's `capabilities` object.
|
||||
|
||||
The producer never calls the MCP server, never imports the registry and never reads a captured server
|
||||
response: era-vs-era, self-snapshot and capture-of-server-output-as-expectation are forbidden.
|
||||
|
||||
The frozen payload is the canonical serialization of that object: compact UTF-8 (`:`/`,` separators),
|
||||
object keys sorted byte-lexicographically, no trailing newline. The audit provenance (inventory digest,
|
||||
projection rule id and the participating identity triples) lives in a separate sidecar file and is
|
||||
never byte-compared with the endpoint.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import hashlib
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
REVISION_ORDER = ("2026-07-28", "2025-11-25")
|
||||
PROJECTION_RULE = "remaining-ac-spec.md#5-server-only-projection-rules-1-4"
|
||||
ADVERTISABLE_KINDS = frozenset({"capability", "extension"})
|
||||
# Rule O1 (accepted SPEC section 5), the same policy the validator applies: exactly these fields may be
|
||||
# redeclared per revision. The structural identity and the applicability scope are resolved from the
|
||||
# default record, so a forbidden `surface`/`revisions` override is a bounded rejection instead of a
|
||||
# silently narrowed eligibility scope (G5).
|
||||
OVERRIDE_ALLOWED_FIELDS = frozenset(
|
||||
{
|
||||
"status",
|
||||
"applicability",
|
||||
"role",
|
||||
"reason",
|
||||
"fallback",
|
||||
"evidence_target",
|
||||
"owner",
|
||||
"requirement",
|
||||
"subfeatures",
|
||||
"open_subfeatures",
|
||||
"advertised",
|
||||
}
|
||||
)
|
||||
# The pinned wire types of the advertisement leaves this projection emits
|
||||
# (`reviewed-inputs/2026-07-28-schema.ts`: `ServerCapabilities.tools.listChanged?: boolean`). An array
|
||||
# leaf used to be written into the frozen artifact, i.e. a fragment the pinned type does not allow (G4).
|
||||
PINNED_LEAF_TYPES: dict[str, type] = {
|
||||
"tools.listChanged": bool,
|
||||
}
|
||||
# The reviewed `subfeatures`/`open` accounting of the two pinned revision schemas
|
||||
# (`surface-inventory.md` sections 3-4 of the accepted SPEC, rule U3): the sub-keys the pinned schema
|
||||
# declares for a capability and whether the pinned value is an open map. The standalone producer is an
|
||||
# artifact oracle of its own, so it rejects a self-declared sub-key that legitimized an advertised leaf
|
||||
# the pinned schema does not declare (`tools.subfeatures = ["invented"]` +
|
||||
# `advertised = {"tools": {"invented": true}}` used to be projected for both eras, H2).
|
||||
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 advertisement_key(kind: Any, surface: Any) -> Any:
|
||||
"""The top-level `capabilities` key an advertisable surface declares its fragment under (spec 5/A1).
|
||||
|
||||
A capability declaration advertises under its own surface name; a capability extension advertises
|
||||
under the `extensions` key (e.g. `io.modelcontextprotocol/tasks` -> `extensions`). Any other
|
||||
top-level key is not the pinned advertisement of the declaring surface and is rejected instead of
|
||||
being merged into the era payload.
|
||||
"""
|
||||
if kind == "extension":
|
||||
return "extensions"
|
||||
return surface
|
||||
|
||||
|
||||
class ProjectionError(Exception):
|
||||
"""The inventory cannot be projected for the requested revision."""
|
||||
|
||||
|
||||
def parse_args() -> argparse.Namespace:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--inventory", type=Path, required=True)
|
||||
parser.add_argument("--revision", required=True, choices=list(REVISION_ORDER))
|
||||
parser.add_argument("--frozen", type=Path, required=True)
|
||||
parser.add_argument("--provenance", type=Path, required=True)
|
||||
return parser.parse_args()
|
||||
|
||||
|
||||
def reject_nonstandard_json_constant(name: str) -> None:
|
||||
"""`NaN`/`Infinity` are JavaScript-only constants, never part of a JSON artifact (G4).
|
||||
|
||||
`json.loads` accepts them by default and `json.dumps` writes them back, so the bounded oracle used
|
||||
to emit an unparseable frozen payload.
|
||||
"""
|
||||
raise ProjectionError(f"inventory carries the non-standard JSON constant {name!r}")
|
||||
|
||||
|
||||
def load_inventory(path: Path) -> tuple[dict[str, Any], str]:
|
||||
try:
|
||||
payload_bytes = path.read_bytes()
|
||||
except OSError as error: # pragma: no cover - defensive
|
||||
raise ProjectionError(f"inventory is unreadable: {path}: {error}") from error
|
||||
digest = hashlib.sha256(payload_bytes).hexdigest()
|
||||
try:
|
||||
document = json.loads(
|
||||
payload_bytes.decode("utf-8"), parse_constant=reject_nonstandard_json_constant
|
||||
)
|
||||
except (UnicodeDecodeError, json.JSONDecodeError) as error:
|
||||
raise ProjectionError(f"inventory is not valid UTF-8 JSON: {path}") from error
|
||||
if not isinstance(document, dict):
|
||||
raise ProjectionError("inventory must be a JSON object")
|
||||
return document, digest
|
||||
|
||||
|
||||
def effective(entry: dict[str, Any], era: str) -> dict[str, Any]:
|
||||
"""Shallow per-field merge `default` + `per_revision[era]` (accepted SPEC rule O2).
|
||||
|
||||
Only the rule O1 allowed fields are merged: the structural identity/applicability scope always
|
||||
resolves from the default record, exactly as in the validator.
|
||||
"""
|
||||
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(era, {})
|
||||
if isinstance(override, dict):
|
||||
merged.update(
|
||||
{
|
||||
key: value
|
||||
for key, value in override.items()
|
||||
if key in OVERRIDE_ALLOWED_FIELDS
|
||||
}
|
||||
)
|
||||
return merged
|
||||
|
||||
|
||||
def check_override_policy(entry: dict[str, Any], surface: Any, era: str) -> None:
|
||||
"""Rule O1 for one entry: only the allowed fields may be redeclared, per era (G5).
|
||||
|
||||
A standalone negative must hold even when no validator ran before, so a forbidden `revisions`
|
||||
override is rejected here rather than silently narrowing the eligibility scope and producing an
|
||||
empty artifact.
|
||||
"""
|
||||
overrides = entry.get("per_revision")
|
||||
if overrides is None:
|
||||
return
|
||||
if not isinstance(overrides, dict):
|
||||
raise ProjectionError(
|
||||
f"per_revision of {surface!r} must be an object for {era}: {overrides!r}"
|
||||
)
|
||||
for revision, override in overrides.items():
|
||||
if not isinstance(override, dict):
|
||||
raise ProjectionError(
|
||||
f"per_revision/{revision} of {surface!r} must be an object for {era}: {override!r}"
|
||||
)
|
||||
for key in override:
|
||||
if key not in OVERRIDE_ALLOWED_FIELDS:
|
||||
raise ProjectionError(
|
||||
f"per-revision override field {key!r} of {surface!r} for {revision} is not "
|
||||
f"allowed by rule O1 (observed while projecting {era})"
|
||||
)
|
||||
|
||||
|
||||
def check_subfeature_basis(resolved: dict[str, Any], era: str) -> None:
|
||||
"""H2/U3 + J2: the declared `subfeatures`/`open_subfeatures` of one effective record are reviewed.
|
||||
|
||||
The producer is a standalone artifact oracle: a self-declared sub-key that legitimizes an
|
||||
advertised leaf the pinned revision schema does not declare must be rejected here as well, even
|
||||
when no validator ran before, and the reviewed open maps / per-era differences stay accepted. The
|
||||
check runs for every capability record of the document (advertisable or not), so a document that
|
||||
misdeclares a client-side row is not silently projectable either.
|
||||
|
||||
J2: the type of that accounting is not deferred to the projected-entry checks (F8), which only ever
|
||||
see a supported server row eligible for the requested era. A wrong-typed `subfeatures` (e.g. `null`
|
||||
or `[{}]`) or `open_subfeatures` (e.g. `"false"`) on a client, truthfully deferred or
|
||||
applicability-skipped capability made the standalone oracle exit 0 and write the frozen payload and
|
||||
the provenance sidecar while the validator rejected the same document. Every capability record is
|
||||
therefore type-checked before its declaration is compared with the reviewed basis; the comparison
|
||||
itself stays limited to the reviewed per-era rows, and a declaration absent from the record is still
|
||||
handled by the projected-entry checks.
|
||||
"""
|
||||
if resolved.get("kind") != "capability":
|
||||
return
|
||||
surface = resolved.get("surface")
|
||||
role = resolved.get("role")
|
||||
if not isinstance(surface, str) or not isinstance(role, str):
|
||||
return
|
||||
declared = resolved.get("subfeatures")
|
||||
if "subfeatures" in resolved and (
|
||||
not isinstance(declared, list) or not all(isinstance(item, str) for item in declared)
|
||||
):
|
||||
raise ProjectionError(
|
||||
f"subfeatures of {surface!r} must be an array of strings for {era}: {declared!r}"
|
||||
)
|
||||
open_flag = resolved.get("open_subfeatures")
|
||||
if "open_subfeatures" in resolved and not isinstance(open_flag, bool):
|
||||
raise ProjectionError(
|
||||
f"open_subfeatures of {surface!r} must be a boolean for {era}: {open_flag!r}"
|
||||
)
|
||||
expected = REVIEWED_SUBFEATURE_BASIS.get((era, role, surface))
|
||||
if expected is None:
|
||||
return
|
||||
expected_keys, expected_open = expected
|
||||
if not isinstance(declared, list):
|
||||
# The type contract of a projected entry is enforced separately (F8).
|
||||
return
|
||||
unexpected = sorted(set(declared) - set(expected_keys))
|
||||
if unexpected:
|
||||
raise ProjectionError(
|
||||
f"the declared subfeatures {unexpected} of {surface!r} are not part of the reviewed "
|
||||
f"pinned {era} basis {list(expected_keys)}"
|
||||
)
|
||||
missing = sorted(set(expected_keys) - set(declared))
|
||||
if missing:
|
||||
raise ProjectionError(
|
||||
f"the reviewed pinned {era} basis of {surface!r} declares {list(expected_keys)}; missing "
|
||||
f"from subfeatures: {missing}"
|
||||
)
|
||||
if isinstance(open_flag, bool) and open_flag is not expected_open:
|
||||
raise ProjectionError(
|
||||
f"open_subfeatures of {surface!r} must be {str(expected_open).lower()} in the pinned "
|
||||
f"{era} revision, observed {open_flag!r}"
|
||||
)
|
||||
|
||||
|
||||
def required_text(value: Any, field: str, era: str) -> str:
|
||||
"""One projected entry field must be a non-empty string; anything else is a bounded rejection.
|
||||
|
||||
The producer is a standalone CLI oracle: a malformed kind/subfeature/map must produce a
|
||||
deterministic `PROJECTION_REJECTED` diagnostic instead of an unhandled `TypeError` (F8).
|
||||
"""
|
||||
if not isinstance(value, str) or not value:
|
||||
raise ProjectionError(f"{field} of a projected entry must be a non-empty string for {era}: {value!r}")
|
||||
return value
|
||||
|
||||
|
||||
def leaf_items(node: dict[str, Any], prefix: str = "") -> list[tuple[str, Any]]:
|
||||
"""Leaf paths 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(leaf_items(value, path))
|
||||
else:
|
||||
items.append((path, value))
|
||||
return items
|
||||
|
||||
|
||||
def project(capabilities: Any, era: str) -> tuple[dict[str, Any], list[dict[str, str]]]:
|
||||
if not isinstance(capabilities, list):
|
||||
raise ProjectionError("protocol.capabilities must be an array")
|
||||
merged: dict[str, Any] = {}
|
||||
participating: list[dict[str, str]] = []
|
||||
for entry in capabilities:
|
||||
if not isinstance(entry, dict):
|
||||
raise ProjectionError("protocol.capabilities entries must be objects")
|
||||
# Rule O1 first, for every entry: a forbidden/unknown per-revision override makes the document
|
||||
# unprojectable even when the entry is not advertisable (G5).
|
||||
check_override_policy(entry, entry.get("surface"), era)
|
||||
resolved = effective(entry, era)
|
||||
# F8: every field this projection reads is type-checked before it is used, so a malformed
|
||||
# kind/subfeature/map is a bounded rejection instead of an unhandled interpreter error.
|
||||
kind = resolved.get("kind")
|
||||
if not isinstance(kind, str) or not kind:
|
||||
raise ProjectionError(
|
||||
f"kind of a protocol.capabilities entry must be a non-empty string for {era}: {kind!r}"
|
||||
)
|
||||
if kind not in ADVERTISABLE_KINDS:
|
||||
continue
|
||||
role = resolved.get("role")
|
||||
if not isinstance(role, str) or not role:
|
||||
raise ProjectionError(
|
||||
f"role of a protocol.capabilities entry must be a non-empty string for {era}: {role!r}"
|
||||
)
|
||||
# H2: the declared per-era subfeature accounting of every capability record is compared with the
|
||||
# reviewed pinned basis before the advertisable filter, so a misdeclared row can never be
|
||||
# projected (and never silently skipped) either.
|
||||
check_subfeature_basis(resolved, era)
|
||||
if role != "server":
|
||||
continue
|
||||
status = resolved.get("status")
|
||||
if not isinstance(status, str) or not status:
|
||||
raise ProjectionError(
|
||||
f"status of a protocol.capabilities entry must be a non-empty string for {era}: "
|
||||
f"{status!r}"
|
||||
)
|
||||
if status != "supported":
|
||||
continue
|
||||
# Eligibility is read from the *default* applicability scope, before any merge (rule O1: an
|
||||
# override may never move the window), exactly as the validator resolves it.
|
||||
revisions = entry.get("revisions")
|
||||
if not isinstance(revisions, list) or not all(isinstance(item, str) for item in revisions):
|
||||
raise ProjectionError(
|
||||
f"revisions of one advertisable entry must be an array of revision strings for {era}: "
|
||||
f"{revisions!r}"
|
||||
)
|
||||
if era not in revisions:
|
||||
continue
|
||||
surface = required_text(resolved.get("surface"), "surface", era)
|
||||
fragment = resolved.get("advertised")
|
||||
if not isinstance(fragment, dict) or not fragment:
|
||||
raise ProjectionError(
|
||||
f"supported server {kind} {surface!r} must carry a non-null "
|
||||
f"advertised fragment for {era}"
|
||||
)
|
||||
declared = resolved.get("subfeatures")
|
||||
if not isinstance(declared, list) or not all(isinstance(item, str) for item in declared):
|
||||
raise ProjectionError(
|
||||
f"subfeatures of {surface!r} must be an array of strings for {era}: {declared!r}"
|
||||
)
|
||||
declared_keys = set(declared)
|
||||
open_flag = resolved.get("open_subfeatures")
|
||||
if not isinstance(open_flag, bool):
|
||||
raise ProjectionError(
|
||||
f"open_subfeatures of {surface!r} must be a boolean for {era}: {open_flag!r}"
|
||||
)
|
||||
open_map = open_flag
|
||||
expected_key = advertisement_key(kind, surface)
|
||||
for top_key, value in fragment.items():
|
||||
if top_key != expected_key:
|
||||
raise ProjectionError(
|
||||
f"advertised top-level key {top_key!r} does not belong to the declaring surface "
|
||||
f"{surface!r} (expected {expected_key!r}) for {era}"
|
||||
)
|
||||
if not isinstance(value, dict):
|
||||
raise ProjectionError(
|
||||
f"advertised fragment {top_key!r} of {surface!r} must be a JSON object for {era}"
|
||||
)
|
||||
if top_key in merged:
|
||||
raise ProjectionError(
|
||||
f"conflicting top-level advertised key {top_key!r} while projecting {era}"
|
||||
)
|
||||
for leaf, leaf_value in leaf_items(value):
|
||||
if not open_map and leaf not in declared_keys:
|
||||
raise ProjectionError(
|
||||
f"advertised leaf {leaf!r} of {surface!r} is not declared by subfeatures for {era}"
|
||||
)
|
||||
pinned = PINNED_LEAF_TYPES.get(f"{top_key}.{leaf}")
|
||||
if pinned is not None and type(leaf_value) is not pinned:
|
||||
raise ProjectionError(
|
||||
f"advertised leaf {leaf!r} of {surface!r} must be a {pinned.__name__} in the "
|
||||
f"pinned revision for {era}: {leaf_value!r}"
|
||||
)
|
||||
merged[top_key] = value
|
||||
participating.append(
|
||||
{"role": str(resolved.get("role")), "kind": str(resolved.get("kind")), "surface": str(surface)}
|
||||
)
|
||||
return merged, participating
|
||||
|
||||
|
||||
def canonical_bytes(payload: dict[str, Any]) -> bytes:
|
||||
"""Compact UTF-8, sorted keys, no trailing newline (accepted SPEC section 5).
|
||||
|
||||
`allow_nan=False` is the backstop of the strict parse: a non-standard JSON constant may never be
|
||||
serialized into the frozen artifact (G4).
|
||||
"""
|
||||
return json.dumps(
|
||||
payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False
|
||||
).encode("utf-8")
|
||||
|
||||
|
||||
def main() -> int:
|
||||
args = parse_args()
|
||||
try:
|
||||
document, digest = load_inventory(args.inventory)
|
||||
protocol = document.get("protocol")
|
||||
if not isinstance(protocol, dict):
|
||||
raise ProjectionError("inventory has no protocol block")
|
||||
projected, participating = project(protocol.get("capabilities"), args.revision)
|
||||
except ProjectionError as error:
|
||||
sys.stderr.write(f"error[PROJECTION_REJECTED] /protocol: {error}\n")
|
||||
return 1
|
||||
except (TypeError, ValueError) as error:
|
||||
# A malformed input shape that the explicit field checks above did not name: the CLI still
|
||||
# answers with a deterministic bounded rejection instead of an unhandled interpreter error.
|
||||
sys.stderr.write(
|
||||
f"error[PROJECTION_REJECTED] /protocol: malformed projection input: {error}\n"
|
||||
)
|
||||
return 1
|
||||
|
||||
frozen_bytes = canonical_bytes(projected)
|
||||
provenance = {
|
||||
"revision": args.revision,
|
||||
"inventory_path": str(args.inventory),
|
||||
"inventory_sha256": digest,
|
||||
"rule": PROJECTION_RULE,
|
||||
"projection_inputs": participating,
|
||||
"note": (
|
||||
"Sidecar provenance only. Never compared byte-for-byte with the endpoint; the payload "
|
||||
"oracle is the sibling .frozen.json file."
|
||||
),
|
||||
}
|
||||
args.frozen.parent.mkdir(parents=True, exist_ok=True)
|
||||
args.provenance.parent.mkdir(parents=True, exist_ok=True)
|
||||
args.frozen.write_bytes(frozen_bytes)
|
||||
args.provenance.write_text(json.dumps(provenance, indent=2) + "\n", encoding="utf-8")
|
||||
print(
|
||||
f"projected {args.revision}: top_level_keys={len(projected)} "
|
||||
f"bytes={len(frozen_bytes)} sha256={hashlib.sha256(frozen_bytes).hexdigest()}"
|
||||
)
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
File diff suppressed because it is too large.
Load diff
Reference in new issue
Block a user