testerkit 0.4.0__py3-none-any.whl

testerkit/_docs/concepts/data/event-sourcing.md

@@ -0,0 +1,76 @@
+# Event sourcing
+
+The platform stores test execution data as an immutable, append-only log of events. The queryable Run / Step / Measurement views (parquet, DuckDB index) are *views built from* that log — derived from the events, rebuildable at any time, never the source of truth themselves.
+
+The companion pages cover the **what**: [Event log](event-log.md) for the event-type taxonomy and dispatch; [Data stores](data-stores.md) for the on-disk layout of events, channels, files, and the run parquet. This page covers the **why** — what a traditional CRUD test-result schema (one where you create a run row and update it in place) forces on a platform, and what changes when you flip the model.
+
+## Why one mutable row is awkward for a live run
+
+A traditional test-result schema models a Run as a single row, with steps and measurements as child rows in a hierarchy. To record what happened, you have one of two options, each with a real cost:
+
+**Option A — UPDATE-style.** Insert the run row at start (with `outcome=NULL, ended_at=NULL`), then UPDATE both fields when the run finishes. Simple, but updating a live row in place brings race conditions when something reads it mid-update, audit-trail difficulties (when did the row become `passed`?), and a category of bugs where consumers see partially-updated state.
+
+**Option B — Post-processing stance.** Buffer everything in memory until the run ends, then INSERT the whole hierarchy in one transaction. No live visibility during the run; total data loss if the producer crashes mid-flight.
+
+Both shapes force the schema to be the source of truth, which means one row has to represent both "the run is in progress" and "the run is finished" — and that's what forces the in-place updates.
+
+## The inversion: events as primary, runs as projections
+
+TesterKit emits a separate immutable event for each thing that happens: `RunStarted`, `StepStarted`, `MeasurementRecorded`, `StepEnded`, `RunEnded`. The event log is the source of truth. The Run/Step/Measurement views (parquet, DuckDB index) are derived projections — regenerable from the events at any time.
+
+Most data systems treat the entity (Run) as primary and the audit log (events) as a secondary concern. TesterKit inverts that: events are primary, the entity is a projection. That single inversion is what sidesteps the whole problem. Nothing ever needs an UPDATE because the view isn't authoritative — it's rebuilt from the events.
+
+## Properties that fall out
+
+- **Live visibility during a run.** The UI subscribes to the event log and surfaces in-progress runs as events arrive. No "wait for end" behavior, no NULL outcomes in queries.
+- **Crash recovery is automatic.** A producer that crashes mid-run leaves a `RunStarted` event with no matching `RunEnded`. The orphan-finalization path emits a synthetic `RunEnded(aborted)` and the view rebuilds normally. No partially-written run row to reconcile.
+- **Replay is free.** Want a new analytical view three years from now — different schema, new format, additional aggregations? Replay the event log into a new projection. Traditional CRUD requires migration scripts; here it's just consumption.
+- **Audit log = primary data path.** Some regulated industries (medical, aerospace, defense) require immutable audit trails of test runs. In CRUD systems that's a parallel write you bolt on; here it's the architecture.
+- **Time-travel queries are natural.** "What did the system know at 14:32:17?" is just `WHERE occurred_at <= '14:32:17'` grouped by `run_id`. CRUD systems need temporal-database extensions to answer that.
+- **Cross-system correlation comes for free.** An async temperature probe doesn't have to be a first-class participant in execution. It writes channel samples (or emits events) on its own schedule; any consumer can correlate against any time window. Producers don't have to know each other exist — that's a property of log-based architectures that integration-by-database can't get.
+- **Composable consumers.** New analytics view, new format, new dashboard? Subscribe to (or replay) the event log and build your own view. The producer side doesn't change.
+
+## The principled split
+
+Not everything is event-sourced — that would be the wrong shape for some data. TesterKit splits along a clean line:
+
+| Data shape | Pattern | Why |
+|---|---|---|
+| Configuration (`testerkit.yaml`, `station.yaml`, parts, catalog) | CRUD via YAML, hand-edited | Operators evolve them deliberately over time |
+| Test execution data (runs, steps, measurements, events) | Append-only events → derived projections | Immutable historical record |
+| Channel sample data (high-rate time-series) | Append-only sample streams (event log carries metadata) | Same domain semantics, different physics — too large for the event log |
+
+Configuration *should* be mutable: you add a station, change a limit, update a part spec. Execution data *shouldn't* be mutable: a run happened on a date with an outcome, and that doesn't change. Channel data is execution data with a size exception — sample streams at kHz–MHz rates can't fit through the event log, so they get their own append-only log with event-log metadata referencing them.
+
+Annotations, retroactive flags, and RMA links don't break this — they're "new facts about old runs," not edits. The event-sourced answer is to emit a new event type for the new fact (e.g. a future `RunFlagged` or `MeasurementAnnotated`) and let projections incorporate it. You're not mutating the past, you're recording new observations about it.
+
+## Materializers run in whatever process cares
+
+In a CRUD world, "the database" is a single shared mutable structure every consumer reads and writes against. In an event-sourced world, the *events* are the shared contract — and each consumer can run *its own* materializer in *its own* process, on whatever cadence makes sense for that consumer. Different processes can care about different projections without coordinating.
+
+That's why TesterKit's materializers take the shape they do:
+
+- The runs daemon cares about an always-on, queryable view of recent runs, so it runs as a long-lived consumer: it collects events per in-flight run and, on `RunEnded`, writes the canonical per-run parquet. It also takes over for runs whose runner crashed. Same view, different trigger.
+- Each exporter (CSV, JSON, HDF5, STDF, …) replays events after the fact via `testerkit export`, each in its own process at whatever cadence the operator invokes.
+- Any future consumer — a Grafana exporter, a Snowflake pipeline, an analytics view — would run its own materializer in its own process at whatever cadence it likes (per-event, per-run, batched hourly). Sync or async, in-process or out, ephemeral or long-running — those are local choices, not architectural commitments.
+
+There's no "the materialization service" everyone has to wait on, no central writer that becomes a bottleneck. Each consumer's timing is local to its process; from the system's perspective they're all running independently, all deriving their own views from the same shared event log. That's the property that makes log-based architectures composable without coordination.
+
+## Trade-offs
+
+- **Eventual consistency on projections.** Between event emission and projection materialization there's a window where queries see stale data. For test execution this window is short (per-event for live views; end-of-run for the canonical parquet) and the live event view fills the gap, but it's a real property to be aware of.
+- **More upfront design work.** You have to choose event types deliberately. Adding a new dimension means adding an event field (additive, fine) or a new event class (also fine). But the design conversation is heavier than "add a column."
+- **Harder mental model for newcomers.** Most developers expect to query a `runs` table directly. The "events are primary, this query hits a projection" framing requires explanation. This page is part of paying that tax.
+
+## See also
+
+**Same topic, other quadrants:**
+
+- [Reference → Event types](../../reference/data/event-types.md) — every event class the runtime emits, generated from source
+- [Reference → Parquet schema](../../reference/data/parquet-schema.md) — the materialized projection's column-level reference
+- [How-to → Export results](../../how-to/data/export-results.md) — exporters as event-replay consumers (one materializer per format)
+
+**Sibling concepts:**
+
+- [Event log](event-log.md) — the *what*: event types, dispatch, durability
+- [Data stores](data-stores.md) — events / channels / files / run projection; on-disk layout, `data_dir` resolution, schema-evolution contract

testerkit/_docs/concepts/data/flight-streaming.md

@@ -0,0 +1,58 @@
+# Flight Cross-Process Model
+
+TesterKit uses Apache Arrow Flight for cross-process data access. This enables real-time queries from any process — the operator UI, CLI tools, AI agents, or Grafana — without file locking or polling.
+
+## Why Arrow Flight
+
+Arrow Flight provides:
+
+- **Zero-copy** — Arrow record batches transfer between processes without being copied or re-encoded, so live queries stay fast even with a lot of data
+- **Cross-process** — Multiple processes query the same data through a shared background service
+- **Language-agnostic** — Any Arrow Flight client (Python, Go, Rust, Java) can connect
+- **SQL queryability** — [DuckDB](https://duckdb.org/) (an embedded analytical SQL engine that reads Parquet/Arrow directly) runs as the query engine behind the service
+
+Reading the files directly from each process works, but processes can collide on file locks, and a reader can't see data still buffered in memory — the shared background service avoids both.
+
+## How multiple processes see the same live data
+
+```mermaid
+flowchart LR
+    A["pytest run"] -->|write + read| svc["Shared background service"]
+    B["testerkit serve / UI"] -->|read| svc
+    C["testerkit runs / your script"] -->|read| svc
+    svc --> disk["Persistent index on disk"]
+    svc --> live["Live in-memory overlay\n(in-progress runs)"]
+```
+
+Your pytest run, `testerkit serve`, `testerkit runs`, and any script you write all talk to the same shared background service. The service keeps data in two places: a persistent index on disk (a DuckDB file) and a live in-memory overlay for in-progress runs. The overlay is what lets a query see a result the instant after it's written — before the run is even complete.
+
+The first tool that needs the data starts the shared background service automatically; everything else just connects to it. You never manage it yourself. The service shuts itself down after it has been idle for a while.
+
+## On disk and live at the same time
+
+The event data uses a dual-write pattern for crash safety and instant queryability:
+
+1. **Arrow files on disk** — append-only, survive crashes. Date-partitioned, with one file per writing process.
+2. **Live push to the shared service** — new data is sent to the service as it's written, making it available for SQL queries immediately.
+
+If that live push fails, the data is still safe in the Arrow files on disk. On the next start, the service loads those files into the index and picks up where it left off.
+
+Event data and channel (waveform) data each have their own shared service — separate background processes running the same mechanism — so a heavy waveform capture doesn't compete with event queries.
+
+## Downsampling waveforms for display
+
+A captured waveform can have millions of samples — too many to plot. The `max_points` parameter thins it to a target count using LTTB (Largest Triangle Three Buckets), a downsampling algorithm that preserves peaks and dips so the displayed shape still matches the real signal.
+
+```python
+# Query with decimation for visualization
+table = channel_store.query(
+    "scope.ch1_waveform",
+    session_id="abc123",
+    max_points=1000,  # LTTB downsample to 1000 points
+)
+```
+
+## See also
+- [Event Log Architecture](event-log.md) — How events flow through the system
+- [Data stores](data-stores.md) — all four data stores
+- [Querying Channels Guide](../../how-to/data/querying-channels.md) — Practical channel queries

testerkit/_docs/concepts/data/index.md

@@ -0,0 +1,17 @@
+# Concepts — Data
+
+Where the run data lives and how the platform stays consistent across processes. The event log is the source of truth; everything else is a derived view.
+
+- [Event log](event-log.md) — the durable, append-only record of every test run; the source of truth
+- [Event sourcing](event-sourcing.md) — why the platform is event-sourced rather than mutation-based; what that buys you for replay, debugging, and audit
+- [Sessions](sessions.md) — connect-to-disconnect observation windows; how a single session can contain multiple runs (multi-UUT) or a long-running instrument session (operator UI, scripts)
+- [Three verbs](three-verbs.md) — `observe`, `verify`, `stream`; how the platform routes a measured value to the right store by shape
+- [Data stores](data-stores.md) — EventStore (events), ChannelStore (time-series), FileStore (artifacts), RunStore (run rows); on-disk layout, `data_dir` resolution, schema-evolution contract
+- [Flight streaming](flight-streaming.md) — cross-process data access via Apache Arrow Flight; why the platform uses it for low-latency queries
+
+## See also
+
+- [Reference → Event types](../../reference/data/event-types.md) — every event class the runtime emits, generated from source
+- [Reference → Parquet schema](../../reference/data/parquet-schema.md) — every column in the materialized run parquet
+- [Reference → Query API](../../reference/data/query-api.md) — `RunsQuery`, `StepsQuery`, `MeasurementsQuery` — the read path the UI and HTTP API both use
+- [How-to → Querying events](../../how-to/data/querying-events.md), [Querying channels](../../how-to/data/querying-channels.md), [Export results](../../how-to/data/export-results.md)

testerkit/_docs/concepts/data/sessions.md

@@ -0,0 +1,78 @@
+# Sessions as Observation Windows
+
+A session is the window from connect to disconnect — the time a process is actively using instruments and logging data.
+
+## What is a Session?
+
+A session begins when a process calls `connect()` and ends when the connection is released. During a session, all events share the same `session_id`, making it easy to group and query related activity.
+
+There's no sessions table. A session is simply every event that shares one `session_id` — TesterKit groups them when you query. It "begins" and "ends" because the first and last events (`SessionStarted` / `SessionEnded`) mark the boundaries.
+
+Sessions are broader than test runs. A single session might contain multiple test runs (e.g., retesting the same UUT), or no test runs at all (e.g., a calibration script or manual instrument exploration).
+
+## Session Metadata
+
+`SessionStarted` (see [event-log](event-log.md) for the full event list) records who ran it, on which station, and how (pytest, Jupyter, a script). Per-run context (UUT, part, test phase, git, environment) lives on `RunStarted`, emitted once per test run within the session.
+
+| Category | Fields |
+|----------|--------|
+| **Session** | `session_type` |
+| **Station** | `station_id`, `station_name`, `station_type`, `station_location`, `station_hostname` |
+| **Process** | `pid`, `client` (pytest, jupyter, script name) |
+| **Operator** | `operator_id`, `operator_name` |
+| **Fixture / site** | `fixture_id`, `site_count`, `site_names` |
+
+`RunStarted` (emitted once per test run within a session) carries the per-run context:
+
+| Category | Fields |
+|----------|--------|
+| **UUT** | `uut_serial_number`, `uut_part_number`, `uut_revision`, `uut_lot_number` |
+| **Part** | `part_id`, `part_name`, `part_revision` |
+| **Site** | `site_index`, `site_name` |
+| **Test context** | `fixture_id`, `test_phase`, `project_name` |
+| **Git** | `git_commit`, `git_branch`, `git_remote` |
+| **Environment** | `environment_json` (Python version, testerkit version, top-level deps, lockfile hash) |
+| **Custom** | `custom_metadata` dict |
+
+Config files (station, fixture, part spec) are tracked via git — the `git_commit` field on each `RunStarted` identifies the exact code and config state.
+
+## Why Sessions Exist
+
+Sessions solve three problems:
+
+1. **Grouping events across runs** — Multiple test runs on the same UUT during one sitting share a session. You can query "everything that happened while bench-7 was connected" without knowing individual run IDs.
+
+2. **Live monitoring** — The operator UI subscribes to events by `session_id` to show real-time progress. The session boundary tells the UI when to start and stop monitoring.
+
+3. **Resource coordination** — Sessions track which instruments are in use, enabling per-resource locking. Two scripts can use different instruments on the same station simultaneously.
+
+## The `connect()` API
+
+```python
+from testerkit import connect
+
+# Using a `with` block (scripts, notebooks)
+with connect("cell-7", mock=True) as station:
+    dmm = station.instrument("dmm")
+    v = dmm.measure_voltage()
+    # All interactions logged with this session's ID
+
+# Explicit start/stop (UI, long-running processes)
+station = connect("cell-7")
+station.start()
+dmm = station.instrument("dmm")
+# ... work ...
+station.stop()
+```
+
+`connect()` starts a session that:
+- gets a new `session_id`
+- emits `SessionStarted` with full context
+- locks each instrument it uses, so two scripts can share a station
+- emits `SessionEnded` when it closes
+
+## See also
+- [Event Log Architecture](event-log.md) — How events are stored and queried
+- [Data stores](data-stores.md) — where the events behind a session are stored
+- [connect() reference](../../reference/runtime/connect.md) — full API surface
+- [Managing Sessions Guide](../../how-to/execution/managing-sessions.md) — Practical session management

testerkit/_docs/concepts/data/three-verbs.md

@@ -0,0 +1,260 @@
+# The Three Test-Author Verbs
+
+Every value a test records plays one of three roles:
+
+| Role | What it means | Written by |
+|---|---|---|
+| `input` | What you set — a commanded value, setpoint, or condition | `context.configure("vin", 5.0)` |
+| `output` | What you read back — a response, environment reading, or captured artifact | `observe("v_rail", 3.3)` |
+| `measurement` | The judged result with limits and a pass/fail outcome | `verify("v_rail", 3.31, limit=…)` / `measure(…)` |
+
+The platform routes each call to the right store. You write the verb; the role follows automatically.
+
+`stream` is a fourth verb — for continuous signals — and is covered below. It does not add an input/output/measurement field to the vector; it writes to the channel timeline.
+
+## What `configure` does
+
+`context.configure` records the stimulus you commanded before the DUT responded:
+
+```python
+def test_load_regulation(psu, dmm, context):
+    context.configure("psu.voltage", 5.0, unit="V")   # → input role
+    context.configure("load.current", 1.0, unit="A")  # → input role
+
+    reading = dmm.measure_dc_voltage()
+    verify("vout", reading, limit=Limit(low=4.75, high=5.25, unit="V"))
+```
+
+The `input` values travel with the measurement row. When you query across runs, you can plot `vout` (measurement) against `psu.voltage` (input) to see load regulation without doing any joins.
+
+## What `observe` does
+
+`observe` records a value you read from the DUT or environment — the response side:
+
+```python
+observe("temp", temp_probe.read(), unit="°C")     # → output role
+observe("v_rail", dmm.measure_dc_voltage())        # → output role, scalar
+observe("scope_cap", scope.capture())              # → output role, Waveform
+```
+
+`observe` accepts any shape — the value's shape determines which store receives it:
+
+| Value shape | Routes to | How to query later |
+|---|---|---|
+| Scalar (`int` / `float` / `bool` / `str`) | Inline on the measurement row | `FieldRef.output("v_rail")` |
+| Array of scalars (list / ndarray) | ChannelStore | `/channels/{id}` chart panel |
+| `Waveform` (Y + `sample_interval`) | ChannelStore | `/channels/{id}` chart panel |
+| `XYData` (paired x/y arrays with per-axis units) | FileStore as `.npz` | `FieldRef.output("iv_curve")` → URI |
+| File / object (image / `bytes` / `Path` / Pydantic model) | FileStore (via a registered serializer) | `FieldRef.output("setup_photo")` → URI |
+
+The verb you call decides that a value is an output. The value's shape decides where the bytes land. The two choices are independent.
+
+## What `verify` and `measure` do
+
+`verify` records a judged result — the measurement proper:
+
+```python
+verify("rise_time_us", rise_time(wf), limit=Limit(low=0, high=20, unit="us"))
+# → measurement role: value, limits, outcome (PASSED / FAILED / ERRORED), unit
+```
+
+`measure` is the record-only sibling — it stamps `Outcome.DONE` and never raises on a missing limit:
+
+```python
+measure("rail_ripple", ripple(dmm.read_waveform()))
+# → measurement role, no limit check
+```
+
+Both are scalar-only. Passing a `Waveform`, array, or blob to `verify` or `measure` raises `TypeError` with a message pointing at the two-verb pattern: `observe` the evidence first, then `verify` the derived scalar.
+
+## Querying by role
+
+Because role is stored with every field, the query API lets you reference any field by its role and name — you don't have to guess a prefixed column name like `in_vin`:
+
+```python
+from testerkit.queries import MeasurementsQuery, FieldRef
+
+q = MeasurementsQuery()
+
+# Plot vout (measurement) vs vin (input) across runs
+rows = q.parametric(
+    y=FieldRef.measurement("vout"),
+    x=FieldRef.input("vin"),
+)
+
+# Plot temperature (output) vs date across runs
+rows = q.parametric(
+    y=FieldRef.output("temp"),
+    x="run_started_at",     # bare string = a built-in run column
+)
+
+# A bare string is measurement shorthand — the most common case
+rows = q.parametric(y="vout", x=FieldRef.input("vin"))
+```
+
+`FieldRef.input("vin")` / `FieldRef.output("v_rail")` / `FieldRef.measurement("vout")` are the three constructors. A bare string resolves to `FieldRef.measurement(name)` because measurements carry limits and outcomes — they're what analysis is overwhelmingly about. Inputs and outputs always require the explicit `FieldRef`.
+
+See [Reference → Query API](../../reference/data/query-api.md) for the full `MeasurementsQuery` surface.
+
+## Discrete vs continuous — where `stream` fits
+
+`observe` and `stream` both write to ChannelStore for array/waveform values. The difference is **intent**, not data shape:
+
+| | `observe` (discrete) | `stream` (continuous) |
+|---|---|---|
+| Unit of data | One call, one captured value | The channel itself; samples are unnamed appends |
+| Identity | Each call has a name and a vector context | The channel has a name; samples don't |
+| Role on the vector | `output` (for scalars / URIs) | None — stream doesn't add an input/output/measurement field |
+| T&M shape | Triggered acquisition, scope capture, snapshot | Live sensor feed, free-run, continuous monitor |
+
+**Rate doesn't decide. Intent does.** A 1-sample-per-5-minute temperature probe is continuous because the temperature is a signal that exists whether you sample it or not.
+
+- **Continuous → stream** — samples accumulate on the channel timeline; the channel as a whole is the unit you query later
+- **Discrete → observe** — each call is anchored to a specific moment in the test; queryable by `FieldRef.output(name)` for scalar outputs or URI navigation for waveforms
+
+What breaks if you mix them up:
+
+- `observe` in a high-rate loop → one event recorded per call (floods the event log), and the last call overwrites the previous output URI on scalar outputs
+- `stream` for a single discrete capture → no output stamped on the vector → can't navigate from the measurement to the supporting waveform without knowing the `channel_id` + time window
+
+To associate a streamed channel with a measurement vector, pass the sink to `observe`:
+
+```python
+with testerkit.channels.stream("scope.continuous") as cap:
+    for _ in range(n_samples):
+        cap.write(scope.read_trace())
+    observe("scope.snapshot", cap)   # stamps cap.uri as an output on the active vector
+```
+
+## Two layers — test-author verbs vs store-direct
+
+TesterKit exposes data writing at two layers:
+
+| Layer | Use when | Discrete | Continuous |
+|---|---|---|---|
+| **Test-author verbs** | Inside a test (has a vector context) | `observe(name, value)`, `verify(name, value, limit=…)` | `stream(name, sample)` |
+| **Store-direct** | Outside a test — notebooks, scripts, operator UI | `channels.write(name, sample)` | `channels.stream(name)` |
+
+The test-author verbs are built on top of the store-direct calls. What `observe` adds is recording the value's role and storage URI on the active test vector. None of that makes sense outside a test, so the store-direct surface skips it.
+
+`stream` does not associate with the vector automatically. Only `observe` stamps the vector. To associate a streamed channel with the active vector, pass the sink to `observe` as shown above.
+
+## Engineering units
+
+`configure`, `observe`, `verify`, `measure`, and `stream` all accept an optional `unit=` keyword across every call shape — top-level verb, pytest fixture, and `Context` method. The unit is stored alongside the value and is visible in query results:
+
+```python
+context.configure("psu.voltage", 12.0, unit="V")
+observe("temp", 24.8, unit="°C")
+stream("current", sample, unit="A")
+verify("output_voltage", dmm.measure_dc_voltage(), Limit(low=4.75, high=5.25, unit="V"))
+measure("quiescent_current", psu.measure_current(), unit="A")
+```
+
+For `verify`, the unit can come from `unit=` on the call, from `Limit(unit=)`, or from both when they agree. If both are provided and they differ, TesterKit raises `ValueError` immediately — it does not silently let one override the other.
+
+For multi-axis data (IV curves, S-parameter sweeps, optical spectra), use `XYData` — it carries `x_unit` and `y_unit` as separate per-axis fields:
+
+```python
+from testerkit.data.models import XYData
+
+iv = XYData(x=[0.0, 0.5, 1.0, 1.5], y=[0.0, 2.1, 4.3, 6.8],
+            x_unit="V", y_unit="mA", x_name="Bias", y_name="Current")
+observe("iv_curve", iv)   # → FileStore .npz; output URI on the vector
+```
+
+## Capturing evidence and judging a metric together
+
+The canonical pattern is `observe` for the raw evidence, then `verify` for the derived scalar:
+
+```python
+def test_psu_step_response(psu, scope, context):
+    psu.set_voltage(5.0)
+    wf = scope.capture()                               # block-mode acquisition
+
+    observe("scope_cap", wf)                           # Waveform → ChannelStore
+                                                        # output URI stamped on this vector
+
+    verify("rise_time_us", rise_time(wf),
+           limit=Limit(low=0, high=20, unit="us"))    # scalar → measurement row, judged
+    verify("overshoot_v", overshoot(wf),
+           limit=Limit(low=0, high=0.05, unit="V"))   # same vector, same scope_cap URI
+```
+
+Both `rise_time_us` and `overshoot_v` measurement rows carry the `scope_cap` channel URI. From any failing measurement on `/results/{run_id}` you can navigate directly to the supporting waveform.
+
+## Streaming continuously while the test runs
+
+For continuous capture across the test body, use the context-managed sink:
+
+```python
+import testerkit.channels
+
+with testerkit.channels.stream("scope.continuous") as cap:
+    for _ in range(n_samples):
+        cap.write(scope.read_trace())
+    observe("scope.snapshot", cap)   # stamps cap.uri as an output on the active vector
+```
+
+For byte-stream artifacts (video / audio / vendor capture), use `testerkit.files.stream`:
+
+```python
+import testerkit.files
+
+with testerkit.files.stream("camera", format="mp4") as cam:
+    for frame in camera.read_frames():
+        cam.write(frame)
+```
+
+`files.stream` requires `format=` — the platform cannot infer `mp4` vs `wav` vs `tdms` vs `raw` from opaque bytes. Every other dispatch (scalar vs array vs blob, ChannelStore vs FileStore, inline vs URI) is automatic.
+
+## How streams are stored — segmented per session, unified by channel
+
+A long-running stream is not one giant file. ChannelStore files are partitioned by date and by session:
+
+```
+data/channels/2026-06-03/env_temp_aaaa1111.arrow    ← Session A, day 1
+data/channels/2026-06-04/env_temp_aaaa1111.arrow    ← Session A, day 2
+data/channels/2026-06-03/env_temp_bbbb2222.arrow    ← Session B, day 1
+```
+
+The session boundary is the natural unit for retention, export, and crash isolation. The date partition keeps any single file from growing unbounded.
+
+The logical channel identity is not partitioned. `channels.query("env.temp")` with no session filter spans every session that wrote to that channel. Add `session_id=…` to scope a query to one session.
+
+## Concurrent sessions share instruments, not records
+
+If two test sessions run concurrently and both share a scope (locked atomically by the platform), their captures are isolated on disk:
+
+- ChannelStore: `session_id` is in the filename
+- FileStore: `session_id` is in the directory
+- EventStore: events from both sessions interleave on one timeline, but every event carries `session_id`
+- RunStore: one parquet file per run, never cross-run mixing
+
+The instrument lock orders captures in time; storage isolation is independent. The one shared thing is the channel-id namespace — `/channels/scope_cap` shows both sessions' data unless filtered. That's deliberate: cross-session views matter for trends and fixture-channel accumulation.
+
+## Custom types
+
+Unknown value types fall back to pickle with a `RuntimeWarning` that names the type and points at `register_serializer`. Register once and your type is auto-routed thereafter:
+
+```python
+from testerkit.data.files import register_serializer
+
+register_serializer(
+    MyInstrumentFrame,
+    extension=".bin",
+    mime="application/octet-stream",
+    write=lambda value, dest: dest.write_bytes(value.to_bytes()),
+)
+```
+
+Alternatively, implement `testerkit_serialize(dest: Path) -> Path` on your type — no registration call needed.
+
+## See also
+
+- [Data stores](data-stores.md) — where parquet, ChannelStore, and FileStore live on disk and how they relate
+- [Tutorial 11 — Waveforms and evidence](../../tutorial/11-waveforms-and-evidence.md) — pytest test with `observe` + `verify`
+- [Tutorial 12 — Continuous monitoring](../../tutorial/12-continuous-monitoring.md) — interactive session with `channels.stream` + live UI
+- [Reference → Query API](../../reference/data/query-api.md) — `MeasurementsQuery`, `FieldRef`, and the role-based query surface
+- [Reference → Parquet schema](../../reference/data/parquet-schema.md) — column conventions; `channel://` and `file://` URI formats
+- [Reference → Channels](../../reference/operator-ui/channels/list.md) — the operator UI page where ChannelStore samples appear

testerkit/_docs/concepts/execution/index.md

@@ -0,0 +1,13 @@
+# Concepts — Execution
+
+How a test run unfolds — the step model, what each step records, and how outcomes roll up from leaves to runs.
+
+- [Step hierarchy](step-hierarchy.md) — how test classes, methods, and parametrize vectors nest into a tree of step events
+- [Step manifest](step-manifest.md) — what each step records (inputs, outputs, measurements, retries) and how the platform turns events into parquet rows
+- [Outcomes](outcomes.md) — the severity ladder (`skipped` → `done` → `passed` → `failed` → `errored` → `terminated` → `aborted`) and how parent steps roll up child outcomes
+
+## See also
+
+- [How-to → Writing tests](../../how-to/execution/writing-tests.md) — task recipe for authoring test code that fits the step model
+- [Reference → Pytest fixtures](../../reference/pytest/fixtures.md) — the fixtures the step model exposes (`context`, `verify`, `measure`)
+- [Data](../data/index.md) — where step events and the materialized run go after execution