@demlik/tea 0.15.0 → 0.17.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-rDbOaJTN.js';
+import { Q as QueueItem } from '../index-CcrKLtse.js';
+import '@standard-schema/spec';
+import '../runtime-types-B62Ucnxr.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-OPH6Y4UT.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-C4U5D5HP.js';
+import '../chunk-K4ETBNKS.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/{index-KXqTRJyb.d.ts → index-BOrsbdAf.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-rDbOaJTN.js';
+import { S as SnapshotWriteCmd, a as SnapshotState, b as SnapshotSavedMsg } from './index-CWmsXNdX.js';
+import { D as DeadlineExceeded, a as DeadlineSub } from './index-DaX_P35Q.js';
+import { Q as QueueItem } from './index-CcrKLtse.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-DrIRb_Ch.d.ts → index-B_BxplWi.d.ts}

@@ -1,4 +1,4 @@
-import { B as BootingRuntime } from './runtime-types-CMF13BBh.js';
+import { B as BootingRuntime } from './runtime-types-B62Ucnxr.js';
 
 /**
  * A recorded run, sufficient to reproduce it via `../trace-replay`.

package/dist/index-CWmsXNdX.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-rDbOaJTN.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-C2DwkjlP.d.ts → index-Cberb5Rr.d.ts}

@@ -1,6 +1,5 @@
-import { C as Cmd } from './core-DnzqWy6u.js';
-import { S as SubscribeHandler } from './types-BseNPIhr.js';
-import { D as DeadlineExceeded, a as DeadlineSub } from './index-HSYgG2Yt.js';
+import { C as Cmd, T as TimerDeps, d as Subscribe } from './core-rDbOaJTN.js';
+import { D as DeadlineExceeded, a as DeadlineSub, b as DeadlinesSub } from './index-DaX_P35Q.js';
 
 /**
  * internal/flow/batch-window — coalesce a stream of items into size- or
@@ -8,14 +7,13 @@ import { D as DeadlineExceeded, a as DeadlineSub } from './index-HSYgG2Yt.js';
  *
  * What this module actually DELEGATES to, vs. what it merely RE-EXPORTS:
  *
- *   - `../deadline` — REAL delegation (the only one). The window timer IS a
- *     `deadline` Sub: `subsFor` returns `deadlineSub` keyed on the window's
- *     identity, the subscribe cell is `subscribeDeadline` verbatim, and the
- *     expiry Msg is `deadlineExceeded`. Nothing about the timer is redrawn here.
- *     "Fire at an absolute instant, even across a rehydrate" is exactly
- *     `deadline`'s absolute-target lifecycle: a late subscribe (post-`Store`
- *     rehydrate) recomputes the remaining delay from the current clock and still
- *     fires at the correct moment.
+ *   - `../deadline` — REAL delegation (the only one). The window timer's Msg
+ *     is `deadlineExceeded`, keyed on the window's identity. `timerFor` arms it
+ *     through the engine's built-in `timer` Sub: `maxMs` counted from the
+ *     transition that opened the window, so a machine needs no runner. The
+ *     absolute-instant form is still here too — `subsFor` lists the same
+ *     deadline for `deadlinesSub` + `subscribeDeadline`, which re-arms for the
+ *     REMAINING time after a `Store` rehydrate rather than a fresh `maxMs`.
  *   - `../work-queue` — TYPE re-export only, NOT a sink this module calls. A
  *     flush emits a Cmd; the CONSUMER's interpret handler is what enqueues onto a
  *     `createQueue(store)`. This module never touches queue status — it has no
@@ -48,10 +46,10 @@ import { D as DeadlineExceeded, a as DeadlineSub } from './index-HSYgG2Yt.js';
  *   // Model:        { batch: BatchWindow<LogLine>, ... }
  *   // init:         (loaded) => [loaded ?? { batch: bw.init(), ... }, []]
  *   // update cells:
- *   //   LogArrived:   (s, m) => mapBatch(s, bw.add(s.batch, m.line, m.at))
- *   //   WindowFired:  (s, m) => mapBatch(s, bw.onWindow(s.batch, m.atMs))
- *   // subscriptions: (s) => bw.subs(s.batch)
- *   // subscribe:     { ...bw.handlers() }
+ *   //   LogArrived:        (s, m) => mapBatch(s, bw.add(s.batch, m.line, m.at))
+ *   //   deadline_exceeded: (s, m) => mapBatch(s, bw.onWindow(s.batch, m.atMs))
+ *   // subs:         [{ type: "timer", deps: (s: Model) => bw.timer(s.batch) }]
+ *   // at run:       run(machine, { interpret })   // `timer` is built in
  *
  * where `mapBatch(s, [batch, cmds]) => [{ ...s, batch }, cmds]` lifts the slice
  * transition into the consumer's Model. The `FlushBatch` Cmd's interpret handler
@@ -118,26 +116,26 @@ interface BatchWindow<I> {
 /** The starting slice: closed window, empty buffer. */
 declare function initBatchWindow<I>(): BatchWindow<I>;
 /**
- * The Sub a batch window's open timer produces: it IS `../deadline`'s
+ * The deadline a batch window's open timer lists: it IS `../deadline`'s
  * `DeadlineSub`, not a re-tagged copy. `atMs` is the absolute flush-by instant
  * (`openedAt + maxMs`). Aliasing the deadline type (rather than redeclaring an
  * identical shape) is what lets `subsFor` return `deadlineSub(...)` with no
  * cast — the value's static type already satisfies this name. Consumers running
- * several windows route each one by the Sub's `id`, not by a distinct type.
+ * several windows route each one by the deadline's `id`, not by a distinct type.
  */
 type BatchWindowSub = DeadlineSub;
 /** The Msg a closed-by-time window dispatches. Alias of `deadline`'s Msg. */
 type BatchWindowExpired = DeadlineExceeded;
 /**
  * Construct the window-expired Msg for the window identified by `id`, flushing
- * by `atMs`. Re-exported alias of `deadlineExceeded` so the subscribe cell and
+ * by `atMs`. Re-exported alias of `deadlineExceeded` so the runner and
  * the consumer's reducer share one constructor rather than two literals that
  * can drift. The consumer handles it in a reducer cell by calling `onWindow`.
  */
 declare function batchWindowExpired(id: string, atMs: number): BatchWindowExpired;
 /**
  * The bound knob returned by `createBatchWindow`. `init` + the two pure verbs +
- * `subs` + `handlers`, all closing over one `BatchWindowConfig`. The verbs
+ * `timer` + `subs`, all closing over one `BatchWindowConfig`. The verbs
  * return `readonly [BatchWindow<I>, readonly C[]]`: the next slice and the Cmds
  * to emit (one `flush` Cmd when a window closes, none otherwise).
  */
@@ -154,18 +152,16 @@ interface BatchWindowKnob<I, C extends Cmd> {
      */
     onWindow(state: BatchWindow<I>, at: number): readonly [BatchWindow<I>, readonly C[]];
     /**
-     * The window timer Sub, armed only while a window is open. See `subsFor`.
-     * `id` keys the deadline so several windows on one machine route distinctly.
+     * The built-in `timer` Sub's deps while a window is open, `null` while it is
+     * closed. See `timerFor`. `id` keys the Msg so several windows on one
+     * machine route distinctly.
      */
-    subs(state: BatchWindow<I>, id?: string): readonly BatchWindowSub[];
+    timer(state: BatchWindow<I>, id?: string): TimerDeps<BatchWindowExpired> | null;
     /**
-     * The `subscribe` cells this knob splices into `machine.subscribe`. One cell,
-     * keyed `"deadline"`, delegating to `../deadline`'s subscribe handler. Spread
-     * into the consumer's subscribe map: `subscribe: { ...bw.handlers() }`.
+     * The window timer as an absolute deadline, listed only while a window is
+     * open — for `deadlinesSub` + `subscribeBatchWindow`. See `subsFor`.
      */
-    handlers(): {
-        deadline: SubscribeHandler<BatchWindowSub, BatchWindowExpired, unknown>;
-    };
+    subs(state: BatchWindow<I>, id?: string): readonly BatchWindowSub[];
 }
 /**
  * Buffer `item` and decide whether the size trigger fires. PURE.
@@ -215,18 +211,18 @@ declare function addItem<I, C extends Cmd>(config: BatchWindowConfig<I, C>, stat
  */
 declare function onWindow<I, C extends Cmd>(config: BatchWindowConfig<I, C>, state: BatchWindow<I>, _at: number): readonly [BatchWindow<I>, readonly C[]];
 /**
- * The window timer Sub, derived from the slice. PURE.
+ * The window timer deadline, derived from the slice. PURE.
  *
- * Returns the single `deadline` Sub targeting `openedAt + maxMs` while a window
- * is open (buffer non-empty), or `[]` while it is closed. The substrate's
- * reconcile pass arms the timer when the array gains the Sub and disarms it
- * (clearing the pending `setTimeout`) when the array loses it — so a size-flush
- * that empties the buffer auto-cancels the now-irrelevant time trigger on the
- * next transition.
+ * Returns the single deadline targeting `openedAt + maxMs` while a window is
+ * open (buffer non-empty), or `[]` while it is closed. Fed through
+ * `deadlinesSub`, the engine arms the timer when the list gains the deadline
+ * and disarms it (clearing the pending `setTimeout`) when the list loses it —
+ * so a size-flush that empties the buffer auto-cancels the now-irrelevant time
+ * trigger on the next transition.
  *
  * `id` defaults to `"batch-window"`; pass a distinct id per window when a
- * machine runs several so the dispatched `BatchWindowExpired` Msg (and its
- * reconcile identity) routes to the right one.
+ * machine runs several so the dispatched `BatchWindowExpired` Msg routes to the
+ * right one.
  *
  * @param config the knob (maxMs)
  * @param state  the current slice
@@ -235,22 +231,38 @@ declare function onWindow<I, C extends Cmd>(config: BatchWindowConfig<I, C>, sta
  */
 declare function subsFor<I, C extends Cmd>(config: BatchWindowConfig<I, C>, state: BatchWindow<I>, id?: string): readonly BatchWindowSub[];
 /**
- * The `subscribe["deadline"]` cell for a batch window's timer — the exact
- * `../deadline` handler. Arms a one-shot timer for `max(0, atMs - now)` and
- * dispatches `batchWindowExpired(...)`; returns a cleanup that clears it. The
- * consumer assigns it via the knob's `handlers()`.
+ * The built-in `timer` Sub's deps for a batch window. PURE.
+ *
+ * While a window is open it counts `maxMs` down from the transition that
+ * opened it — the deps are fixed for the window's life (`openedAt` never moves
+ * while items append), so the engine starts the countdown exactly once — and
+ * fires `batchWindowExpired(id, openedAt + maxMs)`. A closed window is `null`,
+ * so a size-flush that empties the buffer cancels the countdown on the next
+ * transition.
+ *
+ * Relative by construction: a process that rehydrates an open window counts a
+ * fresh `maxMs`. Reach for `subsFor` + `subscribeBatchWindow` when the flush
+ * must land at the original absolute instant.
+ */
+declare function timerFor<I, C extends Cmd>(config: BatchWindowConfig<I, C>, state: BatchWindow<I>, id?: string): TimerDeps<BatchWindowExpired> | null;
+/**
+ * The `deadline` runner for a batch window's absolute timer — the exact
+ * `../deadline` runner. Arms a one-shot timer per listed deadline for
+ * `max(0, atMs - now)` and dispatches `batchWindowExpired(...)`; returns a
+ * cleanup that clears them. Hand it to `run` as `subscribe.deadline` when the
+ * machine declares `deadlinesSub((s) => bw.subs(s.batch))`.
  */
-declare const subscribeBatchWindow: SubscribeHandler<BatchWindowSub, BatchWindowExpired, unknown>;
+declare const subscribeBatchWindow: Subscribe<BatchWindowExpired, DeadlinesSub, unknown>["deadline"];
 /**
  * Build a batch window knob from a config. Combinator form (the default L2
  * ergonomic): hand it the config, splice the ~4 returned hooks into your
  * machine. The pure verbs (`add` / `onWindow`) close over the config so the
- * consumer's reducer cells stay a uniform `(state, ...args)` shape; `subs` /
- * `handlers` pre-wire the window timer.
+ * consumer's reducer cells stay a uniform `(state, ...args)` shape; `timer`
+ * arms the window timer.
  *
  * @typeParam I the item type buffered into each batch
  * @typeParam C the Cmd type `config.flush` returns
  */
 declare function createBatchWindow<I, C extends Cmd>(config: BatchWindowConfig<I, C>): BatchWindowKnob<I, C>;
 
-export { type BatchWindow as B, type BatchWindowSub as a, type BatchWindowExpired as b, type BatchWindowConfig as c, type BatchWindowKnob as d, addItem as e, batchWindowExpired as f, createBatchWindow as g, subscribeBatchWindow as h, initBatchWindow as i, onWindow as o, subsFor as s };
+export { type BatchWindow as B, type BatchWindowSub as a, type BatchWindowExpired as b, type BatchWindowConfig as c, type BatchWindowKnob as d, addItem as e, batchWindowExpired as f, createBatchWindow as g, subscribeBatchWindow as h, initBatchWindow as i, onWindow as o, subsFor as s, timerFor as t };

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

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