@demlik/tea 0.13.0 → 0.15.0

package/dist/{snapshot/index.d.ts → index-ZCMhnVKN.d.ts}

@@ -1,75 +1,4 @@
-import { C as Cmd, I as Interpret } from '../core-Co0LWkIA.js';
-import 'zod';
-
-/**
- * @demlik/tea/snapshot — periodic state checkpoint to a host store (R2/KV-shaped).
- *
- * The problem it solves: a long-running machine (a multi-stage run, a paginated
- * crawl, a saga) lives in TEA's in-memory `State` and is persisted as ONE blob
- * by the substrate's `Store<S>` on every transition. That blob is fine for
- * crash recovery of the *runtime* — but it is NOT a coarse, named checkpoint a
- * human (or a separate recovery job) can point a restart at. `snapshot` adds
- * the "every N units of progress, write a durable checkpoint to R2/KV"
- * discipline on top, so a crashed long run restarts from the last checkpoint
- * instead of from zero (the field-guide pain row).
- *
- * Shape: this is the same knob contract every L2 composition follows —
- * `createSnapshot(config)` hands back a `{ init, <verbs>, handlers }` bundle you
- * splice into your machine. The state it owns is a Model slice (durable +
- * replayable, the two non-negotiables); the verbs are PURE decisions; the I/O
- * (the actual `put` to the store) lives only in `handlers`.
- *
- * It is a LEAF module: it imports only the core substrate (`../index`, for
- * `Cmd` / `Interpret`) and no sibling subpath. (It does NOT reuse
- * `@demlik/tea/retry-backoff` — that is an even-leafier utility that depends on
- * nothing at all, not even the core; the kinship here is "leaf with injected
- * time", not a shared dependency.)
- * Nothing here reads the clock or the RNG on its own behalf — time enters as an
- * `at`/`now` parameter at the verb boundary and the store I/O is realized only
- * when the runtime performs the emitted `Cmd`. That keeps every verb
- * deterministic (invariant 2) and the checkpoint write a `Cmd` the runtime
- * interprets (invariant 3).
- *
- * The Store port is deliberately ABSTRACT — `{ get, put }`, the lowest common
- * shape of R2 and KV — so this module never imports `@cloudflare/workers-types`
- * and can be checkpointed to anything (R2, KV, a DO sub-key, an in-memory map in
- * tests). The host binds the concrete adapter at `handlers({ store })`.
- *
- * Typical wiring:
- *
- *   const snap = createSnapshot<RunState>({ every: 25, key: "run/checkpoint" });
- *
- *   // machine state:
- *   type State = { run: RunState; snapshot: SnapshotState };
- *   init: (loaded) => loaded ? [loaded, []] : [{ run: initRun(), snapshot: snap.init() }, []],
- *
- *   // in `update`, on each progress Msg, fold the snapshot slice:
- *   progress: (s, msg) => {
- *     const run = advance(s.run, msg);
- *     const [snapshot, cmds] = snap.record(s.snapshot, run, msg.at);
- *     return [{ ...s, run, snapshot }, cmds];
- *   },
- *   // the write completed → durable ack folds back through update:
- *   snapshot_saved: (s, msg) => {
- *     const [snapshot, cmds] = snap.confirm(s.snapshot, msg);
- *     return [{ ...s, snapshot }, cmds];
- *   },
- *
- *   // RECOVERY — the half that makes a checkpoint a restart point, not just a
- *   // backup. A `boot` Msg the host dispatches once after `run(...)` asks the
- *   // store for the durable checkpoint; the answer folds the recovered payload
- *   // back into the run slice:
- *   boot: (s) => snap.requestLoad(s),                       // emits snapshot_load Cmd
- *   snapshot_loaded: (s, msg) => {
- *     if (msg.payload === null) return [s, []];             // no checkpoint → keep fresh init
- *     const [snapshot, cmds] = snap.boot(s.snapshot);
- *     return [{ ...s, run: msg.payload, snapshot }, cmds];
- *   },
- *   snapshot_load_failed: (s) => [s, []],                   // errors are data — decide here
- *
- *   // splice the I/O — both effect cells (write + load):
- *   interpret: { ...snap.handlers({ store: r2Adapter }) },
- */
+import { a as CmdOf, b as CmdDef, C as Cmd, I as Interpret } from './core-DnzqWy6u.js';
 
 /**
  * The snapshot knob.
@@ -163,13 +92,20 @@ interface SnapshotPorts<V> {
  * 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.
  */
-type SnapshotWriteCmd<V> = Cmd<"snapshot_write"> & {
+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
@@ -204,9 +140,10 @@ type SnapshotFailedMsg = {
  * 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.
  */
-type SnapshotLoadCmd = Cmd<"snapshot_load"> & {
-    readonly key: string;
-};
+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
@@ -332,4 +269,4 @@ interface SnapshotKnob<V> {
  */
 declare function createSnapshot<V>(config: SnapshotConfig): SnapshotKnob<V>;
 
-export { type SnapshotConfig, type SnapshotFailedMsg, type SnapshotKnob, type SnapshotLoadCmd, type SnapshotLoadFailedMsg, type SnapshotLoadedMsg, type SnapshotPorts, type SnapshotSavedMsg, type SnapshotState, type SnapshotStore, type SnapshotWriteCmd, createSnapshot, snapshotFailed, snapshotLoadFailed, snapshotLoaded, snapshotSaved };
+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 };