raptor-core 0.2.0__py3-none-any.whl

raptor/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2026 Alessandro Masat
+# SPDX-License-Identifier: Apache-2.0
+
+"""raptor — the protocol spine of the RAPTOR family.
+
+Pure contracts; depends on nothing. Schemas live in :mod:`raptor.schema`;
+typing.Protocols live in :mod:`raptor.protocols`.
+"""
+
+from __future__ import annotations
+
+from .version import __version__
+
+__all__ = ["__version__"]

raptor/conformance/__init__.py

@@ -0,0 +1,38 @@
+# Copyright 2026 Alessandro Masat
+# SPDX-License-Identifier: Apache-2.0
+
+"""raptor.conformance — the interop certification declaration and its
+reusable matrix-hygiene scanners. See :mod:`raptor.conformance.interop`.
+"""
+
+from __future__ import annotations
+
+from .interop import (
+    CERTIFIED,
+    ROADMAP,
+    ROW_KINDS,
+    ROWS,
+    UNIVERSE,
+    RowDecl,
+    assert_doc_rows_match,
+    assert_no_skip_tokens,
+    assert_rows_complete,
+    certified_framework,
+    register_row,
+    roadmap_framework,
+)
+
+__all__ = [
+    "CERTIFIED",
+    "ROADMAP",
+    "ROW_KINDS",
+    "ROWS",
+    "UNIVERSE",
+    "RowDecl",
+    "assert_doc_rows_match",
+    "assert_no_skip_tokens",
+    "assert_rows_complete",
+    "certified_framework",
+    "register_row",
+    "roadmap_framework",
+]

raptor/conformance/doc_includes.py

@@ -0,0 +1,178 @@
+# Copyright 2026 Alessandro Masat
+# SPDX-License-Identifier: Apache-2.0
+
+"""raptor.conformance.doc_includes — reusable Sphinx `include`/`literalinclude`
+target checker.
+
+**Why this exists.** `eagle/docs/conf.py` sets `suppress_warnings = [...,
+"docutils", ...]` -- the category Sphinx uses for "Include file ... not
+found" -- so a broken `literalinclude` target prints one warning line and the
+build still exits 0. Several of eagle's targets once pointed at a directory
+later extracted to a downstream package, and this shipped silently for the
+length of the pass. Blanket `-W` is not an option (most surfaced eagle
+warnings are pre-existing doxygen duplicate-ID noise under the SAME
+"docutils" category, so the suppression cannot be narrowed without also
+un-suppressing that noise). This module is a targeted,
+non-Sphinx-warning-dependent check instead: a plain filesystem scan that
+reproduces Sphinx's own path-resolution rules and asserts every
+`include`/`literalinclude` target exists.
+
+**Why it lives here, not downstream:** the logic was always path-free (it
+takes `docs_root` as an argument and knows nothing about which repos exist
+on disk or where they live), but it once shipped from a downstream sibling's
+own suite. That placement broke silently the day that sibling's own suite
+shape changed (a sibling-free venv-gate leg could no longer resolve the tool
+at all, landing the file blocked-at-collection instead of running). The
+claim "eagle's includes resolve" is eagle's; a claim gated only in a
+downstream sibling's suite stops running the day that suite changes shape.
+Moving the LOGIC here (raptor ships to every consumer; `include =
+["raptor*"]`) lets each owner (`eagle/python/tests/test_doc_includes.py`,
+a downstream package's own test) certify its OWN docs tree directly, with
+raptor keeping zero sibling/repo knowledge.
+
+**Resolution rules (reproduce Sphinx's `include`/`literalinclude` directives
+exactly -- verified against the live eagle tree, not assumed):**
+
+1. a target starting with "/" is relative to the docs SOURCE directory
+   (`docs_root`, the directory `conf.py` lives in) -- never the filesystem
+   root (a target like `/schemas/manifest-v1.schema.json` resolves to
+   `<docs_root>/schemas/manifest-v1.schema.json`, not `/schemas/...` on
+   disk);
+2. otherwise the target is relative to the directory containing the
+   document that names it (the common case);
+3. `_build/` is excluded -- it holds generated copies of the same source
+   pages (`_build/html/_sources/**`), so scanning it double-counts every
+   hit and would also flag the generated tree's own copies once a source
+   fix has already landed but the stale `_build/` has not been rebuilt.
+
+Handles both reStructuredText directives (``.. literalinclude:: target``,
+eagle's dialect) and MyST fenced directives (a code fence whose info string is
+``{literalinclude} target`` -- three backticks followed by that info string,
+the rest of the family's dialect) with the same scan, so the same call is
+reusable across the family regardless of which markup a repo's docs use.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+#: reST: ".. include:: target" / ".. literalinclude:: target" (optionally
+#: indented, e.g. nested inside a ".. dropdown::").
+_RST_DIRECTIVE = re.compile(r"^\s*\.\.\s+(include|literalinclude)::\s+(\S+)\s*$")
+
+#: MyST: "```{include} target" / "```{literalinclude} target" (the directive's
+#: argument sits on the fence line itself).
+_MYST_DIRECTIVE = re.compile(r"^\s*`{3,}\{(include|literalinclude)\}\s+(\S+)\s*$")
+
+#: Source file suffixes scanned. `.rst` (docutils) and `.md` (MyST) are the
+#: two dialects in use across the family's docs trees today.
+SOURCE_SUFFIXES = (".rst", ".md")
+
+
+@dataclass(frozen=True)
+class BrokenInclude:
+    """One `include`/`literalinclude` directive whose target does not exist."""
+
+    doc: Path
+    line: int
+    directive: str
+    target: str
+    resolved: Path
+
+    def __str__(self) -> str:
+        return (
+            f"{self.doc}:{self.line}: .. {self.directive}:: {self.target} "
+            f"-> missing {self.resolved}"
+        )
+
+
+@dataclass(frozen=True)
+class DocsScanReport:
+    """One `scan_docs` result: the root scanned, the TOTAL number of
+    `include`/`literalinclude` directives found (regardless of whether they
+    resolved), and the broken subset.
+
+    `n_directives` closes a vacuity trap: a scan pointed at an empty or
+    mis-rooted `docs_root` reports `broken == []` vacuously -- nothing was
+    found to break. A caller must assert `n_directives >= 1` alongside
+    `broken == []`, or an empty/wrong root passes silently.
+    """
+
+    docs_root: Path
+    n_directives: int
+    broken: list[BrokenInclude]
+
+
+def resolve_target(target: str, doc_path: Path, docs_root: Path) -> Path:
+    """Resolve an `include`/`literalinclude` target using Sphinx's own rule.
+
+    ``target`` starting with ``/`` is rooted at ``docs_root`` (the directory
+    ``conf.py`` lives in), never the filesystem root. Otherwise it is
+    resolved relative to ``doc_path``'s own directory (the document that
+    names it), matching both docutils' `include` directive and Sphinx's
+    `literalinclude` extension of it.
+    """
+    if target.startswith("/"):
+        return (docs_root / target[1:]).resolve()
+    return (doc_path.parent / target).resolve()
+
+
+def _iter_directives(text: str):
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        m = _RST_DIRECTIVE.match(line)
+        if m is None:
+            m = _MYST_DIRECTIVE.match(line)
+        if m is not None:
+            yield lineno, m.group(1), m.group(2)
+
+
+def scan_docs(docs_root) -> DocsScanReport:
+    """Scan every ``.rst``/``.md`` file under ``docs_root`` (excluding
+    ``_build/``) for `include`/`literalinclude` directives, resolving each
+    with :func:`resolve_target`. One filesystem walk produces both the total
+    directive count and the broken subset (see :class:`DocsScanReport`).
+    """
+    docs_root = Path(docs_root).resolve()
+    n_directives = 0
+    broken: list[BrokenInclude] = []
+    for suffix in SOURCE_SUFFIXES:
+        for doc_path in sorted(docs_root.rglob(f"*{suffix}")):
+            if "_build" in doc_path.relative_to(docs_root).parts:
+                continue
+            text = doc_path.read_text(encoding="utf-8")
+            for lineno, directive, target in _iter_directives(text):
+                n_directives += 1
+                resolved = resolve_target(target, doc_path, docs_root)
+                if not resolved.is_file():
+                    broken.append(
+                        BrokenInclude(doc_path, lineno, directive, target, resolved)
+                    )
+    return DocsScanReport(docs_root, n_directives, broken)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point: print the directive count and every broken include
+    found under each docs root given."""
+    argv = sys.argv[1:] if argv is None else argv
+    if not argv:
+        print(
+            "usage: python -m raptor.conformance.doc_includes <docs_root> "
+            "[<docs_root> ...]",
+            file=sys.stderr,
+        )
+        return 2
+    red = 0
+    for root in argv:
+        report = scan_docs(Path(root))
+        print(f"{root}: {report.n_directives} directive(s) scanned", file=sys.stderr)
+        for broken in report.broken:
+            red = 1
+            print(broken)
+    return red
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

raptor/conformance/interop.py

@@ -0,0 +1,393 @@
+# Copyright 2026 Alessandro Masat
+# SPDX-License-Identifier: Apache-2.0
+
+"""The interop certification declaration and reusable matrix-hygiene scanners.
+
+raptor is the framework-free contract owner: this module names every
+framework the family will ever bridge to (:data:`UNIVERSE`), which subset is
+certified today (:data:`CERTIFIED`) vs. declared-but-not-yet-built
+(:data:`ROADMAP`), and the row-level ``ROWS`` catalogue, declared here in
+full ahead of the packages that write the matrix tests — so that
+:func:`assert_rows_complete` has a real gap to catch instead of declared and
+collected always landing together. Framework objects NEVER enter raptor —
+pointers and callables are passed in duck-typed; this module itself imports
+no framework, ever (``find_spec`` never imports).
+
+Pure-Python, numpy-free by design — raptor has zero hard dependencies.
+"""
+
+from __future__ import annotations
+
+import ast
+import importlib.util
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+#: every framework the family will ever bridge to, day-0 and roadmap together.
+UNIVERSE = ("numpy", "cupy", "torch", "warp", "jax", "tensorflow")
+
+#: frameworks with an executable, certified round-trip today.
+CERTIFIED = ("numpy", "cupy", "torch", "warp")
+
+#: frameworks declared absent-by-design — no row certifies them yet.
+ROADMAP = ("jax", "tensorflow")
+
+#: the vocabulary a :class:`RowDecl` may declare for how a row moves data.
+#: ``ALIAS`` — the crossing shares the same underlying buffer, no copy (e.g.
+#: DLPack zero-copy into another framework's tensor).
+#: ``COPY`` — the crossing makes an independent copy of the data.
+#: ``STREAM`` — the crossing's ordering relative to other work on the same
+#: stream/queue (not whether data is shared or copied).
+#: ``ENV`` — a precondition on the execution environment/state that gates
+#: whether a crossing is legal (e.g. CUDA graph capture mode, device
+#: placement, a layout self-check) — certifying a loud refusal under the
+#: wrong state as much as acceptance under the right one.
+#: ``INVARIANCE`` — the same plugin body produces equivalent results under
+#: different execution structures (bit-exact for some structures, within a
+#: tolerance band for others) — distinct from ALIAS/COPY (which certify a
+#: framework crossing's pointer semantics) and from STREAM (ordering).
+ROW_KINDS = frozenset({"ALIAS", "COPY", "STREAM", "ENV", "INVARIANCE"})
+
+
+@dataclass(frozen=True)
+class RowDecl:
+    """One declared interop-matrix row.
+
+    ``framework`` must be a member of :data:`CERTIFIED`, OR ``None`` for a row
+    that bridges to no array framework at all — an execution-structure
+    invariant internal to eagle rather than a numpy/cupy/torch crossing.
+    Every prior row, even ``CP-CAPTURE-REJECT``/``T-DEVICE-FAILLOUD``, still
+    names the framework whose crossing it guards; widening ``framework`` to
+    ``Optional[str]`` — rather than inventing a sixth pseudo-framework entry
+    in :data:`CERTIFIED`/:data:`UNIVERSE` — keeps that vocabulary honestly
+    scoped to actual array frameworks. ``owner_repo`` is the repo whose test
+    suite carries the executable assertion, so the matrix rows live with the
+    seam they certify; ``kind`` is one of :data:`ROW_KINDS`.
+    """
+
+    framework: str | None
+    owner_repo: str
+    kind: str
+
+    def __post_init__(self) -> None:
+        if self.kind not in ROW_KINDS:
+            raise ValueError(
+                f"RowDecl.kind={self.kind!r} not in {sorted(ROW_KINDS)}"
+            )
+
+
+#: row_id -> RowDecl — the full row catalogue, declared here ahead of the
+#: packages that write the tests. This is deliberate: if declaring and
+#: collecting happened in the same later package, declared and collected
+#: would always agree by construction and :func:`assert_rows_complete` could
+#: never bite. Every row named elsewhere in the family exists below under its
+#: catalogue ID.
+ROWS: dict[str, RowDecl] = {
+    # numpy (host) rows.
+    # cupy — kernel-level rows and adapter/pipeline rows, split by owner.
+    # CP-STREAM-ORDER is a named cross-reference to STREAM-CUPY-PRODUCER-ORDER
+    # below, not a second row.
+    "CP-CAPTURE-REJECT": RowDecl("cupy", "eagle", "ENV"),
+    # torch — adapter+stream rows, kernel-level rows, and bridge+backend
+    # rows, split by owner.
+    "T-IN-CUDA-ALIAS": RowDecl("torch", "eagle", "ALIAS"),
+    "T-OUT-CUDA-ALIAS": RowDecl("torch", "eagle", "ALIAS"),
+    "T-IN-CPU-COPY": RowDecl("torch", "eagle", "COPY"),
+    # A row separate from T-IN-CPU-COPY immediately above: that row stays
+    # owner=eagle and keeps certifying eagle's own adapter crossing. This one
+    # certifies a different seam: a native host provider round-trips a
+    # conforming (float64, C-contiguous) torch CPU tensor by pointer-alias —
+    # no upload, no eagle, no cupy. The declaration here is authoritative, an
+    # explicit re-declaration rather than a quiet one.
+    # Note eagle's adapter ALSO copies float32 (``eagle/python/eagle/interop.py``);
+    # this row certifies the kernel-level crossing, per the grouping above.
+    "T-BRIDGE-COPY": RowDecl("torch", "learning_runtime", "COPY"),
+    "T-BACKEND-CPU-IN-ALIAS": RowDecl("torch", "learning_runtime", "ALIAS"),
+    # Renamed from "T-BACKEND-CUDA": kind=ALIAS is true for the INPUT crossing
+    # only — the learning runtime's bridge copies unconditionally on export
+    # (any live replay buffer is copied off), so no backend row can be an
+    # alias in the OUT direction — that copy is itself certified by
+    # T-BRIDGE-COPY. The unqualified name would have published as "the CUDA
+    # backend aliases", which is false for outputs; the ID now names its
+    # direction, matching its CPU sibling.
+    "T-BACKEND-CUDA-IN-ALIAS": RowDecl("torch", "learning_runtime", "ALIAS"),
+    "T-DEVICE-FAILLOUD": RowDecl("torch", "learning_runtime", "ENV"),
+    # stream rows — owner eagle, GPU-serial.
+    "STREAM-TORCH-PRODUCER-ORDER": RowDecl("torch", "eagle", "STREAM"),
+    "STREAM-CUPY-PRODUCER-ORDER": RowDecl("cupy", "eagle", "STREAM"),
+    "STREAM-TORCH-CONSUMER-ORDER": RowDecl("torch", "eagle", "STREAM"),
+    "STREAM-IDENTITY": RowDecl("torch", "eagle", "STREAM"),
+    # warp — NVIDIA Warp crosses through eagle's generic zero-copy buffer
+    # layer (eagle.interop.import_buffer), not a dedicated Adapter: any
+    # __dlpack__ + __dlpack_device__ producer already routes through
+    # eagle.interop._DlpackAdapter, so warp needed no new adapter code, only
+    # these rows. Warp speaks legacy (pre-1.0) DLPack, so its access flag is
+    # always "unknown" — that is part of WP-IN-CUDA-ALIAS, not a separate
+    # row (same bundling convention T-IN-CUDA-ALIAS already uses for its own
+    # three legs). It joins the other STREAM-* rows.
+    "WP-IN-CUDA-ALIAS": RowDecl("warp", "eagle", "ALIAS"),
+    "WP-OUT-CUDA-ALIAS": RowDecl("warp", "eagle", "ALIAS"),
+    "STREAM-WARP-PRODUCER-ORDER": RowDecl("warp", "eagle", "STREAM"),
+    # execution rows: the closed RowDecl framework/kind sets extended (above)
+    # so these four can be declared here, ahead of their eagle-owned consumer
+    # implementation — the same declare-before-build convention every other
+    # eagle-owned row above already uses (e.g. CP-CAPTURE-REJECT): raptor's
+    # own suite never calls ``assert_rows_complete("eagle")``, so a
+    # declared-but-uncollected eagle row is not a gap this repo's gate can
+    # see — that completeness gate is eagle's own, in its own suite. Row ids
+    # are given in eagle's own snake_case naming, not this file's
+    # UPPER-HYPHEN convention — kept as given rather than renamed to fit.
+    "execution_partition_identity": RowDecl(None, "eagle", "INVARIANCE"),
+    "execution_host_device_twin": RowDecl(None, "eagle", "INVARIANCE"),
+    "execution_illegal_placement_refused": RowDecl(None, "eagle", "ENV"),
+    "execution_layout_selfcheck_refused": RowDecl(None, "eagle", "ENV"),
+    # HAWK rows: rows that exist only because HAWK exists, declared
+    # owner_repo="hawk" — same declare-before-build convention as the
+    # execution_* rows above, ahead of HAWK's own consumer implementation.
+    # The numpy/cupy/torch crossing rows HAWK will own are declared when its
+    # consumer implementation lands, not here. framework=None for all
+    # five: none bridges to an array framework (see RowDecl's docstring);
+    # every check is deferred to its own consumer implementation. Row ids
+    # cite the row they carry in hawk's own documentation, which gives no
+    # snake_case name for them (contrast the execution_* rows' eagle-given
+    # names above) — this file's own UPPER-HYPHEN convention applies,
+    # prefixed HAWK- for the family.
+    "HAWK-DIFF-POSITIVE-ROUNDTRIP": RowDecl(None, "hawk", "INVARIANCE"),
+    "HAWK-EXEC-DEPLOY-LOADABLE": RowDecl(None, "hawk", "ENV"),
+    "HAWK-EXEC-REFERENCE-HOST": RowDecl(None, "hawk", "INVARIANCE"),
+    "HAWK-EXEC-REFERENCE-RANKPARTITION": RowDecl(None, "hawk", "INVARIANCE"),
+}
+
+
+def certified_framework(fw: str) -> None:
+    """Assert ``fw`` (a name in :data:`CERTIFIED`) is importable here.
+
+    Never skips: an absent certified framework is a hard failure of the gate
+    environment, not a reason to skip the row (a pytest SKIP is RC=0 and
+    certifies nothing). ``pytest`` is imported here, not at module level, so
+    the rest of :mod:`raptor.conformance` stays importable without it.
+    """
+    import pytest
+
+    if importlib.util.find_spec(fw) is None:
+        pytest.fail("certified framework absent from the gate environment")
+
+
+def roadmap_framework(fw: str) -> None:
+    """Assert ``fw`` (a name in :data:`ROADMAP`) is ABSENT here.
+
+    Certified-absent and roadmap-present are BOTH failures — the declaration
+    and reality must agree in both directions, or the matrix certifies
+    nothing.
+    """
+    assert importlib.util.find_spec(fw) is None, (
+        "declared ROADMAP (absent-by-declaration) but INSTALLED — certify it "
+        "or remove it from the env"
+    )
+
+
+#: row IDs actually collected this pytest session (populated by
+#: :func:`register_row` at collection time).
+_COLLECTED_ROWS: set[str] = set()
+
+
+def register_row(row_id: str):
+    """Decorator marking a matrix test as covering declared row ``row_id``.
+
+    Raises :class:`KeyError` immediately if ``row_id`` is not in :data:`ROWS`
+    (a typo'd row id should fail loud at collection, not silently pass
+    :func:`assert_rows_complete`).
+    """
+    if row_id not in ROWS:
+        raise KeyError(f"register_row: {row_id!r} is not a declared row in ROWS")
+
+    def _decorate(fn):
+        _COLLECTED_ROWS.add(row_id)
+        return fn
+
+    return _decorate
+
+
+def assert_rows_complete(owner_repo: str) -> None:
+    """Assert every :data:`ROWS` entry owned by ``owner_repo`` was collected.
+
+    Declared vs. collected row IDs; any declared row with no collected test
+    is RED.
+    """
+    declared = {rid for rid, decl in ROWS.items() if decl.owner_repo == owner_repo}
+    missing = declared - _COLLECTED_ROWS
+    assert not missing, (
+        f"rows declared for {owner_repo!r} but never collected: {sorted(missing)}"
+    )
+
+
+#: token names that must never appear in a matrix module — skip machinery is
+#: banned from matrix modules, mechanically.
+_SKIP_TOKEN_ATTRS = frozenset({"skip", "skipif", "importorskip"})
+
+
+def assert_no_skip_tokens(*module_paths) -> None:
+    """Assert zero ``pytest.skip``/``skipif``/``importorskip`` tokens.
+
+    AST-based over each path in ``module_paths`` (a matrix module file):
+    catches direct calls (``pytest.skip(...)``, ``pytest.importorskip(...)``)
+    and decorator uses (``@pytest.mark.skip``/``@pytest.mark.skipif``) alike,
+    since decorators are ordinary ``Attribute``/``Call`` nodes in the AST.
+    Absence of a certified framework must be a FAILURE by construction, never
+    a silent skip.
+    """
+    hits: list[str] = []
+    for raw_path in module_paths:
+        path = Path(raw_path)
+        tree = ast.parse(path.read_text(), filename=str(path))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Attribute) and node.attr in _SKIP_TOKEN_ATTRS:
+                hits.append(f"{path}:{node.lineno}: pytest.{node.attr}")
+    assert not hits, "banned skip tokens found in matrix modules:\n" + "\n".join(hits)
+
+
+#: markers ANY conftest in the family wires into ``pytest_collection_modifyitems``'s
+#: skip-on-absence machinery — the union across every family member's own
+#: availability markers (verified against each repo's own
+#: ``conftest.py``/``pyproject.toml`` directly, not assumed). Checking for a
+#: marker a given repo's conftest doesn't define is always a zero-hit, never
+#: a false negative — the union is safe to use everywhere.
+_AVAILABILITY_MARKERS = frozenset({"gpu", "torch", "torch_gpu", "jax_gpu", "tf_gpu"})
+
+
+def _calls_register_row(tree: ast.AST) -> bool:
+    return any(
+        isinstance(node, ast.Name) and node.id == "register_row"
+        for node in ast.walk(tree)
+    )
+
+
+def discover_matrix_modules(test_dir) -> list[Path]:
+    """Every ``.py`` file under ``test_dir`` that calls :func:`register_row`
+    (AST-detected, not textually grepped) — the matrix modules a repo actually
+    ships, DISCOVERED rather than hand-passed.
+
+    A hand-passed module list is exactly how a matrix row can go unscanned by
+    accident — a row registered from a file its scanner's caller forgot to
+    name still counts as "collected" (``register_row`` fires at DECORATION
+    time, independent of whether pytest later skips the test), so
+    completeness and skip-freedom silently diverge. Discovery closes that gap
+    by construction: there is no second list to forget to update.
+    """
+    return sorted(p for p in Path(test_dir).rglob("*.py") if _calls_register_row(
+        ast.parse(p.read_text(), filename=str(p))
+    ))
+
+
+def _registered_function_defs(tree: ast.AST):
+    """Yield ``(row_id, FunctionDef)`` for every function decorated
+    ``@register_row("...")`` in ``tree`` — the exact, narrow locus a matrix
+    row's own hygiene must hold at (not the whole file: a file mixing matrix
+    rows with ordinary, legitimately-marker-gated tests must not have its
+    unrelated tests' markers flagged)."""
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for dec in node.decorator_list:
+            if (
+                isinstance(dec, ast.Call)
+                and isinstance(dec.func, ast.Name)
+                and dec.func.id == "register_row"
+            ):
+                row_id = (
+                    dec.args[0].value
+                    if dec.args and isinstance(dec.args[0], ast.Constant)
+                    else "<unresolved>"
+                )
+                yield row_id, node
+                break
+
+
+def _is_marker_decorator(dec: ast.expr, banned_markers: frozenset[str]) -> str | None:
+    """Return the banned marker name ``dec`` applies (``@pytest.mark.<name>``,
+    bare or called), or ``None``."""
+    target = dec.func if isinstance(dec, ast.Call) else dec
+    if (
+        isinstance(target, ast.Attribute)
+        and target.attr in banned_markers
+        and isinstance(target.value, ast.Attribute)
+        and target.value.attr == "mark"
+    ):
+        return target.attr
+    return None
+
+
+def assert_no_skip_machinery(
+    test_dir, *, banned_markers: frozenset[str] = _AVAILABILITY_MARKERS
+) -> None:
+    """Assert every DISCOVERED matrix row (any ``@register_row``-decorated
+    function in any ``.py`` under ``test_dir``) is free of skip machinery:
+    zero ``pytest.skip``/``skipif``/``importorskip`` tokens in its body, AND
+    zero conftest availability-marker decorators (``banned_markers``, default
+    the cross-repo union) on the registered function itself.
+
+    Scoped to the REGISTERED function, not the whole file (see
+    :func:`_registered_function_defs`) — a file may legitimately mix matrix
+    rows with ordinary marker-gated tests; only the declared rows must be
+    unable to skip. Discovery (:func:`discover_matrix_modules`) means there is
+    no hand-passed module list to fall out of sync with reality: that is
+    exactly how a row once skipped silently while
+    :func:`assert_rows_complete` still passed — ``register_row`` collects at
+    decoration time, not at execution.
+    """
+    modules = discover_matrix_modules(test_dir)
+    assert modules, f"no register_row-bearing modules found under {test_dir}"
+    skip_hits: list[str] = []
+    marker_hits: list[str] = []
+    for path in modules:
+        tree = ast.parse(path.read_text(), filename=str(path))
+        for row_id, fn in _registered_function_defs(tree):
+            for dec in fn.decorator_list:
+                marker = _is_marker_decorator(dec, banned_markers)
+                if marker is not None:
+                    marker_hits.append(
+                        f"{path}:{fn.lineno}: row {row_id!r} carries "
+                        f"@pytest.mark.{marker} (skip-capable)"
+                    )
+            for sub in ast.walk(fn):
+                if isinstance(sub, ast.Attribute) and sub.attr in _SKIP_TOKEN_ATTRS:
+                    skip_hits.append(
+                        f"{path}:{sub.lineno}: row {row_id!r} uses pytest.{sub.attr}"
+                    )
+    assert not skip_hits, "banned skip tokens found on registered rows:\n" + "\n".join(
+        skip_hits
+    )
+    assert not marker_hits, (
+        "banned availability-marker decorators found on registered rows:\n"
+        + "\n".join(marker_hits)
+    )
+
+
+def assert_doc_rows_match(
+    doc_path,
+    rows: dict[str, RowDecl],
+    *,
+    row_id_pattern: str = r"`([A-Za-z][A-Za-z0-9_.:/-]*)`",
+) -> None:
+    """Assert the doc's row IDs and ``rows``'s keys are the same set.
+
+    Mirrors ``test_roles_vocab.py``'s technique (``eagle/python/tests/
+    test_roles_vocab.py``): the document is read as raw TEXT and scanned with
+    a regex — no markdown parser, no import of anything the doc describes —
+    then compared by set equality against the declaration, in both
+    directions. ``row_id_pattern`` defaults to backtick-quoted identifiers
+    (the row-id convention a table of ``` `row_id` ``` cells would use);
+    override it if the shipped document's convention differs.
+    """
+    text = Path(doc_path).read_text()
+    doc_ids = set(re.findall(row_id_pattern, text))
+    declared_ids = set(rows)
+    missing_from_doc = declared_ids - doc_ids
+    extra_in_doc = doc_ids - declared_ids
+    assert not missing_from_doc, (
+        f"rows declared but missing from {doc_path}: {sorted(missing_from_doc)}"
+    )
+    assert not extra_in_doc, (
+        f"{doc_path} references undeclared rows: {sorted(extra_in_doc)}"
+    )

raptor/protocols/__init__.py

@@ -0,0 +1,24 @@
+# Copyright 2026 Alessandro Masat
+# SPDX-License-Identifier: Apache-2.0
+
+"""raptor.protocols — the family's typing.Protocols.
+
+Pure structural contracts; zero hard deps; zero imports of any downstream
+package.
+"""
+
+from __future__ import annotations
+
+from .backend import CAPABILITIES, Backend, CapabilityError, Executable
+from .launcher import KernelLauncher, Marshal
+from .provider import ManifestProvider
+
+__all__ = [
+    "CAPABILITIES",
+    "Backend",
+    "CapabilityError",
+    "Executable",
+    "KernelLauncher",
+    "ManifestProvider",
+    "Marshal",
+]