@specific.dev/spectest 0.26.0 → 0.27.0

package/src/recorder.ts

@@ -1,817 +0,0 @@
-// 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
-   *  (reserved) or, absent a reservation, when it was recorded. */
-  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;
-  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";
-  /** 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;
-  /** 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;
-}
-
-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 };
-}