testerkit 0.4.0__py3-none-any.whl

testerkit/data/run_store.py

@@ -0,0 +1,367 @@
+"""RunStore — query API for parquet test run data.
+
+Mirrors EventStore's pattern: parquet files are the source of truth,
+a DuckDB daemon indexes them, and RunStore provides a clean query API.
+ParquetBackend keeps the write path; RunStore owns reads + ref management.
+
+Construct once and reuse across notebook cells or long-running scripts.
+The analytical daemon is a separate process with its own PID-ref and idle
+timeout, so forgetting to call ``close()`` does not leak it. ``close()``
+and ``with`` are optional.
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+from pathlib import Path
+from typing import Any
+
+import pyarrow as pa
+import pyarrow.flight as flight
+import pyarrow.parquet as pq
+
+from testerkit.data import runs_duckdb_manager
+from testerkit.data._flight_query import FlightQueryClient, call_options
+from testerkit.data._sql_helpers import sql_escape as _sql_escape
+from testerkit.data.backends._row_helpers import _decode_io_maps
+from testerkit.data.data_dir import resolve_data_dir
+from testerkit.data.models import RunSummary
+
+logger = logging.getLogger(__name__)
+
+
+class DataUnavailable(Exception):
+    """Raised when a run's parquet data is not locally accessible.
+
+    The run's metadata (outcome, started_at, measurement stats) remains
+    queryable from the index.  Raw scalars and ref data require the file.
+    """
+
+    def __init__(self, file_path: str, *, status: str = "missing") -> None:
+        self.file_path = file_path
+        self.status = status
+        super().__init__(f"Run data {status}: {file_path}")
+
+
+class RunStore:
+    """Query API for parquet test run data.
+
+    Uses a ref-counted in-memory DuckDB daemon for indexed queries — same
+    lifecycle pattern as EventStore. Queries go via Arrow Flight (gRPC).
+
+    Construct once and reuse across calls. ``close()`` / ``with`` are optional
+    — the daemon is a separate process that self-manages via PID-ref and idle
+    timeout, so forgetting to close does not leak it.
+    """
+
+    def __init__(self, *, _data_dir: Path | str | None = None) -> None:
+        data_dir = resolve_data_dir(_data_dir)
+
+        self._runs_dir = data_dir / "runs"
+        self._runs_dir.mkdir(parents=True, exist_ok=True)
+
+        # Start daemon and get gRPC location
+        self._location = runs_duckdb_manager.acquire(self._runs_dir)
+
+        # Flight query client (shared retry logic with EventStore)
+        self._flight = FlightQueryClient(
+            self._location,
+            "runs",
+            reacquire=lambda: runs_duckdb_manager.acquire(self._runs_dir),
+            label="RunStore",
+        )
+
+    def _flight_query(self, sql: str) -> list[dict[str, Any]]:
+        """Execute a SQL query via Flight and return list of dicts."""
+        return self._flight.query(sql)
+
+    # --- Query API ---
+
+    @staticmethod
+    def _id_prefix(run_id: str, length: int = 8) -> str:
+        """Return an 8-char (or shorter) prefix for LIKE matching against the index."""
+        return run_id[:length] if len(run_id) >= length else run_id
+
+    def list_runs(self, limit: int = 50) -> list[RunSummary]:
+        """List recent test runs, most recent first."""
+        rows = self._flight_query(f"""
+            SELECT file_path, run_id, session_id, uut_serial_number, station_id,
+                   outcome, started_at, num_measurements,
+                   test_phase, part_id, operator_id,
+                   project_name
+            FROM runs
+            ORDER BY started_at DESC
+            LIMIT {limit}
+        """)
+
+        return [
+            RunSummary(
+                test_run_id=r["run_id"],
+                session_id=r.get("session_id"),
+                started_at=r.get("started_at"),
+                uut_serial_number=r.get("uut_serial_number"),
+                station_id=r.get("station_id"),
+                outcome=r.get("outcome"),
+                total_measurements=r.get("num_measurements", 0),
+                test_phase=r.get("test_phase"),
+                part_id=r.get("part_id"),
+                operator=r.get("operator_id"),
+                project_name=r.get("project_name"),
+                file_path=r.get("file_path"),
+            )
+            for r in rows
+        ]
+
+    def find_run_file(self, run_id: str) -> Path | None:
+        """Find the measurements parquet for a run_id (prefix match).
+
+        Returns ``None`` when the runs row has no measurements
+        parquet (measurement-less run — only setup / action /
+        skipped steps) or when the file is missing from disk.
+        """
+        prefix = self._id_prefix(run_id)
+        rows = self._flight_query(f"""
+            SELECT file_path FROM runs
+            WHERE run_id LIKE '{_sql_escape(prefix)}%'
+            LIMIT 1
+        """)
+
+        if not rows or rows[0].get("file_path") is None:
+            return None
+        p = Path(rows[0]["file_path"])
+        return p if p.exists() else None
+
+    def get_run(self, run_id: str) -> RunSummary | None:
+        """Get a run summary by ID (prefix match), runs-table-first.
+
+        The runs TABLE (or, for a not-yet-materialized run, the
+        in-flight overlay row — see ``runs`` view) carries every
+        run-level field needed to render the summary card, including
+        ``site_index`` / ``site_name`` (denormalized onto every row at
+        ingest, per ``_RUNS_PERSISTED_COLUMNS``). Only ``station_type``
+        isn't denormalized onto the runs table — we crack open the
+        measurements parquet just for that one, skipped silently when
+        ``file_path`` is NULL (a not-yet-materialized / in-flight run).
+        """
+        prefix = self._id_prefix(run_id)
+        rows = self._flight_query(f"""
+            SELECT * FROM runs
+            WHERE run_id LIKE '{_sql_escape(prefix)}%'
+            LIMIT 1
+        """)
+        if not rows:
+            return None
+        r = rows[0]
+        run_id_val = r.get("run_id")
+        if not run_id_val:
+            return None
+
+        summary = RunSummary(
+            test_run_id=run_id_val,
+            session_id=r.get("session_id"),
+            site_index=r.get("site_index"),
+            site_name=r.get("site_name"),
+            started_at=r.get("started_at"),
+            ended_at=r.get("ended_at"),
+            uut_serial_number=r.get("uut_serial_number"),
+            uut_part_number=r.get("uut_part_number"),
+            part_id=r.get("part_id"),
+            station_id=r.get("station_id"),
+            station_name=r.get("station_name"),
+            station_hostname=r.get("station_hostname"),
+            fixture_id=r.get("fixture_id"),
+            test_phase=r.get("test_phase"),
+            project_name=r.get("project_name"),
+            operator=r.get("operator_id"),
+            outcome=r.get("outcome"),
+            total_measurements=r.get("num_measurements", 0) or 0,
+            file_path=r.get("file_path"),
+        )
+
+        # station_type isn't in the runs table — sourced from the
+        # measurements parquet when available. Skipped silently for
+        # not-yet-materialized (in-flight) runs.
+        pq_path_str = r.get("file_path")
+        if pq_path_str:
+            pq_path = Path(pq_path_str)
+            if pq_path.exists():
+                try:
+                    table = pq.read_table(pq_path)
+                    if table.num_rows > 0:
+                        first = table.to_pylist()[0]
+                        summary.station_type = first.get("station_type")
+                except Exception as exc:
+                    logger.debug("Failed to enrich run %s from parquet: %s", run_id, exc)
+        return summary
+
+    def get_measurements(self, run_id: str) -> list[dict[str, Any]]:
+        """Get all measurements for a specific test run.
+
+        Goes through the daemon's ``measurements`` view (a parquet glob
+        with ``union_by_name=true``) instead of reading the parquet file
+        directly — DuckDB does the multi-file scan in C++ with predicate
+        pushdown on ``run_id`` and avoids client-side parquet decoding.
+
+        Per-row ``inputs``/``outputs`` are derived at query time from the
+        ``inputs``/``outputs`` tables (projection-normalization, 0.3.1) —
+        LEFT JOINed and aggregated into a VARCHAR map per (role, vector
+        coordinate), same key the daemon's EAV joins have always used
+        (``run_id, step_index, step_path, vector_index, vector_outer_index,
+        vector_retry`` — no ``step_retry``: this is the measurement's own
+        FK, matching historical behavior exactly). ``None`` when a run has no
+        materialized rows for that (role, coordinate) — decodes to ``{}``.
+        """
+        prefix = self._id_prefix(run_id)
+        io_join = """
+            LEFT JOIN (
+                SELECT run_id, step_index, step_path, step_retry, vector_index,
+                       vector_outer_index, vector_retry,
+                       MAP(list(name), list(
+                           CASE value_type
+                               WHEN 'scalar:bool'
+                                   THEN CASE WHEN value_bool THEN 'true' ELSE 'false' END
+                               WHEN 'scalar:int' THEN CAST(value_int AS VARCHAR)
+                               WHEN 'scalar:float' THEN CAST(value_double AS VARCHAR)
+                               WHEN 'scalar:datetime' THEN CAST(value_timestamp AS VARCHAR)
+                               WHEN 'list' THEN value_json
+                               WHEN 'dict' THEN value_json
+                               ELSE value_text
+                           END
+                       )) AS {map_col}
+                FROM {table}
+                GROUP BY run_id, step_index, step_path, step_retry, vector_index,
+                    vector_outer_index, vector_retry
+            ) AS {alias} ON {alias}.run_id = m.run_id
+                AND {alias}.step_index = m.step_index
+                AND {alias}.step_path IS NOT DISTINCT FROM m.step_path
+                AND {alias}.step_retry IS NOT DISTINCT FROM m.step_retry
+                AND {alias}.vector_index IS NOT DISTINCT FROM m.vector_index
+                AND {alias}.vector_outer_index IS NOT DISTINCT FROM m.vector_outer_index
+                AND {alias}.vector_retry IS NOT DISTINCT FROM m.vector_retry
+        """
+        try:
+            rows = self._flight_query(f"""
+                SELECT m.*, inputs_agg.inputs_map, outputs_agg.outputs_map
+                FROM measurements m
+                {io_join.format(alias="inputs_agg", table="inputs", map_col="inputs_map")}
+                {io_join.format(alias="outputs_agg", table="outputs", map_col="outputs_map")}
+                WHERE m.run_id LIKE '{_sql_escape(prefix)}%'
+                ORDER BY m.step_index, m.measurement_name
+            """)
+        except Exception as exc:
+            logger.debug("Failed to query measurements for %s: %s", run_id, exc)
+            return []
+
+        for row in rows:
+            # pop removes the raw maps from the dict before returning it
+            row["inputs"], row["outputs"] = _decode_io_maps(
+                row.pop("inputs_map", None), row.pop("outputs_map", None)
+            )
+        return rows
+
+    # --- Ref management (for materialize) ---
+
+    def get_steps(self, run_id: str) -> list[dict[str, Any]]:
+        """Get steps for a run from the daemon's ``steps`` view."""
+        prefix = self._id_prefix(run_id)
+        return self._flight_query(f"""
+            SELECT step_index, step_name, step_path, outcome,
+                   CAST(started_at AT TIME ZONE 'UTC' AS VARCHAR) AS started_at,
+                   CAST(ended_at AT TIME ZONE 'UTC' AS VARCHAR) AS ended_at,
+                   duration_s, measurement_count, step_retry, markers
+            FROM steps
+            WHERE run_id LIKE '{_sql_escape(prefix)}%'
+            ORDER BY step_index, step_retry, vector_index
+        """)
+
+    def find_channel_refs(self, session_shorts: set[str]) -> list[dict[str, Any]]:
+        """Query measurement_refs WHERE session_short IN (...)."""
+        if not session_shorts:
+            return []
+
+        quoted = ", ".join(f"'{_sql_escape(s)}'" for s in session_shorts)
+        return self._flight_query(f"""
+            SELECT file_path, step_index, measurement_name, col_name,
+                   role, row_idx, uri, channel_id, session_short, session_id
+            FROM measurement_refs
+            WHERE session_short IN ({quoted})
+        """)
+
+    def get_measurement(
+        self,
+        file_path: str | Path,
+        measurement_name: str,
+        *,
+        step_index: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Get rows for a specific measurement name, with predicate pushdown.
+
+        Uses pyarrow row-group filters so only matching row groups are read.
+        Raises DataUnavailable if the file is missing or marked non-ok in the index.
+        Returns [] if the parquet file exists but lacks a measurement_name column
+        (e.g. a file written by an older schema version).
+        """
+        pq_file = Path(file_path)
+        if not pq_file.exists():
+            status_rows = self._flight_query(
+                f"SELECT status FROM _ingested WHERE path = '{_sql_escape(str(pq_file))}'"
+            )
+            status = status_rows[0]["status"] if status_rows else "missing"
+            raise DataUnavailable(str(pq_file), status=status)
+
+        filters: list[tuple] = [("measurement_name", "=", measurement_name)]
+        if step_index is not None:
+            filters.append(("step_index", "=", step_index))
+
+        try:
+            table = pq.read_table(pq_file, filters=filters)
+            return table.to_pylist()
+        except Exception as exc:
+            logger.debug(
+                "Failed to read measurement %r from %s: %s", measurement_name, pq_file, exc
+            )
+            return []
+
+    @staticmethod
+    def ref_dir_for(file_path: Path) -> Path:
+        """Return _ref/ sidecar dir path for a parquet file."""
+        return file_path.parent / (file_path.stem + "_ref")
+
+    def notify_new_run(self, parquet_path: Path) -> None:
+        """Notify the daemon of a new unified per-run parquet via do_put."""
+        paths = [str(parquet_path)]
+        try:
+            client = self._flight.get_client()
+            descriptor = flight.FlightDescriptor.for_command(b"runs\0runs")
+            table = pa.table({"file_path": paths})
+            batches = table.to_batches()
+            writer, reader = client.do_put(descriptor, table.schema, options=call_options())
+            for batch in batches:
+                writer.write_batch(batch)
+            # Drain ACKs — each ACK confirms the server committed one batch,
+            # so by the time the last ACK arrives the daemon has fully ingested
+            # the file into all index tables including measurements_materialized.
+            for _ in batches:
+                reader.read()
+            writer.close()
+        except Exception:
+            logger.debug("Failed to notify runs daemon of new run %s", parquet_path, exc_info=True)
+            self._flight.reset()
+
+    def close(self) -> None:
+        """Close Flight client and release daemon ref."""
+        try:
+            self._flight.close()
+        except Exception as exc:
+            warnings.warn(f"FlightQueryClient close failed: {exc}", stacklevel=2)
+        try:
+            runs_duckdb_manager.release(self._runs_dir)
+        except Exception as exc:
+            warnings.warn(f"runs_duckdb_manager.release failed: {exc}", stacklevel=2)
+
+    def __enter__(self) -> RunStore:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()

testerkit/data/runs_duckdb_manager.py

@@ -0,0 +1,103 @@
+"""DuckDB run index daemon manager.
+
+Subclasses ``DaemonManager`` for the runs DuckDB daemon.
+Clients call ``acquire()`` / ``release()``.
+
+Parquet files are the source of truth. The in-memory DuckDB index
+is rebuilt from parquet on every daemon start.
+"""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from typing import Any
+
+from testerkit.data._daemon_lifecycle import DaemonManager, _installed_version, wait_for_location
+from testerkit.data._flight_query import probe_sql
+
+
+class RunsDuckDBManager(DaemonManager):
+    """Manages the DuckDB runs index daemon."""
+
+    _state_name = "_runs_duckdb.json"
+    _lock_name = "_runs_duckdb.lock"
+    _ready_name = "_runs_duckdb_ready"
+    _pid_name = "_runs_duckdb_pid"
+    _daemon_module = "testerkit.data._runs_duckdb_daemon"
+    _port_file = "_runs_duckdb_flight_port"
+
+    # Runs keys daemon reuse on the projection FINGERPRINT, not just the testerkit
+    # version (the base-class default). The fingerprint is a content-address of
+    # the read path (projection DDL + adapters + whitelist), so a daemon serves
+    # exactly one index shape + SQL. Keying reuse on it means a client never
+    # sends a daemon SQL for a different projection — the coexistence law of the
+    # index-epoch design (derived-index-versioning.md §11.1). ``_projection_
+    # fingerprint`` is imported lazily inside the methods to break the import
+    # cycle (the daemon module imports this manager).
+
+    def _daemon_identity(self) -> dict[str, Any]:
+        """Stamp the projection fingerprint (plus the version, for provenance)
+        into the state file, so ``_can_reuse`` can compare it. A projection
+        change — even within one testerkit version (a dev edit / branch switch,
+        invisible to the version ratchet) — yields a new fingerprint and thus a
+        fresh daemon on the matching epoch."""
+        from testerkit.data._runs_duckdb_daemon import _projection_fingerprint
+
+        return {"testerkit_version": _installed_version(), "fingerprint": _projection_fingerprint()}
+
+    def _can_reuse(self, running_state: dict[str, Any]) -> bool:
+        """Reuse only a daemon whose projection fingerprint matches ours exactly.
+        A different — or missing (a pre-fingerprint daemon) — fingerprint means it
+        serves a different-shaped index/SQL, so respawn rather than send it queries
+        it can't answer. Fingerprint equality subsumes the version ratchet: a
+        version bump that changes the projection changes the fingerprint (respawn);
+        one that doesn't keeps it (reuse)."""
+        from testerkit.data._runs_duckdb_daemon import _projection_fingerprint
+
+        return running_state.get("fingerprint") == _projection_fingerprint()
+
+
+# Module-level convenience — RunStore uses these directly.
+
+
+def acquire(runs_dir: Path) -> str:
+    """Acquire a reference to the runs DuckDB daemon, starting it if needed.
+
+    Returns the gRPC location string for Flight queries.
+
+    The location is written to state file by either
+    :meth:`DaemonManager.acquire` (fresh spawn — reads the port file via
+    ``_post_spawn_state``) or by the daemon itself
+    (:meth:`DaemonManager.update_state` after ``write_ready``). Under
+    load on slow CI runners we've seen reuse hit a state file the
+    daemon hasn't finished filling in yet — poll briefly so transient
+    "missing location" cases don't fail the test.
+
+    After getting the location, a lightweight Flight connectivity probe
+    is attempted. If the Flight server isn't responding (e.g. the daemon
+    process is alive but its Flight thread crashed), the daemon is killed
+    and respawned so callers always get a working connection.
+    """
+    mgr = RunsDuckDBManager(runs_dir)
+    mgr.acquire()
+    location = wait_for_location(mgr, runs_dir, "runs")
+
+    # Verify the Flight server is actually responding. The PID may be alive
+    # but the Flight thread may have crashed (e.g. port conflict, OOM).
+    # One cheap probe avoids leaving callers with a silent dead connection.
+    if not probe_sql(location, "runs"):
+        warnings.warn(
+            f"Runs daemon at {location} is not responding — killing and respawning.",
+            stacklevel=2,
+        )
+        mgr.force_restart()
+        mgr.acquire()
+        location = wait_for_location(mgr, runs_dir, "runs")
+
+    return location
+
+
+def release(runs_dir: Path) -> None:
+    """Release our reference to the runs DuckDB daemon."""
+    RunsDuckDBManager(runs_dir).release()

testerkit/data/schema_dispatch.py

@@ -0,0 +1,191 @@
+"""Read-time schema-version dispatch — the seam where a durable artifact's
+stamp selects the adapter that projects it to the current shape.
+
+Called exactly once per store, at that store's ``durable-artifact -> rows``
+read boundary (§1/§4 of ``schema-versioning-migration.md``). The whole
+versioning surface reduces to:
+
+    stamp  --dispatch-->  adapter(source_version -> current)  -->  current rows
+
+Three outcomes when a file's stamp is read:
+
+- **present and whitelisted** (in :data:`KNOWN_SCHEMA_VERSIONS`) -> return that
+  version's adapter (identity today: ``0.1`` == current, no transform).
+- **present but unknown** (a future ``5.0``, or an abandoned version) -> refuse
+  with :class:`SchemaVersionRefused` ("unsupported schema version").
+- **absent** (unstamped) -> refuse ("regenerate"). The current version is always
+  stamped at write, so absence can only mean a pre-stamp file.
+
+Each store's read boundary catches :class:`SchemaVersionRefused` and routes it
+into that store's existing skip/quarantine path, so one bad-version file is
+isolated and the good ones still land.
+
+The adapter registry ships **current-identity only** — no speculative
+transforms. A real ``vN -> current`` adapter is registered here the same commit
+its source version joins :data:`KNOWN_SCHEMA_VERSIONS`.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from testerkit.data.schema_versions import KNOWN_SCHEMA_VERSIONS, SchemaStore
+
+_logger = logging.getLogger(__name__)
+
+# An adapter is a pure transform from a source-version artifact to the current
+# shape. For the Arrow stores (runs / events / channels) it is
+# ``pa.Table -> pa.Table``; for the files sidecar it is
+# ``FileArtifactMetadata -> FileArtifactMetadata``. Kept structurally typed
+# (``Any -> Any``) because the registry spans both.
+Adapter = Callable[[Any], Any]
+
+
+def _schema_version_tuple(v: str) -> tuple[int, ...] | None:
+    """Parse a dotted schema version into a comparable int tuple; ``None`` if
+    unparseable. Named distinctly from ``_daemon_lifecycle._version_tuple``,
+    which *leniently* parses PACKAGE versions (``.dev``/``.rc`` suffixes); schema
+    versions are clean ``major.minor`` and parse strictly."""
+    try:
+        return tuple(int(part) for part in v.split("."))
+    except (ValueError, AttributeError):
+        return None
+
+
+class SchemaVersionRefused(Exception):
+    """A durable artifact carries a schema version this store cannot read.
+
+    ``deferrable`` splits the two refusal classes that need different fates at
+    the read boundary (see #43):
+
+    - **deferrable=True** — the stamp is a version *newer* than anything this
+      daemon knows. The machine's singleton daemon trends newest, so a newer
+      daemon WILL read it — the file must stay re-attemptable (never permanently
+      ledgered), else it goes invisible forever after the daemon is upgraded.
+    - **deferrable=False** — absent (unstamped) or an unparseable / older-unknown
+      stamp. No future daemon will read it: permanent skip (regenerate).
+    """
+
+    def __init__(
+        self, store: SchemaStore, version: str | None, reason: str, *, deferrable: bool
+    ) -> None:
+        self.store = store
+        self.version = version
+        self.deferrable = deferrable
+        super().__init__(f"[{store.value}] schema version {version!r}: {reason}")
+
+
+# ── Adapter registry ────────────────────────────────────────────────────────
+# One transform per (store, source_version) -> current. Empty today (every
+# known version IS current, so dispatch returns identity). ``register_adapter``
+# is how a future epoch's transform is added; ``_identity`` is the current no-op.
+
+
+def _identity(rows: Any) -> Any:
+    """Identity adapter (the current-version no-op). Adapter contract for future
+    authors: an adapter MUST NOT mutate its input in place — return the value.
+    Returning the input unchanged is correct for this no-op (Arrow tables are
+    immutable anyway; the migrate sink calls ``.replace_schema_metadata()`` on the
+    result, which copies). A real transform returns a new table / copied model."""
+    return rows
+
+
+_ADAPTERS: dict[SchemaStore, dict[str, Adapter]] = {store: {} for store in SchemaStore}
+
+
+def register_adapter(store: SchemaStore, source_version: str, adapter: Adapter) -> None:
+    """Register a ``source_version -> current`` transform for *store*, and make
+    that version readable in the same step.
+
+    Registering an adapter also adds ``source_version`` to
+    ``KNOWN_SCHEMA_VERSIONS[store]`` — otherwise the adapter would be dead code:
+    :func:`dispatch` refuses an unknown version *before* it ever reaches the
+    adapter. Self-wiring removes that two-edit footgun.
+    """
+    _ADAPTERS[store][source_version] = adapter
+    KNOWN_SCHEMA_VERSIONS[store] = KNOWN_SCHEMA_VERSIONS[store] | {source_version}
+
+
+def dispatch(store: SchemaStore, version: str | None) -> Adapter:
+    """Whitelist-dispatch *version* for *store*; return its adapter or refuse.
+
+    Returns the registered adapter, or :func:`_identity` when the version is
+    known but current-shaped (the current-version case). Raises
+    :class:`SchemaVersionRefused` for an unknown or absent version.
+    """
+    if version is None:
+        raise SchemaVersionRefused(
+            store,
+            None,
+            "unstamped artifact — unsupported by design; regenerate",
+            deferrable=False,
+        )
+    if version not in KNOWN_SCHEMA_VERSIONS[store]:
+        known = ", ".join(sorted(KNOWN_SCHEMA_VERSIONS[store]))
+        # Deferrable iff strictly NEWER than every known version — a newer daemon
+        # will read it. Older / unparseable-unknown is pre-baseline or garbage: permanent.
+        vt = _schema_version_tuple(version)
+        known_tuples = [
+            t for t in (_schema_version_tuple(k) for k in KNOWN_SCHEMA_VERSIONS[store]) if t
+        ]
+        deferrable = bool(vt and known_tuples and vt > max(known_tuples))
+        raise SchemaVersionRefused(
+            store,
+            version,
+            f"unsupported schema version (known: {known})",
+            deferrable=deferrable,
+        )
+    return _ADAPTERS[store].get(version, _identity)
+
+
+# ── Refusal reporting ────────────────────────────────────────────────────────
+# Process-local dedup so the presence-only stores (channels / files), which
+# re-read an un-ledgered refusal every scan, don't re-warn each time. Not
+# backend-coupled — plain stdlib logging over a set of already-warned paths.
+# Capped so a pathological flood of distinct bad-version files can't grow it
+# without bound; clearing at the cap just lets each path warn once more.
+_MAX_WARNED_PATHS = 4096
+_warned_permanent_refusals: set[str] = set()
+# A daemon may report refusals from more than one ingest thread; the lock keeps
+# the check-and-add atomic so a path warns exactly once (else two threads racing
+# the same path each emit the warning).
+_warned_lock = threading.Lock()
+
+
+def report_schema_refusal(exc: SchemaVersionRefused, path: str) -> None:
+    """Surface a refusal uniformly across all four store boundaries: a
+    *deferrable* (newer) refusal is a transient debug note (a newer daemon will
+    ingest it); a *permanent* (absent / unstamped) refusal is warned once per path
+    so the operator knows the file needs regenerating.
+    """
+    if exc.deferrable:
+        _logger.debug("Deferring newer-version artifact %s: %s", path, exc)
+        return
+    with _warned_lock:
+        if path in _warned_permanent_refusals:
+            return
+        if len(_warned_permanent_refusals) >= _MAX_WARNED_PATHS:
+            _warned_permanent_refusals.clear()
+        _warned_permanent_refusals.add(path)
+    # Log outside the lock (I/O): only the winning thread reaches here per path.
+    _logger.warning("Skipping unsupported (unstamped/unknown) schema in %s: %s", path, exc)
+
+
+# ── Stamp extraction ────────────────────────────────────────────────────────
+
+
+def stamp_from_arrow_metadata(
+    metadata: dict[bytes, bytes] | None, key: bytes = b"schema_version"
+) -> str | None:
+    """Read a schema-version stamp from Arrow/parquet file-level metadata.
+
+    Returns ``None`` if the metadata is absent or lacks *key* — which
+    :func:`dispatch` treats as an unstamped artifact.
+    """
+    if not metadata:
+        return None
+    raw = metadata.get(key)
+    return raw.decode() if raw is not None else None