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
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.
440 lines
21 KiB
Python
Executable File
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())
|