@demlik/tea 0.21.0 → 0.22.0

package/dist/{chunk-YDF6P74H.js.map → chunk-IAHEYPYJ.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/persistence/snapshot/index.ts"],"names":[],"mappings":"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","file":"chunk-YDF6P74H.js","sourcesContent":["/**\n * internal/persistence/snapshot — periodic state checkpoint to a host store\n * (R2/KV-shaped). Internal since #49 — not published on any subpath.\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: `createSnapshot(config)` hands back plain functions and two\n * `Cmd.define`d Cmds (`write`, `load`) you call from your own `update` (ADR\n * 0022). The state it owns is a Model slice (durable + replayable, the two\n * non-negotiables); the verbs are PURE decisions; the I/O (the actual `put` /\n * `get` against your store) lives only in the two handlers you write (ADR 0021).\n *\n * It is a LEAF module: it imports only the core substrate (`../index`, for\n * `Cmd`) 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 is the handler's business, never this module's — so it never\n * imports `@cloudflare/workers-types` and can be checkpointed to anything (R2,\n * KV, a DO sub-key, an in-memory map in tests).\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 *   cmds: [snap.write, snap.load],\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_write_ok: (s, msg) => {\n *     const [snapshot, cmds] = snap.confirm(s.snapshot, msg);\n *     return [{ ...s, snapshot }, cmds];\n *   },\n *   snapshot_write_err: (s) => [s, []],                     // errors are data — decide here\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_load_ok: (s, msg) => {\n *     if (msg.value === null) return [s, []];               // no checkpoint → keep fresh init\n *     const [snapshot, cmds] = snap.boot(s.snapshot);\n *     return [{ ...s, run: msg.value, snapshot }, cmds];\n *   },\n *   snapshot_load_err: (s) => [s, []],                      // errors are data — decide here\n *\n *   // and where the machine runs, the two handlers you write:\n *   run(machine, {\n *     interpret: {\n *       snapshot_write: async (cmd, { ok, err }) => {\n *         try { await r2.put(cmd.key, cmd.payload); return ok(undefined); }\n *         catch (cause) { return err({ _tag: \"snapshot_write_failed\", cause }); }\n *       },\n *       snapshot_load: async (cmd, { ok, err }) => {\n *         try { return ok(await r2.get(cmd.key)); }\n *         catch (cause) { return err({ _tag: \"snapshot_load_failed\", cause }); }\n *       },\n *     },\n *   });\n */\n\nimport {\n  Cmd,\n  type CmdOf,\n  type SettledErr,\n  type SettledOk,\n  type TaggedError,\n} from \"../../../index\";\nimport { unchecked, undefinedOnly } from \"../../schema\";\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// Cmds + Msgs — the write effect, the read effect, and their settled Msgs.\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.\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 *\n * `Cmd.define`d (ADR 0014, 0021), minted per `V` by a factory the way\n * `workflowActivityDef<A>()` is, since the payload type is the knob's own\n * parameter. The handler you write puts the payload in your store and returns\n * `ok(undefined)`, or `err({ _tag: \"snapshot_write_failed\", … })`; the engine\n * mints `snapshot_write_ok` / `snapshot_write_err`.\n */\nexport function snapshotWriteDef<V>() {\n  return Cmd.define(\"snapshot_write\", {\n    input: unchecked<{\n      readonly key: string;\n      readonly seq: number;\n      readonly at: number;\n      readonly payload: V;\n    }>(),\n    ok: undefinedOnly,\n    err: [\"snapshot_write_failed\"],\n  });\n}\n/**\n * The Cmd a snapshot decision emits to write a checkpoint: `payload` under\n * `key`, at sequence `seq`.\n */\nexport type SnapshotWriteCmd<V> = CmdOf<ReturnType<typeof snapshotWriteDef<V>>>;\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 you write reads the store and returns `ok(payload)` — `null` when\n * the store has no checkpoint under `key` — or\n * `err({ _tag: \"snapshot_load_failed\", … })`.\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 function snapshotLoadDef<V>() {\n  return Cmd.define(\"snapshot_load\", {\n    input: unchecked<{ readonly key: string }>(),\n    ok: unchecked<V | null>(),\n    err: [\"snapshot_load_failed\"],\n  });\n}\n/** The Cmd `requestLoad` emits to read the checkpoint saved under `key`. */\nexport type SnapshotLoadCmd<V = unknown> = CmdOf<\n  ReturnType<typeof snapshotLoadDef<V>>\n>;\n\n/**\n * The Msg the engine mints when a write lands. Fold it through\n * `confirm(state, msg)` to advance `lastSavedSeq` / `lastSavedAt`. It carries\n * the write Cmd, so `msg.cmd.seq` matches the emitting decision and a late\n * acknowledgement of an older write can never regress a newer confirmed one.\n */\nexport type SnapshotSavedMsg<V = unknown> = SettledOk<\n  \"snapshot_write\",\n  SnapshotWriteCmd<V>,\n  undefined\n>;\n\n/**\n * The Msg the engine mints when a write fails. Errors are data (never\n * swallowed): the consumer's reducer decides whether a failed checkpoint is\n * fatal, retryable (compose `@demlik/tea/retry-backoff`), or merely logged.\n * `msg.cmd.seq` identifies which checkpoint failed.\n */\nexport type SnapshotFailedMsg<V = unknown> = SettledErr<\n  \"snapshot_write\",\n  SnapshotWriteCmd<V>,\n  TaggedError<\"snapshot_write_failed\">\n>;\n\n/**\n * The Msg the engine mints when a read resolves. `value` is the recovered\n * checkpoint, or `null` when the store has no checkpoint under `key` (fresh\n * boot — never checkpointed, or a wiped store). `null` is NOT an error — \"no\n * checkpoint yet\" is a normal first-run state, distinct from \"the read failed\"\n * (`snapshot_load_err`).\n */\nexport type SnapshotLoadedMsg<V> = SettledOk<\n  \"snapshot_load\",\n  SnapshotLoadCmd<V>,\n  V | null\n>;\n\n/**\n * The Msg the engine mints when a read fails. Errors are data: a failed\n * recovery read is a visible signal the consumer's reducer decides on\n * (fatal-abort, retry, or boot-fresh-and-log). Kept apart from a `null` load\n * so \"the store has no checkpoint\" can never masquerade as \"the read failed\".\n */\nexport type SnapshotLoadFailedMsg<V = unknown> = SettledErr<\n  \"snapshot_load\",\n  SnapshotLoadCmd<V>,\n  TaggedError<\"snapshot_load_failed\">\n>;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// The combinator.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The bundle `createSnapshot` returns: plain functions plus the two Cmd defs to\n * list in `cmds`. There are no subs: a checkpoint is driven by progress (a\n * `record` call from the consumer's reducer), not by a timer.\n */\nexport interface SnapshotKnob<V> {\n  /** The `snapshot_write` Cmd def — list it in the machine's `cmds`. */\n  readonly write: ReturnType<typeof snapshotWriteDef<V>>;\n  /** The `snapshot_load` Cmd def — list it in the machine's `cmds`. */\n  readonly load: ReturnType<typeof snapshotLoadDef<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 SnapshotWriteCmd<V>[]];\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 SnapshotWriteCmd<V>[]];\n  /**\n   * Record a confirmed durable write. PURE. Advances `lastSavedSeq` /\n   * `lastSavedAt` to the acknowledged write's `seq` / `at`, but only forward:\n   * an out-of-order acknowledgement of an OLDER `seq` (a slow write landing\n   * after a newer one) is ignored, so the confirmed watermark is monotonic.\n   * Fold the `snapshot_write_ok` 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_write_ok` cell.\n   */\n  confirm(\n    state: SnapshotState,\n    msg: SnapshotSavedMsg<V>,\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, so the cadence counter starts\n   * fresh from there. `seq` / `lastSavedSeq` / `lastSavedAt` are preserved\n   * (they describe what is durable, which a reload does not change). Call from\n   * a `boot` Msg the host dispatches once after `run(...)`, never from `init`'s\n   * rehydrate branch (invariant 2).\n   *\n   * Returns the reducer-cell shape `readonly [SnapshotState, readonly Cmd[]]`\n   * (with `Cmd.none` — a resume emits nothing) so it drops straight into a\n   * `snapshot_load_ok` cell.\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_load_ok` 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(...)` and folds `requestLoad` there.\n   */\n  requestLoad(\n    state: SnapshotState,\n  ): readonly [SnapshotState, readonly SnapshotLoadCmd<V>[]];\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 `write` / `load` are the Cmd defs whose handlers you write.\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  const snapshotWrite = snapshotWriteDef<V>();\n  const snapshotLoad = snapshotLoadDef<V>();\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 SnapshotWriteCmd<V>[]] {\n    const seq = state.seq + 1;\n    const next: SnapshotState = { ...state, sinceLast: 0, seq };\n    return [next, [snapshotWrite({ key, seq, at, payload })]];\n  }\n\n  return {\n    write: snapshotWrite,\n    load: snapshotLoad,\n\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 }, []];\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      const { seq, at } = msg.cmd;\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 && seq <= state.lastSavedSeq) {\n        return [state, Cmd.none];\n      }\n      return [{ ...state, lastSavedSeq: seq, lastSavedAt: at }, Cmd.none];\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_load_ok` (the consumer's reducer), not here.\n      return [state, [snapshotLoad({ key })]];\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../src/internal/persistence/snapshot/index.ts"],"names":[],"mappings":"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","file":"chunk-IAHEYPYJ.js","sourcesContent":["/**\n * internal/persistence/snapshot — periodic state checkpoint to a host store\n * (R2/KV-shaped). Internal since #49 — not published on any subpath.\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: `createSnapshot(config)` hands back plain functions and two\n * `Cmd.define`d Cmds (`write`, `load`) you call from your own `update` (ADR\n * 0022). The state it owns is a Model slice (durable + replayable, the two\n * non-negotiables); the verbs are PURE decisions; the I/O (the actual `put` /\n * `get` against your store) lives only in the two handlers you write (ADR 0021).\n *\n * It is a LEAF module: it imports only the core substrate (`../index`, for\n * `Cmd`) 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 is the handler's business, never this module's — so it never\n * imports `@cloudflare/workers-types` and can be checkpointed to anything (R2,\n * KV, a DO sub-key, an in-memory map in tests).\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 *   cmds: [snap.write, snap.load],\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_write_ok: (s, msg) => {\n *     const [snapshot, cmds] = snap.confirm(s.snapshot, msg);\n *     return [{ ...s, snapshot }, cmds];\n *   },\n *   snapshot_write_err: (s) => [s, []],                     // errors are data — decide here\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_load_ok: (s, msg) => {\n *     if (msg.value === null) return [s, []];               // no checkpoint → keep fresh init\n *     const [snapshot, cmds] = snap.boot(s.snapshot);\n *     return [{ ...s, run: msg.value, snapshot }, cmds];\n *   },\n *   snapshot_load_err: (s) => [s, []],                      // errors are data — decide here\n *\n *   // and where the machine runs, the two handlers you write:\n *   run(machine, {\n *     interpret: {\n *       snapshot_write: async (cmd, { ok, err }) => {\n *         try { await r2.put(cmd.key, cmd.payload); return ok(undefined); }\n *         catch (cause) { return err({ _tag: \"snapshot_write_failed\", cause }); }\n *       },\n *       snapshot_load: async (cmd, { ok, err }) => {\n *         try { return ok(await r2.get(cmd.key)); }\n *         catch (cause) { return err({ _tag: \"snapshot_load_failed\", cause }); }\n *       },\n *     },\n *   });\n */\n\nimport {\n  Cmd,\n  type CmdOf,\n  type SettledErr,\n  type SettledOk,\n  type TaggedError,\n} from \"../../../index\";\nimport { unchecked, undefinedOnly } from \"../../schema\";\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// Cmds + Msgs — the write effect, the read effect, and their settled Msgs.\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.\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 *\n * `Cmd.define`d (ADR 0014, 0021), minted per `V` by a factory the way\n * `workflowActivityDef<A>()` is, since the payload type is the knob's own\n * parameter. The handler you write puts the payload in your store and returns\n * `ok(undefined)`, or `err({ _tag: \"snapshot_write_failed\", … })`; the engine\n * mints `snapshot_write_ok` / `snapshot_write_err`.\n */\nexport function snapshotWriteDef<V>() {\n  return Cmd.define(\"snapshot_write\", {\n    input: unchecked<{\n      readonly key: string;\n      readonly seq: number;\n      readonly at: number;\n      readonly payload: V;\n    }>(),\n    ok: undefinedOnly,\n    err: [\"snapshot_write_failed\"],\n  });\n}\n/**\n * The Cmd a snapshot decision emits to write a checkpoint: `payload` under\n * `key`, at sequence `seq`.\n */\nexport type SnapshotWriteCmd<V> = CmdOf<ReturnType<typeof snapshotWriteDef<V>>>;\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 you write reads the store and returns `ok(payload)` — `null` when\n * the store has no checkpoint under `key` — or\n * `err({ _tag: \"snapshot_load_failed\", … })`.\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. A pure restored `init` may return\n * resume State and Cmds, including a load Cmd from `requestLoad`. A host `boot`\n * Msg after `run(...)` is an optional protocol; Subs are already open then.\n * Fold the recovered payload into the run slice, then continue.\n */\nexport function snapshotLoadDef<V>() {\n  return Cmd.define(\"snapshot_load\", {\n    input: unchecked<{ readonly key: string }>(),\n    ok: unchecked<V | null>(),\n    err: [\"snapshot_load_failed\"],\n  });\n}\n/** The Cmd `requestLoad` emits to read the checkpoint saved under `key`. */\nexport type SnapshotLoadCmd<V = unknown> = CmdOf<\n  ReturnType<typeof snapshotLoadDef<V>>\n>;\n\n/**\n * The Msg the engine mints when a write lands. Fold it through\n * `confirm(state, msg)` to advance `lastSavedSeq` / `lastSavedAt`. It carries\n * the write Cmd, so `msg.cmd.seq` matches the emitting decision and a late\n * acknowledgement of an older write can never regress a newer confirmed one.\n */\nexport type SnapshotSavedMsg<V = unknown> = SettledOk<\n  \"snapshot_write\",\n  SnapshotWriteCmd<V>,\n  undefined\n>;\n\n/**\n * The Msg the engine mints when a write fails. Errors are data (never\n * swallowed): the consumer's reducer decides whether a failed checkpoint is\n * fatal, retryable (compose `@demlik/tea/retry-backoff`), or merely logged.\n * `msg.cmd.seq` identifies which checkpoint failed.\n */\nexport type SnapshotFailedMsg<V = unknown> = SettledErr<\n  \"snapshot_write\",\n  SnapshotWriteCmd<V>,\n  TaggedError<\"snapshot_write_failed\">\n>;\n\n/**\n * The Msg the engine mints when a read resolves. `value` is the recovered\n * checkpoint, or `null` when the store has no checkpoint under `key` (fresh\n * boot — never checkpointed, or a wiped store). `null` is NOT an error — \"no\n * checkpoint yet\" is a normal first-run state, distinct from \"the read failed\"\n * (`snapshot_load_err`).\n */\nexport type SnapshotLoadedMsg<V> = SettledOk<\n  \"snapshot_load\",\n  SnapshotLoadCmd<V>,\n  V | null\n>;\n\n/**\n * The Msg the engine mints when a read fails. Errors are data: a failed\n * recovery read is a visible signal the consumer's reducer decides on\n * (fatal-abort, retry, or boot-fresh-and-log). Kept apart from a `null` load\n * so \"the store has no checkpoint\" can never masquerade as \"the read failed\".\n */\nexport type SnapshotLoadFailedMsg<V = unknown> = SettledErr<\n  \"snapshot_load\",\n  SnapshotLoadCmd<V>,\n  TaggedError<\"snapshot_load_failed\">\n>;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// The combinator.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The bundle `createSnapshot` returns: plain functions plus the two Cmd defs to\n * list in `cmds`. There are no subs: a checkpoint is driven by progress (a\n * `record` call from the consumer's reducer), not by a timer.\n */\nexport interface SnapshotKnob<V> {\n  /** The `snapshot_write` Cmd def — list it in the machine's `cmds`. */\n  readonly write: ReturnType<typeof snapshotWriteDef<V>>;\n  /** The `snapshot_load` Cmd def — list it in the machine's `cmds`. */\n  readonly load: ReturnType<typeof snapshotLoadDef<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 SnapshotWriteCmd<V>[]];\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 SnapshotWriteCmd<V>[]];\n  /**\n   * Record a confirmed durable write. PURE. Advances `lastSavedSeq` /\n   * `lastSavedAt` to the acknowledged write's `seq` / `at`, but only forward:\n   * an out-of-order acknowledgement of an OLDER `seq` (a slow write landing\n   * after a newer one) is ignored, so the confirmed watermark is monotonic.\n   * Fold the `snapshot_write_ok` 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_write_ok` cell.\n   */\n  confirm(\n    state: SnapshotState,\n    msg: SnapshotSavedMsg<V>,\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, so the cadence counter starts\n   * fresh from there. `seq` / `lastSavedSeq` / `lastSavedAt` are preserved\n   * (they describe what is durable, which a reload does not change). A pure\n   * restored `init` may use this to return resume State and Cmds. A host `boot`\n   * Msg after `run(...)` is an optional protocol; Subs are already open then.\n   *\n   * Returns the reducer-cell shape `readonly [SnapshotState, readonly Cmd[]]`\n   * (with `Cmd.none` — a resume emits nothing) so it drops straight into a\n   * `snapshot_load_ok` cell.\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_load_ok` fold, via `boot`, touches the slice). This is the\n   * entry point of the recovery loop: call from pure restored `init` to return\n   * resume State and the load Cmd, or from an optional host `boot` Msg after\n   * `run(...)`, when Subs are already open.\n   */\n  requestLoad(\n    state: SnapshotState,\n  ): readonly [SnapshotState, readonly SnapshotLoadCmd<V>[]];\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 `write` / `load` are the Cmd defs whose handlers you write.\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  const snapshotWrite = snapshotWriteDef<V>();\n  const snapshotLoad = snapshotLoadDef<V>();\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 SnapshotWriteCmd<V>[]] {\n    const seq = state.seq + 1;\n    const next: SnapshotState = { ...state, sinceLast: 0, seq };\n    return [next, [snapshotWrite({ key, seq, at, payload })]];\n  }\n\n  return {\n    write: snapshotWrite,\n    load: snapshotLoad,\n\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 }, []];\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      const { seq, at } = msg.cmd;\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 && seq <= state.lastSavedSeq) {\n        return [state, Cmd.none];\n      }\n      return [{ ...state, lastSavedSeq: seq, lastSavedAt: at }, Cmd.none];\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_load_ok` (the consumer's reducer), not here.\n      return [state, [snapshotLoad({ key })]];\n    },\n  };\n}\n"]}

package/dist/{chunk-YCJPLPQQ.js → chunk-J5JNLXO7.js}

@@ -1,7 +1,7 @@
 import { idempotencyMemory } from './chunk-PR6TB3BL.js';
 import { undefinedOnly, unchecked } from './chunk-4LPY67E4.js';
 import { queueAdapter } from './chunk-TXN2KFHF.js';
-import { Cmd } from './chunk-GAVLND5C.js';
+import { Cmd } from './chunk-A3QPMX5M.js';
 
 // src/internal/idempotency/idempotent-intake/index.ts
 function intakeProcessDef() {
@@ -102,5 +102,5 @@ function createIntake(config) {
 }
 
 export { createIntake, intakeProcessDef, intakeReplayDef };
-//# sourceMappingURL=chunk-YCJPLPQQ.js.map
-//# sourceMappingURL=chunk-YCJPLPQQ.js.map
+//# sourceMappingURL=chunk-J5JNLXO7.js.map
+//# sourceMappingURL=chunk-J5JNLXO7.js.map

package/dist/{chunk-YCJPLPQQ.js.map → chunk-J5JNLXO7.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/idempotency/idempotent-intake/index.ts"],"names":[],"mappings":"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","file":"chunk-YCJPLPQQ.js","sourcesContent":["/**\n * internal/idempotency/idempotent-intake — receive-once intake for webhooks / queue\n * messages: dedupe by key, enqueue the new ones, replay the cached result to\n * the duplicates. The \"process this payload exactly once even though it\n * arrives N times\" knob.\n *\n * **The recipe.** This is a Level-2 composition — it owns no primitive\n * queue/cache logic of its own, it *splices two L1 bricks into one Model slice*\n * and DELEGATES every transition to their VERB SEAMS — `IdempotencyMemory`\n * (`../idempotency/adapter`) and `QueueAdapter` (`../work-queue/adapter`) —\n * so the store ops and the `QueueItem` / `IdempotencyStore` shapes stay\n * insulated behind verbs the intake calls:\n *\n *   - `../idempotency/adapter` — the dedupe-by-key + last-result cache. The\n *     `seen` half of the slice is its `IdempotencyStore`, keyed by\n *     `keyOf(payload)`. A key is recorded once `receive` calls `memory.remember`;\n *     `complete` calls `memory.remember` again to swap its cached value from\n *     `pending` to the finished `result`. The cache write is the brick's, never\n *     re-rolled here.\n *   - `../work-queue/adapter` — the pending-work list. The `queue` half of the\n *     slice is its `QueueItem<P>[]`. Every status flip routes through the\n *     adapter verbs: `receive` enqueues via `queue.enqueue`, `claimNext` stamps\n *     the `running` claim via `queue.patch`, `boot` re-arms a dead worker's\n *     claim via `queue.patch`. Intake owns only the SELECTION (which item,\n *     gated on the done-cache reconcile below) — the array transition is the\n *     brick's. The consumer drains it (claim → process → `complete`) at its own\n *     pace.\n *\n * Both bricks are pure-state + pure-ops, host- and clock-agnostic by\n * construction, so the combined slice inherits TEA's two non-negotiables:\n *\n *   - **Durable** — the slice is a plain serializable value (a record-backed\n *     idempotency store + an array of queue items, no `Map`, no closures), so\n *     it survives a Durable-Object eviction / reload and rehydrates whole.\n *   - **Replayable** — every verb is a pure `(state, …) => [state, Cmd[]]`\n *     transition; no `Date.now()`, no `Math.random()`, no I/O inside a verb.\n *     `at` (the clock) and `id` (the queue-item id) are *injected* at the call\n *     site, so `trace-replay` reconstructs each transition exactly.\n *\n * **The decision lives in a Cmd, not in a return shape.** `receive` cannot\n * \"return\" what it decided (the knob contract pins the shape to\n * `[State, Cmd[]]`), so the decision is *reified as a Cmd* the runtime\n * performs:\n *\n *   - first sighting of a key  → mark it `pending`, enqueue the payload, emit\n *     `IntakeProcess` (go run the work).\n *   - a key already `pending`  → drop silently (the original is in flight);\n *     emit nothing.\n *   - a key already `done`     → emit `IntakeReplay` carrying the cached\n *     result so the duplicate caller gets the SAME response the first one\n *     produced, with zero re-execution of the side effect.\n *\n * **Two crash-safety guarantees the verbs enforce (and the unit specs alone\n * missed — see the wired-machine test):**\n *\n *   - *A slow worker is never double-enqueued.* The TTL clock starts at\n *     `complete`, not at `receive`: a `pending` entry NEVER ages out, so a\n *     duplicate of an in-flight key is always dropped no matter how long the\n *     worker takes. Only a `done` entry expires (see `liveEntry`).\n *   - *A complete-then-crash never re-runs.* `boot` and `claimNext` reconcile\n *     the queue against the done cache: a queue item whose key already resolved\n *     to `done` in `seen` is skipped (never reset to pending, never claimed),\n *     so a worker that finished and cached its result before the DO evicted is\n *     not re-executed on resume.\n *\n * Typical wiring (the combinator form — splice ~3 hooks into a host machine):\n *\n *   const intake = createIntake<StripeEvent, ChargeResult>({\n *     keyOf: (e) => e.id,          // Stripe's idempotency key\n *     ttlMs: 24 * 60 * 60 * 1000,  // a replayed webhook 24h after it COMPLETED is re-run\n *   });\n *\n *   // in `init`:\n *   intake: intake.init(),\n *   // in `update`, on the inbound-webhook Msg:\n *   const [next, cmds] = intake.receive(state.intake, payload, at, id);\n *   // …route `IntakeProcess` to your worker, `IntakeReplay` to the responder.\n *   // on the worker's done Msg:\n *   const [next, _] = intake.complete(state.intake, key, result, at);\n *   // once, after boot (DO reload), before resuming the drain:\n *   const [next, _] = intake.boot(state.intake);\n *\n * Escape hatch: reach the raw L1 ops via `../idempotency` and `../../work-queue`\n * and thread them by hand.\n */\n\nimport { Cmd, type CmdOf } from \"../../../index\";\nimport { unchecked, undefinedOnly } from \"../../schema\";\nimport type { QueueItem } from \"../../work-queue\";\nimport { queueAdapter } from \"../../work-queue/adapter\";\nimport type { IdempotencyStore } from \"../idempotency\";\nimport { idempotencyMemory } from \"../idempotency/adapter\";\n\n/**\n * A cached intake entry: either a key whose work is still in flight\n * (`pending`) or one whose work has finished and whose `result` is held for\n * replay to later duplicates (`done`). Discriminated on `phase` — `pending`\n * carries no payload, `done` carries the result `R`.\n *\n * Lives inside the `seen` half of the slice (`IdempotencyStore<IntakeEntry<R>>`).\n * It is the dedupe ledger's *value*; the ledger's *key* is `keyOf(payload)`.\n */\nexport type IntakeEntry<R> =\n  | { readonly phase: \"pending\" }\n  | { readonly phase: \"done\"; readonly result: R };\n\n/**\n * The intake knob's config — `keyOf` derives the idempotency key from a\n * payload, `ttlMs` (optional) ages a *completed* cached key out so a webhook\n * replayed long after the work finished is treated as new and re-processed.\n *\n * **The TTL clock starts at `complete`, not at `receive`.** A `pending` entry\n * (work still in flight) NEVER ages out, no matter how slow the worker is —\n * ageing a pending key would let the duplicate re-enqueue the in-flight\n * payload and double-process it. Only a `done` entry expires, measured from\n * the `at` passed to `complete` (the moment the result was cached). Inside the\n * window a duplicate replays the cached result; at/after the window it is\n * re-accepted and re-processed.\n *\n * Omit `ttlMs` for a cache whose `done` entries never expire by age (keys live\n * forever — fine for a bounded universe of ids, unbounded growth otherwise).\n *\n * The TTL is owned HERE, not delegated to the composed `IdempotencyStore`: the\n * store's uniform per-entry TTL cannot tell `pending` from `done`, so intake\n * keeps the store TTL-free and applies the phase-aware rule itself (see\n * `liveEntry`).\n */\nexport interface IntakeConfig<P> {\n  /** Derive the idempotency key from a payload. Must be pure + deterministic. */\n  readonly keyOf: (payload: P) => string;\n  /**\n   * Age a *completed* key out after this many ms, measured from the `at`\n   * passed to `complete`. Pending keys never age out.\n   */\n  readonly ttlMs?: number;\n}\n\n/**\n * The Model slice this knob owns. `seen` is the dedupe + last-result cache\n * (the `../idempotency` brick); `queue` is the pending-work list (the\n * `../work-queue` brick). Both are plain serializable values — the whole slice\n * round-trips through `JSON` so it survives eviction and replays exactly.\n */\nexport interface IntakeState<P, R> {\n  readonly seen: IdempotencyStore<IntakeEntry<R>>;\n  readonly queue: readonly QueueItem<P>[];\n}\n\n// === Cmds the verbs reify ===\n//\n// The knob contract pins verbs to `(state, …) => [State, Cmd[]]`, so a verb's\n// *decision* (new vs. duplicate-pending vs. duplicate-done) cannot be a return\n// value — it is emitted as a Cmd the runtime's interpret handler performs.\n// Each Cmd is plain data (invariant 1): the payload / key / result it carries\n// are values, never closures.\n//\n// Both are `Cmd.define`d (ADR 0014). The payload `P` / result `R` are the\n// knob's own type parameters, so each def is minted per knob by a factory\n// (`createIntake` calls it once) rather than a module-scope constant — the\n// same shape `resilient-call`'s `runCmdDef<I, R>()` takes. The host performs\n// them and settles nothing back through intake, hence `ok: undefinedOnly` and an\n// empty `err` list.\n\n/** A genuinely-new payload was accepted and enqueued — go run the work. */\nexport function intakeProcessDef<P>() {\n  return Cmd.define(\"intake:process\", {\n    input: unchecked<{\n      /** The dedupe key the payload was filed under. */\n      readonly key: string;\n      /** The enqueued queue-item id (the same `id` passed to `receive`). */\n      readonly itemId: string;\n      /** The original payload, for the worker to process. */\n      readonly payload: P;\n    }>(),\n    ok: undefinedOnly,\n    err: [],\n  });\n}\n/**\n * The Cmd intake emits for a first-time request: process `payload` for the\n * queue item `itemId`.\n */\nexport type IntakeProcessCmd<P> = CmdOf<ReturnType<typeof intakeProcessDef<P>>>;\n\n/**\n * A duplicate of an already-completed key arrived — replay the cached result\n * to the caller instead of re-running the side effect.\n */\nexport function intakeReplayDef<R>() {\n  return Cmd.define(\"intake:replay\", {\n    input: unchecked<{\n      /** The dedupe key whose cached result is being replayed. */\n      readonly key: string;\n      /** The result the ORIGINAL request produced, recalled from the cache. */\n      readonly result: R;\n    }>(),\n    ok: undefinedOnly,\n    err: [],\n  });\n}\n/**\n * The Cmd intake emits for a duplicate of a completed request: hand back the\n * cached `result` instead of redoing the work.\n */\nexport type IntakeReplayCmd<R> = CmdOf<ReturnType<typeof intakeReplayDef<R>>>;\n\n/** The Cmd union the intake verbs emit. */\nexport type IntakeCmd<P, R> = IntakeProcessCmd<P> | IntakeReplayCmd<R>;\n\n/**\n * Build an idempotent-intake knob from `config`. Returns the uniform L2\n * contract — `init()` + the verbs (`receive`, `complete`, `boot`, `claimNext`).\n * No `subs` / `handlers`: intake owns no timers and does no I/O of its own (the\n * composed bricks are pure-ops; the worker that runs `IntakeProcess` and the\n * responder that runs `IntakeReplay` live in the host's interpret map).\n */\nexport function createIntake<P, R>(config: IntakeConfig<P>) {\n  const { keyOf, ttlMs } = config;\n\n  // The two store seams, bound once for this knob's `P`/`R`. The intake\n  // delegates every queue status flip to `queue.*` and every dedupe-cache\n  // transition to `memory.*`, so the `QueueItem<P>` / `IdempotencyStore` shapes\n  // are insulated behind the verbs rather than reached by raw ops.\n  const queue = queueAdapter<P>();\n  const memory = idempotencyMemory<IntakeEntry<R>>();\n\n  // The two Cmd constructors, minted once for this knob's `P`/`R`.\n  const intakeProcess = intakeProcessDef<P>();\n  const intakeReplay = intakeReplayDef<R>();\n\n  /**\n   * The empty slice: a TTL-free idempotency store (intake owns the TTL itself —\n   * see `liveEntry`, because the store cannot tell `pending` from `done`) plus\n   * an empty work queue. The rehydrate path is the host's `init(loaded)` — it\n   * passes the persisted slice straight back, this is only the fresh-boot value.\n   */\n  function init(): IntakeState<P, R> {\n    return {\n      seen: memory.init(),\n      queue: [],\n    };\n  }\n\n  /**\n   * The live cached entry for `key` at clock reading `at`, or `undefined` if\n   * the key is absent or its `done` window has elapsed. This is intake's\n   * phase-aware expiry rule, applied HERE rather than by the store's uniform\n   * per-entry TTL:\n   *\n   *   - **`pending`** — work is in flight; NEVER expires. Ageing a pending key\n   *     would let a slow worker's payload be re-enqueued and double-processed.\n   *   - **`done`** — expires `ttlMs` after the `atMs` the result was cached at\n   *     (the `at` passed to `complete`). Half-open, matching the store /\n   *     rate-limit window edge: `at - atMs >= ttlMs` reads as expired. No\n   *     `ttlMs` ⇒ a `done` entry never expires by age.\n   *\n   * PURE — reads `state.seen.entries` directly (no `Date.now`), never mutates.\n   */\n  function liveEntry(\n    store: IdempotencyStore<IntakeEntry<R>>,\n    key: string,\n    at: number,\n  ): IntakeEntry<R> | undefined {\n    const cached = store.entries[key];\n    if (cached === undefined) return undefined;\n    const entry = cached.value;\n    if (entry.phase === \"pending\") return entry; // in flight — never ages out\n    if (ttlMs !== undefined && at - cached.atMs >= ttlMs) return undefined;\n    return entry;\n  }\n\n  /**\n   * Whether the queue item `it`'s key has already resolved to a live `done`\n   * entry in `seen` (the work completed and its result is cached). Such an\n   * item must NOT be re-armed by `boot` or claimed by `claimNext` — doing so\n   * re-runs work whose result is already known (the complete-then-crash bug).\n   *\n   * `at = +Infinity` is the right reading for the reconcile check: a `done`\n   * entry counts as done for reconciliation regardless of how far past its\n   * replay TTL it is. (TTL governs whether a *duplicate receive* re-processes,\n   * not whether a *queued, already-completed* item should re-run — that one\n   * never should.)\n   */\n  function isAlreadyDone(state: IntakeState<P, R>, it: QueueItem<P>): boolean {\n    return state.seen.entries[keyOf(it.input)]?.value.phase === \"done\";\n  }\n\n  /**\n   * Receive a payload at clock reading `at`, filing it under the queue-item\n   * id `id`. PURE — returns a NEW slice; the input is untouched.\n   *\n   * Three outcomes, each reified as a Cmd (see the Cmd union above):\n   *\n   *   1. **New key** (`liveEntry` is absent at `at`) — `remember` the key as\n   *      `pending`, `enqueue` the payload onto the work queue, and emit\n   *      `intake:process`. The only path that grows either half of the slice.\n   *   2. **Duplicate, still pending** — the original is in flight. Drop\n   *      silently: the slice is returned unchanged and no Cmd is emitted, so\n   *      the duplicate neither re-enqueues nor double-processes. A pending\n   *      entry never ages out, so this holds no matter how slow the worker is.\n   *   3. **Duplicate, already done (within TTL)** — emit `intake:replay`\n   *      carrying the cached `result` so the caller gets the original response.\n   *      The slice is unchanged (a replay touches neither cache nor queue). A\n   *      `done` key past its `ttlMs` window reads as absent and falls to (1).\n   *\n   * `id` is injected (work-queue's `genId` reads `Date.now()` / `crypto`, so\n   * it cannot be called inside a pure verb). Generate it at the effect\n   * boundary and thread it in; it becomes the enqueued item's id AND the\n   * `itemId` on the emitted `intake:process` Cmd, so the worker can address the\n   * exact queue item it must `complete`.\n   */\n  function receive(\n    state: IntakeState<P, R>,\n    payload: P,\n    at: number,\n    id: string,\n  ): readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]] {\n    const key = keyOf(payload);\n\n    // Duplicate path — the key has a live entry at `at` (pending never ages;\n    // done ages only past `ttlMs` measured from `complete`).\n    const entry = liveEntry(state.seen, key, at);\n    if (entry !== undefined) {\n      if (entry.phase === \"done\") {\n        // Replay the original result; touch nothing.\n        return [state, [intakeReplay({ key, result: entry.result })]];\n      }\n      // phase === \"pending\": original is in flight — drop silently.\n      return [state, []];\n    }\n\n    // New path — record the key as pending, enqueue the payload, process it.\n    const seenNext = memory.remember(state.seen, key, { phase: \"pending\" }, at);\n    const { next: queueNext, item } = queue.enqueue(\n      state.queue,\n      payload,\n      at,\n      id,\n    );\n    const nextState: IntakeState<P, R> = { seen: seenNext, queue: queueNext };\n    return [nextState, [intakeProcess({ key, itemId: item.id, payload })]];\n  }\n\n  /**\n   * Record the finished `result` for `key` at clock reading `at`. PURE —\n   * returns a NEW slice; the input is untouched. Emits no Cmds (completion is\n   * a pure cache write; the host marks the queue item done via the work-queue\n   * adapter at the effect boundary).\n   *\n   * Swaps the key's cached entry from `pending` to `done` so every subsequent\n   * `receive` of the same key replays this `result`. `remember` stamps the\n   * entry's `atMs` to `at`, which is the moment intake's `done`-TTL clock\n   * starts (see `liveEntry`): a completed key stays replayable for `ttlMs`\n   * past completion, not past first receipt.\n   *\n   * `complete` does NOT remove the queue item — the queue is the host's drain\n   * ledger, and which items leave it (and when) is the host's call via the\n   * work-queue adapter. `complete` owns the cache half only.\n   */\n  function complete(\n    state: IntakeState<P, R>,\n    key: string,\n    result: R,\n    at: number,\n  ): readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]] {\n    const seenNext = memory.remember(\n      state.seen,\n      key,\n      { phase: \"done\", result },\n      at,\n    );\n    return [{ ...state, seen: seenNext }, []];\n  }\n\n  /**\n   * Resume after a boot (Durable-Object reload / process restart). PURE —\n   * returns a NEW slice; the input is untouched. Emits no Cmds.\n   *\n   * Resets every `running` queue item back to `pending` so the host's drain\n   * re-claims it — EXCEPT an item whose key already resolved to `done` in\n   * `seen`. That item's worker finished and cached its result before the crash;\n   * re-arming it would re-run completed work (the complete-then-crash bug). It\n   * is left as-is (and `claimNext` will likewise skip it), so the host drains\n   * it via `markDone` without ever re-executing the side effect.\n   *\n   * A `running` item still `pending` in the cache is one a now-dead worker\n   * claimed but never finished — that one IS reset, so it gets re-claimed.\n   *\n   * Returns the same reference when nothing changed (no running item needed\n   * re-arming) so the host can skip a redundant save.\n   *\n   * Call once from a `boot` Msg the host dispatches after `run(...)` returns —\n   * never from `init`'s rehydrate branch (that branch must be a pure\n   * passthrough; see the substrate's `init` contract).\n   */\n  function boot(\n    state: IntakeState<P, R>,\n  ): readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]] {\n    // Selection lives HERE (the done-cache reconcile is intake's own rule); the\n    // status FLIP is delegated to the `QueueAdapter`. A blanket reset would\n    // re-arm completed-then-crashed items (it cannot see the done cache), so\n    // intake picks the items and `queue.patch` performs each transition — the\n    // same spread the work-queue lifecycle uses, not a re-rolled one.\n    let items = state.queue;\n    let changed = false;\n    for (const it of state.queue) {\n      if (it.status !== \"running\") continue;\n      // Reconcile against the done cache: a completed-then-crashed item must\n      // NOT be re-armed (it would re-run already-cached work).\n      if (isAlreadyDone(state, it)) continue;\n      const flip = queue.patch(items, it.id, (item) => ({\n        ...item,\n        status: \"pending\",\n        startedAt: undefined,\n      }));\n      items = flip.next;\n      changed = changed || flip.changed;\n    }\n    if (!changed) return [state, []];\n    return [{ ...state, queue: items }, []];\n  }\n\n  /**\n   * Claim the next pending queue item, flipping it `running` and stamping\n   * `startedAt` to `at`. PURE — returns a NEW slice plus the claimed item, or\n   * `null` if nothing claimable remains.\n   *\n   * \"Claimable\" is a pending item WHOSE KEY IS NOT ALREADY `done` in `seen`.\n   * An item whose key completed before a crash (its `intake:process` ran, work\n   * finished, result cached, but the item never left the queue) is skipped —\n   * claiming it would re-run already-cached work. Such items are inert here;\n   * the host drains them via `markDone`.\n   *\n   * This is the drain side of the intake, the mirror of `receive`'s enqueue.\n   * It is a pure helper (not a verb that emits Cmds) because \"what to do with\n   * the claimed item\" is the host's decision — typically: dispatch the worker,\n   * await it, then call `complete`. Threading it through the slice keeps the\n   * claim durable: the `running` stamp survives eviction, and `boot` re-arms\n   * it if the worker died.\n   */\n  function claimNext(\n    state: IntakeState<P, R>,\n    at: number,\n  ): {\n    readonly state: IntakeState<P, R>;\n    readonly claimed: QueueItem<P>;\n  } | null {\n    // Selection lives HERE (skip an item whose key already resolved `done`);\n    // the status FLIP is delegated to the `QueueAdapter`. A blind `queue.claim`\n    // would take the first PENDING item regardless of the done cache, which\n    // would re-run already-cached work — so intake selects the eligible item and\n    // `queue.patch` performs the running-stamp transition (the work-queue\n    // lifecycle's own spread, not a re-rolled one).\n    const target = state.queue.find(\n      (it) => it.status === \"pending\" && !isAlreadyDone(state, it),\n    );\n    if (target === undefined) return null;\n    // The patch closure is the single place the claimed item is materialized;\n    // capture it here so the result needs no re-scan of the new queue.\n    let claimed: QueueItem<P> = target;\n    const { next } = queue.patch(state.queue, target.id, (item) => {\n      claimed = { ...item, status: \"running\", startedAt: at };\n      return claimed;\n    });\n    return { state: { ...state, queue: next }, claimed };\n  }\n\n  return { init, receive, complete, boot, claimNext };\n}\n"]}
+{"version":3,"sources":["../src/internal/idempotency/idempotent-intake/index.ts"],"names":[],"mappings":"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","file":"chunk-J5JNLXO7.js","sourcesContent":["/**\n * internal/idempotency/idempotent-intake — receive-once intake for webhooks / queue\n * messages: dedupe by key, enqueue the new ones, replay the cached result to\n * the duplicates. The \"process this payload exactly once even though it\n * arrives N times\" knob.\n *\n * **The recipe.** This is a Level-2 composition — it owns no primitive\n * queue/cache logic of its own, it *splices two L1 bricks into one Model slice*\n * and DELEGATES every transition to their VERB SEAMS — `IdempotencyMemory`\n * (`../idempotency/adapter`) and `QueueAdapter` (`../work-queue/adapter`) —\n * so the store ops and the `QueueItem` / `IdempotencyStore` shapes stay\n * insulated behind verbs the intake calls:\n *\n *   - `../idempotency/adapter` — the dedupe-by-key + last-result cache. The\n *     `seen` half of the slice is its `IdempotencyStore`, keyed by\n *     `keyOf(payload)`. A key is recorded once `receive` calls `memory.remember`;\n *     `complete` calls `memory.remember` again to swap its cached value from\n *     `pending` to the finished `result`. The cache write is the brick's, never\n *     re-rolled here.\n *   - `../work-queue/adapter` — the pending-work list. The `queue` half of the\n *     slice is its `QueueItem<P>[]`. Every status flip routes through the\n *     adapter verbs: `receive` enqueues via `queue.enqueue`, `claimNext` stamps\n *     the `running` claim via `queue.patch`, `boot` re-arms a dead worker's\n *     claim via `queue.patch`. Intake owns only the SELECTION (which item,\n *     gated on the done-cache reconcile below) — the array transition is the\n *     brick's. The consumer drains it (claim → process → `complete`) at its own\n *     pace.\n *\n * Both bricks are pure-state + pure-ops, host- and clock-agnostic by\n * construction, so the combined slice inherits TEA's two non-negotiables:\n *\n *   - **Durable** — the slice is a plain serializable value (a record-backed\n *     idempotency store + an array of queue items, no `Map`, no closures), so\n *     it survives a Durable-Object eviction / reload and rehydrates whole.\n *   - **Replayable** — every verb is a pure `(state, …) => [state, Cmd[]]`\n *     transition; no `Date.now()`, no `Math.random()`, no I/O inside a verb.\n *     `at` (the clock) and `id` (the queue-item id) are *injected* at the call\n *     site, so `trace-replay` reconstructs each transition exactly.\n *\n * **The decision lives in a Cmd, not in a return shape.** `receive` cannot\n * \"return\" what it decided (the knob contract pins the shape to\n * `[State, Cmd[]]`), so the decision is *reified as a Cmd* the runtime\n * performs:\n *\n *   - first sighting of a key  → mark it `pending`, enqueue the payload, emit\n *     `IntakeProcess` (go run the work).\n *   - a key already `pending`  → drop silently (the original is in flight);\n *     emit nothing.\n *   - a key already `done`     → emit `IntakeReplay` carrying the cached\n *     result so the duplicate caller gets the SAME response the first one\n *     produced, with zero re-execution of the side effect.\n *\n * **Two crash-safety guarantees the verbs enforce (and the unit specs alone\n * missed — see the wired-machine test):**\n *\n *   - *A slow worker is never double-enqueued.* The TTL clock starts at\n *     `complete`, not at `receive`: a `pending` entry NEVER ages out, so a\n *     duplicate of an in-flight key is always dropped no matter how long the\n *     worker takes. Only a `done` entry expires (see `liveEntry`).\n *   - *A complete-then-crash never re-runs.* `boot` and `claimNext` reconcile\n *     the queue against the done cache: a queue item whose key already resolved\n *     to `done` in `seen` is skipped (never reset to pending, never claimed),\n *     so a worker that finished and cached its result before the DO evicted is\n *     not re-executed on resume.\n *\n * Typical wiring (the combinator form — splice ~3 hooks into a host machine):\n *\n *   const intake = createIntake<StripeEvent, ChargeResult>({\n *     keyOf: (e) => e.id,          // Stripe's idempotency key\n *     ttlMs: 24 * 60 * 60 * 1000,  // a replayed webhook 24h after it COMPLETED is re-run\n *   });\n *\n *   // in `init`:\n *   intake: intake.init(),\n *   // in `update`, on the inbound-webhook Msg:\n *   const [next, cmds] = intake.receive(state.intake, payload, at, id);\n *   // …route `IntakeProcess` to your worker, `IntakeReplay` to the responder.\n *   // on the worker's done Msg:\n *   const [next, _] = intake.complete(state.intake, key, result, at);\n *   // once, after boot (DO reload), before resuming the drain:\n *   const [next, _] = intake.boot(state.intake);\n *\n * Escape hatch: reach the raw L1 ops via `../idempotency` and `../../work-queue`\n * and thread them by hand.\n */\n\nimport { Cmd, type CmdOf } from \"../../../index\";\nimport { unchecked, undefinedOnly } from \"../../schema\";\nimport type { QueueItem } from \"../../work-queue\";\nimport { queueAdapter } from \"../../work-queue/adapter\";\nimport type { IdempotencyStore } from \"../idempotency\";\nimport { idempotencyMemory } from \"../idempotency/adapter\";\n\n/**\n * A cached intake entry: either a key whose work is still in flight\n * (`pending`) or one whose work has finished and whose `result` is held for\n * replay to later duplicates (`done`). Discriminated on `phase` — `pending`\n * carries no payload, `done` carries the result `R`.\n *\n * Lives inside the `seen` half of the slice (`IdempotencyStore<IntakeEntry<R>>`).\n * It is the dedupe ledger's *value*; the ledger's *key* is `keyOf(payload)`.\n */\nexport type IntakeEntry<R> =\n  | { readonly phase: \"pending\" }\n  | { readonly phase: \"done\"; readonly result: R };\n\n/**\n * The intake knob's config — `keyOf` derives the idempotency key from a\n * payload, `ttlMs` (optional) ages a *completed* cached key out so a webhook\n * replayed long after the work finished is treated as new and re-processed.\n *\n * **The TTL clock starts at `complete`, not at `receive`.** A `pending` entry\n * (work still in flight) NEVER ages out, no matter how slow the worker is —\n * ageing a pending key would let the duplicate re-enqueue the in-flight\n * payload and double-process it. Only a `done` entry expires, measured from\n * the `at` passed to `complete` (the moment the result was cached). Inside the\n * window a duplicate replays the cached result; at/after the window it is\n * re-accepted and re-processed.\n *\n * Omit `ttlMs` for a cache whose `done` entries never expire by age (keys live\n * forever — fine for a bounded universe of ids, unbounded growth otherwise).\n *\n * The TTL is owned HERE, not delegated to the composed `IdempotencyStore`: the\n * store's uniform per-entry TTL cannot tell `pending` from `done`, so intake\n * keeps the store TTL-free and applies the phase-aware rule itself (see\n * `liveEntry`).\n */\nexport interface IntakeConfig<P> {\n  /** Derive the idempotency key from a payload. Must be pure + deterministic. */\n  readonly keyOf: (payload: P) => string;\n  /**\n   * Age a *completed* key out after this many ms, measured from the `at`\n   * passed to `complete`. Pending keys never age out.\n   */\n  readonly ttlMs?: number;\n}\n\n/**\n * The Model slice this knob owns. `seen` is the dedupe + last-result cache\n * (the `../idempotency` brick); `queue` is the pending-work list (the\n * `../work-queue` brick). Both are plain serializable values — the whole slice\n * round-trips through `JSON` so it survives eviction and replays exactly.\n */\nexport interface IntakeState<P, R> {\n  readonly seen: IdempotencyStore<IntakeEntry<R>>;\n  readonly queue: readonly QueueItem<P>[];\n}\n\n// === Cmds the verbs reify ===\n//\n// The knob contract pins verbs to `(state, …) => [State, Cmd[]]`, so a verb's\n// *decision* (new vs. duplicate-pending vs. duplicate-done) cannot be a return\n// value — it is emitted as a Cmd the runtime's interpret handler performs.\n// Each Cmd is plain data (invariant 1): the payload / key / result it carries\n// are values, never closures.\n//\n// Both are `Cmd.define`d (ADR 0014). The payload `P` / result `R` are the\n// knob's own type parameters, so each def is minted per knob by a factory\n// (`createIntake` calls it once) rather than a module-scope constant — the\n// same shape `resilient-call`'s `runCmdDef<I, R>()` takes. The host performs\n// them and settles nothing back through intake, hence `ok: undefinedOnly` and an\n// empty `err` list.\n\n/** A genuinely-new payload was accepted and enqueued — go run the work. */\nexport function intakeProcessDef<P>() {\n  return Cmd.define(\"intake:process\", {\n    input: unchecked<{\n      /** The dedupe key the payload was filed under. */\n      readonly key: string;\n      /** The enqueued queue-item id (the same `id` passed to `receive`). */\n      readonly itemId: string;\n      /** The original payload, for the worker to process. */\n      readonly payload: P;\n    }>(),\n    ok: undefinedOnly,\n    err: [],\n  });\n}\n/**\n * The Cmd intake emits for a first-time request: process `payload` for the\n * queue item `itemId`.\n */\nexport type IntakeProcessCmd<P> = CmdOf<ReturnType<typeof intakeProcessDef<P>>>;\n\n/**\n * A duplicate of an already-completed key arrived — replay the cached result\n * to the caller instead of re-running the side effect.\n */\nexport function intakeReplayDef<R>() {\n  return Cmd.define(\"intake:replay\", {\n    input: unchecked<{\n      /** The dedupe key whose cached result is being replayed. */\n      readonly key: string;\n      /** The result the ORIGINAL request produced, recalled from the cache. */\n      readonly result: R;\n    }>(),\n    ok: undefinedOnly,\n    err: [],\n  });\n}\n/**\n * The Cmd intake emits for a duplicate of a completed request: hand back the\n * cached `result` instead of redoing the work.\n */\nexport type IntakeReplayCmd<R> = CmdOf<ReturnType<typeof intakeReplayDef<R>>>;\n\n/** The Cmd union the intake verbs emit. */\nexport type IntakeCmd<P, R> = IntakeProcessCmd<P> | IntakeReplayCmd<R>;\n\n/**\n * Build an idempotent-intake knob from `config`. Returns the uniform L2\n * contract — `init()` + the verbs (`receive`, `complete`, `boot`, `claimNext`).\n * No `subs` / `handlers`: intake owns no timers and does no I/O of its own (the\n * composed bricks are pure-ops; the worker that runs `IntakeProcess` and the\n * responder that runs `IntakeReplay` live in the host's interpret map).\n */\nexport function createIntake<P, R>(config: IntakeConfig<P>) {\n  const { keyOf, ttlMs } = config;\n\n  // The two store seams, bound once for this knob's `P`/`R`. The intake\n  // delegates every queue status flip to `queue.*` and every dedupe-cache\n  // transition to `memory.*`, so the `QueueItem<P>` / `IdempotencyStore` shapes\n  // are insulated behind the verbs rather than reached by raw ops.\n  const queue = queueAdapter<P>();\n  const memory = idempotencyMemory<IntakeEntry<R>>();\n\n  // The two Cmd constructors, minted once for this knob's `P`/`R`.\n  const intakeProcess = intakeProcessDef<P>();\n  const intakeReplay = intakeReplayDef<R>();\n\n  /**\n   * The empty slice: a TTL-free idempotency store (intake owns the TTL itself —\n   * see `liveEntry`, because the store cannot tell `pending` from `done`) plus\n   * an empty work queue. The rehydrate path is the host's `init(loaded)` — it\n   * passes the persisted slice straight back, this is only the fresh-boot value.\n   */\n  function init(): IntakeState<P, R> {\n    return {\n      seen: memory.init(),\n      queue: [],\n    };\n  }\n\n  /**\n   * The live cached entry for `key` at clock reading `at`, or `undefined` if\n   * the key is absent or its `done` window has elapsed. This is intake's\n   * phase-aware expiry rule, applied HERE rather than by the store's uniform\n   * per-entry TTL:\n   *\n   *   - **`pending`** — work is in flight; NEVER expires. Ageing a pending key\n   *     would let a slow worker's payload be re-enqueued and double-processed.\n   *   - **`done`** — expires `ttlMs` after the `atMs` the result was cached at\n   *     (the `at` passed to `complete`). Half-open, matching the store /\n   *     rate-limit window edge: `at - atMs >= ttlMs` reads as expired. No\n   *     `ttlMs` ⇒ a `done` entry never expires by age.\n   *\n   * PURE — reads `state.seen.entries` directly (no `Date.now`), never mutates.\n   */\n  function liveEntry(\n    store: IdempotencyStore<IntakeEntry<R>>,\n    key: string,\n    at: number,\n  ): IntakeEntry<R> | undefined {\n    const cached = store.entries[key];\n    if (cached === undefined) return undefined;\n    const entry = cached.value;\n    if (entry.phase === \"pending\") return entry; // in flight — never ages out\n    if (ttlMs !== undefined && at - cached.atMs >= ttlMs) return undefined;\n    return entry;\n  }\n\n  /**\n   * Whether the queue item `it`'s key has already resolved to a live `done`\n   * entry in `seen` (the work completed and its result is cached). Such an\n   * item must NOT be re-armed by `boot` or claimed by `claimNext` — doing so\n   * re-runs work whose result is already known (the complete-then-crash bug).\n   *\n   * `at = +Infinity` is the right reading for the reconcile check: a `done`\n   * entry counts as done for reconciliation regardless of how far past its\n   * replay TTL it is. (TTL governs whether a *duplicate receive* re-processes,\n   * not whether a *queued, already-completed* item should re-run — that one\n   * never should.)\n   */\n  function isAlreadyDone(state: IntakeState<P, R>, it: QueueItem<P>): boolean {\n    return state.seen.entries[keyOf(it.input)]?.value.phase === \"done\";\n  }\n\n  /**\n   * Receive a payload at clock reading `at`, filing it under the queue-item\n   * id `id`. PURE — returns a NEW slice; the input is untouched.\n   *\n   * Three outcomes, each reified as a Cmd (see the Cmd union above):\n   *\n   *   1. **New key** (`liveEntry` is absent at `at`) — `remember` the key as\n   *      `pending`, `enqueue` the payload onto the work queue, and emit\n   *      `intake:process`. The only path that grows either half of the slice.\n   *   2. **Duplicate, still pending** — the original is in flight. Drop\n   *      silently: the slice is returned unchanged and no Cmd is emitted, so\n   *      the duplicate neither re-enqueues nor double-processes. A pending\n   *      entry never ages out, so this holds no matter how slow the worker is.\n   *   3. **Duplicate, already done (within TTL)** — emit `intake:replay`\n   *      carrying the cached `result` so the caller gets the original response.\n   *      The slice is unchanged (a replay touches neither cache nor queue). A\n   *      `done` key past its `ttlMs` window reads as absent and falls to (1).\n   *\n   * `id` is injected (work-queue's `genId` reads `Date.now()` / `crypto`, so\n   * it cannot be called inside a pure verb). Generate it at the effect\n   * boundary and thread it in; it becomes the enqueued item's id AND the\n   * `itemId` on the emitted `intake:process` Cmd, so the worker can address the\n   * exact queue item it must `complete`.\n   */\n  function receive(\n    state: IntakeState<P, R>,\n    payload: P,\n    at: number,\n    id: string,\n  ): readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]] {\n    const key = keyOf(payload);\n\n    // Duplicate path — the key has a live entry at `at` (pending never ages;\n    // done ages only past `ttlMs` measured from `complete`).\n    const entry = liveEntry(state.seen, key, at);\n    if (entry !== undefined) {\n      if (entry.phase === \"done\") {\n        // Replay the original result; touch nothing.\n        return [state, [intakeReplay({ key, result: entry.result })]];\n      }\n      // phase === \"pending\": original is in flight — drop silently.\n      return [state, []];\n    }\n\n    // New path — record the key as pending, enqueue the payload, process it.\n    const seenNext = memory.remember(state.seen, key, { phase: \"pending\" }, at);\n    const { next: queueNext, item } = queue.enqueue(\n      state.queue,\n      payload,\n      at,\n      id,\n    );\n    const nextState: IntakeState<P, R> = { seen: seenNext, queue: queueNext };\n    return [nextState, [intakeProcess({ key, itemId: item.id, payload })]];\n  }\n\n  /**\n   * Record the finished `result` for `key` at clock reading `at`. PURE —\n   * returns a NEW slice; the input is untouched. Emits no Cmds (completion is\n   * a pure cache write; the host marks the queue item done via the work-queue\n   * adapter at the effect boundary).\n   *\n   * Swaps the key's cached entry from `pending` to `done` so every subsequent\n   * `receive` of the same key replays this `result`. `remember` stamps the\n   * entry's `atMs` to `at`, which is the moment intake's `done`-TTL clock\n   * starts (see `liveEntry`): a completed key stays replayable for `ttlMs`\n   * past completion, not past first receipt.\n   *\n   * `complete` does NOT remove the queue item — the queue is the host's drain\n   * ledger, and which items leave it (and when) is the host's call via the\n   * work-queue adapter. `complete` owns the cache half only.\n   */\n  function complete(\n    state: IntakeState<P, R>,\n    key: string,\n    result: R,\n    at: number,\n  ): readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]] {\n    const seenNext = memory.remember(\n      state.seen,\n      key,\n      { phase: \"done\", result },\n      at,\n    );\n    return [{ ...state, seen: seenNext }, []];\n  }\n\n  /**\n   * Resume after a boot (Durable-Object reload / process restart). PURE —\n   * returns a NEW slice; the input is untouched. Emits no Cmds.\n   *\n   * Resets every `running` queue item back to `pending` so the host's drain\n   * re-claims it — EXCEPT an item whose key already resolved to `done` in\n   * `seen`. That item's worker finished and cached its result before the crash;\n   * re-arming it would re-run completed work (the complete-then-crash bug). It\n   * is left as-is (and `claimNext` will likewise skip it), so the host drains\n   * it via `markDone` without ever re-executing the side effect.\n   *\n   * A `running` item still `pending` in the cache is one a now-dead worker\n   * claimed but never finished — that one IS reset, so it gets re-claimed.\n   *\n   * Returns the same reference when nothing changed (no running item needed\n   * re-arming) so the host can skip a redundant save.\n   *\n   * Call once during restored init, returning its State and Cmds together,\n   * or from a deliberate host boot Msg after `ready`. Choose one resume path.\n   */\n  function boot(\n    state: IntakeState<P, R>,\n  ): readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]] {\n    // Selection lives HERE (the done-cache reconcile is intake's own rule); the\n    // status FLIP is delegated to the `QueueAdapter`. A blanket reset would\n    // re-arm completed-then-crashed items (it cannot see the done cache), so\n    // intake picks the items and `queue.patch` performs each transition — the\n    // same spread the work-queue lifecycle uses, not a re-rolled one.\n    let items = state.queue;\n    let changed = false;\n    for (const it of state.queue) {\n      if (it.status !== \"running\") continue;\n      // Reconcile against the done cache: a completed-then-crashed item must\n      // NOT be re-armed (it would re-run already-cached work).\n      if (isAlreadyDone(state, it)) continue;\n      const flip = queue.patch(items, it.id, (item) => ({\n        ...item,\n        status: \"pending\",\n        startedAt: undefined,\n      }));\n      items = flip.next;\n      changed = changed || flip.changed;\n    }\n    if (!changed) return [state, []];\n    return [{ ...state, queue: items }, []];\n  }\n\n  /**\n   * Claim the next pending queue item, flipping it `running` and stamping\n   * `startedAt` to `at`. PURE — returns a NEW slice plus the claimed item, or\n   * `null` if nothing claimable remains.\n   *\n   * \"Claimable\" is a pending item WHOSE KEY IS NOT ALREADY `done` in `seen`.\n   * An item whose key completed before a crash (its `intake:process` ran, work\n   * finished, result cached, but the item never left the queue) is skipped —\n   * claiming it would re-run already-cached work. Such items are inert here;\n   * the host drains them via `markDone`.\n   *\n   * This is the drain side of the intake, the mirror of `receive`'s enqueue.\n   * It is a pure helper (not a verb that emits Cmds) because \"what to do with\n   * the claimed item\" is the host's decision — typically: dispatch the worker,\n   * await it, then call `complete`. Threading it through the slice keeps the\n   * claim durable: the `running` stamp survives eviction, and `boot` re-arms\n   * it if the worker died.\n   */\n  function claimNext(\n    state: IntakeState<P, R>,\n    at: number,\n  ): {\n    readonly state: IntakeState<P, R>;\n    readonly claimed: QueueItem<P>;\n  } | null {\n    // Selection lives HERE (skip an item whose key already resolved `done`);\n    // the status FLIP is delegated to the `QueueAdapter`. A blind `queue.claim`\n    // would take the first PENDING item regardless of the done cache, which\n    // would re-run already-cached work — so intake selects the eligible item and\n    // `queue.patch` performs the running-stamp transition (the work-queue\n    // lifecycle's own spread, not a re-rolled one).\n    const target = state.queue.find(\n      (it) => it.status === \"pending\" && !isAlreadyDone(state, it),\n    );\n    if (target === undefined) return null;\n    // The patch closure is the single place the claimed item is materialized;\n    // capture it here so the result needs no re-scan of the new queue.\n    let claimed: QueueItem<P> = target;\n    const { next } = queue.patch(state.queue, target.id, (item) => {\n      claimed = { ...item, status: \"running\", startedAt: at };\n      return claimed;\n    });\n    return { state: { ...state, queue: next }, claimed };\n  }\n\n  return { init, receive, complete, boot, claimNext };\n}\n"]}

package/dist/{chunk-MBQR3LFW.js → chunk-NFOGYDRS.js}

@@ -1,8 +1,8 @@
-import { initCache, deadlineSub, nextTimer, get, set } from './chunk-QIE4Y6BK.js';
+import { initCache, deadlineSub, nextTimer, get, set } from './chunk-UGTC33VH.js';
 import { asRng, recordFailure, shouldRetry, nextDelayMs, initRetry } from './chunk-VBDU4JL6.js';
 import { unchecked } from './chunk-4LPY67E4.js';
-import { liftSlice } from './chunk-VHKDUBXC.js';
-import { Cmd, without } from './chunk-GAVLND5C.js';
+import { liftSlice } from './chunk-BVFS3ICC.js';
+import { Cmd, without } from './chunk-A3QPMX5M.js';
 
 // src/internal/resilience/circuit-breaker/index.ts
 var defaultCircuitPolicy = {
@@ -391,5 +391,5 @@ function liftResilience(state, result) {
 }
 
 export { DEFAULT_RESILIENT_NAME, canPass, createResilientCall, defaultCircuitPolicy, initBucket, initCircuit, initWindow, liftResilience, onFailure, onSuccess, record, refill, remaining, runCmdDef, tryConsume };
-//# sourceMappingURL=chunk-MBQR3LFW.js.map
-//# sourceMappingURL=chunk-MBQR3LFW.js.map
+//# sourceMappingURL=chunk-NFOGYDRS.js.map
+//# sourceMappingURL=chunk-NFOGYDRS.js.map