test: track the full requirements surface in the interaction manifest

Author: maxisbey

tests/interaction/README.md

@@ -60,11 +60,15 @@ test body — each directory pins its flavour's true output exactly.
 - **`source`** is a deep link into the MCP specification for externally mandated behaviour,
   the literal string `"sdk"` for behaviour the SDK chose where the spec is silent, or
   `"issue:#n"` for a regression lock.
-- **`behavior`** describes what the suite *asserts* — which is always the SDK's current
-  behaviour, never an aspiration.
-- **`divergence`** records the gap when current behaviour differs from what `source` mandates,
-  with an issue link once one exists. The test still pins current behaviour.
-- **`deferred`** marks a behaviour that is deliberately not covered, with the reason.
+- **`behavior`** describes the *required* behaviour — what the specification (or the SDK's own
+  contract) says should happen. Tests always pin the SDK's current behaviour; where that falls
+  short of `behavior`, the gap is recorded as data rather than hidden in the test.
+- **`divergence`** records that gap for entries whose tests pin the divergent current behaviour.
+- **`deferred`** marks a behaviour that is tracked but not yet covered by a test in this suite.
+  The reason names the covering tests elsewhere in the repo, starts with "Not implemented in the
+  SDK" for genuine feature gaps, or starts with "Not yet covered here" for tests that are planned.
+- **`transports`** names the transports a behaviour applies to; omitted means transport-independent.
+- **`issue`** carries the tracking link for a recorded gap once one is filed.
 
 Tests link themselves to the manifest with a decorator:
 

tests/interaction/_requirements.py

@@ -20,6 +20,7 @@
 
 
 @requirement("protocol:cancel:in-flight")
+@requirement("protocol:cancel:handler-abort-propagates")
 async def test_cancellation_stops_in_flight_handler() -> None:
     """Cancelling an in-flight request interrupts its handler and fails the pending call.
 

tests/interaction/lowlevel/test_cancellation.py

@@ -20,6 +20,7 @@
 
 
 @requirement("completion:prompt-arg")
+@requirement("completion:result-shape")
 async def test_complete_prompt_argument() -> None:
     """Completing a prompt argument delivers the ref, argument name, and current value to the handler.
 

tests/interaction/lowlevel/test_completion.py

@@ -46,6 +46,7 @@
 pytestmark = pytest.mark.anyio
 
 
+@requirement("lifecycle:initialize:basic")
 @requirement("lifecycle:initialize:server-info")
 async def test_initialize_returns_server_info() -> None:
     """Every identity field the server declares is returned to the client in server_info."""

tests/interaction/lowlevel/test_initialize.py

@@ -12,6 +12,7 @@
 pytestmark = pytest.mark.anyio
 
 
+@requirement("lifecycle:ping")
 @requirement("ping:client-to-server")
 async def test_client_ping_returns_empty_result() -> None:
     """A client ping is answered with an empty result, even by a server with no handlers."""
@@ -23,6 +24,7 @@ async def test_client_ping_returns_empty_result() -> None:
     assert result == snapshot(EmptyResult())
 
 
+@requirement("lifecycle:ping")
 @requirement("ping:server-to-client")
 async def test_server_ping_returns_empty_result() -> None:
     """A server-initiated ping sent while a request is in flight is answered by the client.

tests/interaction/lowlevel/test_ping.py

@@ -2,11 +2,13 @@
 
 The contract runs in both directions: every non-deferred entry in :data:`REQUIREMENTS` must be
 exercised by at least one test, and every test in the suite must carry at least one
-`@requirement(...)` mark referencing a manifest entry. Test modules are imported directly
+`@requirement(...)` mark referencing a manifest entry. Deferral reasons that point at coverage
+elsewhere in the repo must point at paths that exist. Test modules are imported directly
 (rather than relying on pytest collection) so the check holds even when only this file is run.
 """
 
 import importlib
+import re
 from pathlib import Path
 from types import ModuleType
 
@@ -15,6 +17,10 @@
 from tests.interaction._requirements import REQUIREMENTS, Requirement, covered_by, requirement
 
 _SUITE_ROOT = Path(__file__).parent
+_REPO_ROOT = _SUITE_ROOT.parent.parent
+
+# Repo paths cited inside deferral reasons ("Covered by tests/... ").
+_CITED_PATH = re.compile(r"(?:tests|src)/[\w./-]*\w")
 
 # Tests that exercise the suite's own helpers rather than an interaction-model behaviour.
 # Anything listed here is exempt from the every-test-has-a-requirement check.
@@ -70,6 +76,18 @@ def test_every_test_exercises_a_requirement() -> None:
     assert not stale_exemptions, f"Harness self-test exemptions that no longer exist: {stale_exemptions}"
 
 
+def test_deferral_reasons_cite_existing_paths() -> None:
+    """Every repo path named in a deferral reason exists, so coverage pointers cannot rot."""
+    missing = sorted(
+        f"{requirement_id}: {cited}"
+        for requirement_id, spec in REQUIREMENTS.items()
+        if spec.deferred is not None
+        for cited in _CITED_PATH.findall(spec.deferred)
+        if not (_REPO_ROOT / cited).exists()
+    )
+    assert not missing, f"Deferral reasons citing paths that do not exist: {missing}"
+
+
 def test_unknown_requirement_id_is_rejected() -> None:
     """Marking a test with an ID that is not in the manifest fails at decoration time."""
     with pytest.raises(KeyError, match="Unknown requirement id 'tools:call:does-not-exist'"):