@demlik/tea 0.1.0 → 0.1.2

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

@@ -0,0 +1,238 @@
+import { C as Cmd } from '../core-BoB6t7dB.js';
+import { QueueItem } from '../work-queue/index.js';
+import '../index.js';
+
+/**
+ * @demlik/tea/saga — a forward-then-compensate transaction over an ordered list
+ * of reversible steps.
+ *
+ * The Level-2 combinator for "run these N steps in order; if any step fails,
+ * undo the steps that already succeeded, in reverse." It is the distributed-
+ * transaction / compensation knob: each step is a `{ do, undo }` pair of Cmds,
+ * 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 }`
+ *     vocabulary (`pending → running → done | failed | cancelled`), so the step
+ *     taxonomy is the substrate's status enum rather than a parallel invention.
+ *     We reuse the pure `QueueItem` / `QueueItemStatus` types AND delegate every
+ *     status flip to the `QueueAdapter` verbs: `wq.enqueue` stamps each fresh
+ *     ledger record, and `wq.patch` performs every
+ *     `pending → running → done | failed | cancelled` transition. The status
+ *     transitions are NOT re-rolled here — they live in exactly one place
+ *     behind the adapter, per the package's one-shape rule. The async
+ *     `createQueue(store)` adapter is NOT used: its `load → mutate → save` reads
+ *     the clock and lives at an I/O boundary, while a combinator's verbs must be
+ *     pure (invariant 2). We bind the same ops to the in-Model ledger instead —
+ *     durable + replayable, the two non-negotiables every knob preserves.
+ *
+ * The compensation log is the spec's `done: StepId[]` — the indices of the
+ * steps that completed forward, in the order they completed. On `stepErr` the
+ * saga walks that log in reverse, emitting one `undo` per `undoOk`, so the
+ * unwind is the exact mirror of the wind. If an `undo` ITSELF fails, `undoErr`
+ * pivots to the terminal `compensation_failed` phase: a failed compensation is
+ * a real-world fact (a refund that bounced, a hold that won't release) that the
+ * consumer must see and reconcile by hand — never a saga wedged in
+ * `compensating` forever.
+ *
+ * Typical wiring (combinator form — splice the hooks into your machine):
+ *
+ *   const saga = createSaga<BookFlight | ChargeCard | ..., Cancel | Refund | ...>({
+ *     steps: [
+ *       { do: { type: "book_flight" },  undo: { type: "cancel_flight" } },
+ *       { do: { type: "charge_card" },  undo: { type: "refund_card" } },
+ *       { do: { type: "reserve_hotel" },undo: { type: "release_hotel" } },
+ *     ],
+ *   });
+ *
+ *   // in `update`:
+ *   begin:    (s)    => lift(s, saga.start(s.saga)),
+ *   step_ok:  (s)    => lift(s, saga.stepOk(s.saga)),
+ *   step_err: (s, m) => lift(s, saga.stepErr(s.saga, m.error)),
+ *   undo_ok:  (s)    => lift(s, saga.undoOk(s.saga)),
+ *   undo_err: (s, m) => lift(s, saga.undoErr(s.saga, m.error)),
+ *
+ * Every verb is PURE: it returns a NEW slice plus the Cmds to perform (the next
+ * `do` going forward, or the next `undo` rolling back). The reducer never reads
+ * a clock or RNG — step identity is positional (the index into `config.steps`),
+ * so progress survives a round-trip through the durable slice and resumes
+ * exactly where it left off after a DO eviction.
+ *
+ * There is no `subs` and no `handlers`: a saga runs no timers, and the `do` /
+ * `undo` Cmds are fully caller-defined (the consumer's own `interpret` performs
+ * each effect and routes Ok/Err back to the `stepOk` / `stepErr` / `undoOk`
+ * verbs — the same shape `resilient-fetch` uses with `tryInterpret`). The saga
+ * owns the ORDER; the consumer owns the I/O. Pure-ops module, like
+ * `retry-backoff`.
+ *
+ * NOT a substrate primitive: it depends only on `../work-queue`'s pure types
+ * and `../index`'s `Cmd` type. Consumers reach it via the `@demlik/tea/saga`
+ * subpath.
+ */
+
+/**
+ * A step's stable identity. Positional: the 0-based index into
+ * `config.steps`. Positional ids are PURE (no clock, no RNG) and survive a
+ * round-trip through the durable slice, so `done` can be replayed to resume an
+ * interrupted saga exactly. The compensation log is a list of these.
+ */
+type StepId = number;
+/**
+ * One step of the saga: the forward effect and its compensating inverse, both
+ * as data (plain Cmds). `do` runs while winding forward; `undo` runs while
+ * unwinding after a failure. The pair is the unit of reversibility — a step
+ * that completed (`do` succeeded) is exactly a step whose `undo` must run if a
+ * later step fails.
+ */
+interface SagaStep<D extends Cmd, U extends Cmd> {
+    /** The forward effect, performed while the saga winds forward. */
+    readonly do: D;
+    /** The compensating inverse, performed (in reverse) while the saga unwinds. */
+    readonly undo: U;
+}
+/**
+ * The knob. The ordered list of reversible steps. The list is fixed for the
+ * life of one saga instance (a saga drives a known transaction); per-run inputs
+ * ride on the consumer's Msgs, not here.
+ */
+interface SagaConfig<D extends Cmd, U extends Cmd> {
+    /** The steps, in forward order. `do` runs `0 → n-1`; `undo` runs the completed prefix `n-1 → 0`. */
+    readonly steps: readonly SagaStep<D, U>[];
+}
+/**
+ * The lifecycle phase of a saga, narrowed at the type level so a consumer can
+ * branch on `state.phase` (and a Transitions-table reducer can key on it).
+ *
+ *   - `"idle"`         — created, not started. No step has run.
+ *   - `"running"`      — winding forward; `position` is the in-flight step.
+ *   - `"compensating"` — a step failed; unwinding `done` in reverse.
+ *   - `"committed"`    — every step completed forward. Terminal success.
+ *   - `"aborted"`      — compensation finished (every completed step undone, or
+ *                        the first step itself failed with nothing to undo).
+ *                        Terminal failure, fully unwound.
+ *   - `"compensation_failed"` — an `undo` itself failed mid-rollback. Terminal
+ *                        failure, PARTIALLY unwound: the steps still in `done`
+ *                        were never compensated and must be reconciled by hand.
+ *                        Distinguished from `aborted` precisely so a stuck
+ *                        rollback is visible state, not a saga wedged in
+ *                        `compensating` forever.
+ */
+type SagaPhase = "idle" | "running" | "compensating" | "committed" | "aborted" | "compensation_failed";
+/**
+ * The slice this knob owns.
+ *
+ * The spec's three fields are load-bearing:
+ *   - `position` — the index of the step currently in flight while `running`,
+ *     or the index being compensated while `compensating`. Survives eviction,
+ *     so `boot` resumes mid-saga from the durable slice.
+ *   - `done` — the compensation log: the ids of steps that completed forward,
+ *     in completion order. `undo` walks this in reverse. This is the single
+ *     source of truth for what must be unwound.
+ *   - `compensating` — the direction bit. `false` while winding forward, `true`
+ *     once a failure has pivoted the saga into rollback.
+ *
+ * Plus:
+ *   - `phase` — the derived lifecycle tag (see `SagaPhase`). Kept in the slice
+ *     (not recomputed) so a consumer's view and Transitions reducer can key on
+ *     `state.phase` directly, and the terminal states (`committed` / `aborted`)
+ *     are explicit facts rather than "position past the end" arithmetic.
+ *   - `error` — the forward failure that triggered compensation, carried
+ *     forward verbatim (`unknown`) for the consumer to read, never interpreted
+ *     (same discipline as `retry-backoff`'s `lastError` and `fan-out`'s
+ *     `error`).
+ *   - `compensationError` — the failure of an `undo` itself, set only when the
+ *     saga reaches `compensation_failed`. Kept distinct from `error` (the
+ *     forward failure) so a consumer reconciling a stuck rollback can read both
+ *     "what broke the transaction" and "which compensation then bounced".
+ *     Carried verbatim, never interpreted, same as `error`.
+ *   - `items` — the work-queue ledger, one `QueueItem` per step, keyed by the
+ *     step's positional id. The single source of truth for each step's status;
+ *     `phase` / `position` / `done` are the projection the verbs keep in
+ *     lockstep with it.
+ *
+ * Every field is `readonly` and JSON-serializable (plain numbers, arrays, and
+ * the work-queue's plain `QueueItem` records), so the slice round-trips through
+ * a consumer's `Store<S>` unchanged — durable across DO eviction.
+ */
+interface SagaState<I = StepId> {
+    /** The step in flight (`running`) or being compensated (`compensating`). */
+    readonly position: number;
+    /** The compensation log: ids of completed-forward steps, in completion order. */
+    readonly done: readonly StepId[];
+    /** Direction bit: `false` winding forward, `true` unwinding. */
+    readonly compensating: boolean;
+    /** The derived lifecycle tag (see `SagaPhase`). */
+    readonly phase: SagaPhase;
+    /** The forward failure that triggered compensation, if any. Carried, never interpreted. */
+    readonly error?: unknown;
+    /** The failure of an `undo` itself (only when `compensation_failed`). Carried, never interpreted. */
+    readonly compensationError?: unknown;
+    /** The work-queue ledger: one record per step, keyed by positional id. */
+    readonly items: readonly QueueItem<I>[];
+}
+/** Whether the saga has terminated successfully (every step committed). */
+declare function isCommitted<I>(state: SagaState<I>): boolean;
+/** Whether the saga has terminated in failure, fully unwound (every completed step undone). */
+declare function isAborted<I>(state: SagaState<I>): boolean;
+/**
+ * Whether the saga has terminated in failure with an UNFINISHED rollback: an
+ * `undo` itself failed, so some completed steps were never compensated and need
+ * hand reconciliation. Terminal, but distinct from `aborted` (fully unwound).
+ */
+declare function isCompensationFailed<I>(state: SagaState<I>): boolean;
+/**
+ * Whether the saga has reached a terminal phase (success, fully-unwound
+ * failure, or compensation-failed). Derived — reads the slice, never mutates.
+ * Consumers branch their own phase off this; no further verb has any effect
+ * once it holds (the verbs guard on phase and no-op).
+ */
+declare function isSettled<I>(state: SagaState<I>): boolean;
+/**
+ * The starting slice: idle, nothing run, winding-forward direction. `items` is
+ * empty until `start` stamps one ledger record per configured step — the slice
+ * is generic in the ledger payload `I`, defaulting to the positional `StepId`
+ * since a saga's "input" per step is just its index (the consumer's real inputs
+ * ride on its own Msgs).
+ */
+declare function initSaga<I = StepId>(): SagaState<I>;
+/**
+ * Build the saga knob from `config`. Returns the uniform combinator contract:
+ * `init` for the owned slice and the five lifecycle verbs (`start`, `stepOk`,
+ * `stepErr`, `undoOk`, `undoErr`).
+ *
+ * No `subs` and no `handlers` — a saga runs no timers, and each step's `do` /
+ * `undo` effect is owned by the consumer's `interpret` (the saga emits the Cmd;
+ * the consumer performs it and routes the outcome back to a verb). The saga's
+ * sole job is the ORDER: which Cmd to emit next, and when to pivot from winding
+ * to unwinding (and when a failed `undo` ends the rollback). Pure-ops module —
+ * matches `retry-backoff`'s shape.
+ */
+declare function createSaga<D extends Cmd, U extends Cmd>(config: SagaConfig<D, U>): {
+    init: () => SagaState<number>;
+    start: (state: SagaState<StepId>) => readonly [SagaState<StepId>, readonly D[]];
+    stepOk: (state: SagaState<StepId>) => readonly [SagaState<StepId>, readonly D[]];
+    stepErr: (state: SagaState<StepId>, error: unknown) => readonly [SagaState<StepId>, readonly U[]];
+    undoOk: (state: SagaState<StepId>) => readonly [SagaState<StepId>, readonly U[]];
+    undoErr: (state: SagaState<StepId>, error: unknown) => readonly [SagaState<StepId>, readonly U[]];
+    isCommitted: typeof isCommitted;
+    isAborted: typeof isAborted;
+    isCompensationFailed: typeof isCompensationFailed;
+    isSettled: typeof isSettled;
+};
+
+export { type SagaConfig, type SagaPhase, type SagaState, type SagaStep, type StepId, createSaga, initSaga, isAborted, isCommitted, isCompensationFailed, isSettled };

package/dist/saga/index.js

@@ -0,0 +1,150 @@
+import { queueAdapter } from '../chunk-HJO6VNQI.js';
+import '../chunk-TGG26XMK.js';
+
+// src/saga/index.ts
+function isCommitted(state) {
+  return state.phase === "committed";
+}
+function isAborted(state) {
+  return state.phase === "aborted";
+}
+function isCompensationFailed(state) {
+  return state.phase === "compensation_failed";
+}
+function isSettled(state) {
+  return state.phase === "committed" || state.phase === "aborted" || state.phase === "compensation_failed";
+}
+function initSaga() {
+  return {
+    position: 0,
+    done: [],
+    compensating: false,
+    phase: "idle",
+    items: []
+  };
+}
+function createSaga(config) {
+  const wq = queueAdapter();
+  function freshLedger() {
+    let items = [];
+    config.steps.forEach((_step, index) => {
+      items = wq.enqueue(items, index, 0, String(index)).next;
+    });
+    return items;
+  }
+  function setStatus(items, index, status) {
+    return wq.patch(items, String(index), (item) => ({
+      ...item,
+      status
+    })).next;
+  }
+  function stepAt(index) {
+    return config.steps[index];
+  }
+  function lastDone(done) {
+    return done[done.length - 1];
+  }
+  function start(state) {
+    if (state.phase !== "idle") return [state, []];
+    const items = freshLedger();
+    const first = stepAt(0);
+    if (first === void 0) {
+      return [{ ...state, phase: "committed", items }, []];
+    }
+    const next = {
+      ...state,
+      position: 0,
+      phase: "running",
+      items: setStatus(items, 0, "running")
+    };
+    return [next, [first.do]];
+  }
+  function stepOk(state) {
+    if (state.phase !== "running") return [state, []];
+    const completed = state.position;
+    const itemsDone = setStatus(state.items, completed, "done");
+    const done = [...state.done, completed];
+    const nextPosition = completed + 1;
+    const nextStep = stepAt(nextPosition);
+    if (nextStep === void 0) {
+      return [{ ...state, done, items: itemsDone, phase: "committed" }, []];
+    }
+    const next = {
+      ...state,
+      position: nextPosition,
+      done,
+      items: setStatus(itemsDone, nextPosition, "running")
+    };
+    return [next, [nextStep.do]];
+  }
+  function stepErr(state, error) {
+    if (state.phase !== "running") return [state, []];
+    const failed = state.position;
+    const items = setStatus(state.items, failed, "failed");
+    const undoIndex = lastDone(state.done);
+    const undoStep = undoIndex === void 0 ? void 0 : stepAt(undoIndex);
+    if (undoIndex === void 0 || undoStep === void 0) {
+      return [
+        { ...state, items, error, compensating: true, phase: "aborted" },
+        []
+      ];
+    }
+    const next = {
+      ...state,
+      items,
+      error,
+      compensating: true,
+      phase: "compensating",
+      position: undoIndex
+    };
+    return [next, [undoStep.undo]];
+  }
+  function undoOk(state) {
+    if (state.phase !== "compensating") return [state, []];
+    const undone = lastDone(state.done);
+    if (undone === void 0) return [state, []];
+    const remaining = state.done.slice(0, -1);
+    const items = setStatus(state.items, undone, "cancelled");
+    const nextUndo = lastDone(remaining);
+    const nextStep = nextUndo === void 0 ? void 0 : stepAt(nextUndo);
+    if (nextUndo === void 0 || nextStep === void 0) {
+      return [{ ...state, done: remaining, items, phase: "aborted" }, []];
+    }
+    const next = {
+      ...state,
+      done: remaining,
+      items,
+      position: nextUndo
+    };
+    return [next, [nextStep.undo]];
+  }
+  function undoErr(state, error) {
+    if (state.phase !== "compensating") return [state, []];
+    const items = setStatus(state.items, state.position, "failed");
+    return [
+      {
+        ...state,
+        items,
+        compensationError: error,
+        phase: "compensation_failed"
+      },
+      []
+    ];
+  }
+  return {
+    init: initSaga,
+    start,
+    stepOk,
+    stepErr,
+    undoOk,
+    undoErr,
+    isCommitted,
+    isAborted,
+    isCompensationFailed,
+    isSettled
+  };
+}
+
+export { createSaga, initSaga, isAborted, isCommitted, isCompensationFailed, isSettled };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/saga/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/saga/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/saga — a forward-then-compensate transaction over an ordered list\n * of reversible steps.\n *\n * The Level-2 combinator for \"run these N steps in order; if any step fails,\n * undo the steps that already succeeded, in reverse.\" It is the distributed-\n * transaction / compensation knob: each step is a `{ do, undo }` pair of Cmds,\n * the saga drives `do` forward one step at a time, and on the first failure it\n * pivots and drives `undo` backward over exactly the steps that completed.\n *\n * **Boundary with `@demlik/tea/workflow` — the compensation test.** Both drive\n * an ordered multi-step transaction with reverse-order compensation; the line\n * between them is whether every step carries a true inverse. Here\n * `SagaStep<D, U>` REQUIRES both `do` and `undo` — a step without its inverse\n * is unrepresentable, so full reversibility is a type-level guarantee.\n * Workflow's `WorkflowStep.compensation` is OPTIONAL — an irreversible step (a\n * sent email) is skipped during the unwind. Pick by the test: **every step\n * must be reversible → saga; some steps are irreversible but the run must\n * finish → workflow.** Cross to workflow when the transaction includes steps\n * that can't be undone (or when you want each activity recorded as a durable\n * owed effect on the `../do` ledger); stay here when the type system should\n * enforce that every step can be undone.\n *\n * The recipe (which bricks it composes):\n *   - `../work-queue/adapter` — the saga's forward progress IS a work-queue\n *     lifecycle. Each step's record carries the same `{ id, status, input }`\n *     vocabulary (`pending → running → done | failed | cancelled`), so the step\n *     taxonomy is the substrate's status enum rather than a parallel invention.\n *     We reuse the pure `QueueItem` / `QueueItemStatus` types AND delegate every\n *     status flip to the `QueueAdapter` verbs: `wq.enqueue` stamps each fresh\n *     ledger record, and `wq.patch` performs every\n *     `pending → running → done | failed | cancelled` transition. The status\n *     transitions are NOT re-rolled here — they live in exactly one place\n *     behind the adapter, per the package's one-shape rule. The async\n *     `createQueue(store)` adapter is NOT used: its `load → mutate → save` reads\n *     the clock and lives at an I/O boundary, while a combinator's verbs must be\n *     pure (invariant 2). We bind the same ops to the in-Model ledger instead —\n *     durable + replayable, the two non-negotiables every knob preserves.\n *\n * The compensation log is the spec's `done: StepId[]` — the indices of the\n * steps that completed forward, in the order they completed. On `stepErr` the\n * saga walks that log in reverse, emitting one `undo` per `undoOk`, so the\n * unwind is the exact mirror of the wind. If an `undo` ITSELF fails, `undoErr`\n * pivots to the terminal `compensation_failed` phase: a failed compensation is\n * a real-world fact (a refund that bounced, a hold that won't release) that the\n * consumer must see and reconcile by hand — never a saga wedged in\n * `compensating` forever.\n *\n * Typical wiring (combinator form — splice the hooks into your machine):\n *\n *   const saga = createSaga<BookFlight | ChargeCard | ..., Cancel | Refund | ...>({\n *     steps: [\n *       { do: { type: \"book_flight\" },  undo: { type: \"cancel_flight\" } },\n *       { do: { type: \"charge_card\" },  undo: { type: \"refund_card\" } },\n *       { do: { type: \"reserve_hotel\" },undo: { type: \"release_hotel\" } },\n *     ],\n *   });\n *\n *   // in `update`:\n *   begin:    (s)    => lift(s, saga.start(s.saga)),\n *   step_ok:  (s)    => lift(s, saga.stepOk(s.saga)),\n *   step_err: (s, m) => lift(s, saga.stepErr(s.saga, m.error)),\n *   undo_ok:  (s)    => lift(s, saga.undoOk(s.saga)),\n *   undo_err: (s, m) => lift(s, saga.undoErr(s.saga, m.error)),\n *\n * Every verb is PURE: it returns a NEW slice plus the Cmds to perform (the next\n * `do` going forward, or the next `undo` rolling back). The reducer never reads\n * a clock or RNG — step identity is positional (the index into `config.steps`),\n * so progress survives a round-trip through the durable slice and resumes\n * exactly where it left off after a DO eviction.\n *\n * There is no `subs` and no `handlers`: a saga runs no timers, and the `do` /\n * `undo` Cmds are fully caller-defined (the consumer's own `interpret` performs\n * each effect and routes Ok/Err back to the `stepOk` / `stepErr` / `undoOk`\n * verbs — the same shape `resilient-fetch` uses with `tryInterpret`). The saga\n * owns the ORDER; the consumer owns the I/O. Pure-ops module, like\n * `retry-backoff`.\n *\n * NOT a substrate primitive: it depends only on `../work-queue`'s pure types\n * and `../index`'s `Cmd` type. Consumers reach it via the `@demlik/tea/saga`\n * subpath.\n */\n\nimport type { Cmd } from \"../index\";\nimport type { QueueItem, QueueItemStatus } from \"../work-queue\";\nimport { queueAdapter } from \"../work-queue/adapter\";\n\n/**\n * A step's stable identity. Positional: the 0-based index into\n * `config.steps`. Positional ids are PURE (no clock, no RNG) and survive a\n * round-trip through the durable slice, so `done` can be replayed to resume an\n * interrupted saga exactly. The compensation log is a list of these.\n */\nexport type StepId = number;\n\n/**\n * One step of the saga: the forward effect and its compensating inverse, both\n * as data (plain Cmds). `do` runs while winding forward; `undo` runs while\n * unwinding after a failure. The pair is the unit of reversibility — a step\n * that completed (`do` succeeded) is exactly a step whose `undo` must run if a\n * later step fails.\n */\nexport interface SagaStep<D extends Cmd, U extends Cmd> {\n  /** The forward effect, performed while the saga winds forward. */\n  readonly do: D;\n  /** The compensating inverse, performed (in reverse) while the saga unwinds. */\n  readonly undo: U;\n}\n\n/**\n * The knob. The ordered list of reversible steps. The list is fixed for the\n * life of one saga instance (a saga drives a known transaction); per-run inputs\n * ride on the consumer's Msgs, not here.\n */\nexport interface SagaConfig<D extends Cmd, U extends Cmd> {\n  /** The steps, in forward order. `do` runs `0 → n-1`; `undo` runs the completed prefix `n-1 → 0`. */\n  readonly steps: readonly SagaStep<D, U>[];\n}\n\n/**\n * The lifecycle phase of a saga, narrowed at the type level so a consumer can\n * branch on `state.phase` (and a Transitions-table reducer can key on it).\n *\n *   - `\"idle\"`         — created, not started. No step has run.\n *   - `\"running\"`      — winding forward; `position` is the in-flight step.\n *   - `\"compensating\"` — a step failed; unwinding `done` in reverse.\n *   - `\"committed\"`    — every step completed forward. Terminal success.\n *   - `\"aborted\"`      — compensation finished (every completed step undone, or\n *                        the first step itself failed with nothing to undo).\n *                        Terminal failure, fully unwound.\n *   - `\"compensation_failed\"` — an `undo` itself failed mid-rollback. Terminal\n *                        failure, PARTIALLY unwound: the steps still in `done`\n *                        were never compensated and must be reconciled by hand.\n *                        Distinguished from `aborted` precisely so a stuck\n *                        rollback is visible state, not a saga wedged in\n *                        `compensating` forever.\n */\nexport type SagaPhase =\n  | \"idle\"\n  | \"running\"\n  | \"compensating\"\n  | \"committed\"\n  | \"aborted\"\n  | \"compensation_failed\";\n\n/**\n * The slice this knob owns.\n *\n * The spec's three fields are load-bearing:\n *   - `position` — the index of the step currently in flight while `running`,\n *     or the index being compensated while `compensating`. Survives eviction,\n *     so `boot` resumes mid-saga from the durable slice.\n *   - `done` — the compensation log: the ids of steps that completed forward,\n *     in completion order. `undo` walks this in reverse. This is the single\n *     source of truth for what must be unwound.\n *   - `compensating` — the direction bit. `false` while winding forward, `true`\n *     once a failure has pivoted the saga into rollback.\n *\n * Plus:\n *   - `phase` — the derived lifecycle tag (see `SagaPhase`). Kept in the slice\n *     (not recomputed) so a consumer's view and Transitions reducer can key on\n *     `state.phase` directly, and the terminal states (`committed` / `aborted`)\n *     are explicit facts rather than \"position past the end\" arithmetic.\n *   - `error` — the forward failure that triggered compensation, carried\n *     forward verbatim (`unknown`) for the consumer to read, never interpreted\n *     (same discipline as `retry-backoff`'s `lastError` and `fan-out`'s\n *     `error`).\n *   - `compensationError` — the failure of an `undo` itself, set only when the\n *     saga reaches `compensation_failed`. Kept distinct from `error` (the\n *     forward failure) so a consumer reconciling a stuck rollback can read both\n *     \"what broke the transaction\" and \"which compensation then bounced\".\n *     Carried verbatim, never interpreted, same as `error`.\n *   - `items` — the work-queue ledger, one `QueueItem` per step, keyed by the\n *     step's positional id. The single source of truth for each step's status;\n *     `phase` / `position` / `done` are the projection the verbs keep in\n *     lockstep with it.\n *\n * Every field is `readonly` and JSON-serializable (plain numbers, arrays, and\n * the work-queue's plain `QueueItem` records), so the slice round-trips through\n * a consumer's `Store<S>` unchanged — durable across DO eviction.\n */\nexport interface SagaState<I = StepId> {\n  /** The step in flight (`running`) or being compensated (`compensating`). */\n  readonly position: number;\n  /** The compensation log: ids of completed-forward steps, in completion order. */\n  readonly done: readonly StepId[];\n  /** Direction bit: `false` winding forward, `true` unwinding. */\n  readonly compensating: boolean;\n  /** The derived lifecycle tag (see `SagaPhase`). */\n  readonly phase: SagaPhase;\n  /** The forward failure that triggered compensation, if any. Carried, never interpreted. */\n  readonly error?: unknown;\n  /** The failure of an `undo` itself (only when `compensation_failed`). Carried, never interpreted. */\n  readonly compensationError?: unknown;\n  /** The work-queue ledger: one record per step, keyed by positional id. */\n  readonly items: readonly QueueItem<I>[];\n}\n\n/** Whether the saga has terminated successfully (every step committed). */\nexport function isCommitted<I>(state: SagaState<I>): boolean {\n  return state.phase === \"committed\";\n}\n\n/** Whether the saga has terminated in failure, fully unwound (every completed step undone). */\nexport function isAborted<I>(state: SagaState<I>): boolean {\n  return state.phase === \"aborted\";\n}\n\n/**\n * Whether the saga has terminated in failure with an UNFINISHED rollback: an\n * `undo` itself failed, so some completed steps were never compensated and need\n * hand reconciliation. Terminal, but distinct from `aborted` (fully unwound).\n */\nexport function isCompensationFailed<I>(state: SagaState<I>): boolean {\n  return state.phase === \"compensation_failed\";\n}\n\n/**\n * Whether the saga has reached a terminal phase (success, fully-unwound\n * failure, or compensation-failed). Derived — reads the slice, never mutates.\n * Consumers branch their own phase off this; no further verb has any effect\n * once it holds (the verbs guard on phase and no-op).\n */\nexport function isSettled<I>(state: SagaState<I>): boolean {\n  return (\n    state.phase === \"committed\" ||\n    state.phase === \"aborted\" ||\n    state.phase === \"compensation_failed\"\n  );\n}\n\n/**\n * The starting slice: idle, nothing run, winding-forward direction. `items` is\n * empty until `start` stamps one ledger record per configured step — the slice\n * is generic in the ledger payload `I`, defaulting to the positional `StepId`\n * since a saga's \"input\" per step is just its index (the consumer's real inputs\n * ride on its own Msgs).\n */\nexport function initSaga<I = StepId>(): SagaState<I> {\n  return {\n    position: 0,\n    done: [],\n    compensating: false,\n    phase: \"idle\",\n    items: [],\n  };\n}\n\n/**\n * Build the saga knob from `config`. Returns the uniform combinator contract:\n * `init` for the owned slice and the five lifecycle verbs (`start`, `stepOk`,\n * `stepErr`, `undoOk`, `undoErr`).\n *\n * No `subs` and no `handlers` — a saga runs no timers, and each step's `do` /\n * `undo` effect is owned by the consumer's `interpret` (the saga emits the Cmd;\n * the consumer performs it and routes the outcome back to a verb). The saga's\n * sole job is the ORDER: which Cmd to emit next, and when to pivot from winding\n * to unwinding (and when a failed `undo` ends the rollback). Pure-ops module —\n * matches `retry-backoff`'s shape.\n */\nexport function createSaga<D extends Cmd, U extends Cmd>(\n  config: SagaConfig<D, U>,\n) {\n  // The ledger seam, bound once. The saga delegates ledger construction to\n  // `wq.enqueue` and every status flip to `wq.patch`, so the `QueueItem<StepId>`\n  // shape stays insulated behind the verbs.\n  const wq = queueAdapter<StepId>();\n\n  /**\n   * One ledger record per configured step, keyed by its positional id. Each\n   * record is stamped by the `QueueAdapter`'s `enqueue` (the saga delegates\n   * ledger construction to the verb rather than building records inline).\n   *\n   * The positional id is stringified — `QueueItem.id` is a string, the saga's\n   * step identity is the index; `String(index)` keeps both the ledger's\n   * string-id contract and the positional identity. `enqueuedAt` is `0`: saga\n   * verbs are pure and the saga makes no timestamp-based decision (ordering is\n   * positional), so there is no clock to read here.\n   */\n  function freshLedger(): QueueItem<StepId>[] {\n    let items: QueueItem<StepId>[] = [];\n    config.steps.forEach((_step, index) => {\n      items = wq.enqueue(items, index, 0, String(index)).next;\n    });\n    return items;\n  }\n\n  /**\n   * Flip the ledger record for step `index` to `status`, delegating the\n   * transition to the `QueueAdapter`'s `patch` (keyed by the record's string\n   * id, `String(index)`) so the status flip is NOT re-rolled here. PURE —\n   * `patch` returns a new array; an unknown id returns a copy unchanged (the\n   * verbs guard against out-of-range, but the helper is total).\n   */\n  function setStatus(\n    items: readonly QueueItem<StepId>[],\n    index: number,\n    status: QueueItemStatus,\n  ): QueueItem<StepId>[] {\n    return wq.patch(items, String(index), (item) => ({\n      ...item,\n      status,\n    })).next;\n  }\n\n  /**\n   * The step at `index`, or `undefined` if out of range. Centralizes the bounds\n   * check so the verbs read a step through a narrowing guard instead of a\n   * non-null assertion: `const step = stepAt(i); if (step === undefined) …`.\n   */\n  function stepAt(index: number): SagaStep<D, U> | undefined {\n    return config.steps[index];\n  }\n\n  /** The most-recently-completed step id (tail of `done`), or `undefined` if the log is empty. */\n  function lastDone(done: readonly StepId[]): StepId | undefined {\n    return done[done.length - 1];\n  }\n\n  /**\n   * Begin the saga: stamp a `pending` ledger record per step, mark step 0\n   * `running`, and emit step 0's `do` Cmd. PURE.\n   *\n   * A saga with zero configured steps commits immediately (nothing to do, so\n   * the empty transaction trivially succeeds) and emits no Cmd. Calling `start`\n   * on an already-started saga (phase ≠ `\"idle\"`) is a no-op: the slice is\n   * returned unchanged with no Cmds, so a stray re-`start` after a boot/replay\n   * can't relaunch step 0 on top of an in-flight saga.\n   */\n  function start(\n    state: SagaState<StepId>,\n  ): readonly [SagaState<StepId>, readonly D[]] {\n    if (state.phase !== \"idle\") return [state, []];\n\n    const items = freshLedger();\n    const first = stepAt(0);\n    if (first === undefined) {\n      // Empty transaction: trivially committed, no effect.\n      return [{ ...state, phase: \"committed\", items }, []];\n    }\n\n    const next: SagaState<StepId> = {\n      ...state,\n      position: 0,\n      phase: \"running\",\n      items: setStatus(items, 0, \"running\"),\n    };\n    return [next, [first.do]];\n  }\n\n  /**\n   * Record the in-flight step as committed and advance. PURE.\n   *\n   * Flips the current step's ledger record `running → done`, appends its id to\n   * the compensation log, and:\n   *   - if a next step exists, marks it `running` and emits its `do` Cmd;\n   *   - if this was the last step, transitions to `committed` (terminal\n   *     success) and emits no Cmd.\n   *\n   * `stepOk` while not `running` (idle, compensating, or already terminal) is a\n   * no-op — the runtime's serial dispatch makes a true double-`stepOk`\n   * impossible, but a stale success Msg after a boot/replay is real, and\n   * swallowing it is the safe direction (the step's outcome is already recorded\n   * in the ledger).\n   */\n  function stepOk(\n    state: SagaState<StepId>,\n  ): readonly [SagaState<StepId>, readonly D[]] {\n    if (state.phase !== \"running\") return [state, []];\n\n    const completed = state.position;\n    const itemsDone = setStatus(state.items, completed, \"done\");\n    const done = [...state.done, completed];\n    const nextPosition = completed + 1;\n    const nextStep = stepAt(nextPosition);\n\n    if (nextStep === undefined) {\n      // No next step — the last step committed, so the whole transaction\n      // succeeded.\n      return [{ ...state, done, items: itemsDone, phase: \"committed\" }, []];\n    }\n\n    const next: SagaState<StepId> = {\n      ...state,\n      position: nextPosition,\n      done,\n      items: setStatus(itemsDone, nextPosition, \"running\"),\n    };\n    return [next, [nextStep.do]];\n  }\n\n  /**\n   * Pivot from winding to unwinding: the in-flight step failed. PURE.\n   *\n   * Flips the failed step's ledger record `running → failed`, records the\n   * `error`, sets the direction bit, and begins compensation by emitting the\n   * `undo` of the MOST-recently-completed step (the tail of the compensation\n   * log) — rollback is the mirror of progress, so the last step that succeeded\n   * is the first to be undone.\n   *\n   * If nothing completed forward (the first step itself failed), there is\n   * nothing to compensate: the saga goes straight to `aborted` (terminal\n   * failure) and emits no `undo`.\n   *\n   * `stepErr` while not `running` is a no-op (same stale-Msg reasoning as\n   * `stepOk`): once a saga is already compensating or terminal, a late failure\n   * Msg for an old step must not restart or re-pivot the unwind.\n   */\n  function stepErr(\n    state: SagaState<StepId>,\n    error: unknown,\n  ): readonly [SagaState<StepId>, readonly U[]] {\n    if (state.phase !== \"running\") return [state, []];\n\n    const failed = state.position;\n    const items = setStatus(state.items, failed, \"failed\");\n\n    // Compensate the most-recently-completed step first. `lastDone === undefined`\n    // means nothing completed forward (the first step itself failed) — there is\n    // nothing to undo, so the saga aborts straight away. The guard narrows\n    // `undoIndex` to `StepId` and `undoStep` to a present step without a\n    // non-null assertion.\n    const undoIndex = lastDone(state.done);\n    const undoStep = undoIndex === undefined ? undefined : stepAt(undoIndex);\n    if (undoIndex === undefined || undoStep === undefined) {\n      return [\n        { ...state, items, error, compensating: true, phase: \"aborted\" },\n        [],\n      ];\n    }\n\n    const next: SagaState<StepId> = {\n      ...state,\n      items,\n      error,\n      compensating: true,\n      phase: \"compensating\",\n      position: undoIndex,\n    };\n    return [next, [undoStep.undo]];\n  }\n\n  /**\n   * Continue the rollback: the `undo` for the current compensation position\n   * succeeded. PURE.\n   *\n   * Pops the just-undone step off the tail of the compensation log (flipping\n   * its ledger record `done → cancelled` to mark it rolled back), and:\n   *   - if more completed steps remain, emits the next one's `undo` (continuing\n   *     in reverse) and moves `position` to it;\n   *   - if the log is now empty, transitions to `aborted` (terminal failure —\n   *     the saga is fully unwound) and emits no Cmd.\n   *\n   * `undoOk` while not `compensating` is a no-op (same stale-Msg reasoning as\n   * the forward verbs): an `undo`-success Msg that arrives after the saga has\n   * already finished unwinding must not pop a step that isn't there.\n   */\n  function undoOk(\n    state: SagaState<StepId>,\n  ): readonly [SagaState<StepId>, readonly U[]] {\n    if (state.phase !== \"compensating\") return [state, []];\n\n    // The tail of the log is the step we just compensated — mark it cancelled.\n    // `undone === undefined` cannot happen while `compensating` (the phase is\n    // only entered with a non-empty log), but the guard keeps the lookup total\n    // and narrows `undone` to `StepId` without a non-null assertion.\n    const undone = lastDone(state.done);\n    if (undone === undefined) return [state, []];\n    const remaining = state.done.slice(0, -1);\n    const items = setStatus(state.items, undone, \"cancelled\");\n\n    // The next step to compensate is the new tail of the log. `nextUndo`\n    // narrows to `StepId` here and to a present step via `stepAt`, so the\n    // continue-vs-terminate branch needs no non-null assertion.\n    const nextUndo = lastDone(remaining);\n    const nextStep = nextUndo === undefined ? undefined : stepAt(nextUndo);\n    if (nextUndo === undefined || nextStep === undefined) {\n      // Fully unwound — terminal failure.\n      return [{ ...state, done: remaining, items, phase: \"aborted\" }, []];\n    }\n\n    const next: SagaState<StepId> = {\n      ...state,\n      done: remaining,\n      items,\n      position: nextUndo,\n    };\n    return [next, [nextStep.undo]];\n  }\n\n  /**\n   * Halt the rollback: the `undo` for the current compensation position itself\n   * FAILED. PURE.\n   *\n   * A failed compensation is a real-world fact — a refund that bounced, a hold\n   * that won't release — and it must become visible terminal state, never leave\n   * the saga wedged in `compensating` forever waiting for an `undoOk` that will\n   * never come. So `undoErr`:\n   *   - flips the in-flight compensation step's ledger record `done → failed`\n   *     (its `undo` did not take, so it is NOT `cancelled`);\n   *   - records the undo failure in `compensationError` (distinct from `error`,\n   *     the forward failure that started the rollback);\n   *   - transitions to the terminal `compensation_failed` phase and emits no\n   *     Cmd. The compensation log is LEFT INTACT (`done` keeps the steps that\n   *     were never rolled back) so the consumer can see exactly which steps\n   *     still need hand reconciliation.\n   *\n   * `undoErr` while not `compensating` is a no-op (same stale-Msg reasoning as\n   * the other verbs): an `undo`-failure Msg that arrives after the saga has\n   * already settled must not re-pivot a terminal saga.\n   */\n  function undoErr(\n    state: SagaState<StepId>,\n    error: unknown,\n  ): readonly [SagaState<StepId>, readonly U[]] {\n    if (state.phase !== \"compensating\") return [state, []];\n\n    // The step whose `undo` just failed is the current compensation position.\n    // Its forward effect stands un-reversed, so its record goes `done → failed`,\n    // not `cancelled`.\n    const items = setStatus(state.items, state.position, \"failed\");\n    return [\n      {\n        ...state,\n        items,\n        compensationError: error,\n        phase: \"compensation_failed\",\n      },\n      [],\n    ];\n  }\n\n  return {\n    init: initSaga<StepId>,\n    start,\n    stepOk,\n    stepErr,\n    undoOk,\n    undoErr,\n    isCommitted,\n    isAborted,\n    isCompensationFailed,\n    isSettled,\n  };\n}\n"]}