"""Story 3.1 ATDD (red phase): the per-era advertised-capabilities projection artifact (AT-13). Oracle contract declared by this stage (the implementation stage owns the internals): scripts/project-advertised-capabilities.py --inventory --revision <2026-07-28|2025-11-25> --frozen --provenance The script reads ONLY the canonical inventory (`protocol` block), applies the server-only projection rules 1-4 of the accepted spec section 5, and writes * `--frozen` the canonical capabilities payload: one JSON object, UTF-8, compact (`:`/`,`), object keys sorted byte-lexicographically, no trailing newline; * `--provenance` a sidecar with `inventory_sha256`, the projection `rule` id and the participating identity triples. The sidecar is audit-only and is never byte-compared with the endpoint. It must never call the MCP server, must never import the registry and must never read a captured server response: the expectation is derived from the reviewed inventory alone. Why these tests are guarded: the executable does not exist on this revision, so a missing executable is an honest ARTIFACT gap (`skip`), NOT a behavioural red and NOT a pass. The moment the script lands, the same assertions run unchanged - that is the point of writing them now. """ from __future__ import annotations import copy import hashlib import json import subprocess import sys import tempfile import unittest from pathlib import Path ROOT = Path(__file__).resolve().parents[2] SCRIPT = ROOT / "scripts" / "project-advertised-capabilities.py" FIXTURES = ROOT / "tests" / "fixtures" / "mcp-revisions" CANDIDATE = FIXTURES / "inventory-reviewed-v2-candidate.json" MODERN = "2026-07-28" LEGACY = "2025-11-25" # The reviewed v2 candidate is a frozen Story 3.1 input: its Prompt capability is still deferred, so # its own projection stays `resources`+`tools`. EXPECTED_FROZEN = ( b'{"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}}' ) EXPECTED_SHA256 = "e38c795fc28fee74168cb045427df55d882f8f7ace206af5c9a3ca4df5892c9a" # The canonical inventory also implements the logging surface (Story 3.18, FR-19), the # Resource/Prompt list-change signals (Story 3.19, FR-19) and the Tools list-change signal # (Story 3.5, FR-14), so the committed oracle and the canonical projection carry `logging` next to # `completions`/`prompts`/`resources`/`tools`, and every `listChanged` leaf is now implemented. COMMITTED_FROZEN = ( b'{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true,"subscribe":false},"tools":{"listChanged":true}}' ) COMMITTED_SHA256 = "7ffa56029595fc84b6ee29930d65eada2b4d7cffd7d76f72a945fe795cabfe0f" class AdvertisedCapabilitiesProjectionTests(unittest.TestCase): def setUp(self) -> None: if not SCRIPT.is_file(): self.skipTest( "artifact gap, not a behavioural red: scripts/project-advertised-capabilities.py is " "created by the implementation stage (BUILD); the assertions below are ready and run " "unchanged once the executable exists" ) self._temporary_directory = tempfile.TemporaryDirectory() self.root = Path(self._temporary_directory.name) self.addCleanup(self._temporary_directory.cleanup) def load_candidate(self) -> dict: return json.loads(CANDIDATE.read_text(encoding="utf-8")) def project(self, inventory: dict, revision: str, stem: str) -> subprocess.CompletedProcess[str]: inventory_path = self.root / f"{stem}.inventory.json" inventory_path.write_text(json.dumps(inventory), encoding="utf-8") return subprocess.run( [ sys.executable, str(SCRIPT), "--inventory", str(inventory_path), "--revision", revision, "--frozen", str(self.root / f"{stem}.frozen.json"), "--provenance", str(self.root / f"{stem}.provenance.json"), ], check=False, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, cwd=str(ROOT), ) def frozen(self, stem: str) -> Path: return self.root / f"{stem}.frozen.json" def test_positive_projection_equals_the_committed_frozen_oracle_for_both_eras(self) -> None: candidate = self.load_candidate() for revision in (MODERN, LEGACY): with self.subTest(revision=revision): result = self.project(candidate, revision, f"positive-{revision}") combined = result.stdout + result.stderr self.assertEqual(result.returncode, 0, combined) produced = self.frozen(f"positive-{revision}").read_bytes() self.assertEqual(produced, EXPECTED_FROZEN) # The committed oracle is projected from the canonical inventory, which now also # implements the Prompt vertical (Story 3.14); the reviewed v2 candidate is a frozen # Story 3.1 input and is intentionally no longer byte-equal to it. The canonical # inventory -> committed oracle equality is pinned by # `test_r10_canonical_inventory_projects_to_the_committed_oracle_and_binds_its_digest`. provenance = json.loads( (self.root / f"positive-{revision}.provenance.json").read_text(encoding="utf-8") ) self.assertTrue(provenance["rule"]) self.assertTrue(provenance["inventory_sha256"]) self.assertEqual( sorted( (item["role"], item["kind"], item["surface"]) for item in provenance["projection_inputs"] ), [("server", "capability", "resources"), ("server", "capability", "tools")], ) def test_client_role_capability_is_never_projected(self) -> None: candidate = self.load_candidate() for entry in candidate["protocol"]["capabilities"]: if entry["surface"] == "elicitation" and entry["role"] == "client": entry["status"] = "supported" entry["advertised"] = {"elicitation": {"form": {}}} for revision in (MODERN, LEGACY): with self.subTest(revision=revision): result = self.project(candidate, revision, f"client-role-{revision}") combined = result.stdout + result.stderr self.assertEqual(result.returncode, 0, combined) self.assertEqual(self.frozen(f"client-role-{revision}").read_bytes(), EXPECTED_FROZEN) def test_per_revision_override_changes_only_that_revision(self) -> None: candidate = self.load_candidate() for entry in candidate["protocol"]["capabilities"]: if entry["surface"] == "tools" and entry["role"] == "server": entry.setdefault("per_revision", {})[MODERN] = {"status": "deferred", "reason": "modern projection is empty"} modern = self.project(candidate, MODERN, "override-modern") self.assertEqual(modern.returncode, 0, modern.stdout + modern.stderr) self.assertEqual( self.frozen("override-modern").read_bytes(), b'{"resources":{"listChanged":false,"subscribe":false}}', "deferring tools for the modern era leaves the modern resources capability in place", ) legacy = self.project(candidate, LEGACY, "override-legacy") self.assertEqual(legacy.returncode, 0, legacy.stdout + legacy.stderr) self.assertEqual(self.frozen("override-legacy").read_bytes(), EXPECTED_FROZEN) def test_conflicting_top_level_advertised_keys_are_rejected(self) -> None: candidate = self.load_candidate() conflicting = copy.deepcopy(candidate["protocol"]["capabilities"][0]) conflicting.update( { "surface": "logging", "kind": "capability", "role": "server", "status": "supported", "advertised": {"tools": {"listChanged": True}}, } ) candidate["protocol"]["capabilities"].append(conflicting) result = self.project(candidate, MODERN, "conflict") self.assertNotEqual(result.returncode, 0, result.stdout) self.assertFalse(self.frozen("conflict").exists()) def test_advertised_leaf_not_declared_by_subfeatures_is_rejected(self) -> None: candidate = self.load_candidate() for entry in candidate["protocol"]["capabilities"]: if entry["surface"] == "tools" and entry["role"] == "server": entry["advertised"] = {"tools": {"listChanged": False, "unexpected": True}} result = self.project(candidate, MODERN, "undeclared-subfeature") self.assertNotEqual(result.returncode, 0, result.stdout) self.assertFalse(self.frozen("undeclared-subfeature").exists()) def test_supported_server_capability_without_advertised_is_rejected(self) -> None: candidate = self.load_candidate() for entry in candidate["protocol"]["capabilities"]: if entry["surface"] == "tools" and entry["role"] == "server": entry["advertised"] = None result = self.project(candidate, MODERN, "missing-advertised") self.assertNotEqual(result.returncode, 0, result.stdout) self.assertFalse(self.frozen("missing-advertised").exists()) # --- Story 3.1 #8 remaining-foundation regressions (R3 producer side, R10 canonical chain) ----- # The validator (Gate A) and the producer must reject the same malformed advertisement shape # independently: a scalar fragment and a top-level key that does not belong to the declaring # surface both produce a `capabilities` object that is not the reviewed projection. def test_r3_scalar_advertised_fragment_is_rejected_by_the_producer(self) -> None: candidate = self.load_candidate() for entry in candidate["protocol"]["capabilities"]: if entry["surface"] == "tools" and entry["role"] == "server": entry["advertised"] = {"tools": True} result = self.project(candidate, MODERN, "r3-scalar-fragment") self.assertNotEqual( result.returncode, 0, "a scalar advertisement fragment cannot be a canonical capabilities object: " + result.stdout + result.stderr, ) self.assertFalse(self.frozen("r3-scalar-fragment").exists()) def test_r3_foreign_top_level_advertised_key_is_rejected_by_the_producer(self) -> None: candidate = self.load_candidate() for entry in candidate["protocol"]["capabilities"]: if entry["surface"] == "tools" and entry["role"] == "server": entry["advertised"] = {"prompts": {"listChanged": False}} result = self.project(candidate, MODERN, "r3-foreign-key") self.assertNotEqual( result.returncode, 0, "an advertised top-level key that does not belong to the declaring surface must be " "rejected: " + result.stdout + result.stderr, ) self.assertFalse(self.frozen("r3-foreign-key").exists()) def test_r10_canonical_inventory_projects_to_the_committed_oracle_and_binds_its_digest(self) -> None: """The reproducible chain: canonical inventory -> projection -> committed frozen bytes. The producer is run on the real canonical artifact (`docs/capability-inventory.json`), so the frozen bytes and the sidecar digest are derived from the canonical source rather than from a fixture. The committed sidecar itself is pinned by `test_story31_foundation_boundaries.py` (it must record the canonical digest). """ canonical = ROOT / "docs" / "capability-inventory.json" self.assertTrue(canonical.is_file(), "the canonical inventory must exist") canonical_digest = hashlib.sha256(canonical.read_bytes()).hexdigest() for revision in (MODERN, LEGACY): with self.subTest(revision=revision): inventory_path = self.root / f"canonical-{revision}.inventory.json" inventory_path.write_bytes(canonical.read_bytes()) result = subprocess.run( [ sys.executable, str(SCRIPT), "--inventory", str(inventory_path), "--revision", revision, "--frozen", str(self.root / f"canonical-{revision}.frozen.json"), "--provenance", str(self.root / f"canonical-{revision}.provenance.json"), ], check=False, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, cwd=str(ROOT), ) combined = result.stdout + result.stderr self.assertEqual(result.returncode, 0, combined) produced = (self.root / f"canonical-{revision}.frozen.json").read_bytes() committed = (FIXTURES / f"{revision}-advertised-capabilities.frozen.json").read_bytes() self.assertEqual( produced, committed, "the canonical inventory must project to the committed frozen oracle", ) provenance = json.loads( (self.root / f"canonical-{revision}.provenance.json").read_text(encoding="utf-8") ) self.assertEqual( provenance["inventory_sha256"], canonical_digest, "the producer must record the digest of the inventory it actually read", ) self.assertEqual( sorted( (item["role"], item["kind"], item["surface"]) for item in provenance["projection_inputs"] ), [ ("server", "capability", "completions"), ("server", "capability", "logging"), ("server", "capability", "prompts"), ("server", "capability", "resources"), ("server", "capability", "tools"), ], ) class CommittedFrozenOracleTests(unittest.TestCase): """The committed per-era oracle artifacts themselves (runs without the future executable).""" def test_committed_frozen_oracle_is_canonical_and_matches_its_sidecar(self) -> None: for revision in (MODERN, LEGACY): with self.subTest(revision=revision): frozen = FIXTURES / f"{revision}-advertised-capabilities.frozen.json" payload = frozen.read_bytes() self.assertEqual( payload, COMMITTED_FROZEN ) self.assertEqual(hashlib.sha256(payload).hexdigest(), COMMITTED_SHA256) self.assertEqual( json.dumps(json.loads(payload), sort_keys=True, separators=(",", ":")).encode("utf-8"), payload, "the frozen payload must already be in canonical form", ) sidecar = json.loads( (FIXTURES / f"{revision}-advertised-capabilities.provenance.json").read_text( encoding="utf-8" ) ) self.assertTrue(sidecar["inventory_sha256"]) self.assertTrue(sidecar["rule"]) self.assertEqual( sorted( (item["role"], item["kind"], item["surface"]) for item in sidecar["projection_inputs"] ), [ ("server", "capability", "completions"), ("server", "capability", "logging"), ("server", "capability", "prompts"), ("server", "capability", "resources"), ("server", "capability", "tools"), ], "the sidecar must name the exact full projection input set, in any order", ) if __name__ == "__main__": unittest.main()