@demlik/tea 0.3.0 → 0.4.0

package/dist/{chunk-CAXMQJJ3.js.map → chunk-LJJV6ZD5.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/monitored-run/index.ts"],"names":[],"mappings":"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","file":"chunk-CAXMQJJ3.js","sourcesContent":["/**\n * @demlik/tea/monitored-run — a long-running operation that is BOTH staged and\n * watched: an ordered stage pipeline whose POSITION survives eviction, wrapped\n * by a no-progress safety deadline and (optionally) a periodic durable\n * checkpoint.\n *\n * This is the merge of two field-guide concerns the audit-agent machine\n * hand-wired together (`seed/audit-agent-machine`): the OUTER pipeline position\n * (`RunStage` — planning → testing → summarizing → reporting, replayed on cold\n * wake by re-emitting the one outstanding effect) and the no-progress safety\n * alarm (`subs.ts`, keyed on `progressSeq` so every progress event retires the\n * old alarm and arms a fresh one). `monitored-run` lifts both into one config-\n * driven knob with the uniform L2 contract `resilient-call` established:\n * `init()`, the verbs (`start` / `advance` / `progress` / `onDeadline` /\n * `boot`), `subs(state)`, and `handlers(ports)`.\n *\n *   - It is **staged, optionally**. Omit `stages` and the run is single-shot:\n *     `start` enters `running`, `advance` finishes it to `done`. Provide\n *     `stages` and it becomes an ordered pipeline — each `advance` retires the\n *     current stage and claims the next, finishing to `done` only when the last\n *     stage is retired. The pipeline POSITION lives in the Model (a\n *     `work-queue` of stage items), so an eviction mid-pipeline resumes at the\n *     same stage via `boot` — the audit machine's \"pipeline position survives\n *     eviction\" property, generalized.\n *   - It is **watched**. While `running`, a no-progress deadline is armed at\n *     `lastProgressAt + deadlineMs` and keyed on `progressSeq`. Every\n *     `progress` / `advance` bumps the seq, so the substrate retires the old\n *     alarm and arms a new one — a self-rearming watchdog. If the alarm fires\n *     (`onDeadline`) the run goes `failed` with a deadline reason. Omit\n *     `deadlineMs` → no watchdog (the `stale` phase is never reachable).\n *   - It **checkpoints, optionally**. Provide `snapshotEvery` and every\n *     progress unit is accounted to a `../snapshot` slice; once the cadence is\n *     reached a checkpoint Cmd is emitted (interpreted by the spliced snapshot\n *     `handlers`), so a crashed run restarts from the last durable checkpoint\n *     rather than from zero. Omit it → no checkpointing.\n *\n * ## Why the run lifecycle is INLINE (run-tracker not extracted)\n *\n * The phase union (`idle` / `running` / `stale` / `done` / `failed`, a\n * discriminated union carrying only each phase's own data) and its bookkeeping\n * (`runId`, `startedAt`, `lastProgressAt`, `progressSeq`) live directly on this\n * slice rather than behind a `run-tracker` sub-knob.\n * Extraction earns its keep when two independent axes vary; here the lifecycle\n * has exactly one anchoring axis (this run), so a separate module would be a\n * premature seam. The two genuinely independent axes — the safety DEADLINE and\n * the periodic SNAPSHOT — ARE extracted (`../deadline`, `../snapshot`), and the\n * stage list is a `../work-queue` slice (`QueueItem<Stage>[]`) whose every\n * status flip is DELEGATED to the blessed `../work-queue/ops` (`enqueueOp` /\n * `claimNextOp` / `markDoneOp`) — never re-rolled here. The lifecycle is the\n * glue between them.\n *\n * ## The two non-negotiables (canon)\n *\n *   - **Durable** — the slice is plain data (the stage queue is a\n *     JSON-serializable `QueueItem<Stage>[]`, the snapshot slice is plain\n *     numbers), so it survives DO eviction / reload.\n *   - **Replayable** — every transition is a pure verb returning new state +\n *     Cmds; nothing here reads the clock or RNG. Time arrives as an `at` / `atMs`\n *     parameter; the only clock read is `Date.now()` inside the snapshot\n *     `handlers` port (the effect boundary), exactly as `../snapshot` stamps it.\n *\n * ## Typical wiring\n *\n *   const run = createMonitoredRun<MyStage, MyState>({\n *     stages: [\"plan\", \"test\", \"report\"],\n *     deadlineMs: 10 * 60_000,\n *     snapshotEvery: 25,\n *   });\n *\n *   init: (loaded) => loaded ? [loaded, []] : [{ run: run.init() }, []],\n *   update: {\n *     begin:    (s, m) => lift(s, run.start(s.run, m.runId, m.at)),\n *     advance:  (s, m) => lift(s, run.advance(s.run, checkpoint(s), m.result, m.at)),\n *     progress: (s, m) => lift(s, run.progress(s.run, checkpoint(s), m.at)),\n *     run_deadline: (s, m) => lift(s, run.onDeadline(s.run, m)),\n *     boot:     (s, m) => lift(s, run.boot(s.run, m.at)),\n *   },\n *   subscriptions: (s) => run.subs(s.run),\n *   subscribe: { deadline: subscribeDeadline },\n *   interpret: run.handlers({ store: r2 }),\n */\n\nimport {\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineSub,\n  subscribeDeadline,\n} from \"../deadline\";\nimport type { Cmd, Interpret } from \"../index\";\nimport {\n  createSnapshot,\n  type SnapshotFailedMsg,\n  type SnapshotLoadCmd,\n  type SnapshotLoadedMsg,\n  type SnapshotLoadFailedMsg,\n  type SnapshotSavedMsg,\n  type SnapshotState,\n  type SnapshotStore,\n  type SnapshotWriteCmd,\n} from \"../snapshot\";\nimport type { QueueItem } from \"../work-queue\";\nimport { queueAdapter } from \"../work-queue/adapter\";\n\n// ===========================================================================\n// Config — the knob. Every field optional; omit a field → omit its gate.\n// ===========================================================================\n\n/**\n * The monitored-run knob. EVERY field is optional:\n *   - omit `stages`       → single-shot run (no pipeline; one `advance` finishes).\n *   - omit `deadlineMs`   → no no-progress watchdog (the run is never auto-failed).\n *   - omit `snapshotEvery`→ no periodic checkpoint (no `snapshot_write` Cmds).\n *\n * An empty config `{}` is a valid single-shot, unwatched, uncheckpointed run.\n *\n * `Stage` is the consumer's stage identifier — any JSON-serializable value\n * (a string id, a `{ kind, ... }` record). It rides through the stage queue\n * unchanged so the consumer's reducer can branch on the current stage to emit\n * that stage's outstanding effect (the audit machine's `outstandingEffect`).\n */\nexport interface MonitoredRunConfig<Stage> {\n  /**\n   * The ordered stages of the pipeline. Position survives eviction (lives in\n   * the Model's stage queue). Omit for a single-shot run. An empty array is\n   * treated as single-shot too — there is nothing to pipeline through.\n   */\n  readonly stages?: readonly Stage[];\n  /**\n   * No-progress watchdog budget, in ms. The safety deadline is armed at\n   * `lastProgressAt + deadlineMs` and re-armed on every progress event. Omit\n   * for no watchdog.\n   */\n  readonly deadlineMs?: number;\n  /**\n   * Checkpoint cadence — write a durable snapshot once this many progress\n   * units have accumulated. Threaded straight into `../snapshot`'s `every`.\n   * Omit for no checkpointing.\n   */\n  readonly snapshotEvery?: number;\n  /**\n   * Store key the rolling checkpoint is written under. Forwarded to\n   * `../snapshot`'s `key`; defaults to that module's `@@snapshot`. Ignored\n   * when `snapshotEvery` is omitted.\n   */\n  readonly snapshotKey?: string;\n}\n\n// ===========================================================================\n// Slice — the Model field this knob owns. Run lifecycle INLINE + composed bricks.\n// ===========================================================================\n\n/**\n * Why a run terminated as `failed`. Discriminated so each reason carries only\n * its own data (pattern 11):\n *   - `deadline`  — the no-progress watchdog fired (`onDeadline`).\n *   - `stage`     — the consumer reported a stage failure via `advance(..., fail)`.\n *\n * `stale` is a SEPARATE phase (not a fail reason): a run is `stale` only by an\n * explicit consumer signal that progress has wedged WITHOUT the deadline having\n * fired — a soft, recoverable observation. The deadline firing is a hard\n * terminal (`failed { reason: \"deadline\" }`).\n *\n * The `stage` variant carries the FAILING STAGE VALUE (the `Stage` itself), not\n * a positional index: done stages leave the queue (`markDoneOp` filters them),\n * so a residual index drifts as the pipeline advances. The stage value is the\n * stable, meaningful identifier — `undefined` for a single-shot run (no stage).\n */\nexport type RunFailure<Stage> =\n  | { readonly reason: \"deadline\"; readonly at: number }\n  | {\n      readonly reason: \"stage\";\n      readonly stage: Stage | undefined;\n      readonly error: unknown;\n    };\n\n/**\n * The run bookkeeping every phase carries in common, split out so each arm of\n * the `MonitoredRunState` discriminated union names only the data it ADDS\n * (`runId` on started phases, `failure` on `failed`) — the same discipline the\n * sibling `PaginatorState` uses for its shared `seen` / `pages` counters. Plain\n * data end to end so the whole slice survives DO eviction / reload:\n *\n *   - `stepStates`     — the stage pipeline as a `work-queue` of stage items.\n *                        Empty for a single-shot run. The ONE `running` item is\n *                        the current stage; `done` items are retired stages\n *                        (they leave the queue via `markDoneOp`, so the queue\n *                        shrinks as the pipeline advances and is empty at\n *                        `done`). POSITION survives eviction because this list\n *                        is durable.\n *   - `startedAt`      — `at` of `start`. Observability; never compared in a verb.\n *   - `lastProgressAt` — `at` of the most recent progress event; the watchdog\n *                        base. Re-armed by `progress` / `advance`.\n *   - `progressSeq`    — monotonic progress counter; keys the safety alarm Sub\n *                        id so every bump retires the old alarm and arms a new\n *                        one (the audit subs' `safety:{progressSeq}` discipline).\n *   - `snapshot`       — the `../snapshot` slice (cadence counter + durable\n *                        watermark). Always present (uniform shape); the gate\n *                        is simply never driven when `snapshotEvery` is omitted.\n */\ninterface RunCore<Stage> {\n  readonly stepStates: readonly QueueItem<Stage>[];\n  readonly startedAt: number;\n  readonly lastProgressAt: number;\n  readonly progressSeq: number;\n  readonly snapshot: SnapshotState;\n}\n\n/**\n * The slice — a discriminated union on `phase` so each phase carries ONLY its\n * own data and impossible combinations are unrepresentable (pattern 11), the\n * same idiom the sibling `CircuitState` / `PaginatorState` / `RunFailure` follow:\n *\n *   - `idle`    — created but never started. Carries no `runId` (identity is\n *                 host-minted at `start`) and no `failure`: \"not started\" is its\n *                 OWN phase, not a `running` run wearing an empty-string `runId`\n *                 sentinel. `start` is the only transition out, so no verb has to\n *                 guard \"has this actually started?\" — `phase === \"idle\"` says it.\n *   - `running` — the run is live. Carries the host-minted `runId` and the\n *                 `RunCore` pipeline position + watchdog bookkeeping.\n *   - `stale`   — a soft \"no progress observed\" mark the consumer can set and\n *                 clear; still resumable (a `progress` clears it back to\n *                 `running`). Distinct from a fired deadline, which is terminal.\n *   - `done`    — every stage retired (or the single-shot `advance` landed).\n *   - `failed`  — terminal failure; the typed `failure` reason rides ONLY this\n *                 arm, so it is present iff `phase === \"failed\"` BY CONSTRUCTION —\n *                 there is no nullable side field to keep in sync.\n *\n * `runId` is the host-minted run identity, stamped at `start` (the machine never\n * mints — see the audit seed's \"run identity is host-minted\"). It rides every\n * started phase, but not `idle`.\n */\nexport type MonitoredRunState<Stage> =\n  | (RunCore<Stage> & { readonly phase: \"idle\" })\n  | (RunCore<Stage> & { readonly phase: \"running\"; readonly runId: string })\n  | (RunCore<Stage> & { readonly phase: \"stale\"; readonly runId: string })\n  | (RunCore<Stage> & { readonly phase: \"done\"; readonly runId: string })\n  | (RunCore<Stage> & {\n      readonly phase: \"failed\";\n      readonly runId: string;\n      readonly failure: RunFailure<Stage>;\n    });\n\n/**\n * The live (still-timed) phases — `running` or `stale`. The verbs narrow to this\n * before touching the watchdog bookkeeping (`runId` / `progressSeq`), so a\n * settled (`done` / `failed`) or never-started (`idle`) slice can never be bumped\n * — the narrow replaces the old `runId === \"\"` born-live guard.\n */\ntype LiveRun<Stage> = Extract<\n  MonitoredRunState<Stage>,\n  { readonly phase: \"running\" | \"stale\" }\n>;\n\n/**\n * The outcome a consumer reports to `advance`: the current stage either\n * succeeded (retire it, claim the next) or failed (terminate the run). Plain\n * data — the consumer parses its stage result at its own boundary and hands a\n * settled outcome here.\n */\nexport type StageResult =\n  | { readonly kind: \"ok\" }\n  | { readonly kind: \"fail\"; readonly error: unknown };\n\n// ===========================================================================\n// Cmd + Msg — re-exported from the composed bricks so consumers wire one import.\n// ===========================================================================\n\n/** The checkpoint-write Cmd, generic over the consumer's checkpoint value `V`. */\nexport type MonitoredRunCmd<V> = SnapshotWriteCmd<V>;\n\n/** The deadline Msg the safety alarm dispatches when the watchdog fires. */\nexport type MonitoredRunTimerMsg = DeadlineExceeded;\n\n/** Ports the consumer supplies to `handlers` — just the checkpoint store. */\nexport interface MonitoredRunPorts<V> {\n  /** Where periodic checkpoints are written (R2 / KV / DO sub-key / Map). */\n  readonly store: SnapshotStore<V>;\n}\n\n// ===========================================================================\n// Sub-id family. The safety alarm is keyed on `progressSeq` so a progress\n// event retires the old alarm and arms a new one (single-shot, re-armed by id\n// bump — the audit subs discipline).\n// ===========================================================================\n\nfunction safetyTimerId(runId: string, progressSeq: number): string {\n  return `monitored:safety:${runId}:${progressSeq}`;\n}\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build a monitored-run knob from `config`. `Stage` is the consumer's stage\n * identifier type; `V` is the consumer's checkpoint value type (what\n * `snapshotEvery` checkpoints). Returns the uniform L2 knob contract.\n *\n * No `rng` parameter: unlike `resilient-call`, nothing here jitters — the only\n * external inputs are time (an `at` / `atMs` parameter) and the consumer's\n * stage outcomes. The clock is read only inside the snapshot `handlers` port.\n */\nexport function createMonitoredRun<Stage, V = unknown>(\n  config: MonitoredRunConfig<Stage> = {},\n) {\n  const stages = config.stages ?? [];\n  const isPipeline = stages.length > 0;\n\n  // The stage-queue seam, bound once. Every stage status flip delegates to the\n  // `QueueAdapter` verbs (`wq.enqueue` / `wq.claim` / `wq.markDone`), so the\n  // `QueueItem<Stage>` shape stays insulated behind them.\n  const wq = queueAdapter<Stage>();\n\n  // The snapshot sub-knob is built only when `snapshotEvery` is configured;\n  // absence is `null` so the progress gate short-circuits to \"no checkpoint\".\n  // When present, the slice still carries a default SnapshotState so the shape\n  // is uniform across configs — the gate simply never records into it.\n  const snap =\n    config.snapshotEvery !== undefined\n      ? createSnapshot<V>({\n          every: config.snapshotEvery,\n          ...(config.snapshotKey !== undefined\n            ? { key: config.snapshotKey }\n            : {}),\n        })\n      : null;\n\n  // The snapshot knob to actually drive: `snap` when configured, else a single\n  // inert default (`every: 1`) bound ONCE here. Its `record` is never invoked\n  // (the progress gate short-circuits when `snap` is null), so the cadence value\n  // is immaterial — one shared stateless knob of pure functions stands in for\n  // the disabled-checkpoint case across init/boot/handlers.\n  const activeSnap = snap ?? createSnapshot<V>({ every: 1 });\n\n  /** The starting slice for a never-started run: the `idle` phase, no `runId`. */\n  function init(): MonitoredRunState<Stage> {\n    return {\n      phase: \"idle\",\n      stepStates: [],\n      startedAt: 0,\n      lastProgressAt: 0,\n      progressSeq: 0,\n      // A default snapshot slice even without the brick → uniform shape. When\n      // `snap` is null the inert `activeSnap` default supplies the slice; its\n      // `record` is never called, so the cadence value is immaterial.\n      snapshot: activeSnap.init(),\n    };\n  }\n\n  /**\n   * Seed the stage queue from the configured stages: every stage enqueued\n   * `pending`, then the first claimed `running`. `at` stamps the claim. PURE —\n   * the work-queue ops are pure array transforms; ids are positional (`stage:i`)\n   * so they are deterministic and replayable (no `crypto`, no `Math.random`).\n   */\n  function seedStages(at: number): readonly QueueItem<Stage>[] {\n    let queue: readonly QueueItem<Stage>[] = [];\n    stages.forEach((stage, i) => {\n      queue = wq.enqueue(queue, stage, at, `stage:${i}`).next;\n    });\n    // Claim the first stage as the running position. A non-empty pipeline always\n    // has a pending head here, so the claim succeeds.\n    const claimed = wq.claim(queue, at);\n    return claimed ? claimed.next : queue;\n  }\n\n  /** The current (running) stage item, or `undefined` for a single-shot run. */\n  function currentStage(\n    s: MonitoredRunState<Stage>,\n  ): QueueItem<Stage> | undefined {\n    return s.stepStates.find((i) => i.status === \"running\");\n  }\n\n  // === Verb: start =========================================================\n\n  /**\n   * Start (or restart) the run for `runId` at time `at`. Seeds the stage queue\n   * (if a pipeline) and enters `running` with the watchdog clock primed. Stamps\n   * `runId` from the host — the machine never mints (invariant: identity is\n   * host-minted, parsed at the boundary). PURE.\n   */\n  function start(\n    s: MonitoredRunState<Stage>,\n    runId: string,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    // Build the `running` arm explicitly rather than spreading `...s`: a restart\n    // from `failed` must NOT carry the old `failure` field forward (the `running`\n    // arm has none), and a start from `idle` has no `runId` to preserve. Only the\n    // snapshot slice threads through.\n    const next: MonitoredRunState<Stage> = {\n      phase: \"running\",\n      runId,\n      stepStates: isPipeline ? seedStages(at) : [],\n      startedAt: at,\n      lastProgressAt: at,\n      progressSeq: 0,\n      snapshot: s.snapshot,\n    };\n    return [next, []];\n  }\n\n  /**\n   * Bump the watchdog clock: set `lastProgressAt`/`progressSeq` so the safety\n   * alarm Sub id changes and the substrate re-arms a fresh deadline. Shared by\n   * `progress` and `advance`. PURE.\n   */\n  function bumpProgress(s: LiveRun<Stage>, at: number): LiveRun<Stage> {\n    return { ...s, lastProgressAt: at, progressSeq: s.progressSeq + 1 };\n  }\n\n  /**\n   * Account one progress unit to the snapshot slice (when the brick is\n   * configured), returning the new slice + any checkpoint Cmd. `payload` is the\n   * consumer's checkpoint value to persist. PURE — `snap.record` is pure, the\n   * write is realized only when the runtime performs the emitted Cmd.\n   */\n  function recordSnapshot(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (snap === null) return [s, []];\n    const [snapshot, cmds] = snap.record(s.snapshot, payload, at);\n    // `snap.record` only ever emits `SnapshotWriteCmd<V>` (its sole Cmd), but\n    // its signature widens to `readonly Cmd[]`. Narrow back to this knob's\n    // precise Cmd union so a consumer's host Cmd type can stay exact.\n    return [{ ...s, snapshot }, cmds as readonly MonitoredRunCmd<V>[]];\n  }\n\n  // === Verb: progress ======================================================\n\n  /**\n   * Record forward progress: bump the watchdog (re-arming the safety alarm),\n   * clear any `stale` mark back to `running`, and account a snapshot unit\n   * (emitting a checkpoint Cmd on a cadence hit). A no-op unless the run is live\n   * (`running` / `stale`) — a late progress event on a settled (`done` /\n   * `failed`) or never-started (`idle`) run is ignored. PURE.\n   */\n  function progress(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    const bumped: MonitoredRunState<Stage> = {\n      ...bumpProgress(s, at),\n      phase: \"running\",\n    };\n    return recordSnapshot(bumped, payload, at);\n  }\n\n  // === Verb: markStale =====================================================\n\n  /**\n   * Mark the run `stale` — a soft \"no progress observed\" signal the consumer\n   * raises WITHOUT the deadline having fired (e.g. an upstream heartbeat gap).\n   * Recoverable: the next `progress` flips it back to `running`. A no-op unless\n   * the run is currently `running` (a settled run cannot go stale). Does NOT\n   * touch `progressSeq` — going stale is not progress, so the armed deadline\n   * keeps counting toward the hard terminal. PURE.\n   */\n  function markStale(\n    s: MonitoredRunState<Stage>,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\") return [s, []];\n    return [{ ...s, phase: \"stale\" }, []];\n  }\n\n  // === Verb: advance =======================================================\n\n  /**\n   * Advance the pipeline on a stage outcome:\n   *\n   *   - `result.kind === \"fail\"` → terminate `failed { reason: \"stage\" }`,\n   *     carrying the failing stage index + error. No further stages run.\n   *   - `result.kind === \"ok\"`:\n   *       - single-shot run → finish to `done` (and force a final checkpoint\n   *         when checkpointing, so the last durable snapshot is the terminal\n   *         state).\n   *       - pipeline → retire the current stage (`markDoneOp`) and claim the\n   *         next (`claimNextOp`). If none remain, finish to `done`. The new\n   *         position survives eviction.\n   *\n   * An advance is itself a progress event, so it bumps the watchdog (re-arming\n   * the alarm at the new stage) and accounts a snapshot unit. A no-op on a\n   * settled (`done` / `failed`) or never-started (`idle`) run. PURE — `at` is the\n   * only clock, ids are positional.\n   */\n  function advance(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    result: StageResult,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n\n    // Stage failure → hard terminal. Carry the failing stage VALUE (stable),\n    // `undefined` for a single-shot run with no stage.\n    if (result.kind === \"fail\") {\n      const failed: MonitoredRunState<Stage> = {\n        ...s,\n        phase: \"failed\",\n        failure: {\n          reason: \"stage\",\n          stage: currentStage(s)?.input,\n          error: result.error,\n        },\n      };\n      return [failed, []];\n    }\n\n    // Success: bump the watchdog first (an advance is progress), then move the\n    // pipeline position.\n    const bumped = bumpProgress(s, at);\n\n    // Single-shot: one advance finishes the run.\n    if (!isPipeline) {\n      const done: MonitoredRunState<Stage> = { ...bumped, phase: \"done\" };\n      // Force a terminal checkpoint so the last durable snapshot is `done`,\n      // not whatever the cadence happened to land on.\n      return finishWithSnapshot(done, payload, at);\n    }\n\n    // Pipeline: retire the running stage, claim the next.\n    const current = currentStage(s);\n    const afterDone =\n      current !== undefined\n        ? wq.markDone(s.stepStates, current.id).next\n        : s.stepStates;\n    const claimed = wq.claim(afterDone, at);\n\n    if (claimed === null) {\n      // No more stages — the pipeline is complete.\n      const done: MonitoredRunState<Stage> = {\n        ...bumped,\n        phase: \"done\",\n        stepStates: afterDone,\n      };\n      return finishWithSnapshot(done, payload, at);\n    }\n\n    // Advance to the next stage — POSITION now points at the claimed item.\n    const moved: MonitoredRunState<Stage> = {\n      ...bumped,\n      stepStates: claimed.next,\n    };\n    return recordSnapshot(moved, payload, at);\n  }\n\n  /**\n   * Finish helper: force a terminal checkpoint when checkpointing is enabled\n   * (so the durable snapshot is the terminal state), else just settle. Shared\n   * by single-shot finish and pipeline completion. PURE.\n   */\n  function finishWithSnapshot(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (snap === null) return [s, []];\n    const [snapshot, cmds] = snap.force(s.snapshot, payload, at);\n    // Same narrowing as `recordSnapshot`: `snap.force` emits only the write Cmd.\n    return [{ ...s, snapshot }, cmds as readonly MonitoredRunCmd<V>[]];\n  }\n\n  // === Verb: onDeadline ====================================================\n\n  /**\n   * The safety alarm fired. Two outcomes by Sub-id match:\n   *\n   *   - the alarm matches the CURRENT `progressSeq` (no progress since it was\n   *     armed) → the run is wedged → terminate `failed { reason: \"deadline\" }`.\n   *   - the alarm matches an OLDER seq → a stale fire racing a progress event\n   *     that already re-armed the alarm → no-op (the substrate retired this id;\n   *     tolerate a fire still in flight defensively).\n   *\n   * A no-op on a settled run (its alarm was reconciled away; tolerate a stale\n   * fire) and on a NEVER-STARTED (`idle`) run (`subs` armed nothing for it, so\n   * any alarm reaching it is a rogue fire that must not un-start it). PURE —\n   * `msg.atMs` stamps the failure.\n   */\n  function onDeadline(\n    s: MonitoredRunState<Stage>,\n    msg: MonitoredRunTimerMsg,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    // Only a live (`running` / `stale`) run is watched. A settled (`done` /\n    // `failed`) run's alarm was reconciled away, and a never-started (`idle`) run\n    // — which has no host-minted `runId` and armed nothing — must not be\n    // un-started by a born-live/rogue fire. The phase narrow IS the guard the old\n    // `runId === \"\"` sentinel stood in for.\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    // Only the alarm armed against the current progressSeq is live. A bumped\n    // seq means progress re-armed it; an older fire is stale.\n    if (msg.id !== safetyTimerId(s.runId, s.progressSeq)) return [s, []];\n    const failed: MonitoredRunState<Stage> = {\n      ...s,\n      phase: \"failed\",\n      failure: { reason: \"deadline\", at: msg.atMs },\n    };\n    return [failed, []];\n  }\n\n  // === Verb: boot ==========================================================\n\n  /**\n   * Resume after a reload (cold wake). Re-seeds the watchdog clock to `at` so\n   * the safety alarm re-arms from NOW (the pre-crash `lastProgressAt` would\n   * immediately fire a deadline that already elapsed during downtime — a cold\n   * wake is not a no-progress wedge). Bumps `progressSeq` so the alarm gets a\n   * fresh id, and resets the snapshot cadence counter (un-checkpointed\n   * pre-crash progress is moot — recovery resumes from the last durable\n   * checkpoint). The pipeline POSITION (`stepStates`) is preserved untouched —\n   * that is the whole point of staging: resume at the same stage.\n   *\n   * A no-op on a settled (`done` / `failed`) or never-started (`idle`) run. Emits\n   * NO Cmd — re-emitting the current stage's outstanding effect is the CONSUMER's\n   * job (it knows the per-stage Cmd), the audit machine's `outstandingEffect(stage)`\n   * pattern. PURE.\n   */\n  function boot(\n    s: MonitoredRunState<Stage>,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    // `snap.boot` returns the reducer-cell shape `[SnapshotState, Cmd[]]`\n    // (uniform across every sibling knob); a boot emits no Cmd, so take only the\n    // slice. Assigning the tuple itself would put an ARRAY where a SnapshotState\n    // belongs — a type error AND a non-round-trippable slice.\n    const [bootedSnapshot] = activeSnap.boot(s.snapshot);\n    const reseeded: MonitoredRunState<Stage> = {\n      ...s,\n      phase: \"running\",\n      lastProgressAt: at,\n      progressSeq: s.progressSeq + 1,\n      snapshot: bootedSnapshot,\n      // Any stage left `running` mid-flight stays the running position; the\n      // queue is already correct (a single in-flight stage). resetRunningOp is\n      // NOT applied — unlike a work pool, a monitored run has exactly one\n      // in-flight stage and resuming it (not re-queuing it) is the correct\n      // cold-wake behavior.\n    };\n    return [reseeded, []];\n  }\n\n  // === Subs ================================================================\n\n  /**\n   * Pre-wired subscriptions: the no-progress safety deadline, armed only while\n   * the run is live (`running` / `stale`) AND a `deadlineMs` is configured. The\n   * Sub id is keyed on `progressSeq`, so every progress event retires the old\n   * alarm and the substrate arms a fresh one at the new `lastProgressAt +\n   * deadlineMs` — a self-rearming watchdog with no manual `clearTimeout`. A\n   * settled run desires no subs. Wire `subscribe: { deadline: subscribeDeadline }`.\n   *\n   * A NEVER-STARTED slice (`init()`) is its OWN `idle` phase, not a `running` run\n   * with an empty `runId`. The `phase !== \"running\" && phase !== \"stale\"` narrow\n   * therefore excludes it structurally — no separate `runId === \"\"` sentinel gate\n   * is needed. Were `idle` armed, it would fire a deadline at `0 + deadlineMs`\n   * (already in the past) and auto-fail a run that never began — the \"born live\"\n   * defect. `start` is the only transition out of `idle`, so the watchdog exists\n   * exactly once a real run is in flight.\n   */\n  function subs(s: MonitoredRunState<Stage>): readonly DeadlineSub[] {\n    if (config.deadlineMs === undefined) return [];\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [];\n    return [\n      deadlineSub(\n        safetyTimerId(s.runId, s.progressSeq),\n        s.lastProgressAt + config.deadlineMs,\n      ),\n    ];\n  }\n\n  // === Handlers ============================================================\n\n  /**\n   * Pre-wired interpret handler for the checkpoint write. Delegates wholesale to\n   * `../snapshot`'s `handlers` (which performs the `put` and routes Ok →\n   * `snapshot_saved` / Err → `snapshot_failed` via Railway — the write never\n   * rejects into the runtime). When checkpointing is disabled (`snapshotEvery`\n   * omitted), no `snapshot_write` Cmd is ever emitted, so the returned map is an\n   * inert no-op handler — kept for a uniform `handlers(ports)` call shape.\n   *\n   * Fold the `snapshot_saved` Msg back through this knob's `confirmSnapshot`\n   * verb to advance the durable watermark.\n   */\n  function handlers(\n    ports: MonitoredRunPorts<V>,\n  ): Interpret<\n    | SnapshotSavedMsg\n    | SnapshotFailedMsg\n    | SnapshotLoadedMsg<V>\n    | SnapshotLoadFailedMsg,\n    SnapshotWriteCmd<V> | SnapshotLoadCmd,\n    unknown\n  > {\n    return activeSnap.handlers({ store: ports.store });\n  }\n\n  /**\n   * Fold a confirmed checkpoint write into the slice — advances the snapshot\n   * watermark (forward-only). A no-op pass-through when checkpointing is\n   * disabled. PURE. Fold the `snapshot_saved` Msg here.\n   */\n  function confirmSnapshot(\n    s: MonitoredRunState<Stage>,\n    msg: SnapshotSavedMsg,\n  ): MonitoredRunState<Stage> {\n    if (snap === null) return s;\n    // `snap.confirm` returns the reducer-cell shape `[SnapshotState, Cmd[]]`\n    // (an ack emits nothing). Take only the slice — folding the whole tuple into\n    // `snapshot` would store an ARRAY where a SnapshotState belongs (a type error\n    // and a non-round-trippable slice).\n    const [confirmed] = snap.confirm(s.snapshot, msg);\n    return { ...s, snapshot: confirmed };\n  }\n\n  return {\n    init,\n    start,\n    progress,\n    markStale,\n    advance,\n    onDeadline,\n    boot,\n    confirmSnapshot,\n    subs,\n    handlers,\n  };\n}\n\n/**\n * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the\n * slice lives at `state.run`. Convenience for the common single-slice host;\n * hosts with a differently-named field spread by hand. PURE — a thin record\n * rebuild, no clock / RNG.\n */\nexport function liftRun<\n  S extends { run: MonitoredRunState<Stage> },\n  Stage,\n  C extends Cmd,\n>(\n  state: S,\n  [slice, cmds]: readonly [MonitoredRunState<Stage>, readonly C[]],\n): readonly [S, readonly C[]] {\n  return [{ ...state, run: slice }, cmds];\n}\n\n/**\n * Re-export the deadline Sub primitives so consumers (and tests) wire one\n * import: `subscribeDeadline` is the `subscribe` cell, `deadlineSub` builds the\n * Sub literal this knob's `subs` emits.\n */\nexport { subscribeDeadline, deadlineSub };\nexport type {\n  DeadlineSub,\n  DeadlineExceeded,\n  SnapshotSavedMsg,\n  SnapshotWriteCmd,\n};\n"]}
+{"version":3,"sources":["../src/monitored-run/index.ts"],"names":[],"mappings":"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","file":"chunk-LJJV6ZD5.js","sourcesContent":["/**\n * @demlik/tea/monitored-run — a long-running operation that is BOTH staged and\n * watched: an ordered stage pipeline whose POSITION survives eviction, wrapped\n * by a no-progress safety deadline and (optionally) a periodic durable\n * checkpoint.\n *\n * This is the merge of two field-guide concerns the audit-agent machine\n * hand-wired together (`seed/audit-agent-machine`): the OUTER pipeline position\n * (`RunStage` — planning → testing → summarizing → reporting, replayed on cold\n * wake by re-emitting the one outstanding effect) and the no-progress safety\n * alarm (`subs.ts`, keyed on `progressSeq` so every progress event retires the\n * old alarm and arms a fresh one). `monitored-run` lifts both into one config-\n * driven knob with the uniform L2 contract `resilient-call` established:\n * `init()`, the verbs (`start` / `advance` / `progress` / `onDeadline` /\n * `boot`), `subs(state)`, and `handlers(ports)`.\n *\n *   - It is **staged, optionally**. Omit `stages` and the run is single-shot:\n *     `start` enters `running`, `advance` finishes it to `done`. Provide\n *     `stages` and it becomes an ordered pipeline — each `advance` retires the\n *     current stage and claims the next, finishing to `done` only when the last\n *     stage is retired. The pipeline POSITION lives in the Model (a\n *     `work-queue` of stage items), so an eviction mid-pipeline resumes at the\n *     same stage via `boot` — the audit machine's \"pipeline position survives\n *     eviction\" property, generalized.\n *   - It is **watched**. While `running`, a no-progress deadline is armed at\n *     `lastProgressAt + deadlineMs` and keyed on `progressSeq`. Every\n *     `progress` / `advance` bumps the seq, so the substrate retires the old\n *     alarm and arms a new one — a self-rearming watchdog. If the alarm fires\n *     (`onDeadline`) the run goes `failed` with a deadline reason. Omit\n *     `deadlineMs` → no watchdog (the `stale` phase is never reachable).\n *   - It **checkpoints, optionally**. Provide `snapshotEvery` and every\n *     progress unit is accounted to a `../snapshot` slice; once the cadence is\n *     reached a checkpoint Cmd is emitted (interpreted by the spliced snapshot\n *     `handlers`), so a crashed run restarts from the last durable checkpoint\n *     rather than from zero. Omit it → no checkpointing.\n *\n * ## Why the run lifecycle is INLINE (run-tracker not extracted)\n *\n * The phase union (`idle` / `running` / `stale` / `done` / `failed`, a\n * discriminated union carrying only each phase's own data) and its bookkeeping\n * (`runId`, `startedAt`, `lastProgressAt`, `progressSeq`) live directly on this\n * slice rather than behind a `run-tracker` sub-knob.\n * Extraction earns its keep when two independent axes vary; here the lifecycle\n * has exactly one anchoring axis (this run), so a separate module would be a\n * premature seam. The two genuinely independent axes — the safety DEADLINE and\n * the periodic SNAPSHOT — ARE extracted (`../deadline`, `../snapshot`), and the\n * stage list is a `../work-queue` slice (`QueueItem<Stage>[]`) whose every\n * status flip is DELEGATED to the blessed `../work-queue/ops` (`enqueueOp` /\n * `claimNextOp` / `markDoneOp`) — never re-rolled here. The lifecycle is the\n * glue between them.\n *\n * ## The two non-negotiables (canon)\n *\n *   - **Durable** — the slice is plain data (the stage queue is a\n *     JSON-serializable `QueueItem<Stage>[]`, the snapshot slice is plain\n *     numbers), so it survives DO eviction / reload.\n *   - **Replayable** — every transition is a pure verb returning new state +\n *     Cmds; nothing here reads the clock or RNG. Time arrives as an `at` / `atMs`\n *     parameter; the only clock read is `Date.now()` inside the snapshot\n *     `handlers` port (the effect boundary), exactly as `../snapshot` stamps it.\n *\n * ## Typical wiring\n *\n *   const run = createMonitoredRun<MyStage, MyState>({\n *     stages: [\"plan\", \"test\", \"report\"],\n *     deadlineMs: 10 * 60_000,\n *     snapshotEvery: 25,\n *   });\n *\n *   init: (loaded) => loaded ? [loaded, []] : [{ run: run.init() }, []],\n *   update: {\n *     begin:    (s, m) => lift(s, run.start(s.run, m.runId, m.at)),\n *     advance:  (s, m) => lift(s, run.advance(s.run, checkpoint(s), m.result, m.at)),\n *     progress: (s, m) => lift(s, run.progress(s.run, checkpoint(s), m.at)),\n *     run_deadline: (s, m) => lift(s, run.onDeadline(s.run, m)),\n *     boot:     (s, m) => lift(s, run.boot(s.run, m.at)),\n *   },\n *   subscriptions: (s) => run.subs(s.run),\n *   subscribe: { deadline: subscribeDeadline },\n *   interpret: run.handlers({ store: r2 }),\n */\n\nimport {\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineSub,\n  subscribeDeadline,\n} from \"../deadline\";\nimport type { Cmd, Interpret } from \"../index\";\nimport {\n  createSnapshot,\n  type SnapshotFailedMsg,\n  type SnapshotLoadCmd,\n  type SnapshotLoadedMsg,\n  type SnapshotLoadFailedMsg,\n  type SnapshotSavedMsg,\n  type SnapshotState,\n  type SnapshotStore,\n  type SnapshotWriteCmd,\n} from \"../snapshot\";\nimport type { QueueItem } from \"../work-queue\";\nimport { queueAdapter } from \"../work-queue/adapter\";\n\n// ===========================================================================\n// Config — the knob. Every field optional; omit a field → omit its gate.\n// ===========================================================================\n\n/**\n * The monitored-run knob. EVERY field is optional:\n *   - omit `stages`       → single-shot run (no pipeline; one `advance` finishes).\n *   - omit `deadlineMs`   → no no-progress watchdog (the run is never auto-failed).\n *   - omit `snapshotEvery`→ no periodic checkpoint (no `snapshot_write` Cmds).\n *\n * An empty config `{}` is a valid single-shot, unwatched, uncheckpointed run.\n *\n * `Stage` is the consumer's stage identifier — any JSON-serializable value\n * (a string id, a `{ kind, ... }` record). It rides through the stage queue\n * unchanged so the consumer's reducer can branch on the current stage to emit\n * that stage's outstanding effect (the audit machine's `outstandingEffect`).\n */\nexport interface MonitoredRunConfig<Stage> {\n  /**\n   * The ordered stages of the pipeline. Position survives eviction (lives in\n   * the Model's stage queue). Omit for a single-shot run. An empty array is\n   * treated as single-shot too — there is nothing to pipeline through.\n   */\n  readonly stages?: readonly Stage[];\n  /**\n   * No-progress watchdog budget, in ms. The safety deadline is armed at\n   * `lastProgressAt + deadlineMs` and re-armed on every progress event. Omit\n   * for no watchdog.\n   */\n  readonly deadlineMs?: number;\n  /**\n   * Checkpoint cadence — write a durable snapshot once this many progress\n   * units have accumulated. Threaded straight into `../snapshot`'s `every`.\n   * Omit for no checkpointing.\n   */\n  readonly snapshotEvery?: number;\n  /**\n   * Store key the rolling checkpoint is written under. Forwarded to\n   * `../snapshot`'s `key`; defaults to that module's `@@snapshot`. Ignored\n   * when `snapshotEvery` is omitted.\n   */\n  readonly snapshotKey?: string;\n}\n\n// ===========================================================================\n// Slice — the Model field this knob owns. Run lifecycle INLINE + composed bricks.\n// ===========================================================================\n\n/**\n * Why a run terminated as `failed`. Discriminated so each reason carries only\n * its own data (pattern 11):\n *   - `deadline`  — the no-progress watchdog fired (`onDeadline`).\n *   - `stage`     — the consumer reported a stage failure via `advance(..., fail)`.\n *\n * `stale` is a SEPARATE phase (not a fail reason): a run is `stale` only by an\n * explicit consumer signal that progress has wedged WITHOUT the deadline having\n * fired — a soft, recoverable observation. The deadline firing is a hard\n * terminal (`failed { reason: \"deadline\" }`).\n *\n * The `stage` variant carries the FAILING STAGE VALUE (the `Stage` itself), not\n * a positional index: done stages leave the queue (`markDoneOp` filters them),\n * so a residual index drifts as the pipeline advances. The stage value is the\n * stable, meaningful identifier — `undefined` for a single-shot run (no stage).\n */\nexport type RunFailure<Stage> =\n  | { readonly reason: \"deadline\"; readonly at: number }\n  | {\n      readonly reason: \"stage\";\n      readonly stage: Stage | undefined;\n      readonly error: unknown;\n    };\n\n/**\n * The run bookkeeping every phase carries in common, split out so each arm of\n * the `MonitoredRunState` discriminated union names only the data it ADDS\n * (`runId` on started phases, `failure` on `failed`) — the same discipline the\n * sibling `PaginatorState` uses for its shared `seen` / `pages` counters. Plain\n * data end to end so the whole slice survives DO eviction / reload:\n *\n *   - `stepStates`     — the stage pipeline as a `work-queue` of stage items.\n *                        Empty for a single-shot run. The ONE `running` item is\n *                        the current stage; `done` items are retired stages\n *                        (they leave the queue via `markDoneOp`, so the queue\n *                        shrinks as the pipeline advances and is empty at\n *                        `done`). POSITION survives eviction because this list\n *                        is durable.\n *   - `startedAt`      — `at` of `start`. Observability; never compared in a verb.\n *   - `lastProgressAt` — `at` of the most recent progress event; the watchdog\n *                        base. Re-armed by `progress` / `advance`.\n *   - `progressSeq`    — monotonic progress counter; keys the safety alarm Sub\n *                        id so every bump retires the old alarm and arms a new\n *                        one (the audit subs' `safety:{progressSeq}` discipline).\n *   - `snapshot`       — the `../snapshot` slice (cadence counter + durable\n *                        watermark). Always present (uniform shape); the gate\n *                        is simply never driven when `snapshotEvery` is omitted.\n */\ninterface RunCore<Stage> {\n  readonly stepStates: readonly QueueItem<Stage>[];\n  readonly startedAt: number;\n  readonly lastProgressAt: number;\n  readonly progressSeq: number;\n  readonly snapshot: SnapshotState;\n}\n\n/**\n * The slice — a discriminated union on `phase` so each phase carries ONLY its\n * own data and impossible combinations are unrepresentable (pattern 11), the\n * same idiom the sibling `CircuitState` / `PaginatorState` / `RunFailure` follow:\n *\n *   - `idle`    — created but never started. Carries no `runId` (identity is\n *                 host-minted at `start`) and no `failure`: \"not started\" is its\n *                 OWN phase, not a `running` run wearing an empty-string `runId`\n *                 sentinel. `start` is the only transition out, so no verb has to\n *                 guard \"has this actually started?\" — `phase === \"idle\"` says it.\n *   - `running` — the run is live. Carries the host-minted `runId` and the\n *                 `RunCore` pipeline position + watchdog bookkeeping.\n *   - `stale`   — a soft \"no progress observed\" mark the consumer can set and\n *                 clear; still resumable (a `progress` clears it back to\n *                 `running`). Distinct from a fired deadline, which is terminal.\n *   - `done`    — every stage retired (or the single-shot `advance` landed).\n *   - `failed`  — terminal failure; the typed `failure` reason rides ONLY this\n *                 arm, so it is present iff `phase === \"failed\"` BY CONSTRUCTION —\n *                 there is no nullable side field to keep in sync.\n *\n * `runId` is the host-minted run identity, stamped at `start` (the machine never\n * mints — see the audit seed's \"run identity is host-minted\"). It rides every\n * started phase, but not `idle`.\n */\nexport type MonitoredRunState<Stage> =\n  | (RunCore<Stage> & { readonly phase: \"idle\" })\n  | (RunCore<Stage> & { readonly phase: \"running\"; readonly runId: string })\n  | (RunCore<Stage> & { readonly phase: \"stale\"; readonly runId: string })\n  | (RunCore<Stage> & { readonly phase: \"done\"; readonly runId: string })\n  | (RunCore<Stage> & {\n      readonly phase: \"failed\";\n      readonly runId: string;\n      readonly failure: RunFailure<Stage>;\n    });\n\n/**\n * The live (still-timed) phases — `running` or `stale`. The verbs narrow to this\n * before touching the watchdog bookkeeping (`runId` / `progressSeq`), so a\n * settled (`done` / `failed`) or never-started (`idle`) slice can never be bumped\n * — the narrow replaces the old `runId === \"\"` born-live guard.\n */\ntype LiveRun<Stage> = Extract<\n  MonitoredRunState<Stage>,\n  { readonly phase: \"running\" | \"stale\" }\n>;\n\n/**\n * The outcome a consumer reports to `advance`: the current stage either\n * succeeded (retire it, claim the next) or failed (terminate the run). Plain\n * data — the consumer parses its stage result at its own boundary and hands a\n * settled outcome here.\n */\nexport type StageResult =\n  | { readonly kind: \"ok\" }\n  | { readonly kind: \"fail\"; readonly error: unknown };\n\n// ===========================================================================\n// Cmd + Msg — re-exported from the composed bricks so consumers wire one import.\n// ===========================================================================\n\n/** The checkpoint-write Cmd, generic over the consumer's checkpoint value `V`. */\nexport type MonitoredRunCmd<V> = SnapshotWriteCmd<V>;\n\n/** The deadline Msg the safety alarm dispatches when the watchdog fires. */\nexport type MonitoredRunTimerMsg = DeadlineExceeded;\n\n/** Ports the consumer supplies to `handlers` — just the checkpoint store. */\nexport interface MonitoredRunPorts<V> {\n  /** Where periodic checkpoints are written (R2 / KV / DO sub-key / Map). */\n  readonly store: SnapshotStore<V>;\n}\n\n// ===========================================================================\n// Sub-id family. The safety alarm is keyed on `progressSeq` so a progress\n// event retires the old alarm and arms a new one (single-shot, re-armed by id\n// bump — the audit subs discipline).\n// ===========================================================================\n\nfunction safetyTimerId(runId: string, progressSeq: number): string {\n  return `monitored:safety:${runId}:${progressSeq}`;\n}\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build a monitored-run knob from `config`. `Stage` is the consumer's stage\n * identifier type; `V` is the consumer's checkpoint value type (what\n * `snapshotEvery` checkpoints). Returns the uniform L2 knob contract.\n *\n * No `rng` parameter: unlike `resilient-call`, nothing here jitters — the only\n * external inputs are time (an `at` / `atMs` parameter) and the consumer's\n * stage outcomes. The clock is read only inside the snapshot `handlers` port.\n */\nexport function createMonitoredRun<Stage, V = unknown>(\n  config: MonitoredRunConfig<Stage> = {},\n) {\n  const stages = config.stages ?? [];\n  const isPipeline = stages.length > 0;\n\n  // The stage-queue seam, bound once. Every stage status flip delegates to the\n  // `QueueAdapter` verbs (`wq.enqueue` / `wq.claim` / `wq.markDone`), so the\n  // `QueueItem<Stage>` shape stays insulated behind them.\n  const wq = queueAdapter<Stage>();\n\n  // The snapshot sub-knob is built only when `snapshotEvery` is configured;\n  // absence is `null` so the progress gate short-circuits to \"no checkpoint\".\n  // When present, the slice still carries a default SnapshotState so the shape\n  // is uniform across configs — the gate simply never records into it.\n  const snap =\n    config.snapshotEvery !== undefined\n      ? createSnapshot<V>({\n          every: config.snapshotEvery,\n          ...(config.snapshotKey !== undefined\n            ? { key: config.snapshotKey }\n            : {}),\n        })\n      : null;\n\n  // The snapshot knob to actually drive: `snap` when configured, else a single\n  // inert default (`every: 1`) bound ONCE here. Its `record` is never invoked\n  // (the progress gate short-circuits when `snap` is null), so the cadence value\n  // is immaterial — one shared stateless knob of pure functions stands in for\n  // the disabled-checkpoint case across init/boot/handlers.\n  const activeSnap = snap ?? createSnapshot<V>({ every: 1 });\n\n  /** The starting slice for a never-started run: the `idle` phase, no `runId`. */\n  function init(): MonitoredRunState<Stage> {\n    return {\n      phase: \"idle\",\n      stepStates: [],\n      startedAt: 0,\n      lastProgressAt: 0,\n      progressSeq: 0,\n      // A default snapshot slice even without the brick → uniform shape. When\n      // `snap` is null the inert `activeSnap` default supplies the slice; its\n      // `record` is never called, so the cadence value is immaterial.\n      snapshot: activeSnap.init(),\n    };\n  }\n\n  /**\n   * Seed the stage queue from the configured stages: every stage enqueued\n   * `pending`, then the first claimed `running`. `at` stamps the claim. PURE —\n   * the work-queue ops are pure array transforms; ids are positional (`stage:i`)\n   * so they are deterministic and replayable (no `crypto`, no `Math.random`).\n   */\n  function seedStages(at: number): readonly QueueItem<Stage>[] {\n    let queue: readonly QueueItem<Stage>[] = [];\n    stages.forEach((stage, i) => {\n      queue = wq.enqueue(queue, stage, at, `stage:${i}`).next;\n    });\n    // Claim the first stage as the running position. A non-empty pipeline always\n    // has a pending head here, so the claim succeeds.\n    const claimed = wq.claim(queue, at);\n    return claimed ? claimed.next : queue;\n  }\n\n  /** The current (running) stage item, or `undefined` for a single-shot run. */\n  function currentStage(\n    s: MonitoredRunState<Stage>,\n  ): QueueItem<Stage> | undefined {\n    return s.stepStates.find((i) => i.status === \"running\");\n  }\n\n  // === Verb: start =========================================================\n\n  /**\n   * Start (or restart) the run for `runId` at time `at`. Seeds the stage queue\n   * (if a pipeline) and enters `running` with the watchdog clock primed. Stamps\n   * `runId` from the host — the machine never mints (invariant: identity is\n   * host-minted, parsed at the boundary). PURE.\n   */\n  function start(\n    s: MonitoredRunState<Stage>,\n    runId: string,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    // Build the `running` arm explicitly rather than spreading `...s`: a restart\n    // from `failed` must NOT carry the old `failure` field forward (the `running`\n    // arm has none), and a start from `idle` has no `runId` to preserve. Only the\n    // snapshot slice threads through.\n    const next: MonitoredRunState<Stage> = {\n      phase: \"running\",\n      runId,\n      stepStates: isPipeline ? seedStages(at) : [],\n      startedAt: at,\n      lastProgressAt: at,\n      progressSeq: 0,\n      snapshot: s.snapshot,\n    };\n    return [next, []];\n  }\n\n  /**\n   * Bump the watchdog clock: set `lastProgressAt`/`progressSeq` so the safety\n   * alarm Sub id changes and the substrate re-arms a fresh deadline. Shared by\n   * `progress` and `advance`. PURE.\n   */\n  function bumpProgress(s: LiveRun<Stage>, at: number): LiveRun<Stage> {\n    return { ...s, lastProgressAt: at, progressSeq: s.progressSeq + 1 };\n  }\n\n  /**\n   * Account one progress unit to the snapshot slice (when the brick is\n   * configured), returning the new slice + any checkpoint Cmd. `payload` is the\n   * consumer's checkpoint value to persist. PURE — `snap.record` is pure, the\n   * write is realized only when the runtime performs the emitted Cmd.\n   */\n  function recordSnapshot(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (snap === null) return [s, []];\n    const [snapshot, cmds] = snap.record(s.snapshot, payload, at);\n    // `snap.record` only ever emits `SnapshotWriteCmd<V>` (its sole Cmd), but\n    // its signature widens to `readonly Cmd[]`. Narrow back to this knob's\n    // precise Cmd union so a consumer's host Cmd type can stay exact.\n    return [{ ...s, snapshot }, cmds as readonly MonitoredRunCmd<V>[]];\n  }\n\n  // === Verb: progress ======================================================\n\n  /**\n   * Record forward progress: bump the watchdog (re-arming the safety alarm),\n   * clear any `stale` mark back to `running`, and account a snapshot unit\n   * (emitting a checkpoint Cmd on a cadence hit). A no-op unless the run is live\n   * (`running` / `stale`) — a late progress event on a settled (`done` /\n   * `failed`) or never-started (`idle`) run is ignored. PURE.\n   */\n  function progress(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    const bumped: MonitoredRunState<Stage> = {\n      ...bumpProgress(s, at),\n      phase: \"running\",\n    };\n    return recordSnapshot(bumped, payload, at);\n  }\n\n  // === Verb: markStale =====================================================\n\n  /**\n   * Mark the run `stale` — a soft \"no progress observed\" signal the consumer\n   * raises WITHOUT the deadline having fired (e.g. an upstream heartbeat gap).\n   * Recoverable: the next `progress` flips it back to `running`. A no-op unless\n   * the run is currently `running` (a settled run cannot go stale). Does NOT\n   * touch `progressSeq` — going stale is not progress, so the armed deadline\n   * keeps counting toward the hard terminal. PURE.\n   */\n  function markStale(\n    s: MonitoredRunState<Stage>,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\") return [s, []];\n    return [{ ...s, phase: \"stale\" }, []];\n  }\n\n  // === Verb: advance =======================================================\n\n  /**\n   * Advance the pipeline on a stage outcome:\n   *\n   *   - `result.kind === \"fail\"` → terminate `failed { reason: \"stage\" }`,\n   *     carrying the failing stage index + error. No further stages run.\n   *   - `result.kind === \"ok\"`:\n   *       - single-shot run → finish to `done` (and force a final checkpoint\n   *         when checkpointing, so the last durable snapshot is the terminal\n   *         state).\n   *       - pipeline → retire the current stage (`markDoneOp`) and claim the\n   *         next (`claimNextOp`). If none remain, finish to `done`. The new\n   *         position survives eviction.\n   *\n   * An advance is itself a progress event, so it bumps the watchdog (re-arming\n   * the alarm at the new stage) and accounts a snapshot unit. A no-op on a\n   * settled (`done` / `failed`) or never-started (`idle`) run. PURE — `at` is the\n   * only clock, ids are positional.\n   */\n  function advance(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    result: StageResult,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n\n    // Stage failure → hard terminal. Carry the failing stage VALUE (stable),\n    // `undefined` for a single-shot run with no stage.\n    if (result.kind === \"fail\") {\n      const failed: MonitoredRunState<Stage> = {\n        ...s,\n        phase: \"failed\",\n        failure: {\n          reason: \"stage\",\n          stage: currentStage(s)?.input,\n          error: result.error,\n        },\n      };\n      return [failed, []];\n    }\n\n    // Success: bump the watchdog first (an advance is progress), then move the\n    // pipeline position.\n    const bumped = bumpProgress(s, at);\n\n    // Single-shot: one advance finishes the run.\n    if (!isPipeline) {\n      const done: MonitoredRunState<Stage> = { ...bumped, phase: \"done\" };\n      // Force a terminal checkpoint so the last durable snapshot is `done`,\n      // not whatever the cadence happened to land on.\n      return finishWithSnapshot(done, payload, at);\n    }\n\n    // Pipeline: retire the running stage, claim the next.\n    const current = currentStage(s);\n    const afterDone =\n      current !== undefined\n        ? wq.markDone(s.stepStates, current.id).next\n        : s.stepStates;\n    const claimed = wq.claim(afterDone, at);\n\n    if (claimed === null) {\n      // No more stages — the pipeline is complete.\n      const done: MonitoredRunState<Stage> = {\n        ...bumped,\n        phase: \"done\",\n        stepStates: afterDone,\n      };\n      return finishWithSnapshot(done, payload, at);\n    }\n\n    // Advance to the next stage — POSITION now points at the claimed item.\n    const moved: MonitoredRunState<Stage> = {\n      ...bumped,\n      stepStates: claimed.next,\n    };\n    return recordSnapshot(moved, payload, at);\n  }\n\n  /**\n   * Finish helper: force a terminal checkpoint when checkpointing is enabled\n   * (so the durable snapshot is the terminal state), else just settle. Shared\n   * by single-shot finish and pipeline completion. PURE.\n   */\n  function finishWithSnapshot(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (snap === null) return [s, []];\n    const [snapshot, cmds] = snap.force(s.snapshot, payload, at);\n    // Same narrowing as `recordSnapshot`: `snap.force` emits only the write Cmd.\n    return [{ ...s, snapshot }, cmds as readonly MonitoredRunCmd<V>[]];\n  }\n\n  // === Verb: onDeadline ====================================================\n\n  /**\n   * The safety alarm fired. Two outcomes by Sub-id match:\n   *\n   *   - the alarm matches the CURRENT `progressSeq` (no progress since it was\n   *     armed) → the run is wedged → terminate `failed { reason: \"deadline\" }`.\n   *   - the alarm matches an OLDER seq → a stale fire racing a progress event\n   *     that already re-armed the alarm → no-op (the substrate retired this id;\n   *     tolerate a fire still in flight defensively).\n   *\n   * A no-op on a settled run (its alarm was reconciled away; tolerate a stale\n   * fire) and on a NEVER-STARTED (`idle`) run (`subs` armed nothing for it, so\n   * any alarm reaching it is a rogue fire that must not un-start it). PURE —\n   * `msg.atMs` stamps the failure.\n   */\n  function onDeadline(\n    s: MonitoredRunState<Stage>,\n    msg: MonitoredRunTimerMsg,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    // Only a live (`running` / `stale`) run is watched. A settled (`done` /\n    // `failed`) run's alarm was reconciled away, and a never-started (`idle`) run\n    // — which has no host-minted `runId` and armed nothing — must not be\n    // un-started by a born-live/rogue fire. The phase narrow IS the guard the old\n    // `runId === \"\"` sentinel stood in for.\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    // Only the alarm armed against the current progressSeq is live. A bumped\n    // seq means progress re-armed it; an older fire is stale.\n    if (msg.id !== safetyTimerId(s.runId, s.progressSeq)) return [s, []];\n    const failed: MonitoredRunState<Stage> = {\n      ...s,\n      phase: \"failed\",\n      failure: { reason: \"deadline\", at: msg.atMs },\n    };\n    return [failed, []];\n  }\n\n  // === Verb: boot ==========================================================\n\n  /**\n   * Resume after a reload (cold wake). Re-seeds the watchdog clock to `at` so\n   * the safety alarm re-arms from NOW (the pre-crash `lastProgressAt` would\n   * immediately fire a deadline that already elapsed during downtime — a cold\n   * wake is not a no-progress wedge). Bumps `progressSeq` so the alarm gets a\n   * fresh id, and resets the snapshot cadence counter (un-checkpointed\n   * pre-crash progress is moot — recovery resumes from the last durable\n   * checkpoint). The pipeline POSITION (`stepStates`) is preserved untouched —\n   * that is the whole point of staging: resume at the same stage.\n   *\n   * A no-op on a settled (`done` / `failed`) or never-started (`idle`) run. Emits\n   * NO Cmd — re-emitting the current stage's outstanding effect is the CONSUMER's\n   * job (it knows the per-stage Cmd), the audit machine's `outstandingEffect(stage)`\n   * pattern. PURE.\n   */\n  function boot(\n    s: MonitoredRunState<Stage>,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    // `snap.boot` returns the reducer-cell shape `[SnapshotState, Cmd[]]`\n    // (uniform across every sibling knob); a boot emits no Cmd, so take only the\n    // slice. Assigning the tuple itself would put an ARRAY where a SnapshotState\n    // belongs — a type error AND a non-round-trippable slice.\n    const [bootedSnapshot] = activeSnap.boot(s.snapshot);\n    const reseeded: MonitoredRunState<Stage> = {\n      ...s,\n      phase: \"running\",\n      lastProgressAt: at,\n      progressSeq: s.progressSeq + 1,\n      snapshot: bootedSnapshot,\n      // Any stage left `running` mid-flight stays the running position; the\n      // queue is already correct (a single in-flight stage). resetRunningOp is\n      // NOT applied — unlike a work pool, a monitored run has exactly one\n      // in-flight stage and resuming it (not re-queuing it) is the correct\n      // cold-wake behavior.\n    };\n    return [reseeded, []];\n  }\n\n  // === Subs ================================================================\n\n  /**\n   * Pre-wired subscriptions: the no-progress safety deadline, armed only while\n   * the run is live (`running` / `stale`) AND a `deadlineMs` is configured. The\n   * Sub id is keyed on `progressSeq`, so every progress event retires the old\n   * alarm and the substrate arms a fresh one at the new `lastProgressAt +\n   * deadlineMs` — a self-rearming watchdog with no manual `clearTimeout`. A\n   * settled run desires no subs. Wire `subscribe: { deadline: subscribeDeadline }`.\n   *\n   * A NEVER-STARTED slice (`init()`) is its OWN `idle` phase, not a `running` run\n   * with an empty `runId`. The `phase !== \"running\" && phase !== \"stale\"` narrow\n   * therefore excludes it structurally — no separate `runId === \"\"` sentinel gate\n   * is needed. Were `idle` armed, it would fire a deadline at `0 + deadlineMs`\n   * (already in the past) and auto-fail a run that never began — the \"born live\"\n   * defect. `start` is the only transition out of `idle`, so the watchdog exists\n   * exactly once a real run is in flight.\n   */\n  function subs(s: MonitoredRunState<Stage>): readonly DeadlineSub[] {\n    if (config.deadlineMs === undefined) return [];\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [];\n    return [\n      deadlineSub(\n        safetyTimerId(s.runId, s.progressSeq),\n        s.lastProgressAt + config.deadlineMs,\n      ),\n    ];\n  }\n\n  // === Handlers ============================================================\n\n  /**\n   * Pre-wired interpret handler for the checkpoint write. Delegates wholesale to\n   * `../snapshot`'s `handlers` (which performs the `put` and routes Ok →\n   * `snapshot_saved` / Err → `snapshot_failed` via Railway — the write never\n   * rejects into the runtime). When checkpointing is disabled (`snapshotEvery`\n   * omitted), no `snapshot_write` Cmd is ever emitted, so the returned map is an\n   * inert no-op handler — kept for a uniform `handlers(ports)` call shape.\n   *\n   * Fold the `snapshot_saved` Msg back through this knob's `confirmSnapshot`\n   * verb to advance the durable watermark.\n   */\n  function handlers(\n    ports: MonitoredRunPorts<V>,\n  ): Interpret<\n    | SnapshotSavedMsg\n    | SnapshotFailedMsg\n    | SnapshotLoadedMsg<V>\n    | SnapshotLoadFailedMsg,\n    SnapshotWriteCmd<V> | SnapshotLoadCmd,\n    unknown\n  > {\n    return activeSnap.handlers({ store: ports.store });\n  }\n\n  /**\n   * Fold a confirmed checkpoint write into the slice — advances the snapshot\n   * watermark (forward-only). A no-op pass-through when checkpointing is\n   * disabled. PURE. Fold the `snapshot_saved` Msg here.\n   */\n  function confirmSnapshot(\n    s: MonitoredRunState<Stage>,\n    msg: SnapshotSavedMsg,\n  ): MonitoredRunState<Stage> {\n    if (snap === null) return s;\n    // `snap.confirm` returns the reducer-cell shape `[SnapshotState, Cmd[]]`\n    // (an ack emits nothing). Take only the slice — folding the whole tuple into\n    // `snapshot` would store an ARRAY where a SnapshotState belongs (a type error\n    // and a non-round-trippable slice).\n    const [confirmed] = snap.confirm(s.snapshot, msg);\n    return { ...s, snapshot: confirmed };\n  }\n\n  return {\n    init,\n    start,\n    progress,\n    markStale,\n    advance,\n    onDeadline,\n    boot,\n    confirmSnapshot,\n    subs,\n    handlers,\n  };\n}\n\n/**\n * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the\n * slice lives at `state.run`. Convenience for the common single-slice host;\n * hosts with a differently-named field spread by hand. PURE — a thin record\n * rebuild, no clock / RNG.\n */\nexport function liftRun<\n  S extends { run: MonitoredRunState<Stage> },\n  Stage,\n  C extends Cmd,\n>(\n  state: S,\n  [slice, cmds]: readonly [MonitoredRunState<Stage>, readonly C[]],\n): readonly [S, readonly C[]] {\n  return [{ ...state, run: slice }, cmds];\n}\n\n/**\n * Re-export the deadline Sub primitives so consumers (and tests) wire one\n * import: `subscribeDeadline` is the `subscribe` cell, `deadlineSub` builds the\n * Sub literal this knob's `subs` emits.\n */\nexport { subscribeDeadline, deadlineSub };\nexport type {\n  DeadlineSub,\n  DeadlineExceeded,\n  SnapshotSavedMsg,\n  SnapshotWriteCmd,\n};\n"]}

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

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

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

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

package/dist/{chunk-C6QC273X.js → chunk-SSHDBOXF.js}

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

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

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

package/dist/{chunk-SK5JGUY7.js → chunk-TWDHNIY6.js}

@@ -1,5 +1,5 @@
 import { MsgType } from './chunk-JELSZN25.js';
-import { tryInterpret } from './chunk-BP2R7TPP.js';
+import { tryInterpret } from './chunk-D4NJBQAH.js';
 
 // src/token-refresh/index.ts
 function initTokenRefresh() {
@@ -57,5 +57,5 @@ function createTokenRefresh(config = {}) {
 }
 
 export { createTokenRefresh, initTokenRefresh, refreshTokenCmd, tokenRefreshFailedMsg, tokenRefreshedMsg };
-//# sourceMappingURL=chunk-SK5JGUY7.js.map
-//# sourceMappingURL=chunk-SK5JGUY7.js.map
+//# sourceMappingURL=chunk-TWDHNIY6.js.map
+//# sourceMappingURL=chunk-TWDHNIY6.js.map

package/dist/{chunk-SK5JGUY7.js.map → chunk-TWDHNIY6.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/token-refresh/index.ts"],"names":[],"mappings":";;;;AAkJO,SAAS,gBAAA,GAA+B;AAC7C,EAAA,OAAO,EAAE,KAAA,EAAO,IAAA,EAAM,KAAA,EAAO,KAAA,EAAM;AACrC;AAYO,SAAS,eAAA,GAAmC;AACjD,EAAA,OAAO,EAAE,MAAM,eAAA,EAAgB;AACjC;AAaO,SAAS,kBAAkB,KAAA,EAAiC;AACjE,EAAA,OAAO,EAAE,IAAA,EAAM,OAAA,CAAQ,cAAA,EAAgB,KAAA,EAAM;AAC/C;AAgBO,SAAS,sBAAsB,KAAA,EAAuC;AAC3E,EAAA,OAAO,EAAE,IAAA,EAAM,OAAA,CAAQ,kBAAA,EAAoB,KAAA,EAAM;AACnD;AA0BO,SAAS,kBAAA,CAAmB,MAAA,GAA6B,EAAC,EAAG;AAIlE,EAAA,MAAM,MAAA,GACJ,OAAO,MAAA,KAAW,MAAA,IAAa,OAAO,MAAA,GAAS,CAAA,GAAI,OAAO,MAAA,GAAS,CAAA;AAsBrE,EAAA,SAAS,YAAA,CAAa,OAAmB,EAAA,EAAqB;AAC5D,IAAA,IAAI,KAAA,CAAM,KAAA,KAAU,IAAA,EAAM,OAAO,IAAA;AACjC,IAAA,IAAI,KAAA,CAAM,OAAO,OAAO,IAAA;AAKxB,IAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,MAAM,KAAA,CAAM,SAAS,GAAG,OAAO,IAAA;AACpD,IAAA,OAAO,EAAA,IAAM,KAAA,CAAM,KAAA,CAAM,SAAA,GAAY,MAAA;AAAA,EACvC;AAcA,EAAA,SAAS,MAAM,KAAA,EAA+B;AAC5C,IAAA,IAAI,KAAA,CAAM,OAAO,OAAO,KAAA;AACxB,IAAA,OAAO,EAAE,GAAG,KAAA,EAAO,KAAA,EAAO,IAAA,EAAK;AAAA,EACjC;AAmBA,EAAA,SAAS,SAAA,CAAU,OAAmB,KAAA,EAA0B;AAC9D,IAAA,MAAM,UAAA,GAAoB,MAAA,CAAO,EAAA,CAAG,KAAA,CAAM,SAAA,EAAW,EAAE,CAAA,GACnD,EAAE,GAAG,KAAA,EAAO,SAAA,EAAW,CAAA,EAAE,GACzB,KAAA;AACJ,IAAA,OAAO,EAAE,GAAG,KAAA,EAAO,KAAA,EAAO,UAAA,EAAY,OAAO,KAAA,EAAM;AAAA,EACrD;AAgBA,EAAA,SAAS,WAAA,CACP,OACA,EAAA,EACuC;AACvC,IAAA,IAAI,YAAA,CAAa,KAAA,EAAO,EAAE,CAAA,EAAG;AAC3B,MAAA,OAAO,CAAC,KAAA,EAAO,CAAC,eAAA,EAAiB,CAAC,CAAA;AAAA,IACpC;AACA,IAAA,OAAO,CAAC,KAAA,EAAO,EAAE,CAAA;AAAA,EACnB;AAgBA,EAAA,SAAS,SACP,KAAA,EACsD;AACtD,IAAA,OAAO;AAAA,MACL,aAAA,EAAe,YAAA;AAAA,QAMb,MAAM,MAAM,OAAA,EAAQ;AAAA,QACpB,CAAC,KAAA,KAAU,iBAAA,CAAkB,KAAK,CAAA;AAAA,QAClC,CAAC,KAAA,KAAU,qBAAA,CAAsB,KAAK;AAAA;AACxC,KACF;AAAA,EACF;AAEA,EAAA,OAAO;AAAA;AAAA,IAEL,IAAA,EAAM,gBAAA;AAAA,IACN,YAAA;AAAA,IACA,KAAA;AAAA,IACA,SAAA;AAAA,IACA,WAAA;AAAA,IACA;AAAA,GACF;AACF","file":"chunk-SK5JGUY7.js","sourcesContent":["/**\n * @demlik/tea/token-refresh — a credential's lifecycle as pure state + verbs,\n * with the actual token fetch deferred to a single injected port.\n *\n * This is the L1 brick `authed-call` (#10 in the composition specs) stacks on:\n * a token slice `{ token, stale }` plus pure transitions that decide *when* a\n * credential must be re-minted, and one `handlers(ports)` splice that performs\n * the re-mint. It follows the uniform knob contract every composition wears —\n * `createTokenRefresh(config) → { init, <verbs>, handlers }` — so a consumer\n * spreads ~3 hooks into their machine instead of hand-wiring the refresh dance.\n *\n * It is a LEAF module in the same mold as `@demlik/tea/retry-backoff`: it\n * depends only on the core (`../index`), never on a sibling brick. The two\n * non-negotiables of every knob hold here by construction:\n *\n *   - **Durable** — the token slice is plain JSON-serializable data, so it\n *     survives a Durable Object eviction / page reload. A rehydrated machine\n *     resumes knowing exactly which token it holds and whether it is stale.\n *   - **Replayable** — every transition is a pure verb returning\n *     `readonly [State, Cmd[]]`. No verb reads the wall clock or performs I/O,\n *     so `replay` reconstructs the slice exactly. Time enters ONLY as an `at`\n *     parameter the caller stamps; the network fetch enters ONLY at the\n *     `handlers` boundary. This keeps the substrate's purity invariants intact\n *     (invariant 2: pure transitions; invariant 4: I/O is an effect, not a\n *     reducer body).\n *\n * ## The staleness model — two independent reasons to refresh\n *\n * A token becomes unusable for two unrelated reasons, and the slice tracks both\n * without conflating them:\n *\n *   1. **Expiry** — the token has a known `expiresAt` (epoch ms). It is \"near\n *      expiry\" once `at >= expiresAt - skewMs`. The `skewMs` skew refreshes\n *      *ahead* of the hard deadline so an in-flight call never races a token\n *      that expires mid-request. This is the proactive, time-driven reason and\n *      is computed purely from the injected `at` — no clock in the verb.\n *\n *   2. **Server rejection (401)** — the server rejected a request the client\n *      believed was still valid (clock skew, a server-side revocation, an early\n *      rotation). `on401` flips a `stale` flag regardless of `expiresAt`. This\n *      is the reactive reason: the client's belief about validity was wrong, so\n *      the next `needsRefresh` returns true even though the clock says the\n *      token is fine.\n *\n * `needsRefresh` is the union of the two (plus \"no token at all\"). One source\n * of truth for \"should I fetch a fresh credential before the next call?\", read\n * by the consumer's reducer at the call boundary.\n *\n * Typical wiring (inside a consumer machine):\n *\n *   const tr = createTokenRefresh({ skewMs: 30_000 });\n *\n *   // in init:\n *   init: (loaded) => [loaded ?? { auth: tr.init() }, Cmd.none],\n *\n *   // in a reducer cell that is about to make an authed call:\n *   before_call: (s, msg) => {\n *     const [auth, cmds] = tr.ensureFresh(s.auth, msg.at);\n *     return [{ ...s, auth }, cmds]; // emits a refresh Cmd iff a refresh is due\n *   },\n *\n *   // on a 401 from a guarded call:\n *   got_401: (s) => [{ ...s, auth: tr.on401(s.auth) }, []],\n *\n *   // when the refresh port resolves:\n *   token_refreshed: (s, msg) => [{ ...s, auth: tr.refreshed(s.auth, msg.token) }, []],\n *\n *   // splice the I/O:\n *   interpret: { ...tr.handlers({ refresh: () => mySdk.mintToken() }) },\n *\n * NOT a substrate primitive: from `../index` it reuses only the `Cmd` /\n * `Interpret` types and the `tryInterpret` Railway helper (a runtime function,\n * not a type) that every effectful brick uses — and no sibling brick. It is a\n * leaf utility consumers reach via the `@demlik/tea/token-refresh` subpath.\n */\n\nimport { type Cmd, type Interpret, tryInterpret } from \"../index\";\nimport { MsgType } from \"../protocol\";\n\n/**\n * A minted credential: the opaque `value` to send on the wire, and the absolute\n * `expiresAt` (epoch milliseconds — the `Date.now()` scale) the issuer stamped\n * it with. Both fields are plain data so a `Token` is trivially serializable\n * into a consumer's `Store<S>`.\n *\n * `value` is `string` because that is the universal shape of a bearer token /\n * API key / session cookie on the wire. A consumer whose refresh port yields a\n * richer object can JSON-encode it into `value`, or keep this module's slice as\n * the \"is it fresh?\" gate and hold the richer object elsewhere in their Model.\n */\nexport interface Token {\n  /** The opaque credential to present on each request (bearer token, API key). */\n  readonly value: string;\n  /** Absolute expiry instant, epoch milliseconds. The `Date.now()` scale. */\n  readonly expiresAt: number;\n}\n\n/**\n * Pure configuration — the knob's only field. Carries no mutable state;\n * `TokenState` does. One config is shared across all the refreshes of one\n * logical credential (often a module-scope const).\n */\nexport interface TokenRefreshConfig {\n  /**\n   * Refresh-ahead skew, in milliseconds. A token is treated as needing a\n   * refresh once `at >= expiresAt - skewMs`, i.e. `skewMs` BEFORE its hard\n   * expiry. This buys headroom so a call that starts just under the wire never\n   * races a token that lapses mid-flight, and absorbs small client/server clock\n   * disagreement. `0` means \"refresh exactly at expiry\"; a negative value is\n   * clamped to `0` (a skew that pushes the trigger past expiry is meaningless).\n   *\n   * @default 0\n   */\n  readonly skewMs?: number;\n}\n\n/**\n * The token slice this knob owns — the Model field a consumer spreads in via\n * `init()`. A two-field record rather than a phase union because the two\n * dimensions are orthogonal: a token can be present-and-fresh, present-but-stale\n * (a 401 came back), absent, or absent-and-stale (cleared after a failed\n * refresh). Every combination is meaningful, so neither field implies the\n * other's value and a discriminated union would only manufacture impossible\n * arms.\n *\n *   - `token` — the currently held credential, or `null` when none has been\n *     minted yet (fresh boot) or the last refresh failed.\n *   - `stale` — set by `on401` when the server rejected a request the client\n *     believed valid. Forces the next `needsRefresh` to true regardless of\n *     `expiresAt`; cleared by `refreshed` once a new credential lands.\n *\n * Both fields `readonly` so the whole slice threads safely through a pure\n * reducer and serializes into a `Store<S>`.\n */\nexport interface TokenState {\n  /** The held credential, or `null` if none is available (boot / failed refresh). */\n  readonly token: Token | null;\n  /** Whether a 401 has marked the held token unusable ahead of its `expiresAt`. */\n  readonly stale: boolean;\n}\n\n/**\n * The starting slice: no token held, not stale. The first `needsRefresh` after\n * this returns `true` (no token), so a consumer's first guarded call mints a\n * credential before going out.\n */\nexport function initTokenRefresh(): TokenState {\n  return { token: null, stale: false };\n}\n\n/**\n * The Cmd this knob emits to ask the runtime to mint a fresh token. Plain data\n * (no closure — invariant 1) carrying nothing: the refresh port takes no input,\n * and the slice the result installs is read off the follow-up Msg, not this\n * Cmd. The consumer unions this into their machine's Cmd type and lets\n * `handlers` interpret it.\n */\nexport interface RefreshTokenCmd extends Cmd<\"refresh_token\"> {}\n\n/** Construct a `refresh_token` Cmd. */\nexport function refreshTokenCmd(): RefreshTokenCmd {\n  return { type: \"refresh_token\" };\n}\n\n/**\n * The Msg the refresh port dispatches on success — carries the freshly minted\n * `Token`. The consumer unions this into their Msg type and handles it by\n * folding `refreshed(state, msg.token)` into the slice.\n */\nexport interface TokenRefreshedMsg {\n  readonly type: typeof MsgType.TokenRefreshed;\n  readonly token: Token;\n}\n\n/** Construct a `token_refreshed` Msg carrying the new token. */\nexport function tokenRefreshedMsg(token: Token): TokenRefreshedMsg {\n  return { type: MsgType.TokenRefreshed, token };\n}\n\n/**\n * The Msg the refresh port dispatches on failure — carries the rejection so the\n * consumer's reducer can decide whether to back off, surface an error, or give\n * up (errors are data: it is dispatched, never swallowed). The slice itself is\n * left untouched by a failed refresh — the held token (if any) stays held and\n * stale stays set, so the consumer can retry; clearing it is the consumer's\n * policy, expressed in their reducer.\n */\nexport interface TokenRefreshFailedMsg {\n  readonly type: typeof MsgType.TokenRefreshFailed;\n  readonly error: unknown;\n}\n\n/** Construct a `token_refresh_failed` Msg carrying the rejection. */\nexport function tokenRefreshFailedMsg(error: unknown): TokenRefreshFailedMsg {\n  return { type: MsgType.TokenRefreshFailed, error };\n}\n\n/** The two Msgs the refresh port can produce. Union for a consumer's Msg type. */\nexport type TokenRefreshMsg = TokenRefreshedMsg | TokenRefreshFailedMsg;\n\n/** The ports this knob's `handlers` splice needs — the single refresh DI seam. */\nexport interface TokenRefreshPorts {\n  /**\n   * Mint a fresh credential. Called ONLY from the `refresh_token` interpret\n   * handler — never from a verb — so the network I/O and any clock the issuer\n   * reads stay at the effect boundary. May reject; the rejection is routed to\n   * `token_refresh_failed` (errors are data), never thrown into the runtime.\n   */\n  readonly refresh: () => Promise<Token>;\n}\n\n/**\n * The knob: hand it a config, get back the slice initializer, the pure verbs,\n * and the `handlers` splice. Mirrors every L2 composition's uniform contract so\n * the call sites read identically across bricks.\n *\n * @example\n *   const tr = createTokenRefresh({ skewMs: 30_000 });\n *   const s0 = tr.init();\n *   const [s1, cmds] = tr.ensureFresh(s0, Date.now()); // cmds = [refreshTokenCmd()]\n */\nexport function createTokenRefresh(config: TokenRefreshConfig = {}) {\n  // Clamp once at construction: a negative skew would push the refresh trigger\n  // PAST expiry, which inverts the knob's intent (\"refresh ahead\"). NaN (a\n  // miswired config) collapses to 0 so `needsRefresh`'s comparison stays total.\n  const skewMs =\n    config.skewMs !== undefined && config.skewMs > 0 ? config.skewMs : 0;\n\n  /**\n   * Whether the held token must be refreshed before the next guarded call, at\n   * the injected instant `at` (epoch ms). PURE — reads only, no clock, no\n   * mutation. True iff ANY of:\n   *\n   *   - no token is held (`token === null`) — nothing to present;\n   *   - the token was marked `stale` by a 401 — the server disagrees with the\n   *     client's belief that it is valid;\n   *   - the token's `expiresAt` is not a finite number (`NaN` / `±Infinity`) —\n   *     a miswired issuer or a corrupted slice; we cannot reason about when it\n   *     lapses, so we fail SAFE toward minting a fresh one rather than letting\n   *     `at >= NaN` (always `false`) or `at >= Infinity` (always `false`) mask\n   *     a broken expiry as \"fresh forever\";\n   *   - the token is at or past its skewed expiry (`at >= expiresAt - skewMs`)\n   *     — the proactive refresh-ahead window has opened.\n   *\n   * The expiry cutoff is half-open (`>=`), matching the window edges in\n   * `rate-limit` / `cache` / `circuit-breaker`: a token minted to expire at `t`\n   * with zero skew is considered due at exactly `t`.\n   */\n  function needsRefresh(state: TokenState, at: number): boolean {\n    if (state.token === null) return true;\n    if (state.stale) return true;\n    // Non-finite expiry (NaN/±Infinity) can never be compared into a \"due\"\n    // verdict — `at >= NaN` and `at >= Infinity` are both `false`, which would\n    // pin a broken token as fresh forever. Fail safe: treat it as needing a\n    // refresh so the next call mints a credential with a real deadline.\n    if (!Number.isFinite(state.token.expiresAt)) return true;\n    return at >= state.token.expiresAt - skewMs;\n  }\n\n  /**\n   * Mark the held token unusable because a request the client believed valid\n   * came back 401. PURE — returns a new slice; the input is never mutated.\n   * Sets `stale` regardless of `expiresAt`, so the next `needsRefresh` returns\n   * true even when the clock still says the token is fine. The token VALUE is\n   * kept (not nulled) — it is the consumer's last-known credential until a\n   * refresh replaces it, and keeping it lets observability show what was\n   * rejected.\n   *\n   * Idempotent: a second 401 on an already-stale slice returns the same shape.\n   * A 401 with no token held is a no-op (already needs a refresh).\n   */\n  function on401(state: TokenState): TokenState {\n    if (state.stale) return state;\n    return { ...state, stale: true };\n  }\n\n  /**\n   * Install a freshly minted `token`, clearing `stale`. PURE — returns a new\n   * slice; the input is never mutated. This is the fold for the\n   * `token_refreshed` Msg: after it, `needsRefresh(state, at)` is false for any\n   * `at` below the new skewed expiry, and the stale flag is gone (the new\n   * credential supersedes whatever the 401 rejected).\n   *\n   * This is the slice's WRITE boundary for a credential, so it is where the\n   * durability invariant is paid for: it normalizes a negative-zero `expiresAt`\n   * to `+0` before the value enters the slice. `-0` is the one finite double\n   * JSON cannot round-trip — `JSON.stringify(-0)` is `\"0\"`, which parses back as\n   * `+0`, so a slice carrying `-0` would diverge from its persisted form across\n   * a Durable Object eviction / page reload (invariant: the boundary parses, the\n   * core trusts). `-0` and `+0` denote the same epoch-ms instant, so collapsing\n   * them loses no information and makes the un-round-trippable state\n   * unrepresentable in the slice by construction.\n   */\n  function refreshed(state: TokenState, token: Token): TokenState {\n    const normalized: Token = Object.is(token.expiresAt, -0)\n      ? { ...token, expiresAt: 0 }\n      : token;\n    return { ...state, token: normalized, stale: false };\n  }\n\n  /**\n   * The verb a consumer calls at the call boundary: \"make sure I have a fresh\n   * credential before the next request.\" PURE — returns `[next, cmds]`. When a\n   * refresh is due (`needsRefresh(state, at)`), emits a single `refresh_token`\n   * Cmd; otherwise emits none. The slice is returned UNCHANGED in both branches\n   * — the refresh itself is async and lands later via `refreshed`, so there is\n   * no in-flight phase to record here. (A consumer that wants single-flight —\n   * \"don't fire a second refresh while one is pending\" — layers that in their\n   * own reducer, e.g. by tracking a pending flag; this brick stays minimal and\n   * lets the consumer own that policy.)\n   *\n   * The `at` is the caller's stamped clock reading (epoch ms), never read here —\n   * keeping the verb pure and `replay`-able.\n   */\n  function ensureFresh(\n    state: TokenState,\n    at: number,\n  ): readonly [TokenState, readonly Cmd[]] {\n    if (needsRefresh(state, at)) {\n      return [state, [refreshTokenCmd()]];\n    }\n    return [state, []];\n  }\n\n  /**\n   * The interpret splice: wraps the injected `refresh` port and routes its\n   * Ok/Err to `token_refreshed` / `token_refresh_failed` Msgs via the core's\n   * `tryInterpret` Railway helper. Spread the result into a consumer's\n   * `interpret` map:\n   *\n   *   interpret: { ...other, ...tr.handlers({ refresh: () => sdk.mintToken() }) }\n   *\n   * The port is the ONLY place the network (and any clock the issuer reads) is\n   * touched — every verb above stays pure. `tryInterpret` guarantees the\n   * handler never rejects: a port rejection becomes a `token_refresh_failed`\n   * Msg (errors are data), so the runtime's dispatch loop is never poisoned by\n   * an unhandled rejection.\n   */\n  function handlers(\n    ports: TokenRefreshPorts,\n  ): Interpret<TokenRefreshMsg, RefreshTokenCmd, unknown> {\n    return {\n      refresh_token: tryInterpret<\n        RefreshTokenCmd,\n        Token,\n        TokenRefreshMsg,\n        unknown\n      >(\n        () => ports.refresh(),\n        (token) => tokenRefreshedMsg(token),\n        (error) => tokenRefreshFailedMsg(error),\n      ),\n    };\n  }\n\n  return {\n    /** The slice initializer — spread into the consumer's `init`. */\n    init: initTokenRefresh,\n    needsRefresh,\n    on401,\n    refreshed,\n    ensureFresh,\n    handlers,\n  };\n}\n\n/** The shape `createTokenRefresh` returns — useful for typing a held knob. */\nexport type TokenRefresh = ReturnType<typeof createTokenRefresh>;\n"]}
+{"version":3,"sources":["../src/token-refresh/index.ts"],"names":[],"mappings":";;;;AAkJO,SAAS,gBAAA,GAA+B;AAC7C,EAAA,OAAO,EAAE,KAAA,EAAO,IAAA,EAAM,KAAA,EAAO,KAAA,EAAM;AACrC;AAYO,SAAS,eAAA,GAAmC;AACjD,EAAA,OAAO,EAAE,MAAM,eAAA,EAAgB;AACjC;AAaO,SAAS,kBAAkB,KAAA,EAAiC;AACjE,EAAA,OAAO,EAAE,IAAA,EAAM,OAAA,CAAQ,cAAA,EAAgB,KAAA,EAAM;AAC/C;AAgBO,SAAS,sBAAsB,KAAA,EAAuC;AAC3E,EAAA,OAAO,EAAE,IAAA,EAAM,OAAA,CAAQ,kBAAA,EAAoB,KAAA,EAAM;AACnD;AA0BO,SAAS,kBAAA,CAAmB,MAAA,GAA6B,EAAC,EAAG;AAIlE,EAAA,MAAM,MAAA,GACJ,OAAO,MAAA,KAAW,MAAA,IAAa,OAAO,MAAA,GAAS,CAAA,GAAI,OAAO,MAAA,GAAS,CAAA;AAsBrE,EAAA,SAAS,YAAA,CAAa,OAAmB,EAAA,EAAqB;AAC5D,IAAA,IAAI,KAAA,CAAM,KAAA,KAAU,IAAA,EAAM,OAAO,IAAA;AACjC,IAAA,IAAI,KAAA,CAAM,OAAO,OAAO,IAAA;AAKxB,IAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,MAAM,KAAA,CAAM,SAAS,GAAG,OAAO,IAAA;AACpD,IAAA,OAAO,EAAA,IAAM,KAAA,CAAM,KAAA,CAAM,SAAA,GAAY,MAAA;AAAA,EACvC;AAcA,EAAA,SAAS,MAAM,KAAA,EAA+B;AAC5C,IAAA,IAAI,KAAA,CAAM,OAAO,OAAO,KAAA;AACxB,IAAA,OAAO,EAAE,GAAG,KAAA,EAAO,KAAA,EAAO,IAAA,EAAK;AAAA,EACjC;AAmBA,EAAA,SAAS,SAAA,CAAU,OAAmB,KAAA,EAA0B;AAC9D,IAAA,MAAM,UAAA,GAAoB,MAAA,CAAO,EAAA,CAAG,KAAA,CAAM,SAAA,EAAW,EAAE,CAAA,GACnD,EAAE,GAAG,KAAA,EAAO,SAAA,EAAW,CAAA,EAAE,GACzB,KAAA;AACJ,IAAA,OAAO,EAAE,GAAG,KAAA,EAAO,KAAA,EAAO,UAAA,EAAY,OAAO,KAAA,EAAM;AAAA,EACrD;AAgBA,EAAA,SAAS,WAAA,CACP,OACA,EAAA,EACuC;AACvC,IAAA,IAAI,YAAA,CAAa,KAAA,EAAO,EAAE,CAAA,EAAG;AAC3B,MAAA,OAAO,CAAC,KAAA,EAAO,CAAC,eAAA,EAAiB,CAAC,CAAA;AAAA,IACpC;AACA,IAAA,OAAO,CAAC,KAAA,EAAO,EAAE,CAAA;AAAA,EACnB;AAgBA,EAAA,SAAS,SACP,KAAA,EACsD;AACtD,IAAA,OAAO;AAAA,MACL,aAAA,EAAe,YAAA;AAAA,QAMb,MAAM,MAAM,OAAA,EAAQ;AAAA,QACpB,CAAC,KAAA,KAAU,iBAAA,CAAkB,KAAK,CAAA;AAAA,QAClC,CAAC,KAAA,KAAU,qBAAA,CAAsB,KAAK;AAAA;AACxC,KACF;AAAA,EACF;AAEA,EAAA,OAAO;AAAA;AAAA,IAEL,IAAA,EAAM,gBAAA;AAAA,IACN,YAAA;AAAA,IACA,KAAA;AAAA,IACA,SAAA;AAAA,IACA,WAAA;AAAA,IACA;AAAA,GACF;AACF","file":"chunk-TWDHNIY6.js","sourcesContent":["/**\n * @demlik/tea/token-refresh — a credential's lifecycle as pure state + verbs,\n * with the actual token fetch deferred to a single injected port.\n *\n * This is the L1 brick `authed-call` (#10 in the composition specs) stacks on:\n * a token slice `{ token, stale }` plus pure transitions that decide *when* a\n * credential must be re-minted, and one `handlers(ports)` splice that performs\n * the re-mint. It follows the uniform knob contract every composition wears —\n * `createTokenRefresh(config) → { init, <verbs>, handlers }` — so a consumer\n * spreads ~3 hooks into their machine instead of hand-wiring the refresh dance.\n *\n * It is a LEAF module in the same mold as `@demlik/tea/retry-backoff`: it\n * depends only on the core (`../index`), never on a sibling brick. The two\n * non-negotiables of every knob hold here by construction:\n *\n *   - **Durable** — the token slice is plain JSON-serializable data, so it\n *     survives a Durable Object eviction / page reload. A rehydrated machine\n *     resumes knowing exactly which token it holds and whether it is stale.\n *   - **Replayable** — every transition is a pure verb returning\n *     `readonly [State, Cmd[]]`. No verb reads the wall clock or performs I/O,\n *     so `replay` reconstructs the slice exactly. Time enters ONLY as an `at`\n *     parameter the caller stamps; the network fetch enters ONLY at the\n *     `handlers` boundary. This keeps the substrate's purity invariants intact\n *     (invariant 2: pure transitions; invariant 4: I/O is an effect, not a\n *     reducer body).\n *\n * ## The staleness model — two independent reasons to refresh\n *\n * A token becomes unusable for two unrelated reasons, and the slice tracks both\n * without conflating them:\n *\n *   1. **Expiry** — the token has a known `expiresAt` (epoch ms). It is \"near\n *      expiry\" once `at >= expiresAt - skewMs`. The `skewMs` skew refreshes\n *      *ahead* of the hard deadline so an in-flight call never races a token\n *      that expires mid-request. This is the proactive, time-driven reason and\n *      is computed purely from the injected `at` — no clock in the verb.\n *\n *   2. **Server rejection (401)** — the server rejected a request the client\n *      believed was still valid (clock skew, a server-side revocation, an early\n *      rotation). `on401` flips a `stale` flag regardless of `expiresAt`. This\n *      is the reactive reason: the client's belief about validity was wrong, so\n *      the next `needsRefresh` returns true even though the clock says the\n *      token is fine.\n *\n * `needsRefresh` is the union of the two (plus \"no token at all\"). One source\n * of truth for \"should I fetch a fresh credential before the next call?\", read\n * by the consumer's reducer at the call boundary.\n *\n * Typical wiring (inside a consumer machine):\n *\n *   const tr = createTokenRefresh({ skewMs: 30_000 });\n *\n *   // in init:\n *   init: (loaded) => [loaded ?? { auth: tr.init() }, Cmd.none],\n *\n *   // in a reducer cell that is about to make an authed call:\n *   before_call: (s, msg) => {\n *     const [auth, cmds] = tr.ensureFresh(s.auth, msg.at);\n *     return [{ ...s, auth }, cmds]; // emits a refresh Cmd iff a refresh is due\n *   },\n *\n *   // on a 401 from a guarded call:\n *   got_401: (s) => [{ ...s, auth: tr.on401(s.auth) }, []],\n *\n *   // when the refresh port resolves:\n *   token_refreshed: (s, msg) => [{ ...s, auth: tr.refreshed(s.auth, msg.token) }, []],\n *\n *   // splice the I/O:\n *   interpret: { ...tr.handlers({ refresh: () => mySdk.mintToken() }) },\n *\n * NOT a substrate primitive: from `../index` it reuses only the `Cmd` /\n * `Interpret` types and the `tryInterpret` Railway helper (a runtime function,\n * not a type) that every effectful brick uses — and no sibling brick. It is a\n * leaf utility consumers reach via the `@demlik/tea/token-refresh` subpath.\n */\n\nimport { type Cmd, type Interpret, tryInterpret } from \"../index\";\nimport { MsgType } from \"../protocol\";\n\n/**\n * A minted credential: the opaque `value` to send on the wire, and the absolute\n * `expiresAt` (epoch milliseconds — the `Date.now()` scale) the issuer stamped\n * it with. Both fields are plain data so a `Token` is trivially serializable\n * into a consumer's `Store<S>`.\n *\n * `value` is `string` because that is the universal shape of a bearer token /\n * API key / session cookie on the wire. A consumer whose refresh port yields a\n * richer object can JSON-encode it into `value`, or keep this module's slice as\n * the \"is it fresh?\" gate and hold the richer object elsewhere in their Model.\n */\nexport interface Token {\n  /** The opaque credential to present on each request (bearer token, API key). */\n  readonly value: string;\n  /** Absolute expiry instant, epoch milliseconds. The `Date.now()` scale. */\n  readonly expiresAt: number;\n}\n\n/**\n * Pure configuration — the knob's only field. Carries no mutable state;\n * `TokenState` does. One config is shared across all the refreshes of one\n * logical credential (often a module-scope const).\n */\nexport interface TokenRefreshConfig {\n  /**\n   * Refresh-ahead skew, in milliseconds. A token is treated as needing a\n   * refresh once `at >= expiresAt - skewMs`, i.e. `skewMs` BEFORE its hard\n   * expiry. This buys headroom so a call that starts just under the wire never\n   * races a token that lapses mid-flight, and absorbs small client/server clock\n   * disagreement. `0` means \"refresh exactly at expiry\"; a negative value is\n   * clamped to `0` (a skew that pushes the trigger past expiry is meaningless).\n   *\n   * @default 0\n   */\n  readonly skewMs?: number;\n}\n\n/**\n * The token slice this knob owns — the Model field a consumer spreads in via\n * `init()`. A two-field record rather than a phase union because the two\n * dimensions are orthogonal: a token can be present-and-fresh, present-but-stale\n * (a 401 came back), absent, or absent-and-stale (cleared after a failed\n * refresh). Every combination is meaningful, so neither field implies the\n * other's value and a discriminated union would only manufacture impossible\n * arms.\n *\n *   - `token` — the currently held credential, or `null` when none has been\n *     minted yet (fresh boot) or the last refresh failed.\n *   - `stale` — set by `on401` when the server rejected a request the client\n *     believed valid. Forces the next `needsRefresh` to true regardless of\n *     `expiresAt`; cleared by `refreshed` once a new credential lands.\n *\n * Both fields `readonly` so the whole slice threads safely through a pure\n * reducer and serializes into a `Store<S>`.\n */\nexport interface TokenState {\n  /** The held credential, or `null` if none is available (boot / failed refresh). */\n  readonly token: Token | null;\n  /** Whether a 401 has marked the held token unusable ahead of its `expiresAt`. */\n  readonly stale: boolean;\n}\n\n/**\n * The starting slice: no token held, not stale. The first `needsRefresh` after\n * this returns `true` (no token), so a consumer's first guarded call mints a\n * credential before going out.\n */\nexport function initTokenRefresh(): TokenState {\n  return { token: null, stale: false };\n}\n\n/**\n * The Cmd this knob emits to ask the runtime to mint a fresh token. Plain data\n * (no closure — invariant 1) carrying nothing: the refresh port takes no input,\n * and the slice the result installs is read off the follow-up Msg, not this\n * Cmd. The consumer unions this into their machine's Cmd type and lets\n * `handlers` interpret it.\n */\nexport interface RefreshTokenCmd extends Cmd<\"refresh_token\"> {}\n\n/** Construct a `refresh_token` Cmd. */\nexport function refreshTokenCmd(): RefreshTokenCmd {\n  return { type: \"refresh_token\" };\n}\n\n/**\n * The Msg the refresh port dispatches on success — carries the freshly minted\n * `Token`. The consumer unions this into their Msg type and handles it by\n * folding `refreshed(state, msg.token)` into the slice.\n */\nexport interface TokenRefreshedMsg {\n  readonly type: typeof MsgType.TokenRefreshed;\n  readonly token: Token;\n}\n\n/** Construct a `token_refreshed` Msg carrying the new token. */\nexport function tokenRefreshedMsg(token: Token): TokenRefreshedMsg {\n  return { type: MsgType.TokenRefreshed, token };\n}\n\n/**\n * The Msg the refresh port dispatches on failure — carries the rejection so the\n * consumer's reducer can decide whether to back off, surface an error, or give\n * up (errors are data: it is dispatched, never swallowed). The slice itself is\n * left untouched by a failed refresh — the held token (if any) stays held and\n * stale stays set, so the consumer can retry; clearing it is the consumer's\n * policy, expressed in their reducer.\n */\nexport interface TokenRefreshFailedMsg {\n  readonly type: typeof MsgType.TokenRefreshFailed;\n  readonly error: unknown;\n}\n\n/** Construct a `token_refresh_failed` Msg carrying the rejection. */\nexport function tokenRefreshFailedMsg(error: unknown): TokenRefreshFailedMsg {\n  return { type: MsgType.TokenRefreshFailed, error };\n}\n\n/** The two Msgs the refresh port can produce. Union for a consumer's Msg type. */\nexport type TokenRefreshMsg = TokenRefreshedMsg | TokenRefreshFailedMsg;\n\n/** The ports this knob's `handlers` splice needs — the single refresh DI seam. */\nexport interface TokenRefreshPorts {\n  /**\n   * Mint a fresh credential. Called ONLY from the `refresh_token` interpret\n   * handler — never from a verb — so the network I/O and any clock the issuer\n   * reads stay at the effect boundary. May reject; the rejection is routed to\n   * `token_refresh_failed` (errors are data), never thrown into the runtime.\n   */\n  readonly refresh: () => Promise<Token>;\n}\n\n/**\n * The knob: hand it a config, get back the slice initializer, the pure verbs,\n * and the `handlers` splice. Mirrors every L2 composition's uniform contract so\n * the call sites read identically across bricks.\n *\n * @example\n *   const tr = createTokenRefresh({ skewMs: 30_000 });\n *   const s0 = tr.init();\n *   const [s1, cmds] = tr.ensureFresh(s0, Date.now()); // cmds = [refreshTokenCmd()]\n */\nexport function createTokenRefresh(config: TokenRefreshConfig = {}) {\n  // Clamp once at construction: a negative skew would push the refresh trigger\n  // PAST expiry, which inverts the knob's intent (\"refresh ahead\"). NaN (a\n  // miswired config) collapses to 0 so `needsRefresh`'s comparison stays total.\n  const skewMs =\n    config.skewMs !== undefined && config.skewMs > 0 ? config.skewMs : 0;\n\n  /**\n   * Whether the held token must be refreshed before the next guarded call, at\n   * the injected instant `at` (epoch ms). PURE — reads only, no clock, no\n   * mutation. True iff ANY of:\n   *\n   *   - no token is held (`token === null`) — nothing to present;\n   *   - the token was marked `stale` by a 401 — the server disagrees with the\n   *     client's belief that it is valid;\n   *   - the token's `expiresAt` is not a finite number (`NaN` / `±Infinity`) —\n   *     a miswired issuer or a corrupted slice; we cannot reason about when it\n   *     lapses, so we fail SAFE toward minting a fresh one rather than letting\n   *     `at >= NaN` (always `false`) or `at >= Infinity` (always `false`) mask\n   *     a broken expiry as \"fresh forever\";\n   *   - the token is at or past its skewed expiry (`at >= expiresAt - skewMs`)\n   *     — the proactive refresh-ahead window has opened.\n   *\n   * The expiry cutoff is half-open (`>=`), matching the window edges in\n   * `rate-limit` / `cache` / `circuit-breaker`: a token minted to expire at `t`\n   * with zero skew is considered due at exactly `t`.\n   */\n  function needsRefresh(state: TokenState, at: number): boolean {\n    if (state.token === null) return true;\n    if (state.stale) return true;\n    // Non-finite expiry (NaN/±Infinity) can never be compared into a \"due\"\n    // verdict — `at >= NaN` and `at >= Infinity` are both `false`, which would\n    // pin a broken token as fresh forever. Fail safe: treat it as needing a\n    // refresh so the next call mints a credential with a real deadline.\n    if (!Number.isFinite(state.token.expiresAt)) return true;\n    return at >= state.token.expiresAt - skewMs;\n  }\n\n  /**\n   * Mark the held token unusable because a request the client believed valid\n   * came back 401. PURE — returns a new slice; the input is never mutated.\n   * Sets `stale` regardless of `expiresAt`, so the next `needsRefresh` returns\n   * true even when the clock still says the token is fine. The token VALUE is\n   * kept (not nulled) — it is the consumer's last-known credential until a\n   * refresh replaces it, and keeping it lets observability show what was\n   * rejected.\n   *\n   * Idempotent: a second 401 on an already-stale slice returns the same shape.\n   * A 401 with no token held is a no-op (already needs a refresh).\n   */\n  function on401(state: TokenState): TokenState {\n    if (state.stale) return state;\n    return { ...state, stale: true };\n  }\n\n  /**\n   * Install a freshly minted `token`, clearing `stale`. PURE — returns a new\n   * slice; the input is never mutated. This is the fold for the\n   * `token_refreshed` Msg: after it, `needsRefresh(state, at)` is false for any\n   * `at` below the new skewed expiry, and the stale flag is gone (the new\n   * credential supersedes whatever the 401 rejected).\n   *\n   * This is the slice's WRITE boundary for a credential, so it is where the\n   * durability invariant is paid for: it normalizes a negative-zero `expiresAt`\n   * to `+0` before the value enters the slice. `-0` is the one finite double\n   * JSON cannot round-trip — `JSON.stringify(-0)` is `\"0\"`, which parses back as\n   * `+0`, so a slice carrying `-0` would diverge from its persisted form across\n   * a Durable Object eviction / page reload (invariant: the boundary parses, the\n   * core trusts). `-0` and `+0` denote the same epoch-ms instant, so collapsing\n   * them loses no information and makes the un-round-trippable state\n   * unrepresentable in the slice by construction.\n   */\n  function refreshed(state: TokenState, token: Token): TokenState {\n    const normalized: Token = Object.is(token.expiresAt, -0)\n      ? { ...token, expiresAt: 0 }\n      : token;\n    return { ...state, token: normalized, stale: false };\n  }\n\n  /**\n   * The verb a consumer calls at the call boundary: \"make sure I have a fresh\n   * credential before the next request.\" PURE — returns `[next, cmds]`. When a\n   * refresh is due (`needsRefresh(state, at)`), emits a single `refresh_token`\n   * Cmd; otherwise emits none. The slice is returned UNCHANGED in both branches\n   * — the refresh itself is async and lands later via `refreshed`, so there is\n   * no in-flight phase to record here. (A consumer that wants single-flight —\n   * \"don't fire a second refresh while one is pending\" — layers that in their\n   * own reducer, e.g. by tracking a pending flag; this brick stays minimal and\n   * lets the consumer own that policy.)\n   *\n   * The `at` is the caller's stamped clock reading (epoch ms), never read here —\n   * keeping the verb pure and `replay`-able.\n   */\n  function ensureFresh(\n    state: TokenState,\n    at: number,\n  ): readonly [TokenState, readonly Cmd[]] {\n    if (needsRefresh(state, at)) {\n      return [state, [refreshTokenCmd()]];\n    }\n    return [state, []];\n  }\n\n  /**\n   * The interpret splice: wraps the injected `refresh` port and routes its\n   * Ok/Err to `token_refreshed` / `token_refresh_failed` Msgs via the core's\n   * `tryInterpret` Railway helper. Spread the result into a consumer's\n   * `interpret` map:\n   *\n   *   interpret: { ...other, ...tr.handlers({ refresh: () => sdk.mintToken() }) }\n   *\n   * The port is the ONLY place the network (and any clock the issuer reads) is\n   * touched — every verb above stays pure. `tryInterpret` guarantees the\n   * handler never rejects: a port rejection becomes a `token_refresh_failed`\n   * Msg (errors are data), so the runtime's dispatch loop is never poisoned by\n   * an unhandled rejection.\n   */\n  function handlers(\n    ports: TokenRefreshPorts,\n  ): Interpret<TokenRefreshMsg, RefreshTokenCmd, unknown> {\n    return {\n      refresh_token: tryInterpret<\n        RefreshTokenCmd,\n        Token,\n        TokenRefreshMsg,\n        unknown\n      >(\n        () => ports.refresh(),\n        (token) => tokenRefreshedMsg(token),\n        (error) => tokenRefreshFailedMsg(error),\n      ),\n    };\n  }\n\n  return {\n    /** The slice initializer — spread into the consumer's `init`. */\n    init: initTokenRefresh,\n    needsRefresh,\n    on401,\n    refreshed,\n    ensureFresh,\n    handlers,\n  };\n}\n\n/** The shape `createTokenRefresh` returns — useful for typing a held knob. */\nexport type TokenRefresh = ReturnType<typeof createTokenRefresh>;\n"]}

package/dist/deadline/index.js

@@ -1,6 +1,6 @@
 export { deadlineExceeded, deadlineSub, setTimeoutArmTimer, subscribeDeadline, subscribeWith } from '../chunk-RMX4EOQK.js';
 import '../chunk-2YFLOCWX.js';
-import '../chunk-BP2R7TPP.js';
+import '../chunk-D4NJBQAH.js';
 import '../chunk-PBDYW2TU.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/do/index.d.ts

@@ -1,4 +1,4 @@
-import { S as Store, R as Runtime, B as BootingRuntime } from '../runtime-types-gsog27b6.js';
+import { S as Store, R as Runtime, B as BootingRuntime } from '../runtime-types-CukV8kMX.js';
 import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-CFRngTNA.js';
 export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, d as PendingEffectsLedger, c as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-CFRngTNA.js';
 import { RetryPolicy, Rng } from '../retry-backoff/index.js';

package/dist/do/index.js

@@ -1,9 +1,9 @@
-import { status, agentBootMsg, agentEvents } from '../chunk-WGGAMW7Y.js';
+import { status, agentBootMsg, agentEvents } from '../chunk-5W7CNAHB.js';
 export { applyEffectEvent, emptyLedger, foldLedger, isOwed, pendingEffectsLedger, survivingEffects } from '../chunk-25LBDCBC.js';
-import '../chunk-CAXMQJJ3.js';
-import '../chunk-VBUCHVCV.js';
-import '../chunk-MVY5DAMF.js';
-import '../chunk-IXBKFQH5.js';
+import '../chunk-LJJV6ZD5.js';
+import '../chunk-FCKP6N7Y.js';
+import '../chunk-SPWVPIFQ.js';
+import '../chunk-B5RAZVXW.js';
 import '../chunk-JELSZN25.js';
 import '../chunk-D736QUGF.js';
 import { createIntake } from '../chunk-ZVJZ72HY.js';
@@ -20,7 +20,7 @@ import '../chunk-LYLDCIPH.js';
 import '../chunk-2YFLOCWX.js';
 import '../chunk-ZJ5AOYBH.js';
 import '../chunk-G5E74IJB.js';
-import { replay, run } from '../chunk-BP2R7TPP.js';
+import { replay, run } from '../chunk-D4NJBQAH.js';
 import '../chunk-PBDYW2TU.js';
 
 // src/do/durable-timer.ts