@specific.dev/spectest 0.39.0 → 0.41.0

package/src/recorder.ts

@@ -0,0 +1,846 @@
+// Per-test event recorder. The daemon installs a fresh recorder before
+// running a test case and drains it afterwards. While a recorder is
+// active, instrumented sites (the SDK's `expect`, the daemon's wrapped
+// `ctx.exec`, and the test-scoped `fetch` wrapper) push structured
+// events into it.
+//
+// When no test is running (production code paths, eval, etc.) the
+// current recorder is `null` and the `record*` helpers are no-ops, so
+// callers can invoke them unconditionally.
+
+import { clearPendingNullish } from "./inspect.js";
+
+const OUTPUT_SNIPPET_BYTES = 256 * 1024;
+
+export type TestEvent =
+  | ExecEvent
+  | AssertionEvent
+  | HttpEvent
+  | KubeEvent
+  | BrowserEvent
+  | DbEvent
+  | RedisEvent
+  | S3Event
+  | TerminalEvent
+  | TerminalStepEvent
+  | WaitEvent
+  | FakeEvent
+  | EnvEvent
+  | EmailEvent;
+
+interface BaseEvent {
+  /** Order of *start* within the test. Reserved when an op begins (see
+   *  `reserveEvent`), so an op whose nested children finish — and record —
+   *  before it does still sorts ahead of them. Ops that don't reserve get
+   *  their seq at record (= finish) time. */
+  seq: number;
+  /** Milliseconds since the recorder started, captured when the op *began* —
+   *  either reserved up front, or backdated at record time by an op that could
+   *  only reserve at finish (`reserveBackdated`). Consumers read the step's
+   *  completion time as `tOffsetMs + durationMs`, so an op that stamps a bare
+   *  finish offset while also reporting a duration will render late. */
+  tOffsetMs: number;
+  /**
+   * Optional grouping pointer. When set, this event was emitted inside
+   * a larger logical step (e.g. an HTTP call that fed the predicate of
+   * a `ctx.poll(...)`) and should render nested under the parent in
+   * timelines. The parent event is identified by its `seq`.
+   */
+  parentSeq?: number;
+}
+
+export interface ExecEvent extends BaseEvent {
+  kind: "exec";
+  service: string;
+  command: string;
+  /**
+   * Working directory the command ran from (`ctx.exec(svc, cmd, { cwd })`),
+   * if any. Kept off `command` so the sidebar shows just the command; the
+   * detail view surfaces it. Absent when the call used no `cwd`.
+   */
+  cwd?: string;
+  /**
+   * The payload piped to the command's stdin (`ctx.exec(svc, cmd, {
+   * stdin })`), truncated to OUTPUT_SNIPPET_BYTES. Recorded because the
+   * asciicast only captures what the command *wrote* — without this, a
+   * `kubectl apply -f -` step shows its error but not the manifest that
+   * caused it. Absent when the call piped nothing.
+   */
+  stdin?: string;
+  stdinTruncated?: boolean;
+  exitCode: number;
+  /** stdout truncated to OUTPUT_SNIPPET_BYTES. */
+  stdout: string;
+  stdoutTruncated: boolean;
+  stderr: string;
+  stderrTruncated: boolean;
+  durationMs: number;
+  /**
+   * Links this exec to the asciicast `TerminalSessionRecord` of its run
+   * (mirroring `TerminalEvent.sessionId`): one exec step covers one full
+   * CLI run, so the whole recording belongs to this event. Absent on
+   * events recorded before exec runs were captured.
+   */
+  sessionId?: string;
+}
+
+export interface AssertionEvent extends BaseEvent {
+  kind: "assertion";
+  /** Matcher name, e.g. "toBe", "toEqual". */
+  matcher: string;
+  /** Whether this was `expect(x).not.toBe(...)`. */
+  negated: boolean;
+  passed: boolean;
+  /** Best-effort JSON-safe serialization. */
+  actual: unknown;
+  expected?: unknown;
+  /** Failure message produced by the matcher (only when `passed` is false). */
+  error?: string;
+  /**
+   * Author-supplied label for the assertion. **Required** for a raw assertion
+   * (`expectRaw(value, message)`), where it renders as the summary
+   * ("ASSERT <message>") and serves as the diff-alignment key since a raw
+   * assertion has no provenance `path`. **Optional** for a provenance-linked
+   * `expect(value, message)`, where it leads the summary as a clarifying note
+   * alongside the rendered matcher/target. Absent when `expect(...)` was called
+   * without a message.
+   */
+  message?: string;
+  /**
+   * `seq` of the op (http / db / browser) whose return value this
+   * assertion drilled into. Set when `expect()` received a value wrapped
+   * by `inspect.wrap()`. The UI nests assertions with `sourceSeq` under
+   * the matching op; assertions without it render at top level.
+   */
+  sourceSeq?: number;
+  /** JSON-path of property accesses from the op return value down to
+   * the asserted value (e.g. `["body", "user", "name"]`). Empty for
+   * direct asserts on the op return itself. */
+  path?: string[];
+}
+
+export interface DbEvent extends BaseEvent {
+  kind: "db";
+  /** Service the query ran against (the key in `environment.services`). */
+  service: string;
+  /** SQL text. For tagged-template calls, values appear as `$1`, `$2`, … */
+  query: string;
+  /** Parameter values. Best-effort JSON-safe; large/binary values stringified. */
+  params?: unknown[];
+  /** Rows returned — or rows AFFECTED when `rowsAffected` is set. */
+  rowCount?: number;
+  /** Set when `rowCount` counts affected rows (a non-RETURNING
+   *  INSERT/UPDATE/DELETE) rather than a result set — rendered as
+   *  "N affected" so an `UPDATE → 0 rows` can't read as "nothing updated". */
+  rowsAffected?: boolean;
+  /** Captured rows for table rendering in the web UI. Capped at
+   *  MAX_DB_ROWS; `rowsTruncated` is set when there were more. */
+  rows?: unknown[];
+  rowsTruncated?: boolean;
+  /** Column names in the order Bun.SQL returned them. Derived from the
+   *  first captured row, so omitted when no rows. */
+  columns?: string[];
+  durationMs: number;
+  /** Set if the driver threw. */
+  error?: string;
+}
+
+/**
+ * One Redis/Valkey command issued through the instrumented {@link
+ * "../redis".RedisClient} (a drop-in for `Bun.RedisClient` / `Bun.redis`).
+ *
+ * The return value is `wrap()`ped against this event's seq, so a later
+ * `expect(...)` that drills into it nests under this step in the timeline
+ * (same mechanism as http/db).
+ */
+export interface RedisEvent extends BaseEvent {
+  kind: "redis";
+  /** Label for the connection — the URL host (often the service name). */
+  service: string;
+  /** Command name, upper-cased (`GET`, `SET`, `HGETALL`, `PUBLISH`, …). */
+  command: string;
+  /** First argument — almost always the key the command targets. Surfaced
+   *  separately so the UI can read `GET session:42` at a glance. */
+  key?: string;
+  /** Remaining arguments (best-effort JSON-safe; large/binary stringified).
+   *  Omitted when there are none. */
+  args?: unknown[];
+  /** Reply, best-effort JSON-safe and capped. Omitted when the command threw
+   *  or returned `null`/`undefined`. */
+  result?: unknown;
+  resultTruncated?: boolean;
+  durationMs: number;
+  /** Set if the command threw. */
+  error?: string;
+}
+
+/**
+ * One object-storage operation through the instrumented {@link
+ * "../s3".S3Client} (a drop-in for `Bun.S3Client` / `Bun.s3`), covering both
+ * client-level calls (`write`/`delete`/`exists`/`list`/`presign`/`stat`) and
+ * the `S3File` handle `.file(path)` returns (`text`/`json`/`write`/…).
+ *
+ * The return value is `wrap()`ped against this event's seq, so `expect(...)`
+ * drilling into it nests under this step (same mechanism as http/db).
+ */
+export interface S3Event extends BaseEvent {
+  kind: "s3";
+  /** Operation: `write` | `read` | `delete` | `exists` | `list` |
+   *  `presign` | `stat`. */
+  op: string;
+  /** Bucket, when the client/handle knows it. */
+  bucket?: string;
+  /** Object key (path) the op targeted. Omitted for bucket-wide `list`. */
+  key?: string;
+  /** Bytes written or read, when known. */
+  size?: number;
+  /** Content type, when known (read/write/stat). */
+  contentType?: string;
+  /** Small text preview of the body (read/write of text), capped. */
+  preview?: string;
+  previewTruncated?: boolean;
+  /** For `list`: number of keys returned. */
+  count?: number;
+  durationMs: number;
+  /** Set if the op threw. */
+  error?: string;
+}
+
+export interface HttpEvent extends BaseEvent {
+  kind: "http";
+  method: string;
+  url: string;
+  /** Truncated to OUTPUT_SNIPPET_BYTES. Only set for non-binary text bodies. */
+  requestBody?: string;
+  requestBodyTruncated?: boolean;
+  status?: number;
+  responseBody?: string;
+  responseBodyTruncated?: boolean;
+  durationMs: number;
+  /** Set if the request threw (network error, abort, etc.). */
+  error?: string;
+}
+
+/**
+ * A Kubernetes API call (from `ctx.svc.<k3s>.client.*` / `apply(...)`).
+ *
+ * The k3s component routes the kube client through `globalThis.fetch`, so
+ * the daemon's fetch wrapper first records it as a plain `http` event;
+ * the component then parses the request path and *reclassifies* that event
+ * into this richer shape via `recorderAnnotate`, so the UI can show
+ * `verb resource/name` (e.g. `list pods · default`) instead of an opaque
+ * `GET https://k8s.internal:6443/api/v1/...`. The underlying HTTP fields
+ * are retained so the request/response bodies (the actual K8s objects)
+ * still render in the detail view, and `expect(...)` on the returned
+ * object nests under this event exactly as it does for `http`.
+ */
+export interface KubeEvent extends BaseEvent {
+  kind: "kube";
+  /** API verb derived from the HTTP method + path shape: `get` | `list` |
+   *  `watch` | `create` | `update` | `patch` | `delete` |
+   *  `deletecollection`. */
+  verb: string;
+  /** API group — `""` for the core group (`/api/v1`), else e.g. `"apps"`,
+   *  `"networking.k8s.io"`. */
+  group?: string;
+  /** API version, e.g. `"v1"`. */
+  apiVersion?: string;
+  /** Resource plural, e.g. `"pods"`, `"deployments"`, `"ingresses"`. */
+  resource?: string;
+  /** Subresource, when addressed, e.g. `"status"`, `"scale"`, `"log"`. */
+  subresource?: string;
+  /** Object name, when the request targets a single object. */
+  name?: string;
+  /** Namespace, when namespaced. Absent for cluster-scoped requests. */
+  namespace?: string;
+  // Underlying HTTP fields, retained for drill-down (mirror HttpEvent).
+  method: string;
+  url: string;
+  requestBody?: string;
+  requestBodyTruncated?: boolean;
+  status?: number;
+  responseBody?: string;
+  responseBodyTruncated?: boolean;
+  durationMs: number;
+  error?: string;
+}
+
+/**
+ * One call to a fake's helper function (`ctx.fakes.<name>.<fn>(...)`).
+ * Helpers are user-authored functions that read or mutate the fake's
+ * private state, so this is the only window into what a test asked the
+ * fake — distinct from the `http` events the *app under test* generates
+ * when it actually calls the fake's endpoints.
+ *
+ * The return value is `wrap()`ped against this event's seq, so a later
+ * `expect(...)` that drills into it nests under this step in the
+ * timeline (same mechanism as http/db/exec).
+ */
+export interface FakeEvent extends BaseEvent {
+  kind: "fake";
+  /** Fake name — the key in `ctx.fakes`. */
+  fake: string;
+  /** Helper function called, e.g. `"lastCharge"`. */
+  member: string;
+  /** Call arguments (best-effort JSON-safe). */
+  args?: unknown[];
+  /** Return value (best-effort JSON-safe). Omitted when the helper threw
+   *  or returned `undefined`. */
+  result?: unknown;
+  durationMs: number;
+  /** Set if the helper threw. */
+  error?: string;
+}
+
+/**
+ * One captured email, as embedded on an {@link EmailEvent}. The HTML and
+ * text bodies ride along (truncated to the output cap) so the dashboard
+ * can render the actual email a test asserted against.
+ */
+export interface EmailEventMessage {
+  /** Sender address. */
+  from?: string;
+  /** Recipient addresses. */
+  to?: string[];
+  cc?: string[];
+  bcc?: string[];
+  subject?: string;
+  /** RFC date of the message, ISO-formatted. */
+  date?: string;
+  /** HTML body (truncated to the output cap). */
+  html?: string;
+  htmlTruncated?: boolean;
+  /** Plain-text body (truncated to the output cap). */
+  text?: string;
+  textTruncated?: boolean;
+  attachments?: { filename: string; contentType: string; size: number }[];
+}
+
+/** One row of a mailbox listing embedded on an {@link EmailEvent}. */
+export interface EmailEventSummary {
+  from?: string;
+  to?: string[];
+  subject?: string;
+  /** Plain-text preview of the body. */
+  snippet?: string;
+  date?: string;
+}
+
+/**
+ * One call to an email service's helpers (`ctx.svc.<name>.lastEmail(...)`
+ * etc.). Single-message ops embed the full captured message — including its
+ * HTML body — so timelines can render the email itself; listing ops embed
+ * compact summaries. The return value is `wrap()`ped against this event's
+ * seq, so `expect(...)` on it nests under this step (same mechanism as
+ * http/db/fake). Inside a `ctx.poll` predicate the event ride-alongs with
+ * the poll's iteration events: failed iterations get truncated, the winning
+ * one survives as a child of the `wait` event.
+ */
+export interface EmailEvent extends BaseEvent {
+  kind: "email";
+  /** Service key of the mail server (`ctx.svc.<service>`). */
+  service: string;
+  /** Helper called, e.g. `"lastEmail"`. */
+  op: string;
+  /** Human-readable match criteria, e.g. `to alice@example.com`. */
+  query?: string;
+  /** Number of matching messages (listing ops / mailbox size on error). */
+  count?: number;
+  /** The captured message (single-message ops). */
+  message?: EmailEventMessage;
+  /** Message summaries (listing ops). */
+  messages?: EmailEventSummary[];
+  durationMs: number;
+  /** Set if the op threw (e.g. the mail server's query API failed). */
+  error?: string;
+}
+
+/**
+ * A runtime mutation of the environment — `ctx.startService` /
+ * `ctx.stopService` / `ctx.dnsName`, whether called from a test or from a
+ * fake handler reacting to the app under test. Distinct from the `http`
+ * event the app generates when it calls the fake: this is the
+ * infrastructure the fake (or test) created in response. No-op outside a
+ * running test (bootstrap / project-setup / eval), same as every record*.
+ */
+export interface EnvEvent extends BaseEvent {
+  kind: "env";
+  /** Which environment primitive ran. */
+  op: "startService" | "stopService" | "dnsName" | "certificate";
+  /** SANs of a minted leaf (certificate). */
+  hostnames?: string[];
+  /** Service name (startService / stopService). */
+  service?: string;
+  /** Image reference started (startService). */
+  image?: string;
+  /** Resolved IP — the new container's (startService) or the target's (dnsName). */
+  ip?: string;
+  /** Hostname registered (dnsName). */
+  hostname?: string;
+  durationMs: number;
+  /** Set if the op threw. */
+  error?: string;
+}
+
+// A browser step's action label. Since the Playwright-native surface exposes
+// the full locator method vocabulary (click/fill/press/getAttribute/…) plus
+// the session verbs (goto/goBack/evaluate/waitForFunction/screenshot/…), this
+// is an open string rather than a closed union — the value is the Playwright
+// method name verbatim. Both renderers (control-plane web + CLI) treat it as
+// an opaque string with a generic `{action} <target>` fallback, so new method
+// names need no Rust change. Representative values: "goto", "goBack",
+// "goForward", "reload", "evaluate", "waitForFunction",
+// "click", "dblclick", "tap", "fill", "clear", "press", "type", "scroll",
+// "check", "hover", "textContent", "inputValue", "count", "screenshot".
+export type BrowserAction = string;
+
+export interface BrowserEvent extends BaseEvent {
+  kind: "browser";
+  action: BrowserAction;
+  /** Target URL (navigate). */
+  url?: string;
+  /** CSS selector (click, scrollTo). */
+  selector?: string;
+  /** Human-readable label for `evaluate` ops. */
+  description?: string;
+  /** Evaluated script, truncated. */
+  script?: string;
+  scriptTruncated?: boolean;
+  /** Typed text, truncated. */
+  text?: string;
+  textTruncated?: boolean;
+  /** Key name (press). */
+  key?: string;
+  /** Attribute name (getAttribute). */
+  attribute?: string;
+  /** Scroll/click coordinates. */
+  dx?: number;
+  dy?: number;
+  x?: number;
+  y?: number;
+  /** Screenshot image format. */
+  format?: string;
+  /** For `waitFor`: how many times the predicate was polled. */
+  attempts?: number;
+  durationMs: number;
+  error?: string;
+  /**
+   * Session this op belonged to. Set whenever the Browser was opened
+   * with a `BrowserSessionRecorder` attached (the daemon always does).
+   */
+  sessionId?: string;
+  /**
+   * Wall-clock `Date.now()` captured at the moment this op *finished*.
+   * Lives in the same time base as rrweb's `event.timestamp` fields,
+   * so the dashboard can seek the player by computing
+   * `event.timestamp - events[0].timestamp`. Using the post-op time
+   * (rather than op start) means clicking a "type 'foo'" step lands
+   * on the frame where the field already shows the text.
+   */
+  sessionTimestamp?: number;
+}
+
+/**
+ * Inline event for a single `ctx.terminal(...)` call. The heavy
+ * asciicast frames live separately on a `TerminalSessionRecord`
+ * (mirroring how `BrowserEvent` points at a `BrowserSessionRecord`).
+ * The UI shows this row in the step list and seeks the player to
+ * the session's start when clicked.
+ */
+export interface TerminalEvent extends BaseEvent {
+  kind: "terminal";
+  service: string;
+  command: string;
+  exitCode: number;
+  durationMs: number;
+  /** Links this event to its TerminalSessionRecord. */
+  sessionId: string;
+  /** PTY size used for the run. */
+  cols: number;
+  rows: number;
+  /** First N bytes of decoded output, for tooltip/inline preview. */
+  outputPreview: string;
+  outputTruncated: boolean;
+  /** Set if spawning the PTY itself failed. */
+  error?: string;
+}
+
+/** Action taken on an open interactive terminal session. */
+export type TerminalStepAction =
+  | "send"
+  | "sendLine"
+  | "press"
+  | "waitFor"
+  | "exit"
+  | "close";
+
+/**
+ * One operation on an open interactive terminal — analogous to
+ * `BrowserEvent`. The session's heavy asciicast frames live on the
+ * `TerminalSessionRecord`; this event just carries metadata so the
+ * step shows up in the timeline and the UI can seek the player.
+ */
+export interface TerminalStepEvent extends BaseEvent {
+  kind: "terminal-step";
+  /** Links this event back to its TerminalSessionRecord. */
+  sessionId: string;
+  /** Service the terminal is attached to (mirrors TerminalEvent.service). */
+  service: string;
+  /** Which Terminal method produced this event. */
+  action: TerminalStepAction;
+  /** Bytes sent (send/sendLine), truncated. */
+  text?: string;
+  textTruncated?: boolean;
+  /** Key name passed to `press`. */
+  key?: string;
+  /** Human label passed to `waitFor`. */
+  description?: string;
+  /** How many polls `waitFor` made. */
+  attempts?: number;
+  /** Whether `waitFor` matched (false means it timed out). */
+  matched?: boolean;
+  /** Exit code observed on `close`. */
+  exitCode?: number;
+  /** Rendered screen at the moment of the op (post-action), truncated. */
+  screenPreview: string;
+  screenTruncated: boolean;
+  /**
+   * Player-relative offset, in seconds, captured against the *same*
+   * clock the asciicast frames use (the terminal factory's spawn
+   * time). The UI seeks the asciinema-player to this value when the
+   * step is clicked. Persisting it directly avoids ever subtracting
+   * `step.tOffsetMs - session.openedAtMs` on the front-end, which is
+   * fragile because the two timestamps live in slightly different
+   * Date.now() frames (recorder vs. spawn).
+   */
+  castTimeSec: number;
+  durationMs: number;
+  error?: string;
+}
+
+/** An ordering slot claimed at op *start* and handed back to the matching
+ *  `record*` call at op finish. Lets a triggering op (an `exec`/`fetch` that
+ *  reaches the app, which calls a fake, which calls `ctx.startService`) keep a
+ *  lower seq than the nested events it sets off — even though those nested
+ *  events finish, and record, first. */
+export interface EventReservation {
+  seq: number;
+  tOffsetMs: number;
+}
+
+class Recorder {
+  private events: TestEvent[] = [];
+  private seq = 0;
+  private readonly start = Date.now();
+
+  /** Claim a seq + start offset now; pass the result to `push` at finish. */
+  reserve(): EventReservation {
+    return { seq: this.seq++, tOffsetMs: Date.now() - this.start };
+  }
+
+  push(
+    ev: Omit<TestEvent, "seq" | "tOffsetMs">,
+    reservation?: EventReservation,
+  ): number {
+    // A new op invalidates any pending nullish-leaf note: a note must not
+    // survive past the op it belongs to and get adopted by a later, unrelated
+    // `expect`. The assertion event itself is exempt — its `expect()` already
+    // adopted (and consumed) the note before recording.
+    if (ev.kind !== "assertion") clearPendingNullish();
+    const seq = reservation?.seq ?? this.seq++;
+    this.events.push({
+      ...ev,
+      seq,
+      tOffsetMs: reservation?.tOffsetMs ?? Date.now() - this.start,
+    } as TestEvent);
+    return seq;
+  }
+
+  drain(): TestEvent[] {
+    return this.events;
+  }
+
+  /** Index of the next event that would be pushed. Use with `truncate`
+   *  to drop everything pushed since this index. The seq counter does
+   *  not roll back — discarded seqs leave gaps. */
+  eventCount(): number {
+    return this.events.length;
+  }
+
+  /** Drop events with index >= `toLen`. The seq counter is unaffected
+   *  (so seqs already handed out remain unique even though the events
+   *  they named are gone). */
+  truncate(toLen: number): void {
+    if (toLen < this.events.length) {
+      this.events.length = toLen;
+    }
+  }
+
+  /** Stamp `parentSeq` onto every event at index >= `startIdx`. Used
+   *  by `ctx.poll` to group the kept iteration's events under the
+   *  resulting wait event. */
+  markChildren(startIdx: number, parentSeq: number): void {
+    for (let i = startIdx; i < this.events.length; i++) {
+      const ev = this.events[i]!;
+      if (ev.seq === parentSeq) continue;
+      ev.parentSeq = parentSeq;
+    }
+  }
+
+  /** Shallow-merge `patch` into the already-recorded event with this
+   *  `seq`. Lets an instrumentation site enrich or reclassify an event
+   *  after the fact — e.g. the k3s component upgrades the generic `http`
+   *  event its API call produced into a Kubernetes-specific `kube` event
+   *  once it has parsed the request. Searches from the end since the
+   *  target is almost always the most recent event. No-op when no event
+   *  carries that seq. */
+  annotate(seq: number, patch: Record<string, unknown>): void {
+    for (let i = this.events.length - 1; i >= 0; i--) {
+      const ev = this.events[i]!;
+      if (ev.seq === seq) {
+        Object.assign(ev, patch);
+        return;
+      }
+    }
+  }
+
+  /** Drop the single event carrying this `seq`. Used to retract an event
+   *  that an instrumentation site recorded but then decided is noise — e.g.
+   *  the dynamic kube client's internal discovery GET. Caller must ensure
+   *  nothing references the seq (no child events/assertions hang off it).
+   *  The seq counter does not roll back, so the seq stays retired. Searches
+   *  from the end since the target is almost always the most recent event. */
+  remove(seq: number): void {
+    for (let i = this.events.length - 1; i >= 0; i--) {
+      if (this.events[i]!.seq === seq) {
+        this.events.splice(i, 1);
+        return;
+      }
+    }
+  }
+}
+
+let current: Recorder | null = null;
+
+// Counter-based pause: `pauseRecording`/`resumeRecording` nest safely
+// (a nested `ctx.poll` inside another `ctx.poll`'s predicate stays
+// suppressed until its own resume balances out). Active record* sites
+// no-op while `paused > 0`, so http/exec/db/etc. inside a paused
+// region produce no events and the returned seq is `undefined` —
+// which means the daemon's fetch wrapper also skips installing the
+// inspector proxy on the Response.
+let paused = 0;
+
+export function pauseRecording(): void {
+  paused += 1;
+}
+
+export function resumeRecording(): void {
+  paused = Math.max(0, paused - 1);
+}
+
+function active(): boolean {
+  return current !== null && paused === 0;
+}
+
+export function startRecording(): void {
+  current = new Recorder();
+  paused = 0;
+}
+
+export function stopRecording(): TestEvent[] {
+  if (!current) return [];
+  const evs = current.drain();
+  current = null;
+  paused = 0;
+  return evs;
+}
+
+export function isRecording(): boolean {
+  return current !== null;
+}
+
+/** Reserve an ordering slot at the start of an op so nested events it triggers
+ *  (which finish — and record — first) still sort after it. Hand the returned
+ *  reservation to the matching `record*` call at op finish. Returns `undefined`
+ *  when nothing is recording, in which case `record*` falls back to allocating
+ *  the seq at record time. */
+export function reserveEvent(): EventReservation | undefined {
+  return active() ? current!.reserve() : undefined;
+}
+
+/** Reserve at op *finish* but backdate the offset by `elapsedMs` — for ops that
+ *  can't reserve up front because they only know they were an op once they're
+ *  done (the locator matchers: they poll silently and emit one settled step at
+ *  the end). Keeps `tOffsetMs` meaning "when the op started" for every kind,
+ *  which is what lets the dashboard render `tOffsetMs + durationMs` as the
+ *  step's completion time. Ordering is unaffected — the caller records
+ *  immediately, so the seq is the one it would have got anyway. */
+export function reserveBackdated(elapsedMs: number): EventReservation | undefined {
+  const resv = reserveEvent();
+  if (!resv) return undefined;
+  return { seq: resv.seq, tOffsetMs: Math.max(0, resv.tOffsetMs - Math.max(0, elapsedMs)) };
+}
+
+export function recordExec(
+  ev: Omit<ExecEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "exec", ...ev }, reservation) : undefined;
+}
+
+export function recordAssertion(
+  ev: Omit<AssertionEvent, "seq" | "tOffsetMs" | "kind">,
+): number | undefined {
+  return active() ? current!.push({ kind: "assertion", ...ev }) : undefined;
+}
+
+export function recordHttp(
+  ev: Omit<HttpEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "http", ...ev }, reservation) : undefined;
+}
+
+export function recordBrowser(
+  ev: Omit<BrowserEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "browser", ...ev }, reservation) : undefined;
+}
+
+export function recordDb(
+  ev: Omit<DbEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "db", ...ev }, reservation) : undefined;
+}
+
+export function recordRedis(
+  ev: Omit<RedisEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "redis", ...ev }, reservation) : undefined;
+}
+
+export function recordS3(
+  ev: Omit<S3Event, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "s3", ...ev }, reservation) : undefined;
+}
+
+export function recordTerminal(
+  ev: Omit<TerminalEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "terminal", ...ev }, reservation) : undefined;
+}
+
+export function recordTerminalStep(
+  ev: Omit<TerminalStepEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "terminal-step", ...ev }, reservation) : undefined;
+}
+
+export function recordFake(
+  ev: Omit<FakeEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "fake", ...ev }, reservation) : undefined;
+}
+
+export function recordEnv(
+  ev: Omit<EnvEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "env", ...ev }, reservation) : undefined;
+}
+
+export function recordEmail(
+  ev: Omit<EmailEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  return active() ? current!.push({ kind: "email", ...ev }, reservation) : undefined;
+}
+
+/**
+ * Recorded once per `ctx.poll(...)` call. Stands in for the suppressed
+ * intermediate iterations and gives downstream tagged values
+ * (`wrap(polledValue, waitSeq)`) a single, stable event to point at —
+ * assertions on those values then link to the wait, not to one of N
+ * dropped polls.
+ */
+export interface WaitEvent extends BaseEvent {
+  kind: "wait";
+  description: string;
+  attempts: number;
+  durationMs: number;
+  passed: boolean;
+  /** Set when the predicate threw or the wait timed out. */
+  error?: string;
+}
+
+export function recordWait(
+  ev: Omit<WaitEvent, "seq" | "tOffsetMs" | "kind">,
+  reservation?: EventReservation,
+): number | undefined {
+  // Use `current` directly (not `active()`) so a `recordWait` at the
+  // end of a `ctx.poll` block lands even though the surrounding code
+  // just resumed from `paused`. Pushing this event is the whole point
+  // of the poll primitive.
+  return current?.push({ kind: "wait", ...ev }, reservation);
+}
+
+/** Number of events the active recorder has accumulated. Returns 0
+ *  when no recorder is active. */
+export function recorderEventCount(): number {
+  return current?.eventCount() ?? 0;
+}
+
+/** Drop events with index >= `toLen` from the active recorder. */
+export function recorderTruncate(toLen: number): void {
+  current?.truncate(toLen);
+}
+
+/** Stamp `parentSeq` onto every event from `startIdx` onward, so the
+ *  UI groups them under the parent in the timeline. */
+export function recorderMarkChildren(
+  startIdx: number,
+  parentSeq: number,
+): void {
+  current?.markChildren(startIdx, parentSeq);
+}
+
+/** Shallow-merge `patch` into the active recorder's event with this
+ *  `seq` (enrich/reclassify after the fact). No-op when nothing is
+ *  recording or no event carries that seq. */
+export function recorderAnnotate(
+  seq: number,
+  patch: Record<string, unknown>,
+): void {
+  current?.annotate(seq, patch);
+}
+
+/** Retract the active recorder's event with this `seq` (an instrumentation
+ *  site recorded it, then decided it's noise). No-op when nothing is
+ *  recording or no event carries that seq. */
+export function recorderRemove(seq: number): void {
+  current?.remove(seq);
+}
+
+/** Best-effort JSON-safe deep clone; falls back to `String(v)`. */
+export function safeSerialize(v: unknown): unknown {
+  if (v === undefined) return undefined;
+  try {
+    return JSON.parse(JSON.stringify(v));
+  } catch {
+    return String(v);
+  }
+}
+
+export function truncateUtf8(s: string): { value: string; truncated: boolean } {
+  if (s.length <= OUTPUT_SNIPPET_BYTES) return { value: s, truncated: false };
+  return { value: s.slice(0, OUTPUT_SNIPPET_BYTES), truncated: true };
+}