@demlik/tea 0.15.0 → 0.16.0

package/dist/idempotency/index.d.ts

@@ -1,10 +1,9 @@
 import { I as IdempotencyStore } from '../index-Bc40JWVl.js';
 export { a as IdempotencyEntry, e as evictExpired, i as initStore, r as recall, b as remember, s as seen } from '../index-Bc40JWVl.js';
-import { a as CmdOf, b as CmdDef } from '../core-DnzqWy6u.js';
-import { Q as QueueItem } from '../index-CSyMYDAB.js';
-import 'zod';
-import '../runtime-types-CMF13BBh.js';
-import 'better-result';
+import { c as CmdOf, b as CmdDef } from '../core-BbgtiXdg.js';
+import { Q as QueueItem } from '../index-7vV8xmsD.js';
+import '@standard-schema/spec';
+import '../runtime-types-CiVpC0HN.js';
 
 /**
  * A cached intake entry: either a key whose work is still in flight
@@ -69,7 +68,7 @@ declare function intakeProcessDef<P>(): CmdDef<"intake:process", {
     readonly itemId: string;
     /** The original payload, for the worker to process. */
     readonly payload: P;
-}, void, never, unknown>;
+}, undefined, never>;
 type IntakeProcessCmd<P> = CmdOf<ReturnType<typeof intakeProcessDef<P>>>;
 /**
  * A duplicate of an already-completed key arrived — replay the cached result
@@ -80,7 +79,7 @@ declare function intakeReplayDef<R>(): CmdDef<"intake:replay", {
     readonly key: string;
     /** The result the ORIGINAL request produced, recalled from the cache. */
     readonly result: R;
-}, void, never, unknown>;
+}, undefined, never>;
 type IntakeReplayCmd<R> = CmdOf<ReturnType<typeof intakeReplayDef<R>>>;
 /** The Cmd union the intake verbs emit. */
 type IntakeCmd<P, R> = IntakeProcessCmd<P> | IntakeReplayCmd<R>;

package/dist/idempotency/index.js

@@ -1,6 +1,8 @@
-export { createIntake, intakeProcessDef, intakeReplayDef } from '../chunk-VTQI2NHP.js';
+export { createIntake, intakeProcessDef, intakeReplayDef } from '../chunk-MYNLY3HP.js';
 export { evictExpired, initStore, recall, remember, seen } from '../chunk-PR6TB3BL.js';
 import '../chunk-TXN2KFHF.js';
-import '../chunk-66PY5WYF.js';
+import '../chunk-4LPY67E4.js';
+import '../chunk-GOX2CYIM.js';
+import '../chunk-CH5KTOEZ.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{index-CSyMYDAB.d.ts → index-7vV8xmsD.d.ts}

@@ -1,4 +1,4 @@
-import { S as Store } from './runtime-types-CMF13BBh.js';
+import { S as Store } from './runtime-types-CiVpC0HN.js';
 
 /**
  * internal/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.

package/dist/{index-KXqTRJyb.d.ts → index-Bz5Rh9Ga.d.ts}

@@ -1,89 +1,7 @@
-import { I as Interpret, C as Cmd } from './core-DnzqWy6u.js';
-import { S as SnapshotWriteCmd, a as SnapshotState, b as SnapshotStore, c as SnapshotSavedMsg, d as SnapshotFailedMsg, e as SnapshotLoadedMsg, f as SnapshotLoadFailedMsg, g as SnapshotLoadCmd } from './index-ZCMhnVKN.js';
-import { D as DeadlineExceeded, a as DeadlineSub } from './index-HSYgG2Yt.js';
-import { Q as QueueItem } from './index-CSyMYDAB.js';
-
-/**
- * internal/flow/monitored-run — a long-running operation that is BOTH staged and
- * watched: an ordered stage pipeline whose POSITION survives eviction, wrapped
- * by a no-progress safety deadline and (optionally) a periodic durable
- * checkpoint.
- *
- * This is the merge of two field-guide concerns the audit-agent machine
- * hand-wired together (`seed/audit-agent-machine`): the OUTER pipeline position
- * (`RunStage` — planning → testing → summarizing → reporting, replayed on cold
- * wake by re-emitting the one outstanding effect) and the no-progress safety
- * alarm (`subs.ts`, keyed on `progressSeq` so every progress event retires the
- * old alarm and arms a fresh one). `monitored-run` lifts both into one config-
- * driven knob with the uniform L2 contract `resilient-call` established:
- * `init()`, the verbs (`start` / `advance` / `progress` / `onDeadline` /
- * `boot`), `subs(state)`, and `handlers(ports)`.
- *
- *   - It is **staged, optionally**. Omit `stages` and the run is single-shot:
- *     `start` enters `running`, `advance` finishes it to `done`. Provide
- *     `stages` and it becomes an ordered pipeline — each `advance` retires the
- *     current stage and claims the next, finishing to `done` only when the last
- *     stage is retired. The pipeline POSITION lives in the Model (a
- *     `work-queue` of stage items), so an eviction mid-pipeline resumes at the
- *     same stage via `boot` — the audit machine's "pipeline position survives
- *     eviction" property, generalized.
- *   - It is **watched**. While `running`, a no-progress deadline is armed at
- *     `lastProgressAt + deadlineMs` and keyed on `progressSeq`. Every
- *     `progress` / `advance` bumps the seq, so the substrate retires the old
- *     alarm and arms a new one — a self-rearming watchdog. If the alarm fires
- *     (`onDeadline`) the run goes `failed` with a deadline reason. Omit
- *     `deadlineMs` → no watchdog (the `stale` phase is never reachable).
- *   - It **checkpoints, optionally**. Provide `snapshotEvery` and every
- *     progress unit is accounted to a `../snapshot` slice; once the cadence is
- *     reached a checkpoint Cmd is emitted (interpreted by the spliced snapshot
- *     `handlers`), so a crashed run restarts from the last durable checkpoint
- *     rather than from zero. Omit it → no checkpointing.
- *
- * ## Why the run lifecycle is INLINE (run-tracker not extracted)
- *
- * The phase union (`idle` / `running` / `stale` / `done` / `failed` / `cancelled`, a
- * discriminated union carrying only each phase's own data) and its bookkeeping
- * (`runId`, `startedAt`, `lastProgressAt`, `progressSeq`) live directly on this
- * slice rather than behind a `run-tracker` sub-knob.
- * Extraction earns its keep when two independent axes vary; here the lifecycle
- * has exactly one anchoring axis (this run), so a separate module would be a
- * premature seam. The two genuinely independent axes — the safety DEADLINE and
- * the periodic SNAPSHOT — ARE extracted (`../deadline`, `../snapshot`), and the
- * stage list is a `../work-queue` slice (`QueueItem<Stage>[]`) whose every
- * status flip is DELEGATED to the blessed `../work-queue/ops` (`enqueueOp` /
- * `claimNextOp` / `markDoneOp`) — never re-rolled here. The lifecycle is the
- * glue between them.
- *
- * ## The two non-negotiables (canon)
- *
- *   - **Durable** — the slice is plain data (the stage queue is a
- *     JSON-serializable `QueueItem<Stage>[]`, the snapshot slice is plain
- *     numbers), so it survives DO eviction / reload.
- *   - **Replayable** — every transition is a pure verb returning new state +
- *     Cmds; nothing here reads the clock or RNG. Time arrives as an `at` / `atMs`
- *     parameter; the only clock read is `Date.now()` inside the snapshot
- *     `handlers` port (the effect boundary), exactly as `../snapshot` stamps it.
- *
- * ## Typical wiring
- *
- *   const run = createMonitoredRun<MyStage, MyState>({
- *     stages: ["plan", "test", "report"],
- *     deadlineMs: 10 * 60_000,
- *     snapshotEvery: 25,
- *   });
- *
- *   init: (loaded) => loaded ? [loaded, []] : [{ run: run.init() }, []],
- *   update: {
- *     begin:    (s, m) => lift(s, run.start(s.run, m.runId, m.at)),
- *     advance:  (s, m) => lift(s, run.advance(s.run, checkpoint(s), m.result, m.at)),
- *     progress: (s, m) => lift(s, run.progress(s.run, checkpoint(s), m.at)),
- *     run_deadline: (s, m) => lift(s, run.onDeadline(s.run, m)),
- *     boot:     (s, m) => lift(s, run.boot(s.run, m.at)),
- *   },
- *   subscriptions: (s) => run.subs(s.run),
- *   subscribe: { deadline: subscribeDeadline },
- *   interpret: run.handlers({ store: r2 }),
- */
+import { b as CmdDef, T as TimerDeps, C as Cmd } from './core-BbgtiXdg.js';
+import { S as SnapshotWriteCmd, a as SnapshotState, b as SnapshotSavedMsg } from './index-CjFDUBeq.js';
+import { D as DeadlineExceeded, a as DeadlineSub } from './index-Xufl55W8.js';
+import { Q as QueueItem } from './index-7vV8xmsD.js';
 
 /**
  * The monitored-run knob. EVERY field is optional:
@@ -263,11 +181,6 @@ type StageResult = {
 type MonitoredRunCmd<V> = SnapshotWriteCmd<V>;
 /** The deadline Msg the safety alarm dispatches when the watchdog fires. */
 type MonitoredRunTimerMsg = DeadlineExceeded;
-/** Ports the consumer supplies to `handlers` — just the checkpoint store. */
-interface MonitoredRunPorts<V> {
-    /** Where periodic checkpoints are written (R2 / KV / DO sub-key / Map). */
-    readonly store: SnapshotStore<V>;
-}
 /**
  * Build a monitored-run knob from `config`. `Stage` is the consumer's stage
  * identifier type; `V` is the consumer's checkpoint value type (what
@@ -275,9 +188,19 @@ interface MonitoredRunPorts<V> {
  *
  * No `rng` parameter: unlike `resilient-call`, nothing here jitters — the only
  * external inputs are time (an `at` / `atMs` parameter) and the consumer's
- * stage outcomes. The clock is read only inside the snapshot `handlers` port.
+ * stage outcomes.
  */
 declare function createMonitoredRun<Stage, V = unknown>(config?: MonitoredRunConfig<Stage>): {
+    /** The `snapshot_write` Cmd def — list it in `cmds` when checkpointing. */
+    checkpoint: CmdDef<"snapshot_write", {
+        readonly key: string;
+        readonly seq: number;
+        readonly at: number;
+        readonly payload: V;
+    }, undefined, {
+        readonly [detail: string]: unknown;
+        readonly _tag: "snapshot_write_failed";
+    }>;
     init: () => MonitoredRunState<Stage>;
     start: (s: MonitoredRunState<Stage>, runId: string, at: number) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
     progress: (s: MonitoredRunState<Stage>, payload: V, at: number) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
@@ -286,9 +209,9 @@ declare function createMonitoredRun<Stage, V = unknown>(config?: MonitoredRunCon
     advance: (s: MonitoredRunState<Stage>, payload: V, result: StageResult, at: number) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
     onDeadline: (s: MonitoredRunState<Stage>, msg: MonitoredRunTimerMsg) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
     boot: (s: MonitoredRunState<Stage>, at: number) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
-    confirmSnapshot: (s: MonitoredRunState<Stage>, msg: SnapshotSavedMsg) => MonitoredRunState<Stage>;
-    subs: (s: MonitoredRunState<Stage>) => readonly DeadlineSub[];
-    handlers: (ports: MonitoredRunPorts<V>) => Interpret<SnapshotSavedMsg | SnapshotFailedMsg | SnapshotLoadedMsg<V> | SnapshotLoadFailedMsg, SnapshotWriteCmd<V> | SnapshotLoadCmd, unknown>;
+    confirmSnapshot: (s: MonitoredRunState<Stage>, msg: SnapshotSavedMsg<V>) => MonitoredRunState<Stage>;
+    deadlines: (s: MonitoredRunState<Stage>) => readonly DeadlineSub[];
+    timer: (s: MonitoredRunState<Stage>) => TimerDeps<MonitoredRunTimerMsg> | null;
 };
 /**
  * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the
@@ -300,4 +223,4 @@ declare function liftRun<S extends {
     run: MonitoredRunState<Stage>;
 }, Stage, C extends Cmd>(state: S, [slice, cmds]: readonly [MonitoredRunState<Stage>, readonly C[]]): readonly [S, readonly C[]];
 
-export { type EndedRun as E, type MonitoredRunCmd as M, type RunFailure as R, type StageResult as S, type MonitoredRunState as a, type MonitoredRunConfig as b, type MonitoredRunPorts as c, type MonitoredRunTimerMsg as d, createMonitoredRun as e, liftRun as l };
+export { type EndedRun as E, type MonitoredRunCmd as M, type RunFailure as R, type StageResult as S, type MonitoredRunState as a, type MonitoredRunConfig as b, type MonitoredRunTimerMsg as c, createMonitoredRun as d, liftRun as l };

package/dist/index-CjFDUBeq.d.ts

@@ -0,0 +1,207 @@
+import { c as CmdOf, b as CmdDef, e as SettledOk, f as SettledErr, g as TaggedError, C as Cmd } from './core-BbgtiXdg.js';
+
+/**
+ * The snapshot knob.
+ *
+ * `every` is the cadence: a checkpoint is written once `every` units of
+ * progress have accumulated since the last one (see `record`). It is the
+ * `snapshotEvery` field `monitored-run` threads through to this module.
+ *
+ * `key` is the store key the checkpoint is written under. A single machine
+ * keeps a single rolling checkpoint, so the key is fixed at config time rather
+ * than passed per write — the latest checkpoint overwrites the previous one
+ * (R2/KV are last-write-wins on a key). Defaults to `"@@snapshot"`, mirroring
+ * `doStore`'s `@@state` default-key convention.
+ */
+interface SnapshotConfig {
+    /**
+     * Write a checkpoint once this many progress units have accumulated since the
+     * last write. `every: 1` checkpoints on every `record`; a value `<= 0` is
+     * treated as `1` (every progress unit triggers a write) — a non-positive
+     * cadence has no other sensible meaning, and clamping keeps `record` from
+     * never checkpointing on a misconfigured `0`.
+     */
+    readonly every: number;
+    /** Store key the rolling checkpoint is written under. Defaults to `"@@snapshot"`. */
+    readonly key?: string;
+}
+/**
+ * The snapshot bookkeeping slice. Plain data — JSON-serializable so it rides
+ * inside the consumer's `Store<S>` blob and survives DO eviction / reload (the
+ * "durable" non-negotiable). It carries NO payload: the thing being
+ * checkpointed lives elsewhere in the machine's state; this slice only tracks
+ * *when* to checkpoint and *what has been acknowledged durable*.
+ *
+ *   - `sinceLast` — progress units accumulated since the last checkpoint
+ *     DECISION (reset to 0 the moment `record` decides to write, not when the
+ *     write lands). The cadence counter.
+ *   - `seq` — monotonic checkpoint sequence. Bumped each time a write is
+ *     emitted, so the write Cmd and its later acknowledgement can be matched
+ *     even if several are in flight. The "version" of the latest emitted
+ *     checkpoint.
+ *   - `lastSavedSeq` — the highest `seq` whose write the host has confirmed
+ *     durable (via `confirm`). `null` until the first confirmed write. The gap
+ *     `seq - lastSavedSeq` is the "writes emitted but not yet acknowledged"
+ *     depth — observable for backpressure / health.
+ *   - `lastSavedAt` — the `at` of the most recent confirmed write (epoch ms),
+ *     `null` until the first. Carried for observability, never compared inside
+ *     a verb (time is injected, never read here).
+ */
+interface SnapshotState {
+    readonly sinceLast: number;
+    readonly seq: number;
+    readonly lastSavedSeq: number | null;
+    readonly lastSavedAt: number | null;
+}
+/**
+ * The checkpoint-write Cmd a `record` / `force` decision emits. Plain data
+ * (invariant 1 — Cmds are data, not closures): it carries the `payload` to
+ * write, the `key` to write it under, the `seq` it represents, and the `at` it
+ * was decided.
+ *
+ * `payload` is `V` — the consumer's serializable checkpoint value (the run
+ * state, the cursor, whatever the machine wants restartable). The verb takes it
+ * as an argument so the snapshot slice never has to hold a copy of the
+ * machine's domain state.
+ *
+ * `Cmd.define`d (ADR 0014, 0021), minted per `V` by a factory the way
+ * `workflowActivityDef<A>()` is, since the payload type is the knob's own
+ * parameter. The handler you write puts the payload in your store and returns
+ * `ok(undefined)`, or `err({ _tag: "snapshot_write_failed", … })`; the engine
+ * mints `snapshot_write_ok` / `snapshot_write_err`.
+ */
+declare function snapshotWriteDef<V>(): CmdDef<"snapshot_write", {
+    readonly key: string;
+    readonly seq: number;
+    readonly at: number;
+    readonly payload: V;
+}, undefined, {
+    readonly [detail: string]: unknown;
+    readonly _tag: "snapshot_write_failed";
+}>;
+type SnapshotWriteCmd<V> = CmdOf<ReturnType<typeof snapshotWriteDef<V>>>;
+/**
+ * The checkpoint-READ Cmd a `requestLoad` decision emits — the recovery half of
+ * the module. Plain data (invariant 1): it carries only the `key` to read. The
+ * handler you write reads the store and returns `ok(payload)` — `null` when
+ * the store has no checkpoint under `key` — or
+ * `err({ _tag: "snapshot_load_failed", … })`.
+ *
+ * Distinct from `snapshot_write`: a write carries a payload OUT to the store; a
+ * load asks the store to hand a payload BACK. The consumer dispatches the
+ * triggering Msg once on resume (a `boot` Msg, never `init`'s rehydrate branch —
+ * invariant 2), folds the recovered payload into its run slice, then continues.
+ */
+declare function snapshotLoadDef<V>(): CmdDef<"snapshot_load", {
+    readonly key: string;
+}, V | null, {
+    readonly [detail: string]: unknown;
+    readonly _tag: "snapshot_load_failed";
+}>;
+type SnapshotLoadCmd<V = unknown> = CmdOf<ReturnType<typeof snapshotLoadDef<V>>>;
+/**
+ * The Msg the engine mints when a write lands. Fold it through
+ * `confirm(state, msg)` to advance `lastSavedSeq` / `lastSavedAt`. It carries
+ * the write Cmd, so `msg.cmd.seq` matches the emitting decision and a late
+ * acknowledgement of an older write can never regress a newer confirmed one.
+ */
+type SnapshotSavedMsg<V = unknown> = SettledOk<"snapshot_write", SnapshotWriteCmd<V>, undefined>;
+/**
+ * The Msg the engine mints when a write fails. Errors are data (never
+ * swallowed): the consumer's reducer decides whether a failed checkpoint is
+ * fatal, retryable (compose `@demlik/tea/retry-backoff`), or merely logged.
+ * `msg.cmd.seq` identifies which checkpoint failed.
+ */
+type SnapshotFailedMsg<V = unknown> = SettledErr<"snapshot_write", SnapshotWriteCmd<V>, TaggedError<"snapshot_write_failed">>;
+/**
+ * The Msg the engine mints when a read resolves. `value` is the recovered
+ * checkpoint, or `null` when the store has no checkpoint under `key` (fresh
+ * boot — never checkpointed, or a wiped store). `null` is NOT an error — "no
+ * checkpoint yet" is a normal first-run state, distinct from "the read failed"
+ * (`snapshot_load_err`).
+ */
+type SnapshotLoadedMsg<V> = SettledOk<"snapshot_load", SnapshotLoadCmd<V>, V | null>;
+/**
+ * The Msg the engine mints when a read fails. Errors are data: a failed
+ * recovery read is a visible signal the consumer's reducer decides on
+ * (fatal-abort, retry, or boot-fresh-and-log). Kept apart from a `null` load
+ * so "the store has no checkpoint" can never masquerade as "the read failed".
+ */
+type SnapshotLoadFailedMsg<V = unknown> = SettledErr<"snapshot_load", SnapshotLoadCmd<V>, TaggedError<"snapshot_load_failed">>;
+/**
+ * The bundle `createSnapshot` returns: plain functions plus the two Cmd defs to
+ * list in `cmds`. There are no subs: a checkpoint is driven by progress (a
+ * `record` call from the consumer's reducer), not by a timer.
+ */
+interface SnapshotKnob<V> {
+    /** The `snapshot_write` Cmd def — list it in the machine's `cmds`. */
+    readonly write: ReturnType<typeof snapshotWriteDef<V>>;
+    /** The `snapshot_load` Cmd def — list it in the machine's `cmds`. */
+    readonly load: ReturnType<typeof snapshotLoadDef<V>>;
+    /** The initial slice — zero progress, no checkpoint emitted or confirmed yet. */
+    init(): SnapshotState;
+    /**
+     * Account one unit of progress. PURE. Increments `sinceLast`; once the
+     * accumulated count reaches the configured cadence, DECIDES to checkpoint:
+     * resets `sinceLast` to 0, bumps `seq`, and emits a single `snapshot_write`
+     * Cmd carrying `payload` + `key` + the new `seq` + `at`. Below the cadence it
+     * returns the bumped slice and NO Cmd.
+     *
+     * `payload` is the checkpoint value to persist (the consumer's domain state);
+     * `at` is the caller-stamped time the progress occurred (epoch ms) — injected,
+     * never read from the clock here.
+     */
+    record(state: SnapshotState, payload: V, at: number): readonly [SnapshotState, readonly SnapshotWriteCmd<V>[]];
+    /**
+     * Force a checkpoint regardless of the cadence counter. PURE. Always bumps
+     * `seq`, resets `sinceLast`, and emits the write Cmd. Use on a phase boundary
+     * the cadence would otherwise miss — e.g. "the run just finished, checkpoint
+     * the terminal state now" — so the last durable checkpoint is the final state,
+     * not whatever the modulo happened to land on.
+     */
+    force(state: SnapshotState, payload: V, at: number): readonly [SnapshotState, readonly SnapshotWriteCmd<V>[]];
+    /**
+     * Record a confirmed durable write. PURE. Advances `lastSavedSeq` /
+     * `lastSavedAt` to the acknowledged write's `seq` / `at`, but only forward:
+     * an out-of-order acknowledgement of an OLDER `seq` (a slow write landing
+     * after a newer one) is ignored, so the confirmed watermark is monotonic.
+     * Fold the `snapshot_write_ok` Msg here.
+     *
+     * Returns the reducer-cell shape `readonly [SnapshotState, readonly Cmd[]]`
+     * (with `Cmd.none` — an ack emits nothing) for uniformity with every sibling
+     * knob, so it drops straight into a `snapshot_write_ok` cell.
+     */
+    confirm(state: SnapshotState, msg: SnapshotSavedMsg<V>): readonly [SnapshotState, readonly Cmd[]];
+    /**
+     * Resume after a reload. PURE. Resets `sinceLast` to 0 because any
+     * un-checkpointed progress accumulated before the crash is moot — recovery
+     * resumes from the last DURABLE checkpoint, so the cadence counter starts
+     * fresh from there. `seq` / `lastSavedSeq` / `lastSavedAt` are preserved
+     * (they describe what is durable, which a reload does not change). Call from
+     * a `boot` Msg the host dispatches once after `run(...)`, never from `init`'s
+     * rehydrate branch (invariant 2).
+     *
+     * Returns the reducer-cell shape `readonly [SnapshotState, readonly Cmd[]]`
+     * (with `Cmd.none` — a resume emits nothing) so it drops straight into a
+     * `snapshot_load_ok` cell.
+     */
+    boot(state: SnapshotState): readonly [SnapshotState, readonly Cmd[]];
+    /**
+     * Ask the store for the durable checkpoint. PURE. Emits a single
+     * `snapshot_load` Cmd carrying the configured `key`; returns the slice
+     * UNCHANGED (a read decides nothing about the cadence bookkeeping — only the
+     * later `snapshot_load_ok` fold, via `boot`, touches the slice). This is the
+     * entry point of the recovery loop: the consumer dispatches a `boot` Msg once
+     * after `run(...)` and folds `requestLoad` there.
+     */
+    requestLoad(state: SnapshotState): readonly [SnapshotState, readonly SnapshotLoadCmd<V>[]];
+}
+/**
+ * Create a snapshot knob from a `SnapshotConfig`. The returned bundle is spliced
+ * into a consumer machine: `init()` seeds the slice, `record` / `force` are
+ * folded in reducer cells, `confirm` / `boot` handle the acknowledgement +
+ * resume Msgs, and `write` / `load` are the Cmd defs whose handlers you write.
+ */
+declare function createSnapshot<V>(config: SnapshotConfig): SnapshotKnob<V>;
+
+export { type SnapshotWriteCmd as S, type SnapshotState as a, type SnapshotSavedMsg as b, type SnapshotConfig as c, type SnapshotFailedMsg as d, type SnapshotKnob as e, type SnapshotLoadCmd as f, type SnapshotLoadFailedMsg as g, type SnapshotLoadedMsg as h, createSnapshot as i, snapshotWriteDef as j, snapshotLoadDef as s };

package/dist/{index-CuNO9m8i.d.ts → index-CkFYA9Y6.d.ts}

@@ -1,5 +1,5 @@
-import { C as Cmd, P as Port } from './core-DnzqWy6u.js';
-import { Q as QueueItem } from './index-CSyMYDAB.js';
+import { C as Cmd, P as Port } from './core-BbgtiXdg.js';
+import { Q as QueueItem } from './index-7vV8xmsD.js';
 
 /**
  * internal/flow/fan-out — scatter-gather over a bounded-concurrency work list.
@@ -54,15 +54,13 @@ import { Q as QueueItem } from './index-CSyMYDAB.js';
  * is supplied by the caller's `idOf` so `scatter` is deterministic, and the
  * launch effects are plain data the runtime performs (invariant 3).
  *
- * `handlers(ports)` is the I/O splice: it wires the runtime side that actually
- * runs each launched `of(item)` Cmd. Because `of` already produces a fully
- * caller-defined Cmd, fan-out does NOT own the interpret handler for it — the
- * consumer's own `interpret` performs the effect and routes Ok/Err back to the
- * `itemOk` / `itemErr` verbs (the same shape resilient-fetch uses with
- * `tryInterpret`). `handlers` therefore exposes the one piece fan-out CAN
- * pre-wire generically: emitting the gathered batch onto a typed Port when the
- * batch completes, for consumers that observe completion out-of-band rather
- * than through the `join` Cmd.
+ * Fan-out does NOT own the interpret handler for a launched `of(item)` Cmd: `of`
+ * already produces a fully caller-defined Cmd, so the consumer's own
+ * `interpret` performs the effect and routes Ok/Err back to the `itemOk` /
+ * `itemErr` verbs. `completion(ports)` is the one piece fan-out CAN pre-wire
+ * generically: emitting the gathered batch onto a typed Port when the batch
+ * completes, for consumers that observe completion out-of-band rather than
+ * through the `join` Cmd.
  *
  * NOT a substrate primitive: it depends only on `../work-queue`'s pure types +
  * blessed ops and the core `Cmd` / `Port` types. Internal since #48 — not
@@ -162,7 +160,7 @@ interface FanOutState<I, R> {
  *
  * Field optionality follows the resilient-call rule — omit `join`, omit the
  * completion Cmd (a consumer that observes `isComplete` itself, or wires the
- * `handlers` Port, doesn't need one).
+ * `completion` Port, doesn't need one).
  */
 interface FanOutConfig<I, R, C extends Cmd, J extends Cmd> {
     /** Max in-flight `of(item)` effects. Clamped to `>= 1` (a 0/negative cap would deadlock). */
@@ -180,7 +178,7 @@ interface FanOutConfig<I, R, C extends Cmd, J extends Cmd> {
     /**
      * Optional: fold the gathered done-results into a single completion Cmd,
      * fired exactly once at the transition that empties `pending` + `running`.
-     * Omit to drive completion off `isComplete` (or the `handlers` Port) instead.
+     * Omit to drive completion off `isComplete` (or the `completion` Port) instead.
      */
     readonly join?: (results: readonly R[]) => J;
 }
@@ -199,7 +197,7 @@ declare function initFanOut<I, R>(): FanOutState<I, R>;
 declare function isComplete<I, R>(state: FanOutState<I, R>): boolean;
 /**
  * Optional Port for observing batch completion out-of-band. When a consumer
- * passes `handlers(ports)` a `complete` Port, the runtime side can emit the
+ * passes `completion(ports)` a `complete` Port, the runtime side can emit the
  * gathered results onto it the moment `isComplete` flips true — distinct from
  * the in-band `join` Cmd (which threads back through `update`). Use the Port
  * for "tell the outside world the batch finished" without folding a completion
@@ -212,7 +210,7 @@ interface FanOutPorts<R> {
 /**
  * Build the fan-out knob from `config`. Returns the uniform combinator
  * contract: `init` for the owned slice, the three settle verbs + the derived
- * `isComplete`, and `handlers` for the optional out-of-band completion Port.
+ * `isComplete`, and `completion` for the optional out-of-band completion Port.
  *
  * No `subs` — fan-out runs no timers (the spec pins "Subs: none"). The
  * per-item effect's lifetime is owned by the consumer's `interpret`, and
@@ -225,7 +223,7 @@ declare function createFanOut<I, R, C extends Cmd = Cmd, J extends Cmd = Cmd>(co
     itemOk: (state: FanOutState<I, R>, id: string, result: R) => readonly [FanOutState<I, R>, readonly (C | J)[]];
     itemErr: (state: FanOutState<I, R>, id: string, error: unknown) => readonly [FanOutState<I, R>, readonly (C | J)[]];
     isComplete: typeof isComplete;
-    handlers: (ports: FanOutPorts<R>) => {
+    completion: (ports: FanOutPorts<R>) => {
         /**
          * Emit the gathered done-results onto `ports.complete` iff `state` is a
          * just-completed batch. Idempotency is the caller's concern (call it once