@demlik/tea 0.15.0 → 0.16.0

package/dist/chunk-7MGXQZPW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/flow/monitored-run/index.ts"],"names":[],"mappings":"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","file":"chunk-7MGXQZPW.js","sourcesContent":["/**\n * internal/flow/monitored-run — a long-running operation that is BOTH staged and\n * watched: an ordered stage pipeline whose POSITION survives eviction, wrapped\n * by a no-progress safety deadline and (optionally) a periodic durable\n * checkpoint.\n *\n * This is the merge of two field-guide concerns the audit-agent machine\n * hand-wired together (`seed/audit-agent-machine`): the OUTER pipeline position\n * (`RunStage` — planning → testing → summarizing → reporting, replayed on cold\n * wake by re-emitting the one outstanding effect) and the no-progress safety\n * alarm (`subs.ts`, keyed on `progressSeq` so every progress event retires the\n * old alarm and arms a fresh one). `monitored-run` lifts both into one config-\n * driven knob of plain functions (ADR 0022): `init()`, the verbs (`start` /\n * `advance` / `progress` / `onDeadline` / `boot` / `confirmSnapshot`),\n * `deadlines(state)` / `timer(state)`, and the checkpoint Cmd def\n * (`checkpoint`).\n *\n *   - It is **staged, optionally**. Omit `stages` and the run is single-shot:\n *     `start` enters `running`, `advance` finishes it to `done`. Provide\n *     `stages` and it becomes an ordered pipeline — each `advance` retires the\n *     current stage and claims the next, finishing to `done` only when the last\n *     stage is retired. The pipeline POSITION lives in the Model (a\n *     `work-queue` of stage items), so an eviction mid-pipeline resumes at the\n *     same stage via `boot` — the audit machine's \"pipeline position survives\n *     eviction\" property, generalized.\n *   - It is **watched**. While `running`, a no-progress deadline is armed at\n *     `lastProgressAt + deadlineMs` and keyed on `progressSeq`. Every\n *     `progress` / `advance` bumps the seq, so the substrate retires the old\n *     alarm and arms a new one — a self-rearming watchdog. If the alarm fires\n *     (`onDeadline`) the run goes `failed` with a deadline reason. Omit\n *     `deadlineMs` → no watchdog (the `stale` phase is never reachable).\n *   - It **checkpoints, optionally**. Provide `snapshotEvery` and every\n *     progress unit is accounted to a `../snapshot` slice; once the cadence is\n *     reached a `snapshot_write` Cmd is emitted (its handler is yours), so a\n *     crashed run restarts from the last durable checkpoint rather than from\n *     zero. Omit it → no checkpointing.\n *\n * ## Why the run lifecycle is INLINE (run-tracker not extracted)\n *\n * The phase union (`idle` / `running` / `stale` / `done` / `failed` / `cancelled`, a\n * discriminated union carrying only each phase's own data) and its bookkeeping\n * (`runId`, `startedAt`, `lastProgressAt`, `progressSeq`) live directly on this\n * slice rather than behind a `run-tracker` sub-knob.\n * Extraction earns its keep when two independent axes vary; here the lifecycle\n * has exactly one anchoring axis (this run), so a separate module would be a\n * premature seam. The two genuinely independent axes — the safety DEADLINE and\n * the periodic SNAPSHOT — ARE extracted (`../deadline`, `../snapshot`), and the\n * stage list is a `../work-queue` slice (`QueueItem<Stage>[]`) whose every\n * status flip is DELEGATED to the blessed `../work-queue/ops` (`enqueueOp` /\n * `claimNextOp` / `markDoneOp`) — never re-rolled here. The lifecycle is the\n * glue between them.\n *\n * ## The two non-negotiables (canon)\n *\n *   - **Durable** — the slice is plain data (the stage queue is a\n *     JSON-serializable `QueueItem<Stage>[]`, the snapshot slice is plain\n *     numbers), so it survives DO eviction / reload.\n *   - **Replayable** — every transition is a pure verb returning new state +\n *     Cmds; nothing here reads the clock or RNG. Time arrives as an `at` / `atMs`\n *     parameter. The knob ships no I/O.\n *\n * ## Typical wiring\n *\n *   const run = createMonitoredRun<MyStage, MyState>({\n *     stages: [\"plan\", \"test\", \"report\"],\n *     deadlineMs: 10 * 60_000,\n *     snapshotEvery: 25,\n *   });\n *\n *   cmds: [run.checkpoint],\n *   init: (loaded) => loaded ? [loaded, []] : [{ run: run.init() }, []],\n *   update: {\n *     begin:    (s, m) => lift(s, run.start(s.run, m.runId, m.at)),\n *     advance:  (s, m) => lift(s, run.advance(s.run, checkpoint(s), m.result, m.at)),\n *     progress: (s, m) => lift(s, run.progress(s.run, checkpoint(s), m.at)),\n *     deadline_exceeded: (s, m) => lift(s, run.onDeadline(s.run, m)),\n *     boot:     (s, m) => lift(s, run.boot(s.run, m.at)),\n *     snapshot_write_ok: (s, m) => [{ ...s, run: run.confirmSnapshot(s.run, m) }, []],\n *     snapshot_write_err: (s) => [s, []],\n *   },\n *   subs: [{ type: \"timer\", deps: (s) => run.timer(s.run) }],\n *\n *   // and where it runs — the checkpoint write is the handler you write (the\n *   // engine's `run` imported under another name, since `run` is the knob):\n *   runMachine(machine, {\n *     interpret: {\n *       snapshot_write: async (cmd, { ok, err }) => {\n *         try { await r2.put(cmd.key, cmd.payload); return ok(undefined); }\n *         catch (cause) { return err({ _tag: \"snapshot_write_failed\", cause }); }\n *       },\n *     },\n *   });\n */\n\nimport type { Cmd, TimerDeps } from \"../../../index\";\nimport {\n  createSnapshot,\n  type SnapshotSavedMsg,\n  type SnapshotState,\n  type SnapshotWriteCmd,\n} from \"../../persistence/snapshot\";\nimport {\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineSub,\n  nextTimer,\n} from \"../../resilience/deadline\";\nimport type { QueueItem } from \"../../work-queue\";\nimport { queueAdapter } from \"../../work-queue/adapter\";\n\n// ===========================================================================\n// Config — the knob. Every field optional; omit a field → omit its gate.\n// ===========================================================================\n\n/**\n * The monitored-run knob. EVERY field is optional:\n *   - omit `stages`       → single-shot run (no pipeline; one `advance` finishes).\n *   - omit `deadlineMs`   → no no-progress watchdog (the run is never auto-failed).\n *   - omit `snapshotEvery`→ no periodic checkpoint (no `snapshot_write` Cmds).\n *\n * An empty config `{}` is a valid single-shot, unwatched, uncheckpointed run.\n *\n * `Stage` is the consumer's stage identifier — any JSON-serializable value\n * (a string id, a `{ kind, ... }` record). It rides through the stage queue\n * unchanged so the consumer's reducer can branch on the current stage to emit\n * that stage's outstanding effect (the audit machine's `outstandingEffect`).\n */\nexport interface MonitoredRunConfig<Stage> {\n  /**\n   * The ordered stages of the pipeline. Position survives eviction (lives in\n   * the Model's stage queue). Omit for a single-shot run. An empty array is\n   * treated as single-shot too — there is nothing to pipeline through.\n   */\n  readonly stages?: readonly Stage[];\n  /**\n   * No-progress watchdog budget, in ms. The safety deadline is armed at\n   * `lastProgressAt + deadlineMs` and re-armed on every progress event. Omit\n   * for no watchdog.\n   */\n  readonly deadlineMs?: number;\n  /**\n   * Checkpoint cadence — write a durable snapshot once this many progress\n   * units have accumulated. Threaded straight into `../snapshot`'s `every`.\n   * Omit for no checkpointing.\n   */\n  readonly snapshotEvery?: number;\n  /**\n   * Store key the rolling checkpoint is written under. Forwarded to\n   * `../snapshot`'s `key`; defaults to that module's `@@snapshot`. Ignored\n   * when `snapshotEvery` is omitted.\n   */\n  readonly snapshotKey?: string;\n}\n\n// ===========================================================================\n// Slice — the Model field this knob owns. Run lifecycle INLINE + composed bricks.\n// ===========================================================================\n\n/**\n * Why a run terminated as `failed`. Discriminated so each reason carries only\n * its own data (pattern 11):\n *   - `deadline`  — the no-progress watchdog fired (`onDeadline`).\n *   - `stage`     — the consumer reported a stage failure via `advance(..., fail)`.\n *\n * `stale` is a SEPARATE phase (not a fail reason): a run is `stale` only by an\n * explicit consumer signal that progress has wedged WITHOUT the deadline having\n * fired — a soft, recoverable observation. The deadline firing is a hard\n * terminal (`failed { reason: \"deadline\" }`).\n *\n * The `stage` variant carries the FAILING STAGE VALUE (the `Stage` itself), not\n * a positional index: done stages leave the queue (`markDoneOp` filters them),\n * so a residual index drifts as the pipeline advances. The stage value is the\n * stable, meaningful identifier — `undefined` for a single-shot run (no stage).\n */\nexport type RunFailure<Stage> =\n  | { readonly reason: \"deadline\"; readonly at: number }\n  | {\n      readonly reason: \"stage\";\n      readonly stage: Stage | undefined;\n      readonly error: unknown;\n    };\n\n/**\n * The run bookkeeping every phase carries in common, split out so each arm of\n * the `MonitoredRunState` discriminated union names only the data it ADDS\n * (`runId` on started phases, `failure` on `failed`) — the same discipline the\n * sibling `PaginatorState` uses for its shared `seen` / `pages` counters. Plain\n * data end to end so the whole slice survives DO eviction / reload:\n *\n *   - `stepStates`     — the stage pipeline as a `work-queue` of stage items.\n *                        Empty for a single-shot run. The ONE `running` item is\n *                        the current stage; `done` items are retired stages\n *                        (they leave the queue via `markDoneOp`, so the queue\n *                        shrinks as the pipeline advances and is empty at\n *                        `done`). POSITION survives eviction because this list\n *                        is durable.\n *   - `startedAt`      — `at` of `start`. Observability; never compared in a verb.\n *   - `lastProgressAt` — `at` of the most recent progress event; the watchdog\n *                        base. Re-armed by `progress` / `advance`.\n *   - `progressSeq`    — monotonic progress counter; keys the safety alarm Sub\n *                        id so every bump retires the old alarm and arms a new\n *                        one (the audit subs' `safety:{progressSeq}` discipline).\n *   - `snapshot`       — the `../snapshot` slice (cadence counter + durable\n *                        watermark). Always present (uniform shape); the gate\n *                        is simply never driven when `snapshotEvery` is omitted.\n */\ninterface RunCore<Stage> {\n  readonly stepStates: readonly QueueItem<Stage>[];\n  readonly startedAt: number;\n  readonly lastProgressAt: number;\n  readonly progressSeq: number;\n  readonly snapshot: SnapshotState;\n}\n\n/**\n * The slice — a discriminated union on `phase` so each phase carries ONLY its\n * own data and impossible combinations are unrepresentable (pattern 11), the\n * same idiom the sibling `CircuitState` / `PaginatorState` / `RunFailure` follow:\n *\n *   - `idle`    — created but never started. Carries no `runId` (identity is\n *                 host-minted at `start`) and no `failure`: \"not started\" is its\n *                 OWN phase, not a `running` run wearing an empty-string `runId`\n *                 sentinel. `start` is the only transition out, so no verb has to\n *                 guard \"has this actually started?\" — `phase === \"idle\"` says it.\n *   - `running` — the run is live. Carries the host-minted `runId` and the\n *                 `RunCore` pipeline position + watchdog bookkeeping.\n *   - `stale`   — a soft \"no progress observed\" mark the consumer can set and\n *                 clear; still resumable (a `progress` clears it back to\n *                 `running`). Distinct from a fired deadline, which is terminal.\n *   - `done`    — every stage retired (or the single-shot `advance` landed).\n *   - `failed`  — terminal failure; the typed `failure` reason rides ONLY this\n *                 arm, so it is present iff `phase === \"failed\"` BY CONSTRUCTION —\n *                 there is no nullable side field to keep in sync.\n *   - `cancelled` — the consumer stopped the run from outside (`cancel`). Its own\n *                 phase rather than a `RunFailure` reason, on the same argument\n *                 that keeps `stale` a phase: a caller who asked for the stop did\n *                 not suffer a failure, and every \"did this fail?\" reader would\n *                 otherwise have to except one reason. Terminal, so it re-enters\n *                 no verb and arms no watchdog.\n *\n * `runId` is the host-minted run identity, stamped at `start` (the machine never\n * mints — see the audit seed's \"run identity is host-minted\"). It rides every\n * started phase, but not `idle`. `cancelled` is the one phase reachable from BOTH\n * sides of that line, so its `runId` is `string | null`: `null` says the run was\n * cancelled before it ever started and there was no identity to mint, which is a\n * different fact from a cancelled live run and stays a different value.\n */\nexport type MonitoredRunState<Stage> =\n  | (RunCore<Stage> & { readonly phase: \"idle\" })\n  | (RunCore<Stage> & { readonly phase: \"running\"; readonly runId: string })\n  | (RunCore<Stage> & { readonly phase: \"stale\"; readonly runId: string })\n  | (RunCore<Stage> & { readonly phase: \"done\"; readonly runId: string })\n  | (RunCore<Stage> & {\n      readonly phase: \"failed\";\n      readonly runId: string;\n      readonly failure: RunFailure<Stage>;\n    })\n  | (RunCore<Stage> & {\n      readonly phase: \"cancelled\";\n      readonly runId: string | null;\n      readonly at: number;\n    });\n\n/**\n * The live (still-timed) phases — `running` or `stale`. The verbs narrow to this\n * before touching the watchdog bookkeeping (`runId` / `progressSeq`), so a\n * settled (`done` / `failed` / `cancelled`) or never-started (`idle`) slice can never be bumped\n * — the narrow replaces the old `runId === \"\"` born-live guard.\n */\ntype LiveRun<Stage> = Extract<\n  MonitoredRunState<Stage>,\n  { readonly phase: \"running\" | \"stale\" }\n>;\n\n/**\n * The ENDED phases — a run that finished (`done`) or was stopped from outside\n * (`cancelled`). Every arm here was started or explicitly stopped, so `idle` is\n * out and `runId` is present on the whole union: a consumer holding one of these\n * reads the run identity without a `phase` guard the value can never fail.\n *\n * It is the resolved half of a drive: a promise that resolves only on an ended\n * run should say so in its type rather than resolve `MonitoredRunState` and\n * leave every reader to re-prove the `idle` arm impossible (#155). `cancelled`\n * keeps its `string | null` `runId` unchanged — a run cancelled before it ever\n * started genuinely has no identity, and that stays a different value here.\n */\nexport type EndedRun<Stage> = Extract<\n  MonitoredRunState<Stage>,\n  { readonly phase: \"done\" | \"cancelled\" }\n>;\n\n/**\n * The outcome a consumer reports to `advance`: the current stage either\n * succeeded (retire it, claim the next) or failed (terminate the run). Plain\n * data — the consumer parses its stage result at its own boundary and hands a\n * settled outcome here.\n */\nexport type StageResult =\n  | { readonly kind: \"ok\" }\n  | { readonly kind: \"fail\"; readonly error: unknown };\n\n// ===========================================================================\n// Cmd + Msg — re-exported from the composed bricks so consumers wire one import.\n// ===========================================================================\n\n/** The checkpoint-write Cmd, generic over the consumer's checkpoint value `V`. */\nexport type MonitoredRunCmd<V> = SnapshotWriteCmd<V>;\n\n/** The deadline Msg the safety alarm dispatches when the watchdog fires. */\nexport type MonitoredRunTimerMsg = DeadlineExceeded;\n\n// ===========================================================================\n// Deadline-id family. The safety alarm is keyed on `progressSeq` so a progress\n// event retires the old alarm and arms a new one (single-shot, re-armed by id\n// bump — the audit subs discipline).\n// ===========================================================================\n\nfunction safetyTimerId(runId: string, progressSeq: number): string {\n  return `monitored:safety:${runId}:${progressSeq}`;\n}\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build a monitored-run knob from `config`. `Stage` is the consumer's stage\n * identifier type; `V` is the consumer's checkpoint value type (what\n * `snapshotEvery` checkpoints). Returns the uniform L2 knob contract.\n *\n * No `rng` parameter: unlike `resilient-call`, nothing here jitters — the only\n * external inputs are time (an `at` / `atMs` parameter) and the consumer's\n * stage outcomes.\n */\nexport function createMonitoredRun<Stage, V = unknown>(\n  config: MonitoredRunConfig<Stage> = {},\n) {\n  const stages = config.stages ?? [];\n  const isPipeline = stages.length > 0;\n\n  // The stage-queue seam, bound once. Every stage status flip delegates to the\n  // `QueueAdapter` verbs (`wq.enqueue` / `wq.claim` / `wq.markDone`), so the\n  // `QueueItem<Stage>` shape stays insulated behind them.\n  const wq = queueAdapter<Stage>();\n\n  // The snapshot sub-knob is built only when `snapshotEvery` is configured;\n  // absence is `null` so the progress gate short-circuits to \"no checkpoint\".\n  // When present, the slice still carries a default SnapshotState so the shape\n  // is uniform across configs — the gate simply never records into it.\n  const snap =\n    config.snapshotEvery !== undefined\n      ? createSnapshot<V>({\n          every: config.snapshotEvery,\n          ...(config.snapshotKey !== undefined\n            ? { key: config.snapshotKey }\n            : {}),\n        })\n      : null;\n\n  // The snapshot knob to actually drive: `snap` when configured, else a single\n  // inert default (`every: 1`) bound ONCE here. Its `record` is never invoked\n  // (the progress gate short-circuits when `snap` is null), so the cadence value\n  // is immaterial — one shared stateless knob of pure functions stands in for\n  // the disabled-checkpoint case across init/boot/handlers.\n  const activeSnap = snap ?? createSnapshot<V>({ every: 1 });\n\n  /** The starting slice for a never-started run: the `idle` phase, no `runId`. */\n  function init(): MonitoredRunState<Stage> {\n    return {\n      phase: \"idle\",\n      stepStates: [],\n      startedAt: 0,\n      lastProgressAt: 0,\n      progressSeq: 0,\n      // A default snapshot slice even without the brick → uniform shape. When\n      // `snap` is null the inert `activeSnap` default supplies the slice; its\n      // `record` is never called, so the cadence value is immaterial.\n      snapshot: activeSnap.init(),\n    };\n  }\n\n  /**\n   * Seed the stage queue from the configured stages: every stage enqueued\n   * `pending`, then the first claimed `running`. `at` stamps the claim. PURE —\n   * the work-queue ops are pure array transforms; ids are positional (`stage:i`)\n   * so they are deterministic and replayable (no `crypto`, no `Math.random`).\n   */\n  function seedStages(at: number): readonly QueueItem<Stage>[] {\n    let queue: readonly QueueItem<Stage>[] = [];\n    stages.forEach((stage, i) => {\n      queue = wq.enqueue(queue, stage, at, `stage:${i}`).next;\n    });\n    // Claim the first stage as the running position. A non-empty pipeline always\n    // has a pending head here, so the claim succeeds.\n    const claimed = wq.claim(queue, at);\n    return claimed ? claimed.next : queue;\n  }\n\n  /** The current (running) stage item, or `undefined` for a single-shot run. */\n  function currentStage(\n    s: MonitoredRunState<Stage>,\n  ): QueueItem<Stage> | undefined {\n    return s.stepStates.find((i) => i.status === \"running\");\n  }\n\n  // === Verb: start =========================================================\n\n  /**\n   * Start (or restart) the run for `runId` at time `at`. Seeds the stage queue\n   * (if a pipeline) and enters `running` with the watchdog clock primed. Stamps\n   * `runId` from the host — the machine never mints (invariant: identity is\n   * host-minted, parsed at the boundary). PURE.\n   */\n  function start(\n    s: MonitoredRunState<Stage>,\n    runId: string,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    // Build the `running` arm explicitly rather than spreading `...s`: a restart\n    // from `failed` must NOT carry the old `failure` field forward (the `running`\n    // arm has none), and a start from `idle` has no `runId` to preserve. Only the\n    // snapshot slice threads through.\n    const next: MonitoredRunState<Stage> = {\n      phase: \"running\",\n      runId,\n      stepStates: isPipeline ? seedStages(at) : [],\n      startedAt: at,\n      lastProgressAt: at,\n      progressSeq: 0,\n      snapshot: s.snapshot,\n    };\n    return [next, []];\n  }\n\n  /**\n   * Bump the watchdog clock: set `lastProgressAt`/`progressSeq` so the safety\n   * alarm's id changes and the engine re-arms a fresh deadline. Shared by\n   * `progress` and `advance`. PURE.\n   */\n  function bumpProgress(s: LiveRun<Stage>, at: number): LiveRun<Stage> {\n    return { ...s, lastProgressAt: at, progressSeq: s.progressSeq + 1 };\n  }\n\n  /**\n   * Account one progress unit to the snapshot slice (when the brick is\n   * configured), returning the new slice + any checkpoint Cmd. `payload` is the\n   * consumer's checkpoint value to persist. PURE — `snap.record` is pure, the\n   * write is realized only when the runtime performs the emitted Cmd.\n   */\n  function recordSnapshot(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (snap === null) return [s, []];\n    const [snapshot, cmds] = snap.record(s.snapshot, payload, at);\n    // `snap.record` only ever emits `SnapshotWriteCmd<V>` (its sole Cmd), but\n    // its signature widens to `readonly Cmd[]`. Narrow back to this knob's\n    // precise Cmd union so a consumer's host Cmd type can stay exact.\n    return [{ ...s, snapshot }, cmds as readonly MonitoredRunCmd<V>[]];\n  }\n\n  // === Verb: progress ======================================================\n\n  /**\n   * Record forward progress: bump the watchdog (re-arming the safety alarm),\n   * clear any `stale` mark back to `running`, and account a snapshot unit\n   * (emitting a checkpoint Cmd on a cadence hit). A no-op unless the run is live\n   * (`running` / `stale`) — a late progress event on a settled (`done` /\n   * `failed`) or never-started (`idle`) run is ignored. PURE.\n   */\n  function progress(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    const bumped: MonitoredRunState<Stage> = {\n      ...bumpProgress(s, at),\n      phase: \"running\",\n    };\n    return recordSnapshot(bumped, payload, at);\n  }\n\n  // === Verb: markStale =====================================================\n\n  /**\n   * Mark the run `stale` — a soft \"no progress observed\" signal the consumer\n   * raises WITHOUT the deadline having fired (e.g. an upstream heartbeat gap).\n   * Recoverable: the next `progress` flips it back to `running`. A no-op unless\n   * the run is currently `running` (a settled run cannot go stale). Does NOT\n   * touch `progressSeq` — going stale is not progress, so the armed deadline\n   * keeps counting toward the hard terminal. PURE.\n   */\n  function markStale(\n    s: MonitoredRunState<Stage>,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\") return [s, []];\n    return [{ ...s, phase: \"stale\" }, []];\n  }\n\n  // === Verb: cancel ========================================================\n\n  /**\n   * Stop the run from outside and settle it `cancelled` at `at`. The durable half\n   * of an `AbortSignal`: the outcome is a phase in the slice, so a reload reads a\n   * run that ended rather than one to resume.\n   *\n   * Legal from `idle` too, not just the live phases — a signal already aborted\n   * when the run is asked for has to end it BEFORE `start`, and leaving it `idle`\n   * would let the next boot start the very run the caller stopped. That is the\n   * one arm where `runId` is `null`, built explicitly rather than spread so no\n   * stale `failure` or absent `runId` rides along.\n   *\n   * A no-op on a settled run (`done` / `failed` / `cancelled`): a terminal outcome\n   * is already the answer, and an abort landing after it must not overwrite it.\n   * That also makes a second abort idempotent. Emits no Cmd — cancelling issues no\n   * effect, and the in-flight ones it cannot recall are the consumer's to drain.\n   * PURE.\n   */\n  function cancel(\n    s: MonitoredRunState<Stage>,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"idle\" && s.phase !== \"running\" && s.phase !== \"stale\") {\n      return [s, []];\n    }\n    const next: MonitoredRunState<Stage> = {\n      phase: \"cancelled\",\n      runId: s.phase === \"idle\" ? null : s.runId,\n      at,\n      stepStates: s.stepStates,\n      startedAt: s.startedAt,\n      lastProgressAt: s.lastProgressAt,\n      progressSeq: s.progressSeq,\n      snapshot: s.snapshot,\n    };\n    return [next, []];\n  }\n\n  // === Verb: advance =======================================================\n\n  /**\n   * Advance the pipeline on a stage outcome:\n   *\n   *   - `result.kind === \"fail\"` → terminate `failed { reason: \"stage\" }`,\n   *     carrying the failing stage index + error. No further stages run.\n   *   - `result.kind === \"ok\"`:\n   *       - single-shot run → finish to `done` (and force a final checkpoint\n   *         when checkpointing, so the last durable snapshot is the terminal\n   *         state).\n   *       - pipeline → retire the current stage (`markDoneOp`) and claim the\n   *         next (`claimNextOp`). If none remain, finish to `done`. The new\n   *         position survives eviction.\n   *\n   * An advance is itself a progress event, so it bumps the watchdog (re-arming\n   * the alarm at the new stage) and accounts a snapshot unit. A no-op on a\n   * settled (`done` / `failed` / `cancelled`) or never-started (`idle`) run. PURE — `at` is the\n   * only clock, ids are positional.\n   */\n  function advance(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    result: StageResult,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n\n    // Stage failure → hard terminal. Carry the failing stage VALUE (stable),\n    // `undefined` for a single-shot run with no stage.\n    if (result.kind === \"fail\") {\n      const failed: MonitoredRunState<Stage> = {\n        ...s,\n        phase: \"failed\",\n        failure: {\n          reason: \"stage\",\n          stage: currentStage(s)?.input,\n          error: result.error,\n        },\n      };\n      return [failed, []];\n    }\n\n    // Success: bump the watchdog first (an advance is progress), then move the\n    // pipeline position.\n    const bumped = bumpProgress(s, at);\n\n    // Single-shot: one advance finishes the run.\n    if (!isPipeline) {\n      const done: MonitoredRunState<Stage> = { ...bumped, phase: \"done\" };\n      // Force a terminal checkpoint so the last durable snapshot is `done`,\n      // not whatever the cadence happened to land on.\n      return finishWithSnapshot(done, payload, at);\n    }\n\n    // Pipeline: retire the running stage, claim the next.\n    const current = currentStage(s);\n    const afterDone =\n      current !== undefined\n        ? wq.markDone(s.stepStates, current.id).next\n        : s.stepStates;\n    const claimed = wq.claim(afterDone, at);\n\n    if (claimed === null) {\n      // No more stages — the pipeline is complete.\n      const done: MonitoredRunState<Stage> = {\n        ...bumped,\n        phase: \"done\",\n        stepStates: afterDone,\n      };\n      return finishWithSnapshot(done, payload, at);\n    }\n\n    // Advance to the next stage — POSITION now points at the claimed item.\n    const moved: MonitoredRunState<Stage> = {\n      ...bumped,\n      stepStates: claimed.next,\n    };\n    return recordSnapshot(moved, payload, at);\n  }\n\n  /**\n   * Finish helper: force a terminal checkpoint when checkpointing is enabled\n   * (so the durable snapshot is the terminal state), else just settle. Shared\n   * by single-shot finish and pipeline completion. PURE.\n   */\n  function finishWithSnapshot(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (snap === null) return [s, []];\n    const [snapshot, cmds] = snap.force(s.snapshot, payload, at);\n    // Same narrowing as `recordSnapshot`: `snap.force` emits only the write Cmd.\n    return [{ ...s, snapshot }, cmds as readonly MonitoredRunCmd<V>[]];\n  }\n\n  // === Verb: onDeadline ====================================================\n\n  /**\n   * The safety alarm fired. Two outcomes by deadline-id match:\n   *\n   *   - the alarm matches the CURRENT `progressSeq` (no progress since it was\n   *     armed) → the run is wedged → terminate `failed { reason: \"deadline\" }`.\n   *   - the alarm matches an OLDER seq → a stale fire racing a progress event\n   *     that already re-armed the alarm → no-op (the engine retired this id;\n   *     tolerate a fire still in flight defensively).\n   *\n   * A no-op on a settled run (its alarm was reconciled away; tolerate a stale\n   * fire) and on a NEVER-STARTED (`idle`) run (`subs` armed nothing for it, so\n   * any alarm reaching it is a rogue fire that must not un-start it). PURE —\n   * `msg.atMs` stamps the failure.\n   */\n  function onDeadline(\n    s: MonitoredRunState<Stage>,\n    msg: MonitoredRunTimerMsg,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    // Only a live (`running` / `stale`) run is watched. A settled (`done` /\n    // `failed`) run's alarm was reconciled away, and a never-started (`idle`) run\n    // — which has no host-minted `runId` and armed nothing — must not be\n    // un-started by a born-live/rogue fire. The phase narrow IS the guard the old\n    // `runId === \"\"` sentinel stood in for.\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    // Only the alarm armed against the current progressSeq is live. A bumped\n    // seq means progress re-armed it; an older fire is stale.\n    if (msg.id !== safetyTimerId(s.runId, s.progressSeq)) return [s, []];\n    const failed: MonitoredRunState<Stage> = {\n      ...s,\n      phase: \"failed\",\n      failure: { reason: \"deadline\", at: msg.atMs },\n    };\n    return [failed, []];\n  }\n\n  // === Verb: boot ==========================================================\n\n  /**\n   * Resume after a reload (cold wake). Re-seeds the watchdog clock to `at` so\n   * the safety alarm re-arms from NOW (the pre-crash `lastProgressAt` would\n   * immediately fire a deadline that already elapsed during downtime — a cold\n   * wake is not a no-progress wedge). Bumps `progressSeq` so the alarm gets a\n   * fresh id, and resets the snapshot cadence counter (un-checkpointed\n   * pre-crash progress is moot — recovery resumes from the last durable\n   * checkpoint). The pipeline POSITION (`stepStates`) is preserved untouched —\n   * that is the whole point of staging: resume at the same stage.\n   *\n   * A no-op on a settled (`done` / `failed` / `cancelled`) or never-started (`idle`) run. Emits\n   * NO Cmd — re-emitting the current stage's outstanding effect is the CONSUMER's\n   * job (it knows the per-stage Cmd), the audit machine's `outstandingEffect(stage)`\n   * pattern. PURE.\n   */\n  function boot(\n    s: MonitoredRunState<Stage>,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    // `snap.boot` returns the reducer-cell shape `[SnapshotState, Cmd[]]`\n    // (uniform across every sibling knob); a boot emits no Cmd, so take only the\n    // slice. Assigning the tuple itself would put an ARRAY where a SnapshotState\n    // belongs — a type error AND a non-round-trippable slice.\n    const [bootedSnapshot] = activeSnap.boot(s.snapshot);\n    const reseeded: MonitoredRunState<Stage> = {\n      ...s,\n      phase: \"running\",\n      lastProgressAt: at,\n      progressSeq: s.progressSeq + 1,\n      snapshot: bootedSnapshot,\n      // Any stage left `running` mid-flight stays the running position; the\n      // queue is already correct (a single in-flight stage). resetRunningOp is\n      // NOT applied — unlike a work pool, a monitored run has exactly one\n      // in-flight stage and resuming it (not re-queuing it) is the correct\n      // cold-wake behavior.\n    };\n    return [reseeded, []];\n  }\n\n  // === Timers ==============================================================\n\n  /**\n   * The no-progress safety deadline, listed only while the run is live\n   * (`running` / `stale`) AND a `deadlineMs` is configured. Its id is keyed on\n   * `progressSeq`, so every progress event retires the old alarm and arms a\n   * fresh one at the new `lastProgressAt + deadlineMs` — a self-rearming\n   * watchdog with no manual `clearTimeout`. A settled run lists none.\n   *\n   * A NEVER-STARTED slice (`init()`) is its OWN `idle` phase, not a `running` run\n   * with an empty `runId`. The `phase !== \"running\" && phase !== \"stale\"` narrow\n   * therefore excludes it structurally — no separate `runId === \"\"` sentinel gate\n   * is needed. Were `idle` armed, it would fire a deadline at `0 + deadlineMs`\n   * (already in the past) and auto-fail a run that never began — the \"born live\"\n   * defect. `start` is the only transition out of `idle`, so the watchdog exists\n   * exactly once a real run is in flight.\n   */\n  function deadlines(s: MonitoredRunState<Stage>): readonly DeadlineSub[] {\n    if (config.deadlineMs === undefined) return [];\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [];\n    return [\n      deadlineSub(\n        safetyTimerId(s.runId, s.progressSeq),\n        s.lastProgressAt + config.deadlineMs,\n      ),\n    ];\n  }\n\n  /**\n   * The built-in `timer` Sub's deps for the watchdog: `deadlineMs` counted from\n   * `lastProgressAt`, the instant the current alarm was armed. Its fire is a\n   * `deadline_exceeded` Msg; route it to `onDeadline`. Declare\n   * `{ type: \"timer\", deps: (s) => run.timer(s.run) }`. PURE.\n   */\n  function timer(\n    s: MonitoredRunState<Stage>,\n  ): TimerDeps<MonitoredRunTimerMsg> | null {\n    return nextTimer(deadlines(s), s.lastProgressAt);\n  }\n\n  /**\n   * Fold a confirmed checkpoint write into the slice — advances the snapshot\n   * watermark (forward-only). A no-op pass-through when checkpointing is\n   * disabled. PURE. Fold the `snapshot_write_ok` Msg here.\n   */\n  function confirmSnapshot(\n    s: MonitoredRunState<Stage>,\n    msg: SnapshotSavedMsg<V>,\n  ): MonitoredRunState<Stage> {\n    if (snap === null) return s;\n    // `snap.confirm` returns the reducer-cell shape `[SnapshotState, Cmd[]]`\n    // (an ack emits nothing). Take only the slice — folding the whole tuple into\n    // `snapshot` would store an ARRAY where a SnapshotState belongs (a type error\n    // and a non-round-trippable slice).\n    const [confirmed] = snap.confirm(s.snapshot, msg);\n    return { ...s, snapshot: confirmed };\n  }\n\n  return {\n    /** The `snapshot_write` Cmd def — list it in `cmds` when checkpointing. */\n    checkpoint: activeSnap.write,\n    init,\n    start,\n    progress,\n    markStale,\n    cancel,\n    advance,\n    onDeadline,\n    boot,\n    confirmSnapshot,\n    deadlines,\n    timer,\n  };\n}\n\n/**\n * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the\n * slice lives at `state.run`. Convenience for the common single-slice host;\n * hosts with a differently-named field spread by hand. PURE — a thin record\n * rebuild, no clock / RNG.\n */\nexport function liftRun<\n  S extends { run: MonitoredRunState<Stage> },\n  Stage,\n  C extends Cmd,\n>(\n  state: S,\n  [slice, cmds]: readonly [MonitoredRunState<Stage>, readonly C[]],\n): readonly [S, readonly C[]] {\n  return [{ ...state, run: slice }, cmds];\n}\n\nexport type { SnapshotSavedMsg, SnapshotWriteCmd };\n"]}

package/dist/{chunk-V46HSVCK.js → chunk-BCTEOVOU.js}

@@ -1,5 +1,5 @@
+import { replay } from './chunk-CH5KTOEZ.js';
 import { typeOf, indexPath, unionKeys, keyPath } from './chunk-HWVW4AXC.js';
-import { replay } from './chunk-66PY5WYF.js';
 
 // src/internal/persistence/recorder/index.ts
 function recorder(runtime, opts) {
@@ -204,5 +204,5 @@ function firstDivergence(expected, actual, path) {
 }
 
 export { breadcrumbsFromTrace, deepEqual, parseJSONL, recorder, replayTrace, traceAttachment };
-//# sourceMappingURL=chunk-V46HSVCK.js.map
-//# sourceMappingURL=chunk-V46HSVCK.js.map
+//# sourceMappingURL=chunk-BCTEOVOU.js.map
+//# sourceMappingURL=chunk-BCTEOVOU.js.map

package/dist/{chunk-V46HSVCK.js.map → chunk-BCTEOVOU.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/persistence/recorder/index.ts","../src/internal/persistence/trace-replay/index.ts"],"names":[],"mappings":"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","file":"chunk-V46HSVCK.js","sourcesContent":["// ---------------------------------------------------------------------------\n// recorder — capture a Runtime's Msg sequence for later replay.\n//\n// `historyTracker` (in ../index) is the exemplar: a BOUNDED, in-memory ring\n// buffer over `runtime.observe`. The recorder is its UNBOUNDED, SERIALIZABLE\n// cousin. Where historyTracker exists to answer \"what were the last N\n// transitions?\", the recorder exists to answer \"reproduce this entire run\n// locally against the current reducer.\"\n//\n// The killer feature this enables: record a prod Msg sequence, dump it as\n// JSONL, ship the file home, and feed it to `../trace-replay`'s `replayTrace`\n// — which folds the SAME msgs through `replay(machine, ...)` and diffs the\n// resulting state against the recorded final state. If they diverge, the\n// reducer changed behavior for that input. Regression-as-a-trace.\n//\n// What `replay` needs to reproduce a run (see `replay` in ../index):\n//   - `loaded`   — the value `init` was booted with. Captured at the boot\n//                  observe, where `msg === null` and `state` is the post-init\n//                  initial state. (We capture the post-init state, not the raw\n//                  storage value, because replay re-runs `init(loaded, ctx)`\n//                  itself — and for a faithful re-run we feed it that initial\n//                  state as `loaded` so `init` returns `[loaded, []]`. This is\n//                  the rehydrate path, which the substrate guarantees is a pure\n//                  passthrough; see Invariant 2.)\n//   - `msgs`     — every non-null msg, in dispatch order.\n//   - `ctx`      — NOT captured here. Ctx is host wiring (sibling runtimes,\n//                  clients), supplied fresh at replay time. The trace is the\n//                  INPUT (loaded + msgs); ctx is the ENVIRONMENT.\n//\n// This module OWNS the `Trace` type. `../trace-replay` imports it.\n// ---------------------------------------------------------------------------\n\nimport type { BootingRuntime } from \"../../../index\";\n\n/**\n * A recorded run, sufficient to reproduce it via `../trace-replay`.\n *\n * The recorder OWNS this type; `../trace-replay` imports it. It is the wire\n * contract between the two halves of the record/replay feature.\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport interface Trace<S, M> {\n  /**\n   * The initial state captured at the boot observe (the transition where\n   * `msg === null`). Fed back to replay as `loaded` so `init(loaded, ctx)`\n   * reproduces the exact starting point. `null` only if the recorder attached\n   * AFTER boot (it missed the boot observe) — replay then re-runs fresh `init`.\n   */\n  readonly loaded: S | null;\n  /** The ordered, non-null msgs as observed. The replay input sequence. */\n  readonly msgs: readonly M[];\n  /**\n   * The last observed state. The oracle: `replayTrace` deep-compares its\n   * recomputed final state against this. Equal ⇒ the reducer still produces\n   * the same result for this input.\n   */\n  readonly finalState: S;\n  /**\n   * Per-transition `(msg, post-state)` pairs, in dispatch order, for human\n   * inspection (e.g. \"show me the state after step 3\"). When present, there\n   * is exactly one entry per recorded msg and `state` is the POST-transition\n   * state for that msg (so `steps[i].msg === msgs[i]` and `steps.at(-1).state`\n   * deep-equals `finalState`). NOT required for replay — replay only needs\n   * `loaded` + `msgs` + `finalState`.\n   *\n   * Present iff the recorder was created with `captureSteps: true`, OR the\n   * Trace was re-hydrated from JSONL via {@link parseJSONL} (the JSONL format\n   * carries per-step state, so the parser populates `steps` whenever a step\n   * line had a non-null state). A trace dumped with `captureSteps: false` has\n   * `steps === undefined`.\n   */\n  readonly steps?: readonly { readonly msg: M; readonly state: S }[];\n}\n\n/** Options for {@link recorder}. */\nexport interface RecorderOptions {\n  /**\n   * Fraction of msgs to record, in `(0, 1]`. Default `1` (record everything).\n   *\n   * IMPORTANT — sampling breaks replay fidelity. A sampled trace DROPS msgs,\n   * so its `msgs` array is no longer the complete input sequence and\n   * `replayTrace` will NOT reproduce `finalState`. Sampling exists for\n   * VOLUME STATISTICS (how much traffic, msg-type distribution), not for\n   * faithful replay. Use the default `1` for any trace you intend to replay.\n   *\n   * The boot observe (`msg === null`) is ALWAYS recorded regardless of\n   * `sampleRate` — `loaded` and `finalState` are anchors, not samples.\n   */\n  readonly sampleRate?: number;\n  /**\n   * When `true`, retain a per-transition `(msg, post-state)` pair in\n   * {@link Trace.steps} for EVERY recorded transition. Default `false`.\n   *\n   * Size vs. fidelity — the precise trade-off:\n   *\n   *   - `captureSteps: false` (default) — the MINIMAL replay-faithful trace.\n   *     The recorder keeps `loaded` (boot state), the ordered `msgs`, and\n   *     `finalState`. That is exactly what `../trace-replay` needs to refold\n   *     the run and diff the result. Memory is O(msgs) — one msg ref each, no\n   *     per-step state snapshot. `dump().steps` is `undefined`; in JSONL,\n   *     interior step lines carry `state: null` (the post-states were never\n   *     retained) and only the LAST step line carries `finalState`. A trace\n   *     dumped this way REPLAYS correctly but cannot answer \"what was the\n   *     state after step 3?\".\n   *\n   *   - `captureSteps: true` — the FULL-fidelity trace. The recorder also\n   *     snapshots the post-transition state for every msg, so `dump().steps`\n   *     holds `{ msg, state }` for every transition (post-state) and\n   *     `toJSONL()` emits a non-null `state` on every step line. Memory is\n   *     O(msgs × |state|) — a state ref per transition (refs, not deep\n   *     copies; TEA states are conventionally immutable, so the runtime's\n   *     post-transition state object is retained by reference). This is the\n   *     mode for per-step inspection and for a JSONL file that round-trips\n   *     `steps` exactly via {@link parseJSONL}.\n   *\n   * Replay fidelity is identical in both modes — `../trace-replay` reads\n   * `loaded` + `msgs` + `finalState` only and never touches `steps`. The\n   * choice is purely \"do I also want to inspect intermediate states?\".\n   */\n  readonly captureSteps?: boolean;\n}\n\n/**\n * A live recorder attached to a Runtime. Mirrors `historyTracker`'s\n * stop/snapshot semantics: `dump()` works at any time (including after\n * `stop()`), `stop()` is idempotent and detaches the observer.\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport interface Recorder<S, M> {\n  /**\n   * Snapshot the recording so far as a {@link Trace}. Returns a fresh object\n   * with copied arrays on every call (callers may slice/replay without\n   * affecting the recorder's buffers). Entry values are references to the\n   * originals (TEA states/msgs are conventionally immutable).\n   *\n   * Throws only if called before the boot observe has fired AND no msgs have\n   * been recorded — i.e. there is no `finalState` yet. In practice callers\n   * `await runtime.ready` before `dump()`, after which boot has fired.\n   */\n  dump(): Trace<S, M>;\n  /**\n   * Serialize the recording as JSONL (one JSON object per line) — a streamable\n   * format that appends cleanly and survives truncation (a partial tail line\n   * is the only loss). The first line is the boot header\n   * `{ kind: \"boot\", state }`; each subsequent line is\n   * `{ kind: \"step\", msg, state }` for one recorded transition.\n   *\n   * Re-hydrate with {@link parseJSONL}.\n   *\n   * Round-trip fidelity depends on `captureSteps`:\n   *   - `captureSteps: true` — every step line carries its non-null\n   *     post-state, so `parseJSONL(rec.toJSONL())` reconstructs `steps`\n   *     EXACTLY and deep-equals `rec.dump()` (which also has `steps`). Full\n   *     per-step fidelity round-trips.\n   *   - `captureSteps: false` (default) — interior step lines carry\n   *     `state: null` (those post-states were never retained); only the last\n   *     step line carries `finalState`. `parseJSONL` then populates `steps`\n   *     with just the entries that had a non-null state (the final one), so\n   *     the re-hydrated Trace is NOT deep-equal to `rec.dump()` (which has no\n   *     `steps`). It is still fully replay-faithful: `loaded`, `msgs`, and\n   *     `finalState` are intact. Record with `captureSteps: true` if you need\n   *     interior states to survive the round-trip.\n   */\n  toJSONL(): string;\n  /**\n   * Detach the underlying observer. After `stop()`:\n   *   - no new transitions are recorded;\n   *   - `dump()` / `toJSONL()` keep working against the buffered contents;\n   *   - the recorder holds no observer reference into the runtime.\n   *\n   * Idempotent — subsequent calls are no-ops.\n   */\n  stop(): void;\n}\n\n/**\n * Attach a recorder to a Runtime. Subscribes via `runtime.observe`, capturing\n * the boot state as `loaded` and every subsequent non-null msg in order.\n *\n * One-line creation, mirroring `historyTracker`:\n *\n *     const rec = recorder(runtime);\n *     // ... drive the runtime ...\n *     await runtime.ready;            // boot observe has fired\n *     const trace = rec.dump();       // { loaded, msgs, finalState }\n *\n * @param runtime - any `BootingRuntime<S, M>` (a full `Runtime` satisfies it).\n *                  The recorder uses only `observe`, which is total before boot\n *                  — so you attach it to the synchronous `run()` handle to\n *                  capture the boot transition as `loaded`.\n * @param opts    - see {@link RecorderOptions}. Default records everything,\n *                  no step retention.\n */\nexport function recorder<S, M extends { type: string }>(\n  runtime: BootingRuntime<S, M>,\n  opts?: RecorderOptions,\n): Recorder<S, M> {\n  // Clamp sampleRate into (0, 1]. A non-positive or NaN rate would record\n  // nothing (and break replay anchors); default it to 1 (record all). Rates\n  // above 1 are meaningless — clamp to 1.\n  const rawRate = opts?.sampleRate;\n  const sampleRate =\n    rawRate === undefined || Number.isNaN(rawRate) || rawRate <= 0\n      ? 1\n      : Math.min(rawRate, 1);\n  const captureSteps = opts?.captureSteps ?? false;\n\n  // `loaded` is the post-init state captured at the boot observe. `undefined`\n  // sentinel = boot not yet seen; resolved to `S | null` in dump() (null when\n  // the recorder attached after boot and never observed msg === null).\n  let loaded: S | undefined;\n  let sawBoot = false;\n  // The ordered, recorded msgs. Unbounded (the recorder's whole point vs the\n  // bounded historyTracker).\n  const msgs: M[] = [];\n  // Per-step (msg, state) pairs — only populated when captureSteps is on.\n  const steps: { msg: M; state: S }[] = [];\n  // The last observed state — boot state until the first step, then advances\n  // with every recorded OR dropped transition (finalState must reflect the\n  // true latest state even under sampling, so it stays a valid replay oracle\n  // for the unsampled case and an honest \"where the run ended\" marker).\n  let finalState: S | undefined;\n  let stopped = false;\n\n  // The boot transition — the post-init initial state the old `observe(msg ===\n  // null)` arm captured as `loaded` — now arrives via `onBoot` (#47). Always\n  // captured (boot is the replay anchor). It is also the first `finalState`\n  // until the first applied transition advances it.\n  const unboot = runtime.onBoot((state) => {\n    finalState = state;\n    loaded = state;\n    sawBoot = true;\n  });\n\n  const unobserve = runtime.observe((msg, state) => {\n    // finalState tracks the latest state regardless of sampling — it is the\n    // run's endpoint, an anchor, not a sample.\n    finalState = state;\n\n    // Sampling decision. sampleRate === 1 short-circuits to always-record so\n    // the common (faithful) path pays no RNG cost. Math.random() < rate keeps\n    // a `rate` fraction in expectation.\n    if (sampleRate < 1 && Math.random() >= sampleRate) return;\n\n    msgs.push(msg);\n    if (captureSteps) steps.push({ msg, state });\n  });\n\n  return {\n    dump(): Trace<S, M> {\n      if (finalState === undefined) {\n        throw new Error(\n          \"tea recorder: dump() called before any transition was observed. \" +\n            \"Await `runtime.ready` (boot fires the first observe) before dumping.\",\n        );\n      }\n      return {\n        // sawBoot ⇒ `loaded` is the captured boot state; otherwise the\n        // recorder attached post-boot and replay must re-run fresh init.\n        loaded: sawBoot ? (loaded as S) : null,\n        msgs: msgs.slice(),\n        finalState,\n        // Only attach `steps` when captureSteps was requested — keeps the\n        // dumped Trace shape honest about what was retained.\n        ...(captureSteps ? { steps: steps.slice() } : {}),\n      };\n    },\n    toJSONL(): string {\n      if (finalState === undefined) {\n        throw new Error(\n          \"tea recorder: toJSONL() called before any transition was observed. \" +\n            \"Await `runtime.ready` (boot fires the first observe) before serializing.\",\n        );\n      }\n      // Serialize the live snapshot via the shared Trace→JSONL writer so the\n      // recorder and the standalone `traceAttachment` path emit byte-identical\n      // wire format. `dump()` resolves the captureSteps logic (steps present\n      // iff captureSteps was on); `traceToJSONL` then emits a non-null state\n      // on every step line when steps exist, or `null` interior + finalState\n      // on the last line when they don't. The replay path never reads step\n      // states, so the captureSteps:false null-interiors never affect replay.\n      return traceToJSONL(this.dump());\n    },\n    stop(): void {\n      if (stopped) return;\n      stopped = true;\n      unobserve();\n      unboot();\n    },\n  };\n}\n\n/** One line of the JSONL format produced by {@link Recorder.toJSONL}. */\ntype JsonlLine<S, M> =\n  | { readonly kind: \"boot\"; readonly state: S | null }\n  | { readonly kind: \"step\"; readonly msg: M; readonly state: S | null };\n\n/**\n * Re-hydrate a {@link Trace} from the JSONL produced by\n * {@link Recorder.toJSONL}. The inverse of `toJSONL`, so\n * `parseJSONL(rec.toJSONL())` deep-equals `rec.dump()`.\n *\n * Parsing rules:\n *   - The first non-blank line MUST be the boot header `{ kind: \"boot\", state }`.\n *     Its `state` becomes `Trace.loaded`.\n *   - Each `{ kind: \"step\", msg, state }` line contributes `msg` to\n *     `Trace.msgs` and `(msg, state)` to `Trace.steps`.\n *   - `Trace.finalState` is the `state` of the LAST step line, or the boot\n *     `state` when there are no steps (a boot-only trace).\n *\n * Blank lines are skipped (tolerant of trailing newlines / hand-edited files).\n * A malformed line, a missing/duplicate boot header, or a step with `null`\n * final state throws — the trace is unusable for replay and silent corruption\n * is worse than a loud parse error (errors are data; surface them).\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport function parseJSONL<S, M>(jsonl: string): Trace<S, M> {\n  const rawLines = jsonl.split(\"\\n\");\n  let loaded: S | null = null;\n  let sawBoot = false;\n  const msgs: M[] = [];\n  const steps: { msg: M; state: S }[] = [];\n  let finalState: S | null = null;\n  let finalKnown = false;\n\n  for (const [i, rawLine] of rawLines.entries()) {\n    const line = rawLine.trim();\n    if (line === \"\") continue; // tolerate blank / trailing-newline lines\n\n    let parsed: JsonlLine<S, M>;\n    try {\n      parsed = JSON.parse(line) as JsonlLine<S, M>;\n    } catch (err) {\n      throw new Error(\n        `tea recorder: parseJSONL failed on line ${i + 1}: not valid JSON. ${String(err)}`,\n      );\n    }\n\n    if (parsed.kind === \"boot\") {\n      if (sawBoot) {\n        throw new Error(\n          `tea recorder: parseJSONL saw a second boot header on line ${i + 1}. ` +\n            \"A trace has exactly one boot line.\",\n        );\n      }\n      sawBoot = true;\n      loaded = parsed.state;\n      // The boot state is the finalState until a step supersedes it (boot-only\n      // trace case).\n      finalState = parsed.state;\n      finalKnown = parsed.state !== null;\n    } else if (parsed.kind === \"step\") {\n      if (!sawBoot) {\n        throw new Error(\n          `tea recorder: parseJSONL saw a step line before the boot header on line ${i + 1}.`,\n        );\n      }\n      msgs.push(parsed.msg);\n      if (parsed.state !== null) {\n        steps.push({ msg: parsed.msg, state: parsed.state });\n        finalState = parsed.state;\n        finalKnown = true;\n      }\n    } else {\n      throw new Error(\n        `tea recorder: parseJSONL saw an unknown line kind on line ${i + 1}: ` +\n          JSON.stringify((parsed as { kind?: unknown }).kind),\n      );\n    }\n  }\n\n  if (!sawBoot) {\n    throw new Error(\n      \"tea recorder: parseJSONL found no boot header. A trace must start with \" +\n        '{ kind: \"boot\", state }.',\n    );\n  }\n  if (!finalKnown || finalState === null) {\n    throw new Error(\n      \"tea recorder: parseJSONL could not determine finalState — the boot state \" +\n        \"was null and no step carried a non-null state. The trace is unusable for replay.\",\n    );\n  }\n\n  return { loaded, msgs, finalState, steps };\n}\n\n// ---------------------------------------------------------------------------\n// Sentry crash→trace adapters — pure, zero-dependency, Sentry-SHAPED.\n//\n// The killer DevX flow: a machine crashes in prod → its recorded Trace rides\n// along on the Sentry event → one click later you `parseJSONL` it and replay\n// the exact run locally against the (possibly fixed) reducer. These two\n// adapters are the bridge from a `Trace` to the two Sentry surfaces that carry\n// it: an Attachment (the full replayable trace) and Breadcrumbs (a human-\n// readable timeline of the msgs that led to the crash).\n//\n// They take NO dependency on `@sentry/*`. They emit PLAIN OBJECTS whose shapes\n// match Sentry's public `Attachment` and `Breadcrumb` types, and the consumer\n// wires them at their own Sentry boundary (browser or node). This keeps the\n// recorder runnable anywhere a machine runs (a Worker, a Node script, a test)\n// and lets the consumer pin whatever Sentry SDK version they already ship.\n// ---------------------------------------------------------------------------\n\n/**\n * A Sentry-shaped attachment carrying the full {@link Trace} as JSONL. The\n * shape matches Sentry's `Attachment` type so the consumer can hand it\n * straight to `addAttachment(...)` without any adaptation.\n *\n * - `filename`    — `\"tea-trace.jsonl\"`. The name Sentry shows in the UI and\n *                   uses for download; `.jsonl` signals the streamable format.\n * - `data`        — the trace serialized via {@link Recorder.toJSONL}'s format\n *                   (re-hydrate downstream with {@link parseJSONL}).\n * - `contentType` — `\"application/x-ndjson\"`, the standard MIME for\n *                   newline-delimited JSON.\n */\nexport interface TraceAttachment {\n  readonly filename: string;\n  readonly data: string;\n  readonly contentType: string;\n}\n\n/**\n * Serialize a {@link Trace} into a Sentry-shaped attachment so a crash event\n * carries the full, replayable run. Pure — no Sentry import, no I/O. The\n * returned object matches Sentry's `Attachment` shape exactly.\n *\n * The `data` field is JSONL in the same format {@link Recorder.toJSONL}\n * produces, so the home-side flow is `parseJSONL(attachment.data)` →\n * `replayTrace(machine, trace, ctx)`.\n *\n * Consumer wiring (no Sentry import here — the consumer owns the boundary):\n *\n * ```ts\n * import * as Sentry from \"@sentry/browser\"; // or \"@sentry/node\"\n * import { traceAttachment } from \"./internal/persistence/recorder\"; // internal module\n * Sentry.getCurrentScope().addAttachment(traceAttachment(rec.dump()));\n * ```\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport function traceAttachment<S, M extends { type: string }>(\n  trace: Trace<S, M>,\n): TraceAttachment {\n  return {\n    filename: \"tea-trace.jsonl\",\n    data: traceToJSONL(trace),\n    contentType: \"application/x-ndjson\",\n  };\n}\n\n/** A Sentry-shaped breadcrumb. Matches the fields of Sentry's `Breadcrumb`. */\nexport interface TraceBreadcrumb {\n  readonly category: string;\n  readonly type: string;\n  readonly level: string;\n  readonly message: string;\n  readonly data?: Record<string, unknown>;\n}\n\n/** Options for {@link breadcrumbsFromTrace}. */\nexport interface BreadcrumbsOptions<M> {\n  /**\n   * Max breadcrumbs to emit. Default `100` (Sentry's own default breadcrumb\n   * cap). When the trace has more msgs than `limit`, the OLDEST are dropped —\n   * the returned list is the newest-last tail, matching how a Sentry\n   * breadcrumb ring buffer behaves (the crash context is the recent past).\n   */\n  readonly limit?: number;\n  /**\n   * Customize each breadcrumb's `message`. Default uses `msg.type`. Provide a\n   * serializer to surface a richer one-liner (e.g. include an id). The msg is\n   * ALSO always attached verbatim under `data.msg` regardless of this option,\n   * so the structured payload is never lost to the string rendering.\n   */\n  readonly serialize?: (msg: M) => string;\n}\n\n/**\n * Project a {@link Trace}'s recorded msgs into Sentry-shaped breadcrumbs — a\n * human-readable timeline of \"what happened before the crash\". Pure — no\n * Sentry import, no I/O. Each returned object matches Sentry's `Breadcrumb`\n * shape, so the consumer can loop and call `addBreadcrumb(...)`.\n *\n * One breadcrumb per recorded msg, in dispatch order (NEWEST LAST — Sentry\n * renders breadcrumbs oldest-first and the crash is the most recent event).\n * Each breadcrumb:\n *   - `category` — `\"tea\"` (groups them in the Sentry breadcrumb panel).\n *   - `type`     — `\"default\"` (the generic Sentry breadcrumb type).\n *   - `level`    — `\"info\"` (msgs are normal flow; the crash is the event).\n *   - `message`  — `msg.type`, or `serialize(msg)` when provided.\n *   - `data.msg` — the full msg object (structured detail kept verbatim).\n *\n * Capped at `opts.limit` (default 100). When the trace has more msgs than the\n * cap, the OLDEST are dropped and the newest `limit` are kept — the recent\n * lead-up to the crash is the useful context.\n *\n * Consumer wiring (no Sentry import here — the consumer owns the boundary):\n *\n * ```ts\n * import * as Sentry from \"@sentry/browser\"; // or \"@sentry/node\"\n * import { breadcrumbsFromTrace } from \"./internal/persistence/recorder\"; // internal module\n * for (const b of breadcrumbsFromTrace(rec.dump())) Sentry.addBreadcrumb(b);\n * ```\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport function breadcrumbsFromTrace<S, M extends { type: string }>(\n  trace: Trace<S, M>,\n  opts?: BreadcrumbsOptions<M>,\n): TraceBreadcrumb[] {\n  const rawLimit = opts?.limit;\n  // Clamp limit to a non-negative integer. `undefined`/NaN → 100 (Sentry's\n  // default). A negative or zero limit yields an empty list (the caller asked\n  // for no breadcrumbs); fractional values floor (you can't emit half a crumb).\n  const limit =\n    rawLimit === undefined || Number.isNaN(rawLimit)\n      ? 100\n      : Math.max(0, Math.floor(rawLimit));\n  const serialize = opts?.serialize;\n\n  // Keep the NEWEST `limit` msgs (the recent lead-up to the crash). Slicing\n  // from `length - limit` (clamped to 0) preserves dispatch order within the\n  // kept window. Note we do NOT use `slice(-limit)`: `slice(-0)` is `slice(0)`\n  // (JS treats -0 as 0), which would return the WHOLE array for `limit: 0`.\n  const start = Math.max(0, trace.msgs.length - limit);\n  const kept = start === 0 ? trace.msgs : trace.msgs.slice(start);\n\n  const crumbs: TraceBreadcrumb[] = [];\n  for (const msg of kept) {\n    crumbs.push({\n      category: \"tea\",\n      type: \"default\",\n      level: \"info\",\n      message: serialize ? serialize(msg) : msg.type,\n      // Full msg kept verbatim so the structured payload survives even when\n      // `message` is a terse one-liner. Cast: a Msg is a `{ type: string }`\n      // record, which is a `Record<string, unknown>` for Sentry's `data`.\n      data: { msg: msg as unknown as Record<string, unknown> },\n    });\n  }\n  return crumbs;\n}\n\n// ---------------------------------------------------------------------------\n// traceToJSONL — serialize a STANDALONE Trace to JSONL (the dump→file path).\n//\n// `Recorder.toJSONL()` serializes the recorder's live buffers. `traceAttachment`\n// works over a plain `Trace` value (a `dump()` snapshot or a `parseJSONL`\n// result), which has no recorder behind it — so it needs a Trace→JSONL\n// function. This is the same wire format `Recorder.toJSONL` emits and\n// `parseJSONL` reads, so `parseJSONL(traceToJSONL(trace))` round-trips.\n//\n// When `trace.steps` is present (captureSteps was on, or the trace came from\n// parseJSONL), every step line carries its post-state. When absent, interior\n// step states are unknown — emitted as `null`, with `finalState` on the LAST\n// step line (identical to the captureSteps:false path in `Recorder.toJSONL`).\n// ---------------------------------------------------------------------------\nfunction traceToJSONL<S, M>(trace: Trace<S, M>): string {\n  const lines: string[] = [];\n  lines.push(JSON.stringify({ kind: \"boot\", state: trace.loaded }));\n\n  const steps = trace.steps;\n  for (let i = 0; i < trace.msgs.length; i++) {\n    const msg = trace.msgs[i];\n    const stepState = steps\n      ? steps[i]?.state\n      : i === trace.msgs.length - 1\n        ? trace.finalState\n        : null;\n    lines.push(JSON.stringify({ kind: \"step\", msg, state: stepState }));\n  }\n  return lines.join(\"\\n\");\n}\n","// ---------------------------------------------------------------------------\n// trace-replay — replay a recorded Trace against a machine and diff the state.\n//\n// This is the back half of the record/replay feature. `../recorder` captures\n// a run (`loaded` + `msgs` + `finalState`); this module feeds that input\n// through the core `replay(machine, { msgs, ctx, loaded })` fold and asks:\n//\n//     does the current reducer still produce the SAME final state for this\n//     recorded input?\n//\n// Equal ⇒ the reducer is behavior-compatible with the recording. Diverged ⇒\n// the reducer changed for that input, and the divergence path\n// (`state.queue[2].status`) points at exactly the cell that drifted. This is\n// the regression / production-repro tool: record a prod incident, replay it\n// against the fixed reducer locally, confirm the fix changes the state at the\n// path you expected — or catch an unintended drift before it ships.\n//\n// Standalone by design. It imports ONLY the `Trace` type from `../recorder`\n// and the `replay` engine from `../index`. The deep-equal + first-divergence\n// path finder is self-contained (no external diff lib) — a richer pretty-diff\n// lands in `../devtools` later; trace-replay stays dependency-free so it can\n// run anywhere a machine runs (CI, a Worker, a Node script).\n// ---------------------------------------------------------------------------\n\nimport { type Cmd, type Machine, replay, type Sub } from \"../../../index\";\nimport type { Trace } from \"../recorder\";\nimport { indexPath, keyPath, typeOf, unionKeys } from \"./state-walk\";\n\n/**\n * The outcome of {@link replayTrace}.\n *\n * @typeParam S - the machine's State type.\n */\nexport interface ReplayResult<S> {\n  /** `true` iff the recomputed final state deep-equals the trace's `finalState`. */\n  matches: boolean;\n  /** The trace's recorded `finalState` — what the run originally produced. */\n  expected: S;\n  /** The state the current reducer produced for the same input. */\n  actual: S;\n  /**\n   * Present iff `matches` is `false`. The FIRST point of divergence found by\n   * a deterministic pre-order walk:\n   *   - `path`     — a dotted/indexed access path from the state root, e.g.\n   *                  `state.queue[2].status` or `state` for a root-level\n   *                  scalar mismatch.\n   *   - `expected` — the recorded value at that path.\n   *   - `actual`   — the recomputed value at that path.\n   */\n  divergence?: { path: string; expected: unknown; actual: unknown };\n}\n\n/**\n * Replay a recorded {@link Trace} against `machine` and diff the recomputed\n * final state against the recorded one.\n *\n * Runs the core pure fold `replay(machine, { msgs: trace.msgs, ctx,\n * loaded: trace.loaded })` — init + update only, never `interpret`, never a\n * `Store`, never a live subscription (see `replay` in ../index). The `ctx` is\n * supplied fresh by the caller: the trace is the INPUT (loaded + msgs); ctx is\n * the ENVIRONMENT the reducer runs against now.\n *\n * @param machine - the machine to replay against. Mutating its reducer (the\n *                  whole point of a regression check) is what makes a recorded\n *                  trace diverge.\n * @param trace   - a Trace from `../recorder` (live `dump()` or a re-hydrated\n *                  `parseJSONL(...)`).\n * @param ctx     - the runtime ctx, supplied fresh at replay time.\n */\nexport function replayTrace<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  trace: Trace<S, M>,\n  ctx: Ctx,\n): ReplayResult<S> {\n  const result = replay(machine, {\n    msgs: trace.msgs,\n    ctx,\n    loaded: trace.loaded,\n  });\n  const actual = result.state;\n  const expected = trace.finalState;\n\n  const divergence = firstDivergence(expected, actual, \"state\");\n  if (divergence === null) {\n    return { matches: true, expected, actual };\n  }\n  return { matches: false, expected, actual, divergence };\n}\n\n/**\n * Order-insensitive structural deep-equality — the comparator the\n * record/replay lane owns, exposed so consumers (e.g. `@demlik/tea/parity`'s\n * `parityEqual`) reuse it rather than adding a fourth deep-compare. It is one\n * of three structural walkers in the package, divergent on purpose:\n * this `deepEqual` returns a boolean verdict (order-insensitive, for\n * replay/parity equality), `devtools`'s `diffState` returns a change list (for\n * a human-readable diff view), and `testing`'s `__deepEqual` is the assertion\n * helpers' internal compare — same shape, three jobs, not one to collapse.\n * `true` iff `a` and `b` are structurally equal under {@link firstDivergence}'s\n * walk (object keys compared order-insensitively, arrays index-by-index).\n */\nexport function deepEqual(a: unknown, b: unknown): boolean {\n  return firstDivergence(a, b, \"state\") === null;\n}\n\n// === deep-equal + first-divergence path finder ===\n//\n// One walk does both jobs: it returns the FIRST point where `expected` and\n// `actual` differ (as a path + the two values), or `null` when they are\n// deeply equal. \"First\" is defined by a deterministic pre-order traversal:\n// the node itself, then its children in a stable key order (array index\n// order; object keys sorted so the result does not depend on insertion\n// order — two states with the same data but different key order are equal,\n// and the reported path for a real mismatch is reproducible run-to-run).\n//\n// The path grammar (`typeOf`, `indexPath`/`keyPath` segments, `unionKeys`\n// order) is shared with devtools' `diffState` via `./state-walk`, so the two\n// walkers print the SAME path for the same cell by construction. Only the leaf\n// policy differs, on purpose: first-hit here, collect-all there.\n//\n// Scope: TEA state is plain JSON-shaped data (the substrate's __DEV__ guards\n// reject closures in Cmds, and states are conventionally serializable). So\n// the walk handles: primitives, null/undefined, arrays, and plain objects.\n// It treats other object kinds (Date, Map, Set, class instances) by reference\n// identity + a structural fallback via Object.entries — sufficient for the\n// JSON-shaped states this tool targets; a richer differ lives in ../devtools.\n\n/** A divergence record, or `null` when the two values are deeply equal. */\ntype Divergence = { path: string; expected: unknown; actual: unknown } | null;\n\nfunction firstDivergence(\n  expected: unknown,\n  actual: unknown,\n  path: string,\n): Divergence {\n  // Identity / primitive fast path. Handles same-reference, and equal\n  // primitives. `Object.is` so NaN === NaN and +0 ≠ -0 (matches structural\n  // equality intent better than ===).\n  if (Object.is(expected, actual)) return null;\n\n  const te = typeOf(expected);\n  const ta = typeOf(actual);\n  // Different kinds at this node (e.g. object vs array, number vs string,\n  // present vs null) — this node IS the divergence.\n  if (te !== ta) return { path, expected, actual };\n\n  if (te === \"array\") {\n    const ae = expected as unknown[];\n    const aa = actual as unknown[];\n    if (ae.length !== aa.length) {\n      // Length mismatch reported at the array node itself — the shape differs,\n      // which is more informative than an arbitrary element index.\n      return { path, expected, actual };\n    }\n    for (let i = 0; i < ae.length; i++) {\n      const d = firstDivergence(ae[i], aa[i], indexPath(path, i));\n      if (d !== null) return d;\n    }\n    return null;\n  }\n\n  if (te === \"object\") {\n    const oe = expected as Record<string, unknown>;\n    const oa = actual as Record<string, unknown>;\n    // Sorted union of keys for deterministic traversal. A key present in one\n    // but absent in the other diverges at that child path (its value is\n    // `undefined` on the missing side).\n    for (const key of unionKeys(oe, oa)) {\n      const d = firstDivergence(oe[key], oa[key], keyPath(path, key));\n      if (d !== null) return d;\n    }\n    return null;\n  }\n\n  // Primitives (string/number/boolean/bigint/symbol/function) that failed the\n  // Object.is fast path, or null/undefined that differ — this node diverges.\n  return { path, expected, actual };\n}\n"]}
+{"version":3,"sources":["../src/internal/persistence/recorder/index.ts","../src/internal/persistence/trace-replay/index.ts"],"names":[],"mappings":"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","file":"chunk-BCTEOVOU.js","sourcesContent":["// ---------------------------------------------------------------------------\n// recorder — capture a Runtime's Msg sequence for later replay.\n//\n// `historyTracker` (in ../index) is the exemplar: a BOUNDED, in-memory ring\n// buffer over `runtime.observe`. The recorder is its UNBOUNDED, SERIALIZABLE\n// cousin. Where historyTracker exists to answer \"what were the last N\n// transitions?\", the recorder exists to answer \"reproduce this entire run\n// locally against the current reducer.\"\n//\n// The killer feature this enables: record a prod Msg sequence, dump it as\n// JSONL, ship the file home, and feed it to `../trace-replay`'s `replayTrace`\n// — which folds the SAME msgs through `replay(machine, ...)` and diffs the\n// resulting state against the recorded final state. If they diverge, the\n// reducer changed behavior for that input. Regression-as-a-trace.\n//\n// What `replay` needs to reproduce a run (see `replay` in ../index):\n//   - `loaded`   — the value `init` was booted with. Captured at the boot\n//                  observe, where `msg === null` and `state` is the post-init\n//                  initial state. (We capture the post-init state, not the raw\n//                  storage value, because replay re-runs `init(loaded, ctx)`\n//                  itself — and for a faithful re-run we feed it that initial\n//                  state as `loaded` so `init` returns `[loaded, []]`. This is\n//                  the rehydrate path, which the substrate guarantees is a pure\n//                  passthrough; see Invariant 2.)\n//   - `msgs`     — every non-null msg, in dispatch order.\n//   - `ctx`      — NOT captured here. Ctx is host wiring (sibling runtimes,\n//                  clients), supplied fresh at replay time. The trace is the\n//                  INPUT (loaded + msgs); ctx is the ENVIRONMENT.\n//\n// This module OWNS the `Trace` type. `../trace-replay` imports it.\n// ---------------------------------------------------------------------------\n\nimport type { BootingRuntime } from \"../../../index\";\n\n/**\n * A recorded run, sufficient to reproduce it via `../trace-replay`.\n *\n * The recorder OWNS this type; `../trace-replay` imports it. It is the wire\n * contract between the two halves of the record/replay feature.\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport interface Trace<S, M> {\n  /**\n   * The initial state captured at the boot observe (the transition where\n   * `msg === null`). Fed back to replay as `loaded` so `init(loaded, ctx)`\n   * reproduces the exact starting point. `null` only if the recorder attached\n   * AFTER boot (it missed the boot observe) — replay then re-runs fresh `init`.\n   */\n  readonly loaded: S | null;\n  /** The ordered, non-null msgs as observed. The replay input sequence. */\n  readonly msgs: readonly M[];\n  /**\n   * The last observed state. The oracle: `replayTrace` deep-compares its\n   * recomputed final state against this. Equal ⇒ the reducer still produces\n   * the same result for this input.\n   */\n  readonly finalState: S;\n  /**\n   * Per-transition `(msg, post-state)` pairs, in dispatch order, for human\n   * inspection (e.g. \"show me the state after step 3\"). When present, there\n   * is exactly one entry per recorded msg and `state` is the POST-transition\n   * state for that msg (so `steps[i].msg === msgs[i]` and `steps.at(-1).state`\n   * deep-equals `finalState`). NOT required for replay — replay only needs\n   * `loaded` + `msgs` + `finalState`.\n   *\n   * Present iff the recorder was created with `captureSteps: true`, OR the\n   * Trace was re-hydrated from JSONL via {@link parseJSONL} (the JSONL format\n   * carries per-step state, so the parser populates `steps` whenever a step\n   * line had a non-null state). A trace dumped with `captureSteps: false` has\n   * `steps === undefined`.\n   */\n  readonly steps?: readonly { readonly msg: M; readonly state: S }[];\n}\n\n/** Options for {@link recorder}. */\nexport interface RecorderOptions {\n  /**\n   * Fraction of msgs to record, in `(0, 1]`. Default `1` (record everything).\n   *\n   * IMPORTANT — sampling breaks replay fidelity. A sampled trace DROPS msgs,\n   * so its `msgs` array is no longer the complete input sequence and\n   * `replayTrace` will NOT reproduce `finalState`. Sampling exists for\n   * VOLUME STATISTICS (how much traffic, msg-type distribution), not for\n   * faithful replay. Use the default `1` for any trace you intend to replay.\n   *\n   * The boot observe (`msg === null`) is ALWAYS recorded regardless of\n   * `sampleRate` — `loaded` and `finalState` are anchors, not samples.\n   */\n  readonly sampleRate?: number;\n  /**\n   * When `true`, retain a per-transition `(msg, post-state)` pair in\n   * {@link Trace.steps} for EVERY recorded transition. Default `false`.\n   *\n   * Size vs. fidelity — the precise trade-off:\n   *\n   *   - `captureSteps: false` (default) — the MINIMAL replay-faithful trace.\n   *     The recorder keeps `loaded` (boot state), the ordered `msgs`, and\n   *     `finalState`. That is exactly what `../trace-replay` needs to refold\n   *     the run and diff the result. Memory is O(msgs) — one msg ref each, no\n   *     per-step state snapshot. `dump().steps` is `undefined`; in JSONL,\n   *     interior step lines carry `state: null` (the post-states were never\n   *     retained) and only the LAST step line carries `finalState`. A trace\n   *     dumped this way REPLAYS correctly but cannot answer \"what was the\n   *     state after step 3?\".\n   *\n   *   - `captureSteps: true` — the FULL-fidelity trace. The recorder also\n   *     snapshots the post-transition state for every msg, so `dump().steps`\n   *     holds `{ msg, state }` for every transition (post-state) and\n   *     `toJSONL()` emits a non-null `state` on every step line. Memory is\n   *     O(msgs × |state|) — a state ref per transition (refs, not deep\n   *     copies; TEA states are conventionally immutable, so the runtime's\n   *     post-transition state object is retained by reference). This is the\n   *     mode for per-step inspection and for a JSONL file that round-trips\n   *     `steps` exactly via {@link parseJSONL}.\n   *\n   * Replay fidelity is identical in both modes — `../trace-replay` reads\n   * `loaded` + `msgs` + `finalState` only and never touches `steps`. The\n   * choice is purely \"do I also want to inspect intermediate states?\".\n   */\n  readonly captureSteps?: boolean;\n}\n\n/**\n * A live recorder attached to a Runtime. Mirrors `historyTracker`'s\n * stop/snapshot semantics: `dump()` works at any time (including after\n * `stop()`), `stop()` is idempotent and detaches the observer.\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport interface Recorder<S, M> {\n  /**\n   * Snapshot the recording so far as a {@link Trace}. Returns a fresh object\n   * with copied arrays on every call (callers may slice/replay without\n   * affecting the recorder's buffers). Entry values are references to the\n   * originals (TEA states/msgs are conventionally immutable).\n   *\n   * Throws only if called before the boot observe has fired AND no msgs have\n   * been recorded — i.e. there is no `finalState` yet. In practice callers\n   * `await runtime.ready` before `dump()`, after which boot has fired.\n   */\n  dump(): Trace<S, M>;\n  /**\n   * Serialize the recording as JSONL (one JSON object per line) — a streamable\n   * format that appends cleanly and survives truncation (a partial tail line\n   * is the only loss). The first line is the boot header\n   * `{ kind: \"boot\", state }`; each subsequent line is\n   * `{ kind: \"step\", msg, state }` for one recorded transition.\n   *\n   * Re-hydrate with {@link parseJSONL}.\n   *\n   * Round-trip fidelity depends on `captureSteps`:\n   *   - `captureSteps: true` — every step line carries its non-null\n   *     post-state, so `parseJSONL(rec.toJSONL())` reconstructs `steps`\n   *     EXACTLY and deep-equals `rec.dump()` (which also has `steps`). Full\n   *     per-step fidelity round-trips.\n   *   - `captureSteps: false` (default) — interior step lines carry\n   *     `state: null` (those post-states were never retained); only the last\n   *     step line carries `finalState`. `parseJSONL` then populates `steps`\n   *     with just the entries that had a non-null state (the final one), so\n   *     the re-hydrated Trace is NOT deep-equal to `rec.dump()` (which has no\n   *     `steps`). It is still fully replay-faithful: `loaded`, `msgs`, and\n   *     `finalState` are intact. Record with `captureSteps: true` if you need\n   *     interior states to survive the round-trip.\n   */\n  toJSONL(): string;\n  /**\n   * Detach the underlying observer. After `stop()`:\n   *   - no new transitions are recorded;\n   *   - `dump()` / `toJSONL()` keep working against the buffered contents;\n   *   - the recorder holds no observer reference into the runtime.\n   *\n   * Idempotent — subsequent calls are no-ops.\n   */\n  stop(): void;\n}\n\n/**\n * Attach a recorder to a Runtime. Subscribes via `runtime.observe`, capturing\n * the boot state as `loaded` and every subsequent non-null msg in order.\n *\n * One-line creation, mirroring `historyTracker`:\n *\n *     const rec = recorder(runtime);\n *     // ... drive the runtime ...\n *     await runtime.ready;            // boot observe has fired\n *     const trace = rec.dump();       // { loaded, msgs, finalState }\n *\n * @param runtime - any `BootingRuntime<S, M>` (a full `Runtime` satisfies it).\n *                  The recorder uses only `observe`, which is total before boot\n *                  — so you attach it to the synchronous `run()` handle to\n *                  capture the boot transition as `loaded`.\n * @param opts    - see {@link RecorderOptions}. Default records everything,\n *                  no step retention.\n */\nexport function recorder<S, M extends { type: string }>(\n  runtime: BootingRuntime<S, M>,\n  opts?: RecorderOptions,\n): Recorder<S, M> {\n  // Clamp sampleRate into (0, 1]. A non-positive or NaN rate would record\n  // nothing (and break replay anchors); default it to 1 (record all). Rates\n  // above 1 are meaningless — clamp to 1.\n  const rawRate = opts?.sampleRate;\n  const sampleRate =\n    rawRate === undefined || Number.isNaN(rawRate) || rawRate <= 0\n      ? 1\n      : Math.min(rawRate, 1);\n  const captureSteps = opts?.captureSteps ?? false;\n\n  // `loaded` is the post-init state captured at the boot observe. `undefined`\n  // sentinel = boot not yet seen; resolved to `S | null` in dump() (null when\n  // the recorder attached after boot and never observed msg === null).\n  let loaded: S | undefined;\n  let sawBoot = false;\n  // The ordered, recorded msgs. Unbounded (the recorder's whole point vs the\n  // bounded historyTracker).\n  const msgs: M[] = [];\n  // Per-step (msg, state) pairs — only populated when captureSteps is on.\n  const steps: { msg: M; state: S }[] = [];\n  // The last observed state — boot state until the first step, then advances\n  // with every recorded OR dropped transition (finalState must reflect the\n  // true latest state even under sampling, so it stays a valid replay oracle\n  // for the unsampled case and an honest \"where the run ended\" marker).\n  let finalState: S | undefined;\n  let stopped = false;\n\n  // The boot transition — the post-init initial state the old `observe(msg ===\n  // null)` arm captured as `loaded` — now arrives via `onBoot` (#47). Always\n  // captured (boot is the replay anchor). It is also the first `finalState`\n  // until the first applied transition advances it.\n  const unboot = runtime.onBoot((state) => {\n    finalState = state;\n    loaded = state;\n    sawBoot = true;\n  });\n\n  const unobserve = runtime.observe((msg, state) => {\n    // finalState tracks the latest state regardless of sampling — it is the\n    // run's endpoint, an anchor, not a sample.\n    finalState = state;\n\n    // Sampling decision. sampleRate === 1 short-circuits to always-record so\n    // the common (faithful) path pays no RNG cost. Math.random() < rate keeps\n    // a `rate` fraction in expectation.\n    if (sampleRate < 1 && Math.random() >= sampleRate) return;\n\n    msgs.push(msg);\n    if (captureSteps) steps.push({ msg, state });\n  });\n\n  return {\n    dump(): Trace<S, M> {\n      if (finalState === undefined) {\n        throw new Error(\n          \"tea recorder: dump() called before any transition was observed. \" +\n            \"Await `runtime.ready` (boot fires the first observe) before dumping.\",\n        );\n      }\n      return {\n        // sawBoot ⇒ `loaded` is the captured boot state; otherwise the\n        // recorder attached post-boot and replay must re-run fresh init.\n        loaded: sawBoot ? (loaded as S) : null,\n        msgs: msgs.slice(),\n        finalState,\n        // Only attach `steps` when captureSteps was requested — keeps the\n        // dumped Trace shape honest about what was retained.\n        ...(captureSteps ? { steps: steps.slice() } : {}),\n      };\n    },\n    toJSONL(): string {\n      if (finalState === undefined) {\n        throw new Error(\n          \"tea recorder: toJSONL() called before any transition was observed. \" +\n            \"Await `runtime.ready` (boot fires the first observe) before serializing.\",\n        );\n      }\n      // Serialize the live snapshot via the shared Trace→JSONL writer so the\n      // recorder and the standalone `traceAttachment` path emit byte-identical\n      // wire format. `dump()` resolves the captureSteps logic (steps present\n      // iff captureSteps was on); `traceToJSONL` then emits a non-null state\n      // on every step line when steps exist, or `null` interior + finalState\n      // on the last line when they don't. The replay path never reads step\n      // states, so the captureSteps:false null-interiors never affect replay.\n      return traceToJSONL(this.dump());\n    },\n    stop(): void {\n      if (stopped) return;\n      stopped = true;\n      unobserve();\n      unboot();\n    },\n  };\n}\n\n/** One line of the JSONL format produced by {@link Recorder.toJSONL}. */\ntype JsonlLine<S, M> =\n  | { readonly kind: \"boot\"; readonly state: S | null }\n  | { readonly kind: \"step\"; readonly msg: M; readonly state: S | null };\n\n/**\n * Re-hydrate a {@link Trace} from the JSONL produced by\n * {@link Recorder.toJSONL}. The inverse of `toJSONL`, so\n * `parseJSONL(rec.toJSONL())` deep-equals `rec.dump()`.\n *\n * Parsing rules:\n *   - The first non-blank line MUST be the boot header `{ kind: \"boot\", state }`.\n *     Its `state` becomes `Trace.loaded`.\n *   - Each `{ kind: \"step\", msg, state }` line contributes `msg` to\n *     `Trace.msgs` and `(msg, state)` to `Trace.steps`.\n *   - `Trace.finalState` is the `state` of the LAST step line, or the boot\n *     `state` when there are no steps (a boot-only trace).\n *\n * Blank lines are skipped (tolerant of trailing newlines / hand-edited files).\n * A malformed line, a missing/duplicate boot header, or a step with `null`\n * final state throws — the trace is unusable for replay and silent corruption\n * is worse than a loud parse error (errors are data; surface them).\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport function parseJSONL<S, M>(jsonl: string): Trace<S, M> {\n  const rawLines = jsonl.split(\"\\n\");\n  let loaded: S | null = null;\n  let sawBoot = false;\n  const msgs: M[] = [];\n  const steps: { msg: M; state: S }[] = [];\n  let finalState: S | null = null;\n  let finalKnown = false;\n\n  for (const [i, rawLine] of rawLines.entries()) {\n    const line = rawLine.trim();\n    if (line === \"\") continue; // tolerate blank / trailing-newline lines\n\n    let parsed: JsonlLine<S, M>;\n    try {\n      parsed = JSON.parse(line) as JsonlLine<S, M>;\n    } catch (err) {\n      throw new Error(\n        `tea recorder: parseJSONL failed on line ${i + 1}: not valid JSON. ${String(err)}`,\n      );\n    }\n\n    if (parsed.kind === \"boot\") {\n      if (sawBoot) {\n        throw new Error(\n          `tea recorder: parseJSONL saw a second boot header on line ${i + 1}. ` +\n            \"A trace has exactly one boot line.\",\n        );\n      }\n      sawBoot = true;\n      loaded = parsed.state;\n      // The boot state is the finalState until a step supersedes it (boot-only\n      // trace case).\n      finalState = parsed.state;\n      finalKnown = parsed.state !== null;\n    } else if (parsed.kind === \"step\") {\n      if (!sawBoot) {\n        throw new Error(\n          `tea recorder: parseJSONL saw a step line before the boot header on line ${i + 1}.`,\n        );\n      }\n      msgs.push(parsed.msg);\n      if (parsed.state !== null) {\n        steps.push({ msg: parsed.msg, state: parsed.state });\n        finalState = parsed.state;\n        finalKnown = true;\n      }\n    } else {\n      throw new Error(\n        `tea recorder: parseJSONL saw an unknown line kind on line ${i + 1}: ` +\n          JSON.stringify((parsed as { kind?: unknown }).kind),\n      );\n    }\n  }\n\n  if (!sawBoot) {\n    throw new Error(\n      \"tea recorder: parseJSONL found no boot header. A trace must start with \" +\n        '{ kind: \"boot\", state }.',\n    );\n  }\n  if (!finalKnown || finalState === null) {\n    throw new Error(\n      \"tea recorder: parseJSONL could not determine finalState — the boot state \" +\n        \"was null and no step carried a non-null state. The trace is unusable for replay.\",\n    );\n  }\n\n  return { loaded, msgs, finalState, steps };\n}\n\n// ---------------------------------------------------------------------------\n// Sentry crash→trace adapters — pure, zero-dependency, Sentry-SHAPED.\n//\n// The killer DevX flow: a machine crashes in prod → its recorded Trace rides\n// along on the Sentry event → one click later you `parseJSONL` it and replay\n// the exact run locally against the (possibly fixed) reducer. These two\n// adapters are the bridge from a `Trace` to the two Sentry surfaces that carry\n// it: an Attachment (the full replayable trace) and Breadcrumbs (a human-\n// readable timeline of the msgs that led to the crash).\n//\n// They take NO dependency on `@sentry/*`. They emit PLAIN OBJECTS whose shapes\n// match Sentry's public `Attachment` and `Breadcrumb` types, and the consumer\n// wires them at their own Sentry boundary (browser or node). This keeps the\n// recorder runnable anywhere a machine runs (a Worker, a Node script, a test)\n// and lets the consumer pin whatever Sentry SDK version they already ship.\n// ---------------------------------------------------------------------------\n\n/**\n * A Sentry-shaped attachment carrying the full {@link Trace} as JSONL. The\n * shape matches Sentry's `Attachment` type so the consumer can hand it\n * straight to `addAttachment(...)` without any adaptation.\n *\n * - `filename`    — `\"tea-trace.jsonl\"`. The name Sentry shows in the UI and\n *                   uses for download; `.jsonl` signals the streamable format.\n * - `data`        — the trace serialized via {@link Recorder.toJSONL}'s format\n *                   (re-hydrate downstream with {@link parseJSONL}).\n * - `contentType` — `\"application/x-ndjson\"`, the standard MIME for\n *                   newline-delimited JSON.\n */\nexport interface TraceAttachment {\n  readonly filename: string;\n  readonly data: string;\n  readonly contentType: string;\n}\n\n/**\n * Serialize a {@link Trace} into a Sentry-shaped attachment so a crash event\n * carries the full, replayable run. Pure — no Sentry import, no I/O. The\n * returned object matches Sentry's `Attachment` shape exactly.\n *\n * The `data` field is JSONL in the same format {@link Recorder.toJSONL}\n * produces, so the home-side flow is `parseJSONL(attachment.data)` →\n * `replayTrace(machine, trace, ctx)`.\n *\n * Consumer wiring (no Sentry import here — the consumer owns the boundary):\n *\n * ```ts\n * import * as Sentry from \"@sentry/browser\"; // or \"@sentry/node\"\n * import { traceAttachment } from \"./internal/persistence/recorder\"; // internal module\n * Sentry.getCurrentScope().addAttachment(traceAttachment(rec.dump()));\n * ```\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport function traceAttachment<S, M extends { type: string }>(\n  trace: Trace<S, M>,\n): TraceAttachment {\n  return {\n    filename: \"tea-trace.jsonl\",\n    data: traceToJSONL(trace),\n    contentType: \"application/x-ndjson\",\n  };\n}\n\n/** A Sentry-shaped breadcrumb. Matches the fields of Sentry's `Breadcrumb`. */\nexport interface TraceBreadcrumb {\n  readonly category: string;\n  readonly type: string;\n  readonly level: string;\n  readonly message: string;\n  readonly data?: Record<string, unknown>;\n}\n\n/** Options for {@link breadcrumbsFromTrace}. */\nexport interface BreadcrumbsOptions<M> {\n  /**\n   * Max breadcrumbs to emit. Default `100` (Sentry's own default breadcrumb\n   * cap). When the trace has more msgs than `limit`, the OLDEST are dropped —\n   * the returned list is the newest-last tail, matching how a Sentry\n   * breadcrumb ring buffer behaves (the crash context is the recent past).\n   */\n  readonly limit?: number;\n  /**\n   * Customize each breadcrumb's `message`. Default uses `msg.type`. Provide a\n   * serializer to surface a richer one-liner (e.g. include an id). The msg is\n   * ALSO always attached verbatim under `data.msg` regardless of this option,\n   * so the structured payload is never lost to the string rendering.\n   */\n  readonly serialize?: (msg: M) => string;\n}\n\n/**\n * Project a {@link Trace}'s recorded msgs into Sentry-shaped breadcrumbs — a\n * human-readable timeline of \"what happened before the crash\". Pure — no\n * Sentry import, no I/O. Each returned object matches Sentry's `Breadcrumb`\n * shape, so the consumer can loop and call `addBreadcrumb(...)`.\n *\n * One breadcrumb per recorded msg, in dispatch order (NEWEST LAST — Sentry\n * renders breadcrumbs oldest-first and the crash is the most recent event).\n * Each breadcrumb:\n *   - `category` — `\"tea\"` (groups them in the Sentry breadcrumb panel).\n *   - `type`     — `\"default\"` (the generic Sentry breadcrumb type).\n *   - `level`    — `\"info\"` (msgs are normal flow; the crash is the event).\n *   - `message`  — `msg.type`, or `serialize(msg)` when provided.\n *   - `data.msg` — the full msg object (structured detail kept verbatim).\n *\n * Capped at `opts.limit` (default 100). When the trace has more msgs than the\n * cap, the OLDEST are dropped and the newest `limit` are kept — the recent\n * lead-up to the crash is the useful context.\n *\n * Consumer wiring (no Sentry import here — the consumer owns the boundary):\n *\n * ```ts\n * import * as Sentry from \"@sentry/browser\"; // or \"@sentry/node\"\n * import { breadcrumbsFromTrace } from \"./internal/persistence/recorder\"; // internal module\n * for (const b of breadcrumbsFromTrace(rec.dump())) Sentry.addBreadcrumb(b);\n * ```\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport function breadcrumbsFromTrace<S, M extends { type: string }>(\n  trace: Trace<S, M>,\n  opts?: BreadcrumbsOptions<M>,\n): TraceBreadcrumb[] {\n  const rawLimit = opts?.limit;\n  // Clamp limit to a non-negative integer. `undefined`/NaN → 100 (Sentry's\n  // default). A negative or zero limit yields an empty list (the caller asked\n  // for no breadcrumbs); fractional values floor (you can't emit half a crumb).\n  const limit =\n    rawLimit === undefined || Number.isNaN(rawLimit)\n      ? 100\n      : Math.max(0, Math.floor(rawLimit));\n  const serialize = opts?.serialize;\n\n  // Keep the NEWEST `limit` msgs (the recent lead-up to the crash). Slicing\n  // from `length - limit` (clamped to 0) preserves dispatch order within the\n  // kept window. Note we do NOT use `slice(-limit)`: `slice(-0)` is `slice(0)`\n  // (JS treats -0 as 0), which would return the WHOLE array for `limit: 0`.\n  const start = Math.max(0, trace.msgs.length - limit);\n  const kept = start === 0 ? trace.msgs : trace.msgs.slice(start);\n\n  const crumbs: TraceBreadcrumb[] = [];\n  for (const msg of kept) {\n    crumbs.push({\n      category: \"tea\",\n      type: \"default\",\n      level: \"info\",\n      message: serialize ? serialize(msg) : msg.type,\n      // Full msg kept verbatim so the structured payload survives even when\n      // `message` is a terse one-liner. Cast: a Msg is a `{ type: string }`\n      // record, which is a `Record<string, unknown>` for Sentry's `data`.\n      data: { msg: msg as unknown as Record<string, unknown> },\n    });\n  }\n  return crumbs;\n}\n\n// ---------------------------------------------------------------------------\n// traceToJSONL — serialize a STANDALONE Trace to JSONL (the dump→file path).\n//\n// `Recorder.toJSONL()` serializes the recorder's live buffers. `traceAttachment`\n// works over a plain `Trace` value (a `dump()` snapshot or a `parseJSONL`\n// result), which has no recorder behind it — so it needs a Trace→JSONL\n// function. This is the same wire format `Recorder.toJSONL` emits and\n// `parseJSONL` reads, so `parseJSONL(traceToJSONL(trace))` round-trips.\n//\n// When `trace.steps` is present (captureSteps was on, or the trace came from\n// parseJSONL), every step line carries its post-state. When absent, interior\n// step states are unknown — emitted as `null`, with `finalState` on the LAST\n// step line (identical to the captureSteps:false path in `Recorder.toJSONL`).\n// ---------------------------------------------------------------------------\nfunction traceToJSONL<S, M>(trace: Trace<S, M>): string {\n  const lines: string[] = [];\n  lines.push(JSON.stringify({ kind: \"boot\", state: trace.loaded }));\n\n  const steps = trace.steps;\n  for (let i = 0; i < trace.msgs.length; i++) {\n    const msg = trace.msgs[i];\n    const stepState = steps\n      ? steps[i]?.state\n      : i === trace.msgs.length - 1\n        ? trace.finalState\n        : null;\n    lines.push(JSON.stringify({ kind: \"step\", msg, state: stepState }));\n  }\n  return lines.join(\"\\n\");\n}\n","// ---------------------------------------------------------------------------\n// trace-replay — replay a recorded Trace against a machine and diff the state.\n//\n// This is the back half of the record/replay feature. `../recorder` captures\n// a run (`loaded` + `msgs` + `finalState`); this module feeds that input\n// through the core `replay(machine, { msgs, ctx, loaded })` fold and asks:\n//\n//     does the current reducer still produce the SAME final state for this\n//     recorded input?\n//\n// Equal ⇒ the reducer is behavior-compatible with the recording. Diverged ⇒\n// the reducer changed for that input, and the divergence path\n// (`state.queue[2].status`) points at exactly the cell that drifted. This is\n// the regression / production-repro tool: record a prod incident, replay it\n// against the fixed reducer locally, confirm the fix changes the state at the\n// path you expected — or catch an unintended drift before it ships.\n//\n// Standalone by design. It imports ONLY the `Trace` type from `../recorder`\n// and the `replay` engine from `../index`. The deep-equal + first-divergence\n// path finder is self-contained (no external diff lib) — a richer pretty-diff\n// lands in `../devtools` later; trace-replay stays dependency-free so it can\n// run anywhere a machine runs (CI, a Worker, a Node script).\n// ---------------------------------------------------------------------------\n\nimport { type Cmd, type Machine, replay, type Sub } from \"../../../index\";\nimport type { Trace } from \"../recorder\";\nimport { indexPath, keyPath, typeOf, unionKeys } from \"./state-walk\";\n\n/**\n * The outcome of {@link replayTrace}.\n *\n * @typeParam S - the machine's State type.\n */\nexport interface ReplayResult<S> {\n  /** `true` iff the recomputed final state deep-equals the trace's `finalState`. */\n  matches: boolean;\n  /** The trace's recorded `finalState` — what the run originally produced. */\n  expected: S;\n  /** The state the current reducer produced for the same input. */\n  actual: S;\n  /**\n   * Present iff `matches` is `false`. The FIRST point of divergence found by\n   * a deterministic pre-order walk:\n   *   - `path`     — a dotted/indexed access path from the state root, e.g.\n   *                  `state.queue[2].status` or `state` for a root-level\n   *                  scalar mismatch.\n   *   - `expected` — the recorded value at that path.\n   *   - `actual`   — the recomputed value at that path.\n   */\n  divergence?: { path: string; expected: unknown; actual: unknown };\n}\n\n/**\n * Replay a recorded {@link Trace} against `machine` and diff the recomputed\n * final state against the recorded one.\n *\n * Runs the core pure fold `replay(machine, { msgs: trace.msgs, ctx,\n * loaded: trace.loaded })` — init + update only, never `interpret`, never a\n * `Store`, never a live subscription (see `replay` in ../index). The `ctx` is\n * supplied fresh by the caller: the trace is the INPUT (loaded + msgs); ctx is\n * the ENVIRONMENT the reducer runs against now.\n *\n * @param machine - the machine to replay against. Mutating its reducer (the\n *                  whole point of a regression check) is what makes a recorded\n *                  trace diverge.\n * @param trace   - a Trace from `../recorder` (live `dump()` or a re-hydrated\n *                  `parseJSONL(...)`).\n * @param ctx     - the runtime ctx, supplied fresh at replay time.\n */\nexport function replayTrace<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  trace: Trace<S, M>,\n  ctx: Ctx,\n): ReplayResult<S> {\n  const result = replay(machine, {\n    msgs: trace.msgs,\n    ctx,\n    loaded: trace.loaded,\n  });\n  const actual = result.state;\n  const expected = trace.finalState;\n\n  const divergence = firstDivergence(expected, actual, \"state\");\n  if (divergence === null) {\n    return { matches: true, expected, actual };\n  }\n  return { matches: false, expected, actual, divergence };\n}\n\n/**\n * Order-insensitive structural deep-equality — the comparator the\n * record/replay lane owns, exposed so consumers (e.g. `@demlik/tea/parity`'s\n * `parityEqual`) reuse it rather than adding a fourth deep-compare. It is one\n * of three structural walkers in the package, divergent on purpose:\n * this `deepEqual` returns a boolean verdict (order-insensitive, for\n * replay/parity equality), `devtools`'s `diffState` returns a change list (for\n * a human-readable diff view), and `testing`'s `__deepEqual` is the assertion\n * helpers' internal compare — same shape, three jobs, not one to collapse.\n * `true` iff `a` and `b` are structurally equal under {@link firstDivergence}'s\n * walk (object keys compared order-insensitively, arrays index-by-index).\n */\nexport function deepEqual(a: unknown, b: unknown): boolean {\n  return firstDivergence(a, b, \"state\") === null;\n}\n\n// === deep-equal + first-divergence path finder ===\n//\n// One walk does both jobs: it returns the FIRST point where `expected` and\n// `actual` differ (as a path + the two values), or `null` when they are\n// deeply equal. \"First\" is defined by a deterministic pre-order traversal:\n// the node itself, then its children in a stable key order (array index\n// order; object keys sorted so the result does not depend on insertion\n// order — two states with the same data but different key order are equal,\n// and the reported path for a real mismatch is reproducible run-to-run).\n//\n// The path grammar (`typeOf`, `indexPath`/`keyPath` segments, `unionKeys`\n// order) is shared with devtools' `diffState` via `./state-walk`, so the two\n// walkers print the SAME path for the same cell by construction. Only the leaf\n// policy differs, on purpose: first-hit here, collect-all there.\n//\n// Scope: TEA state is plain JSON-shaped data (the substrate's __DEV__ guards\n// reject closures in Cmds, and states are conventionally serializable). So\n// the walk handles: primitives, null/undefined, arrays, and plain objects.\n// It treats other object kinds (Date, Map, Set, class instances) by reference\n// identity + a structural fallback via Object.entries — sufficient for the\n// JSON-shaped states this tool targets; a richer differ lives in ../devtools.\n\n/** A divergence record, or `null` when the two values are deeply equal. */\ntype Divergence = { path: string; expected: unknown; actual: unknown } | null;\n\nfunction firstDivergence(\n  expected: unknown,\n  actual: unknown,\n  path: string,\n): Divergence {\n  // Identity / primitive fast path. Handles same-reference, and equal\n  // primitives. `Object.is` so NaN === NaN and +0 ≠ -0 (matches structural\n  // equality intent better than ===).\n  if (Object.is(expected, actual)) return null;\n\n  const te = typeOf(expected);\n  const ta = typeOf(actual);\n  // Different kinds at this node (e.g. object vs array, number vs string,\n  // present vs null) — this node IS the divergence.\n  if (te !== ta) return { path, expected, actual };\n\n  if (te === \"array\") {\n    const ae = expected as unknown[];\n    const aa = actual as unknown[];\n    if (ae.length !== aa.length) {\n      // Length mismatch reported at the array node itself — the shape differs,\n      // which is more informative than an arbitrary element index.\n      return { path, expected, actual };\n    }\n    for (let i = 0; i < ae.length; i++) {\n      const d = firstDivergence(ae[i], aa[i], indexPath(path, i));\n      if (d !== null) return d;\n    }\n    return null;\n  }\n\n  if (te === \"object\") {\n    const oe = expected as Record<string, unknown>;\n    const oa = actual as Record<string, unknown>;\n    // Sorted union of keys for deterministic traversal. A key present in one\n    // but absent in the other diverges at that child path (its value is\n    // `undefined` on the missing side).\n    for (const key of unionKeys(oe, oa)) {\n      const d = firstDivergence(oe[key], oa[key], keyPath(path, key));\n      if (d !== null) return d;\n    }\n    return null;\n  }\n\n  // Primitives (string/number/boolean/bigint/symbol/function) that failed the\n  // Object.is fast path, or null/undefined that differ — this node diverges.\n  return { path, expected, actual };\n}\n"]}