@demlik/tea 0.20.0 → 0.22.0

package/dist/{chunk-TGJLXZAU.js → chunk-ZRRET3RP.js}

@@ -1,5 +1,5 @@
 import { typeOf, indexPath, unionKeys, keyPath } from './chunk-HWVW4AXC.js';
-import { replay } from './chunk-RKVUVALV.js';
+import { foldMsgs } from './chunk-A3QPMX5M.js';
 
 // src/internal/persistence/recorder/index.ts
 function recorder(runtime, opts) {
@@ -32,7 +32,7 @@ function recorder(runtime, opts) {
       }
       return {
         // sawBoot ⇒ `loaded` is the captured boot state; otherwise the
-        // recorder attached post-boot and replay must re-run fresh init.
+        // trace has no replay anchor and replayTrace will refuse it.
         loaded: sawBoot ? loaded : null,
         msgs: msgs.slice(),
         finalState,
@@ -157,13 +157,13 @@ function traceToJSONL(trace) {
 }
 
 // src/internal/persistence/trace-replay/index.ts
-function replayTrace(machine, trace, ctx) {
-  const result = replay(machine, {
-    msgs: trace.msgs,
-    ctx,
-    loaded: trace.loaded
-  });
-  const actual = result.state;
+function replayTrace(machine, trace, _ctx) {
+  if (trace.loaded === null) {
+    throw new Error(
+      "tea replayTrace: trace has no captured initial State; record boot before replaying."
+    );
+  }
+  const actual = foldMsgs(machine, trace.loaded, trace.msgs);
   const expected = trace.finalState;
   const divergence = firstDivergence(expected, actual, "state");
   if (divergence === null) {
@@ -204,5 +204,5 @@ function firstDivergence(expected, actual, path) {
 }
 
 export { breadcrumbsFromTrace, deepEqual, parseJSONL, recorder, replayTrace, traceAttachment };
-//# sourceMappingURL=chunk-TGJLXZAU.js.map
-//# sourceMappingURL=chunk-TGJLXZAU.js.map
+//# sourceMappingURL=chunk-ZRRET3RP.js.map
+//# sourceMappingURL=chunk-ZRRET3RP.js.map

package/dist/chunk-ZRRET3RP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/persistence/recorder/index.ts","../src/internal/persistence/trace-replay/index.ts"],"names":[],"mappings":";;;;AAwKO,SAAS,QAAA,CACd,SACA,IAAA,EACgB;AAIhB,EAAA,MAAM,UAAU,IAAA,EAAM,UAAA;AACtB,EAAA,MAAM,UAAA,GACJ,OAAA,KAAY,MAAA,IAAa,MAAA,CAAO,KAAA,CAAM,OAAO,CAAA,IAAK,OAAA,IAAW,CAAA,GACzD,CAAA,GACA,IAAA,CAAK,GAAA,CAAI,SAAS,CAAC,CAAA;AACzB,EAAA,MAAM,YAAA,GAAe,MAAM,YAAA,IAAgB,KAAA;AAI3C,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI,OAAA,GAAU,KAAA;AAGd,EAAA,MAAM,OAAY,EAAC;AAEnB,EAAA,MAAM,QAAgC,EAAC;AAKvC,EAAA,IAAI,UAAA;AACJ,EAAA,IAAI,OAAA,GAAU,KAAA;AAMd,EAAA,MAAM,MAAA,GAAS,OAAA,CAAQ,MAAA,CAAO,CAAC,KAAA,KAAU;AACvC,IAAA,UAAA,GAAa,KAAA;AACb,IAAA,MAAA,GAAS,KAAA;AACT,IAAA,OAAA,GAAU,IAAA;AAAA,EACZ,CAAC,CAAA;AAED,EAAA,MAAM,SAAA,GAAY,OAAA,CAAQ,OAAA,CAAQ,CAAC,KAAK,KAAA,KAAU;AAGhD,IAAA,UAAA,GAAa,KAAA;AAKb,IAAA,IAAI,UAAA,GAAa,CAAA,IAAK,IAAA,CAAK,MAAA,MAAY,UAAA,EAAY;AAEnD,IAAA,IAAA,CAAK,KAAK,GAAG,CAAA;AACb,IAAA,IAAI,cAAc,KAAA,CAAM,IAAA,CAAK,EAAE,GAAA,EAAK,OAAO,CAAA;AAAA,EAC7C,CAAC,CAAA;AAED,EAAA,OAAO;AAAA,IACL,IAAA,GAAoB;AAClB,MAAA,IAAI,eAAe,MAAA,EAAW;AAC5B,QAAA,MAAM,IAAI,KAAA;AAAA,UACR;AAAA,SAEF;AAAA,MACF;AACA,MAAA,OAAO;AAAA;AAAA;AAAA,QAGL,MAAA,EAAQ,UAAW,MAAA,GAAe,IAAA;AAAA,QAClC,IAAA,EAAM,KAAK,KAAA,EAAM;AAAA,QACjB,UAAA;AAAA;AAAA;AAAA,QAGA,GAAI,eAAe,EAAE,KAAA,EAAO,MAAM,KAAA,EAAM,KAAM;AAAC,OACjD;AAAA,IACF,CAAA;AAAA,IACA,OAAA,GAAkB;AAChB,MAAA,IAAI,eAAe,MAAA,EAAW;AAC5B,QAAA,MAAM,IAAI,KAAA;AAAA,UACR;AAAA,SAEF;AAAA,MACF;AAQA,MAAA,OAAO,YAAA,CAAa,IAAA,CAAK,IAAA,EAAM,CAAA;AAAA,IACjC,CAAA;AAAA,IACA,IAAA,GAAa;AACX,MAAA,IAAI,OAAA,EAAS;AACb,MAAA,OAAA,GAAU,IAAA;AACV,MAAA,SAAA,EAAU;AACV,MAAA,MAAA,EAAO;AAAA,IACT;AAAA,GACF;AACF;AA4BO,SAAS,WAAiB,KAAA,EAA4B;AAC3D,EAAA,MAAM,QAAA,GAAW,KAAA,CAAM,KAAA,CAAM,IAAI,CAAA;AACjC,EAAA,IAAI,MAAA,GAAmB,IAAA;AACvB,EAAA,IAAI,OAAA,GAAU,KAAA;AACd,EAAA,MAAM,OAAY,EAAC;AACnB,EAAA,MAAM,QAAgC,EAAC;AACvC,EAAA,IAAI,UAAA,GAAuB,IAAA;AAC3B,EAAA,IAAI,UAAA,GAAa,KAAA;AAEjB,EAAA,KAAA,MAAW,CAAC,CAAA,EAAG,OAAO,CAAA,IAAK,QAAA,CAAS,SAAQ,EAAG;AAC7C,IAAA,MAAM,IAAA,GAAO,QAAQ,IAAA,EAAK;AAC1B,IAAA,IAAI,SAAS,EAAA,EAAI;AAEjB,IAAA,IAAI,MAAA;AACJ,IAAA,IAAI;AACF,MAAA,MAAA,GAAS,IAAA,CAAK,MAAM,IAAI,CAAA;AAAA,IAC1B,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,2CAA2C,CAAA,GAAI,CAAC,CAAA,kBAAA,EAAqB,MAAA,CAAO,GAAG,CAAC,CAAA;AAAA,OAClF;AAAA,IACF;AAEA,IAAA,IAAI,MAAA,CAAO,SAAS,MAAA,EAAQ;AAC1B,MAAA,IAAI,OAAA,EAAS;AACX,QAAA,MAAM,IAAI,KAAA;AAAA,UACR,CAAA,0DAAA,EAA6D,IAAI,CAAC,CAAA,oCAAA;AAAA,SAEpE;AAAA,MACF;AACA,MAAA,OAAA,GAAU,IAAA;AACV,MAAA,MAAA,GAAS,MAAA,CAAO,KAAA;AAGhB,MAAA,UAAA,GAAa,MAAA,CAAO,KAAA;AACpB,MAAA,UAAA,GAAa,OAAO,KAAA,KAAU,IAAA;AAAA,IAChC,CAAA,MAAA,IAAW,MAAA,CAAO,IAAA,KAAS,MAAA,EAAQ;AACjC,MAAA,IAAI,CAAC,OAAA,EAAS;AACZ,QAAA,MAAM,IAAI,KAAA;AAAA,UACR,CAAA,wEAAA,EAA2E,IAAI,CAAC,CAAA,CAAA;AAAA,SAClF;AAAA,MACF;AACA,MAAA,IAAA,CAAK,IAAA,CAAK,OAAO,GAAG,CAAA;AACpB,MAAA,IAAI,MAAA,CAAO,UAAU,IAAA,EAAM;AACzB,QAAA,KAAA,CAAM,IAAA,CAAK,EAAE,GAAA,EAAK,MAAA,CAAO,KAAK,KAAA,EAAO,MAAA,CAAO,OAAO,CAAA;AACnD,QAAA,UAAA,GAAa,MAAA,CAAO,KAAA;AACpB,QAAA,UAAA,GAAa,IAAA;AAAA,MACf;AAAA,IACF,CAAA,MAAO;AACL,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,6DAA6D,CAAA,GAAI,CAAC,OAChE,IAAA,CAAK,SAAA,CAAW,OAA8B,IAAI;AAAA,OACtD;AAAA,IACF;AAAA,EACF;AAEA,EAAA,IAAI,CAAC,OAAA,EAAS;AACZ,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KAEF;AAAA,EACF;AACA,EAAA,IAAI,CAAC,UAAA,IAAc,UAAA,KAAe,IAAA,EAAM;AACtC,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KAEF;AAAA,EACF;AAEA,EAAA,OAAO,EAAE,MAAA,EAAQ,IAAA,EAAM,UAAA,EAAY,KAAA,EAAM;AAC3C;AAyDO,SAAS,gBACd,KAAA,EACiB;AACjB,EAAA,OAAO;AAAA,IACL,QAAA,EAAU,iBAAA;AAAA,IACV,IAAA,EAAM,aAAa,KAAK,CAAA;AAAA,IACxB,WAAA,EAAa;AAAA,GACf;AACF;AA2DO,SAAS,oBAAA,CACd,OACA,IAAA,EACmB;AACnB,EAAA,MAAM,WAAW,IAAA,EAAM,KAAA;AAIvB,EAAA,MAAM,KAAA,GACJ,QAAA,KAAa,MAAA,IAAa,MAAA,CAAO,MAAM,QAAQ,CAAA,GAC3C,GAAA,GACA,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,IAAA,CAAK,KAAA,CAAM,QAAQ,CAAC,CAAA;AACtC,EAAA,MAAM,YAAY,IAAA,EAAM,SAAA;AAMxB,EAAA,MAAM,QAAQ,IAAA,CAAK,GAAA,CAAI,GAAG,KAAA,CAAM,IAAA,CAAK,SAAS,KAAK,CAAA;AACnD,EAAA,MAAM,IAAA,GAAO,UAAU,CAAA,GAAI,KAAA,CAAM,OAAO,KAAA,CAAM,IAAA,CAAK,MAAM,KAAK,CAAA;AAE9D,EAAA,MAAM,SAA4B,EAAC;AACnC,EAAA,KAAA,MAAW,OAAO,IAAA,EAAM;AACtB,IAAA,MAAA,CAAO,IAAA,CAAK;AAAA,MACV,QAAA,EAAU,KAAA;AAAA,MACV,IAAA,EAAM,SAAA;AAAA,MACN,KAAA,EAAO,MAAA;AAAA,MACP,OAAA,EAAS,SAAA,GAAY,SAAA,CAAU,GAAG,IAAI,GAAA,CAAI,IAAA;AAAA;AAAA;AAAA;AAAA,MAI1C,IAAA,EAAM,EAAE,GAAA;AAA+C,KACxD,CAAA;AAAA,EACH;AACA,EAAA,OAAO,MAAA;AACT;AAgBA,SAAS,aAAmB,KAAA,EAA4B;AACtD,EAAA,MAAM,QAAkB,EAAC;AACzB,EAAA,KAAA,CAAM,IAAA,CAAK,IAAA,CAAK,SAAA,CAAU,EAAE,IAAA,EAAM,QAAQ,KAAA,EAAO,KAAA,CAAM,MAAA,EAAQ,CAAC,CAAA;AAEhE,EAAA,MAAM,QAAQ,KAAA,CAAM,KAAA;AACpB,EAAA,KAAA,IAAS,IAAI,CAAA,EAAG,CAAA,GAAI,KAAA,CAAM,IAAA,CAAK,QAAQ,CAAA,EAAA,EAAK;AAC1C,IAAA,MAAM,GAAA,GAAM,KAAA,CAAM,IAAA,CAAK,CAAC,CAAA;AACxB,IAAA,MAAM,SAAA,GAAY,KAAA,GACd,KAAA,CAAM,CAAC,CAAA,EAAG,KAAA,GACV,CAAA,KAAM,KAAA,CAAM,IAAA,CAAK,MAAA,GAAS,CAAA,GACxB,KAAA,CAAM,UAAA,GACN,IAAA;AACN,IAAA,KAAA,CAAM,IAAA,CAAK,IAAA,CAAK,SAAA,CAAU,EAAE,IAAA,EAAM,QAAQ,GAAA,EAAK,KAAA,EAAO,SAAA,EAAW,CAAC,CAAA;AAAA,EACpE;AACA,EAAA,OAAO,KAAA,CAAM,KAAK,IAAI,CAAA;AACxB;;;AC1fO,SAAS,WAAA,CAOd,OAAA,EACA,KAAA,EACA,IAAA,EACiB;AACjB,EAAA,IAAI,KAAA,CAAM,WAAW,IAAA,EAAM;AACzB,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACA,EAAA,MAAM,SAAS,QAAA,CAAS,OAAA,EAAS,KAAA,CAAM,MAAA,EAAQ,MAAM,IAAI,CAAA;AACzD,EAAA,MAAM,WAAW,KAAA,CAAM,UAAA;AAEvB,EAAA,MAAM,UAAA,GAAa,eAAA,CAAgB,QAAA,EAAU,MAAA,EAAQ,OAAO,CAAA;AAC5D,EAAA,IAAI,eAAe,IAAA,EAAM;AACvB,IAAA,OAAO,EAAE,OAAA,EAAS,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAAA,EAC3C;AACA,EAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,QAAA,EAAU,QAAQ,UAAA,EAAW;AACxD;AAaO,SAAS,SAAA,CAAU,GAAY,CAAA,EAAqB;AACzD,EAAA,OAAO,eAAA,CAAgB,CAAA,EAAG,CAAA,EAAG,OAAO,CAAA,KAAM,IAAA;AAC5C;AA2BA,SAAS,eAAA,CACP,QAAA,EACA,MAAA,EACA,IAAA,EACY;AAIZ,EAAA,IAAI,MAAA,CAAO,EAAA,CAAG,QAAA,EAAU,MAAM,GAAG,OAAO,IAAA;AAExC,EAAA,MAAM,EAAA,GAAK,OAAO,QAAQ,CAAA;AAC1B,EAAA,MAAM,EAAA,GAAK,OAAO,MAAM,CAAA;AAGxB,EAAA,IAAI,OAAO,EAAA,EAAI,OAAO,EAAE,IAAA,EAAM,UAAU,MAAA,EAAO;AAE/C,EAAA,IAAI,OAAO,OAAA,EAAS;AAClB,IAAA,MAAM,EAAA,GAAK,QAAA;AACX,IAAA,MAAM,EAAA,GAAK,MAAA;AACX,IAAA,IAAI,EAAA,CAAG,MAAA,KAAW,EAAA,CAAG,MAAA,EAAQ;AAG3B,MAAA,OAAO,EAAE,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAAA,IAClC;AACA,IAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,EAAA,CAAG,QAAQ,CAAA,EAAA,EAAK;AAClC,MAAA,MAAM,CAAA,GAAI,eAAA,CAAgB,EAAA,CAAG,CAAC,CAAA,EAAG,EAAA,CAAG,CAAC,CAAA,EAAG,SAAA,CAAU,IAAA,EAAM,CAAC,CAAC,CAAA;AAC1D,MAAA,IAAI,CAAA,KAAM,MAAM,OAAO,CAAA;AAAA,IACzB;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,IAAI,OAAO,QAAA,EAAU;AACnB,IAAA,MAAM,EAAA,GAAK,QAAA;AACX,IAAA,MAAM,EAAA,GAAK,MAAA;AAIX,IAAA,KAAA,MAAW,GAAA,IAAO,SAAA,CAAU,EAAA,EAAI,EAAE,CAAA,EAAG;AACnC,MAAA,MAAM,CAAA,GAAI,eAAA,CAAgB,EAAA,CAAG,GAAG,CAAA,EAAG,EAAA,CAAG,GAAG,CAAA,EAAG,OAAA,CAAQ,IAAA,EAAM,GAAG,CAAC,CAAA;AAC9D,MAAA,IAAI,CAAA,KAAM,MAAM,OAAO,CAAA;AAAA,IACzB;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AAIA,EAAA,OAAO,EAAE,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAClC","file":"chunk-ZRRET3RP.js","sourcesContent":["// Capture the post-init State and applied Msg sequence for update-only replay.\n// `loaded` is the replay anchor, not the raw value read from the Store.\n// `trace-replay` folds from it without init, handlers or host context.\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 post-init State captured by `onBoot`, used directly as the recorded\n   * replay's starting State. No init call is repeated. `null` marks a missing\n   * anchor in an older or incomplete trace; `replayTrace` refuses it.\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; a trace without that anchor cannot replay.\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        // trace has no replay anchor and replayTrace will refuse it.\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","// Recorded replay folds captured post-init State and reports the first divergence.\n\nimport { type Cmd, foldMsgs, type Machine, 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 * Folds recorded messages from the captured post-init State, without calling\n * init, Cmd handlers, Store operations or Sub runners. A trace without that\n * anchor is refused; a fresh init cannot reconstruct its starting State.\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    - optional legacy argument; recorded replay needs no init context.\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  if (trace.loaded === null) {\n    throw new Error(\n      \"tea replayTrace: trace has no captured initial State; record boot before replaying.\",\n    );\n  }\n  const actual = foldMsgs(machine, trace.loaded, trace.msgs);\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 third deep-compare. It is one\n * of two structural walkers in the package, divergent on purpose:\n * this `deepEqual` returns a boolean verdict (order-insensitive, for\n * replay/parity equality), and `devtools`'s `diffState` returns a change list\n * (for a human-readable diff view) — same shape, two 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"]}

package/dist/{core-CtvAyPpH.d.ts → core-DNDAEhO2.d.ts}

@@ -11,7 +11,7 @@ import { StandardSchemaV1 } from '@standard-schema/spec';
  * **Dependency direction (the actual decoupling):** this module imports
  * NOTHING from the runtime — no `run`/host/`Store`. The
  * runtime (`run`, the host, interpret, `Store`, subscribe — all in
- * `../index.ts`) imports *from* here; never the reverse. The root door
+ * `../index.ts`) imports *from* here; never the reverse. The root entry
  * re-exports this surface through `./index.ts`, and
  * `pure/import-graph.test.ts` is the regression fence asserting the pure
  * entrypoint's import graph never reaches `run`.
@@ -712,17 +712,14 @@ type Machine<S, M extends {
      * Boot the runtime. Called once by `run(...)` with whatever `Store.load()`
      * returned: `null` on fresh boot, the persisted state on rehydrate.
      *
-     * **Contract:** when `loaded !== null`, init MUST return `[loaded, []]` —
-     * no Cmds. Init's rehydrate branch is the migration / parse boundary, not
-     * the boot-effect hook. See Invariant 2 in `.patterns/tea/tea-invariants.md`.
+     * Both fresh and restored init may return a new State and Cmds. Init is
+     * pure: it describes effects; handlers perform them. The engine saves the
+     * returned State, reconciles its Subs, then runs its Cmds.
      *
-     * Boot effects routes:
-     *   - Stateless infrastructure → host module top, outside TEA.
-     *   - State-conditional resume → a `boot` Msg the host dispatches once
-     *     after `run(...)` returns.
-     *
-     * Violations are caught at runtime by `replay` (which throws with a
-     * pointer to the alternatives).
+     * Put state-conditional resume work here, with the in-flight phase in the
+     * returned State so a fast Sub cannot start it again. A host Msg sent after
+     * `ready` runs after Subs have opened and supplies no such ordering.
+     * Recorded replay starts from captured post-init State without calling init.
      */
     init: (loaded: S | null, ctx: Ctx) => readonly [S, readonly C[]];
     /**
@@ -808,4 +805,4 @@ declare function foldMsgs<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, base: S, msgs: readonly M[]): S;
 
-export { applyCell as $, type AnyCmdDef as A, type BuiltinSub as B, Cmd as C, type Dispose as D, type ErrorsOf as E, type InterpretCell as F, type MachineShape as G, type HandlerCtx as H, type Interpret as I, type NoCtx as J, OutcomeContractError as K, type OutcomeHelpers as L, type Machine as M, NoCellError as N, Outcome as O, type Port as P, type PortEmitter as Q, type RunHandlers as R, type Sub as S, type TimerDeps as T, type UpdateForm as U, type SubscribeArg as V, type Wired as W, type SyncReturn as X, UndeclaredFailureError as Y, acceptedTypes as Z, acceptsOf as _, type CmdOf as a, applyCellChecked as a0, describeMachine as a1, detectUpdateForm as a2, foldMsgs as a3, foldUpdates as a4, formOf as a5, msgKeysOf as a6, structuralHash as a7, subId as a8, subIdOf as a9, type CmdDef as b, type Subscribe as c, type SettledOk as d, type SettledErr as e, type TaggedError as f, type Reducer as g, type Settled as h, type Transitions as i, type InterpretDetached as j, type SubId as k, type DepKeyedSub as l, type TimerSub as m, type MalformedResult as n, type OkOfCmd as o, type DeclaredErrorsOf as p, type BuiltinSubType as q, type Tagged as r, type OkOf as s, type ErrOf as t, type CmdValue as u, AsyncSchemaError as v, type CmdInput as w, type ExhaustiveTransitions as x, type Identity as y, type InterpretArg as z };
+export { applyCell as $, type AnyCmdDef as A, type BuiltinSub as B, Cmd as C, type Dispose as D, type ErrorsOf as E, type InterpretCell as F, type MachineShape as G, type HandlerCtx as H, type Interpret as I, type NoCtx as J, OutcomeContractError as K, type OutcomeHelpers as L, type Machine as M, NoCellError as N, Outcome as O, type Port as P, type PortEmitter as Q, type RunHandlers as R, type Subscribe as S, type TimerDeps as T, type UpdateForm as U, type SubscribeArg as V, type Wired as W, type SyncReturn as X, UndeclaredFailureError as Y, acceptedTypes as Z, acceptsOf as _, type CmdOf as a, applyCellChecked as a0, describeMachine as a1, detectUpdateForm as a2, foldMsgs as a3, foldUpdates as a4, formOf as a5, msgKeysOf as a6, structuralHash as a7, subId as a8, subIdOf as a9, type CmdDef as b, type Sub as c, type SettledOk as d, type SettledErr as e, type TaggedError as f, type Reducer as g, type Settled as h, type Transitions as i, type InterpretDetached as j, type CmdInput as k, type SubId as l, type DepKeyedSub as m, type TimerSub as n, type MalformedResult as o, type OkOfCmd as p, type DeclaredErrorsOf as q, type BuiltinSubType as r, type Tagged as s, type OkOf as t, type ErrOf as u, type CmdValue as v, AsyncSchemaError as w, type ExhaustiveTransitions as x, type Identity as y, type InterpretArg as z };

package/dist/devtools/index.d.ts

@@ -1,4 +1,4 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
 
 /** One row of the `MsgLog`: a timestamp, a category and the text to show. */
 type MsgLogEntry = {
@@ -17,7 +17,7 @@ interface MsgLogProps {
 /**
  * React component that renders a list of `MsgLogEntry` rows as a message log.
  */
-declare function MsgLog({ history, className }: MsgLogProps): react_jsx_runtime.JSX.Element;
+declare function MsgLog({ history, className }: MsgLogProps): react.JSX.Element;
 
 /**
  * A single differing leaf value between two states.
@@ -102,7 +102,7 @@ interface StateDiffProps {
  * When the states are deeply equal the list is empty; a tiny "no changes" hint
  * renders so an operator can tell "equal" from "not yet computed".
  */
-declare function StateDiff({ expected, actual, className }: StateDiffProps): react_jsx_runtime.JSX.Element;
+declare function StateDiff({ expected, actual, className }: StateDiffProps): react.JSX.Element;
 
 /**
  * Props for `StateInspector`: the `state` to show, an optional `flashKey`, and
@@ -128,7 +128,7 @@ interface StateInspectorProps {
  * React component that renders a state value as formatted JSON, and flashes
  * when `flashKey` changes.
  */
-declare function StateInspector({ state, flashKey, className, }: StateInspectorProps): react_jsx_runtime.JSX.Element;
+declare function StateInspector({ state, flashKey, className, }: StateInspectorProps): react.JSX.Element;
 
 /**
  * Wrap a `dispatch` so every Msg it sees lands in a bounded history buffer.

package/dist/do/index.d.ts

@@ -1,18 +1,18 @@
-import { S as Store, b as BootedRunHandle, E as EngineRun, d as RunHandle, M as Migrated, F as FencedStore, D as DeletableStore } from '../runtime-types-DEluQgGO.js';
-import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-Ump5lSdO.js';
-export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, c as PendingEffectsLedger, d as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-Ump5lSdO.js';
+import { b as Store, a as BootedRunHandle, E as EngineRun, S as StoreAndOnError, e as RunHandle, M as Migrated, F as FencedStore, D as DeletableStore } from '../runtime-types-CP-ykwgf.js';
+import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-wLWEdy9H.js';
+export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, c as PendingEffectsLedger, d as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-wLWEdy9H.js';
 import { RetryPolicy, Rng } from '../retry-backoff/index.js';
-import { C as Cmd, S as Sub, M as Machine, W as Wired } from '../core-CtvAyPpH.js';
-import { A as AgentEvent, f as AgentTurn, e as AgentState, i as AgentMachineMsg, K as AgentStatus } from '../machine-Dtre2TmN.js';
+import { C as Cmd, c as Sub, M as Machine, W as Wired } from '../core-DNDAEhO2.js';
+import { A as AgentEvent, f as AgentTurn, e as AgentState, i as AgentMachineMsg, K as AgentStatus } from '../machine-C0WhOAyB.js';
 import '@standard-schema/spec';
-import '../index-CZZ3HI-Z.js';
-import '../index-Bk2hBUdK.js';
-import '../index-CVU7SK3a.js';
-import '../types-CXNzlbAg.js';
-import '../index-D3NY3VCN.js';
-import '../index-CKtEKGyp.js';
+import '../index-CAsUE_d1.js';
+import '../index-COeX9Bmz.js';
+import '../index-Cg0QXnzf.js';
+import '../types-S53WDy_h.js';
+import '../index-BBLI2WWN.js';
+import '../index-C92SgNWz.js';
 import '../protocol-ClRZBhHQ.js';
-import '../index-CrcoVfd_.js';
+import '../index-9P1PaXIV.js';
 
 /**
  * @demlik/tea/do — `stepHost`, the HTTP-PULL control carrier (#92).
@@ -344,14 +344,48 @@ declare function stepHost<R, I, O>(ctx: StepCtx, engine: StepEngine<R, I, O>, co
 type StepTransport<R, I, O> = (request: StepRequest<R>) => Promise<DeferredStepResponse<I, O>>;
 /** Execute one tool call and produce its result (the consumer's hands). */
 type ExecuteStep<I, R> = (step: NextStep<I>) => Promise<R> | R;
-/** Tuning for {@link runStepLoop}. */
-interface RunStepLoopConfig {
+/**
+ * What {@link ExecutedSteps} holds for a step that ran. The box is what tells a
+ * step whose result is `undefined` apart from a step that never ran, and it
+ * still does after a JSON round trip (`{}` is a box; a missing entry is not).
+ */
+interface ExecutedStep<R> {
+    readonly result: R;
+}
+/**
+ * The hands' memory of the steps they already ran, keyed by `callId`. Pass one
+ * that outlives the process and a restarted {@link runStepLoop} re-POSTs a saved
+ * result instead of running the step again.
+ *
+ * Use one store per run: a host's `callId` only has to be unique inside its run.
+ * The caller owns where it lives and when it is cleared.
+ */
+interface ExecutedSteps<R> {
+    /** The box saved for `callId`, or `undefined` if that step never ran. */
+    get(callId: string): Promise<ExecutedStep<R> | undefined> | ExecutedStep<R> | undefined;
+    /** Save the box for `callId`. Settled before the result is POSTed. */
+    set(callId: string, step: ExecutedStep<R>): Promise<void> | void;
+}
+/**
+ * Tuning for {@link runStepLoop}.
+ *
+ * `R` is the step result type, and only {@link RunStepLoopConfig.executed} reads
+ * it. It defaults to `never` because a bare `RunStepLoopConfig` says nothing
+ * about results: it has to fit a drive of any `R`, and a store of `unknown`
+ * could not hand a drive its `R` back.
+ */
+interface RunStepLoopConfig<R = never> {
     /**
      * Absolute wall-clock deadline (ms epoch). The loop stops asking once `now()`
      * reaches it, surfacing a `deadline_exceeded` outcome. Mirrors the poller's
      * absolute-deadline contract (a resumed loop honors the SAME moment).
      */
     readonly deadlineMs: number;
+    /**
+     * Where the hands remember the steps they ran. Defaults to a fresh in-memory
+     * store per drive, which a restart forgets. See {@link runStepLoop}.
+     */
+    readonly executed?: ExecutedSteps<R>;
     /** Backoff policy for FAILED `/step` POSTs. Defaults to `defaultRetryPolicy`. */
     readonly retry?: RetryPolicy;
     /** Clock, injected for determinism. Defaults to `Date.now`. */
@@ -384,17 +418,29 @@ type StepLoopOutcome<O> = {
  *   - **backoff** — a FAILED POST (transport reject) is retried on the
  *     `retry-backoff` curve; once `shouldRetry` is exhausted the loop stops
  *     with `gave_up`. A success resets the retry counter.
- *   - **dedupe** — a step whose `callId` was already executed in THIS drive is
- *     not re-executed; its prior result is re-POSTed. Closes the "the host
- *     re-handed the same step after a duplicate settle" path (the host side is
- *     idempotent; the hands match it).
+ *   - **dedupe** — a step whose `callId` is already in `config.executed` is not
+ *     re-executed; its saved result is re-POSTed. Closes the "the host re-handed
+ *     the same step after a duplicate settle" path (the host side is idempotent;
+ *     the hands match it). That memory lives in `config.executed`. Left out, it
+ *     is a fresh in-memory store that lasts one drive, so hands that restart
+ *     forget it and run the re-handed step again; pass a store that outlives the
+ *     process to keep it across restarts.
+ *   - **store failure** — a `get` or `set` that throws or rejects ends the drive
+ *     with `gave_up` carrying the store's error. A failed `get` runs nothing. A
+ *     failed `set` means the step ran but is not remembered, and its result is
+ *     not POSTed, so a later drive over that store would run it again.
  *   - **not-ready re-poll** — a {@link StepWorking} arm (a defer-resume host
  *     computing the step out-of-band) is not a step: the loop re-POSTs the SAME
  *     `posted` after a backoff (honoring the host's advisory `retryAfterMs`),
  *     until a real step / done arrives. Bounded only by the absolute deadline —
  *     an inline host never returns this arm, so its drive is unchanged.
+ *
+ * **Crash window:** a store gives "run once per `callId`" except between
+ * `execute` finishing and `set` landing. Hands that die there have run the step
+ * with no record of it, and the next drive runs it again. No store can close
+ * that: the step itself has to be safe to repeat, as with `idempotentEffect`.
  */
-declare function runStepLoop<R, I, O>(token: string, runId: string, transport: StepTransport<R, I, O>, execute: ExecuteStep<I, R>, config: RunStepLoopConfig): Promise<StepLoopOutcome<O>>;
+declare function runStepLoop<R, I, O>(token: string, runId: string, transport: StepTransport<R, I, O>, execute: ExecuteStep<I, R>, config: RunStepLoopConfig<R>): Promise<StepLoopOutcome<O>>;
 
 /**
  * `@demlik/tea/do` — the durable-timer / alarm-carrier port (#180).
@@ -533,9 +579,9 @@ declare function durableTimer(config: DurableTimerConfig): DurableTimer;
  *      replay bounded by ELAPSED TIME/TICKS rather than raw event count drives
  *      `snapshotNow()` instead (or alongside) — see that method.
  *   3. On activation REBUILDS state by FOLDING the log on top of the latest
- *      snapshot. The fold is the substrate's own `replay` — `init(snapshot)`
- *      then one reducer step per logged Msg. `replay` returns Cmds as data and
- *      never interprets them, so **side effects are suppressed on replay**
+ *      snapshot. The fold starts directly from a snapshot; without one it
+ *      starts from fresh init. One reducer step per logged Msg follows, with
+ *      no Cmd handlers executed: **side effects are suppressed on replay**
  *      (recovery.md). This is the same primitive `foldEvents` / the recorder
  *      use; it is reused here, not reinvented (ADR 0003: "the fold already
  *      exists; wire it to Store").
@@ -702,12 +748,10 @@ interface EventSourcedStore<S, M> {
  * count-based snapshot is taken. The cooperating DO additionally calls
  * `append(msg)` from `runtime.observe` to grow the log.
  *
- * `machine` and `ctx` are required because the fold is `replay(machine, {
- * loaded: snapshot, msgs: log, ctx })` — the same pure reducer the live runtime
- * uses, so the rebuilt state is identical to the never-evicted state by
- * construction. `ctx` is only used to satisfy `init`'s signature during the
- * fold; an event-sourced machine's `init` rehydrate branch is a pure
- * passthrough (TEA invariant 2), so the fold touches nothing in `ctx`.
+ * Snapshot recovery folds update directly from the captured State; it does
+ * not initialize that State again. With no snapshot, `ctx` supplies the fresh
+ * init used to establish the event log's starting State. Live resume commands
+ * belong to the runtime's subsequent init over the recovered State.
  */
 declare function doEventSourcedStore<S, M extends {
     type: string;
@@ -1078,8 +1122,16 @@ declare function sseFromAgentEvents<R, Frame>(runtime: {
  * `C`/`U`/`Ctx` are the machine's own Cmd/Sub/Ctx — inferred from
  * `buildMachine` at the `createAgentHost` call site (never name them by hand;
  * an erased `any` here cost consumers all checking on this layer — #278).
+ *
+ * `store` is required, and a fenced one needs an `onError` (see
+ * {@link StoreAndOnError}).
  */
-interface AgentHostConfig<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame, C extends Cmd = Cmd, U extends Sub = Sub, Ctx = unknown> {
+type AgentHostConfig<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame, C extends Cmd = Cmd, U extends Sub = Sub, Ctx = unknown> = AgentHostWiring<Stage, P, O, R, Frame, C, U, Ctx> & StoreAndOnError<AgentState<Stage, P, O, R>> & {
+    /** The durable `Store` for the agent slice (typically `doStore(storage, parse)`). */
+    readonly store: Store<AgentState<Stage, P, O, R>>;
+};
+/** The part of {@link AgentHostConfig} that is not the store and its sink. */
+interface AgentHostWiring<Stage, P extends string, O extends Record<P, AgentTurn>, R, Frame, C extends Cmd = Cmd, U extends Sub = Sub, Ctx = unknown> {
     /**
      * The engine's `run` — `run` from `@demlik/tea/promise`, or any engine's. The
      * host imports no engine; it boots the machine through this.
@@ -1093,8 +1145,6 @@ interface AgentHostConfig<Stage, P extends string, O extends Record<P, AgentTurn
      * here, and `agent.toMachine({ toolInterpret })` already returns exactly this.
      */
     readonly buildMachine: () => Wired<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, C, U, Ctx>;
-    /** The durable `Store` for the agent slice (typically `doStore(storage, parse)`). */
-    readonly store: Store<AgentState<Stage, P, O, R>>;
     /** The plain Ctx the machine threads to its interpret cells. */
     readonly ctx: Ctx;
     /**
@@ -1153,9 +1203,11 @@ interface AgentHost<Stage, P extends string, O extends Record<P, AgentTurn>, R,
      */
     readonly sse: SseHub<Frame>;
     /**
-     * Tear down the cached runtime (drain its tail via `stop()`, drop the handle)
-     * so the next `runtime()` rebuilds from storage. The framework `settle` test
-     * seam, owned once.
+     * Tear down the cached runtime (drain its tail via `stop()`, up to
+     * `disposeTimeoutMs`, then drop the handle) so the next `runtime()` rebuilds
+     * from storage. A Cmd handler that has not returned by the limit is given up
+     * on, so `reset()` returns either way. The framework `settle` test seam,
+     * owned once.
      */
     reset(): Promise<void>;
 }
@@ -1436,6 +1488,11 @@ interface ResumePort<S, M extends {
  * hand-written `if (isResumable(state)) await runtime.dispatch(bootMsg(now()))`
  * every DO-hosted machine otherwise re-derives.
  *
+ * Use this when the host deliberately supplies a Msg after boot, including
+ * the existing agent boot protocol. Subs are already open after `ready`; this
+ * helper cannot order resume ahead of their Msgs. Prefer restored init Cmds
+ * when the machine owns its first move, and do not resume the same work twice.
+ *
  * `await ready` is the single boot gate (issue #45): `getState()` is total only
  * on the booted handle, so state cannot be inspected before boot populates
  * it. Takes any engine's {@link RunHandle}. `now` is injected (the sole boot clock read) so a test can pin it.
@@ -1462,7 +1519,7 @@ declare function agentIsResumable<Stage, P extends string, O extends Record<P, u
  * resumable, a no-op on a fresh DO. Wires the agent slice's `agentIsResumable`
  * predicate + the agent-owned `agentBootMsg` typed port into the
  * generalized helper, so the resume dispatch lives in ONE place — see
- * `bootResume`'s docblock for the boot-gate / init-purity rationale.
+ * `bootResume`'s docblock for the post-boot ordering boundary.
  *
  * `now` is injected (the host's only clock read for boot) so a test can pin it.
  */
@@ -1953,7 +2010,8 @@ interface DoStoreOptions<S> {
      * `storage.transaction`, so the read, the compare and the two writes are one
      * atomic unit. Inside a single DO the platform already guarantees one writer;
      * fencing is what refuses a SECOND grain — a stale zombie isolate mid-migration,
-     * or a second DO id pointed at the same state by a routing bug.
+     * or a second DO id pointed at the same state by a routing bug. A run on a
+     * fenced store must be given an `onError` (see `StoreAndOnError`).
      */
     readonly fenced?: true;
 }
@@ -2000,10 +2058,17 @@ interface DoStoreOptions<S> {
  *
  * Either form is a `DeletableStore<S>`: `delete()` removes the state cell and
  * its `<key>@@version` cell in one `storage.delete` call.
+ *
+ * Options whose `fenced` is known only at runtime, such as a value typed
+ * {@link DoStoreOptions}, return a store that may be fenced, so a run on it must
+ * be given an `onError` (see `StoreAndOnError`).
  */
 declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => Migrated<S>, keyOrOptions: DoStoreOptions<S> & {
     readonly fenced: true;
 }): FencedStore<S> & DeletableStore<S>;
-declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => Migrated<S>, keyOrOptions?: string | DoStoreOptions<S>): DeletableStore<S>;
+declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => Migrated<S>, keyOrOptions?: string | (DoStoreOptions<S> & {
+    readonly fenced?: never;
+})): DeletableStore<S>;
+declare function doStore<S>(storage: DurableObjectStorage, parse: (raw: unknown) => Migrated<S>, keyOrOptions?: string | DoStoreOptions<S>): DeletableStore<S> | (FencedStore<S> & DeletableStore<S>);
 
-export { type AgentHost, type AgentHostConfig, type AlarmStorage, type AppliedEffects, type AppliedEffectsEvent, type AppliedEffectsGuard, type AttachableSocket, type BroadcastOptions, type BroadcastReport, type DeferResumeHook, type DeferStepHostConfig, type DeferredGateway, type DeferredStepOutcome, type DeferredStepResponse, type DoStoreOptions, type DurableCommandCarrier, type DurableTimer, type DurableTimerConfig, type EffectApplied, EffectConfirmed, type EffectForgotten, type EffectKey, EffectOwed, type EventLogRange, type EventSourcedOptions, type EventSourcedStore, type ExecuteStep, type HibernatableCtx, type IdempotentEffect, type IdempotentOutcome, type NextStep, PendingEffectsRecorder, type PersistedEvent, type PresenceCtx, type PresenceSocket, type PresenceUpgrade, type Projection, type ProjectionErrorContext, type ProjectionId, type ProjectionOnError, type ProjectionRegistry, type ProjectionRunner, type ProjectionUpdate, type RegisterOptions, type ResumePort, type RunStepLoopConfig, type SseHub, type StepCtx, type StepEngine, type StepHostConfig, type StepLoopOutcome, type StepOutcome, type StepRequest, type StepResponse, type StepResult, type StepTransport, type StepWorking, WS_READY_STATE_OPEN, acceptCommandSocket, acceptDurableCommandSocket, acceptPresenceSocket, agentIsResumable, appliedEffects, applyAppliedEvent, autoBoot, bootResume, broadcast, broadcastFrame, broadcastHibernatable, constantTimeEqual, createAgentHost, deferredGateway, doEventSourcedStore, doStore, driveProjections, durableCommandCarrier, durableDeferredGateway, durableTimer, emptyApplied, foldApplied, idempotentEffect, isApplied, mintRunToken, presenceCount, projectionIdString, projectionRegistry, rebuildProjection, registerHibernatableSocket, reissueSurvivingEffects, runProjection, runStepLoop, sseFromAgentEvents, sseHub, sseProjection, stepHost };
+export { type AgentHost, type AgentHostConfig, type AgentHostWiring, type AlarmStorage, type AppliedEffects, type AppliedEffectsEvent, type AppliedEffectsGuard, type AttachableSocket, type BroadcastOptions, type BroadcastReport, type DeferResumeHook, type DeferStepHostConfig, type DeferredGateway, type DeferredStepOutcome, type DeferredStepResponse, type DoStoreOptions, type DurableCommandCarrier, type DurableTimer, type DurableTimerConfig, type EffectApplied, EffectConfirmed, type EffectForgotten, type EffectKey, EffectOwed, type EventLogRange, type EventSourcedOptions, type EventSourcedStore, type ExecuteStep, type ExecutedStep, type ExecutedSteps, type HibernatableCtx, type IdempotentEffect, type IdempotentOutcome, type NextStep, PendingEffectsRecorder, type PersistedEvent, type PresenceCtx, type PresenceSocket, type PresenceUpgrade, type Projection, type ProjectionErrorContext, type ProjectionId, type ProjectionOnError, type ProjectionRegistry, type ProjectionRunner, type ProjectionUpdate, type RegisterOptions, type ResumePort, type RunStepLoopConfig, type SseHub, type StepCtx, type StepEngine, type StepHostConfig, type StepLoopOutcome, type StepOutcome, type StepRequest, type StepResponse, type StepResult, type StepTransport, type StepWorking, WS_READY_STATE_OPEN, acceptCommandSocket, acceptDurableCommandSocket, acceptPresenceSocket, agentIsResumable, appliedEffects, applyAppliedEvent, autoBoot, bootResume, broadcast, broadcastFrame, broadcastHibernatable, constantTimeEqual, createAgentHost, deferredGateway, doEventSourcedStore, doStore, driveProjections, durableCommandCarrier, durableDeferredGateway, durableTimer, emptyApplied, foldApplied, idempotentEffect, isApplied, mintRunToken, presenceCount, projectionIdString, projectionRegistry, rebuildProjection, registerHibernatableSocket, reissueSurvivingEffects, runProjection, runStepLoop, sseFromAgentEvents, sseHub, sseProjection, stepHost };

package/dist/do/index.js

@@ -1,20 +1,22 @@
-import { status, agentBootMsg, AGENT_EVENT_TYPES, agentEvents } from '../chunk-2774I242.js';
-import { createIntake } from '../chunk-NGYFBD5G.js';
+import { status, agentBootMsg, AGENT_EVENT_TYPES, agentEvents } from '../chunk-WZEDIUWR.js';
+import { createIntake } from '../chunk-J5JNLXO7.js';
 export { applyEffectEvent, emptyLedger, foldLedger, isOwed, pendingEffectsLedger, survivingEffects } from '../chunk-6IQPODUF.js';
-import '../chunk-EA47MI5Q.js';
-import '../chunk-2R62Q5UK.js';
+import '../chunk-VH5MYJ2K.js';
+import '../chunk-IAHEYPYJ.js';
 import '../chunk-QNGYQMZB.js';
-import '../chunk-72CN3VPY.js';
-import '../chunk-TAKPC6SD.js';
+import '../chunk-NFOGYDRS.js';
+import '../chunk-UGTC33VH.js';
 import { defaultRetryPolicy, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-VBDU4JL6.js';
 import '../chunk-PR6TB3BL.js';
 import '../chunk-4LPY67E4.js';
 import '../chunk-TXN2KFHF.js';
-import '../chunk-JAKM53JF.js';
-import '../chunk-UHAQ4PI6.js';
-import '../chunk-A73IJ27X.js';
-import '../chunk-DVNXEB7V.js';
-import { StoreConflictError, replay } from '../chunk-RKVUVALV.js';
+import '../chunk-7K7SEYCH.js';
+import '../chunk-GFGOQIEC.js';
+import '../chunk-2A5XTKQQ.js';
+import '../chunk-R2YNDRGL.js';
+import '../chunk-DEAPNMKO.js';
+import '../chunk-BVFS3ICC.js';
+import { StoreConflictError, replay, foldMsgs } from '../chunk-A3QPMX5M.js';
 
 // src/do/durable-timer.ts
 function durableTimer(config) {
@@ -101,11 +103,7 @@ function doEventSourcedStore(storage, machine, ctx, opts = {}) {
       snapshotSeq = snapSeq;
       lastSeq = await readMeta();
       const events = await readLog(snapSeq);
-      const { state } = replay(machine, {
-        msgs: events,
-        ctx,
-        loaded: snapshot
-      });
+      const state = snapshot === null ? replay(machine, { msgs: events, ctx }).state : foldMsgs(machine, snapshot, events);
       if (!readyFired) {
         readyFired = true;
         opts.onReady?.(state);
@@ -253,6 +251,7 @@ function createAgentHost(config) {
       ...wired,
       ...ctxArg,
       store: config.store,
+      onError: config.onError,
       events: agentEvents()
     });
     sseFromAgentEvents(booting, sse, config.toSseFrame);
@@ -658,7 +657,7 @@ async function runStepLoop(token, runId, transport, execute, config) {
   const now = config.now ?? Date.now;
   const sleep = config.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const rng = config.rng;
-  const executed = /* @__PURE__ */ new Map();
+  const executed = config.executed ?? stepsInMemory();
   let posted = null;
   let pollRetry = initRetry();
   for (; ; ) {
@@ -685,12 +684,32 @@ async function runStepLoop(token, runId, transport, execute, config) {
     }
     pollRetry = initRetry();
     const step = response.step;
-    const cached = executed.get(step.callId);
-    const result = cached !== void 0 ? cached : await execute(step);
-    if (cached === void 0) executed.set(step.callId, result);
-    posted = { callId: step.callId, result };
+    let saved;
+    try {
+      saved = await executed.get(step.callId);
+    } catch (error) {
+      return { kind: "gave_up", error };
+    }
+    if (saved === void 0) {
+      saved = { result: await execute(step) };
+      try {
+        await executed.set(step.callId, saved);
+      } catch (error) {
+        return { kind: "gave_up", error };
+      }
+    }
+    posted = { callId: step.callId, result: saved.result };
   }
 }
+function stepsInMemory() {
+  const steps = /* @__PURE__ */ new Map();
+  return {
+    get: (callId) => steps.get(callId),
+    set: (callId, step) => {
+      steps.set(callId, step);
+    }
+  };
+}
 
 // src/do/index.ts
 var DEFAULT_STATE_KEY = "@@state";