@demlik/tea 0.15.0 → 0.17.0

package/dist/chunk-VTQI2NHP.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/internal/idempotency/idempotent-intake/index.ts"],"names":[],"mappings":"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","file":"chunk-VTQI2NHP.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 { z } from \"zod\";\nimport { Cmd, type CmdOf } from \"../../../index\";\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: z.void()` 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: z.custom<{\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: z.void(),\n    err: [],\n  });\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: z.custom<{\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: z.void(),\n    err: [],\n  });\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"]}

package/dist/index-ZCMhnVKN.d.ts

@@ -1,272 +0,0 @@
-import { a as CmdOf, b as CmdDef, C as Cmd, I as Interpret } from './core-DnzqWy6u.js';
-
-/**
- * The snapshot knob.
- *
- * `every` is the cadence: a checkpoint is written once `every` units of
- * progress have accumulated since the last one (see `record`). It is the
- * `snapshotEvery` field `monitored-run` threads through to this module.
- *
- * `key` is the store key the checkpoint is written under. A single machine
- * keeps a single rolling checkpoint, so the key is fixed at config time rather
- * than passed per write — the latest checkpoint overwrites the previous one
- * (R2/KV are last-write-wins on a key). Defaults to `"@@snapshot"`, mirroring
- * `doStore`'s `@@state` default-key convention.
- */
-interface SnapshotConfig {
-    /**
-     * Write a checkpoint once this many progress units have accumulated since the
-     * last write. `every: 1` checkpoints on every `record`; a value `<= 0` is
-     * treated as `1` (every progress unit triggers a write) — a non-positive
-     * cadence has no other sensible meaning, and clamping keeps `record` from
-     * never checkpointing on a misconfigured `0`.
-     */
-    readonly every: number;
-    /** Store key the rolling checkpoint is written under. Defaults to `"@@snapshot"`. */
-    readonly key?: string;
-}
-/**
- * The snapshot bookkeeping slice. Plain data — JSON-serializable so it rides
- * inside the consumer's `Store<S>` blob and survives DO eviction / reload (the
- * "durable" non-negotiable). It carries NO payload: the thing being
- * checkpointed lives elsewhere in the machine's state; this slice only tracks
- * *when* to checkpoint and *what has been acknowledged durable*.
- *
- *   - `sinceLast` — progress units accumulated since the last checkpoint
- *     DECISION (reset to 0 the moment `record` decides to write, not when the
- *     write lands). The cadence counter.
- *   - `seq` — monotonic checkpoint sequence. Bumped each time a write is
- *     emitted, so the write Cmd and its later acknowledgement can be matched
- *     even if several are in flight. The "version" of the latest emitted
- *     checkpoint.
- *   - `lastSavedSeq` — the highest `seq` whose write the host has confirmed
- *     durable (via `confirm`). `null` until the first confirmed write. The gap
- *     `seq - lastSavedSeq` is the "writes emitted but not yet acknowledged"
- *     depth — observable for backpressure / health.
- *   - `lastSavedAt` — the `at` of the most recent confirmed write (epoch ms),
- *     `null` until the first. Carried for observability, never compared inside
- *     a verb (time is injected, never read here).
- */
-interface SnapshotState {
-    readonly sinceLast: number;
-    readonly seq: number;
-    readonly lastSavedSeq: number | null;
-    readonly lastSavedAt: number | null;
-}
-/**
- * The abstract checkpoint sink — the intersection of R2's and KV's surface,
- * narrowed to exactly the two methods a rolling checkpoint needs. Deliberately
- * NOT the substrate's `Store<S>` (`{ load, save, migrate }`): that is the
- * runtime's whole-state persistence boundary keyed at a fixed cell, whereas a
- * checkpoint store is keyed, value-typed, and host-supplied.
- *
- *   - `put(key, value)` — write the checkpoint. Last-write-wins on `key`.
- *   - `get(key)` — read the latest checkpoint back, or `null` if none. Used by
- *     a recovery path to seed `init`'s `loaded` from the durable checkpoint
- *     when the runtime's own `Store<S>` blob is gone.
- *
- * No `@cloudflare/workers-types` import — an R2 bucket, a KV namespace, a DO
- * sub-key, or an in-memory `Map` all satisfy this shape with a 3-line adapter
- * at the host.
- */
-interface SnapshotStore<V> {
-    get(key: string): Promise<V | null>;
-    put(key: string, value: V): Promise<void>;
-}
-/**
- * The ports `handlers` binds. Just the store today — named so a future port
- * (a metrics sink, a clock) can grow without breaking the `handlers(ports)`
- * call shape.
- */
-interface SnapshotPorts<V> {
-    readonly store: SnapshotStore<V>;
-}
-/**
- * The checkpoint-write Cmd a `record` / `force` decision emits. Plain data
- * (invariant 1 — Cmds are data, not closures): it carries the `payload` to
- * write, the `key` to write it under, the `seq` it represents, and the `at` it
- * was decided. The handler performs the `put` and routes the result back to a
- * `confirm` / fail Msg.
- *
- * `payload` is `V` — the consumer's serializable checkpoint value (the run
- * state, the cursor, whatever the machine wants restartable). The verb takes it
- * as an argument so the snapshot slice never has to hold a copy of the
- * machine's domain state.
- *
- * `Cmd.define`d (ADR 0014), minted per `V` by a factory the way
- * `workflowActivityDef<A>()` is, since the payload type is the knob's own
- * parameter. The handler answers through this module's OWN Msgs
- * (`snapshot_saved` / `snapshot_failed`), never the minted `_ok` / `_err`,
- * hence `ok: z.void()` and an empty `err` list.
- */
-declare function snapshotWriteDef<V>(): CmdDef<"snapshot_write", {
-    readonly key: string;
-    readonly seq: number;
-    readonly at: number;
-    readonly payload: V;
-}, void, never, unknown>;
-type SnapshotWriteCmd<V> = CmdOf<ReturnType<typeof snapshotWriteDef<V>>>;
-/**
- * The Msg the write handler dispatches on a SUCCESSFUL `put`. Fold it back
- * through `confirm(state, msg)` to advance `lastSavedSeq` / `lastSavedAt`. The
- * `seq` matches the emitting Cmd so a late acknowledgement of an older write
- * can never regress a newer confirmed one.
- */
-type SnapshotSavedMsg = {
-    readonly type: "snapshot_saved";
-    readonly seq: number;
-    readonly at: number;
-};
-/**
- * The Msg the write handler dispatches on a FAILED `put`. Errors are data
- * (never swallowed): the consumer's reducer decides whether a failed checkpoint
- * is fatal, retryable (compose `@demlik/tea/retry-backoff`), or merely logged.
- * `seq` identifies which checkpoint failed; `error` is carried, never
- * interpreted here.
- */
-type SnapshotFailedMsg = {
-    readonly type: "snapshot_failed";
-    readonly seq: number;
-    readonly error: unknown;
-};
-/**
- * The checkpoint-READ Cmd a `requestLoad` decision emits — the recovery half of
- * the module. Plain data (invariant 1): it carries only the `key` to read. The
- * handler performs `store.get(key)` and routes the result back to a
- * `snapshot_loaded` (Ok, payload-or-null) / `snapshot_load_failed` (Err) Msg.
- *
- * Distinct from `snapshot_write`: a write carries a payload OUT to the store; a
- * load asks the store to hand a payload BACK. The consumer dispatches the
- * triggering Msg once on resume (a `boot` Msg, never `init`'s rehydrate branch —
- * invariant 2), folds the recovered payload into its run slice, then continues.
- */
-declare const snapshotLoad: CmdDef<"snapshot_load", {
-    key: string;
-}, void, never, unknown>;
-type SnapshotLoadCmd = CmdOf<typeof snapshotLoad>;
-/**
- * The Msg the load handler dispatches when `store.get` RESOLVES. `payload` is
- * the recovered checkpoint value, or `null` when the store has no checkpoint
- * under `key` (fresh boot — never checkpointed, or a wiped store). The consumer
- * folds this into `init`'s loaded branch: `payload === null` → keep the fresh
- * `init` state; non-null → seed the run slice from the durable checkpoint and
- * `boot` the snapshot slice's cadence counter.
- *
- * A `null` payload is NOT an error — "no checkpoint yet" is a normal first-run
- * state, distinct from "the read failed" (`snapshot_load_failed`).
- */
-type SnapshotLoadedMsg<V> = {
-    readonly type: "snapshot_loaded";
-    readonly payload: V | null;
-};
-/**
- * The Msg the load handler dispatches when `store.get` REJECTS. Errors are data
- * (never swallowed — the field-guide rule): a failed recovery read is a visible
- * signal the consumer's reducer decides on (fatal-abort, retry via
- * `@demlik/tea/retry-backoff`, or boot-fresh-and-log). `error` is carried, never
- * interpreted here. Kept separate from `snapshot_loaded`'s `null` so "the store
- * has no checkpoint" can never masquerade as "the read failed".
- */
-type SnapshotLoadFailedMsg = {
-    readonly type: "snapshot_load_failed";
-    readonly error: unknown;
-};
-/** Construct a `snapshot_saved` Msg. Shared by the handler and tests so the wire shape can't drift. */
-declare function snapshotSaved(seq: number, at: number): SnapshotSavedMsg;
-/** Construct a `snapshot_failed` Msg. Shared by the handler and tests so the wire shape can't drift. */
-declare function snapshotFailed(seq: number, error: unknown): SnapshotFailedMsg;
-/** Construct a `snapshot_loaded` Msg. Shared by the handler and tests so the wire shape can't drift. */
-declare function snapshotLoaded<V>(payload: V | null): SnapshotLoadedMsg<V>;
-/** Construct a `snapshot_load_failed` Msg. Shared by the handler and tests so the wire shape can't drift. */
-declare function snapshotLoadFailed(error: unknown): SnapshotLoadFailedMsg;
-/**
- * The bundle `createSnapshot` returns — the uniform knob contract. `subs` is
- * omitted: a checkpoint is driven by progress (a `record` call from the
- * consumer's reducer), not by a timer, so this module has no subscriptions.
- */
-interface SnapshotKnob<V> {
-    /** The initial slice — zero progress, no checkpoint emitted or confirmed yet. */
-    init(): SnapshotState;
-    /**
-     * Account one unit of progress. PURE. Increments `sinceLast`; once the
-     * accumulated count reaches the configured cadence, DECIDES to checkpoint:
-     * resets `sinceLast` to 0, bumps `seq`, and emits a single `snapshot_write`
-     * Cmd carrying `payload` + `key` + the new `seq` + `at`. Below the cadence it
-     * returns the bumped slice and NO Cmd.
-     *
-     * `payload` is the checkpoint value to persist (the consumer's domain state);
-     * `at` is the caller-stamped time the progress occurred (epoch ms) — injected,
-     * never read from the clock here.
-     */
-    record(state: SnapshotState, payload: V, at: number): readonly [SnapshotState, readonly Cmd[]];
-    /**
-     * Force a checkpoint regardless of the cadence counter. PURE. Always bumps
-     * `seq`, resets `sinceLast`, and emits the write Cmd. Use on a phase boundary
-     * the cadence would otherwise miss — e.g. "the run just finished, checkpoint
-     * the terminal state now" — so the last durable checkpoint is the final state,
-     * not whatever the modulo happened to land on.
-     */
-    force(state: SnapshotState, payload: V, at: number): readonly [SnapshotState, readonly Cmd[]];
-    /**
-     * Record a confirmed durable write. PURE. Advances `lastSavedSeq` /
-     * `lastSavedAt` to the acknowledged `seq` / `at`, but only forward: an
-     * out-of-order acknowledgement of an OLDER `seq` (a slow write landing after a
-     * newer one) is ignored, so the confirmed watermark is monotonic. Fold the
-     * `snapshot_saved` Msg here.
-     *
-     * Returns the reducer-cell shape `readonly [SnapshotState, readonly Cmd[]]`
-     * (with `Cmd.none` — an ack emits nothing) for uniformity with every sibling
-     * knob, so it drops straight into a `snapshot_saved` cell without the caller
-     * re-wrapping a bare State.
-     */
-    confirm(state: SnapshotState, msg: SnapshotSavedMsg): readonly [SnapshotState, readonly Cmd[]];
-    /**
-     * Resume after a reload. PURE. Resets `sinceLast` to 0 because any
-     * un-checkpointed progress accumulated before the crash is moot — recovery
-     * resumes from the last DURABLE checkpoint (`get` from the store), so the
-     * cadence counter starts fresh from there. `seq` / `lastSavedSeq` /
-     * `lastSavedAt` are preserved (they describe what is durable, which a reload
-     * does not change). Call from a `boot` Msg the host dispatches once after
-     * `run(...)`, never from `init`'s rehydrate branch (invariant 2).
-     *
-     * Returns the reducer-cell shape `readonly [SnapshotState, readonly Cmd[]]`
-     * (with `Cmd.none` — a resume emits nothing) for uniformity with every sibling
-     * knob, so it drops straight into a `snapshot_loaded` cell without the caller
-     * re-wrapping a bare State.
-     */
-    boot(state: SnapshotState): readonly [SnapshotState, readonly Cmd[]];
-    /**
-     * Ask the store for the durable checkpoint. PURE. Emits a single
-     * `snapshot_load` Cmd carrying the configured `key`; returns the slice
-     * UNCHANGED (a read decides nothing about the cadence bookkeeping — only the
-     * later `snapshot_loaded` fold, via `boot`, touches the slice). This is the
-     * entry point of the recovery loop: the consumer dispatches a `boot` Msg once
-     * after `run(...)`, folds `requestLoad` here, and the emitted Cmd's handler
-     * reads `store.get(key)` and dispatches `snapshot_loaded` / `snapshot_load_failed`.
-     *
-     * Returns `readonly [SnapshotState, readonly Cmd[]]` (the reducer-cell shape)
-     * so it drops straight into a `boot: (s) => snap.requestLoad(s)` cell.
-     */
-    requestLoad(state: SnapshotState): readonly [SnapshotState, readonly Cmd[]];
-    /**
-     * The `interpret` map for this knob's two effect Cmds:
-     *
-     *   - `snapshot_write` — binds the store and performs the `put`, routing
-     *     Ok → `snapshot_saved` / Err → `snapshot_failed`.
-     *   - `snapshot_load`  — binds the store and performs the `get`, routing
-     *     Ok → `snapshot_loaded` (payload-or-null) / Err → `snapshot_load_failed`.
-     *
-     * Railway throughout — neither effect throws into the runtime; the outcome is
-     * always a Msg. Spread into your machine's `interpret`.
-     */
-    handlers(ports: SnapshotPorts<V>): Interpret<SnapshotSavedMsg | SnapshotFailedMsg | SnapshotLoadedMsg<V> | SnapshotLoadFailedMsg, SnapshotWriteCmd<V> | SnapshotLoadCmd, unknown>;
-}
-/**
- * Create a snapshot knob from a `SnapshotConfig`. The returned bundle is spliced
- * into a consumer machine: `init()` seeds the slice, `record` / `force` are
- * folded in reducer cells, `confirm` / `boot` handle the acknowledgement +
- * resume Msgs, and `handlers({ store })` supplies the write `interpret` cell.
- */
-declare function createSnapshot<V>(config: SnapshotConfig): SnapshotKnob<V>;
-
-export { type SnapshotWriteCmd as S, type SnapshotState as a, type SnapshotStore as b, type SnapshotSavedMsg as c, type SnapshotFailedMsg as d, type SnapshotLoadedMsg as e, type SnapshotLoadFailedMsg as f, type SnapshotLoadCmd as g, type SnapshotConfig as h, type SnapshotKnob as i, type SnapshotPorts as j, createSnapshot as k, snapshotLoad as l, snapshotLoadFailed as m, snapshotLoaded as n, snapshotSaved as o, snapshotWriteDef as p, snapshotFailed as s };