testerkit 0.4.0__py3-none-any.whl

testerkit/data/schema_migrate.py

@@ -0,0 +1,76 @@
+"""Opt-in **migrate** sink — rewrite an owned durable file forward to the current
+schema, in place, via the same adapter the reader uses.
+
+The re-index sink (the whitelist-dispatch reader at each store's ingest boundary)
+is the *mandatory floor*: it projects any readable version forward at query time
+and never touches the file. Migrate is the *optional* housekeeping layer on top —
+"migration is re-index that also persists the adapter output" (§4 of
+``schema-versioning-migration.md``). It exists so an operator can retire old-major
+files (and their adapters) once they're rewritten, not because reading requires
+it. Never a substitute for read-time projection: files in the wild are unreachable.
+
+Both content kinds the adapters span are covered here:
+- ``migrate_parquet_file`` — Arrow/parquet (runs). Events/channels are the same
+  Arrow pattern over IPC; wired when a real adapter first needs them (YAGNI).
+- ``migrate_sidecar_file`` — the FileStore JSON sidecar (Pydantic model).
+
+Each is idempotent (a current-version file is a no-op) and raises
+:class:`~testerkit.data.schema_dispatch.SchemaVersionRefused` for a file the current
+build cannot read (absent/pre-1.0 or unknown) — the caller decides whether to
+skip or surface it, exactly as the re-index sink does.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pyarrow.parquet as pq
+
+from testerkit.data._atomic import atomic_write_table, atomic_write_text
+from testerkit.data.files.models import FileArtifactMetadata
+from testerkit.data.schema_dispatch import dispatch, stamp_from_arrow_metadata
+from testerkit.data.schema_versions import CURRENT_SCHEMA_VERSION, SchemaStore
+
+
+def migrate_parquet_file(store: SchemaStore, path: Path | str) -> bool:
+    """Rewrite a parquet artifact forward to the current schema, atomically.
+
+    Reads the footer stamp, applies the ``source -> current`` adapter, re-stamps
+    the result to the current version, and atomically replaces the file. Returns
+    ``True`` if it migrated, ``False`` if already current (no-op). Raises
+    :class:`SchemaVersionRefused` for an unreadable version.
+    """
+    path = Path(path)
+    parquet_file = pq.ParquetFile(str(path))
+    stamp = stamp_from_arrow_metadata(parquet_file.schema_arrow.metadata)
+    current = CURRENT_SCHEMA_VERSION[store]
+    if stamp == current:
+        return False
+    adapter = dispatch(store, stamp)
+    migrated = adapter(parquet_file.read()).replace_schema_metadata(
+        {b"schema_version": current.encode()}
+    )
+    atomic_write_table(migrated, path)
+    return True
+
+
+def migrate_sidecar_file(path: Path | str) -> bool:
+    """Rewrite a FileStore ``.meta.json`` sidecar forward to the current schema.
+
+    Reads the raw JSON (so an absent stamp is detectable), applies the
+    ``source -> current`` adapter to the ``FileArtifactMetadata`` model, re-stamps
+    to the current version, and atomically replaces the sidecar. The blob is never
+    touched (it is opaque user payload). Returns ``True`` if migrated, ``False`` if
+    already current. Raises :class:`SchemaVersionRefused` for an unreadable version.
+    """
+    path = Path(path)
+    raw = json.loads(path.read_text())
+    current = CURRENT_SCHEMA_VERSION[SchemaStore.FILES]
+    if raw.get("schema_version") == current:
+        return False
+    adapter = dispatch(SchemaStore.FILES, raw.get("schema_version"))
+    migrated = adapter(FileArtifactMetadata.model_validate(raw))
+    migrated = migrated.model_copy(update={"schema_version": current})
+    atomic_write_text(migrated.model_dump_json(), path)
+    return True

testerkit/data/schema_versions.py

@@ -0,0 +1,85 @@
+"""Central registry of durable-artifact schema versions.
+
+The single home for *which durable stores exist and which schema versions
+each can read*. Every durable artifact a TesterKit daemon writes carries a
+schema-version stamp in its file metadata; the stamp is the **migration
+key**. At each store's ``durable-artifact -> rows`` read boundary a
+whitelist-dispatch reader matches the stamp against
+:data:`KNOWN_SCHEMA_VERSIONS` and picks the adapter that projects that
+version forward to the current shape. See
+``docs/_internal/explorations/schema-versioning-migration.md`` for the full
+strategy (read-time adaptation, coexist-always + optional-migrate).
+
+Versioning is SemVer and **decoupled from the testerkit package version** — the
+stores diverge on their own lines, so schema ``0.1`` at package ``0.3.0`` is
+deliberate, not a mismatch.
+
+The breaking unit is the **epoch = leftmost-significant SemVer component**:
+
+- **Pre-1.0** — the **MINOR** is the epoch. ``0.1 -> 0.2`` is a breaking
+  reshape (a new epoch); there is no additive tier yet. Each 0.x epoch is a
+  clean break that regenerates or read-time-adapts prior-epoch artifacts —
+  deliberately rehearsing the same epoch -> quarantine/adapter path we'll bet
+  on at the first real ``2.0``, so the apparatus is proven before 1.0.
+- **Post-1.0** — the **MAJOR** is the epoch. ``1.0 -> 1.1`` becomes additive
+  (``union_by_name`` null-fills old files, ``ALTER TABLE ADD COLUMN IF NOT
+  EXISTS`` extends the projection); ``1.x -> 2.0`` is the breaking epoch,
+  needing a per-version read-time adapter + a frozen reference doc for the
+  outgoing epoch.
+
+All stores start at ``"0.1"`` — a distinct pre-1.0 schema line, **not frozen**.
+1.0 is graduated to later, once the schema design and this apparatus have real
+mileage (see ``docs/_internal/explorations/pre-1.0-epoch-strategy.md``).
+Unstamped artifacts are unsupported by design (regenerate).
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class SchemaStore(StrEnum):
+    """A durable-artifact store that stamps and dispatches on a schema version.
+
+    Events carries **two** coordinates (§3 of the strategy doc): the storage
+    ``ENVELOPE`` (the ``_IPC_SCHEMA`` column shape) and the payload
+    ``EVENT_CATALOG`` (the event models). They version independently.
+    """
+
+    RUNS = "runs"
+    """Runs parquet — content fused into the columnar schema (footer metadata)."""
+    EVENTS_ENVELOPE = "events_envelope"
+    """Event WAL Arrow IPC envelope — ``event_log._IPC_SCHEMA``."""
+    EVENT_CATALOG = "event_catalog"
+    """Event payload catalog — the event models in ``data.events``."""
+    CHANNELS = "channels"
+    """Channel ``.arrow`` skeleton, value typed by ``value_type``."""
+    FILES = "files"
+    """FileStore sidecar (``FileArtifactMetadata``); the blob is opaque."""
+
+
+# The stamp a freshly written artifact carries, per store. This is the one
+# home for the current version — every store's public constant aliases the
+# matching entry here (do not hardcode the string at the write site).
+CURRENT_SCHEMA_VERSION: dict[SchemaStore, str] = {
+    SchemaStore.RUNS: "0.1",
+    SchemaStore.EVENTS_ENVELOPE: "0.1",
+    SchemaStore.EVENT_CATALOG: "0.1",
+    SchemaStore.CHANNELS: "0.1",
+    SchemaStore.FILES: "0.1",
+}
+
+# Older epochs a store still ships a read-time adapter for. Empty today
+# (0.1-only). Add an entry the *same commit* its ``vN -> current`` adapter
+# lands, so the whitelist reader starts accepting that version exactly when it
+# can transform it.
+_LEGACY_READABLE: dict[SchemaStore, frozenset[str]] = {store: frozenset() for store in SchemaStore}
+
+# Versions each store's reader will dispatch. Current ∪ legacy-readable, so the
+# current version is always accepted by construction. Anything not in this set
+# is refused at read time ("unsupported schema version"); an absent stamp is
+# refused as unstamped/pre-baseline ("regenerate").
+KNOWN_SCHEMA_VERSIONS: dict[SchemaStore, frozenset[str]] = {
+    store: frozenset({CURRENT_SCHEMA_VERSION[store]}) | _LEGACY_READABLE[store]
+    for store in SchemaStore
+}

testerkit/data/schemas.py

@@ -0,0 +1,288 @@
+"""Canonical Arrow schema contract shared across all backends.
+
+Defines the measurement schema, type inference for dynamic columns,
+and helpers for constructing validated Arrow tables. Any backend
+(Parquet, Flight, NATS) imports from here rather than defining its own
+schema.
+"""
+
+from datetime import datetime
+from typing import Any
+
+import pyarrow as pa
+
+from testerkit.data.backends._row_helpers import (
+    INSTRUMENT_STRUCT_FIELDS,
+    LANE_FIELDS,
+    MEASUREMENT_STRUCT_FIELDS,
+)
+from testerkit.data.schema_versions import CURRENT_SCHEMA_VERSION, SchemaStore
+
+__all__ = [
+    "RUN_ROW_SCHEMA",
+    "SCHEMA_VERSION",
+    "INSTRUMENT_STRUCT_FIELDS",
+    "_INSTRUMENT_LIST",
+    "_INSTRUMENT_STRUCT",
+    "_LANE_LIST",
+    "_MEASUREMENT_LIST",
+    "_MEASUREMENT_STRUCT",
+    "_SCHEMA_DICT",
+    "_build_write_schema",
+    "table_from_rows",
+]
+
+# Runs parquet footer stamp. Sourced from the central registry (one home);
+# see ``testerkit.data.schema_versions`` for the SemVer / migration contract.
+SCHEMA_VERSION = CURRENT_SCHEMA_VERSION[SchemaStore.RUNS]
+
+# EAV lane struct — the nested at-rest representation of one input / output
+# entry. ``value_type`` selects which ``value_*`` lane holds the value. Field
+# names must match ``_row_helpers.LANE_FIELDS`` / the encoder (guarded below).
+_LANE_STRUCT = pa.struct(
+    [
+        ("name", pa.string()),
+        ("value_type", pa.string()),
+        ("value_int", pa.int64()),
+        ("value_double", pa.float64()),
+        ("value_bool", pa.bool_()),
+        ("value_text", pa.string()),
+        ("value_timestamp", pa.timestamp("us", tz="UTC")),
+        ("value_json", pa.string()),
+        ("unit", pa.string()),
+        ("uut_pin", pa.string()),
+    ]
+)
+assert [f.name for f in _LANE_STRUCT] == list(LANE_FIELDS), (
+    "schemas._LANE_STRUCT drifted from _row_helpers.LANE_FIELDS"
+)
+_LANE_LIST = pa.list_(_LANE_STRUCT)
+
+# Nested measurement struct — the at-rest representation of one measurement,
+# carried in the vector row's ``measurements`` LIST. Field names must match
+# ``_row_helpers.MEASUREMENT_STRUCT_FIELDS`` (guarded below). The daemon
+# UNNESTs these into the flat measurement fact at ingest.
+_MEASUREMENT_STRUCT = pa.struct(
+    [
+        ("name", pa.string()),
+        ("value", pa.float64()),
+        ("unit", pa.string()),
+        ("outcome", pa.string()),
+        ("timestamp", pa.timestamp("us", tz="UTC")),
+        ("limit_low", pa.float64()),
+        ("limit_high", pa.float64()),
+        ("limit_nominal", pa.float64()),
+        ("limit_comparator", pa.string()),
+        ("characteristic_id", pa.string()),
+        ("spec_ref", pa.string()),
+        ("uut_pin", pa.string()),
+        ("fixture_connection", pa.string()),
+        ("instrument_name", pa.string()),
+        ("instrument_resource", pa.string()),
+        ("instrument_channel", pa.string()),
+    ]
+)
+assert [f.name for f in _MEASUREMENT_STRUCT] == list(MEASUREMENT_STRUCT_FIELDS), (
+    "schemas._MEASUREMENT_STRUCT drifted from _row_helpers.MEASUREMENT_STRUCT_FIELDS"
+)
+_MEASUREMENT_LIST = pa.list_(_MEASUREMENT_STRUCT)
+
+# Instrument inventory struct — the at-rest representation of one instrument
+# connected during a run. Carried as a ``LIST<STRUCT>`` on every row
+# (dense, self-describing). The daemon UNNESTs these into the flat
+# ``instruments_materialized`` table for queries. Field names must match
+# ``_row_helpers.INSTRUMENT_STRUCT_FIELDS`` (guarded below).
+_INSTRUMENT_STRUCT = pa.struct(
+    [
+        ("name", pa.string()),
+        ("id", pa.string()),
+        ("driver", pa.string()),
+        ("resource", pa.string()),
+        ("protocol", pa.string()),
+        ("manufacturer", pa.string()),
+        ("model", pa.string()),
+        ("serial_number", pa.string()),
+        ("firmware", pa.string()),
+        ("cal_due", pa.string()),
+        ("cal_last", pa.string()),
+        ("cal_certificate", pa.string()),
+        ("cal_lab", pa.string()),
+        ("mocked", pa.bool_()),
+    ]
+)
+assert [f.name for f in _INSTRUMENT_STRUCT] == list(INSTRUMENT_STRUCT_FIELDS), (
+    "schemas._INSTRUMENT_STRUCT drifted from _row_helpers.INSTRUMENT_STRUCT_FIELDS"
+)
+_INSTRUMENT_LIST = pa.list_(_INSTRUMENT_STRUCT)
+
+# Canonical row schema for the unified per-run parquet — a chronological
+# telling of the run. Every row carries an explicit ``record_type``
+# discriminator with one of three values:
+#   * ``record_type = 'run'`` — one row per run; run / UUT / station /
+#     environment context. Step / vector columns are NULL.
+#   * ``record_type = 'step'`` — one step-execution, keyed ``(step_path,
+#     step_retry, vector_outer_index)``; carries code identity + timing +
+#     rolled-up outcome, and its OWN ``inputs``/``outputs``/``measurements``
+#     (a non-looping step can have zero vector rows — the step row carries
+#     its own data, no synthesized scope vector). ``vector_index`` is always
+#     NULL on this row kind.
+#   * ``record_type = 'vector'`` — one condition-point execution carrier: a
+#     swept step's own sweep variant, or an in-body ``vectors`` loop
+#     iteration. Holds the ``inputs``/``outputs`` lanes and the nested
+#     ``measurements`` list for that execution; ``vector_index`` is its own
+#     0..N position.
+#
+# ``inputs`` / ``outputs`` are nested ``LIST<STRUCT<lanes>>`` columns (see
+# ``_LANE_STRUCT``), not wide ``in_*``/``out_*`` columns; the DuckDB daemon
+# UNNESTs them into the honestly-named ``inputs``/``outputs`` EAV tables (one
+# per role, no ``role`` column) for queries. ``measurements`` is a nested
+# ``LIST<STRUCT>`` on the vector row; the daemon UNNESTs it into the flat
+# measurement fact for queries.
+RUN_ROW_SCHEMA = pa.schema(
+    [
+        # Discriminator — 'run', 'step', or 'vector'
+        ("record_type", pa.string()),
+        # Identity & timing
+        ("session_id", pa.string()),
+        ("run_id", pa.string()),
+        ("site_index", pa.int64()),
+        ("site_name", pa.string()),
+        ("run_started_at", pa.timestamp("us", tz="UTC")),
+        ("run_ended_at", pa.timestamp("us", tz="UTC")),
+        ("step_name", pa.string()),
+        ("step_index", pa.int64()),
+        ("step_path", pa.string()),
+        ("step_started_at", pa.timestamp("us", tz="UTC")),
+        ("step_ended_at", pa.timestamp("us", tz="UTC")),
+        ("step_node_id", pa.string()),
+        ("step_module", pa.string()),
+        ("step_file", pa.string()),
+        ("step_class", pa.string()),
+        ("step_function", pa.string()),
+        ("step_markers", pa.string()),
+        # step_retry: 0-based outer (item) retry — pytest-rerunfailures rerun
+        # count of this step. Distinct from vector_retry (the inner per-vector
+        # retry). Both stamp every execution so a rerun is a distinct row.
+        ("step_retry", pa.int64()),
+        ("vector_index", pa.int64()),
+        ("vector_outer_index", pa.int64()),
+        ("vector_retry", pa.int64()),
+        ("vector_started_at", pa.timestamp("us", tz="UTC")),
+        ("vector_ended_at", pa.timestamp("us", tz="UTC")),
+        # Who
+        ("operator_id", pa.string()),
+        ("operator_name", pa.string()),
+        # UUT
+        ("uut_serial_number", pa.string()),
+        ("uut_part_number", pa.string()),
+        ("uut_revision", pa.string()),
+        ("uut_lot_number", pa.string()),
+        # Part
+        ("part_id", pa.string()),
+        ("part_name", pa.string()),
+        ("part_revision", pa.string()),
+        # Station
+        ("station_id", pa.string()),
+        ("station_name", pa.string()),
+        ("station_type", pa.string()),
+        ("station_location", pa.string()),
+        ("station_hostname", pa.string()),
+        # Fixture
+        ("fixture_id", pa.string()),
+        # Test context
+        ("test_phase", pa.string()),
+        ("project_name", pa.string()),
+        ("git_commit", pa.string()),
+        ("git_branch", pa.string()),
+        ("git_remote", pa.string()),
+        # Rollup
+        ("step_outcome", pa.string()),
+        ("vector_outcome", pa.string()),
+        ("run_outcome", pa.string()),
+        # Environment traceability
+        ("python_version", pa.string()),
+        ("testerkit_version", pa.string()),
+        ("env_fingerprint", pa.string()),
+        # Dynamic attributes — nested EAV lanes (see _row_helpers). Names are
+        # values inside the structs, so there is no column explosion.
+        ("inputs", _LANE_LIST),
+        ("outputs", _LANE_LIST),
+        # Nested measurements on the vector row; the daemon UNNESTs these into
+        # the flat measurement fact at ingest.
+        ("measurements", _MEASUREMENT_LIST),
+        # Instrument inventory on every row (dense, self-describing); the daemon
+        # UNNESTs these into the flat ``instruments_materialized`` table.
+        ("instruments", _INSTRUMENT_LIST),
+    ],
+    # Stamp the schema itself with its version (like events' ``_IPC_SCHEMA``), so
+    # every table built with ``schema=RUN_ROW_SCHEMA`` carries the stamp by
+    # construction — the real write path overrides this metadata with the fuller
+    # ``_build_parquet_metadata`` dict (still schema_version), and fixtures that
+    # write directly are stamped automatically instead of silently unstamped.
+    metadata={b"schema_version": SCHEMA_VERSION.encode()},
+)
+
+_SCHEMA_DICT = {f.name: f.type for f in RUN_ROW_SCHEMA}
+
+
+def _infer_type_from_value(value: Any) -> pa.DataType:
+    """Infer Arrow type from a Python value. None → string (safe default)."""
+    if value is None:
+        return pa.string()
+    if isinstance(value, bool):
+        return pa.bool_()
+    if isinstance(value, (int, float)):
+        return pa.float64()
+    if isinstance(value, datetime):
+        return pa.timestamp("us", tz="UTC")
+    if isinstance(value, list):
+        return pa.list_(pa.string())
+    return pa.string()
+
+
+def _build_write_schema(rows: list[dict[str, Any]]) -> pa.Schema:
+    """Build complete Arrow schema: fixed canonical + dynamic columns.
+
+    Fixed columns (including the nested ``inputs``/``outputs`` lanes and
+    the ``instruments`` struct list) use ``RUN_ROW_SCHEMA`` types. Any other
+    stray column is inferred from its first non-None value. Passed to
+    ``pa.Table.from_pylist()`` so Arrow validates at construction time.
+
+    Single pass over rows to collect keys and first non-None values.
+    """
+    first_values: dict[str, Any] = {}
+    all_keys: set[str] = set()
+    for row in rows:
+        for k, v in row.items():
+            all_keys.add(k)
+            if k not in first_values and v is not None:
+                first_values[k] = v
+
+    fields: list[pa.Field] = []
+    used: set[str] = set()
+
+    # Fixed columns first, in canonical order
+    for field in RUN_ROW_SCHEMA:
+        if field.name in all_keys:
+            fields.append(field)
+            used.add(field.name)
+
+    # Remaining dynamic columns inferred from values
+    for key in sorted(all_keys - used):
+        fields.append(pa.field(key, _infer_type_from_value(first_values.get(key))))
+
+    # Carry the version stamp (as RUN_ROW_SCHEMA does), so tables built from this
+    # dynamic schema are stamped by construction. The real write path overrides
+    # with the fuller _build_parquet_metadata dict; direct writers are covered.
+    return pa.schema(fields, metadata={b"schema_version": SCHEMA_VERSION.encode()})
+
+
+def table_from_rows(rows: list[dict[str, Any]], schema: pa.Schema) -> pa.Table:
+    """Build a PyArrow Table from row dicts against ``schema``.
+
+    Wraps ``pa.Table.from_pylist`` so a build failure carries row context.
+    """
+    try:
+        return pa.Table.from_pylist(rows, schema=schema)
+    except (pa.ArrowInvalid, pa.ArrowTypeError, pa.ArrowNotImplementedError) as exc:
+        raise pa.ArrowInvalid(f"Cannot build measurement table from rows: {exc}") from exc

testerkit/data/subscribers/__init__.py

@@ -0,0 +1,48 @@
+"""Internal event-subscriber registry — used by the ``testerkit export``
+CLI replay path (csv/json/stdf/hdf5/tdms/mdf4 converters in
+:mod:`testerkit.data.exporters`). The canonical run materializer
+(parquet + DuckDB index) is owned by the runs daemon and does NOT
+go through this registry.
+
+Not a public extension protocol: third-party packages should not register
+formats via entry points or any other mechanism. The set of supported
+formats is fixed by the package and ships through ``testerkit export``.
+"""
+
+import testerkit.data.exporters.csv_exporter  # noqa: F401
+import testerkit.data.exporters.json_exporter  # noqa: F401
+from testerkit.data.event_log import EventSubscriber
+from testerkit.data.subscribers._base import get_subscriber_class, list_subscribers
+from testerkit.data.subscribers._output_file import OutputFile
+from testerkit.data.subscribers.replay import replay_to_subscriber
+
+# Optional industry-format subscribers — registered via ``__init_subclass__``
+# at import time when their respective extras are installed
+# (``testerkit[stdf]``, ``[hdf5]``, ``[tdms]``, ``[mdf4]``). When the
+# extra isn't installed the import fails; swallow so the rest of the
+# package still loads. The CLI surfaces a "format not registered" error
+# pointing at the right extra.
+try:
+    import testerkit.data.exporters.stdf  # noqa: F401
+except ImportError:
+    pass
+try:
+    import testerkit.data.exporters.hdf5  # noqa: F401
+except ImportError:
+    pass
+try:
+    import testerkit.data.exporters.tdms  # noqa: F401
+except ImportError:
+    pass
+try:
+    import testerkit.data.exporters.mdf4  # noqa: F401
+except ImportError:
+    pass
+
+__all__ = [
+    "EventSubscriber",
+    "OutputFile",
+    "get_subscriber_class",
+    "list_subscribers",
+    "replay_to_subscriber",
+]

testerkit/data/subscribers/_base.py

@@ -0,0 +1,20 @@
+"""Subscriber lookup functions.
+
+Registration is automatic via ``EventSubscriber.__init_subclass__``.
+Built-in subscribers are imported in ``__init__.py``.
+Third-party plugins are loaded via entry points.
+"""
+
+from __future__ import annotations
+
+from testerkit.data.event_log import EventSubscriber
+
+
+def get_subscriber_class(format_name: str) -> type[EventSubscriber] | None:
+    """Look up a subscriber class by format name."""
+    return EventSubscriber._registry.get(format_name)
+
+
+def list_subscribers() -> list[str]:
+    """Return sorted list of all registered subscriber format names."""
+    return sorted(EventSubscriber._registry)

testerkit/data/subscribers/_output_file.py

@@ -0,0 +1,25 @@
+"""OutputFile descriptor — metadata about a file produced by a subscriber.
+
+Transports use ``format`` to decide how to ship the file. The ``on_output``
+callback receives an ``OutputFile`` after each successful write.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class OutputFile:
+    """Describes a file produced by a subscriber.
+
+    Attributes:
+        path: Absolute path to the written file.
+        format: Format name (``"parquet"``, ``"csv"``, ``"stdf"``, etc.).
+        run_id: Run ID associated with the file, if known.
+    """
+
+    path: Path
+    format: str
+    run_id: str | None = None

testerkit/data/subscribers/replay.py

@@ -0,0 +1,55 @@
+"""Replay stored events through a subscriber — the post-hoc bridge.
+
+This replaces the old ``reconstruct_test_run → exporter.export()`` chain.
+Any subscriber can be fed stored events to produce its output format
+after the fact, without needing a live test session.
+
+Usage::
+
+    from testerkit.data.subscribers.replay import replay_to_subscriber
+    from testerkit.data.exporters.json_exporter import JsonSubscriber
+
+    sub = JsonSubscriber(output_dir=Path("out"))
+    replay_to_subscriber(sub, event_dicts)
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+from pydantic import TypeAdapter, ValidationError
+
+from testerkit.data.event_log import EventSubscriber
+from testerkit.data.events import Event
+
+_event_adapter: TypeAdapter[Any] = TypeAdapter(Event)
+
+
+def replay_to_subscriber(
+    subscriber: EventSubscriber,
+    events: list[dict[str, Any]],
+) -> None:
+    """Deserialize event dicts and feed them through a subscriber.
+
+    Args:
+        subscriber: An ``EventSubscriber`` instance (has ``open``,
+            ``on_event``, ``close``, and ``event_types``).
+        events: Raw event dicts, e.g. from ``EventLog.events()``
+            or ``EventStore.events(session_id=...)``.
+    """
+    subscriber.open()
+    try:
+        for raw in events:
+            try:
+                event = _event_adapter.validate_python(raw)
+            except ValidationError:
+                warnings.warn(
+                    f"Skipping invalid event: {raw.get('event_type', '?')}",
+                    stacklevel=2,
+                )
+                continue
+            if type(event) in subscriber.event_types:
+                subscriber.on_event(event)
+    finally:
+        subscriber.close()

testerkit/environment.py

@@ -0,0 +1,84 @@
+"""Environment snapshot for software traceability.
+
+Captures the Python runtime environment (version, OS, top-level dependencies)
+at test start.  Full package resolution is tracked by ``uv.lock`` in git;
+we store only the hash here for correlation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import platform
+from pathlib import Path
+
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+
+class EnvironmentSnapshot(BaseModel):
+    """Snapshot of the software environment at test time."""
+
+    python_version: str
+    os_name: str
+    os_version: str
+    platform_machine: str
+    testerkit_version: str
+    dependencies: list[str]
+    lockfile_hash: str | None = None
+
+
+def _read_top_level_deps() -> list[str]:
+    """Read direct dependencies from pyproject.toml [project.dependencies]."""
+    pyproject = Path("pyproject.toml")
+    if not pyproject.exists():
+        return []
+    try:
+        import tomllib
+    except ModuleNotFoundError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    try:
+        data = tomllib.loads(pyproject.read_text())
+        return sorted(data.get("project", {}).get("dependencies", []))
+    except Exception as exc:
+        logger.debug("Could not parse pyproject.toml: %s", exc)
+        return []
+
+
+def _hash_file(path: Path) -> str | None:
+    """SHA-256 prefix of a file, or None if missing/unreadable."""
+    try:
+        if path.exists():
+            return hashlib.sha256(path.read_bytes()).hexdigest()[:16]
+    except OSError as exc:
+        logger.debug("Could not read %s: %s", path, exc)
+    return None
+
+
+def capture_environment() -> EnvironmentSnapshot:
+    """Capture current environment snapshot.
+
+    Stores top-level dependencies from pyproject.toml (the ones you chose),
+    not the full transitive dependency tree.  ``lockfile_hash`` covers the
+    exact resolved versions; ``pyproject_hash`` covers the intent.
+    """
+    from testerkit import __version__
+
+    # Hash lockfile (uv.lock preferred, fallback to others)
+    lockfile_hash = None
+    for name in ("uv.lock", "poetry.lock", "Pipfile.lock", "requirements.txt"):
+        lockfile_hash = _hash_file(Path(name))
+        if lockfile_hash:
+            break
+
+    return EnvironmentSnapshot(
+        python_version=platform.python_version(),
+        os_name=platform.system(),
+        os_version=platform.release(),
+        platform_machine=platform.machine(),
+        testerkit_version=__version__,
+        dependencies=_read_top_level_deps(),
+        lockfile_hash=lockfile_hash,
+    )