tests/interaction: add compute_cells/cell_id helpers and __post_init__ self-tests

compute_cells() expands a test's stacked @requirement marks into the
(transport, spec_version) pytest.param list with intersection semantics:
a cell is dropped if any requirement's [added_in, removed_in) window or
arm_exclusions excludes it, and marked xfail-strict if any requirement's
known_failures matches it. Requirement.transports is intentionally not
consulted (descriptive metadata only). cell_id() keeps node-id suffixes
as bare transport names while SPEC_VERSIONS has a single entry.

test_coverage.py gains pytest.raises self-tests for every new
__post_init__ validation branch on ArmExclusion / KnownFailure /
Requirement.

12 passed; pyright/ruff clean; conftest not yet wired.

Claude-Session: https://claude.ai/code/session_01NF95tmzF6RhVPktJdL6fK5

Author: maxisbey

tests/interaction/_requirements.py

@@ -33,9 +33,9 @@
 """
 
 import re
-from collections.abc import Callable
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass
-from typing import Literal, TypeVar
+from typing import Any, Literal, TypeVar
 
 import pytest
 
@@ -2889,3 +2889,74 @@ def apply(test_fn: _TestFn) -> _TestFn:
 def covered_by(requirement_id: str) -> list[str]:
     """Return the (mutable) list of test names recorded as exercising `requirement_id`."""
     return _COVERAGE.setdefault(requirement_id, [])
+
+
+def cell_id(transport: Transport, version: SpecVersion, *, spec_versions: Sequence[SpecVersion] = SPEC_VERSIONS) -> str:
+    """Return the pytest node-id suffix for a (transport, spec_version) cell.
+
+    While the active matrix has a single spec version, the suffix is just the transport name so
+    existing node ids stay byte-identical; once a second version is on the axis the suffix becomes
+    ``transport-version``.
+    """
+    return transport if len(spec_versions) == 1 else f"{transport}-{version}"
+
+
+def compute_cells(
+    requirements: Sequence[Requirement],
+    *,
+    spec_versions: Sequence[SpecVersion] = SPEC_VERSIONS,
+    transports: Sequence[Transport] = CONNECTABLE_TRANSPORTS,
+) -> list[Any]:
+    """Compute the (transport, spec_version) parametrization cells for a test.
+
+    Stacked ``@requirement`` decorators contribute multiple entries; the cells emitted are the
+    INTERSECTION across all of them: a cell is dropped if it falls outside any requirement's
+    ``[added_in, removed_in)`` window or matches any requirement's ``arm_exclusions``. An empty
+    ``requirements`` sequence yields the full transport x spec-version grid.
+
+    ``Requirement.transports`` is intentionally NOT consulted -- it is descriptive metadata about
+    where a behaviour is observable, not a cell filter (only ``arm_exclusions`` / ``added_in`` /
+    ``removed_in`` drive cell generation).
+
+    Returns a list of ``pytest.param((transport, version), id=..., marks=...)`` values for use as
+    ``metafunc.parametrize`` argvalues.
+    """
+    cells: list[Any] = []
+    for version in spec_versions:
+        version_ordinal = KNOWN_PROTOCOL_VERSIONS.index(version)
+        for transport in sorted(transports):
+            if transport in TRANSPORT_SPEC_VERSIONS and version not in TRANSPORT_SPEC_VERSIONS[transport]:
+                continue
+            # Requirement.transports is descriptive metadata only and does not filter cells.
+            if any(
+                (req.added_in is not None and version_ordinal < KNOWN_PROTOCOL_VERSIONS.index(req.added_in))
+                or (req.removed_in is not None and version_ordinal >= KNOWN_PROTOCOL_VERSIONS.index(req.removed_in))
+                for req in requirements
+            ):
+                continue
+            if any(
+                (ex.transport is None or ex.transport == transport)
+                and (ex.spec_version is None or ex.spec_version == version)
+                for req in requirements
+                for ex in req.arm_exclusions
+            ):
+                continue
+            matched_failure = next(
+                (
+                    kf
+                    for req in requirements
+                    for kf in req.known_failures
+                    if (kf.transport is None or kf.transport == transport)
+                    and (kf.spec_version is None or kf.spec_version == version)
+                ),
+                None,
+            )
+            marks = [pytest.mark.xfail(reason=matched_failure.note, strict=True)] if matched_failure else ()
+            cells.append(
+                pytest.param(
+                    (transport, version),
+                    id=cell_id(transport, version, spec_versions=spec_versions),
+                    marks=marks,
+                )
+            )
+    return cells

tests/interaction/test_coverage.py

@@ -11,10 +11,19 @@
 import re
 from pathlib import Path
 from types import ModuleType
+from typing import cast
 
 import pytest
 
-from tests.interaction._requirements import REQUIREMENTS, Requirement, covered_by, requirement
+from tests.interaction._requirements import (
+    REQUIREMENTS,
+    ArmExclusion,
+    KnownFailure,
+    Requirement,
+    SpecVersion,
+    covered_by,
+    requirement,
+)
 
 _SUITE_ROOT = Path(__file__).parent
 _REPO_ROOT = _SUITE_ROOT.parent.parent
@@ -103,3 +112,45 @@ def test_invalid_requirement_source_is_rejected() -> None:
     """A requirement whose source is not a spec URL, 'sdk', or an issue reference fails at construction."""
     with pytest.raises(ValueError, match="source must be a specification URL"):
         Requirement(source="https://example.com/not-the-spec", behavior="Never constructed.")
+
+
+def test_arm_exclusion_with_unknown_spec_version_is_rejected() -> None:
+    """An arm exclusion naming a spec version outside KNOWN_PROTOCOL_VERSIONS fails at construction."""
+    with pytest.raises(ValueError, match="is not in KNOWN_PROTOCOL_VERSIONS"):
+        ArmExclusion(reason="requires-session", spec_version=cast("SpecVersion", "2099-01-01"))
+
+
+def test_known_failure_with_empty_note_is_rejected() -> None:
+    """A known failure with a blank note fails at construction."""
+    with pytest.raises(ValueError, match="note must be non-empty"):
+        KnownFailure(note="   ")
+
+
+def test_known_failure_with_unknown_spec_version_is_rejected() -> None:
+    """A known failure naming a spec version outside KNOWN_PROTOCOL_VERSIONS fails at construction."""
+    with pytest.raises(ValueError, match="is not in KNOWN_PROTOCOL_VERSIONS"):
+        KnownFailure(note="x", spec_version=cast("SpecVersion", "2099-01-01"))
+
+
+def test_known_failure_with_malformed_issue_is_rejected() -> None:
+    """A known failure whose issue reference is neither '#<n>' nor a GitHub URL fails at construction."""
+    with pytest.raises(ValueError, match="must be '#<n>' or a GitHub URL"):
+        KnownFailure(note="x", issue="not-a-link")
+
+
+def test_requirement_with_unknown_added_in_is_rejected() -> None:
+    """A requirement whose added_in is outside KNOWN_PROTOCOL_VERSIONS fails at construction."""
+    with pytest.raises(ValueError, match="added_in .* is not in KNOWN_PROTOCOL_VERSIONS"):
+        Requirement(source="sdk", behavior="x", added_in=cast("SpecVersion", "2099-01-01"))
+
+
+def test_requirement_with_unknown_removed_in_is_rejected() -> None:
+    """A requirement whose removed_in is outside KNOWN_PROTOCOL_VERSIONS fails at construction."""
+    with pytest.raises(ValueError, match="removed_in .* is not in KNOWN_PROTOCOL_VERSIONS"):
+        Requirement(source="sdk", behavior="x", removed_in=cast("SpecVersion", "2099-01-01"))
+
+
+def test_requirement_with_empty_version_range_is_rejected() -> None:
+    """A requirement whose added_in is not strictly earlier than its removed_in fails at construction."""
+    with pytest.raises(ValueError, match="must be earlier than"):
+        Requirement(source="sdk", behavior="x", added_in="2025-11-25", removed_in="2025-11-25")