@demlik/tea 0.1.0 → 0.1.2

package/dist/monitored-run/index.d.ts

@@ -0,0 +1,253 @@
+import { DeadlineExceeded, DeadlineSub } from '../deadline/index.js';
+export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
+import { I as Interpret, C as Cmd } from '../core-BoB6t7dB.js';
+import { SnapshotState, SnapshotWriteCmd, SnapshotStore, SnapshotSavedMsg, SnapshotFailedMsg, SnapshotLoadedMsg, SnapshotLoadFailedMsg, SnapshotLoadCmd } from '../snapshot/index.js';
+import { QueueItem } from '../work-queue/index.js';
+import '../types-B-8bcAp8.js';
+import '../index.js';
+
+/**
+ * @demlik/tea/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 (`running` / `done` / `failed` / `stale`) 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 }),
+ */
+
+/**
+ * The monitored-run knob. EVERY field is optional:
+ *   - omit `stages`       → single-shot run (no pipeline; one `advance` finishes).
+ *   - omit `deadlineMs`   → no no-progress watchdog (the run is never auto-failed).
+ *   - omit `snapshotEvery`→ no periodic checkpoint (no `snapshot_write` Cmds).
+ *
+ * An empty config `{}` is a valid single-shot, unwatched, uncheckpointed run.
+ *
+ * `Stage` is the consumer's stage identifier — any JSON-serializable value
+ * (a string id, a `{ kind, ... }` record). It rides through the stage queue
+ * unchanged so the consumer's reducer can branch on the current stage to emit
+ * that stage's outstanding effect (the audit machine's `outstandingEffect`).
+ */
+interface MonitoredRunConfig<Stage> {
+    /**
+     * The ordered stages of the pipeline. Position survives eviction (lives in
+     * the Model's stage queue). Omit for a single-shot run. An empty array is
+     * treated as single-shot too — there is nothing to pipeline through.
+     */
+    readonly stages?: readonly Stage[];
+    /**
+     * No-progress watchdog budget, in ms. The safety deadline is armed at
+     * `lastProgressAt + deadlineMs` and re-armed on every progress event. Omit
+     * for no watchdog.
+     */
+    readonly deadlineMs?: number;
+    /**
+     * Checkpoint cadence — write a durable snapshot once this many progress
+     * units have accumulated. Threaded straight into `../snapshot`'s `every`.
+     * Omit for no checkpointing.
+     */
+    readonly snapshotEvery?: number;
+    /**
+     * Store key the rolling checkpoint is written under. Forwarded to
+     * `../snapshot`'s `key`; defaults to that module's `@@snapshot`. Ignored
+     * when `snapshotEvery` is omitted.
+     */
+    readonly snapshotKey?: string;
+}
+/**
+ * Why a run terminated as `failed`. Discriminated so each reason carries only
+ * its own data (pattern 11):
+ *   - `deadline`  — the no-progress watchdog fired (`onDeadline`).
+ *   - `stage`     — the consumer reported a stage failure via `advance(..., fail)`.
+ *
+ * `stale` is a SEPARATE phase (not a fail reason): a run is `stale` only by an
+ * explicit consumer signal that progress has wedged WITHOUT the deadline having
+ * fired — a soft, recoverable observation. The deadline firing is a hard
+ * terminal (`failed { reason: "deadline" }`).
+ *
+ * The `stage` variant carries the FAILING STAGE VALUE (the `Stage` itself), not
+ * a positional index: done stages leave the queue (`markDoneOp` filters them),
+ * so a residual index drifts as the pipeline advances. The stage value is the
+ * stable, meaningful identifier — `undefined` for a single-shot run (no stage).
+ */
+type RunFailure<Stage> = {
+    readonly reason: "deadline";
+    readonly at: number;
+} | {
+    readonly reason: "stage";
+    readonly stage: Stage | undefined;
+    readonly error: unknown;
+};
+/**
+ * Run lifecycle phase. Discriminated on `phase`:
+ *
+ *   - `running` — the run is live. Carries the current pipeline position
+ *     (`stepStates` is the stage queue; the single `running` item in it is the
+ *     current stage, `undefined` for a single-shot run) and the watchdog
+ *     bookkeeping (`lastProgressAt` / `progressSeq` keying the safety alarm).
+ *   - `stale`   — a soft "no progress observed" mark the consumer can set and
+ *     clear; the run is still resumable (a `progress` clears it back to
+ *     `running`). Distinct from a fired deadline, which is terminal.
+ *   - `done`    — every stage retired (or the single-shot `advance` landed).
+ *   - `failed`  — terminal failure; `failure` carries why.
+ */
+type RunPhase = "running" | "stale" | "done" | "failed";
+/**
+ * The slice. Plain data end to end:
+ *   - `phase`          — the lifecycle discriminant.
+ *   - `runId`          — host-minted run identity, stamped at `start` (the
+ *                        machine never mints — see the audit seed's
+ *                        "run identity is host-minted").
+ *   - `stepStates`     — the stage pipeline as a `work-queue` of stage items.
+ *                        Empty for a single-shot run. The ONE `running` item is
+ *                        the current stage; `done` items are retired stages
+ *                        (they leave the queue via `markDoneOp`, so the queue
+ *                        shrinks as the pipeline advances and is empty at
+ *                        `done`). POSITION survives eviction because this list
+ *                        is durable.
+ *   - `startedAt`      — `at` of `start`. Observability; never compared in a verb.
+ *   - `lastProgressAt` — `at` of the most recent progress event; the watchdog
+ *                        base. Re-armed by `progress` / `advance`.
+ *   - `progressSeq`    — monotonic progress counter; keys the safety alarm Sub
+ *                        id so every bump retires the old alarm and arms a new
+ *                        one (the audit subs' `safety:{progressSeq}` discipline).
+ *   - `failure`        — present iff `phase === "failed"`; the typed reason.
+ *   - `snapshot`       — the `../snapshot` slice (cadence counter + durable
+ *                        watermark). Always present (uniform shape); the gate
+ *                        is simply never driven when `snapshotEvery` is omitted.
+ */
+interface MonitoredRunState<Stage> {
+    readonly phase: RunPhase;
+    readonly runId: string;
+    readonly stepStates: readonly QueueItem<Stage>[];
+    readonly startedAt: number;
+    readonly lastProgressAt: number;
+    readonly progressSeq: number;
+    readonly failure: RunFailure<Stage> | null;
+    readonly snapshot: SnapshotState;
+}
+/**
+ * The outcome a consumer reports to `advance`: the current stage either
+ * succeeded (retire it, claim the next) or failed (terminate the run). Plain
+ * data — the consumer parses its stage result at its own boundary and hands a
+ * settled outcome here.
+ */
+type StageResult = {
+    readonly kind: "ok";
+} | {
+    readonly kind: "fail";
+    readonly error: unknown;
+};
+/** The checkpoint-write Cmd, generic over the consumer's checkpoint value `V`. */
+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
+ * `snapshotEvery` checkpoints). Returns the uniform L2 knob contract.
+ *
+ * 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.
+ */
+declare function createMonitoredRun<Stage, V = unknown>(config?: MonitoredRunConfig<Stage>): {
+    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>[]];
+    markStale: (s: MonitoredRunState<Stage>) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
+    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>;
+};
+/**
+ * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the
+ * slice lives at `state.run`. Convenience for the common single-slice host;
+ * hosts with a differently-named field spread by hand. PURE — a thin record
+ * rebuild, no clock / RNG.
+ */
+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 { DeadlineExceeded, DeadlineSub, type MonitoredRunCmd, type MonitoredRunConfig, type MonitoredRunPorts, type MonitoredRunState, type MonitoredRunTimerMsg, type RunFailure, type RunPhase, SnapshotSavedMsg, SnapshotWriteCmd, type StageResult, createMonitoredRun, liftRun };

package/dist/monitored-run/index.js

@@ -0,0 +1,10 @@
+export { createMonitoredRun, liftRun } from '../chunk-7W4LMPUW.js';
+import '../chunk-EHIX7NYZ.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-K7Q23EQ4.js';
+import '../chunk-HJO6VNQI.js';
+import '../chunk-TGG26XMK.js';
+import '../chunk-2YFLOCWX.js';
+import '../chunk-MMH7CW5K.js';
+import '../chunk-QLA76GIT.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/monitored-run/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/node/index.d.ts

@@ -1,5 +1,6 @@
-import { Store, SubId, Sub } from '../index.js';
 import WebSocket from 'ws';
+import { Store } from '../index.js';
+import { a as SubId, S as Sub } from '../core-BoB6t7dB.js';
 
 /**
  * @demlik/tea/node — Node host adapter for `@demlik/tea`.
@@ -99,10 +100,9 @@ type NodeWsRegistry = Map<SubId, WebSocket>;
  * The Ctx fields the node Subs depend on. A consumer's Ctx must extend this so
  * `node_ws` can register the live socket and Cmd handlers can reach it.
  *
- * Deliberately NOT parameterized by Msg (unlike tea-do's `DoSubscribeCtx<M>`):
- * the registry holds raw `WebSocket`s, and each Sub variant carries its own
- * Msg-typed callbacks. Trip-wire: if a future node Sub holds a Msg-typed
- * callback on ctx (the way tea-do's registries do), this becomes
+ * Deliberately NOT parameterized by Msg: the registry holds raw `WebSocket`s,
+ * and each Sub variant carries its own Msg-typed callbacks. Trip-wire: if a
+ * future node Sub holds a Msg-typed callback on ctx, this becomes
  * `NodeSubscribeCtx<M>`.
  */
 interface NodeSubscribeCtx {

package/dist/node/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/node/index.ts"],"names":["handle"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/node — Node host adapter for `@demlik/tea`.\n *\n * Every host adapter ships two halves (mirrors `@demlik/tea/do`):\n *\n *   1. `fileStore<S>(path, parse)` — a `Store<S>` over a JSON file on disk.\n *      Atomic save (temp + rename). Absent file → `load()` resolves `null`\n *      (fresh boot). Structurally malformed JSON throws at `load()` (an infra\n *      error), matching `doStore`; a shape mismatch is NOT a throw — the\n *      substrate calls `migrate`, which returns `null` and boots fresh.\n *      Use for resumable scripts / local repro of prod machines. Ephemeral\n *      CLIs can skip persistence with `memoryStore` from `@demlik/tea/mem`.\n *\n *   2. `nodeSubscribe<M, Ctx>()` — handler registry for the three node-native\n *      Sub types this package owns:\n *        - `node_ws`     — opens a `ws` WebSocket; routes open/message/close/\n *                          error into Msgs. Registers the live socket in\n *                          `ctx.wsRegistry` so a Cmd handler can write to it\n *                          (see `sendToWebSocket`). Cleanup closes the socket\n *                          for ANY non-CLOSED state.\n *        - `node_timer`  — setTimeout / setInterval; cleanup clears it.\n *        - `node_signal` — a process signal (SIGINT/SIGTERM/…) → Msg; cleanup\n *                          detaches the listener.\n *\n * Unlike tea-do — whose `alarm()` / `webSocketMessage()` are DO lifecycle\n * methods the handler can't observe from the outside, hence its registries —\n * a node process is continuously alive: each handler holds its resource in\n * closure and the returned cleanup closes it. The substrate's subscription\n * reconciler runs that cleanup the instant `subscriptions(state)` stops listing\n * the Sub — end-then-start choreography for free (Rule 9, [invariant 4]).\n * A lifecycle-bound resource (a socket, a timer) becomes impossible to leak\n * from a reducer cell, because no reducer cell owns its teardown.\n *\n * `ctx.wsRegistry` is the one shared surface: `node_ws` populates it; a Cmd\n * interpreter reads it to write to the open socket. Same shape as tea-do's\n * `wsRegistry`.\n */\n\nimport { mkdir, readFile, rename, writeFile } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport type { Store, Sub, SubId } from \"../index\";\nimport WebSocket, { type RawData } from \"ws\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// fileStore — `Store<S>` over a JSON file.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * `Store<S>` backed by a JSON file at `path`.\n *\n * `parse` is REQUIRED because the file is a real serialization boundary — the\n * bytes that come back through `JSON.parse` are structurally `unknown`, and the\n * caller (who owns `S`) is the only party that can validate the shape.\n * Returning `null` from `parse` means \"no usable persisted state\" — the\n * substrate boots `init` with `loaded = null`. `parse` must NOT throw per the\n * `Store<S>.migrate` contract.\n */\nexport function fileStore<S>(path: string, parse: (raw: unknown) => S | null): Store<S> {\n  return {\n    async load(): Promise<unknown> {\n      let raw: string;\n      try {\n        raw = await readFile(path, \"utf8\");\n      } catch (err) {\n        if ((err as NodeJS.ErrnoException).code === \"ENOENT\") return null;\n        throw err;\n      }\n      // JSON.parse throws on structural malformation — propagate (infra error),\n      // matching `doStore`. The decoded value is intentionally returned as\n      // `unknown`; the substrate's `migrate` callback is the boundary parse.\n      return JSON.parse(raw);\n    },\n    async save(state: S): Promise<void> {\n      await mkdir(dirname(path), { recursive: true });\n      // Write to a pid-scoped temp then atomically rename. The rename gives\n      // torn-write safety (a reader sees the old file or the new one, never a\n      // partial) and survives process crash / Ctrl-C — the only failure a local\n      // resumable run resumes from. fsync (file + dir) would add power-loss\n      // durability the use case doesn't need; the substrate serializes saves\n      // through run()'s queue, so there's never a second concurrent writer.\n      const tmp = `${path}.${process.pid}.tmp`;\n      await writeFile(tmp, JSON.stringify(state), \"utf8\");\n      await rename(tmp, path);\n    },\n    migrate(raw: unknown): S | null {\n      return parse(raw);\n    },\n  };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// NodeSub — the three node-native subscription variants.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * A node WebSocket sub. The substrate diffs subs by `id`; the same `id` across\n * transitions = the same socket (kept open). Emit a DIFFERENT `id` to force a\n * reconnect.\n *\n * Only `onMessage` returns `M | null` (null drops the frame) because inbound\n * frames are the boundary that needs a parse-and-maybe-discard seam. `onOpen`/\n * `onClose`/`onError` always dispatch — a spurious one is dropped in the reducer\n * (the cell ignores it), not here.\n */\nexport type NodeWsSub<M> = {\n  id: SubId;\n  type: \"node_ws\";\n  url: string;\n  onMessage: (data: string) => M | null;\n  onOpen?: () => M;\n  onClose?: (code: number, reason: string) => M;\n  onError?: (message: string) => M;\n};\n\n/**\n * A node timer sub. One-shot `setTimeout` by default; `repeat: true` →\n * `setInterval`. Cleanup clears the timer — a timer keyed to a phase is\n * cancelled the moment the machine leaves that phase.\n */\nexport type NodeTimerSub<M> = {\n  id: SubId;\n  type: \"node_timer\";\n  delayMs: number;\n  msg: M;\n  repeat?: boolean;\n};\n\n/**\n * A process-signal sub: `signal` (SIGINT/SIGTERM/…) → `msg`. Cleanup detaches\n * the listener. Lets graceful shutdown be a real machine transition rather than\n * an out-of-band `process.on` that the reducer can't see.\n */\nexport type NodeSignalSub<M> = {\n  id: SubId;\n  type: \"node_signal\";\n  signal: NodeJS.Signals;\n  msg: M;\n};\n\nexport type NodeSub<M> = NodeWsSub<M> | NodeTimerSub<M> | NodeSignalSub<M>;\n\n// Compile-time guarantee: `NodeSub<M>` is structurally a `Sub` (has `id`+`type`).\n// Erased at runtime — the `extends Sub` constraint on the alias's type\n// parameter fails to compile if `NodeSub` ever drifts off the `Sub` shape.\nexport type AssertNodeSubIsSub<T extends Sub = NodeSub<unknown>> = T;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Ctx — what the node Subs read / populate.\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type NodeWsRegistry = Map<SubId, WebSocket>;\n\n/**\n * The Ctx fields the node Subs depend on. A consumer's Ctx must extend this so\n * `node_ws` can register the live socket and Cmd handlers can reach it.\n *\n * Deliberately NOT parameterized by Msg (unlike tea-do's `DoSubscribeCtx<M>`):\n * the registry holds raw `WebSocket`s, and each Sub variant carries its own\n * Msg-typed callbacks. Trip-wire: if a future node Sub holds a Msg-typed\n * callback on ctx (the way tea-do's registries do), this becomes\n * `NodeSubscribeCtx<M>`.\n */\nexport interface NodeSubscribeCtx {\n  wsRegistry: NodeWsRegistry;\n}\n\n/**\n * Write a frame to a registered `node_ws` socket. No-op (returns `false`) when\n * the socket is absent, not OPEN, or `send()` throws. The Cmd-side companion to\n * the `node_ws` Sub: the Sub owns the socket's lifetime; this writes to it.\n *\n * The contract is a boolean no-op, never a throw: the socket can transition out\n * of OPEN between the `readyState` check and `send()` (or `ws` can throw on an\n * errored underlying connection), and a Cmd interpreter must not crash on that.\n */\nexport function sendToWebSocket(ctx: NodeSubscribeCtx, id: SubId, data: string): boolean {\n  const socket = ctx.wsRegistry.get(id);\n  if (!socket || socket.readyState !== WebSocket.OPEN) return false;\n  try {\n    socket.send(data);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// nodeSubscribe — the handler registry.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Build the `subscribe` handlers for `node_ws`, `node_timer`, and\n * `node_signal`. Matches `Machine#subscribe`'s\n * `[K in U[\"type\"]]: (sub, ctx, dispatch) => () => void` contract for the\n * `NodeSub<M>` variants. Generic `Ctx` must extend `NodeSubscribeCtx` so the\n * `node_ws` handler can register its socket.\n */\nexport function nodeSubscribe<M, Ctx extends NodeSubscribeCtx>(): {\n  node_ws: (sub: NodeWsSub<M>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;\n  node_timer: (sub: NodeTimerSub<M>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;\n  node_signal: (sub: NodeSignalSub<M>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;\n} {\n  return {\n    node_ws: (sub, ctx, dispatch) => {\n      const socket = new WebSocket(sub.url);\n      ctx.wsRegistry.set(sub.id, socket);\n\n      socket.on(\"open\", () => {\n        if (sub.onOpen) dispatch(sub.onOpen());\n      });\n      socket.on(\"message\", (data: RawData) => {\n        const msg = sub.onMessage(data.toString());\n        if (msg !== null) dispatch(msg);\n      });\n      socket.on(\"close\", (code: number, reason: Buffer) => {\n        if (sub.onClose) dispatch(sub.onClose(code, reason.toString()));\n      });\n      socket.on(\"error\", (err: Error) => {\n        if (sub.onError) dispatch(sub.onError(err.message));\n      });\n\n      return () => {\n        ctx.wsRegistry.delete(sub.id);\n        socket.removeAllListeners();\n        // Swallow teardown-induced errors: terminate()-ing a CONNECTING socket\n        // emits an 'error' (\"closed before the connection was established\"),\n        // and with our listeners gone that would be an unhandled 'error' that\n        // crashes the process. A no-op listener absorbs it.\n        socket.on(\"error\", () => {});\n        // Close for ANY non-closed state: a graceful 1000 when OPEN, a hard\n        // terminate() otherwise (CONNECTING/CLOSING) so a socket caught mid-\n        // handshake can't dangle. This is the teardown the hand-driven Cmd-pair\n        // approach (`cleanup_browser` closing the ws only `if OPEN`) could not\n        // guarantee.\n        if (socket.readyState === WebSocket.OPEN) {\n          socket.close(1000, \"tea-node sub cleanup\");\n        } else if (socket.readyState !== WebSocket.CLOSED) {\n          socket.terminate();\n        }\n      };\n    },\n\n    node_timer: (sub, _ctx, dispatch) => {\n      // Two reconcile lifecycles under one variant: a one-shot (`setTimeout`)\n      // that `subscriptions(state)` should drop on the render after it fires,\n      // vs a repeating (`setInterval`) one the state keeps listing across\n      // renders. Same Sub.type; the `repeat` flag picks the install + cleanup.\n      if (sub.repeat) {\n        const handle = setInterval(() => dispatch(sub.msg), sub.delayMs);\n        return () => clearInterval(handle);\n      }\n      const handle = setTimeout(() => dispatch(sub.msg), sub.delayMs);\n      return () => clearTimeout(handle);\n    },\n\n    node_signal: (sub, _ctx, dispatch) => {\n      const handler = () => dispatch(sub.msg);\n      process.on(sub.signal, handler);\n      return () => {\n        process.off(sub.signal, handler);\n      };\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../../src/node/index.ts"],"names":["handle"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/node — Node host adapter for `@demlik/tea`.\n *\n * Every host adapter ships two halves (mirrors `@demlik/tea/do`):\n *\n *   1. `fileStore<S>(path, parse)` — a `Store<S>` over a JSON file on disk.\n *      Atomic save (temp + rename). Absent file → `load()` resolves `null`\n *      (fresh boot). Structurally malformed JSON throws at `load()` (an infra\n *      error), matching `doStore`; a shape mismatch is NOT a throw — the\n *      substrate calls `migrate`, which returns `null` and boots fresh.\n *      Use for resumable scripts / local repro of prod machines. Ephemeral\n *      CLIs can skip persistence with `memoryStore` from `@demlik/tea/mem`.\n *\n *   2. `nodeSubscribe<M, Ctx>()` — handler registry for the three node-native\n *      Sub types this package owns:\n *        - `node_ws`     — opens a `ws` WebSocket; routes open/message/close/\n *                          error into Msgs. Registers the live socket in\n *                          `ctx.wsRegistry` so a Cmd handler can write to it\n *                          (see `sendToWebSocket`). Cleanup closes the socket\n *                          for ANY non-CLOSED state.\n *        - `node_timer`  — setTimeout / setInterval; cleanup clears it.\n *        - `node_signal` — a process signal (SIGINT/SIGTERM/…) → Msg; cleanup\n *                          detaches the listener.\n *\n * Unlike tea-do — whose `alarm()` / `webSocketMessage()` are DO lifecycle\n * methods the handler can't observe from the outside, hence its registries —\n * a node process is continuously alive: each handler holds its resource in\n * closure and the returned cleanup closes it. The substrate's subscription\n * reconciler runs that cleanup the instant `subscriptions(state)` stops listing\n * the Sub — end-then-start choreography for free (Rule 9, [invariant 4]).\n * A lifecycle-bound resource (a socket, a timer) becomes impossible to leak\n * from a reducer cell, because no reducer cell owns its teardown.\n *\n * `ctx.wsRegistry` is the one shared surface: `node_ws` populates it; a Cmd\n * interpreter reads it to write to the open socket. Same shape as tea-do's\n * `wsRegistry`.\n */\n\nimport { mkdir, readFile, rename, writeFile } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport WebSocket, { type RawData } from \"ws\";\nimport type { Store, Sub, SubId } from \"../index\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// fileStore — `Store<S>` over a JSON file.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * `Store<S>` backed by a JSON file at `path`.\n *\n * `parse` is REQUIRED because the file is a real serialization boundary — the\n * bytes that come back through `JSON.parse` are structurally `unknown`, and the\n * caller (who owns `S`) is the only party that can validate the shape.\n * Returning `null` from `parse` means \"no usable persisted state\" — the\n * substrate boots `init` with `loaded = null`. `parse` must NOT throw per the\n * `Store<S>.migrate` contract.\n */\nexport function fileStore<S>(\n  path: string,\n  parse: (raw: unknown) => S | null,\n): Store<S> {\n  return {\n    async load(): Promise<unknown> {\n      let raw: string;\n      try {\n        raw = await readFile(path, \"utf8\");\n      } catch (err) {\n        if ((err as NodeJS.ErrnoException).code === \"ENOENT\") return null;\n        throw err;\n      }\n      // JSON.parse throws on structural malformation — propagate (infra error),\n      // matching `doStore`. The decoded value is intentionally returned as\n      // `unknown`; the substrate's `migrate` callback is the boundary parse.\n      return JSON.parse(raw);\n    },\n    async save(state: S): Promise<void> {\n      await mkdir(dirname(path), { recursive: true });\n      // Write to a pid-scoped temp then atomically rename. The rename gives\n      // torn-write safety (a reader sees the old file or the new one, never a\n      // partial) and survives process crash / Ctrl-C — the only failure a local\n      // resumable run resumes from. fsync (file + dir) would add power-loss\n      // durability the use case doesn't need; the substrate serializes saves\n      // through run()'s queue, so there's never a second concurrent writer.\n      const tmp = `${path}.${process.pid}.tmp`;\n      await writeFile(tmp, JSON.stringify(state), \"utf8\");\n      await rename(tmp, path);\n    },\n    migrate(raw: unknown): S | null {\n      return parse(raw);\n    },\n  };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// NodeSub — the three node-native subscription variants.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * A node WebSocket sub. The substrate diffs subs by `id`; the same `id` across\n * transitions = the same socket (kept open). Emit a DIFFERENT `id` to force a\n * reconnect.\n *\n * Only `onMessage` returns `M | null` (null drops the frame) because inbound\n * frames are the boundary that needs a parse-and-maybe-discard seam. `onOpen`/\n * `onClose`/`onError` always dispatch — a spurious one is dropped in the reducer\n * (the cell ignores it), not here.\n */\nexport type NodeWsSub<M> = {\n  id: SubId;\n  type: \"node_ws\";\n  url: string;\n  onMessage: (data: string) => M | null;\n  onOpen?: () => M;\n  onClose?: (code: number, reason: string) => M;\n  onError?: (message: string) => M;\n};\n\n/**\n * A node timer sub. One-shot `setTimeout` by default; `repeat: true` →\n * `setInterval`. Cleanup clears the timer — a timer keyed to a phase is\n * cancelled the moment the machine leaves that phase.\n */\nexport type NodeTimerSub<M> = {\n  id: SubId;\n  type: \"node_timer\";\n  delayMs: number;\n  msg: M;\n  repeat?: boolean;\n};\n\n/**\n * A process-signal sub: `signal` (SIGINT/SIGTERM/…) → `msg`. Cleanup detaches\n * the listener. Lets graceful shutdown be a real machine transition rather than\n * an out-of-band `process.on` that the reducer can't see.\n */\nexport type NodeSignalSub<M> = {\n  id: SubId;\n  type: \"node_signal\";\n  signal: NodeJS.Signals;\n  msg: M;\n};\n\nexport type NodeSub<M> = NodeWsSub<M> | NodeTimerSub<M> | NodeSignalSub<M>;\n\n// Compile-time guarantee: `NodeSub<M>` is structurally a `Sub` (has `id`+`type`).\n// Erased at runtime — the `extends Sub` constraint on the alias's type\n// parameter fails to compile if `NodeSub` ever drifts off the `Sub` shape.\nexport type AssertNodeSubIsSub<T extends Sub = NodeSub<unknown>> = T;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Ctx — what the node Subs read / populate.\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type NodeWsRegistry = Map<SubId, WebSocket>;\n\n/**\n * The Ctx fields the node Subs depend on. A consumer's Ctx must extend this so\n * `node_ws` can register the live socket and Cmd handlers can reach it.\n *\n * Deliberately NOT parameterized by Msg: the registry holds raw `WebSocket`s,\n * and each Sub variant carries its own Msg-typed callbacks. Trip-wire: if a\n * future node Sub holds a Msg-typed callback on ctx, this becomes\n * `NodeSubscribeCtx<M>`.\n */\nexport interface NodeSubscribeCtx {\n  wsRegistry: NodeWsRegistry;\n}\n\n/**\n * Write a frame to a registered `node_ws` socket. No-op (returns `false`) when\n * the socket is absent, not OPEN, or `send()` throws. The Cmd-side companion to\n * the `node_ws` Sub: the Sub owns the socket's lifetime; this writes to it.\n *\n * The contract is a boolean no-op, never a throw: the socket can transition out\n * of OPEN between the `readyState` check and `send()` (or `ws` can throw on an\n * errored underlying connection), and a Cmd interpreter must not crash on that.\n */\nexport function sendToWebSocket(\n  ctx: NodeSubscribeCtx,\n  id: SubId,\n  data: string,\n): boolean {\n  const socket = ctx.wsRegistry.get(id);\n  if (!socket || socket.readyState !== WebSocket.OPEN) return false;\n  try {\n    socket.send(data);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// nodeSubscribe — the handler registry.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Build the `subscribe` handlers for `node_ws`, `node_timer`, and\n * `node_signal`. Matches `Machine#subscribe`'s\n * `[K in U[\"type\"]]: (sub, ctx, dispatch) => () => void` contract for the\n * `NodeSub<M>` variants. Generic `Ctx` must extend `NodeSubscribeCtx` so the\n * `node_ws` handler can register its socket.\n */\nexport function nodeSubscribe<M, Ctx extends NodeSubscribeCtx>(): {\n  node_ws: (\n    sub: NodeWsSub<M>,\n    ctx: Ctx,\n    dispatch: (msg: M) => void,\n  ) => () => void;\n  node_timer: (\n    sub: NodeTimerSub<M>,\n    ctx: Ctx,\n    dispatch: (msg: M) => void,\n  ) => () => void;\n  node_signal: (\n    sub: NodeSignalSub<M>,\n    ctx: Ctx,\n    dispatch: (msg: M) => void,\n  ) => () => void;\n} {\n  return {\n    node_ws: (sub, ctx, dispatch) => {\n      const socket = new WebSocket(sub.url);\n      ctx.wsRegistry.set(sub.id, socket);\n\n      socket.on(\"open\", () => {\n        if (sub.onOpen) dispatch(sub.onOpen());\n      });\n      socket.on(\"message\", (data: RawData) => {\n        const msg = sub.onMessage(data.toString());\n        if (msg !== null) dispatch(msg);\n      });\n      socket.on(\"close\", (code: number, reason: Buffer) => {\n        if (sub.onClose) dispatch(sub.onClose(code, reason.toString()));\n      });\n      socket.on(\"error\", (err: Error) => {\n        if (sub.onError) dispatch(sub.onError(err.message));\n      });\n\n      return () => {\n        ctx.wsRegistry.delete(sub.id);\n        socket.removeAllListeners();\n        // Swallow teardown-induced errors: terminate()-ing a CONNECTING socket\n        // emits an 'error' (\"closed before the connection was established\"),\n        // and with our listeners gone that would be an unhandled 'error' that\n        // crashes the process. A no-op listener absorbs it.\n        socket.on(\"error\", () => {});\n        // Close for ANY non-closed state: a graceful 1000 when OPEN, a hard\n        // terminate() otherwise (CONNECTING/CLOSING) so a socket caught mid-\n        // handshake can't dangle. This is the teardown the hand-driven Cmd-pair\n        // approach (`cleanup_browser` closing the ws only `if OPEN`) could not\n        // guarantee.\n        if (socket.readyState === WebSocket.OPEN) {\n          socket.close(1000, \"tea-node sub cleanup\");\n        } else if (socket.readyState !== WebSocket.CLOSED) {\n          socket.terminate();\n        }\n      };\n    },\n\n    node_timer: (sub, _ctx, dispatch) => {\n      // Two reconcile lifecycles under one variant: a one-shot (`setTimeout`)\n      // that `subscriptions(state)` should drop on the render after it fires,\n      // vs a repeating (`setInterval`) one the state keeps listing across\n      // renders. Same Sub.type; the `repeat` flag picks the install + cleanup.\n      if (sub.repeat) {\n        const handle = setInterval(() => dispatch(sub.msg), sub.delayMs);\n        return () => clearInterval(handle);\n      }\n      const handle = setTimeout(() => dispatch(sub.msg), sub.delayMs);\n      return () => clearTimeout(handle);\n    },\n\n    node_signal: (sub, _ctx, dispatch) => {\n      const handler = () => dispatch(sub.msg);\n      process.on(sub.signal, handler);\n      return () => {\n        process.off(sub.signal, handler);\n      };\n    },\n  };\n}\n"]}

package/dist/paginated-walk/index.d.ts

@@ -0,0 +1,234 @@
+import { C as Cmd } from '../core-BoB6t7dB.js';
+import { PaginatorState } from '../paginator/index.js';
+import { CircuitConfig, RateLimitConfig, DeadlineConfig, ResilientState, RunCmd, SucceedMsg, FailMsg, ResilientTimerMsg, ResilientPorts } from '../resilient-call/index.js';
+import { RetryPolicy } from '../retry-backoff/index.js';
+import { DeadlineSub } from '../deadline/index.js';
+export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
+import '../cache/index.js';
+import '../types-B-8bcAp8.js';
+import '../circuit-breaker/index.js';
+import '../protocol-B5YmJr0d.js';
+import '../rate-limit/index.js';
+
+/**
+ * @demlik/tea/paginated-walk — traverse a paginated API / sitemap end to end
+ * WITHOUT a fake clock, without 429s, and resumable across a Durable-Object
+ * eviction. The L2 composition that bolts `../resilient-call`'s resilience onto
+ * `../paginator`'s cursor walk: each page is fetched as ONE keyed resilient
+ * call (retry + backoff + rate-limit gate), and the cursor advances only once a
+ * page settles `ok`.
+ *
+ * ## The recipe (the two siblings it composes)
+ *
+ *   - **`../paginator`** owns the walk loop: the opaque `Cursor`, the `seen` /
+ *     `pages` counters, and the `idle → fetching → … → done` phase machine.
+ *     `paginated-walk` never re-implements cursor advancement — it folds each
+ *     settled page through `recordPage`, letting the paginator decide
+ *     `done` / `fetching(next)` / `paused`. Backpressure is a TWO-way valve:
+ *     `recordPage` parks the walk in `paused` once `seen >= highWaterMark`, and
+ *     the `drain` / `resume` verbs (delegating to the paginator's own
+ *     `drain` / `resume`) lower the gauge and re-open the parked fetch — without
+ *     them `highWaterMark` would be a one-way valve that strands a paused walk.
+ *   - **`../resilient-call`** owns the page fetch: the single `resilient_run`
+ *     effect per page is gated through that knob's cache → circuit → rate-limit
+ *     → retry pipeline. A transient page failure backs off and re-issues the
+ *     SAME cursor (idempotent retry); the walk does not advance until the page
+ *     genuinely settles.
+ *
+ * Those are the only two siblings this module calls into. The resilience knobs
+ * (`retry` / `circuit` / `rateLimit` / `deadline`) are NOT separate bricks
+ * `paginated-walk` composes — they belong to `resilient-call`, which owns the
+ * rate-limit gate internally. This module merely passes them through to
+ * `createResilientCall` and re-uses two config TYPES at the boundary:
+ * `RateLimitConfig` (re-exported by `resilient-call`) and `RetryPolicy` (from
+ * `../retry-backoff`). Pass a `rateLimit` and `resilient-call`'s token bucket
+ * throttles page fetches ("don't 429 the upstream"); omit it and the walk runs
+ * as fast as the upstream answers.
+ *
+ * Because the page-fetch resilience IS a `resilient-call` slice, this knob
+ * **inherits that knob's contract verbatim**: the slice is a flat record, every
+ * verb returns `readonly [State, Cmd[]]`, time is always an `at` parameter, and
+ * the jitter RNG is injected once at `createPaginatedWalk(config, rng)` — never
+ * read inside a verb (per the spec, `paginated-walk` *extends* `resilient-call`).
+ *
+ * ## The two non-negotiables (canon)
+ *
+ *   - **Durable** — the slice is plain data: the paginator phase + counters, and
+ *     the resilient-call brick states (all JSON-serializable). The cursor lives
+ *     in the Model, not a closure, so a walk survives eviction mid-traversal and
+ *     resumes from the exact page it was fetching.
+ *   - **Replayable** — every transition is a verb returning new state + Cmds.
+ *     `nextCursor` / `onPage` are pure config functions applied at the verb
+ *     boundary; the Cmds they yield are plain data. `replay` reconstructs the
+ *     whole walk exactly.
+ *
+ * ## Where the clock / RNG live
+ *
+ * Inside the verbs: nowhere. `at` arrives on `start` / `pageOk` / `pageErr` /
+ * `onTimer` and is threaded straight into the underlying resilient-call gate (so
+ * a rate-limited or retried page measures backoff from that `at`). The jitter
+ * RNG is injected at construction. The only clock read is `Date.now()` inside
+ * the resilient-call `handlers` port (the effect boundary), inherited unchanged.
+ *
+ * ## The fixed fetch key
+ *
+ * A walk fetches one page at a time, so the resilient-call layer tracks exactly
+ * one logical call under the constant key `PAGE_KEY`. The cursor being fetched
+ * is the resilient call's `input`, so a post-eviction resume re-issues the same
+ * page request. (`resilient-call` is keyed to support N concurrent calls; a walk
+ * deliberately uses a single key — the paginator is the sequencer.)
+ *
+ * ## Typical wiring
+ *
+ *   const walk = createPaginatedWalk<PageToken, ApiPage>({
+ *     firstPage: null,                          // the API's "page one" sentinel
+ *     nextCursor: (page) => page.nextToken ?? null,
+ *     onPage: (page) => [{ type: "index_rows", rows: page.items }],
+ *     rateLimit: { capacity: 10, refillPerSec: 5 },
+ *     retry: defaultRetryPolicy,
+ *   });
+ *
+ *   // in the machine:
+ *   init: () => [{ walk: walk.init() }, []],
+ *   update: {
+ *     start:    (s, m)  => lift(s, walk.start(s.walk, m.at)),
+ *     page_ok:  (s, m)  => lift(s, walk.pageOk(s.walk, m.result, m.at)),
+ *     page_err: (s, m)  => lift(s, walk.pageErr(s.walk, m.error, m.at)),
+ *     retry_due:(s, m)  => lift(s, walk.onTimer(s.walk, m)),
+ *     drained:  (s, m)  => lift(s, walk.drain(s.walk, m.n)),
+ *     resume:   (s, m)  => lift(s, walk.resume(s.walk, m.at)),
+ *   },
+ *   subscriptions: (s) => walk.subs(s.walk),
+ *   subscribe: { deadline: subscribeDeadline },
+ *   interpret: walk.handlers({ run: (cursor) => api.fetchPage(cursor) }),
+ */
+
+/**
+ * The paginated-walk knob. Generic in `Cursor` (the opaque page handle the
+ * upstream API hands back — offset, page token, "next" URL, …) and `Page` (the
+ * shape your fetch port resolves with).
+ *
+ * `nextCursor` and `onPage` are PURE config functions applied at the verb
+ * boundary, never stored in the slice or in a Cmd (invariant 3 — Cmds are
+ * plain data, not closures). `nextCursor(page)` extracts the API's next-page
+ * handle (or `null` at the end); `onPage(page)` yields the Cmds the consumer
+ * wants emitted for each successfully fetched page (index rows, write to R2,
+ * dispatch a downstream Msg — whatever; an empty array is fine).
+ *
+ * The resilience bricks (`retry` / `circuit` / `rateLimit` / `deadline`) are
+ * the SAME optional knobs `resilient-call` exposes — paginated-walk extends it.
+ * `rateLimit` is the brick that keeps the walk from 429-ing the upstream.
+ */
+interface PaginatedWalkConfig<Cursor, Page, EmittedCmd extends Cmd> {
+    /**
+     * The cursor the walk fetches first. For an offset API this is typically `0`;
+     * for a token API, whatever sentinel the API treats as "page one" (often
+     * `null` or `""`). Threaded into `paginator`'s `firstCursor`.
+     */
+    readonly firstPage: Cursor;
+    /**
+     * Extract the next cursor from a just-fetched page. Return a `Cursor` to keep
+     * walking, or `null` when the API signalled the end (the walk finishes). PURE
+     * + consumer-specific (only the consumer knows the API's pagination shape).
+     */
+    readonly nextCursor: (page: Page) => Cursor | null;
+    /**
+     * The Cmds to emit for each successfully fetched page — the consumer's work
+     * per page (index, persist, fan out, …). Returns plain-data Cmds; `[]` is a
+     * valid "I process the page synchronously elsewhere" answer. PURE.
+     */
+    readonly onPage: (page: Page) => readonly EmittedCmd[];
+    /**
+     * How many items a page contributes to the paginator's backpressure gauge
+     * (`seen`). Defaults to `1` per page (count pages, not items) when omitted; a
+     * consumer that wants per-item backpressure returns `page.items.length`. PURE.
+     */
+    readonly pageSize?: (page: Page) => number;
+    /**
+     * Backpressure threshold handed to the paginator. `seen >= highWaterMark`
+     * parks the walk in `paused` instead of fetching the next page. Non-positive
+     * (the default `0`) disables backpressure — the walk runs flat out until the
+     * API exhausts. See `../paginator`'s `highWaterMark` docs.
+     */
+    readonly highWaterMark?: number;
+    /** Exponential-backoff retry policy for a transient page-fetch failure. */
+    readonly retry?: RetryPolicy;
+    /** Circuit breaker around the page fetch (one upstream → one breaker). */
+    readonly circuit?: CircuitConfig;
+    /** Token-bucket rate limit — the "don't 429 the upstream" knob. */
+    readonly rateLimit?: RateLimitConfig;
+    /** Overall wall-clock deadline per individual page fetch. */
+    readonly deadline?: DeadlineConfig;
+}
+/**
+ * The slice. `walk` is the cursor/phase/counters from `../paginator`;
+ * `resilience` is the `../resilient-call` slice that gates the page fetch.
+ * Every field is JSON-serializable, so the whole walk survives a reload.
+ *
+ * The two move in lockstep: `walk` decides WHICH cursor to fetch next, while
+ * `resilience` decides HOW that fetch is attempted (gated, retried, backed
+ * off). `pageOk` advances `walk`; `pageErr` defers to `resilience` and leaves
+ * `walk` parked on the same cursor until the page truly settles.
+ */
+interface PaginatedWalkState<Cursor, Page> {
+    readonly walk: PaginatorState<Cursor>;
+    readonly resilience: ResilientState<Cursor, Page>;
+}
+/**
+ * The page-fetch effect this knob emits: the inherited `resilient_run` Cmd from
+ * resilient-call, whose `input` is the `Cursor` to fetch and whose `key` is the
+ * fixed `PAGE_KEY`. The consumer's `handlers(ports)` interprets it.
+ */
+type FetchPageCmd<Cursor> = RunCmd<Cursor>;
+/** Page-settled Msgs the `handlers` port dispatches back (inherited verbatim). */
+type PageOkMsg<Page> = SucceedMsg<Page>;
+type PageErrMsg = FailMsg;
+/** The retry / deadline timer Msg — inherited from resilient-call. */
+type PaginatedWalkTimerMsg = ResilientTimerMsg;
+/**
+ * Ports the consumer supplies to `handlers`. `run(cursor)` fetches ONE page for
+ * the given cursor; throwing routes to `pageErr` (and thus the resilience
+ * backoff). Same shape as resilient-call's port, specialized to the page fetch.
+ */
+interface PaginatedWalkPorts<Cursor, Page> extends ResilientPorts<Cursor, Page> {
+}
+/** The single resilient-call key every page fetch runs under. */
+declare const PAGE_KEY = "page";
+/**
+ * Build a paginated-walk knob from `config`. `rng` is injected for the
+ * underlying retry jitter — pass a fixed `() => 0` in tests to pin backoff;
+ * defaults to `Math.random` (read at the verb boundary inside resilient-call,
+ * never in a `paginated-walk` verb). Inherited straight from resilient-call.
+ *
+ * Returns the uniform L2 knob contract: `init()`, the verbs `start` / `pageOk`
+ * / `pageErr` / `onTimer`, `subs(state)`, and `handlers(ports)`. `Cursor` is
+ * the page handle, `Page` the fetch result, `EmittedCmd` the consumer's
+ * per-page Cmds plus the inherited `FetchPageCmd`.
+ */
+declare function createPaginatedWalk<Cursor, Page, EmittedCmd extends Cmd = Cmd>(config: PaginatedWalkConfig<Cursor, Page, EmittedCmd>, rng?: () => number): {
+    init: () => PaginatedWalkState<Cursor, Page>;
+    start: (s: PaginatedWalkState<Cursor, Page>, at: number) => readonly [PaginatedWalkState<Cursor, Page>, readonly (EmittedCmd | FetchPageCmd<Cursor>)[]];
+    pageOk: (s: PaginatedWalkState<Cursor, Page>, page: Page, at: number) => readonly [PaginatedWalkState<Cursor, Page>, readonly (EmittedCmd | FetchPageCmd<Cursor>)[]];
+    pageErr: (s: PaginatedWalkState<Cursor, Page>, error: unknown, at: number) => readonly [PaginatedWalkState<Cursor, Page>, readonly (EmittedCmd | FetchPageCmd<Cursor>)[]];
+    onTimer: (s: PaginatedWalkState<Cursor, Page>, msg: PaginatedWalkTimerMsg) => readonly [PaginatedWalkState<Cursor, Page>, readonly (EmittedCmd | FetchPageCmd<Cursor>)[]];
+    drain: (s: PaginatedWalkState<Cursor, Page>, n: number) => readonly [PaginatedWalkState<Cursor, Page>, readonly (EmittedCmd | FetchPageCmd<Cursor>)[]];
+    resume: (s: PaginatedWalkState<Cursor, Page>, at: number) => readonly [PaginatedWalkState<Cursor, Page>, readonly (EmittedCmd | FetchPageCmd<Cursor>)[]];
+    isComplete: (s: PaginatedWalkState<Cursor, Page>) => boolean;
+    failure: (s: PaginatedWalkState<Cursor, Page>) => unknown;
+    isStuck: (s: PaginatedWalkState<Cursor, Page>) => boolean;
+    subs: (s: PaginatedWalkState<Cursor, Page>) => readonly DeadlineSub[];
+    handlers: (ports: PaginatedWalkPorts<Cursor, Page>) => {
+        resilient_run: (cmd: RunCmd<Cursor>, ctx: Readonly<Record<never, never>>) => Promise<FailMsg | SucceedMsg<Page>>;
+    };
+};
+/**
+ * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the slice
+ * lives at `state.walk`. A convenience for the common single-slice host;
+ * consumers with a differently-named field spread by hand. Pure — a thin record
+ * rebuild, no clock / RNG.
+ */
+declare function liftWalk<S extends {
+    walk: PaginatedWalkState<Cursor, Page>;
+}, Cursor, Page, C extends Cmd>(state: S, [slice, cmds]: readonly [PaginatedWalkState<Cursor, Page>, readonly C[]]): readonly [S, readonly C[]];
+
+export { DeadlineSub, type FetchPageCmd, PAGE_KEY, type PageErrMsg, type PageOkMsg, type PaginatedWalkConfig, type PaginatedWalkPorts, type PaginatedWalkState, type PaginatedWalkTimerMsg, createPaginatedWalk, liftWalk };

package/dist/paginated-walk/index.js

@@ -0,0 +1,15 @@
+export { PAGE_KEY, createPaginatedWalk, liftWalk } from '../chunk-5DEQ5I3U.js';
+import '../chunk-SINXE47Y.js';
+import '../chunk-27N2SPTN.js';
+import '../chunk-JELSZN25.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-K7Q23EQ4.js';
+import '../chunk-5VNWZADP.js';
+import '../chunk-2YOE5PIS.js';
+import '../chunk-SC3FAFZN.js';
+import '../chunk-IN33Q4VJ.js';
+import '../chunk-NSDFA6M6.js';
+import '../chunk-2YFLOCWX.js';
+import '../chunk-MMH7CW5K.js';
+import '../chunk-QLA76GIT.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/paginated-walk/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}