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

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

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

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

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

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

440 lines
21 KiB
Python
Executable File

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