tests/interaction: manifest invariants and README for the era-axis model

test_coverage.py gains five manifest-level invariants (vacuously green
until entries start using the new fields):
- SPEC_VERSIONS subset of KNOWN_PROTOCOL_VERSIONS and includes LATEST
- CONNECTABLE_TRANSPORTS == conftest._FACTORIES keys
- supersedes / superseded_by links are bidirectional and versioned
- every arm_exclusion / known_failure targets a reachable cell

README.md: the requirements-manifest field list documents the new
fields, and the spec-revision section is rewritten as 'Spec versions
and the era axis' covering compute_cells() intersection semantics, the
transports-is-metadata-only rule, and the checklist for landing a new
revision.

Full gate: 2299 passed, 100.00% coverage, pyright/ruff clean,
411 connect cells with unchanged ids.

Author: maxisbey

tests/interaction/README.md

@@ -95,6 +95,14 @@ clients can share one session manager.
   would require real-time waits the suite refuses.
 - **`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.
+- **`note`** carries free-form context that does not fit `divergence` or `deferred`.
+- **`added_in`** / **`removed_in`** bound the spec versions the behaviour exists in, as a half-open
+  `[added_in, removed_in)` window.
+- **`supersedes`** / **`superseded_by`** link a retired entry to its replacement; the link is
+  bidirectional and both ends must be versioned.
+- **`arm_exclusions`** carve specific `(transport, spec_version)` matrix cells out with a typed
+  `ArmExclusionReason`.
+- **`known_failures`** mark specific `(transport, spec_version)` cells as strict xfail.
 
 Tests link themselves to the manifest with a decorator:
 
@@ -126,15 +134,45 @@ This is also the triage key for any rewrite: a test that fails on the new code p
 divergence note (the rewrite accidentally fixed a known gap — decide whether to keep the fix) or
 it does not (the rewrite broke something that was correct — fix the rewrite).
 
-### When a new spec revision is released
-
-1. Update `SPEC_REVISION` and walk the new revision's changelog.
-2. For each changed interaction, find its requirements (the IDs use the wire method strings the
-   changelog speaks in), re-audit the tests against the new text, and update `source` links and
-   assertions where behaviour legitimately changed.
-3. New interactions get new requirements and new tests; removed interactions get their
-   requirements deleted along with their tests.
-4. A behaviour that is correct under both revisions needs no change beyond the `source` link.
+### Spec versions and the era axis
+
+`SPEC_VERSIONS` in `_requirements.py` is the ordered tuple of protocol revisions the suite
+exercises; `SPEC_REVISION = SPEC_VERSIONS[-1]` is the newest. The `connect` fixture fans out over
+`CONNECTABLE_TRANSPORTS × SPEC_VERSIONS`, but the grid is filtered per test:
+`pytest_generate_tests` reads the test's stacked `@requirement` marks and calls `compute_cells()`,
+which intersects the admissible cells across every cited requirement — a cell survives only if
+**all** of the test's requirements admit it.
+
+What admits or excludes a cell:
+
+- **`added_in` / `removed_in`** gate which spec versions a requirement exists in, as a half-open
+  `[added_in, removed_in)` window. A test runs only on versions inside every cited requirement's
+  window.
+- **`arm_exclusions`** carve specific `(transport, spec_version)` cells out with a typed
+  `ArmExclusionReason`. The reason vocabulary doubles as a re-admission checklist: when the gap
+  closes, grep for the reason string to find every cell to re-admit.
+- **`known_failures`** keep a cell in the grid but mark it as a strict xfail — the test runs and
+  must fail; an unexpected pass fails the suite.
+- **`transports`** is descriptive metadata for the non-`connect` transport-specific suites under
+  `transports/` and does **not** drive cell generation. Only `arm_exclusions`, `added_in`, and
+  `removed_in` filter the grid.
+- **`supersedes` / `superseded_by`** link a retired entry to its replacement. `test_coverage.py`
+  enforces that links are bidirectional and versioned: the retired entry carries `removed_in`, the
+  replacement carries `added_in`.
+
+Node IDs stay `[transport]` while `len(SPEC_VERSIONS) == 1`, so today's test IDs are
+byte-identical to before the era axis existed. They become `[transport-version]` the moment a
+second version is appended to `SPEC_VERSIONS`.
+
+When a new spec revision lands:
+
+1. Append the version string to `SPEC_VERSIONS` (and to the `SpecVersion` `Literal`).
+2. Walk the new revision's changelog.
+3. For each affected requirement: set `removed_in` on retired behaviour, add a new entry with
+   `added_in` for its replacement, and link the pair with `supersedes` / `superseded_by`.
+   Behaviour that survives unchanged needs nothing beyond a re-audit of its `source` URL.
+4. For requirements that cannot run on the new era's path, add an `arm_exclusions` entry with the
+   appropriate `ArmExclusionReason`.
 
 ## Writing a test
 

tests/interaction/test_coverage.py

@@ -15,9 +15,12 @@
 
 import pytest
 
+from mcp.shared.version import KNOWN_PROTOCOL_VERSIONS
+from mcp.types import LATEST_PROTOCOL_VERSION
 from tests.interaction._requirements import (
     CONNECTABLE_TRANSPORTS,
     REQUIREMENTS,
+    SPEC_VERSIONS,
     ArmExclusion,
     KnownFailure,
     Requirement,
@@ -28,6 +31,7 @@
     covered_by,
     requirement,
 )
+from tests.interaction.conftest import _FACTORIES
 
 _SUITE_ROOT = Path(__file__).parent
 _REPO_ROOT = _SUITE_ROOT.parent.parent
@@ -106,6 +110,59 @@ def test_deferral_reasons_cite_existing_paths() -> None:
     assert not missing, f"Deferral reasons citing paths that do not exist: {missing}"
 
 
+def test_spec_versions_are_known_and_include_latest() -> None:
+    """Every active spec version is one the SDK knows about, and the SDK's latest is on the active axis."""
+    assert set(SPEC_VERSIONS) <= set(KNOWN_PROTOCOL_VERSIONS)
+    assert LATEST_PROTOCOL_VERSION in SPEC_VERSIONS
+
+
+def test_connectable_transports_match_connect_factories() -> None:
+    """CONNECTABLE_TRANSPORTS and the conftest factory map name exactly the same transports."""
+    assert set(CONNECTABLE_TRANSPORTS) == set(_FACTORIES)
+
+
+def test_supersession_links_are_symmetric_and_versioned() -> None:
+    """``supersedes``/``superseded_by`` reference real entries, agree in both directions, and carry version bounds."""
+    broken = [
+        f"{req_id} -> {target}"
+        for req_id, req in REQUIREMENTS.items()
+        for target in req.supersedes
+        if target not in REQUIREMENTS or REQUIREMENTS[target].superseded_by != req_id or req.added_in is None
+    ] + [
+        f"{req_id} <- {req.superseded_by}"
+        for req_id, req in REQUIREMENTS.items()
+        if req.superseded_by is not None
+        if req.superseded_by not in REQUIREMENTS
+        or req_id not in REQUIREMENTS[req.superseded_by].supersedes
+        or req.removed_in is None
+    ]
+    assert not broken, f"Broken supersession links (forward '->' or back '<-'): {broken}"
+
+
+def test_every_arm_exclusion_targets_a_reachable_cell() -> None:
+    """Every arm exclusion names a connectable transport and an active spec version (or wildcards)."""
+    unreachable = [
+        f"{req_id}: {exclusion}"
+        for req_id, req in REQUIREMENTS.items()
+        for exclusion in req.arm_exclusions
+        if (exclusion.transport is not None and exclusion.transport not in CONNECTABLE_TRANSPORTS)
+        or (exclusion.spec_version is not None and exclusion.spec_version not in SPEC_VERSIONS)
+    ]
+    assert not unreachable, f"Arm exclusions targeting unreachable cells: {unreachable}"
+
+
+def test_every_known_failure_targets_a_reachable_cell() -> None:
+    """Every known failure names a connectable transport and an active spec version (or wildcards)."""
+    unreachable = [
+        f"{req_id}: {failure}"
+        for req_id, req in REQUIREMENTS.items()
+        for failure in req.known_failures
+        if (failure.transport is not None and failure.transport not in CONNECTABLE_TRANSPORTS)
+        or (failure.spec_version is not None and failure.spec_version not in SPEC_VERSIONS)
+    ]
+    assert not unreachable, f"Known failures targeting unreachable cells: {unreachable}"
+
+
 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'"):