Files
crank/tests/unit/test_project_advertised_capabilities.py
T
bsodfather a965bc4137
CI / UI Checks (pull_request) Successful in 9s
CI / Rust Checks (pull_request) Failing after 4m10s
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
feat(epic3): уведомления об изменении Resource/Prompt каталога MCP (Story 3.19)
Story 3.19 / FR-19 на принятой базе Story 3.18 (`47a6e54`, PR #99): после
commit опубликованного каталога Agent клиент получает
`notifications/resources/list_changed` и/или
`notifications/prompts/list_changed`, обе pinned revisions, а обычное чтение
каталога остаётся авторитетным при потере сигнала. Scope ограничен
list-change: `resources/subscribe`/`unsubscribe` остаются `-32601`, значение
`resources.subscribe` остаётся `false` (одобренный владельцем вариант A).

Публикация переносит только semantic delta Story 3.19 из
`/home/codex/code/crank-worktrees/story31-worktree`
(`1b6db09` + cumulative overlay) на принятый head 3.18, а не копирует
worktree:
- новый `protocol/signals.rs` (watcher, отпечаток каталога, bounded filter,
  revision-correct encoders, bounded legacy stream registry) и
  `protocol/signals_tests.rs` (17 unit oracles);
- `subscriptions/listen` (modern-only dispatch registration) + честные
  `listChanged: true` объявления; `app/endpoint.rs` получает legacy GET
  producer/DELETE retire, `app/dispatch.rs` — modern listen stream;
- ATDD `mcp_signals` 5 сценариев на реальном endpoint/PostgreSQL/artifact
  store; capability inventory и frozen/provenance проекции обновлены
  (`b90b59f3…`, inventory `10ca3538…`);
- `scripts/ci-story-checks.sh`: добавлены 3.19-проверки, записи Story 3.18
  сохранены (гейт не ослаблен).

Принятая правка code-health `206ca78` сохранена: `app/endpoint.rs` 402 строки
(было 381), `app/legacy_dispatch.rs` 731 без изменений, т.е. split не
переписан. Новый ATDD-файл `mcp_signals.rs` до 1138 строк превышал лимит
`scripts/check-rust-code-health.sh`, поэтому его сценарии механически
вынесены в `mcp_signals/scenarios.rs` без изменения проверок.

Наследованный дефект tooling-гейта: `tests/unit/test_validate_capability_inventory.py`
требует, чтобы `Run tooling unit tests` шёл раньше
`scripts/validate-capability-inventory.py`; в принятом `ci.yml` (3.18) шаг
оказался в условном feature-job. Шаг перенесён в обязательный `rust` job перед
проверкой inventory — исполняемый tooling-гейт теперь проверяется там же, где
применяется; ни одна проверка не отключена и не ослаблена.

Проверки на этом коммите: `ci-story-checks.sh` exit 0 — 4/9/1/12/10/3/5(+1
manual ignored)/17 passed; `crank-community-mcp --lib` 102/0; transport 20/0,
mcp_prompts 15/0, revision_matrix::negotiation 23/0, era_isolation 5/0;
`cargo fmt --check` и `cargo clippy -p crank-community-mcp -p mcp-server
--all-targets -D warnings` — 0; `check-rust-code-health.sh` — pass;
capability inventory `status=valid protocol_items=50 revisions=2`;
`python3 -m unittest discover -s tests/unit` — 305 OK.

NOT_RUN (честно, не PASS): полный `just verify`, межкомпонентная интеграция,
нагрузка и квалификация ≥3 реальных клиентов — остаются на собранной фиче 3.20
по validation-policy.md.
2026-10-25 21:00:51 +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) and the
# Resource/Prompt list-change signals (Story 3.19, FR-19), so the committed oracle and the canonical
# projection carry `logging` next to `completions`/`prompts`/`resources`/`tools`, and both
# `listChanged` leaves are now implemented.
COMMITTED_FROZEN = (
b'{"completions":{},"logging":{},"prompts":{"listChanged":true},"resources":{"listChanged":true,"subscribe":false},"tools":{"listChanged":false}}'
)
COMMITTED_SHA256 = "b90b59f32e2e5c43e829b96339b99a52852bc04f48a2ca0ce7e971affa3a878e"
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()