@demlik/tea 0.3.0 → 0.5.0

package/dist/{chunk-MVY5DAMF.js → chunk-KWPB6BM6.js}

@@ -1,5 +1,5 @@
-import { tryInterpret } from './chunk-BP2R7TPP.js';
-import { Cmd } from './chunk-PBDYW2TU.js';
+import { tryInterpret } from './chunk-PBAYOJJO.js';
+import { Cmd } from './chunk-DBOJ2UC6.js';
 
 // src/snapshot/index.ts
 var DEFAULT_SNAPSHOT_KEY = "@@snapshot";
@@ -89,5 +89,5 @@ function createSnapshot(config) {
 }
 
 export { createSnapshot, snapshotFailed, snapshotLoadFailed, snapshotLoaded, snapshotSaved };
-//# sourceMappingURL=chunk-MVY5DAMF.js.map
-//# sourceMappingURL=chunk-MVY5DAMF.js.map
+//# sourceMappingURL=chunk-KWPB6BM6.js.map
+//# sourceMappingURL=chunk-KWPB6BM6.js.map

package/dist/{chunk-MVY5DAMF.js.map → chunk-KWPB6BM6.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/snapshot/index.ts"],"names":[],"mappings":"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","file":"chunk-MVY5DAMF.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"]}
+{"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-KWPB6BM6.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-C6QC273X.js → chunk-LFW66IIV.js}

@@ -1,5 +1,5 @@
-import { replay } from './chunk-BP2R7TPP.js';
-import { applyCell } from './chunk-PBDYW2TU.js';
+import { replay } from './chunk-PBAYOJJO.js';
+import { applyCell } from './chunk-DBOJ2UC6.js';
 import * as fc from 'fast-check';
 
 // src/pbt/runners/replay-fold.ts
@@ -67,5 +67,5 @@ function propertyTrace(machine, ctx, seqArb, predicate, opts) {
 }
 
 export { foldEvents, propertyInvariant, propertyTerminates, propertyTrace };
-//# sourceMappingURL=chunk-C6QC273X.js.map
-//# sourceMappingURL=chunk-C6QC273X.js.map
+//# sourceMappingURL=chunk-LFW66IIV.js.map
+//# sourceMappingURL=chunk-LFW66IIV.js.map

package/dist/{chunk-C6QC273X.js.map → chunk-LFW66IIV.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/pbt/runners/replay-fold.ts","../src/pbt/runners/property.ts"],"names":[],"mappings":"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","file":"chunk-C6QC273X.js","sourcesContent":["// ---------------------------------------------------------------------------\n// `foldEvents` — pure deterministic fold over a Msg sequence.\n//\n// PBT needs the per-step (prev/msg/next/cmds) structure to assert\n// step-shaped invariants. The substrate's `replay(machine, opts)` returns\n// only final state + cumulative cmds — insufficient. We use `replay` for\n// the boot step (calls `machine.init(loaded, ctx)` faithfully) then walk\n// msgs ourselves through `applyCell`, the substrate's own cell dispatch.\n//\n// Why walk cells directly instead of looping `replay` once per msg with\n// `loaded: prevState`? Because `init(loaded)` runs every call, and on\n// machines with non-trivial init transforms (e.g. the audit machine's\n// `auditing → attach_debugger` resume cell) that would either (a) re-fire\n// the transform on every step, or (b) require fragile cmd-subtraction to\n// isolate this step's cmds. Calling the cells directly keeps the fold pure\n// and the cmds per-step exactly.\n//\n// Dispatches through `applyCell` — the single primitive `run`/`replay` use —\n// so form classification agrees with production by construction (#275).\n//\n// `foldEvents` does NOT call `interpret`, does NOT touch a Store, does NOT\n// start Subs. The reducer surface is the contract.\n// ---------------------------------------------------------------------------\n\nimport {\n  applyCell,\n  type Cmd,\n  type Machine,\n  replay,\n  type Sub,\n} from \"../../index\";\n\n/**\n * One unit in a fold trace — the four pieces of data a property\n * invariant typically asserts on. `prev` is the state before the msg\n * applied; `next` is the state after; `cmds` is the cmds emitted by this\n * single step (NOT the running total).\n */\nexport interface Step<S, M, C> {\n  readonly prev: S;\n  readonly msg: M;\n  readonly next: S;\n  readonly cmds: readonly C[];\n}\n\n/**\n * Fold a Msg sequence through a machine's pure reducer, returning the\n * per-step trace, every state in order, and the final state. Initial\n * state comes from `replay(machine, { msgs: [], ctx, loaded })` — i.e.\n * `machine.init(loaded ?? null, ctx)` faithfully. Init's emitted cmds\n * are NOT included in any `Step` (they're the boot moment, not a Msg).\n *\n * @param machine  The machine under test.\n * @param ctx      The Ctx — typically `stubCtxThrowingProxy<Ctx>()` when\n *                 init is pure. Pass a real ctx if init reads from it.\n * @param loaded   Optional pre-init snapshot (the `loaded` arg to\n *                 `machine.init`). Defaults to `null` (fresh boot).\n * @param msgs     The Msg sequence to fold.\n *\n * @example\n *   const { states, steps, finalState } = foldEvents(machine, ctx, null, [\n *     { type: \"start\" }, { type: \"tick\" }, { type: \"stop\" },\n *   ]);\n *   // steps[1] = { prev: { type: \"counting\", n: 0 }, msg: { type: \"tick\" }, ... }\n */\nexport function foldEvents<\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  ctx: NoInfer<Ctx>,\n  loaded: NoInfer<S> | null,\n  msgs: readonly NoInfer<M>[],\n): {\n  readonly states: readonly S[];\n  readonly steps: readonly Step<S, M, C>[];\n  readonly finalState: S;\n} {\n  // Boot through `replay` so `init` runs faithfully and we honor the\n  // substrate's loaded-snapshot contract (init may transform the loaded\n  // value before the first Msg lands — e.g. the audit machine flips\n  // `debuggerAttached: false` on resume).\n  const { state: initialState } = replay(machine, {\n    msgs: [],\n    ctx,\n    loaded: loaded ?? null,\n  });\n\n  // Per-msg dispatch goes through `applyCell` — the same primitive `run` and\n  // `replay` use — so this runner classifies the update form identically to\n  // production (`formOf` honors the `__form` tag; #275).\n  const states: S[] = [initialState];\n  const steps: Step<S, M, C>[] = [];\n  let current = initialState;\n\n  for (const msg of msgs) {\n    const [next, emitted] = applyCell<S, M, C>(machine, current, msg);\n    steps.push({ prev: current, msg, next, cmds: [...emitted] });\n    states.push(next);\n    current = next;\n  }\n\n  return { states, steps, finalState: current };\n}\n","// ---------------------------------------------------------------------------\n// Property runners — three thin wrappers over `fc.assert(fc.property(...))`\n// that fold a generated Msg sequence through the machine via `foldEvents`\n// and pipe the result into a TEA-shaped predicate.\n//\n//   - `propertyTerminates` — every sequence ends in a terminal state.\n//   - `propertyInvariant`  — predicate holds on every (prev, msg, next, cmds) step.\n//   - `propertyTrace`      — predicate holds on the full (trace, final) shape.\n//\n// Each runner accepts `numRuns` (passed through to fast-check), an optional\n// `loaded` snapshot (forwarded to `foldEvents`), and the Msg-sequence\n// arbitrary. They return `void`; failures throw via fast-check's standard\n// shrinking output.\n//\n// Default shrinker is fast-check's built-in (open question 4): drop-msg /\n// prefix shrinkers can be layered later but are opt-in, not default. The\n// built-in shrinker handles array-shape shrinking + per-element variant\n// shrinking automatically.\n// ---------------------------------------------------------------------------\n\nimport * as fc from \"fast-check\";\nimport type { Cmd, Machine, Sub } from \"../../index\";\nimport { foldEvents, type Step } from \"./replay-fold\";\n\n/** Common options shared by every property runner. */\ninterface PropertyOpts<S> {\n  /** Pre-init snapshot — passed to `machine.init(loaded, ctx)`. Default `null`. */\n  readonly loaded?: S | null;\n  /** Number of generated sequences to test. Forwarded to `fc.assert`. */\n  readonly numRuns?: number;\n  /** Optional fast-check seed for reproducibility. */\n  readonly seed?: number;\n}\n\n/** The `foldEvents` result a runner's `check` inspects. */\ntype FoldResult<S, M, C> = {\n  readonly states: readonly S[];\n  readonly steps: readonly Step<S, M, C>[];\n  readonly finalState: S;\n};\n\n/**\n * Build the fast-check parameters shared by every runner: the 200-default\n * `numRuns` plus an optional `seed`. Single source of truth so a change to\n * the default lands in one place.\n */\nfunction resolveFcParams<M>(\n  opts: PropertyOpts<unknown> | undefined,\n): fc.Parameters<[readonly M[]]> {\n  return {\n    numRuns: opts?.numRuns ?? 200,\n    ...(opts?.seed !== undefined ? { seed: opts.seed } : {}),\n  };\n}\n\n/**\n * The fold+assert core every runner shares: assert `check` over each\n * generated Msg sequence, folded once through the machine via `foldEvents`.\n * `check` throws on failure so the error message carries the offending\n * shape into fast-check's shrunk counter-example.\n */\nfunction runProperty<\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  ctx: Ctx,\n  seqArb: fc.Arbitrary<readonly M[]>,\n  opts: PropertyOpts<S> | undefined,\n  check: (result: FoldResult<S, M, C>) => void,\n): void {\n  fc.assert(\n    fc.property(seqArb, (msgs) => {\n      check(foldEvents(machine, ctx, opts?.loaded ?? null, msgs));\n    }),\n    resolveFcParams<M>(opts),\n  );\n}\n\n/**\n * Assert every generated Msg sequence ends in a terminal state. `terminal`\n * is the predicate that names the acceptable final states (often\n * `(s) => s.type === \"done\" || s.type === \"idle\"`).\n *\n * The \"every sequence\" property catches stuck states (machine gets to a\n * non-terminal state and no further msg can escape) AND silent loops\n * (every msg variant is a noop from a given state).\n *\n * @example\n *   propertyTerminates(\n *     auditBackgroundMachine,\n *     stubCtxThrowingProxy<BackgroundCtx>(),\n *     arbMsgSequence(msgArb, { minLength: 1, maxLength: 30 }),\n *     (s) => s.type === \"done\" || s.type === \"idle\",\n *     { loaded: auditingState, numRuns: 500 },\n *   );\n */\nexport function propertyTerminates<\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  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  terminal: (state: NoInfer<S>) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ finalState }) => {\n    if (!terminal(finalState)) {\n      // Throwing here (vs returning false) lets the error message carry\n      // the offending final state — fast-check pretty-prints it inside\n      // the shrunk counter-example.\n      throw new Error(\n        `propertyTerminates: final state did not match terminal predicate. ` +\n          `Final: ${JSON.stringify(finalState)}`,\n      );\n    }\n  });\n}\n\n/**\n * Assert a predicate holds on EVERY transition step in a generated\n * sequence. The predicate sees `{ prev, msg, next, cmds }` per step;\n * return true to accept, false (or throw) to fail.\n *\n * Use to pin a \"when X happens in state Y, cmd Z must be emitted\" rule.\n * The shrinker minimizes the offending sequence to the smallest Msg list\n * that still violates the predicate.\n *\n * @example\n *   // Pin the resume-handshake fix: `ws:client:hello` in auditing must\n *   // emit `send_ws { client:ready }`.\n *   propertyInvariant(\n *     auditBackgroundMachine, ctx,\n *     arbMsgSequence(msgArb, { prefix: [{ type: \"ws:client:hello\" }] }),\n *     ({ prev, msg, cmds }) =>\n *       !(prev.type === \"auditing\" && msg.type === \"ws:client:hello\") ||\n *       cmds.some((c) => c.type === \"send_ws\" && c.msg.type === \"client:ready\"),\n *     { loaded: auditingState, numRuns: 200 },\n *   );\n */\nexport function propertyInvariant<\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  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  invariant: (step: Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ steps }) => {\n    for (const step of steps) {\n      if (!invariant(step)) {\n        throw new Error(\n          `propertyInvariant: failed at step msg=${JSON.stringify(step.msg)} ` +\n            `prev=${JSON.stringify(step.prev)} next=${JSON.stringify(step.next)} ` +\n            `cmds=${JSON.stringify(step.cmds)}`,\n        );\n      }\n    }\n  });\n}\n\n/**\n * Assert a predicate over the full trace plus the final state. Use when\n * the property is \"some Msg appeared in the trace before reaching the\n * final state\" or \"no two consecutive steps had the same state.type\" —\n * predicates that need the full sequence, not a single step.\n *\n * @example\n *   propertyTrace(\n *     machine, ctx, seqArb,\n *     (steps, final) =>\n *       final.type !== \"done\" ||\n *       steps.some((step) => step.msg.type === \"ws:audit:done\"),\n *     { loaded: auditingState, numRuns: 500 },\n *   );\n */\nexport function propertyTrace<\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  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  predicate: (\n    steps: readonly Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>[],\n    finalState: NoInfer<S>,\n  ) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ steps, finalState }) => {\n    if (!predicate(steps, finalState)) {\n      throw new Error(\n        `propertyTrace: predicate failed on trace length=${steps.length}, ` +\n          `final=${JSON.stringify(finalState)}`,\n      );\n    }\n  });\n}\n"]}
+{"version":3,"sources":["../src/pbt/runners/replay-fold.ts","../src/pbt/runners/property.ts"],"names":[],"mappings":";;;;;AAiEO,SAAS,UAAA,CAOd,OAAA,EACA,GAAA,EACA,MAAA,EACA,IAAA,EAKA;AAKA,EAAA,MAAM,EAAE,KAAA,EAAO,YAAA,EAAa,GAAI,OAAO,OAAA,EAAS;AAAA,IAC9C,MAAM,EAAC;AAAA,IACP,GAAA;AAAA,IACA,QAAQ,MAAA,IAAU;AAAA,GACnB,CAAA;AAKD,EAAA,MAAM,MAAA,GAAc,CAAC,YAAY,CAAA;AACjC,EAAA,MAAM,QAAyB,EAAC;AAChC,EAAA,IAAI,OAAA,GAAU,YAAA;AAEd,EAAA,KAAA,MAAW,OAAO,IAAA,EAAM;AACtB,IAAA,MAAM,CAAC,IAAA,EAAM,OAAO,IAAI,SAAA,CAAmB,OAAA,EAAS,SAAS,GAAG,CAAA;AAChE,IAAA,KAAA,CAAM,IAAA,CAAK,EAAE,IAAA,EAAM,OAAA,EAAS,GAAA,EAAK,IAAA,EAAM,IAAA,EAAM,CAAC,GAAG,OAAO,CAAA,EAAG,CAAA;AAC3D,IAAA,MAAA,CAAO,KAAK,IAAI,CAAA;AAChB,IAAA,OAAA,GAAU,IAAA;AAAA,EACZ;AAEA,EAAA,OAAO,EAAE,MAAA,EAAQ,KAAA,EAAO,UAAA,EAAY,OAAA,EAAQ;AAC9C;;;AC5DA,SAAS,gBACP,IAAA,EAC+B;AAC/B,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,MAAM,OAAA,IAAW,GAAA;AAAA,IAC1B,GAAI,MAAM,IAAA,KAAS,MAAA,GAAY,EAAE,IAAA,EAAM,IAAA,CAAK,IAAA,EAAK,GAAI;AAAC,GACxD;AACF;AAQA,SAAS,WAAA,CAOP,OAAA,EACA,GAAA,EACA,MAAA,EACA,MACA,KAAA,EACM;AACN,EAAG,EAAA,CAAA,MAAA;AAAA,IACE,EAAA,CAAA,QAAA,CAAS,MAAA,EAAQ,CAAC,IAAA,KAAS;AAC5B,MAAA,KAAA,CAAM,WAAW,OAAA,EAAS,GAAA,EAAK,MAAM,MAAA,IAAU,IAAA,EAAM,IAAI,CAAC,CAAA;AAAA,IAC5D,CAAC,CAAA;AAAA,IACD,gBAAmB,IAAI;AAAA,GACzB;AACF;AAoBO,SAAS,kBAAA,CAOd,OAAA,EACA,GAAA,EACA,MAAA,EACA,UACA,IAAA,EACM;AACN,EAAA,WAAA,CAAY,SAAS,GAAA,EAAK,MAAA,EAAQ,MAAM,CAAC,EAAE,YAAW,KAAM;AAC1D,IAAA,IAAI,CAAC,QAAA,CAAS,UAAU,CAAA,EAAG;AAIzB,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,yEAAA,EACY,IAAA,CAAK,SAAA,CAAU,UAAU,CAAC,CAAA;AAAA,OACxC;AAAA,IACF;AAAA,EACF,CAAC,CAAA;AACH;AAuBO,SAAS,iBAAA,CAOd,OAAA,EACA,GAAA,EACA,MAAA,EACA,WACA,IAAA,EACM;AACN,EAAA,WAAA,CAAY,SAAS,GAAA,EAAK,MAAA,EAAQ,MAAM,CAAC,EAAE,OAAM,KAAM;AACrD,IAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,MAAA,IAAI,CAAC,SAAA,CAAU,IAAI,CAAA,EAAG;AACpB,QAAA,MAAM,IAAI,KAAA;AAAA,UACR,CAAA,sCAAA,EAAyC,KAAK,SAAA,CAAU,IAAA,CAAK,GAAG,CAAC,CAAA,MAAA,EACvD,IAAA,CAAK,SAAA,CAAU,IAAA,CAAK,IAAI,CAAC,CAAA,MAAA,EAAS,IAAA,CAAK,SAAA,CAAU,IAAA,CAAK,IAAI,CAAC,SAC3D,IAAA,CAAK,SAAA,CAAU,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,SACrC;AAAA,MACF;AAAA,IACF;AAAA,EACF,CAAC,CAAA;AACH;AAiBO,SAAS,aAAA,CAOd,OAAA,EACA,GAAA,EACA,MAAA,EACA,WAIA,IAAA,EACM;AACN,EAAA,WAAA,CAAY,OAAA,EAAS,KAAK,MAAA,EAAQ,IAAA,EAAM,CAAC,EAAE,KAAA,EAAO,YAAW,KAAM;AACjE,IAAA,IAAI,CAAC,SAAA,CAAU,KAAA,EAAO,UAAU,CAAA,EAAG;AACjC,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,mDAAmD,KAAA,CAAM,MAAM,WACpD,IAAA,CAAK,SAAA,CAAU,UAAU,CAAC,CAAA;AAAA,OACvC;AAAA,IACF;AAAA,EACF,CAAC,CAAA;AACH","file":"chunk-LFW66IIV.js","sourcesContent":["// ---------------------------------------------------------------------------\n// `foldEvents` — pure deterministic fold over a Msg sequence.\n//\n// PBT needs the per-step (prev/msg/next/cmds) structure to assert\n// step-shaped invariants. The substrate's `replay(machine, opts)` returns\n// only final state + cumulative cmds — insufficient. We use `replay` for\n// the boot step (calls `machine.init(loaded, ctx)` faithfully) then walk\n// msgs ourselves through `applyCell`, the substrate's own cell dispatch.\n//\n// Why walk cells directly instead of looping `replay` once per msg with\n// `loaded: prevState`? Because `init(loaded)` runs every call, and on\n// machines with non-trivial init transforms (e.g. the audit machine's\n// `auditing → attach_debugger` resume cell) that would either (a) re-fire\n// the transform on every step, or (b) require fragile cmd-subtraction to\n// isolate this step's cmds. Calling the cells directly keeps the fold pure\n// and the cmds per-step exactly.\n//\n// Dispatches through `applyCell` — the single primitive `run`/`replay` use —\n// so form classification agrees with production by construction (#275).\n//\n// `foldEvents` does NOT call `interpret`, does NOT touch a Store, does NOT\n// start Subs. The reducer surface is the contract.\n// ---------------------------------------------------------------------------\n\nimport {\n  applyCell,\n  type Cmd,\n  type Machine,\n  replay,\n  type Sub,\n} from \"../../index\";\n\n/**\n * One unit in a fold trace — the four pieces of data a property\n * invariant typically asserts on. `prev` is the state before the msg\n * applied; `next` is the state after; `cmds` is the cmds emitted by this\n * single step (NOT the running total).\n */\nexport interface Step<S, M, C> {\n  readonly prev: S;\n  readonly msg: M;\n  readonly next: S;\n  readonly cmds: readonly C[];\n}\n\n/**\n * Fold a Msg sequence through a machine's pure reducer, returning the\n * per-step trace, every state in order, and the final state. Initial\n * state comes from `replay(machine, { msgs: [], ctx, loaded })` — i.e.\n * `machine.init(loaded ?? null, ctx)` faithfully. Init's emitted cmds\n * are NOT included in any `Step` (they're the boot moment, not a Msg).\n *\n * @param machine  The machine under test.\n * @param ctx      The Ctx — typically `stubCtxThrowingProxy<Ctx>()` when\n *                 init is pure. Pass a real ctx if init reads from it.\n * @param loaded   Optional pre-init snapshot (the `loaded` arg to\n *                 `machine.init`). Defaults to `null` (fresh boot).\n * @param msgs     The Msg sequence to fold.\n *\n * @example\n *   const { states, steps, finalState } = foldEvents(machine, ctx, null, [\n *     { type: \"start\" }, { type: \"tick\" }, { type: \"stop\" },\n *   ]);\n *   // steps[1] = { prev: { type: \"counting\", n: 0 }, msg: { type: \"tick\" }, ... }\n */\nexport function foldEvents<\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  ctx: NoInfer<Ctx>,\n  loaded: NoInfer<S> | null,\n  msgs: readonly NoInfer<M>[],\n): {\n  readonly states: readonly S[];\n  readonly steps: readonly Step<S, M, C>[];\n  readonly finalState: S;\n} {\n  // Boot through `replay` so `init` runs faithfully and we honor the\n  // substrate's loaded-snapshot contract (init may transform the loaded\n  // value before the first Msg lands — e.g. the audit machine flips\n  // `debuggerAttached: false` on resume).\n  const { state: initialState } = replay(machine, {\n    msgs: [],\n    ctx,\n    loaded: loaded ?? null,\n  });\n\n  // Per-msg dispatch goes through `applyCell` — the same primitive `run` and\n  // `replay` use — so this runner classifies the update form identically to\n  // production (`formOf` honors the `__form` tag; #275).\n  const states: S[] = [initialState];\n  const steps: Step<S, M, C>[] = [];\n  let current = initialState;\n\n  for (const msg of msgs) {\n    const [next, emitted] = applyCell<S, M, C>(machine, current, msg);\n    steps.push({ prev: current, msg, next, cmds: [...emitted] });\n    states.push(next);\n    current = next;\n  }\n\n  return { states, steps, finalState: current };\n}\n","// ---------------------------------------------------------------------------\n// Property runners — three thin wrappers over `fc.assert(fc.property(...))`\n// that fold a generated Msg sequence through the machine via `foldEvents`\n// and pipe the result into a TEA-shaped predicate.\n//\n//   - `propertyTerminates` — every sequence ends in a terminal state.\n//   - `propertyInvariant`  — predicate holds on every (prev, msg, next, cmds) step.\n//   - `propertyTrace`      — predicate holds on the full (trace, final) shape.\n//\n// Each runner accepts `numRuns` (passed through to fast-check), an optional\n// `loaded` snapshot (forwarded to `foldEvents`), and the Msg-sequence\n// arbitrary. They return `void`; failures throw via fast-check's standard\n// shrinking output.\n//\n// Default shrinker is fast-check's built-in (open question 4): drop-msg /\n// prefix shrinkers can be layered later but are opt-in, not default. The\n// built-in shrinker handles array-shape shrinking + per-element variant\n// shrinking automatically.\n// ---------------------------------------------------------------------------\n\nimport * as fc from \"fast-check\";\nimport type { Cmd, Machine, Sub } from \"../../index\";\nimport { foldEvents, type Step } from \"./replay-fold\";\n\n/** Common options shared by every property runner. */\ninterface PropertyOpts<S> {\n  /** Pre-init snapshot — passed to `machine.init(loaded, ctx)`. Default `null`. */\n  readonly loaded?: S | null;\n  /** Number of generated sequences to test. Forwarded to `fc.assert`. */\n  readonly numRuns?: number;\n  /** Optional fast-check seed for reproducibility. */\n  readonly seed?: number;\n}\n\n/** The `foldEvents` result a runner's `check` inspects. */\ntype FoldResult<S, M, C> = {\n  readonly states: readonly S[];\n  readonly steps: readonly Step<S, M, C>[];\n  readonly finalState: S;\n};\n\n/**\n * Build the fast-check parameters shared by every runner: the 200-default\n * `numRuns` plus an optional `seed`. Single source of truth so a change to\n * the default lands in one place.\n */\nfunction resolveFcParams<M>(\n  opts: PropertyOpts<unknown> | undefined,\n): fc.Parameters<[readonly M[]]> {\n  return {\n    numRuns: opts?.numRuns ?? 200,\n    ...(opts?.seed !== undefined ? { seed: opts.seed } : {}),\n  };\n}\n\n/**\n * The fold+assert core every runner shares: assert `check` over each\n * generated Msg sequence, folded once through the machine via `foldEvents`.\n * `check` throws on failure so the error message carries the offending\n * shape into fast-check's shrunk counter-example.\n */\nfunction runProperty<\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  ctx: Ctx,\n  seqArb: fc.Arbitrary<readonly M[]>,\n  opts: PropertyOpts<S> | undefined,\n  check: (result: FoldResult<S, M, C>) => void,\n): void {\n  fc.assert(\n    fc.property(seqArb, (msgs) => {\n      check(foldEvents(machine, ctx, opts?.loaded ?? null, msgs));\n    }),\n    resolveFcParams<M>(opts),\n  );\n}\n\n/**\n * Assert every generated Msg sequence ends in a terminal state. `terminal`\n * is the predicate that names the acceptable final states (often\n * `(s) => s.type === \"done\" || s.type === \"idle\"`).\n *\n * The \"every sequence\" property catches stuck states (machine gets to a\n * non-terminal state and no further msg can escape) AND silent loops\n * (every msg variant is a noop from a given state).\n *\n * @example\n *   propertyTerminates(\n *     auditBackgroundMachine,\n *     stubCtxThrowingProxy<BackgroundCtx>(),\n *     arbMsgSequence(msgArb, { minLength: 1, maxLength: 30 }),\n *     (s) => s.type === \"done\" || s.type === \"idle\",\n *     { loaded: auditingState, numRuns: 500 },\n *   );\n */\nexport function propertyTerminates<\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  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  terminal: (state: NoInfer<S>) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ finalState }) => {\n    if (!terminal(finalState)) {\n      // Throwing here (vs returning false) lets the error message carry\n      // the offending final state — fast-check pretty-prints it inside\n      // the shrunk counter-example.\n      throw new Error(\n        `propertyTerminates: final state did not match terminal predicate. ` +\n          `Final: ${JSON.stringify(finalState)}`,\n      );\n    }\n  });\n}\n\n/**\n * Assert a predicate holds on EVERY transition step in a generated\n * sequence. The predicate sees `{ prev, msg, next, cmds }` per step;\n * return true to accept, false (or throw) to fail.\n *\n * Use to pin a \"when X happens in state Y, cmd Z must be emitted\" rule.\n * The shrinker minimizes the offending sequence to the smallest Msg list\n * that still violates the predicate.\n *\n * @example\n *   // Pin the resume-handshake fix: `ws:client:hello` in auditing must\n *   // emit `send_ws { client:ready }`.\n *   propertyInvariant(\n *     auditBackgroundMachine, ctx,\n *     arbMsgSequence(msgArb, { prefix: [{ type: \"ws:client:hello\" }] }),\n *     ({ prev, msg, cmds }) =>\n *       !(prev.type === \"auditing\" && msg.type === \"ws:client:hello\") ||\n *       cmds.some((c) => c.type === \"send_ws\" && c.msg.type === \"client:ready\"),\n *     { loaded: auditingState, numRuns: 200 },\n *   );\n */\nexport function propertyInvariant<\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  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  invariant: (step: Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ steps }) => {\n    for (const step of steps) {\n      if (!invariant(step)) {\n        throw new Error(\n          `propertyInvariant: failed at step msg=${JSON.stringify(step.msg)} ` +\n            `prev=${JSON.stringify(step.prev)} next=${JSON.stringify(step.next)} ` +\n            `cmds=${JSON.stringify(step.cmds)}`,\n        );\n      }\n    }\n  });\n}\n\n/**\n * Assert a predicate over the full trace plus the final state. Use when\n * the property is \"some Msg appeared in the trace before reaching the\n * final state\" or \"no two consecutive steps had the same state.type\" —\n * predicates that need the full sequence, not a single step.\n *\n * @example\n *   propertyTrace(\n *     machine, ctx, seqArb,\n *     (steps, final) =>\n *       final.type !== \"done\" ||\n *       steps.some((step) => step.msg.type === \"ws:audit:done\"),\n *     { loaded: auditingState, numRuns: 500 },\n *   );\n */\nexport function propertyTrace<\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  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  predicate: (\n    steps: readonly Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>[],\n    finalState: NoInfer<S>,\n  ) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ steps, finalState }) => {\n    if (!predicate(steps, finalState)) {\n      throw new Error(\n        `propertyTrace: predicate failed on trace length=${steps.length}, ` +\n          `final=${JSON.stringify(finalState)}`,\n      );\n    }\n  });\n}\n"]}

package/dist/{chunk-BP2R7TPP.js → chunk-PBAYOJJO.js}

@@ -1,4 +1,4 @@
-import { detectUpdateForm, foldUpdates, structuralHash, applyCellChecked } from './chunk-PBDYW2TU.js';
+import { detectUpdateForm, foldUpdates, depsInactive, structuralHash, applyCellChecked } from './chunk-DBOJ2UC6.js';
 import { Result } from 'better-result';
 
 // src/observability.ts
@@ -65,6 +65,49 @@ var QuiescenceTimeoutError = class extends Error {
   name = "QuiescenceTimeoutError";
   _tag = "QuiescenceTimeoutError";
 };
+var RuntimeDiscardNotice = class extends Error {
+};
+var RuntimeDiscardedError = class extends RuntimeDiscardNotice {
+  constructor(pendingCmds) {
+    super(
+      `@demlik/tea: runtime stopped with ${pendingCmds} Cmd(s) in flight \u2014 their results will reach no listener. In React this is usually a ctx-identity change rebuilding useMachine's runtime mid-flight: stabilize the ctx (useMemo / useState) so the runtime outlives the Cmds it started. An intentional teardown (unmount, navigation) can silence this with a run({ onError }) sink that ignores phase: "discard".`
+    );
+    this.pendingCmds = pendingCmds;
+  }
+  name = "RuntimeDiscardedError";
+  _tag = "RuntimeDiscardedError";
+};
+var IdentityDropNotice = class extends RuntimeDiscardNotice {
+  constructor(msgType) {
+    super(
+      `@demlik/tea: Msg "${msgType}" was addressed to a different instance than this state owns and was dropped before \`update\` ran \u2014 the machine's \`identity\` filter working as declared. If this Msg was meant for THIS instance, its \`ofMsg\` projection disagrees with \`ofState\`; if the instance is being reused across runs, route the message to the run that owns it.`
+    );
+    this.msgType = msgType;
+  }
+  name = "IdentityDropNotice";
+  _tag = "IdentityDropNotice";
+};
+var DisposeTimeoutNotice = class extends RuntimeDiscardNotice {
+  constructor(pendingDisposals, timeoutMs) {
+    super(
+      `@demlik/tea: stop() gave up waiting for ${pendingDisposals} async teardown(s) after ${timeoutMs}ms \u2014 the resources they release may still be open. Make \`release\` / the Sub cleanup settle (bound its own IO), or raise run({ disposeTimeoutMs }).`
+    );
+    this.pendingDisposals = pendingDisposals;
+    this.timeoutMs = timeoutMs;
+  }
+  name = "DisposeTimeoutNotice";
+  _tag = "DisposeTimeoutNotice";
+};
+var DispatchDiscardedError = class extends RuntimeDiscardNotice {
+  constructor(msgType) {
+    super(
+      `@demlik/tea: Msg "${msgType}" arrived while the runtime was stopping and was discarded \u2014 stop() refuses new work so the drain terminates. It is the result of a Cmd that outlived its runtime; keep the runtime alive until the Cmd settles (in React: stabilize useMachine's ctx) if the transition matters.`
+    );
+    this.msgType = msgType;
+  }
+  name = "DispatchDiscardedError";
+  _tag = "DispatchDiscardedError";
+};
 function definePort(name) {
   let isHmr = false;
   try {
@@ -124,7 +167,8 @@ function replay(machine, opts) {
   if (machine.subs) {
     for (const [index, entry] of machine.subs.entries()) {
       const deps = entry.deps(state);
-      if (deps !== null) depSubs.push({ index, id: structuralHash(deps) });
+      if (!depsInactive(deps))
+        depSubs.push({ index, id: structuralHash(deps) });
     }
   }
   return { state, cmds, subs, depSubs };
@@ -154,6 +198,10 @@ function tryInterpret(work, onOk, onErr) {
 
 // src/run.ts
 function defaultOnError(error, _context) {
+  if (error instanceof RuntimeDiscardNotice) {
+    console.warn(error);
+    return;
+  }
   setTimeout(() => {
     throw error;
   }, 0);
@@ -167,6 +215,7 @@ function run(machine, opts) {
   const { store } = opts;
   const ctx = opts.ctx ?? {};
   const idleCap = opts.__idleCap ?? 1e5;
+  const disposeTimeoutMs = opts.disposeTimeoutMs ?? 5e3;
   const projectEvents = opts.events ?? (() => []);
   const isTerminal = opts.terminal ?? (() => false);
   const onError = opts.onError ?? defaultOnError;
@@ -189,7 +238,8 @@ function run(machine, opts) {
   const supervision = normalizeSupervision(opts.supervision);
   let state;
   let bootError = null;
-  let stopped = false;
+  let gate = "open";
+  let inFlightCmds = 0;
   const subRegistry = /* @__PURE__ */ new Map();
   const depSubRegistry = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Set();
@@ -211,19 +261,50 @@ function run(machine, opts) {
       const cleanup = subRegistry.get(id);
       if (cleanup === void 0) continue;
       try {
-        cleanup();
+        trackDisposal(cleanup());
       } catch (err) {
         reportError(err, { phase: "sub-cleanup" });
       }
       subRegistry.delete(id);
     }
   }
+  const pendingDisposals = /* @__PURE__ */ new Set();
+  function trackDisposal(result) {
+    if (!(result instanceof Promise)) return;
+    const settling = result.catch((err) => {
+      reportError(err, { phase: "sub-cleanup" });
+    }).finally(() => {
+      pendingDisposals.delete(settling);
+    });
+    pendingDisposals.add(settling);
+  }
+  async function drainDisposals() {
+    if (pendingDisposals.size === 0) return;
+    const outstanding = [...pendingDisposals];
+    let timer;
+    try {
+      const outcome = await Promise.race([
+        Promise.all(outstanding).then(() => "settled"),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve("timeout"), disposeTimeoutMs);
+        })
+      ]);
+      if (outcome === "timeout") {
+        reportError(
+          new DisposeTimeoutNotice(outstanding.length, disposeTimeoutMs),
+          { phase: "discard" }
+        );
+      }
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  }
   function disposeDepSubs(indices) {
     for (const index of indices) {
       const running = depSubRegistry.get(index);
       if (running === void 0) continue;
       try {
-        running.dispose();
+        trackDisposal(running.dispose());
       } catch (err) {
         reportError(err, { phase: "sub-cleanup" });
       }
@@ -235,19 +316,26 @@ function run(machine, opts) {
     const subs = machine.subs;
     if (!subs) return firstError;
     for (const [i, entry] of subs.entries()) {
-      const deps = entry.deps(state);
-      if (deps === null) {
-        disposeDepSubs([i]);
+      let deps;
+      let id;
+      try {
+        deps = entry.deps(state);
+        if (depsInactive(deps)) {
+          disposeDepSubs([i]);
+          continue;
+        }
+        id = structuralHash(deps);
+      } catch (err) {
+        if (firstError === null) firstError = err;
         continue;
       }
-      const id = structuralHash(deps);
       const running = depSubRegistry.get(i);
       if (running !== void 0 && running.runningId === id) {
         continue;
       }
       disposeDepSubs([i]);
       try {
-        const dispose = entry.source(state, enqueueDispatch, ctx);
+        const dispose = entry.source(state, dispatchUnawaited, ctx);
         depSubRegistry.set(i, { runningId: id, dispose });
       } catch (err) {
         if (firstError === null) firstError = err;
@@ -284,7 +372,7 @@ function run(machine, opts) {
         const cleanup = handler(
           sub,
           ctx,
-          enqueueDispatch
+          dispatchUnawaited
         );
         subRegistry.set(sub.id, cleanup);
       } catch (err) {
@@ -294,24 +382,33 @@ function run(machine, opts) {
     if (firstStartError !== null) throw firstStartError;
   }
   const interpretMap = machine.interpret ?? {};
-  const interpretDispatch = (msg) => {
-    enqueueDispatch(msg).catch((error) => {
-      reportError(error, { phase: "follow-up" });
-    });
+  const dispatchUnawaited = (msg) => {
+    enqueueDispatch(msg).catch(reportUndelivered);
   };
+  function reportUndelivered(error) {
+    reportError(error, {
+      phase: error instanceof DispatchDiscardedError ? "discard" : "follow-up"
+    });
+  }
+  function trackInFlight(work) {
+    inFlightCmds++;
+    return Promise.resolve(work).finally(() => {
+      inFlightCmds--;
+    });
+  }
   async function runInterpret(cmds) {
     for (const cmd of cmds) {
       const handler = interpretMap[cmd.type];
       if (!handler) continue;
-      const follow = await handler(
-        cmd,
-        augmentedCtx,
-        interpretDispatch
+      const follow = await trackInFlight(
+        handler(
+          cmd,
+          augmentedCtx,
+          dispatchUnawaited
+        )
       );
       if (follow !== void 0 && follow !== null) {
-        enqueueDispatch(follow).catch((error) => {
-          reportError(error, { phase: "follow-up" });
-        });
+        enqueueDispatch(follow).catch(reportUndelivered);
       }
     }
   }
@@ -362,22 +459,27 @@ function run(machine, opts) {
     fireEvents(msg);
     settleDoneWaiters();
   }
+  function isMisaddressed(msg, current) {
+    if (machine.identity === void 0) return false;
+    const addressed = machine.identity.ofMsg(msg);
+    if (addressed === void 0) return false;
+    const own = machine.identity.ofState(current);
+    if (own === void 0) return false;
+    return structuralHash(addressed) !== structuralHash(own);
+  }
   async function stepDispatch(msg) {
     if (state === void 0) {
       throw new Error("@demlik/tea: runtime not booted");
     }
-    if (machine.identity !== void 0) {
-      const addressed = machine.identity.ofMsg(msg);
-      if (addressed !== void 0) {
-        const own = machine.identity.ofState(state);
-        if (own !== void 0 && structuralHash(addressed) !== structuralHash(own)) {
-          return;
-        }
-      }
-    }
     let next;
     let cmds;
     try {
+      if (isMisaddressed(msg, state)) {
+        reportError(new IdentityDropNotice(msg.type), {
+          phase: "identity-drop"
+        });
+        return;
+      }
       [next, cmds] = applyCellChecked(machine, state, msg);
     } catch (reduceError) {
       reportError(reduceError, { phase: "reduce" });
@@ -389,7 +491,7 @@ function run(machine, opts) {
         case "escalate":
           throw reduceError;
         default:
-          stopped = true;
+          gate = "closed";
           throw reduceError;
       }
     }
@@ -417,8 +519,11 @@ function run(machine, opts) {
     settleDoneWaiters();
   }
   function enqueueDispatch(msg) {
-    if (stopped)
-      return Promise.reject(new Error("@demlik/tea: runtime stopped"));
+    if (gate !== "open") {
+      return Promise.reject(
+        gate === "draining" ? new DispatchDiscardedError(msg.type) : new Error("@demlik/tea: runtime stopped")
+      );
+    }
     const next = tail.then(() => {
       if (bootError !== null) throw bootError;
       return stepDispatch(msg);
@@ -527,10 +632,17 @@ function run(machine, opts) {
       });
     },
     async stop() {
-      stopped = true;
+      if (gate === "open") gate = "draining";
+      if (inFlightCmds > 0) {
+        reportError(new RuntimeDiscardedError(inFlightCmds), {
+          phase: "discard"
+        });
+      }
       await tail;
+      gate = "closed";
       stopSubs([...subRegistry.keys()]);
       disposeDepSubs([...depSubRegistry.keys()]);
+      await drainDisposals();
       if (store && state !== void 0 && bootError === null) {
         try {
           await store.save(state);
@@ -543,6 +655,6 @@ function run(machine, opts) {
   return runtime;
 }
 
-export { PortNameCollisionError, QuiescenceTimeoutError, SubIdCollisionError, __resetPortRegistry, absurd, asReducer, defineMachine, definePort, historyTracker, noop, replay, run, schemaMigrate, tryInterpret, wrapDetached };
-//# sourceMappingURL=chunk-BP2R7TPP.js.map
-//# sourceMappingURL=chunk-BP2R7TPP.js.map
+export { DispatchDiscardedError, DisposeTimeoutNotice, IdentityDropNotice, PortNameCollisionError, QuiescenceTimeoutError, RuntimeDiscardNotice, RuntimeDiscardedError, SubIdCollisionError, __resetPortRegistry, absurd, asReducer, defineMachine, definePort, historyTracker, noop, replay, run, schemaMigrate, tryInterpret, wrapDetached };
+//# sourceMappingURL=chunk-PBAYOJJO.js.map
+//# sourceMappingURL=chunk-PBAYOJJO.js.map