@demlik/tea 0.1.0 → 0.1.1

package/dist/chunk-D5EQDLDV.js

@@ -0,0 +1,186 @@
+import { createSnapshot } from './chunk-EIZJTYKR.js';
+import { deadlineSub } from './chunk-QGZW4W3E.js';
+import { queueAdapter } from './chunk-HJO6VNQI.js';
+
+// src/monitored-run/index.ts
+function safetyTimerId(runId, progressSeq) {
+  return `monitored:safety:${runId}:${progressSeq}`;
+}
+function createMonitoredRun(config = {}) {
+  const stages = config.stages ?? [];
+  const isPipeline = stages.length > 0;
+  const wq = queueAdapter();
+  const snap = config.snapshotEvery !== void 0 ? createSnapshot({
+    every: config.snapshotEvery,
+    ...config.snapshotKey !== void 0 ? { key: config.snapshotKey } : {}
+  }) : null;
+  function init() {
+    return {
+      phase: "running",
+      runId: "",
+      stepStates: [],
+      startedAt: 0,
+      lastProgressAt: 0,
+      progressSeq: 0,
+      failure: null,
+      // A default snapshot slice even without the brick → uniform shape. When
+      // `snap` is null the slice is created with a throwaway cadence; its
+      // `record` is never called, so the cadence value is inert.
+      snapshot: (snap ?? createSnapshot({ every: 1 })).init()
+    };
+  }
+  function seedStages(at) {
+    let queue = [];
+    stages.forEach((stage, i) => {
+      queue = wq.enqueue(queue, stage, at, `stage:${i}`).next;
+    });
+    const claimed = wq.claim(queue, at);
+    return claimed ? claimed.next : queue;
+  }
+  function currentStage(s) {
+    return s.stepStates.find((i) => i.status === "running");
+  }
+  function start(s, runId, at) {
+    const next = {
+      ...s,
+      phase: "running",
+      runId,
+      stepStates: isPipeline ? seedStages(at) : [],
+      startedAt: at,
+      lastProgressAt: at,
+      progressSeq: 0,
+      failure: null
+    };
+    return [next, []];
+  }
+  function bumpProgress(s, at) {
+    return { ...s, lastProgressAt: at, progressSeq: s.progressSeq + 1 };
+  }
+  function recordSnapshot(s, payload, at) {
+    if (snap === null) return [s, []];
+    const [snapshot, cmds] = snap.record(s.snapshot, payload, at);
+    return [{ ...s, snapshot }, cmds];
+  }
+  function progress(s, payload, at) {
+    if (s.phase === "done" || s.phase === "failed") return [s, []];
+    const bumped = {
+      ...bumpProgress(s, at),
+      phase: "running"
+    };
+    return recordSnapshot(bumped, payload, at);
+  }
+  function markStale(s) {
+    if (s.phase !== "running") return [s, []];
+    return [{ ...s, phase: "stale" }, []];
+  }
+  function advance(s, payload, result, at) {
+    if (s.phase === "done" || s.phase === "failed") return [s, []];
+    if (result.kind === "fail") {
+      const failed = {
+        ...s,
+        phase: "failed",
+        failure: {
+          reason: "stage",
+          stage: currentStage(s)?.input,
+          error: result.error
+        }
+      };
+      return [failed, []];
+    }
+    const bumped = bumpProgress(s, at);
+    if (!isPipeline) {
+      const done = { ...bumped, phase: "done" };
+      return finishWithSnapshot(done, payload, at);
+    }
+    const current = currentStage(s);
+    const afterDone = current !== void 0 ? wq.markDone(s.stepStates, current.id).next : s.stepStates;
+    const claimed = wq.claim(afterDone, at);
+    if (claimed === null) {
+      const done = {
+        ...bumped,
+        phase: "done",
+        stepStates: afterDone
+      };
+      return finishWithSnapshot(done, payload, at);
+    }
+    const moved = {
+      ...bumped,
+      stepStates: claimed.next
+    };
+    return recordSnapshot(moved, payload, at);
+  }
+  function finishWithSnapshot(s, payload, at) {
+    if (snap === null) return [s, []];
+    const [snapshot, cmds] = snap.force(s.snapshot, payload, at);
+    return [{ ...s, snapshot }, cmds];
+  }
+  function onDeadline(s, msg) {
+    if (s.phase === "done" || s.phase === "failed") return [s, []];
+    if (s.runId === "") return [s, []];
+    if (msg.id !== safetyTimerId(s.runId, s.progressSeq)) return [s, []];
+    const failed = {
+      ...s,
+      phase: "failed",
+      failure: { reason: "deadline", at: msg.atMs }
+    };
+    return [failed, []];
+  }
+  function boot(s, at) {
+    if (s.phase === "done" || s.phase === "failed") return [s, []];
+    const [bootedSnapshot] = (snap ?? createSnapshot({ every: 1 })).boot(
+      s.snapshot
+    );
+    const reseeded = {
+      ...s,
+      phase: "running",
+      lastProgressAt: at,
+      progressSeq: s.progressSeq + 1,
+      snapshot: bootedSnapshot
+      // Any stage left `running` mid-flight stays the running position; the
+      // queue is already correct (a single in-flight stage). resetRunningOp is
+      // NOT applied — unlike a work pool, a monitored run has exactly one
+      // in-flight stage and resuming it (not re-queuing it) is the correct
+      // cold-wake behavior.
+    };
+    return [reseeded, []];
+  }
+  function subs(s) {
+    if (config.deadlineMs === void 0) return [];
+    if (s.runId === "") return [];
+    if (s.phase !== "running" && s.phase !== "stale") return [];
+    return [
+      deadlineSub(
+        safetyTimerId(s.runId, s.progressSeq),
+        s.lastProgressAt + config.deadlineMs
+      )
+    ];
+  }
+  function handlers(ports) {
+    const active = snap ?? createSnapshot({ every: 1 });
+    return active.handlers({ store: ports.store });
+  }
+  function confirmSnapshot(s, msg) {
+    if (snap === null) return s;
+    const [confirmed] = snap.confirm(s.snapshot, msg);
+    return { ...s, snapshot: confirmed };
+  }
+  return {
+    init,
+    start,
+    progress,
+    markStale,
+    advance,
+    onDeadline,
+    boot,
+    confirmSnapshot,
+    subs,
+    handlers
+  };
+}
+function liftRun(state, [slice, cmds]) {
+  return [{ ...state, run: slice }, cmds];
+}
+
+export { createMonitoredRun, liftRun };
+//# sourceMappingURL=chunk-D5EQDLDV.js.map
+//# sourceMappingURL=chunk-D5EQDLDV.js.map

package/dist/chunk-D5EQDLDV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/monitored-run/index.ts"],"names":[],"mappings":"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","file":"chunk-D5EQDLDV.js","sourcesContent":["/**\n * @demlik/tea/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 with the uniform L2 contract `resilient-call` established:\n * `init()`, the verbs (`start` / `advance` / `progress` / `onDeadline` /\n * `boot`), `subs(state)`, and `handlers(ports)`.\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 checkpoint Cmd is emitted (interpreted by the spliced snapshot\n *     `handlers`), so a crashed run restarts from the last durable checkpoint\n *     rather than from zero. Omit it → no checkpointing.\n *\n * ## Why the run lifecycle is INLINE (run-tracker not extracted)\n *\n * The phase union (`running` / `done` / `failed` / `stale`) and its\n * bookkeeping (`runId`, `startedAt`, `lastProgressAt`, `progressSeq`) live\n * directly on this 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 only clock read is `Date.now()` inside the snapshot\n *     `handlers` port (the effect boundary), exactly as `../snapshot` stamps it.\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 *   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 *     run_deadline: (s, m) => lift(s, run.onDeadline(s.run, m)),\n *     boot:     (s, m) => lift(s, run.boot(s.run, m.at)),\n *   },\n *   subscriptions: (s) => run.subs(s.run),\n *   subscribe: { deadline: subscribeDeadline },\n *   interpret: run.handlers({ store: r2 }),\n */\n\nimport {\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineSub,\n  subscribeDeadline,\n} from \"../deadline\";\nimport type { Cmd, Interpret } from \"../index\";\nimport {\n  createSnapshot,\n  type SnapshotFailedMsg,\n  type SnapshotLoadCmd,\n  type SnapshotLoadedMsg,\n  type SnapshotLoadFailedMsg,\n  type SnapshotSavedMsg,\n  type SnapshotState,\n  type SnapshotStore,\n  type SnapshotWriteCmd,\n} from \"../snapshot\";\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 * Run lifecycle phase. Discriminated on `phase`:\n *\n *   - `running` — the run is live. Carries the current pipeline position\n *     (`stepStates` is the stage queue; the single `running` item in it is the\n *     current stage, `undefined` for a single-shot run) and the watchdog\n *     bookkeeping (`lastProgressAt` / `progressSeq` keying the safety alarm).\n *   - `stale`   — a soft \"no progress observed\" mark the consumer can set and\n *     clear; the run is 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; `failure` carries why.\n */\nexport type RunPhase = \"running\" | \"stale\" | \"done\" | \"failed\";\n\n/**\n * The slice. Plain data end to end:\n *   - `phase`          — the lifecycle discriminant.\n *   - `runId`          — host-minted run identity, stamped at `start` (the\n *                        machine never mints — see the audit seed's\n *                        \"run identity is host-minted\").\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 *   - `failure`        — present iff `phase === \"failed\"`; the typed reason.\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 */\nexport interface MonitoredRunState<Stage> {\n  readonly phase: RunPhase;\n  readonly runId: string;\n  readonly stepStates: readonly QueueItem<Stage>[];\n  readonly startedAt: number;\n  readonly lastProgressAt: number;\n  readonly progressSeq: number;\n  readonly failure: RunFailure<Stage> | null;\n  readonly snapshot: SnapshotState;\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/** Ports the consumer supplies to `handlers` — just the checkpoint store. */\nexport interface MonitoredRunPorts<V> {\n  /** Where periodic checkpoints are written (R2 / KV / DO sub-key / Map). */\n  readonly store: SnapshotStore<V>;\n}\n\n// ===========================================================================\n// Sub-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. The clock is read only inside the snapshot `handlers` port.\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 starting slice for a never-started run. `runId` is filled at `start`. */\n  function init(): MonitoredRunState<Stage> {\n    return {\n      phase: \"running\",\n      runId: \"\",\n      stepStates: [],\n      startedAt: 0,\n      lastProgressAt: 0,\n      progressSeq: 0,\n      failure: null,\n      // A default snapshot slice even without the brick → uniform shape. When\n      // `snap` is null the slice is created with a throwaway cadence; its\n      // `record` is never called, so the cadence value is inert.\n      snapshot: (snap ?? createSnapshot<V>({ every: 1 })).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    const next: MonitoredRunState<Stage> = {\n      ...s,\n      phase: \"running\",\n      runId,\n      stepStates: isPipeline ? seedStages(at) : [],\n      startedAt: at,\n      lastProgressAt: at,\n      progressSeq: 0,\n      failure: null,\n    };\n    return [next, []];\n  }\n\n  /**\n   * Bump the watchdog clock: set `lastProgressAt`/`progressSeq` so the safety\n   * alarm Sub id changes and the substrate re-arms a fresh deadline. Shared by\n   * `progress` and `advance`. PURE.\n   */\n  function bumpProgress(\n    s: MonitoredRunState<Stage>,\n    at: number,\n  ): MonitoredRunState<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 on a settled run\n   * (`done` / `failed`) — a late progress event after the run ended is ignored.\n   * 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 === \"done\" || s.phase === \"failed\") 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: 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 run. PURE — `at` is the 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 === \"done\" || s.phase === \"failed\") 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 Sub-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 substrate 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 run (empty `runId` → `subs` armed nothing, 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    if (s.phase === \"done\" || s.phase === \"failed\") return [s, []];\n    // A never-started run has no host-minted runId, so `subs` never armed a\n    // watchdog for it. Any alarm reaching this slice is a born-live/rogue fire;\n    // refuse to auto-fail a run that was never started.\n    if (s.runId === \"\") 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 run. Emits NO Cmd — re-emitting the current stage's\n   * outstanding effect is the CONSUMER's job (it knows the per-stage Cmd), the\n   * audit machine's `outstandingEffect(stage)` pattern. PURE.\n   */\n  function boot(\n    s: MonitoredRunState<Stage>,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase === \"done\" || s.phase === \"failed\") 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] = (snap ?? createSnapshot<V>({ every: 1 })).boot(\n      s.snapshot,\n    );\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  // === Subs ================================================================\n\n  /**\n   * Pre-wired subscriptions: the no-progress safety deadline, armed only while\n   * the run is live (`running` / `stale`) AND a `deadlineMs` is configured. The\n   * Sub id is keyed on `progressSeq`, so every progress event retires the old\n   * alarm and the substrate arms a fresh one at the new `lastProgressAt +\n   * deadlineMs` — a self-rearming watchdog with no manual `clearTimeout`. A\n   * settled run desires no subs. Wire `subscribe: { deadline: subscribeDeadline }`.\n   *\n   * A NEVER-STARTED slice (`init()`) is `running` with an empty `runId` and a\n   * zero `lastProgressAt`. Without the `runId` gate it would arm a deadline at\n   * `0 + deadlineMs` — already in the past — which fires immediately and\n   * auto-fails a run that never began (the \"born live\" defect). `start` is the\n   * only verb that stamps a host-minted `runId`, so `runId !== \"\"` is the exact\n   * \"has this run actually been started?\" predicate: a pre-start slice arms\n   * nothing, and the watchdog only exists once a real run is in flight.\n   */\n  function subs(s: MonitoredRunState<Stage>): readonly DeadlineSub[] {\n    if (config.deadlineMs === undefined) return [];\n    if (s.runId === \"\") 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  // === Handlers ============================================================\n\n  /**\n   * Pre-wired interpret handler for the checkpoint write. Delegates wholesale to\n   * `../snapshot`'s `handlers` (which performs the `put` and routes Ok →\n   * `snapshot_saved` / Err → `snapshot_failed` via Railway — the write never\n   * rejects into the runtime). When checkpointing is disabled (`snapshotEvery`\n   * omitted), no `snapshot_write` Cmd is ever emitted, so the returned map is an\n   * inert no-op handler — kept for a uniform `handlers(ports)` call shape.\n   *\n   * Fold the `snapshot_saved` Msg back through this knob's `confirmSnapshot`\n   * verb to advance the durable watermark.\n   */\n  function handlers(\n    ports: MonitoredRunPorts<V>,\n  ): Interpret<\n    | SnapshotSavedMsg\n    | SnapshotFailedMsg\n    | SnapshotLoadedMsg<V>\n    | SnapshotLoadFailedMsg,\n    SnapshotWriteCmd<V> | SnapshotLoadCmd,\n    unknown\n  > {\n    const active = snap ?? createSnapshot<V>({ every: 1 });\n    return active.handlers({ store: ports.store });\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_saved` Msg here.\n   */\n  function confirmSnapshot(\n    s: MonitoredRunState<Stage>,\n    msg: SnapshotSavedMsg,\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    init,\n    start,\n    progress,\n    markStale,\n    advance,\n    onDeadline,\n    boot,\n    confirmSnapshot,\n    subs,\n    handlers,\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\n/**\n * Re-export the deadline Sub primitives so consumers (and tests) wire one\n * import: `subscribeDeadline` is the `subscribe` cell, `deadlineSub` builds the\n * Sub literal this knob's `subs` emits.\n */\nexport { subscribeDeadline, deadlineSub };\nexport type {\n  DeadlineSub,\n  DeadlineExceeded,\n  SnapshotSavedMsg,\n  SnapshotWriteCmd,\n};\n"]}

package/dist/chunk-EDGDR5XX.js

@@ -0,0 +1,60 @@
+import { replay } from './chunk-2WZHS4P2.js';
+
+// src/trace-replay/index.ts
+function replayTrace(machine, trace, ctx) {
+  const result = replay(machine, {
+    msgs: trace.msgs,
+    ctx,
+    loaded: trace.loaded
+  });
+  const actual = result.state;
+  const expected = trace.finalState;
+  const divergence = firstDivergence(expected, actual, "state");
+  if (divergence === null) {
+    return { matches: true, expected, actual };
+  }
+  return { matches: false, expected, actual, divergence };
+}
+function deepEqual(a, b) {
+  return firstDivergence(a, b, "state") === null;
+}
+function firstDivergence(expected, actual, path) {
+  if (Object.is(expected, actual)) return null;
+  const te = typeOf(expected);
+  const ta = typeOf(actual);
+  if (te !== ta) return { path, expected, actual };
+  if (te === "array") {
+    const ae = expected;
+    const aa = actual;
+    if (ae.length !== aa.length) {
+      return { path, expected, actual };
+    }
+    for (let i = 0; i < ae.length; i++) {
+      const d = firstDivergence(ae[i], aa[i], `${path}[${i}]`);
+      if (d !== null) return d;
+    }
+    return null;
+  }
+  if (te === "object") {
+    const oe = expected;
+    const oa = actual;
+    const keys = [.../* @__PURE__ */ new Set([...Object.keys(oe), ...Object.keys(oa)])].sort();
+    for (const key of keys) {
+      const d = firstDivergence(oe[key], oa[key], `${path}.${key}`);
+      if (d !== null) return d;
+    }
+    return null;
+  }
+  return { path, expected, actual };
+}
+function typeOf(v) {
+  if (v === null) return "null";
+  if (v === void 0) return "undefined";
+  if (Array.isArray(v)) return "array";
+  if (typeof v === "object") return "object";
+  return "primitive";
+}
+
+export { deepEqual, replayTrace };
+//# sourceMappingURL=chunk-EDGDR5XX.js.map
+//# sourceMappingURL=chunk-EDGDR5XX.js.map

package/dist/chunk-EDGDR5XX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/trace-replay/index.ts"],"names":[],"mappings":"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","file":"chunk-EDGDR5XX.js","sourcesContent":["// ---------------------------------------------------------------------------\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\";\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 single comparator this\n * package owns, exposed so consumers (e.g. `@demlik/tea/parity`'s `diff`)\n * reuse it rather than adding a second deep-compare. `true` iff `a` and `b`\n * are structurally equal under {@link firstDivergence}'s walk (object keys\n * 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// === self-contained 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// 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], `${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    // Union of keys, sorted 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    const keys = [...new Set([...Object.keys(oe), ...Object.keys(oa)])].sort();\n    for (const key of keys) {\n      const d = firstDivergence(oe[key], oa[key], `${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\n/** Coarse type tag used by the divergence walk to decide how to recurse. */\nfunction typeOf(\n  v: unknown,\n): \"null\" | \"undefined\" | \"array\" | \"object\" | \"primitive\" {\n  if (v === null) return \"null\";\n  if (v === undefined) return \"undefined\";\n  if (Array.isArray(v)) return \"array\";\n  if (typeof v === \"object\") return \"object\";\n  return \"primitive\";\n}\n"]}

package/dist/chunk-EIZJTYKR.js

@@ -0,0 +1,93 @@
+import { tryInterpret } from './chunk-2WZHS4P2.js';
+import { Cmd } from './chunk-BNJYE4AU.js';
+
+// src/snapshot/index.ts
+var DEFAULT_SNAPSHOT_KEY = "@@snapshot";
+function snapshotSaved(seq, at) {
+  return { type: "snapshot_saved", seq, at };
+}
+function snapshotFailed(seq, error) {
+  return { type: "snapshot_failed", seq, error };
+}
+function snapshotLoaded(payload) {
+  return { type: "snapshot_loaded", payload };
+}
+function snapshotLoadFailed(error) {
+  return { type: "snapshot_load_failed", error };
+}
+function createSnapshot(config) {
+  const every = config.every >= 1 ? config.every : 1;
+  const key = config.key ?? DEFAULT_SNAPSHOT_KEY;
+  function emitWrite(state, payload, at) {
+    const seq = state.seq + 1;
+    const next = { ...state, sinceLast: 0, seq };
+    const cmd = {
+      type: "snapshot_write",
+      key,
+      seq,
+      at,
+      payload
+    };
+    return [next, [cmd]];
+  }
+  return {
+    init() {
+      return { sinceLast: 0, seq: 0, lastSavedSeq: null, lastSavedAt: null };
+    },
+    record(state, payload, at) {
+      const sinceLast = state.sinceLast + 1;
+      if (sinceLast < every) {
+        return [{ ...state, sinceLast }, Cmd.none];
+      }
+      return emitWrite(state, payload, at);
+    },
+    force(state, payload, at) {
+      return emitWrite(state, payload, at);
+    },
+    confirm(state, msg) {
+      if (state.lastSavedSeq !== null && msg.seq <= state.lastSavedSeq) {
+        return [state, Cmd.none];
+      }
+      return [
+        { ...state, lastSavedSeq: msg.seq, lastSavedAt: msg.at },
+        Cmd.none
+      ];
+    },
+    boot(state) {
+      return [{ ...state, sinceLast: 0 }, Cmd.none];
+    },
+    requestLoad(state) {
+      const cmd = { type: "snapshot_load", key };
+      return [state, [cmd]];
+    },
+    handlers(ports) {
+      const { store } = ports;
+      return {
+        // The write effect. Performs the `put`; on success the saved `seq`/`at`
+        // ride the `snapshot_saved` Msg back into `confirm`; on failure the
+        // error rides `snapshot_failed`. Railway via the core's `tryInterpret`
+        // (matching every other module's handler) — the handler always resolves
+        // with a Msg, never rejects into the runtime.
+        snapshot_write: tryInterpret(
+          (cmd) => store.put(cmd.key, cmd.payload),
+          (_value, cmd) => snapshotSaved(cmd.seq, cmd.at),
+          (error, cmd) => snapshotFailed(cmd.seq, error)
+        ),
+        // The read effect — the recovery half. Performs the `get`; on success
+        // the recovered payload (or `null` when no checkpoint exists) rides the
+        // `snapshot_loaded` Msg the consumer folds into `init`'s loaded branch;
+        // on failure the error rides `snapshot_load_failed`. Same Railway
+        // discipline via `tryInterpret` — the read never rejects into the runtime.
+        snapshot_load: tryInterpret(
+          (cmd) => store.get(cmd.key),
+          (payload) => snapshotLoaded(payload),
+          (error) => snapshotLoadFailed(error)
+        )
+      };
+    }
+  };
+}
+
+export { createSnapshot, snapshotFailed, snapshotLoadFailed, snapshotLoaded, snapshotSaved };
+//# sourceMappingURL=chunk-EIZJTYKR.js.map
+//# sourceMappingURL=chunk-EIZJTYKR.js.map

package/dist/chunk-EIZJTYKR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/snapshot/index.ts"],"names":[],"mappings":";;;;AAsGA,IAAM,oBAAA,GAAuB,YAAA;AAkKtB,SAAS,aAAA,CAAc,KAAa,EAAA,EAA8B;AACvE,EAAA,OAAO,EAAE,IAAA,EAAM,gBAAA,EAAkB,GAAA,EAAK,EAAA,EAAG;AAC3C;AAGO,SAAS,cAAA,CAAe,KAAa,KAAA,EAAmC;AAC7E,EAAA,OAAO,EAAE,IAAA,EAAM,iBAAA,EAAmB,GAAA,EAAK,KAAA,EAAM;AAC/C;AAGO,SAAS,eAAkB,OAAA,EAAyC;AACzE,EAAA,OAAO,EAAE,IAAA,EAAM,iBAAA,EAAmB,OAAA,EAAQ;AAC5C;AAGO,SAAS,mBAAmB,KAAA,EAAuC;AACxE,EAAA,OAAO,EAAE,IAAA,EAAM,sBAAA,EAAwB,KAAA,EAAM;AAC/C;AAmHO,SAAS,eAAkB,MAAA,EAAyC;AAIzE,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,KAAA,IAAS,CAAA,GAAI,OAAO,KAAA,GAAQ,CAAA;AACjD,EAAA,MAAM,GAAA,GAAM,OAAO,GAAA,IAAO,oBAAA;AAQ1B,EAAA,SAAS,SAAA,CACP,KAAA,EACA,OAAA,EACA,EAAA,EAC0C;AAC1C,IAAA,MAAM,GAAA,GAAM,MAAM,GAAA,GAAM,CAAA;AACxB,IAAA,MAAM,OAAsB,EAAE,GAAG,KAAA,EAAO,SAAA,EAAW,GAAG,GAAA,EAAI;AAC1D,IAAA,MAAM,GAAA,GAA2B;AAAA,MAC/B,IAAA,EAAM,gBAAA;AAAA,MACN,GAAA;AAAA,MACA,GAAA;AAAA,MACA,EAAA;AAAA,MACA;AAAA,KACF;AACA,IAAA,OAAO,CAAC,IAAA,EAAM,CAAC,GAAG,CAAC,CAAA;AAAA,EACrB;AAEA,EAAA,OAAO;AAAA,IACL,IAAA,GAAsB;AACpB,MAAA,OAAO,EAAE,WAAW,CAAA,EAAG,GAAA,EAAK,GAAG,YAAA,EAAc,IAAA,EAAM,aAAa,IAAA,EAAK;AAAA,IACvE,CAAA;AAAA,IAEA,MAAA,CAAO,KAAA,EAAO,OAAA,EAAS,EAAA,EAAI;AACzB,MAAA,MAAM,SAAA,GAAY,MAAM,SAAA,GAAY,CAAA;AAEpC,MAAA,IAAI,YAAY,KAAA,EAAO;AACrB,QAAA,OAAO,CAAC,EAAE,GAAG,OAAO,SAAA,EAAU,EAAG,IAAI,IAAI,CAAA;AAAA,MAC3C;AAEA,MAAA,OAAO,SAAA,CAAU,KAAA,EAAO,OAAA,EAAS,EAAE,CAAA;AAAA,IACrC,CAAA;AAAA,IAEA,KAAA,CAAM,KAAA,EAAO,OAAA,EAAS,EAAA,EAAI;AACxB,MAAA,OAAO,SAAA,CAAU,KAAA,EAAO,OAAA,EAAS,EAAE,CAAA;AAAA,IACrC,CAAA;AAAA,IAEA,OAAA,CAAQ,OAAO,GAAA,EAAK;AAGlB,MAAA,IAAI,MAAM,YAAA,KAAiB,IAAA,IAAQ,GAAA,CAAI,GAAA,IAAO,MAAM,YAAA,EAAc;AAChE,QAAA,OAAO,CAAC,KAAA,EAAO,GAAA,CAAI,IAAI,CAAA;AAAA,MACzB;AACA,MAAA,OAAO;AAAA,QACL,EAAE,GAAG,KAAA,EAAO,YAAA,EAAc,IAAI,GAAA,EAAK,WAAA,EAAa,IAAI,EAAA,EAAG;AAAA,QACvD,GAAA,CAAI;AAAA,OACN;AAAA,IACF,CAAA;AAAA,IAEA,KAAK,KAAA,EAAO;AACV,MAAA,OAAO,CAAC,EAAE,GAAG,KAAA,EAAO,WAAW,CAAA,EAAE,EAAG,IAAI,IAAI,CAAA;AAAA,IAC9C,CAAA;AAAA,IAEA,YAAY,KAAA,EAAO;AAIjB,MAAA,MAAM,GAAA,GAAuB,EAAE,IAAA,EAAM,eAAA,EAAiB,GAAA,EAAI;AAC1D,MAAA,OAAO,CAAC,KAAA,EAAO,CAAC,GAAG,CAAC,CAAA;AAAA,IACtB,CAAA;AAAA,IAEA,SAAS,KAAA,EAAO;AACd,MAAA,MAAM,EAAE,OAAM,GAAI,KAAA;AAClB,MAAA,OAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAML,cAAA,EAAgB,YAAA;AAAA,UAMd,CAAC,GAAA,KAAQ,KAAA,CAAM,IAAI,GAAA,CAAI,GAAA,EAAK,IAAI,OAAO,CAAA;AAAA,UACvC,CAAC,MAAA,EAAQ,GAAA,KAAQ,cAAc,GAAA,CAAI,GAAA,EAAK,IAAI,EAAE,CAAA;AAAA,UAC9C,CAAC,KAAA,EAAO,GAAA,KAAQ,cAAA,CAAe,GAAA,CAAI,KAAK,KAAK;AAAA,SAC/C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAMA,aAAA,EAAe,YAAA;AAAA,UAMb,CAAC,GAAA,KAAQ,KAAA,CAAM,GAAA,CAAI,IAAI,GAAG,CAAA;AAAA,UAC1B,CAAC,OAAA,KAAY,cAAA,CAAe,OAAO,CAAA;AAAA,UACnC,CAAC,KAAA,KAAU,kBAAA,CAAmB,KAAK;AAAA;AACrC,OACF;AAAA,IACF;AAAA,GACF;AACF","file":"chunk-EIZJTYKR.js","sourcesContent":["/**\n * @demlik/tea/snapshot — periodic state checkpoint to a host store (R2/KV-shaped).\n *\n * The problem it solves: a long-running machine (a multi-stage run, a paginated\n * crawl, a saga) lives in TEA's in-memory `State` and is persisted as ONE blob\n * by the substrate's `Store<S>` on every transition. That blob is fine for\n * crash recovery of the *runtime* — but it is NOT a coarse, named checkpoint a\n * human (or a separate recovery job) can point a restart at. `snapshot` adds\n * the \"every N units of progress, write a durable checkpoint to R2/KV\"\n * discipline on top, so a crashed long run restarts from the last checkpoint\n * instead of from zero (the field-guide pain row).\n *\n * Shape: this is the same knob contract every L2 composition follows —\n * `createSnapshot(config)` hands back a `{ init, <verbs>, handlers }` bundle you\n * splice into your machine. The state it owns is a Model slice (durable +\n * replayable, the two non-negotiables); the verbs are PURE decisions; the I/O\n * (the actual `put` to the store) lives only in `handlers`.\n *\n * It is a LEAF module: it imports only the core substrate (`../index`, for\n * `Cmd` / `Interpret`) and no sibling subpath. (It does NOT reuse\n * `@demlik/tea/retry-backoff` — that is an even-leafier utility that depends on\n * nothing at all, not even the core; the kinship here is \"leaf with injected\n * time\", not a shared dependency.)\n * Nothing here reads the clock or the RNG on its own behalf — time enters as an\n * `at`/`now` parameter at the verb boundary and the store I/O is realized only\n * when the runtime performs the emitted `Cmd`. That keeps every verb\n * deterministic (invariant 2) and the checkpoint write a `Cmd` the runtime\n * interprets (invariant 3).\n *\n * The Store port is deliberately ABSTRACT — `{ get, put }`, the lowest common\n * shape of R2 and KV — so this module never imports `@cloudflare/workers-types`\n * and can be checkpointed to anything (R2, KV, a DO sub-key, an in-memory map in\n * tests). The host binds the concrete adapter at `handlers({ store })`.\n *\n * Typical wiring:\n *\n *   const snap = createSnapshot<RunState>({ every: 25, key: \"run/checkpoint\" });\n *\n *   // machine state:\n *   type State = { run: RunState; snapshot: SnapshotState };\n *   init: (loaded) => loaded ? [loaded, []] : [{ run: initRun(), snapshot: snap.init() }, []],\n *\n *   // in `update`, on each progress Msg, fold the snapshot slice:\n *   progress: (s, msg) => {\n *     const run = advance(s.run, msg);\n *     const [snapshot, cmds] = snap.record(s.snapshot, run, msg.at);\n *     return [{ ...s, run, snapshot }, cmds];\n *   },\n *   // the write completed → durable ack folds back through update:\n *   snapshot_saved: (s, msg) => {\n *     const [snapshot, cmds] = snap.confirm(s.snapshot, msg);\n *     return [{ ...s, snapshot }, cmds];\n *   },\n *\n *   // RECOVERY — the half that makes a checkpoint a restart point, not just a\n *   // backup. A `boot` Msg the host dispatches once after `run(...)` asks the\n *   // store for the durable checkpoint; the answer folds the recovered payload\n *   // back into the run slice:\n *   boot: (s) => snap.requestLoad(s),                       // emits snapshot_load Cmd\n *   snapshot_loaded: (s, msg) => {\n *     if (msg.payload === null) return [s, []];             // no checkpoint → keep fresh init\n *     const [snapshot, cmds] = snap.boot(s.snapshot);\n *     return [{ ...s, run: msg.payload, snapshot }, cmds];\n *   },\n *   snapshot_load_failed: (s) => [s, []],                   // errors are data — decide here\n *\n *   // splice the I/O — both effect cells (write + load):\n *   interpret: { ...snap.handlers({ store: r2Adapter }) },\n */\n\nimport { Cmd, type Interpret, tryInterpret } from \"../index\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Config — the knob.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The snapshot knob.\n *\n * `every` is the cadence: a checkpoint is written once `every` units of\n * progress have accumulated since the last one (see `record`). It is the\n * `snapshotEvery` field `monitored-run` threads through to this module.\n *\n * `key` is the store key the checkpoint is written under. A single machine\n * keeps a single rolling checkpoint, so the key is fixed at config time rather\n * than passed per write — the latest checkpoint overwrites the previous one\n * (R2/KV are last-write-wins on a key). Defaults to `\"@@snapshot\"`, mirroring\n * `doStore`'s `@@state` default-key convention.\n */\nexport interface SnapshotConfig {\n  /**\n   * Write a checkpoint once this many progress units have accumulated since the\n   * last write. `every: 1` checkpoints on every `record`; a value `<= 0` is\n   * treated as `1` (every progress unit triggers a write) — a non-positive\n   * cadence has no other sensible meaning, and clamping keeps `record` from\n   * never checkpointing on a misconfigured `0`.\n   */\n  readonly every: number;\n  /** Store key the rolling checkpoint is written under. Defaults to `\"@@snapshot\"`. */\n  readonly key?: string;\n}\n\nconst DEFAULT_SNAPSHOT_KEY = \"@@snapshot\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Slice — the Model field this knob owns.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The snapshot bookkeeping slice. Plain data — JSON-serializable so it rides\n * inside the consumer's `Store<S>` blob and survives DO eviction / reload (the\n * \"durable\" non-negotiable). It carries NO payload: the thing being\n * checkpointed lives elsewhere in the machine's state; this slice only tracks\n * *when* to checkpoint and *what has been acknowledged durable*.\n *\n *   - `sinceLast` — progress units accumulated since the last checkpoint\n *     DECISION (reset to 0 the moment `record` decides to write, not when the\n *     write lands). The cadence counter.\n *   - `seq` — monotonic checkpoint sequence. Bumped each time a write is\n *     emitted, so the write Cmd and its later acknowledgement can be matched\n *     even if several are in flight. The \"version\" of the latest emitted\n *     checkpoint.\n *   - `lastSavedSeq` — the highest `seq` whose write the host has confirmed\n *     durable (via `confirm`). `null` until the first confirmed write. The gap\n *     `seq - lastSavedSeq` is the \"writes emitted but not yet acknowledged\"\n *     depth — observable for backpressure / health.\n *   - `lastSavedAt` — the `at` of the most recent confirmed write (epoch ms),\n *     `null` until the first. Carried for observability, never compared inside\n *     a verb (time is injected, never read here).\n */\nexport interface SnapshotState {\n  readonly sinceLast: number;\n  readonly seq: number;\n  readonly lastSavedSeq: number | null;\n  readonly lastSavedAt: number | null;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Store port — abstract R2/KV-shaped checkpoint sink.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The abstract checkpoint sink — the intersection of R2's and KV's surface,\n * narrowed to exactly the two methods a rolling checkpoint needs. Deliberately\n * NOT the substrate's `Store<S>` (`{ load, save, migrate }`): that is the\n * runtime's whole-state persistence boundary keyed at a fixed cell, whereas a\n * checkpoint store is keyed, value-typed, and host-supplied.\n *\n *   - `put(key, value)` — write the checkpoint. Last-write-wins on `key`.\n *   - `get(key)` — read the latest checkpoint back, or `null` if none. Used by\n *     a recovery path to seed `init`'s `loaded` from the durable checkpoint\n *     when the runtime's own `Store<S>` blob is gone.\n *\n * No `@cloudflare/workers-types` import — an R2 bucket, a KV namespace, a DO\n * sub-key, or an in-memory `Map` all satisfy this shape with a 3-line adapter\n * at the host.\n */\nexport interface SnapshotStore<V> {\n  get(key: string): Promise<V | null>;\n  put(key: string, value: V): Promise<void>;\n}\n\n/**\n * The ports `handlers` binds. Just the store today — named so a future port\n * (a metrics sink, a clock) can grow without breaking the `handlers(ports)`\n * call shape.\n */\nexport interface SnapshotPorts<V> {\n  readonly store: SnapshotStore<V>;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Cmd + Msg — the write effect and its durable acknowledgement.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The checkpoint-write Cmd a `record` / `force` decision emits. Plain data\n * (invariant 1 — Cmds are data, not closures): it carries the `payload` to\n * write, the `key` to write it under, the `seq` it represents, and the `at` it\n * was decided. The handler performs the `put` and routes the result back to a\n * `confirm` / fail Msg.\n *\n * `payload` is `V` — the consumer's serializable checkpoint value (the run\n * state, the cursor, whatever the machine wants restartable). The verb takes it\n * as an argument so the snapshot slice never has to hold a copy of the\n * machine's domain state.\n */\nexport type SnapshotWriteCmd<V> = Cmd<\"snapshot_write\"> & {\n  readonly key: string;\n  readonly seq: number;\n  readonly at: number;\n  readonly payload: V;\n};\n\n/**\n * The Msg the write handler dispatches on a SUCCESSFUL `put`. Fold it back\n * through `confirm(state, msg)` to advance `lastSavedSeq` / `lastSavedAt`. The\n * `seq` matches the emitting Cmd so a late acknowledgement of an older write\n * can never regress a newer confirmed one.\n */\nexport type SnapshotSavedMsg = {\n  readonly type: \"snapshot_saved\";\n  readonly seq: number;\n  readonly at: number;\n};\n\n/**\n * The Msg the write handler dispatches on a FAILED `put`. Errors are data\n * (never swallowed): the consumer's reducer decides whether a failed checkpoint\n * is fatal, retryable (compose `@demlik/tea/retry-backoff`), or merely logged.\n * `seq` identifies which checkpoint failed; `error` is carried, never\n * interpreted here.\n */\nexport type SnapshotFailedMsg = {\n  readonly type: \"snapshot_failed\";\n  readonly seq: number;\n  readonly error: unknown;\n};\n\n/**\n * The checkpoint-READ Cmd a `requestLoad` decision emits — the recovery half of\n * the module. Plain data (invariant 1): it carries only the `key` to read. The\n * handler performs `store.get(key)` and routes the result back to a\n * `snapshot_loaded` (Ok, payload-or-null) / `snapshot_load_failed` (Err) Msg.\n *\n * Distinct from `snapshot_write`: a write carries a payload OUT to the store; a\n * load asks the store to hand a payload BACK. The consumer dispatches the\n * triggering Msg once on resume (a `boot` Msg, never `init`'s rehydrate branch —\n * invariant 2), folds the recovered payload into its run slice, then continues.\n */\nexport type SnapshotLoadCmd = Cmd<\"snapshot_load\"> & {\n  readonly key: string;\n};\n\n/**\n * The Msg the load handler dispatches when `store.get` RESOLVES. `payload` is\n * the recovered checkpoint value, or `null` when the store has no checkpoint\n * under `key` (fresh boot — never checkpointed, or a wiped store). The consumer\n * folds this into `init`'s loaded branch: `payload === null` → keep the fresh\n * `init` state; non-null → seed the run slice from the durable checkpoint and\n * `boot` the snapshot slice's cadence counter.\n *\n * A `null` payload is NOT an error — \"no checkpoint yet\" is a normal first-run\n * state, distinct from \"the read failed\" (`snapshot_load_failed`).\n */\nexport type SnapshotLoadedMsg<V> = {\n  readonly type: \"snapshot_loaded\";\n  readonly payload: V | null;\n};\n\n/**\n * The Msg the load handler dispatches when `store.get` REJECTS. Errors are data\n * (never swallowed — the field-guide rule): a failed recovery read is a visible\n * signal the consumer's reducer decides on (fatal-abort, retry via\n * `@demlik/tea/retry-backoff`, or boot-fresh-and-log). `error` is carried, never\n * interpreted here. Kept separate from `snapshot_loaded`'s `null` so \"the store\n * has no checkpoint\" can never masquerade as \"the read failed\".\n */\nexport type SnapshotLoadFailedMsg = {\n  readonly type: \"snapshot_load_failed\";\n  readonly error: unknown;\n};\n\n/** Construct a `snapshot_saved` Msg. Shared by the handler and tests so the wire shape can't drift. */\nexport function snapshotSaved(seq: number, at: number): SnapshotSavedMsg {\n  return { type: \"snapshot_saved\", seq, at };\n}\n\n/** Construct a `snapshot_failed` Msg. Shared by the handler and tests so the wire shape can't drift. */\nexport function snapshotFailed(seq: number, error: unknown): SnapshotFailedMsg {\n  return { type: \"snapshot_failed\", seq, error };\n}\n\n/** Construct a `snapshot_loaded` Msg. Shared by the handler and tests so the wire shape can't drift. */\nexport function snapshotLoaded<V>(payload: V | null): SnapshotLoadedMsg<V> {\n  return { type: \"snapshot_loaded\", payload };\n}\n\n/** Construct a `snapshot_load_failed` Msg. Shared by the handler and tests so the wire shape can't drift. */\nexport function snapshotLoadFailed(error: unknown): SnapshotLoadFailedMsg {\n  return { type: \"snapshot_load_failed\", error };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// The combinator.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The bundle `createSnapshot` returns — the uniform knob contract. `subs` is\n * omitted: a checkpoint is driven by progress (a `record` call from the\n * consumer's reducer), not by a timer, so this module has no subscriptions.\n */\nexport interface SnapshotKnob<V> {\n  /** The initial slice — zero progress, no checkpoint emitted or confirmed yet. */\n  init(): SnapshotState;\n  /**\n   * Account one unit of progress. PURE. Increments `sinceLast`; once the\n   * accumulated count reaches the configured cadence, DECIDES to checkpoint:\n   * resets `sinceLast` to 0, bumps `seq`, and emits a single `snapshot_write`\n   * Cmd carrying `payload` + `key` + the new `seq` + `at`. Below the cadence it\n   * returns the bumped slice and NO Cmd.\n   *\n   * `payload` is the checkpoint value to persist (the consumer's domain state);\n   * `at` is the caller-stamped time the progress occurred (epoch ms) — injected,\n   * never read from the clock here.\n   */\n  record(\n    state: SnapshotState,\n    payload: V,\n    at: number,\n  ): readonly [SnapshotState, readonly Cmd[]];\n  /**\n   * Force a checkpoint regardless of the cadence counter. PURE. Always bumps\n   * `seq`, resets `sinceLast`, and emits the write Cmd. Use on a phase boundary\n   * the cadence would otherwise miss — e.g. \"the run just finished, checkpoint\n   * the terminal state now\" — so the last durable checkpoint is the final state,\n   * not whatever the modulo happened to land on.\n   */\n  force(\n    state: SnapshotState,\n    payload: V,\n    at: number,\n  ): readonly [SnapshotState, readonly Cmd[]];\n  /**\n   * Record a confirmed durable write. PURE. Advances `lastSavedSeq` /\n   * `lastSavedAt` to the acknowledged `seq` / `at`, but only forward: an\n   * out-of-order acknowledgement of an OLDER `seq` (a slow write landing after a\n   * newer one) is ignored, so the confirmed watermark is monotonic. Fold the\n   * `snapshot_saved` Msg here.\n   *\n   * Returns the reducer-cell shape `readonly [SnapshotState, readonly Cmd[]]`\n   * (with `Cmd.none` — an ack emits nothing) for uniformity with every sibling\n   * knob, so it drops straight into a `snapshot_saved` cell without the caller\n   * re-wrapping a bare State.\n   */\n  confirm(\n    state: SnapshotState,\n    msg: SnapshotSavedMsg,\n  ): readonly [SnapshotState, readonly Cmd[]];\n  /**\n   * Resume after a reload. PURE. Resets `sinceLast` to 0 because any\n   * un-checkpointed progress accumulated before the crash is moot — recovery\n   * resumes from the last DURABLE checkpoint (`get` from the store), so the\n   * cadence counter starts fresh from there. `seq` / `lastSavedSeq` /\n   * `lastSavedAt` are preserved (they describe what is durable, which a reload\n   * does not change). Call from a `boot` Msg the host dispatches once after\n   * `run(...)`, never from `init`'s rehydrate branch (invariant 2).\n   *\n   * Returns the reducer-cell shape `readonly [SnapshotState, readonly Cmd[]]`\n   * (with `Cmd.none` — a resume emits nothing) for uniformity with every sibling\n   * knob, so it drops straight into a `snapshot_loaded` cell without the caller\n   * re-wrapping a bare State.\n   */\n  boot(state: SnapshotState): readonly [SnapshotState, readonly Cmd[]];\n  /**\n   * Ask the store for the durable checkpoint. PURE. Emits a single\n   * `snapshot_load` Cmd carrying the configured `key`; returns the slice\n   * UNCHANGED (a read decides nothing about the cadence bookkeeping — only the\n   * later `snapshot_loaded` fold, via `boot`, touches the slice). This is the\n   * entry point of the recovery loop: the consumer dispatches a `boot` Msg once\n   * after `run(...)`, folds `requestLoad` here, and the emitted Cmd's handler\n   * reads `store.get(key)` and dispatches `snapshot_loaded` / `snapshot_load_failed`.\n   *\n   * Returns `readonly [SnapshotState, readonly Cmd[]]` (the reducer-cell shape)\n   * so it drops straight into a `boot: (s) => snap.requestLoad(s)` cell.\n   */\n  requestLoad(state: SnapshotState): readonly [SnapshotState, readonly Cmd[]];\n  /**\n   * The `interpret` map for this knob's two effect Cmds:\n   *\n   *   - `snapshot_write` — binds the store and performs the `put`, routing\n   *     Ok → `snapshot_saved` / Err → `snapshot_failed`.\n   *   - `snapshot_load`  — binds the store and performs the `get`, routing\n   *     Ok → `snapshot_loaded` (payload-or-null) / Err → `snapshot_load_failed`.\n   *\n   * Railway throughout — neither effect throws into the runtime; the outcome is\n   * always a Msg. Spread into your machine's `interpret`.\n   */\n  handlers(\n    ports: SnapshotPorts<V>,\n  ): Interpret<\n    | SnapshotSavedMsg\n    | SnapshotFailedMsg\n    | SnapshotLoadedMsg<V>\n    | SnapshotLoadFailedMsg,\n    SnapshotWriteCmd<V> | SnapshotLoadCmd,\n    unknown\n  >;\n}\n\n/**\n * Create a snapshot knob from a `SnapshotConfig`. The returned bundle is spliced\n * into a consumer machine: `init()` seeds the slice, `record` / `force` are\n * folded in reducer cells, `confirm` / `boot` handle the acknowledgement +\n * resume Msgs, and `handlers({ store })` supplies the write `interpret` cell.\n */\nexport function createSnapshot<V>(config: SnapshotConfig): SnapshotKnob<V> {\n  // Clamp the cadence to >= 1 at construction so `record`'s threshold check is\n  // branchless and a misconfigured `0` / negative `every` checkpoints on every\n  // progress unit instead of never.\n  const every = config.every >= 1 ? config.every : 1;\n  const key = config.key ?? DEFAULT_SNAPSHOT_KEY;\n\n  /**\n   * Emit the write Cmd for a checkpoint decision. Shared by `record`'s\n   * cadence-hit branch and `force`. Bumps `seq`, resets `sinceLast`, returns the\n   * new slice + the single `snapshot_write` Cmd. The input slice is never\n   * mutated (invariant 1).\n   */\n  function emitWrite(\n    state: SnapshotState,\n    payload: V,\n    at: number,\n  ): readonly [SnapshotState, readonly Cmd[]] {\n    const seq = state.seq + 1;\n    const next: SnapshotState = { ...state, sinceLast: 0, seq };\n    const cmd: SnapshotWriteCmd<V> = {\n      type: \"snapshot_write\",\n      key,\n      seq,\n      at,\n      payload,\n    };\n    return [next, [cmd]];\n  }\n\n  return {\n    init(): SnapshotState {\n      return { sinceLast: 0, seq: 0, lastSavedSeq: null, lastSavedAt: null };\n    },\n\n    record(state, payload, at) {\n      const sinceLast = state.sinceLast + 1;\n      // Below the cadence: accumulate, emit nothing.\n      if (sinceLast < every) {\n        return [{ ...state, sinceLast }, Cmd.none];\n      }\n      // Cadence reached: checkpoint. `emitWrite` resets the counter + bumps seq.\n      return emitWrite(state, payload, at);\n    },\n\n    force(state, payload, at) {\n      return emitWrite(state, payload, at);\n    },\n\n    confirm(state, msg) {\n      // Forward-only watermark: ignore a stale ack of an older seq so a slow\n      // write landing after a newer one can't regress `lastSavedSeq`.\n      if (state.lastSavedSeq !== null && msg.seq <= state.lastSavedSeq) {\n        return [state, Cmd.none];\n      }\n      return [\n        { ...state, lastSavedSeq: msg.seq, lastSavedAt: msg.at },\n        Cmd.none,\n      ];\n    },\n\n    boot(state) {\n      return [{ ...state, sinceLast: 0 }, Cmd.none];\n    },\n\n    requestLoad(state) {\n      // A read decides nothing about the cadence bookkeeping — return the slice\n      // unchanged and emit the single read Cmd. The recovered payload folds back\n      // through `snapshot_loaded` (the consumer's reducer), not here.\n      const cmd: SnapshotLoadCmd = { type: \"snapshot_load\", key };\n      return [state, [cmd]];\n    },\n\n    handlers(ports) {\n      const { store } = ports;\n      return {\n        // The write effect. Performs the `put`; on success the saved `seq`/`at`\n        // ride the `snapshot_saved` Msg back into `confirm`; on failure the\n        // error rides `snapshot_failed`. Railway via the core's `tryInterpret`\n        // (matching every other module's handler) — the handler always resolves\n        // with a Msg, never rejects into the runtime.\n        snapshot_write: tryInterpret<\n          SnapshotWriteCmd<V>,\n          void,\n          SnapshotSavedMsg | SnapshotFailedMsg,\n          unknown\n        >(\n          (cmd) => store.put(cmd.key, cmd.payload),\n          (_value, cmd) => snapshotSaved(cmd.seq, cmd.at),\n          (error, cmd) => snapshotFailed(cmd.seq, error),\n        ),\n        // The read effect — the recovery half. Performs the `get`; on success\n        // the recovered payload (or `null` when no checkpoint exists) rides the\n        // `snapshot_loaded` Msg the consumer folds into `init`'s loaded branch;\n        // on failure the error rides `snapshot_load_failed`. Same Railway\n        // discipline via `tryInterpret` — the read never rejects into the runtime.\n        snapshot_load: tryInterpret<\n          SnapshotLoadCmd,\n          V | null,\n          SnapshotLoadedMsg<V> | SnapshotLoadFailedMsg,\n          unknown\n        >(\n          (cmd) => store.get(cmd.key),\n          (payload) => snapshotLoaded(payload),\n          (error) => snapshotLoadFailed(error),\n        ),\n      };\n    },\n  };\n}\n"]}

package/dist/chunk-EQRUAP2A.js

@@ -0,0 +1,56 @@
+// src/debounce/index.ts
+function debounce(fn, ms, opts) {
+  const leading = opts?.leading ?? false;
+  const trailing = opts?.trailing ?? true;
+  let handle = null;
+  let pendingArgs = null;
+  let leadingFired = false;
+  function clearHandle() {
+    if (handle !== null) {
+      clearTimeout(handle);
+      handle = null;
+    }
+  }
+  function onTimerExpired() {
+    handle = null;
+    if (trailing && pendingArgs !== null) {
+      const args = pendingArgs;
+      pendingArgs = null;
+      fn(...args);
+    }
+    leadingFired = false;
+  }
+  const debounced = (...args) => {
+    const isBurstStart = handle === null;
+    if (leading && isBurstStart && !leadingFired) {
+      leadingFired = true;
+      fn(...args);
+    } else if (trailing) {
+      pendingArgs = args;
+    }
+    clearHandle();
+    handle = setTimeout(onTimerExpired, ms);
+  };
+  debounced.cancel = () => {
+    clearHandle();
+    pendingArgs = null;
+    leadingFired = false;
+  };
+  debounced.flush = () => {
+    if (pendingArgs !== null) {
+      const args = pendingArgs;
+      pendingArgs = null;
+      clearHandle();
+      leadingFired = false;
+      fn(...args);
+    } else {
+      clearHandle();
+      leadingFired = false;
+    }
+  };
+  return debounced;
+}
+
+export { debounce };
+//# sourceMappingURL=chunk-EQRUAP2A.js.map
+//# sourceMappingURL=chunk-EQRUAP2A.js.map

package/dist/chunk-EQRUAP2A.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/debounce/index.ts"],"names":[],"mappings":";AA8GO,SAAS,QAAA,CACd,EAAA,EACA,EAAA,EACA,IAAA,EACc;AACd,EAAA,MAAM,OAAA,GAAU,MAAM,OAAA,IAAW,KAAA;AACjC,EAAA,MAAM,QAAA,GAAW,MAAM,QAAA,IAAY,IAAA;AAMnC,EAAA,IAAI,MAAA,GAA+C,IAAA;AAOnD,EAAA,IAAI,WAAA,GAAwB,IAAA;AAK5B,EAAA,IAAI,YAAA,GAAe,KAAA;AAEnB,EAAA,SAAS,WAAA,GAAoB;AAC3B,IAAA,IAAI,WAAW,IAAA,EAAM;AACnB,MAAA,YAAA,CAAa,MAAM,CAAA;AACnB,MAAA,MAAA,GAAS,IAAA;AAAA,IACX;AAAA,EACF;AAKA,EAAA,SAAS,cAAA,GAAuB;AAC9B,IAAA,MAAA,GAAS,IAAA;AAQT,IAAA,IAAI,QAAA,IAAY,gBAAgB,IAAA,EAAM;AACpC,MAAA,MAAM,IAAA,GAAO,WAAA;AACb,MAAA,WAAA,GAAc,IAAA;AACd,MAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,IACZ;AAEA,IAAA,YAAA,GAAe,KAAA;AAAA,EACjB;AAEA,EAAA,MAAM,SAAA,GAAY,IAAI,IAAA,KAAkB;AAItC,IAAA,MAAM,eAAe,MAAA,KAAW,IAAA;AAChC,IAAA,IAAI,OAAA,IAAW,YAAA,IAAgB,CAAC,YAAA,EAAc;AAC5C,MAAA,YAAA,GAAe,IAAA;AACf,MAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,IACZ,WAAW,QAAA,EAAU;AAGnB,MAAA,WAAA,GAAc,IAAA;AAAA,IAChB;AAKA,IAAA,WAAA,EAAY;AACZ,IAAA,MAAA,GAAS,UAAA,CAAW,gBAAgB,EAAE,CAAA;AAAA,EACxC,CAAA;AAEA,EAAA,SAAA,CAAU,SAAS,MAAY;AAC7B,IAAA,WAAA,EAAY;AACZ,IAAA,WAAA,GAAc,IAAA;AACd,IAAA,YAAA,GAAe,KAAA;AAAA,EACjB,CAAA;AAEA,EAAA,SAAA,CAAU,QAAQ,MAAY;AAI5B,IAAA,IAAI,gBAAgB,IAAA,EAAM;AACxB,MAAA,MAAM,IAAA,GAAO,WAAA;AACb,MAAA,WAAA,GAAc,IAAA;AACd,MAAA,WAAA,EAAY;AAEZ,MAAA,YAAA,GAAe,KAAA;AACf,MAAA,EAAA,CAAG,GAAG,IAAI,CAAA;AAAA,IACZ,CAAA,MAAO;AAGL,MAAA,WAAA,EAAY;AACZ,MAAA,YAAA,GAAe,KAAA;AAAA,IACjB;AAAA,EACF,CAAA;AAEA,EAAA,OAAO,SAAA;AACT","file":"chunk-EQRUAP2A.js","sourcesContent":["/**\n * @demlik/tea/debounce — a timer-based call transformer that coalesces a burst\n * of calls into a single fire.\n *\n * Sibling of `@demlik/tea/throttle` — the two share a SYMMETRIC surface\n * (`Debounced<A>` / `Throttled<A>`, both callable + `.cancel()` + `.flush()`,\n * both `{ leading?, trailing? }`) so they read as a pair. They are kept in\n * separate files with NO cross-import: each is a self-contained timer, and the\n * coalesce-vs-drop policies are different enough that sharing code would hide\n * the distinction. Read one to understand the other; do not couple them.\n *\n * WHAT THIS IS NOT — and why it lives outside `update`:\n *\n *   - NOT a reducer / Transitions cell. Reducers are PURE (invariant 2 — same\n *     inputs → same outputs, no `Date.now`, no timers). A debounce holds a live\n *     `setTimeout` handle and mutable pending-args state; folding it into\n *     `update` would smuggle a timer into the pure core.\n *   - NOT a Sub. A Sub is a continuous SOURCE of Msgs the substrate reconciles\n *     by id every transition (invariant 4). A debounce is a SINK transformer:\n *     it wraps a `void`-returning handler (the canonical one is\n *     `Runtime.dispatch`) so bursty HOST events coalesce BEFORE they ever\n *     become a Msg.\n *\n * It is a higher-order function at the host boundary (pattern 14 — TEA owns\n * state, JS owns timing). The host attaches the wrapped function to a noisy\n * event source (`scroll`, `resize`, `input`, a ResizeObserver) and the\n * substrate downstream only ever sees the coalesced Msg:\n *\n *   const onResized = debounce(\n *     () => runtime.dispatch({ type: \"BrowserResizedWindow\" }),\n *     150,\n *   );\n *   window.addEventListener(\"resize\", onResized);\n *   // cleanup: onResized.cancel(); window.removeEventListener(\"resize\", onResized);\n *\n * NOT exported from the package root — reached via the `@demlik/tea/debounce`\n * subpath, same one-shape-per-package rule as `rate-limit`, `deadline`, and\n * `work-queue`.\n *\n * Uses the universal `setTimeout` / `clearTimeout` timer idiom (same discipline\n * as `subs/from-timeout.ts`): exactly one live handle at a time, every arm\n * clears the previous, every fire / cancel clears the handle and nulls it so a\n * stale callback can never run.\n */\n\n/**\n * A debounced wrapper around `fn`. Callable with the SAME argument tuple as\n * `fn` — `(...args: A) => void` — plus two control methods that share names and\n * shapes with `Throttled<A>` so the two modules read as a symmetric pair.\n */\nexport interface Debounced<A extends readonly unknown[]> {\n  /** Schedule (or re-schedule) a fire of the wrapped `fn`. See `debounce`. */\n  (...args: A): void;\n  /**\n   * Drop any pending trailing fire WITHOUT invoking `fn`. Clears the timer and\n   * forgets the captured args. Idempotent — calling it with nothing pending is\n   * a no-op. The leading-edge latch (if `leading` is enabled) also resets, so\n   * the next call after `cancel` is treated as a fresh burst.\n   *\n   * The host-cleanup partner of `removeEventListener`: cancel the pending fire\n   * when the component unmounts / the listener detaches, so a queued\n   * `dispatch` can't land after teardown.\n   */\n  cancel(): void;\n  /**\n   * Fire any pending trailing call IMMEDIATELY with its captured args, then\n   * clear the timer. No-op when nothing is pending. Use to force the last\n   * coalesced call out early — e.g. flush a debounced save on `beforeunload`,\n   * or flush a debounced search when the user presses Enter.\n   */\n  flush(): void;\n}\n\n/**\n * Wrap `fn` so a BURST of calls collapses to a single invocation.\n *\n * Trailing edge (the default): each call (re)starts a `ms` timer; `fn` fires\n * once with the LAST args after `ms` of quiet. Every call within `ms` of the\n * previous resets the timer — the classic \"wait until the user stops typing\"\n * behavior.\n *\n * @param fn   The handler to coalesce. Typically `(...) => runtime.dispatch(...)`,\n *             but any `(...args: A) => void` works. The return value is\n *             ignored — debounce is a fire transformer, not a value pipe.\n * @param ms   Quiet window in milliseconds. Calls closer together than `ms`\n *             coalesce; a gap of at least `ms` lets the trailing fire through.\n * @param opts.leading   Fire on the FIRST call of a burst (the leading edge),\n *             with that first call's args. Default `false`.\n * @param opts.trailing  Fire on the trailing edge with the LAST call's args.\n *             Default `true`.\n *\n * Edge combinations (matching lodash's settled semantics, the de-facto\n * standard the ecosystem rediscovered):\n *\n *   - `{ trailing: true }` (default): one fire, after the burst, last args.\n *   - `{ leading: true, trailing: false }`: one fire, at the burst START,\n *     first args. Subsequent calls within the window are swallowed; the timer\n *     only re-opens the \"can lead again\" latch after `ms` of quiet.\n *   - `{ leading: true, trailing: true }`: fires at the start AND end of a\n *     burst — BUT the trailing fire is SUPPRESSED for a burst of exactly ONE\n *     call (the leading fire already covered it, so a lone call doesn't\n *     double-fire). This matches lodash and is the behavior tests pin.\n *   - `{ leading: false, trailing: false }`: never fires. Degenerate but legal;\n *     we don't throw — the caller asked for a no-op transformer.\n *\n * WHY a default of trailing-only: a debounce's whole job is \"act after the\n * activity settles.\" The trailing edge IS that semantic — fire with the final\n * state of the burst (the last keystroke, the final scroll position). Leading\n * is the opt-in for \"respond instantly, then go quiet.\"\n */\nexport function debounce<A extends readonly unknown[]>(\n  fn: (...args: A) => void,\n  ms: number,\n  opts?: { leading?: boolean; trailing?: boolean },\n): Debounced<A> {\n  const leading = opts?.leading ?? false;\n  const trailing = opts?.trailing ?? true;\n\n  // Exactly one live handle at a time (the from-timeout discipline). `null`\n  // when no fire is pending — the single source of truth for \"is a timer\n  // armed?\". Every arm clears the previous handle before opening a new one, so\n  // we never leak overlapping timers across a burst.\n  let handle: ReturnType<typeof setTimeout> | null = null;\n  // The most recent args, held only while a trailing fire is pending. Captured\n  // on every call (the trailing edge fires with the LAST args), cleared the\n  // instant we fire / cancel so a stale tuple can never leak into a later\n  // burst. `null` (not `undefined`) is the empty sentinel because `A` may\n  // itself contain `undefined` elements — a present-but-empty tuple is still a\n  // pending call, distinct from \"nothing pending\".\n  let pendingArgs: A | null = null;\n  // Leading-edge latch: true once a leading fire has happened for the current\n  // burst, reset to false after `ms` of quiet (the timer's expiry) or on\n  // `cancel`. Gates the \"fire on first call of a burst, then stay quiet\" rule\n  // so mid-burst calls don't re-trigger the leading fire.\n  let leadingFired = false;\n\n  function clearHandle(): void {\n    if (handle !== null) {\n      clearTimeout(handle);\n      handle = null;\n    }\n  }\n\n  // Timer expiry: the burst has gone quiet for `ms`. Fire the trailing edge if\n  // one is owed, then reset all burst state so the NEXT call starts a fresh\n  // burst (re-arming the leading latch, clearing pending args).\n  function onTimerExpired(): void {\n    handle = null;\n    // Suppress the trailing fire for a lone leading-only-eligible call:\n    // when `leadingFired` is true AND trailing is enabled, a burst of exactly\n    // one call already fired on the leading edge — `pendingArgs` was cleared\n    // at that point, so there is nothing to fire here. A burst of 2+ calls\n    // re-captured `pendingArgs` after the leading fire, so the trailing fire\n    // lands with the last args. The `pendingArgs !== null` guard encodes\n    // exactly that distinction; no separate call-count needed.\n    if (trailing && pendingArgs !== null) {\n      const args = pendingArgs;\n      pendingArgs = null;\n      fn(...args);\n    }\n    // Burst over — re-open the leading latch for the next burst.\n    leadingFired = false;\n  }\n\n  const debounced = (...args: A): void => {\n    // Leading edge: the FIRST call of a burst (no timer armed yet, latch open).\n    // Fire immediately with this call's args; do NOT stash them as pending so a\n    // lone call won't also fire on the trailing edge.\n    const isBurstStart = handle === null;\n    if (leading && isBurstStart && !leadingFired) {\n      leadingFired = true;\n      fn(...args);\n    } else if (trailing) {\n      // Capture the latest args for the trailing fire. Overwrites any prior\n      // pending tuple — the trailing edge fires with the LAST args, by design.\n      pendingArgs = args;\n    }\n\n    // (Re)arm the quiet-window timer. Clearing the previous handle is what\n    // makes the window SLIDE: every call within `ms` pushes the trailing fire\n    // out to `ms` after THIS call.\n    clearHandle();\n    handle = setTimeout(onTimerExpired, ms);\n  };\n\n  debounced.cancel = (): void => {\n    clearHandle();\n    pendingArgs = null;\n    leadingFired = false;\n  };\n\n  debounced.flush = (): void => {\n    // Force the pending trailing fire out now. Mirrors `onTimerExpired`'s fire\n    // branch but is caller-driven rather than timer-driven, so it also tears\n    // down the armed timer (a timer-driven expiry already nulled `handle`).\n    if (pendingArgs !== null) {\n      const args = pendingArgs;\n      pendingArgs = null;\n      clearHandle();\n      // A flushed trailing fire ends the burst, same as a natural expiry.\n      leadingFired = false;\n      fn(...args);\n    } else {\n      // Nothing pending — still tear down a lingering leading-only timer so a\n      // post-flush call leads cleanly.\n      clearHandle();\n      leadingFired = false;\n    }\n  };\n\n  return debounced;\n}\n"]}