CI / UI Checks (pull_request) Successful in 11s
CI / Rust Checks (pull_request) Failing after 4m11s
CI / Rust Feature Validation (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Required Checks (pull_request) Failing after 1s
CI / Deploy (pull_request) Skipped
Story 3.18 (#25) surface: клиент получает только закрытые structured `notifications/message` выбранного уровня, без запросов, секретов и internal causes. - `logging` capability advertising в обеих поддерживаемых revisions; `logging/setLevel` — legacy-only dispatch (modern — `_meta` per request); - закрытый словарь LoggingLevel (RFC 5424), malformed → -32602 с одним safe detail; закрытый набор safe events, task-local request scope; bounded in-memory opt-in, без миграций; - `notifications/message` идут перед ответом в SSE; JSON-режим их не несёт; - ATDD в `scripts/ci-story-checks.sh`: mcp_logging (10), inventory projection (3), protocol::logging unit (12); - проекция capability inventory/frozen oracle переведена на `logging`. Story ATDD и affected проверки пройдены на этом дереве (fmt, clippy, python oracle 56 OK, capability inventory valid). Полный `just verify` — NOT_RUN на story по validation-policy, остаётся на собранной фиче.
346 lines
16 KiB
Python
346 lines
16 KiB
Python
"""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 <path> --revision <2026-07-28|2025-11-25>
|
|
--frozen <path> --provenance <path>
|
|
|
|
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), so the committed
|
|
# oracle and the canonical projection carry `logging` next to `completions`/`prompts`/`resources`/`tools`.
|
|
COMMITTED_FROZEN = (
|
|
b'{"completions":{},"logging":{},"prompts":{"listChanged":false},"resources":{"listChanged":false,"subscribe":false},"tools":{"listChanged":false}}'
|
|
)
|
|
COMMITTED_SHA256 = "f806e750402d418b8a3784eff200338cd8fd91b69c2f99e9d564cb08217b84d2"
|
|
|
|
|
|
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()
|