phase-loop-runtime 0.2.0__py3-none-any.whl

phase_loop_runtime/advisor_board/resolver.py

@@ -0,0 +1,253 @@
+"""Board resolution — name -> seats, settable default, ad-hoc seats (ABDRESOLVE lane 1).
+
+Turns a board *reference* into a concrete ``Board`` of seats:
+
+* a **name** (``"default"``, ``"code-review"``, ...) -> the named board from the
+  catalog;
+* **nothing** -> the settable *default* board (bare ``advisor-board``);
+* an **ad-hoc** ``--seats model:effort[:harness]`` spec -> a synthesized board.
+
+Coded against the frozen registry/matrix interface (``registries``); the harness
+lane for a bare ``model:effort`` seat is resolved via
+``CompatibilityMatrix.default_lane``. Until ABDREG ships the config loader +
+presets, the catalog defaults to a **stand-in** built from the shared canonical
+fixtures (``STANDIN_BOARDS``) so ABDRESOLVE resolves ``default`` and
+``code-review`` without depending on ABDREG's live output (integration at
+ABDVERIFY). A caller (or ABDREG) injects the real catalog + matrix.
+
+``advisor-panel`` remains a working alias of the default board
+(``BOARD_ALIASES``) so the historical name keeps resolving after the
+advisor-panel -> advisor-board rename.
+"""
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+
+from .fixtures import DEFAULT_BOARD
+from .registries import CompatibilityMatrix
+from .schema import EFFORT_LEVELS, Board, Seat
+
+
+class SeatSpecError(ValueError):
+    """A ``--seats model:effort[:harness]`` token is malformed."""
+
+
+class BoardResolutionError(KeyError):
+    """A board reference names no board in the catalog (and is not an alias)."""
+
+    def __init__(self, name: str, available: Sequence[str]) -> None:
+        self.name = name
+        self.available = tuple(available)
+        joined = ", ".join(sorted(self.available)) or "(none)"
+        super().__init__(
+            f"unknown board {name!r}; available boards: {joined} "
+            "(ad-hoc seats: --seats model:effort[:harness])"
+        )
+
+    def __str__(self) -> str:  # KeyError repr wraps the message in quotes otherwise
+        return self.args[0]
+
+
+# The historical panel name resolves to the default premerge-review board, so
+# existing agent instructions that say "advisor-panel" keep working after the
+# advisor-panel -> advisor-board rename.
+BOARD_ALIASES: dict[str, str] = {
+    "advisor-panel": "default",
+    "panel": "default",
+}
+
+
+# --- ad-hoc seat parsing ----------------------------------------------------
+
+
+def parse_seat_spec(spec: str, *, matrix: CompatibilityMatrix | None = None) -> Seat:
+    """Parse one ``model:effort[:harness]`` token into a ``Seat``.
+
+    ``model``   required, the primary key.
+    ``effort``  required, a canonical level in ``EFFORT_LEVELS``.
+    ``harness`` optional; when omitted the lane is resolved via
+                ``matrix.default_lane(model)`` (frozen interface). With no matrix
+                the seat is left lane-unresolved (``harness=None``) for the
+                validation/backing phase to fill.
+    """
+    raw = (spec or "").strip()
+    if not raw:
+        raise SeatSpecError("empty seat spec; expected model:effort[:harness]")
+    parts = raw.split(":")
+    if len(parts) < 2 or len(parts) > 3:
+        raise SeatSpecError(
+            f"seat spec {spec!r} must be model:effort[:harness] (1 or 2 colons)"
+        )
+    model = parts[0].strip()
+    effort = parts[1].strip().lower()
+    harness = parts[2].strip() if len(parts) == 3 and parts[2].strip() else None
+    if not model:
+        raise SeatSpecError(f"seat spec {spec!r} has an empty model")
+    if effort not in EFFORT_LEVELS:
+        raise SeatSpecError(
+            f"seat spec {spec!r} effort {effort!r} not in {EFFORT_LEVELS}"
+        )
+    if harness is None and matrix is not None:
+        harness = matrix.default_lane(model)
+    return Seat(model=model, effort=effort, harness=harness)
+
+
+def parse_seats(
+    specs: str | Iterable[str], *, matrix: CompatibilityMatrix | None = None
+) -> tuple[Seat, ...]:
+    """Parse a comma-separated string OR an iterable of ``model:effort[:harness]``
+    tokens into an ordered tuple of seats (order preserved for result re-keying)."""
+    if isinstance(specs, str):
+        tokens = [tok for tok in (t.strip() for t in specs.split(",")) if tok]
+    else:
+        tokens = [str(tok).strip() for tok in specs if str(tok).strip()]
+    if not tokens:
+        raise SeatSpecError("no seats parsed; expected model:effort[:harness], ...")
+    return tuple(parse_seat_spec(tok, matrix=matrix) for tok in tokens)
+
+
+# --- stand-in board catalog (until ABDREG's config loader + presets) --------
+
+# A stand-in ``code-review`` preset mirroring ``fixtures/advisor-boards.example.toml``
+# so ``advisor-board --board code-review`` resolved in ABDRESOLVE before the config
+# loader landed. SUPERSEDED by ``presets.PRESETS`` / ``config.load_boards`` (which
+# ship the seven real presets — the live ``code-review`` is now three frontier
+# adversarial seats on Fable, not this two-seat mirror); kept only as the ABDRESOLVE
+# stand-in fixture, off every live path.
+_STANDIN_CODE_REVIEW = Board(
+    name="code-review",
+    purpose="code-review",
+    seats=(
+        Seat(model="gpt-5.5", effort="max", harness="codex"),
+        Seat(model="claude-sonnet-5", effort="max", harness="claude", lens="adversarial"),
+    ),
+)
+
+STANDIN_BOARDS: dict[str, Board] = {
+    DEFAULT_BOARD.name: DEFAULT_BOARD,
+    _STANDIN_CODE_REVIEW.name: _STANDIN_CODE_REVIEW,
+}
+
+
+# --- resolver ---------------------------------------------------------------
+
+
+class BoardResolver:
+    """Resolve a board reference to seats against an (injectable) catalog + matrix.
+
+    ``boards``          the named-board catalog; defaults to ``STANDIN_BOARDS``
+                        (ABDREG injects the real config-loaded presets).
+    ``default_board``   the board a bare ``advisor-board`` resolves to (settable
+                        via ``set_default``).
+    ``matrix``          frozen ``CompatibilityMatrix`` used to resolve a bare
+                        ad-hoc seat's default lane; optional.
+    ``aliases``         board-name aliases (``advisor-panel`` -> ``default`` by
+                        default) so the historical name keeps resolving.
+    """
+
+    def __init__(
+        self,
+        boards: Mapping[str, Board] | None = None,
+        *,
+        default_board: str = "default",
+        matrix: CompatibilityMatrix | None = None,
+        aliases: Mapping[str, str] | None = None,
+    ) -> None:
+        self._boards: dict[str, Board] = dict(boards) if boards is not None else dict(STANDIN_BOARDS)
+        self._aliases: dict[str, str] = dict(aliases) if aliases is not None else dict(BOARD_ALIASES)
+        self._matrix = matrix
+        self.set_default(default_board)
+
+    @property
+    def default_board(self) -> str:
+        return self._default_board
+
+    def set_default(self, name: str) -> None:
+        """Set the board a bare ``advisor-board`` resolves to. Fails fast if the
+        name (after alias) is not in the catalog."""
+        resolved = self._resolve_name(name)
+        if resolved not in self._boards:
+            raise BoardResolutionError(name, self.available())
+        self._default_board = resolved
+
+    def available(self) -> tuple[str, ...]:
+        """Every resolvable board name (catalog names + aliases)."""
+        return tuple(self._boards) + tuple(self._aliases)
+
+    def _resolve_name(self, name: str) -> str:
+        key = (name or "").strip()
+        return self._aliases.get(key, key)
+
+    def resolve(
+        self,
+        name: str | None = None,
+        *,
+        seats: str | Iterable[str] | None = None,
+    ) -> Board:
+        """Resolve to a concrete ``Board``.
+
+        * ``seats`` given  -> a synthesized ad-hoc board (``--seats`` path);
+        * ``name`` is None/empty -> the settable default board;
+        * else            -> the named board (alias-aware), or ``BoardResolutionError``.
+        """
+        if seats is not None:
+            parsed = parse_seats(seats, matrix=self._matrix)
+            return Board(name="ad-hoc", purpose="ad-hoc", seats=parsed)
+        if name is None or not str(name).strip():
+            return self._boards[self._default_board]
+        resolved = self._resolve_name(name)
+        try:
+            return self._boards[resolved]
+        except KeyError:
+            raise BoardResolutionError(name, self.available()) from None
+
+
+def resolve_board(
+    name: str | None = None,
+    *,
+    seats: str | Iterable[str] | None = None,
+    boards: Mapping[str, Board] | None = None,
+    matrix: CompatibilityMatrix | None = None,
+) -> Board:
+    """One-shot convenience over ``BoardResolver`` (stand-in catalog by default)."""
+    return BoardResolver(boards, matrix=matrix).resolve(name, seats=seats)
+
+
+# --- leg -> seat result re-keying (expressibility for same-vendor seats) -----
+
+
+def seat_result_key(seat: Seat) -> str:
+    """The stable per-seat label a result is keyed by (``Seat.seat_key``)."""
+    return seat.seat_key
+
+
+def key_results_by_seat(
+    seats: Sequence[Seat], results: Sequence["object"]
+) -> tuple[tuple[Seat, object], ...]:
+    """Pair a board's seats with its panel-leg results **by position**.
+
+    The v4 ``PanelLegResult.leg`` keys results by vendor, so a board with two
+    same-vendor seats (e.g. two openai seats on ``codex`` and ``opencode``) could
+    not be told apart. Pairing by position, with ``seat.seat_key`` as the label,
+    makes two same-vendor seats distinctly expressible. ABDHOME wires the actual
+    per-seat spawn; ABDRESOLVE freezes the position<->seat_key identity.
+    """
+    if len(seats) != len(results):
+        raise ValueError(
+            f"seat/result count mismatch: {len(seats)} seats vs {len(results)} results"
+        )
+    return tuple((seat, result) for seat, result in zip(seats, results))
+
+
+__all__ = [
+    "SeatSpecError",
+    "BoardResolutionError",
+    "BOARD_ALIASES",
+    "STANDIN_BOARDS",
+    "BoardResolver",
+    "resolve_board",
+    "parse_seat_spec",
+    "parse_seats",
+    "seat_result_key",
+    "key_results_by_seat",
+]

phase_loop_runtime/advisor_board/schema.py

@@ -0,0 +1,269 @@
+"""Advisor Board — frozen seat/board schema + vendor projection (IF-0-ABDFREEZE-1, -4).
+
+This module is the **interface freeze** for the model-first Advisor Board. It is
+additive and behavior-neutral: it introduces no runtime path and does not touch
+`panel_invoker`. Downstream phases (ABDREG / ABDRESOLVE / ABDHOME) code against
+the typed structures frozen here so the fan-out integrates without a big-bang.
+
+The seat model inverts the v4 panel: a **seat is a cognition** — `{model, effort,
+harness?, lens?, auth?}` — where the harness is a defaulted-but-overridable
+execution *lane*, not the primary key. A **board** is a named, purpose-tagged,
+open-ended list of seats.
+
+Two freezes here are load-bearing for back-compat and must reproduce today's
+behavior exactly (proven by ``tests/test_advisor_board_schema.py`` and
+``tests/test_advisor_board_backcompat.py``):
+
+* **Seat -> vendor-family projection** (``vendor_family`` / ``seat_vendor_family``)
+  must be byte-consistent with the existing governed-gate logic
+  (`governed_review.author_vendor_for_model` :60-75 and
+  `governed_review._EXECUTOR_VENDOR` :47-53). The governed reviewer != author
+  disjointness keys on vendor identity; model-first breaks the ``leg == vendor``
+  assumption, so ABDHOME rewires `governed_review` / `governed_premerge` to
+  consume *this* canonical projection. If the projection drifts, custom boards
+  silently corrupt reviewer-disjointness.
+
+* **Host-leg identity** — which seat is the native in-process host leg when the
+  board runs *inside* a harness (e.g. Claude Code -> native ``Agent``) versus the
+  homebrew subprocess legs. Today the standalone Python runner spawns every leg
+  as a subprocess (no host leg), so the additive ``Seat.host_leg`` marker
+  defaults ``False`` and ``identify_host_leg`` returns ``None`` for the default
+  board — today's behavior, untouched.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+# --- canonical vocabularies -------------------------------------------------
+
+# Model-first, harness-agnostic effort ladder. Each harness translates a canonical
+# level to its own invocation form (see ``harness_mapping``). Ordered low -> high.
+EFFORT_LEVELS: tuple[str, ...] = ("low", "medium", "high", "max")
+
+# Credential lane for a seat. Subscription is the default lane (Assumptions §);
+# ``api_key`` is only reachable behind an explicit board-level opt-in
+# (``Board.allow_api_key_fallback``) and injects ONLY the seat vendor's key.
+AUTH_SUBSCRIPTION = "subscription"
+AUTH_API_KEY = "api_key"
+AUTH_LANES: tuple[str, ...] = (AUTH_SUBSCRIPTION, AUTH_API_KEY)
+
+# Provider transport backing a seat. ``homebrew`` keeps the built-3 + the native
+# host leg (ABDHOME); ``omnigent`` supplies breadth via omniagent-plus -> Omnigent
+# (ABDOMNI). Default homebrew keeps the default board all-homebrew.
+BACKING_HOMEBREW = "homebrew"
+BACKING_OMNIGENT = "omnigent"
+PROVIDER_BACKINGS: tuple[str, ...] = (BACKING_HOMEBREW, BACKING_OMNIGENT)
+
+# Board config format + location (IF-0-ABDFREEZE-1). Honors ``XDG_CONFIG_HOME``.
+CONFIG_RELATIVE_PATH = "agent-harness/advisor-boards.toml"
+
+
+def board_config_path(env: "os._Environ[str] | dict[str, str] | None" = None) -> Path:
+    """Frozen config location: ``$XDG_CONFIG_HOME/agent-harness/advisor-boards.toml``
+    (default ``~/.config/agent-harness/advisor-boards.toml``). The loader lands in
+    ABDREG; this only freezes *where* it reads."""
+    src = os.environ if env is None else env
+    base = src.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / CONFIG_RELATIVE_PATH
+
+
+# --- vendor-family projection (governed reviewer != author, model-first) -----
+
+# Harness -> vendor family. Mirrors `governed_review._EXECUTOR_VENDOR` (:47-53)
+# EXACTLY so the projection reproduces today's executor->vendor mapping. Two
+# same-vendor seats on different harnesses (gpt-5.5 on ``codex`` and on
+# ``opencode``) MUST project to the same family, which this table encodes.
+_HARNESS_VENDOR: dict[str, str] = {
+    "codex": "codex",
+    "opencode": "codex",  # openai-family models
+    "claude": "claude",
+    "gemini": "gemini",
+    "pi": "pi",
+}
+
+
+def vendor_of_harness(harness: str) -> str:
+    """Harness (execution lane) -> vendor family, with an identity fallback for an
+    unknown harness. Byte-consistent with
+    `governed_review.author_vendor_for_executor`."""
+    h = (harness or "").lower()
+    return _HARNESS_VENDOR.get(h, h)
+
+
+def vendor_of_model(model: str) -> str:
+    """Concrete model id -> vendor family, or ``""`` when the model is inconclusive.
+
+    The matched branches reproduce `governed_review.author_vendor_for_model`
+    (:69-74) EXACTLY. The one intentional difference: this returns ``""`` (rather
+    than the raw model) for an unmatched model, so ``vendor_family`` can then fall
+    back to the harness lane. ``author_vendor_for_model``-equivalence for a bare
+    model is recovered as ``vendor_of_model(m) or m.lower()`` and is asserted in
+    the schema test.
+    """
+    m = (model or "").lower()
+    if not m:
+        return ""
+    if "claude" in m or "opus" in m or "sonnet" in m or "haiku" in m:
+        return "claude"
+    if "gemini" in m or m in {"pro", "flash", "flash-lite", "auto"}:
+        return "gemini"
+    if m.startswith("gpt") or m.startswith("o1") or m.startswith("o3") or m.startswith("openai/"):
+        return "codex"  # the codex panel leg runs the openai-family model
+    return ""
+
+
+def vendor_family(model: str, harness: str | None = None) -> str:
+    """Canonical model-first seat -> vendor-family projection.
+
+    Model wins when conclusive; otherwise the harness lane decides; otherwise the
+    lowercased model is the family (matching the historical bare-model fallback).
+    This is THE canonical projection ABDHOME rewires the governed gates onto — not
+    a parallel copy — so reviewer != author disjointness survives model-first.
+    """
+    fam = vendor_of_model(model)
+    if fam:
+        return fam
+    if harness:
+        return vendor_of_harness(harness)
+    return (model or "").lower()
+
+
+# --- seat + board -----------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Seat:
+    """A single cognition on a board (model-first).
+
+    ``model``     concrete model id (the primary key). Required.
+    ``effort``    canonical effort level (``EFFORT_LEVELS``). Required — the
+                  model-registry default is applied by the resolver (ABDRESOLVE),
+                  not silently here.
+    ``harness``   execution lane; ``None`` -> ``default_lane(model)`` at resolution.
+    ``lens``      optional review persona/lens (advisory framing); no behavior yet.
+    ``auth``      credential lane (``AUTH_LANES``); subscription by default.
+    ``backing``   provider transport (``PROVIDER_BACKINGS``); homebrew by default.
+    ``host_leg``  additive marker: this seat is the native in-process host leg
+                  (not a subprocess). Default ``False`` == today's subprocess leg.
+    """
+
+    model: str
+    effort: str
+    harness: str | None = None
+    lens: str | None = None
+    auth: str = AUTH_SUBSCRIPTION
+    backing: str = BACKING_HOMEBREW
+    host_leg: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.model or not str(self.model).strip():
+            raise ValueError("seat.model is required")
+        if self.effort not in EFFORT_LEVELS:
+            raise ValueError(f"seat.effort {self.effort!r} not in {EFFORT_LEVELS}")
+        if self.auth not in AUTH_LANES:
+            raise ValueError(f"seat.auth {self.auth!r} not in {AUTH_LANES}")
+        if self.backing not in PROVIDER_BACKINGS:
+            raise ValueError(f"seat.backing {self.backing!r} not in {PROVIDER_BACKINGS}")
+
+    @property
+    def vendor_family(self) -> str:
+        """This seat's vendor family (model-first projection)."""
+        return vendor_family(self.model, self.harness)
+
+    @property
+    def seat_key(self) -> str:
+        """Stable per-seat LABEL for result re-keying (ABDRESOLVE re-keys
+        ``PanelLegResult.leg`` -> seat so two same-vendor seats are expressible).
+
+        Incorporates every user-distinguishing field — (harness-lane, model,
+        effort, lens) — so seats that differ only by ``lens`` (a natural
+        brainstorm board: same model, adversarial vs supportive) get distinct
+        keys. This is a LABEL, not a guaranteed-unique id: a board may still hold
+        two byte-identical seats, so ABDRESOLVE MUST key results by **seat
+        position** and use ``seat_key`` only as the human-readable label. Frozen
+        this way so the fan-out builds on a stable, collision-aware contract.
+        """
+        lane = self.harness or f"@{vendor_family(self.model)}"
+        base = f"{lane}:{self.model}:{self.effort}"
+        return f"{base}:{self.lens}" if self.lens else base
+
+
+@dataclass(frozen=True)
+class Board:
+    """A named, purpose-tagged, open-ended list of seats.
+
+    ``allow_api_key_fallback`` defaults ``False`` — no seat may use the api-key
+    lane unless the board explicitly opts in (never-silent-key, IF-0-ABDFREEZE-3).
+    """
+
+    name: str
+    purpose: str
+    seats: tuple[Seat, ...]
+    allow_api_key_fallback: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.name or not str(self.name).strip():
+            raise ValueError("board.name is required")
+        if not isinstance(self.seats, tuple):
+            # keep the board hashable/frozen: seats must be a tuple of Seat
+            raise TypeError("board.seats must be a tuple of Seat")
+        for seat in self.seats:
+            if not isinstance(seat, Seat):
+                raise TypeError(f"board.seats entries must be Seat, got {type(seat)!r}")
+        if not self.allow_api_key_fallback:
+            offenders = [s for s in self.seats if s.auth == AUTH_API_KEY]
+            if offenders:
+                raise ValueError(
+                    "board has api_key seats but allow_api_key_fallback is False "
+                    "(never-silent-key): "
+                    + ", ".join(s.seat_key for s in offenders)
+                )
+
+    def seat_vendor_families(self) -> tuple[str, ...]:
+        return tuple(seat.vendor_family for seat in self.seats)
+
+
+def seat_vendor_family(seat: Seat) -> str:
+    """Free-function form of ``Seat.vendor_family`` (the projection ABDHOME calls
+    when it holds a seat but not the property)."""
+    return vendor_family(seat.model, seat.harness)
+
+
+# --- host-leg identity ------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class HostContext:
+    """The runtime host the board is currently running *inside*.
+
+    ``host_harness`` is the harness whose process is hosting the board (e.g.
+    ``"claude"`` when the board runs inside Claude Code and can reach the native
+    in-process ``Agent`` tool). ``None`` == the standalone Python runner, which
+    spawns every leg as a subprocess — TODAY'S DEFAULT, no host leg.
+    """
+
+    host_harness: str | None = None
+
+
+def identify_host_leg(board: Board, host: HostContext | None = None) -> Seat | None:
+    """Return the seat that IS the native host leg for ``host``, or ``None``.
+
+    A seat is the host leg iff (a) the board runs inside a harness
+    (``host.host_harness`` set), and (b) the seat's resolved lane matches that
+    harness, and (c) the seat is marked ``host_leg`` OR it is the first seat on
+    the hosting harness (auto-identification for a board that predates the
+    marker). For the standalone runner (``host_harness is None``) this returns
+    ``None`` — every leg is a subprocess, exactly as today. The native host leg,
+    once identified, must never be routed through the gateway (ABDHOME invariant).
+    """
+    if host is None or not host.host_harness:
+        return None
+    hosting = host.host_harness.lower()
+    on_host = [s for s in board.seats if (s.harness or "").lower() == hosting]
+    if not on_host:
+        return None
+    explicit = [s for s in on_host if s.host_leg]
+    return explicit[0] if explicit else on_host[0]

phase_loop_runtime/advisor_board/standin.py

@@ -0,0 +1,166 @@
+"""Fixture-backed stand-in registries + matrix (ABDRESOLVE / ABDHOME test support).
+
+ABDREG (Phase 2) populates the *real* six-harness registry, model registry, and
+``(model x harness)`` compatibility matrix behind the frozen Protocols in
+``registries``. Until then, ABDRESOLVE codes against those Protocols using a
+stand-in built **from the shared canonical fixtures** (``fixtures.py``) — the
+ABDFREEZE anti-divergence keystone. Because the stand-in is derived from the same
+``CANONICAL_VALID_PAIRS`` / ``CANONICAL_INVALID_PAIRS`` / ``DEFAULT_SEATS`` that
+ABDREG populates from, the resolver/validation logic verified here integrates with
+ABDREG's real data at ABDVERIFY without a mock-vs-real cliff.
+
+This module is deliberately thin and additive: it introduces no running path and
+is imported only by the resolver's default catalog and by tests. ABDREG replaces
+these with populated implementations; ABDRESOLVE never depends on ABDREG's live
+output (integration is at ABDVERIFY).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .fixtures import (
+    CANONICAL_INVALID_PAIRS,
+    CANONICAL_VALID_PAIRS,
+    DEFAULT_SEATS,
+)
+from .registries import (
+    AuthAvailability,
+    HarnessSpec,
+    MatrixVerdict,
+    ModelSpec,
+)
+from .schema import (
+    AUTH_SUBSCRIPTION,
+    BACKING_HOMEBREW,
+    vendor_family,
+    vendor_of_harness,
+    vendor_of_model,
+)
+
+
+# The default lane a bare ``model`` seat resolves onto, derived from the canonical
+# default seats (the built-3) plus the same-vendor-across-harness valid pairs. This
+# is the stand-in for ``ModelRegistry.default_lane`` / ``CompatibilityMatrix.default_lane``.
+_DEFAULT_LANE: dict[str, str] = {seat.model: seat.harness or "" for seat in DEFAULT_SEATS}
+
+
+def _default_lane_for(model: str) -> str:
+    lane = _DEFAULT_LANE.get(model)
+    if lane:
+        return lane
+    # Fall back to the first canonical valid lane for the model, else the vendor family.
+    for pair_model, pair_harness in CANONICAL_VALID_PAIRS:
+        if pair_model == model:
+            return pair_harness
+    return vendor_family(model)
+
+
+@dataclass(frozen=True)
+class StandinCompatibilityMatrix:
+    """A ``CompatibilityMatrix`` (frozen Protocol) backed by the canonical fixtures.
+
+    ``is_valid`` accepts every ``CANONICAL_VALID_PAIRS`` entry (and any
+    same-vendor-family pairing derivable from them), rejects every
+    ``CANONICAL_INVALID_PAIRS`` entry, and rejects an unknown pairing as a
+    cross-vendor mismatch. The returned ``AuthAvailability`` reports the
+    subscription lane available for a valid pair (the default lane) so a
+    valid-but-unauthed seat is *expressible* distinctly from an invalid pairing.
+    """
+
+    def is_valid(self, model: str, harness: str) -> MatrixVerdict:
+        pair = (model, harness)
+        if pair in CANONICAL_INVALID_PAIRS:
+            return (False, AuthAvailability(detail=f"{model} does not run on the {harness} lane"))
+        if pair in CANONICAL_VALID_PAIRS:
+            return (True, AuthAvailability(subscription=True, detail="subscription"))
+        # Not enumerated: valid iff the model's vendor family matches the harness
+        # lane's family (the same rule the canonical pairs encode) — so gpt-5.5 on
+        # any openai-family lane is valid, gpt-5.5 on claude is not.
+        model_fam = vendor_of_model(model)
+        lane_fam = vendor_of_harness(harness)
+        if model_fam and model_fam == lane_fam:
+            return (True, AuthAvailability(subscription=True, detail="subscription"))
+        return (
+            False,
+            AuthAvailability(detail=f"{model} is not compatible with the {harness} lane"),
+        )
+
+    def default_lane(self, model: str) -> str:
+        return _default_lane_for(model)
+
+
+@dataclass(frozen=True)
+class StandinModelRegistry:
+    """A ``ModelRegistry`` (frozen Protocol) backed by the canonical fixtures.
+
+    ``runnable_by`` lists every canonical lane a model is valid on — used by
+    ``validation`` to render an actionable "did you mean" diagnostic on an invalid
+    seat.
+    """
+
+    def list_models(self) -> tuple[ModelSpec, ...]:
+        return tuple(self.get(model) for model in _canonical_models())
+
+    def get(self, model: str) -> ModelSpec:
+        lanes = runnable_lanes(model)
+        return ModelSpec(
+            model=model,
+            vendor_family=vendor_family(model),
+            default_lane=_default_lane_for(model),
+            runnable_by=lanes,
+        )
+
+    def default_lane(self, model: str) -> str:
+        return _default_lane_for(model)
+
+
+@dataclass(frozen=True)
+class StandinHarnessRegistry:
+    """A minimal ``HarnessRegistry`` over the canonical lanes (probe-agnostic)."""
+
+    def list_harnesses(self) -> tuple[HarnessSpec, ...]:
+        return tuple(self.get(name) for name in _canonical_harnesses())
+
+    def get(self, name: str) -> HarnessSpec:
+        return HarnessSpec(
+            name=name,
+            cli=name,
+            auth_lanes=(AUTH_SUBSCRIPTION,),
+            backing=BACKING_HOMEBREW,
+        )
+
+    def is_available(self, name: str) -> bool:
+        return name in _canonical_harnesses()
+
+
+def runnable_lanes(model: str) -> tuple[str, ...]:
+    """The canonical harness lanes a ``model`` is valid on (fixture-derived)."""
+    lanes: list[str] = []
+    for pair_model, pair_harness in CANONICAL_VALID_PAIRS:
+        if pair_model == model and pair_harness not in lanes:
+            lanes.append(pair_harness)
+    return tuple(lanes)
+
+
+def _canonical_models() -> tuple[str, ...]:
+    seen: list[str] = []
+    for model, _ in CANONICAL_VALID_PAIRS:
+        if model not in seen:
+            seen.append(model)
+    return tuple(seen)
+
+
+def _canonical_harnesses() -> tuple[str, ...]:
+    seen: list[str] = []
+    for _, harness in CANONICAL_VALID_PAIRS:
+        if harness not in seen:
+            seen.append(harness)
+    return tuple(seen)
+
+
+__all__ = [
+    "StandinCompatibilityMatrix",
+    "StandinModelRegistry",
+    "StandinHarnessRegistry",
+    "runnable_lanes",
+]