@demlik/tea 0.13.0 → 0.15.0

package/dist/saga/index.d.ts

@@ -1,241 +0,0 @@
-import { C as Cmd } from '../core-Co0LWkIA.js';
-import { QueueItem } from '../work-queue/index.js';
-import 'zod';
-import '../runtime-types-CNLmhWif.js';
-import 'better-result';
-
-/**
- * @packageDocumentation
- * @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

@@ -1,150 +0,0 @@
-import { queueAdapter } from '../chunk-MU6MCIAC.js';
-import '../chunk-FV3Z5MBE.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

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/saga/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @packageDocumentation\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"]}

package/dist/samples-B3My5oh2.d.ts

@@ -1,59 +0,0 @@
-import { M as MsgOf, E as EventName } from './graph-B3L5e0N1.js';
-
-type Narrow<U, K> = Extract<U, {
-    type: K;
-}>;
-/**
- * Event `E`'s declared payload — its Msg member minus the `type` the chart
- * already owns.
- *
- * Read off `MsgOf<C>` rather than off the `events` section directly, so it is
- * the SAME derivation the compiled machine consumes: a sample that type-checks
- * here is a msg the machine accepts, by construction. An event with no `data`
- * has `DataOf = unknown`, so this is `{}` — no keys, nothing to supply.
- */
-type SamplePayload<C, E extends string> = Omit<Narrow<MsgOf<C>, E>, "type">;
-/** Does event `E` declare a payload the author must fill in? */
-type NeedsSample<C, E extends string> = [keyof SamplePayload<C, E>] extends [
-    never
-] ? false : true;
-/**
- * The sample bag: one entry per event that DECLARES a payload, each typed as
- * exactly that payload.
- *
- * The `as` clause drops the payload-free events from the key union entirely —
- * so `{ START: {} }` for a bare `START: { scope: "edges" }` is an excess
- * property tsc rejects, rather than a meaningless entry it accepts. "Where an
- * event has no declared payload, no sample is required" is therefore not a
- * convention; it is unrepresentable to supply one.
- *
- * The `type` tag is absent for the same reason it is absent from an `assign`'s
- * return: it is the chart's fact, stamped on by {@link sampleMsg}, so the
- * author cannot write it wrong and cannot write it twice.
- *
- * ```ts
- * const samples: Samples<LaneG> = {
- *   WIP: { at: 1 },
- *   FAIL: { at: 2, reason: "flaky" },   // `reason` is REQUIRED — the chart says so
- *   // BLOCKED: …                        // omit one and tsc names it
- * };
- * ```
- */
-type Samples<C> = {
-    readonly [E in EventName<C> as [NeedsSample<C, E>] extends [true] ? E : never]: SamplePayload<C, E>;
-};
-/** The samples bag as the runtime reads it: event name → payload object. */
-type RtSamples = Readonly<Record<string, object | undefined>>;
-/**
- * Build the Msg for `event` from the sample bag: the payload, plus the `type`
- * the chart owns.
- *
- * Returns `undefined` exactly when the event needs a payload and none was
- * supplied — which is the honest "cannot" the guard preview degrades on,
- * rather than a half-built msg that makes a guard throw for the wrong reason.
- */
-declare function sampleMsg(event: string, hasPayload: boolean, samples: RtSamples | undefined): {
-    readonly type: string;
-} | undefined;
-
-export { type RtSamples as R, type SamplePayload as S, type Samples as a, sampleMsg as s };

package/dist/snapshot/index.js

@@ -1,5 +0,0 @@
-export { createSnapshot, snapshotFailed, snapshotLoadFailed, snapshotLoaded, snapshotSaved } from '../chunk-O4MVQTEJ.js';
-import '../chunk-ZSUUOEPL.js';
-import '../chunk-OOYD44JI.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/snapshot/index.js.map

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