@demlik/tea 0.1.1 → 0.2.0

package/dist/poller/index.d.ts

@@ -1,8 +1,8 @@
 import { DeadlineSub } from '../deadline/index.js';
 import { IdempotencyStore } from '../idempotency/index.js';
-import { C as Cmd, S as Sub } from '../core-CymXZCeY.js';
+import { C as Cmd, S as Sub } from '../core-BmlJOvxM.js';
 import { RetryPolicy, RetryState } from '../retry-backoff/index.js';
-import '../types-N9LZbdnr.js';
+import '../types-BoUWgwSm.js';
 
 /**
  * @demlik/tea/poller — "poll a source every N ms until a predicate holds, with

package/dist/poller/index.js

@@ -1,10 +1,10 @@
-import { deadlineSub } from '../chunk-QGZW4W3E.js';
+import { deadlineSub } from '../chunk-SKAMZKTE.js';
 import { asRng, defaultRetryPolicy, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-5VNWZADP.js';
 import { idempotencyMemory } from '../chunk-BYQUGDD3.js';
 import '../chunk-K575PT4S.js';
 import '../chunk-2YFLOCWX.js';
-import '../chunk-2WZHS4P2.js';
-import '../chunk-BNJYE4AU.js';
+import '../chunk-6VDCTR7N.js';
+import '../chunk-DYRKDCJI.js';
 
 // src/poller/index.ts
 function pollerSubId(atMs) {

package/dist/prediction/index.d.ts

@@ -1,4 +1,4 @@
-import { C as Cmd, S as Sub, M as Machine } from '../core-CymXZCeY.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-BmlJOvxM.js';
 
 /**
  * @demlik/tea/prediction — the client-prediction ack primitive (epic #186, facet 2).
@@ -56,6 +56,27 @@ interface Ack {
 }
 /** Construct an `Ack` for a last-applied sequence number. */
 declare const ack: (lastAppliedSeq: Seq) => Ack;
+/**
+ * The "nothing applied yet" cursor — the ack value for a server that has applied
+ * no client input at all. Because `nextSeq` mints **0-based** seqs and
+ * `partitionByAck` acks **inclusively** (`seq <= lastAppliedSeq`), the pre-first
+ * cursor must sit strictly *below* seq 0: `lastAppliedSeq = 0` would falsely ack
+ * the seq-0 input before the server ever saw it. `-1` is "before any seq", and
+ * `partitionByAck(buffer, NO_ACK)` therefore leaves the whole buffer PENDING.
+ *
+ * This names the boundary value on the seam so no consumer has to re-discover it
+ * as a magic number: it is the primitive's own design (0-based mint + inclusive
+ * partition) that creates the trap, so it is the primitive's job to name the
+ * escape. Pair with {@link initAck} when an {@link Ack} is wanted instead of the
+ * bare `Seq`.
+ */
+declare const NO_ACK: Seq;
+/**
+ * The `Ack` for a server that has applied nothing yet — `ack(NO_ACK)`. The `Ack`
+ * counterpart to the {@link NO_ACK} `Seq` sentinel, for a consumer that carries
+ * an `Ack` rather than a bare `lastAppliedSeq`.
+ */
+declare const initAck: () => Ack;
 /** The result of splitting a seq-tagged buffer against an ack. */
 interface AckPartition<T> {
     /** Inputs the authoritative side has applied (`seq <= lastAppliedSeq`). */
@@ -106,4 +127,4 @@ declare function reconcile<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, authoritativeState: S, lastAppliedSeq: Ack | Seq, pending: readonly SeqTagged<M>[]): S;
 
-export { type Ack, type AckPartition, type Seq, type SeqTagged, ack, nextSeq, partitionByAck, reconcile, tagSeq };
+export { type Ack, type AckPartition, NO_ACK, type Seq, type SeqTagged, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq };

package/dist/prediction/index.js

@@ -1,4 +1,4 @@
-export { ack, nextSeq, partitionByAck, reconcile, tagSeq } from '../chunk-RVU3RBE6.js';
-import '../chunk-BNJYE4AU.js';
+export { NO_ACK, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq } from '../chunk-G2U7DJHL.js';
+import '../chunk-DYRKDCJI.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/pure/index.d.ts

@@ -1,2 +1,2 @@
-export { Ack, AckPartition, Seq, SeqTagged, ack, nextSeq, partitionByAck, reconcile, tagSeq } from '../prediction/index.js';
-export { C as Cmd, b as ContextFree, I as Interpret, M as Machine, N as NoCtx, P as Port, c as PortEmitter, R as Reducer, S as Sub, a as SubId, d as Subscribe, e as SyncReturn, T as Transitions, U as UpdateForm, f as detectUpdateForm, g as foldMsgs, h as formOf, s as subId } from '../core-CymXZCeY.js';
+export { Ack, AckPartition, NO_ACK, Seq, SeqTagged, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq } from '../prediction/index.js';
+export { C as Cmd, b as ContextFree, I as Interpret, M as Machine, j as NoCellError, N as NoCtx, P as Port, c as PortEmitter, R as Reducer, S as Sub, a as SubId, d as Subscribe, e as SyncReturn, T as Transitions, U as UpdateForm, g as detectUpdateForm, h as foldMsgs, i as formOf, s as subId } from '../core-BmlJOvxM.js';

package/dist/pure/index.js

@@ -1,4 +1,4 @@
-export { ack, nextSeq, partitionByAck, reconcile, tagSeq } from '../chunk-RVU3RBE6.js';
-export { Cmd, detectUpdateForm, foldMsgs, formOf, subId } from '../chunk-BNJYE4AU.js';
+export { NO_ACK, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq } from '../chunk-G2U7DJHL.js';
+export { Cmd, NoCellError, detectUpdateForm, foldMsgs, formOf, subId } from '../chunk-DYRKDCJI.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/react/index.d.ts

@@ -1,5 +1,5 @@
 import { Store, Runtime } from '../index.js';
-import { C as Cmd, S as Sub, M as Machine } from '../core-CymXZCeY.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-BmlJOvxM.js';
 
 /**
  * @demlik/tea/react — React host adapter for `@demlik/tea`.

package/dist/react/index.js

@@ -1,6 +1,6 @@
-import { run } from '../chunk-2WZHS4P2.js';
-import '../chunk-BNJYE4AU.js';
-import { useMemo, useRef, useSyncExternalStore, useEffect } from 'react';
+import { run } from '../chunk-6VDCTR7N.js';
+import '../chunk-DYRKDCJI.js';
+import { useMemo, useRef, useReducer, useSyncExternalStore, useEffect } from 'react';
 
 function useMachine(machine, opts) {
   const ctx = opts.ctx;
@@ -10,6 +10,7 @@ function useMachine(machine, opts) {
     [machine, ctx, store]
   );
   const readyRef = useRef(null);
+  const [, markBooted] = useReducer((tick) => tick + 1, 0);
   const preliminaryState = useMemo(
     () => machine.init(null, ctx)[0],
     [machine, ctx]
@@ -24,7 +25,10 @@ function useMachine(machine, opts) {
     let live = true;
     booting.ready.then(
       (r) => {
-        if (live) readyRef.current = r;
+        if (live) {
+          readyRef.current = r;
+          markBooted();
+        }
       },
       () => {
       }

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/react/index.ts"],"names":[],"mappings":";;;;AA+DO,SAAS,UAAA,CAOd,SACA,IAAA,EACgC;AAMhC,EAAA,MAAM,MAAM,IAAA,CAAK,GAAA;AACjB,EAAA,MAAM,QAAQ,IAAA,CAAK,KAAA;AAMnB,EAAA,MAAM,OAAA,GAAU,OAAA;AAAA,IACd,MAAM,GAAA,CAAI,OAAA,EAAS,EAAE,GAAA,EAAK,OAAO,CAAA;AAAA,IACjC,CAAC,OAAA,EAAS,GAAA,EAAK,KAAK;AAAA,GACtB;AAQA,EAAA,MAAM,QAAA,GAAW,OAA6B,IAAI,CAAA;AAalD,EAAA,MAAM,gBAAA,GAAmB,OAAA;AAAA,IACvB,MAAM,OAAA,CAAQ,IAAA,CAAK,IAAA,EAAM,GAAG,EAAE,CAAC,CAAA;AAAA,IAC/B,CAAC,SAAS,GAAG;AAAA,GACf;AAMA,EAAA,MAAM,WAAA,GAAc,MAClB,QAAA,CAAS,OAAA,KAAY,OAAO,QAAA,CAAS,OAAA,CAAQ,UAAS,GAAI,gBAAA;AAE5D,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,OAAA,CAAQ,SAAA;AAAA,IACR,WAAA;AAAA,IACA;AAAA,GACF;AAEA,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,IAAA,GAAO,IAAA;AAOX,IAAA,OAAA,CAAQ,KAAA,CAAM,IAAA;AAAA,MACZ,CAAC,CAAA,KAAM;AACL,QAAA,IAAI,IAAA,WAAe,OAAA,GAAU,CAAA;AAAA,MAC/B,CAAA;AAAA,MACA,MAAM;AAAA,MAAC;AAAA,KACT;AACA,IAAA,OAAO,MAAM;AACX,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,QAAA,CAAS,OAAA,GAAU,IAAA;AAInB,MAAA,OAAA,CAAQ,IAAA,EAAK,CAAE,KAAA,CAAM,MAAM;AAAA,MAAC,CAAC,CAAA;AAAA,IAC/B,CAAA;AAAA,EACF,CAAA,EAAG,CAAC,OAAO,CAAC,CAAA;AAEZ,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC;AAeO,SAAS,WACd,OAAA,EACgC;AAChC,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,OAAA,CAAQ,SAAA;AAAA,IACR,OAAA,CAAQ,QAAA;AAAA,IACR,OAAA,CAAQ;AAAA,GACV;AACA,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC","file":"index.js","sourcesContent":["/**\n * @demlik/tea/react — React host adapter for `@demlik/tea`.\n *\n * The thinnest possible adapter that makes a tea machine consumable from a\n * React component. Three rules (PRD §\"React adapter\"):\n *\n *   1. The runtime is the source of truth, NOT React state. We subscribe via\n *      `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *      runtime.getState)`. React renders are driven by runtime state changes;\n *      React never owns the state.\n *   2. The runtime is memoized per component-mount, not per render. The deps\n *      array is `[machine, opts.ctx, opts.store]` — IDENTITY, not value. See\n *      `README.md` for the ctx-identity footgun + fix.\n *   3. Concurrent React is the design target. `useSyncExternalStore` is the\n *      React-blessed primitive for tearing-free external state.\n *\n * Client-only in v1 — components that call `useMachine` MUST be `\"use client\"`.\n * Server Components consume data via Relay/RSC as today; tea machines own\n * client-side stateful flows. No RSC streaming, no server-side state\n * hydration. Crossing this boundary is a v2 concern.\n */\n\n\"use client\";\n\nimport { useEffect, useMemo, useRef, useSyncExternalStore } from \"react\";\nimport {\n  type BootingRuntime,\n  type Cmd,\n  type Machine,\n  type Runtime,\n  run,\n  type Store,\n  type Sub,\n} from \"../index\";\n\n/**\n * Options passed to `useMachine`. The shape is intentionally minimal — `ctx`\n * is required (every machine has one), `store` is optional (omit it for\n * volatile-state machines).\n *\n * **Identity matters.** The runtime is memoized on `[machine, opts.ctx,\n * opts.store]`. A new `ctx` reference rebuilds the runtime. Always `useMemo`\n * (or otherwise stabilize) the ctx at the call site. See README.\n */\nexport interface UseMachineOpts<S, Ctx> {\n  ctx: Ctx;\n  store?: Store<S>;\n}\n\n/**\n * Build and own a `Runtime<S, M>` for the lifetime of the component mount.\n *\n * - Builds via `useMemo(() => run(machine, opts), [machine, opts.ctx,\n *   opts.store])` — runtime is recreated when ANY of the three identities\n *   change.\n * - Subscribes via `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *   runtime.getState)` — tearing-free under React 18 concurrent rendering.\n * - On unmount (or any dep change), `useEffect` cleanup calls\n *   `runtime.stop()` — drains the queue, runs every active sub cleanup,\n *   flushes state.\n *\n * Returns `[state, dispatch]` shaped like `useReducer`.\n */\nexport function useMachine<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  opts: UseMachineOpts<S, Ctx>,\n): [S, (msg: M) => Promise<void>] {\n  // Deps are literal: machine identity, ctx identity, store identity. NOT\n  // `[opts]` (would rebuild every render — callers pass fresh objects).\n  // We pass explicit fields to `run()` so the closure captures only the\n  // deps in the array — keeps biome's `useExhaustiveDependencies` happy\n  // without lying about what the memo actually depends on.\n  const ctx = opts.ctx;\n  const store = opts.store;\n  // `run()` returns a `BootingRuntime<S, M>` SYNCHRONOUSLY (issue #45) — exactly\n  // what `useMemo` needs. We never `await` here: awaiting would force an async\n  // memo, a null first-commit state, and a resolved-flag dance. Instead we hold\n  // the booting handle and capture the booted `Runtime` (the only thing with a\n  // total `getState`) once `ready` resolves.\n  const booting = useMemo<BootingRuntime<S, M>>(\n    () => run(machine, { ctx, store }),\n    [machine, ctx, store],\n  );\n\n  // Captures the booted `Runtime` once `ready` resolves. Until then it is\n  // `null` and `getSnapshot` serves `preliminaryState`. A ref (not state)\n  // because the booted runtime arrives via a subscription notification, not a\n  // render: `subscribe` fires the boot fanout, React re-reads `getSnapshot`,\n  // and by then `ready` has populated the ref. Reset whenever the booting\n  // handle identity changes (a new machine/ctx/store mount).\n  const readyRef = useRef<Runtime<S, M> | null>(null);\n\n  // Preliminary state computed sync from `machine.init(null, ctx)`. This is\n  // the snapshot React sees BEFORE the runtime finishes booting (matters\n  // only when `opts.store` is present — without a store, the substrate\n  // already sets state synchronously inside `run()`, so the boot fanout that\n  // captures `readyRef` lands on the same microtask as the first commit).\n  //\n  // We deliberately recompute on each render but cache by `[machine,\n  // opts.ctx]` — `init` is pure by convention, so cost is negligible. The\n  // cached snapshot is also identity-stable across rerenders when the deps\n  // don't change, which `useSyncExternalStore` rewards (no spurious\n  // re-renders).\n  const preliminaryState = useMemo<S>(\n    () => machine.init(null, ctx)[0],\n    [machine, ctx],\n  );\n\n  // `getSnapshot` reads the booted runtime if `ready` has resolved (the ref is\n  // populated), else falls back to the preliminary state. No try/catch dance\n  // anymore — pre-boot there is simply no booted `Runtime` to read from, so\n  // the fallback is structural, not exception-driven.\n  const getSnapshot = (): S =>\n    readyRef.current !== null ? readyRef.current.getState() : preliminaryState;\n\n  const state = useSyncExternalStore(\n    booting.subscribe,\n    getSnapshot,\n    getSnapshot,\n  );\n\n  useEffect(() => {\n    let live = true;\n    // Capture the booted runtime when `ready` resolves. The boot fanout\n    // (`fireListeners`) runs as part of boot, so the `useSyncExternalStore`\n    // subscriber is notified right after this ref is set — React re-reads\n    // `getSnapshot` and swaps preliminary → real state with no extra render\n    // plumbing. Boot rejections are swallowed: a failed boot surfaces on every\n    // `dispatch`, which is where the consumer handles it.\n    booting.ready.then(\n      (r) => {\n        if (live) readyRef.current = r;\n      },\n      () => {},\n    );\n    return () => {\n      live = false;\n      readyRef.current = null;\n      // Fire-and-forget — `stop()` is async but `useEffect` cleanup is sync.\n      // The runtime swallows in-flight rejections internally, so this never\n      // rejects in practice; we still attach `.catch` for safety.\n      booting.stop().catch(() => {});\n    };\n  }, [booting]);\n\n  return [state, booting.dispatch];\n}\n\n/**\n * Lower-level escape hatch: consume an externally-built `Runtime<S, M>`.\n *\n * Use this when the runtime is owned by something OTHER than the component —\n * a parent component, a test harness, a singleton. **The component does NOT\n * call `runtime.stop()` on unmount** — the caller owns the lifecycle.\n *\n * Primary use case in this repo: component tests. Build a runtime with\n * `@demlik/tea/mem` and pre-seed it via `replay`, then mount the component with\n * `useRuntime(testRuntime)` to render in any phase.\n *\n * Returns `[state, dispatch]` — same shape as `useMachine`.\n */\nexport function useRuntime<S, M extends { type: string }>(\n  runtime: Runtime<S, M>,\n): [S, (msg: M) => Promise<void>] {\n  const state = useSyncExternalStore(\n    runtime.subscribe,\n    runtime.getState,\n    runtime.getState,\n  );\n  return [state, runtime.dispatch];\n}\n"]}
+{"version":3,"sources":["../../src/react/index.ts"],"names":[],"mappings":";;;;AAqEO,SAAS,UAAA,CAOd,SACA,IAAA,EACgC;AAMhC,EAAA,MAAM,MAAM,IAAA,CAAK,GAAA;AACjB,EAAA,MAAM,QAAQ,IAAA,CAAK,KAAA;AAMnB,EAAA,MAAM,OAAA,GAAU,OAAA;AAAA,IACd,MAAM,GAAA,CAAI,OAAA,EAAS,EAAE,GAAA,EAAK,OAAO,CAAA;AAAA,IACjC,CAAC,OAAA,EAAS,GAAA,EAAK,KAAK;AAAA,GACtB;AAeA,EAAA,MAAM,QAAA,GAAW,OAA6B,IAAI,CAAA;AAClD,EAAA,MAAM,GAAG,UAAU,CAAA,GAAI,WAAW,CAAC,IAAA,KAAiB,IAAA,GAAO,CAAA,EAAG,CAAC,CAAA;AAa/D,EAAA,MAAM,gBAAA,GAAmB,OAAA;AAAA,IACvB,MAAM,OAAA,CAAQ,IAAA,CAAK,IAAA,EAAM,GAAG,EAAE,CAAC,CAAA;AAAA,IAC/B,CAAC,SAAS,GAAG;AAAA,GACf;AAMA,EAAA,MAAM,WAAA,GAAc,MAClB,QAAA,CAAS,OAAA,KAAY,OAAO,QAAA,CAAS,OAAA,CAAQ,UAAS,GAAI,gBAAA;AAE5D,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,OAAA,CAAQ,SAAA;AAAA,IACR,WAAA;AAAA,IACA;AAAA,GACF;AAEA,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,IAAA,GAAO,IAAA;AAMX,IAAA,OAAA,CAAQ,KAAA,CAAM,IAAA;AAAA,MACZ,CAAC,CAAA,KAAM;AACL,QAAA,IAAI,IAAA,EAAM;AACR,UAAA,QAAA,CAAS,OAAA,GAAU,CAAA;AACnB,UAAA,UAAA,EAAW;AAAA,QACb;AAAA,MACF,CAAA;AAAA,MACA,MAAM;AAAA,MAAC;AAAA,KACT;AACA,IAAA,OAAO,MAAM;AACX,MAAA,IAAA,GAAO,KAAA;AACP,MAAA,QAAA,CAAS,OAAA,GAAU,IAAA;AAInB,MAAA,OAAA,CAAQ,IAAA,EAAK,CAAE,KAAA,CAAM,MAAM;AAAA,MAAC,CAAC,CAAA;AAAA,IAC/B,CAAA;AAAA,EACF,CAAA,EAAG,CAAC,OAAO,CAAC,CAAA;AAEZ,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC;AAeO,SAAS,WACd,OAAA,EACgC;AAChC,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,OAAA,CAAQ,SAAA;AAAA,IACR,OAAA,CAAQ,QAAA;AAAA,IACR,OAAA,CAAQ;AAAA,GACV;AACA,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC","file":"index.js","sourcesContent":["/**\n * @demlik/tea/react — React host adapter for `@demlik/tea`.\n *\n * The thinnest possible adapter that makes a tea machine consumable from a\n * React component. Three rules (PRD §\"React adapter\"):\n *\n *   1. The runtime is the source of truth, NOT React state. We subscribe via\n *      `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *      runtime.getState)`. React renders are driven by runtime state changes;\n *      React never owns the state.\n *   2. The runtime is memoized per component-mount, not per render. The deps\n *      array is `[machine, opts.ctx, opts.store]` — IDENTITY, not value. See\n *      `README.md` for the ctx-identity footgun + fix.\n *   3. Concurrent React is the design target. `useSyncExternalStore` is the\n *      React-blessed primitive for tearing-free external state.\n *\n * Client-only in v1 — components that call `useMachine` MUST be `\"use client\"`.\n * Server Components consume data via Relay/RSC as today; tea machines own\n * client-side stateful flows. No RSC streaming, no server-side state\n * hydration. Crossing this boundary is a v2 concern.\n */\n\n\"use client\";\n\nimport {\n  useEffect,\n  useMemo,\n  useReducer,\n  useRef,\n  useSyncExternalStore,\n} from \"react\";\nimport {\n  type BootingRuntime,\n  type Cmd,\n  type Machine,\n  type Runtime,\n  run,\n  type Store,\n  type Sub,\n} from \"../index\";\n\n/**\n * Options passed to `useMachine`. The shape is intentionally minimal — `ctx`\n * is required (every machine has one), `store` is optional (omit it for\n * volatile-state machines).\n *\n * **Identity matters.** The runtime is memoized on `[machine, opts.ctx,\n * opts.store]`. A new `ctx` reference rebuilds the runtime. Always `useMemo`\n * (or otherwise stabilize) the ctx at the call site. See README.\n */\nexport interface UseMachineOpts<S, Ctx> {\n  ctx: Ctx;\n  store?: Store<S>;\n}\n\n/**\n * Build and own a `Runtime<S, M>` for the lifetime of the component mount.\n *\n * - Builds via `useMemo(() => run(machine, opts), [machine, opts.ctx,\n *   opts.store])` — runtime is recreated when ANY of the three identities\n *   change.\n * - Subscribes via `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *   runtime.getState)` — tearing-free under React 18 concurrent rendering.\n * - On unmount (or any dep change), `useEffect` cleanup calls\n *   `runtime.stop()` — drains the queue, runs every active sub cleanup,\n *   flushes state.\n *\n * Returns `[state, dispatch]` shaped like `useReducer`.\n */\nexport function useMachine<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  opts: UseMachineOpts<S, Ctx>,\n): [S, (msg: M) => Promise<void>] {\n  // Deps are literal: machine identity, ctx identity, store identity. NOT\n  // `[opts]` (would rebuild every render — callers pass fresh objects).\n  // We pass explicit fields to `run()` so the closure captures only the\n  // deps in the array — keeps biome's `useExhaustiveDependencies` happy\n  // without lying about what the memo actually depends on.\n  const ctx = opts.ctx;\n  const store = opts.store;\n  // `run()` returns a `BootingRuntime<S, M>` SYNCHRONOUSLY (issue #45) — exactly\n  // what `useMemo` needs. We never `await` here: awaiting would force an async\n  // memo, a null first-commit state, and a resolved-flag dance. Instead we hold\n  // the booting handle and capture the booted `Runtime` (the only thing with a\n  // total `getState`) once `ready` resolves.\n  const booting = useMemo<BootingRuntime<S, M>>(\n    () => run(machine, { ctx, store }),\n    [machine, ctx, store],\n  );\n\n  // Captures the booted `Runtime` once `ready` resolves. Until then it is\n  // `null` and `getSnapshot` serves `preliminaryState`. Reset whenever the\n  // booting handle identity changes (a new machine/ctx/store mount).\n  //\n  // The boot race the paired `bootedTick` bump exists for: the substrate's\n  // boot fanout fires BEFORE `ready` resolves (fireListeners runs inside the\n  // boot step; `ready` chains off the boot promise), so at notification time\n  // this ref is still null and `getSnapshot` returns the same\n  // `preliminaryState` reference — React sees an unchanged snapshot and\n  // skips the re-render. Nothing re-notifies after the ref is set, so a\n  // store-backed mount would stay stuck on the preliminary state until the\n  // next unrelated transition. Bumping a reducer when we capture the booted\n  // runtime forces the render that swaps preliminary → real state.\n  const readyRef = useRef<Runtime<S, M> | null>(null);\n  const [, markBooted] = useReducer((tick: number) => tick + 1, 0);\n\n  // Preliminary state computed sync from `machine.init(null, ctx)`. This is\n  // the snapshot React sees BEFORE the runtime finishes booting (matters\n  // only when `opts.store` is present — without a store, the substrate\n  // already sets state synchronously inside `run()`, so the boot fanout that\n  // captures `readyRef` lands on the same microtask as the first commit).\n  //\n  // We deliberately recompute on each render but cache by `[machine,\n  // opts.ctx]` — `init` is pure by convention, so cost is negligible. The\n  // cached snapshot is also identity-stable across rerenders when the deps\n  // don't change, which `useSyncExternalStore` rewards (no spurious\n  // re-renders).\n  const preliminaryState = useMemo<S>(\n    () => machine.init(null, ctx)[0],\n    [machine, ctx],\n  );\n\n  // `getSnapshot` reads the booted runtime if `ready` has resolved (the ref is\n  // populated), else falls back to the preliminary state. No try/catch dance\n  // anymore — pre-boot there is simply no booted `Runtime` to read from, so\n  // the fallback is structural, not exception-driven.\n  const getSnapshot = (): S =>\n    readyRef.current !== null ? readyRef.current.getState() : preliminaryState;\n\n  const state = useSyncExternalStore(\n    booting.subscribe,\n    getSnapshot,\n    getSnapshot,\n  );\n\n  useEffect(() => {\n    let live = true;\n    // Capture the booted runtime when `ready` resolves, then force the\n    // render that swaps preliminary → real state (see the boot-race note on\n    // `readyRef` — the boot fanout fires too early to do it for us). Boot\n    // rejections are swallowed: a failed boot surfaces on every `dispatch`,\n    // which is where the consumer handles it.\n    booting.ready.then(\n      (r) => {\n        if (live) {\n          readyRef.current = r;\n          markBooted();\n        }\n      },\n      () => {},\n    );\n    return () => {\n      live = false;\n      readyRef.current = null;\n      // Fire-and-forget — `stop()` is async but `useEffect` cleanup is sync.\n      // The runtime swallows in-flight rejections internally, so this never\n      // rejects in practice; we still attach `.catch` for safety.\n      booting.stop().catch(() => {});\n    };\n  }, [booting]);\n\n  return [state, booting.dispatch];\n}\n\n/**\n * Lower-level escape hatch: consume an externally-built `Runtime<S, M>`.\n *\n * Use this when the runtime is owned by something OTHER than the component —\n * a parent component, a test harness, a singleton. **The component does NOT\n * call `runtime.stop()` on unmount** — the caller owns the lifecycle.\n *\n * Primary use case in this repo: component tests. Build a runtime with\n * `@demlik/tea/mem` and pre-seed it via `replay`, then mount the component with\n * `useRuntime(testRuntime)` to render in any phase.\n *\n * Returns `[state, dispatch]` — same shape as `useMachine`.\n */\nexport function useRuntime<S, M extends { type: string }>(\n  runtime: Runtime<S, M>,\n): [S, (msg: M) => Promise<void>] {\n  const state = useSyncExternalStore(\n    runtime.subscribe,\n    runtime.getState,\n    runtime.getState,\n  );\n  return [state, runtime.dispatch];\n}\n"]}

package/dist/reconciler/index.d.ts

@@ -1,6 +1,6 @@
 import { CircuitConfig, RateLimitConfig, DeadlineConfig, ResilientPorts, RunCmd, FailMsg, SucceedMsg } from '../resilient-call/index.js';
 import { TtlCache } from '../cache/index.js';
-import { C as Cmd } from '../core-CymXZCeY.js';
+import { C as Cmd } from '../core-BmlJOvxM.js';
 import { PaginatedWalkState, FetchPageCmd, PageOkMsg, PageErrMsg, PaginatedWalkTimerMsg } from '../paginated-walk/index.js';
 import { RetryPolicy } from '../retry-backoff/index.js';
 import { DeadlineSub } from '../deadline/index.js';
@@ -8,7 +8,7 @@ export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
 import '../circuit-breaker/index.js';
 import '../protocol-B5YmJr0d.js';
 import '../rate-limit/index.js';
-import '../types-N9LZbdnr.js';
+import '../types-BoUWgwSm.js';
 import '../paginator/index.js';
 
 /**

package/dist/reconciler/index.js

@@ -1,16 +1,16 @@
-import { createPaginatedWalk, PAGE_KEY } from '../chunk-IFBQJYGI.js';
+import { createPaginatedWalk, PAGE_KEY } from '../chunk-FOGL3TC7.js';
 import '../chunk-SINXE47Y.js';
-import '../chunk-RVJFGRGK.js';
+import '../chunk-6GIGQT6C.js';
 import '../chunk-JELSZN25.js';
-export { deadlineSub, subscribeDeadline } from '../chunk-QGZW4W3E.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-SKAMZKTE.js';
 import '../chunk-5VNWZADP.js';
 import '../chunk-2YOE5PIS.js';
 import '../chunk-SC3FAFZN.js';
 import { initCache, get, set } from '../chunk-IN33Q4VJ.js';
 import '../chunk-NSDFA6M6.js';
 import '../chunk-2YFLOCWX.js';
-import '../chunk-2WZHS4P2.js';
-import '../chunk-BNJYE4AU.js';
+import '../chunk-6VDCTR7N.js';
+import '../chunk-DYRKDCJI.js';
 
 // src/reconciler/index.ts
 function createReconciler(config, rng = Math.random) {

package/dist/recorder/index.d.ts

@@ -1,5 +1,5 @@
 import { BootingRuntime } from '../index.js';
-import '../core-CymXZCeY.js';
+import '../core-BmlJOvxM.js';
 
 /**
  * A recorded run, sufficient to reproduce it via `../trace-replay`.

package/dist/resilient-call/index.d.ts

@@ -2,12 +2,48 @@ import { TtlCache } from '../cache/index.js';
 import { CircuitState } from '../circuit-breaker/index.js';
 import { DeadlineExceeded, DeadlineSub } from '../deadline/index.js';
 export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
-import { C as Cmd } from '../core-CymXZCeY.js';
+import { C as Cmd } from '../core-BmlJOvxM.js';
 import { M as MsgType } from '../protocol-B5YmJr0d.js';
 import { TokenBucket } from '../rate-limit/index.js';
 import { RetryState, RetryPolicy } from '../retry-backoff/index.js';
-import '../types-N9LZbdnr.js';
+import '../types-BoUWgwSm.js';
 
+/**
+ * @deprecated `@demlik/tea/resilient-call` is deprecated in favor of
+ * `@demlik/tea/with-resilience` — the higher-order `withResilience(base,
+ * config)` wrapper (TEA-idiomatic: it wraps any existing machine instead of
+ * forcing a bespoke embedded slice; epic consolidation verdict, survivor
+ * `with-resilience`). The APIs are NOT drop-in; migration map:
+ *
+ *   - `createResilientCall(config, rng)` + hand-wiring `init` / the verbs /
+ *     `subs` / `handlers` into your machine → `withResilience(base, { target,
+ *     ...bricks }, rng)`. Nothing is wired by hand anymore: the wrapper
+ *     intercepts the `target` base Cmd and routes it through the gate.
+ *   - `ResilientConfig` bricks (`retry` / `circuit` / `rateLimit` / `cache` /
+ *     `deadline`) → unchanged; `ResilienceConfig` extends the same knob and
+ *     adds `target` (required), `keyOf?` (per-call key — was `attempt`'s `key`
+ *     argument), and `at?` (time-as-data reader — REQUIRED with any
+ *     time-sensitive brick; `withResilience` throws at construction without it).
+ *   - The slice at your chosen Model field + `liftResilience` → the wrapper
+ *     owns `model.$resilience`; there is nothing to lift.
+ *   - Verbs `attempt` / `succeed` / `fail` / `onTimer` → internal to the
+ *     wrapper; results route as `$resilience:ok` / `$resilience:err` /
+ *     `$resilience:timer` Msgs through the merged `update` (the old
+ *     `resilient_run` / `resilient_ok` / `resilient_err` vocabulary is renamed
+ *     into the `$resilience:` namespace).
+ *   - `settleFailed` → NO equivalent. It exists for embedded-slice consumers
+ *     (`authed-call`, `paginated-walk`) that settle a call without touching the
+ *     breaker; the wrapper exposes no caller-facing settle verb.
+ *   - `handlers(ports)` / `subs(state)` / the `subscribeDeadline` re-export →
+ *     handled by the wrapper; run the returned machine like any other.
+ *
+ * Removal window ("deprecate, don't delete"): the `./resilient-call` subpath
+ * export survives one minor release after this deprecation ships, then is
+ * removed. Internal sibling modules (`with-resilience` itself, `agent`,
+ * `llm-call`, `authed-call`, `reconciler`, `paginated-walk`) intentionally keep
+ * importing `../resilient-call` — the deprecation targets the PUBLISHED export,
+ * not the module's internal role.
+ */
 /**
  * @demlik/tea/resilient-call — the ROOT composition: a single resilience knob
  * that bundles cache → circuit-breaker → rate-limit → exponential-backoff retry
@@ -225,6 +261,9 @@ interface ResilientPorts<I, R> {
  *
  * Returns the uniform L2 knob contract. `I` is the port input type, `R` the
  * port result type.
+ *
+ * @deprecated Use `withResilience` from `@demlik/tea/with-resilience` — not
+ * drop-in; see the migration map at the top of this module.
  */
 declare function createResilientCall<I, R>(config: ResilientConfig, rng?: () => number): {
     init: () => ResilientState<I, R>;
@@ -243,6 +282,10 @@ declare function createResilientCall<I, R>(config: ResilientConfig, rng?: () =>
  * slice lives at `state.resilience`. 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.
+ *
+ * @deprecated Use `withResilience` from `@demlik/tea/with-resilience` — the
+ * wrapper owns `model.$resilience`, so there is nothing to lift; see the
+ * migration map at the top of this module.
  */
 declare function liftResilience<S extends {
     resilience: ResilientState<I, R>;

package/dist/resilient-call/index.js

@@ -1,13 +1,13 @@
-export { createResilientCall, liftResilience } from '../chunk-RVJFGRGK.js';
+export { createResilientCall, liftResilience } from '../chunk-6GIGQT6C.js';
 import '../chunk-JELSZN25.js';
-export { deadlineSub, subscribeDeadline } from '../chunk-QGZW4W3E.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-SKAMZKTE.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-2WZHS4P2.js';
-import '../chunk-BNJYE4AU.js';
+import '../chunk-6VDCTR7N.js';
+import '../chunk-DYRKDCJI.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/retry-to-success/index.d.ts

@@ -0,0 +1,109 @@
+import { Rng, RetryPolicy } from '../retry-backoff/index.js';
+
+/**
+ * @demlik/tea/retry-to-success — run a fallible async port through BOUNDED
+ * retry + exponential backoff to success-or-terminal-give-up, and hand the
+ * caller a `Promise<R>` that resolves on the first success or REJECTS with a
+ * checkable {@link RetryExhaustedError} the moment the retry bound is hit.
+ *
+ * This is the retry-side parallel to `./await-terminal`. `runToTerminal` gives a
+ * caller with a one-shot decision *machine* a fire-and-await `Promise<State>`
+ * without wiring `observe`; this gives a caller with a one-shot fallible *port*
+ * a fire-and-await `Promise<R>` without either hand-folding the
+ * `./retry-backoff` primitives (`recordFailure` / `shouldRetry` / `nextDelayMs`)
+ * into their own reducer each time, or standing up the full `./resilient-call`
+ * verb contract (`init` + `attempt`/`succeed`/`fail`/`onTimer` + `subs` +
+ * `handlers`) when they want retry only and none of cache / circuit / rate-limit
+ * / deadline.
+ *
+ * It adds NO new runtime capability and NO new backoff math — the whole retry
+ * decision is `./retry-backoff` exactly as `resilient-call`'s `backoff` verb
+ * wires it:
+ *   - `initRetry()` seeds the per-call attempt counter.
+ *   - `recordFailure(retry, error)` folds each thrown failure (attempt++).
+ *   - `shouldRetry(retry, policy)` is the terminal-at-`maxAttempts` bound — the
+ *     `maxAttempts`-th recorded failure refuses another attempt (attempts
+ *     `0 .. maxAttempts-1` run; the port is invoked at most `maxAttempts` times).
+ *   - `nextDelayMs(retry, policy, rng)` is the exp+jitter+cap delay before the
+ *     next attempt, computed on the incremented state — same call order as
+ *     `resilient-call`.
+ *
+ * Where the clock / RNG live: injected, never read on the module's own behalf,
+ * mirroring `retry-backoff`'s purity discipline. `rng` is an {@link Rng} (branded
+ * `[0, 1)` via `asRng` at the caller boundary) threaded straight into
+ * `nextDelayMs`; the wait itself is a `sleep(ms)` port defaulting to a real
+ * `setTimeout`, injectable so a test can drive the backoff schedule
+ * deterministically without touching wall-clock timers.
+ *
+ * Exhaustion is NEVER a silent swallow: at the bound the returned promise
+ * rejects with {@link RetryExhaustedError} (carrying the attempt count and the
+ * final failure), the retry-side dialect of `await-terminal`'s
+ * `TerminalTimeoutError` — a distinct `instanceof`- and `_tag`-checkable
+ * rejection.
+ *
+ * NOT a substrate primitive: it depends on nothing from `../index`, only on the
+ * leaf `../retry-backoff` utility. Callers reach it via the
+ * `@demlik/tea/retry-to-success` subpath.
+ */
+
+/**
+ * Raised when `retryToSuccess` exhausts the retry bound without a success — the
+ * `maxAttempts`-th recorded failure refuses another attempt. Follows the tea
+ * error dialect (`override readonly name`) and carries a `_tag` discriminant, so
+ * a caller can branch on it by `instanceof` or on the tag. It carries the number
+ * of attempts made and the final failure (`lastError`) so the terminal give-up
+ * is a distinct, checkable rejection — never a silent resolve, and never a
+ * swallowed error.
+ */
+declare class RetryExhaustedError extends Error {
+    /** How many times the port was invoked before giving up (= `policy.maxAttempts`). */
+    readonly attempts: number;
+    /** The failure the final attempt threw — carried, never interpreted. */
+    readonly lastError: unknown;
+    readonly name = "RetryExhaustedError";
+    readonly _tag: "RetryExhaustedError";
+    constructor(
+    /** How many times the port was invoked before giving up (= `policy.maxAttempts`). */
+    attempts: number, 
+    /** The failure the final attempt threw — carried, never interpreted. */
+    lastError: unknown);
+}
+/** Options for {@link retryToSuccess}. */
+interface RetryToSuccessOptions {
+    /**
+     * The `[0, 1)` jitter source threaded into `nextDelayMs`, branded via
+     * `asRng` at construction (a raw `() => number` is rejected by the type).
+     * Injected for deterministic backoff in tests; defaults to `defaultRng`
+     * (`Math.random`), read only at the delay boundary — never inside the loop's
+     * decision.
+     */
+    readonly rng?: Rng;
+    /**
+     * The wait between attempts, given the backoff delay in ms. Injectable so a
+     * test can drive the retry schedule without wall-clock timers (and assert the
+     * exact delays); defaults to a real `setTimeout`. The delay value is always
+     * `./retry-backoff`'s `nextDelayMs` — this port only realizes the wait.
+     */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Fire-and-await bounded retry: invoke the fallible `port`, and on each thrown
+ * failure fold it through `./retry-backoff` — record it, and if the policy
+ * still permits an attempt, back off `nextDelayMs` and retry; otherwise REJECT
+ * with {@link RetryExhaustedError}. Resolves with the port's value on the first
+ * success.
+ *
+ * The port is invoked at most `policy.maxAttempts` times (attempts
+ * `0 .. maxAttempts-1`); the `maxAttempts`-th failure is terminal. Every failure
+ * is either retried or surfaced on the rejection's `lastError` — none is
+ * swallowed.
+ *
+ * @param port   the fallible work — throws on failure, resolves with `R` on success.
+ * @param policy the bounded-retry curve (`baseMs` / `factor` / `capMs` /
+ *               `maxAttempts` / `jitter`) from `./retry-backoff`.
+ * @param opts   optional injected `rng` (jitter) and `sleep` (the wait) — see
+ *               {@link RetryToSuccessOptions}.
+ */
+declare function retryToSuccess<R>(port: () => Promise<R>, policy: RetryPolicy, opts?: RetryToSuccessOptions): Promise<R>;
+
+export { RetryExhaustedError, type RetryToSuccessOptions, retryToSuccess };

package/dist/retry-to-success/index.js

@@ -0,0 +1,35 @@
+import { defaultRng, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-5VNWZADP.js';
+
+// src/retry-to-success/index.ts
+var RetryExhaustedError = class extends Error {
+  constructor(attempts, lastError) {
+    super(
+      `@demlik/tea: retryToSuccess gave up after ${attempts} attempt(s) \u2014 the bounded retry reached maxAttempts without a success. See .lastError for the final failure.`
+    );
+    this.attempts = attempts;
+    this.lastError = lastError;
+  }
+  name = "RetryExhaustedError";
+  _tag = "RetryExhaustedError";
+};
+var defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function retryToSuccess(port, policy, opts = {}) {
+  const rng = opts.rng ?? defaultRng;
+  const sleep = opts.sleep ?? defaultSleep;
+  let retry = initRetry();
+  for (; ; ) {
+    try {
+      return await port();
+    } catch (error) {
+      retry = recordFailure(retry, error);
+      if (!shouldRetry(retry, policy)) {
+        throw new RetryExhaustedError(retry.attempt, error);
+      }
+      await sleep(nextDelayMs(retry, policy, rng));
+    }
+  }
+}
+
+export { RetryExhaustedError, retryToSuccess };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/retry-to-success/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/retry-to-success/index.ts"],"names":[],"mappings":";;;AAiEO,IAAM,mBAAA,GAAN,cAAkC,KAAA,CAAM;AAAA,EAG7C,WAAA,CAEkB,UAEA,SAAA,EAChB;AACA,IAAA,KAAA;AAAA,MACE,6CAA6C,QAAQ,CAAA,iHAAA;AAAA,KAGvD;AARgB,IAAA,IAAA,CAAA,QAAA,GAAA,QAAA;AAEA,IAAA,IAAA,CAAA,SAAA,GAAA,SAAA;AAAA,EAOlB;AAAA,EAbkB,IAAA,GAAO,qBAAA;AAAA,EAChB,IAAA,GAAO,qBAAA;AAalB;AAGA,IAAM,YAAA,GAAe,CAAC,EAAA,KACpB,IAAI,OAAA,CAAQ,CAAC,OAAA,KAAY,UAAA,CAAW,OAAA,EAAS,EAAE,CAAC,CAAA;AAuClD,eAAsB,cAAA,CACpB,IAAA,EACA,MAAA,EACA,IAAA,GAA8B,EAAC,EACnB;AACZ,EAAA,MAAM,GAAA,GAAM,KAAK,GAAA,IAAO,UAAA;AACxB,EAAA,MAAM,KAAA,GAAQ,KAAK,KAAA,IAAS,YAAA;AAI5B,EAAA,IAAI,QAAQ,SAAA,EAAU;AACtB,EAAA,WAAS;AACP,IAAA,IAAI;AACF,MAAA,OAAO,MAAM,IAAA,EAAK;AAAA,IACpB,SAAS,KAAA,EAAO;AAId,MAAA,KAAA,GAAQ,aAAA,CAAc,OAAO,KAAK,CAAA;AAClC,MAAA,IAAI,CAAC,WAAA,CAAY,KAAA,EAAO,MAAM,CAAA,EAAG;AAG/B,QAAA,MAAM,IAAI,mBAAA,CAAoB,KAAA,CAAM,OAAA,EAAS,KAAK,CAAA;AAAA,MACpD;AACA,MAAA,MAAM,KAAA,CAAM,WAAA,CAAY,KAAA,EAAO,MAAA,EAAQ,GAAG,CAAC,CAAA;AAAA,IAC7C;AAAA,EACF;AACF","file":"index.js","sourcesContent":["/**\n * @demlik/tea/retry-to-success — run a fallible async port through BOUNDED\n * retry + exponential backoff to success-or-terminal-give-up, and hand the\n * caller a `Promise<R>` that resolves on the first success or REJECTS with a\n * checkable {@link RetryExhaustedError} the moment the retry bound is hit.\n *\n * This is the retry-side parallel to `./await-terminal`. `runToTerminal` gives a\n * caller with a one-shot decision *machine* a fire-and-await `Promise<State>`\n * without wiring `observe`; this gives a caller with a one-shot fallible *port*\n * a fire-and-await `Promise<R>` without either hand-folding the\n * `./retry-backoff` primitives (`recordFailure` / `shouldRetry` / `nextDelayMs`)\n * into their own reducer each time, or standing up the full `./resilient-call`\n * verb contract (`init` + `attempt`/`succeed`/`fail`/`onTimer` + `subs` +\n * `handlers`) when they want retry only and none of cache / circuit / rate-limit\n * / deadline.\n *\n * It adds NO new runtime capability and NO new backoff math — the whole retry\n * decision is `./retry-backoff` exactly as `resilient-call`'s `backoff` verb\n * wires it:\n *   - `initRetry()` seeds the per-call attempt counter.\n *   - `recordFailure(retry, error)` folds each thrown failure (attempt++).\n *   - `shouldRetry(retry, policy)` is the terminal-at-`maxAttempts` bound — the\n *     `maxAttempts`-th recorded failure refuses another attempt (attempts\n *     `0 .. maxAttempts-1` run; the port is invoked at most `maxAttempts` times).\n *   - `nextDelayMs(retry, policy, rng)` is the exp+jitter+cap delay before the\n *     next attempt, computed on the incremented state — same call order as\n *     `resilient-call`.\n *\n * Where the clock / RNG live: injected, never read on the module's own behalf,\n * mirroring `retry-backoff`'s purity discipline. `rng` is an {@link Rng} (branded\n * `[0, 1)` via `asRng` at the caller boundary) threaded straight into\n * `nextDelayMs`; the wait itself is a `sleep(ms)` port defaulting to a real\n * `setTimeout`, injectable so a test can drive the backoff schedule\n * deterministically without touching wall-clock timers.\n *\n * Exhaustion is NEVER a silent swallow: at the bound the returned promise\n * rejects with {@link RetryExhaustedError} (carrying the attempt count and the\n * final failure), the retry-side dialect of `await-terminal`'s\n * `TerminalTimeoutError` — a distinct `instanceof`- and `_tag`-checkable\n * rejection.\n *\n * NOT a substrate primitive: it depends on nothing from `../index`, only on the\n * leaf `../retry-backoff` utility. Callers reach it via the\n * `@demlik/tea/retry-to-success` subpath.\n */\n\nimport {\n  defaultRng,\n  initRetry,\n  nextDelayMs,\n  type RetryPolicy,\n  type Rng,\n  recordFailure,\n  shouldRetry,\n} from \"../retry-backoff\";\n\n/**\n * Raised when `retryToSuccess` exhausts the retry bound without a success — the\n * `maxAttempts`-th recorded failure refuses another attempt. Follows the tea\n * error dialect (`override readonly name`) and carries a `_tag` discriminant, so\n * a caller can branch on it by `instanceof` or on the tag. It carries the number\n * of attempts made and the final failure (`lastError`) so the terminal give-up\n * is a distinct, checkable rejection — never a silent resolve, and never a\n * swallowed error.\n */\nexport class RetryExhaustedError extends Error {\n  override readonly name = \"RetryExhaustedError\";\n  readonly _tag = \"RetryExhaustedError\" as const;\n  constructor(\n    /** How many times the port was invoked before giving up (= `policy.maxAttempts`). */\n    public readonly attempts: number,\n    /** The failure the final attempt threw — carried, never interpreted. */\n    public readonly lastError: unknown,\n  ) {\n    super(\n      `@demlik/tea: retryToSuccess gave up after ${attempts} attempt(s) — the ` +\n        `bounded retry reached maxAttempts without a success. See .lastError ` +\n        `for the final failure.`,\n    );\n  }\n}\n\n/** Default wait: a real `setTimeout(ms)`, the sole clock read this module makes. */\nconst defaultSleep = (ms: number): Promise<void> =>\n  new Promise((resolve) => setTimeout(resolve, ms));\n\n/** Options for {@link retryToSuccess}. */\nexport interface RetryToSuccessOptions {\n  /**\n   * The `[0, 1)` jitter source threaded into `nextDelayMs`, branded via\n   * `asRng` at construction (a raw `() => number` is rejected by the type).\n   * Injected for deterministic backoff in tests; defaults to `defaultRng`\n   * (`Math.random`), read only at the delay boundary — never inside the loop's\n   * decision.\n   */\n  readonly rng?: Rng;\n  /**\n   * The wait between attempts, given the backoff delay in ms. Injectable so a\n   * test can drive the retry schedule without wall-clock timers (and assert the\n   * exact delays); defaults to a real `setTimeout`. The delay value is always\n   * `./retry-backoff`'s `nextDelayMs` — this port only realizes the wait.\n   */\n  readonly sleep?: (ms: number) => Promise<void>;\n}\n\n/**\n * Fire-and-await bounded retry: invoke the fallible `port`, and on each thrown\n * failure fold it through `./retry-backoff` — record it, and if the policy\n * still permits an attempt, back off `nextDelayMs` and retry; otherwise REJECT\n * with {@link RetryExhaustedError}. Resolves with the port's value on the first\n * success.\n *\n * The port is invoked at most `policy.maxAttempts` times (attempts\n * `0 .. maxAttempts-1`); the `maxAttempts`-th failure is terminal. Every failure\n * is either retried or surfaced on the rejection's `lastError` — none is\n * swallowed.\n *\n * @param port   the fallible work — throws on failure, resolves with `R` on success.\n * @param policy the bounded-retry curve (`baseMs` / `factor` / `capMs` /\n *               `maxAttempts` / `jitter`) from `./retry-backoff`.\n * @param opts   optional injected `rng` (jitter) and `sleep` (the wait) — see\n *               {@link RetryToSuccessOptions}.\n */\nexport async function retryToSuccess<R>(\n  port: () => Promise<R>,\n  policy: RetryPolicy,\n  opts: RetryToSuccessOptions = {},\n): Promise<R> {\n  const rng = opts.rng ?? defaultRng;\n  const sleep = opts.sleep ?? defaultSleep;\n\n  // The retry counter folds over `./retry-backoff` exactly as resilient-call's\n  // `backoff` verb does — no local attempt bookkeeping, no local backoff math.\n  let retry = initRetry();\n  for (;;) {\n    try {\n      return await port();\n    } catch (error) {\n      // Fold the failure first (attempt++), then consult the bound on the\n      // incremented state — same order as resilient-call so the semantics of\n      // `maxAttempts` are identical across both surfaces.\n      retry = recordFailure(retry, error);\n      if (!shouldRetry(retry, policy)) {\n        // Terminal give-up at the bound: reject, never swallow. `retry.attempt`\n        // is the number of failures = the number of port invocations made.\n        throw new RetryExhaustedError(retry.attempt, error);\n      }\n      await sleep(nextDelayMs(retry, policy, rng));\n    }\n  }\n}\n"]}

package/dist/saga/index.d.ts

@@ -1,4 +1,4 @@
-import { C as Cmd } from '../core-CymXZCeY.js';
+import { C as Cmd } from '../core-BmlJOvxM.js';
 import { QueueItem } from '../work-queue/index.js';
 import '../index.js';
 
@@ -12,6 +12,19 @@ import '../index.js';
  * the saga drives `do` forward one step at a time, and on the first failure it
  * pivots and drives `undo` backward over exactly the steps that completed.
  *
+ * **Boundary with `@demlik/tea/workflow` — the compensation test.** Both drive
+ * an ordered multi-step transaction with reverse-order compensation; the line
+ * between them is whether every step carries a true inverse. Here
+ * `SagaStep<D, U>` REQUIRES both `do` and `undo` — a step without its inverse
+ * is unrepresentable, so full reversibility is a type-level guarantee.
+ * Workflow's `WorkflowStep.compensation` is OPTIONAL — an irreversible step (a
+ * sent email) is skipped during the unwind. Pick by the test: **every step
+ * must be reversible → saga; some steps are irreversible but the run must
+ * finish → workflow.** Cross to workflow when the transaction includes steps
+ * that can't be undone (or when you want each activity recorded as a durable
+ * owed effect on the `../do` ledger); stay here when the type system should
+ * enforce that every step can be undone.
+ *
  * The recipe (which bricks it composes):
  *   - `../work-queue/adapter` — the saga's forward progress IS a work-queue
  *     lifecycle. Each step's record carries the same `{ id, status, input }`