Files
crank/tests/unit/test_project_advertised_capabilities.py
hermes-dev a0365bb80b feat(epic3): отправлять Tools catalog change signals после commit (Story 3.5, FR-14)
Клиент, согласовавший tools list-changed, получает bounded
`notifications/tools/list_changed` после коммита видимой Tool-проекции
опубликованного Agent snapshot; `tools/list` остаётся авторитетным для
клиента без notification и после reconnect.

- signals.rs: третий тип сигнала в существующем stream-local watcher
  (один tick = максимум один кадр на тип, fixed-capacity queue, без
  cross-process bus и без post-commit hook); fingerprint сравнивает
  tool_name/operation.version/title/description, поэтому Tool-only
  commit не даёт Resource/Prompt сигналов и наоборот.
- registry.rs: tools.listChanged=true (реально отправляется в обеих
  revision); modern filter toolsListChanged теперь подтверждается
  acknowledge и не шлётся вне согласованного набора.
- legacy GET-стрим несёт Tools-сигнал вместе с Resource/Prompt.
- ATDD: RED на baseline (ack пуст, Tools-кадра нет, capability false),
  GREEN — 8 integration-сценариев × обе revision, unit-оракулы wire,
  representatives official MCP SDK 1.32.2 smoke со штатными headers.
- capability inventory/baseline manifest и frozen projection обновлены
  под tools.listChanged=true; ci-story-checks.sh дополнен AC 3.5.
2026-10-26 17:22:07 +00:00

348 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), 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()