@demlik/tea 0.14.0 → 0.16.0

package/dist/index-DMCeMPMJ.d.ts

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