@demlik/tea 0.1.0 → 0.1.1

package/dist/work-queue/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/work-queue/ops.ts","../../src/work-queue/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Pure queue-lifecycle ops over `QueueItem<I>[]`.\n *\n * Each op is `(queue, ...args) => { next, result? }`. No I/O, no Date.now\n * indirection beyond a plain call site — the adapter in `./index.ts` injects\n * `Store<QueueItem<I>[]>` and orchestrates `load → mutate → save`.\n *\n * Substrate-agnostic by construction: nothing here references chrome.storage,\n * Cloudflare, or any concrete persistence layer. The audit-specific shape\n * (journeyId, projectId, ...) is lifted into the caller's `I` parameter.\n *\n * NOT exported from package root. Tests reach this file only through the\n * `createQueue(memoryStore(...))` adapter — same one-shape-per-package rule as\n * `@demlik/tea/do`.\n */\n\nimport type { QueueItem, QueueItemStatus } from \"./index\";\n\n/** Append a new pending item. Returns the new queue and the created item. */\nexport function enqueueOp<I>(\n  queue: readonly QueueItem<I>[],\n  input: I,\n  now: number,\n  id: string,\n): { next: QueueItem<I>[]; item: QueueItem<I> } {\n  const item: QueueItem<I> = {\n    id,\n    status: \"pending\",\n    input,\n    enqueuedAt: now,\n  };\n  return { next: [...queue, item], item };\n}\n\n/**\n * Claim the first pending item by flipping it to `running` and stamping\n * `startedAt`. Returns the new queue and the claimed item, or `null` if no\n * pending item exists.\n */\nexport function claimNextOp<I>(\n  queue: readonly QueueItem<I>[],\n  now: number,\n): { next: QueueItem<I>[]; claimed: QueueItem<I> } | null {\n  const idx = queue.findIndex((i) => i.status === \"pending\");\n  if (idx === -1) return null;\n  // `idx !== -1` guarantees the slot is present.\n  const claimed: QueueItem<I> = {\n    ...queue[idx]!,\n    status: \"running\",\n    startedAt: now,\n  };\n  const next = queue.slice();\n  next[idx] = claimed;\n  return { next, claimed };\n}\n\n/**\n * Done items leave the queue — completed runs live wherever the caller\n * persists their output. Returns the new queue (or the original reference if\n * no item matched, so the adapter can skip a save).\n */\nexport function markDoneOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const next = queue.filter((i) => i.id !== id);\n  return { next, changed: next.length !== queue.length };\n}\n\n/**\n * Generic single-item status transition. Used by `markFailed`,\n * `markCancelled`, `retryItem`, `bindOutput`. The patch closure receives the\n * matched item and returns its replacement; returning the same reference is\n * fine (the adapter only saves on `changed`).\n */\nexport function patchItemOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n  patch: (item: QueueItem<I>) => QueueItem<I>,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const idx = queue.findIndex((i) => i.id === id);\n  if (idx === -1) return { next: queue.slice(), changed: false };\n  const next = queue.slice();\n  // `idx !== -1` guarantees the slot is present.\n  next[idx] = patch(queue[idx]!);\n  return { next, changed: true };\n}\n\n/** Reset every `running` item back to `pending`, clearing `startedAt`. */\nexport function resetRunningOp<I>(queue: readonly QueueItem<I>[]): {\n  next: QueueItem<I>[];\n  changed: boolean;\n} {\n  let changed = false;\n  const next = queue.map((i) => {\n    if (i.status !== \"running\") return i;\n    changed = true;\n    return { ...i, status: \"pending\" as QueueItemStatus, startedAt: undefined };\n  });\n  return { next, changed };\n}\n\n/** Hard-delete an item regardless of status. */\nexport function removeOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const next = queue.filter((i) => i.id !== id);\n  return { next, changed: next.length !== queue.length };\n}\n","/**\n * @demlik/tea/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.\n *\n * The pure ops live in `./ops` and are NOT exported. Tests and consumers reach\n * them only through `createQueue(store)`. This mirrors `@demlik/tea/do`'s\n * one-shape-per-package rule: a single adapter is the public surface.\n *\n * The package is generic in the input payload `I` (audit-specific fields go\n * here in apps/extension). `output` is a free-form side-channel correlation\n * token (a backend id, URL, trace id) — typed as `string` because that's its\n * only honest type. Consumers that need structured per-item data persist it in\n * their own store and put the foreign-key string in `output`.\n */\n\nimport type { Store } from \"../index\";\nimport { claimNextOp, enqueueOp, markDoneOp, patchItemOp, removeOp, resetRunningOp } from \"./ops\";\n\n/**\n * Generate a queue-item id at the adapter boundary. Reads `Date.now()` and\n * `Math.random()` — impure helpers belong in the adapter (`index.ts`),\n * never in `ops.ts` (which is purely-functional by contract). Uses native\n * UUID when available, falls back to timestamp + random for environments\n * without `crypto.randomUUID`.\n */\nfunction genId(): string {\n  return (\n    globalThis.crypto?.randomUUID?.() ?? `q_${Date.now()}_${Math.random().toString(36).slice(2)}`\n  );\n}\n\nexport type QueueItemStatus = \"pending\" | \"running\" | \"done\" | \"failed\" | \"cancelled\";\n\nexport interface QueueItem<I> {\n  id: string;\n  status: QueueItemStatus;\n  input: I;\n  enqueuedAt: number;\n  startedAt?: number;\n  finishedAt?: number;\n  output?: string;\n  error?: string;\n}\n\n/**\n * Caller-facing enqueue payload. Just `I` today — kept named so future\n * variants (priority, deferUntil, …) can grow without breaking callers.\n */\nexport type EnqueueInput<I> = I;\n\n/**\n * Adapter that binds the pure ops to an injected `Store<QueueItem<I>[]>`.\n *\n * `load → mutate → save` is the only durability discipline this package\n * imposes. The store decides what \"save\" means (chrome.storage, KV, DO\n * storage, in-memory) — that decision belongs at the caller.\n *\n * Ops that don't change the queue (e.g. `markDone` on an unknown id) skip the\n * save call so the underlying store doesn't observe a write churn.\n */\nexport function createQueue<I>(store: Store<QueueItem<I>[]>) {\n  // `Store<S>.load()` returns `unknown` (invariant 8 boundary). Route\n  // through `store.migrate(raw)` to get the typed value before any\n  // queue operation reads it — same wiring the substrate's `run()` uses at\n  // boot. The work queue is a substrate-agnostic primitive on top of\n  // `Store<S>`, so it honors the same contract.\n  async function loadParsed(): Promise<QueueItem<I>[] | null> {\n    const raw = await store.load();\n    return store.migrate(raw);\n  }\n\n  async function list(): Promise<QueueItem<I>[]> {\n    return (await loadParsed()) ?? [];\n  }\n\n  async function enqueue(input: EnqueueInput<I>): Promise<QueueItem<I>> {\n    const queue = await list();\n    const { next, item } = enqueueOp<I>(queue, input, Date.now(), genId());\n    await store.save(next);\n    return item;\n  }\n\n  async function claimNext(): Promise<QueueItem<I> | null> {\n    const queue = await list();\n    const result = claimNextOp<I>(queue, Date.now());\n    if (!result) return null;\n    await store.save(result.next);\n    return result.claimed;\n  }\n\n  // `markDone` ignores the optional second arg by design: completed runs leave\n  // the queue, and the consumer is expected to persist any output (auditId,\n  // etc.) wherever those completed records belong. Kept in the signature for\n  // call-site readability and forward-compat with `bindOutput`.\n  async function markDone(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = markDoneOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function markFailed(id: string, error: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"failed\",\n      finishedAt: Date.now(),\n      error,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function markCancelled(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"cancelled\",\n      finishedAt: Date.now(),\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function resetRunningToPending(): Promise<void> {\n    const queue = await list();\n    const { next, changed } = resetRunningOp<I>(queue);\n    if (changed) await store.save(next);\n  }\n\n  async function removeItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = removeOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function retryItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"pending\",\n      startedAt: undefined,\n      finishedAt: undefined,\n      error: undefined,\n      output: undefined,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  // `bindOutput` attaches a side-channel correlation token (string) to a\n  // running item without changing its status. The queue can't reach into\n  // `I` to mutate it (the substrate is domain-agnostic), so callers that\n  // need to thread a backend id / URL / trace id through the lifecycle\n  // route it here. Consumers needing structured payloads should persist\n  // them in their own store and put the foreign-key string in `output`.\n  async function bindOutput(id: string, value: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      output: value,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  return {\n    enqueue,\n    claimNext,\n    markDone,\n    markFailed,\n    markCancelled,\n    resetRunningToPending,\n    removeItem,\n    retryItem,\n    bindOutput,\n    list,\n  };\n}\n"]}
+{"version":3,"sources":["../../src/work-queue/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.\n *\n * Two public surfaces, one shape:\n *   - `createQueue(store)` (this file) is the in-process adapter — it binds the\n *     pure ops to an injected `Store` and runs `load → mutate → save`.\n *   - `@demlik/tea/work-queue/ops` (`./ops`) is the BLESSED, importable surface\n *     of those same pure ops. L2 compositions that own their own Model slice\n *     (`monitored-run`, `idempotent-intake`, …) import the ops directly and\n *     delegate status flips to them instead of re-rolling the transitions.\n * Both routes call the identical ops, so the lifecycle rules live in exactly\n * one place. This mirrors `@demlik/tea/do`'s one-shape-per-package rule.\n *\n * The package is generic in the input payload `I` (audit-specific fields go\n * here in apps/extension). `output` is a free-form side-channel correlation\n * token (a backend id, URL, trace id) — typed as `string` because that's its\n * only honest type. Consumers that need structured per-item data persist it in\n * their own store and put the foreign-key string in `output`.\n */\n\nimport type { Store } from \"../index\";\nimport {\n  claimNextOp,\n  enqueueOp,\n  markDoneOp,\n  patchItemOp,\n  removeOp,\n  resetRunningOp,\n} from \"./ops\";\n\n/**\n * Generate a queue-item id at the adapter boundary. Reads `Date.now()` and\n * `Math.random()` — impure helpers belong in the adapter (`index.ts`),\n * never in `ops.ts` (which is purely-functional by contract). Uses native\n * UUID when available, falls back to timestamp + random for environments\n * without `crypto.randomUUID`.\n */\nfunction genId(): string {\n  return (\n    globalThis.crypto?.randomUUID?.() ??\n    `q_${Date.now()}_${Math.random().toString(36).slice(2)}`\n  );\n}\n\nexport type QueueItemStatus =\n  | \"pending\"\n  | \"running\"\n  | \"done\"\n  | \"failed\"\n  | \"cancelled\";\n\n/**\n * A single queue entry. Every field is `readonly`: a persisted slice is\n * immutable, so a transition returns a NEW item (the ops always spread —\n * `{ ...item, status: … }`) rather than mutating in place. This type-enforces\n * the durability invariant the consumers already honor by convention, and\n * keeps a slice round-trippable through JSON unchanged across a reload.\n */\nexport interface QueueItem<I> {\n  readonly id: string;\n  readonly status: QueueItemStatus;\n  readonly input: I;\n  readonly enqueuedAt: number;\n  readonly startedAt?: number;\n  readonly finishedAt?: number;\n  readonly output?: string;\n  readonly error?: string;\n}\n\n/**\n * Caller-facing enqueue payload. Just `I` today — kept named so future\n * variants (priority, deferUntil, …) can grow without breaking callers.\n */\nexport type EnqueueInput<I> = I;\n\n/**\n * Adapter that binds the pure ops to an injected `Store<QueueItem<I>[]>`.\n *\n * `load → mutate → save` is the only durability discipline this package\n * imposes. The store decides what \"save\" means (chrome.storage, KV, DO\n * storage, in-memory) — that decision belongs at the caller.\n *\n * Ops that don't change the queue (e.g. `markDone` on an unknown id) skip the\n * save call so the underlying store doesn't observe a write churn.\n */\nexport function createQueue<I>(store: Store<QueueItem<I>[]>) {\n  // `Store<S>.load()` returns `unknown` (invariant 8 boundary). Route\n  // through `store.migrate(raw)` to get the typed value before any\n  // queue operation reads it — same wiring the substrate's `run()` uses at\n  // boot. The work queue is a substrate-agnostic primitive on top of\n  // `Store<S>`, so it honors the same contract.\n  async function loadParsed(): Promise<QueueItem<I>[] | null> {\n    const raw = await store.load();\n    return store.migrate(raw);\n  }\n\n  async function list(): Promise<QueueItem<I>[]> {\n    return (await loadParsed()) ?? [];\n  }\n\n  async function enqueue(input: EnqueueInput<I>): Promise<QueueItem<I>> {\n    const queue = await list();\n    const { next, item } = enqueueOp<I>(queue, input, Date.now(), genId());\n    await store.save(next);\n    return item;\n  }\n\n  async function claimNext(): Promise<QueueItem<I> | null> {\n    const queue = await list();\n    const result = claimNextOp<I>(queue, Date.now());\n    if (!result) return null;\n    await store.save(result.next);\n    return result.claimed;\n  }\n\n  // `markDone` ignores the optional second arg by design: completed runs leave\n  // the queue, and the consumer is expected to persist any output (auditId,\n  // etc.) wherever those completed records belong. Kept in the signature for\n  // call-site readability and forward-compat with `bindOutput`.\n  async function markDone(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = markDoneOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function markFailed(id: string, error: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"failed\",\n      finishedAt: Date.now(),\n      error,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function markCancelled(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"cancelled\",\n      finishedAt: Date.now(),\n    }));\n    if (changed) await store.save(next);\n  }\n\n  async function resetRunningToPending(): Promise<void> {\n    const queue = await list();\n    const { next, changed } = resetRunningOp<I>(queue);\n    if (changed) await store.save(next);\n  }\n\n  async function removeItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = removeOp<I>(queue, id);\n    if (changed) await store.save(next);\n  }\n\n  async function retryItem(id: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      status: \"pending\",\n      startedAt: undefined,\n      finishedAt: undefined,\n      error: undefined,\n      output: undefined,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  // `bindOutput` attaches a side-channel correlation token (string) to a\n  // running item without changing its status. The queue can't reach into\n  // `I` to mutate it (the substrate is domain-agnostic), so callers that\n  // need to thread a backend id / URL / trace id through the lifecycle\n  // route it here. Consumers needing structured payloads should persist\n  // them in their own store and put the foreign-key string in `output`.\n  async function bindOutput(id: string, value: string): Promise<void> {\n    const queue = await list();\n    const { next, changed } = patchItemOp<I>(queue, id, (item) => ({\n      ...item,\n      output: value,\n    }));\n    if (changed) await store.save(next);\n  }\n\n  return {\n    enqueue,\n    claimNext,\n    markDone,\n    markFailed,\n    markCancelled,\n    resetRunningToPending,\n    removeItem,\n    retryItem,\n    bindOutput,\n    list,\n  };\n}\n"]}

package/dist/work-queue/ops.d.ts

@@ -0,0 +1,69 @@
+import { QueueItem } from './index.js';
+import '../index.js';
+import '../core-CymXZCeY.js';
+
+/**
+ * Pure queue-lifecycle ops over `QueueItem<I>[]` — the BLESSED delegation
+ * surface for this package.
+ *
+ * Each op is `(queue, ...args) => { next, result? }`. No I/O, no Date.now
+ * indirection beyond a plain call site — the adapter in `./index.ts` injects
+ * `Store<QueueItem<I>[]>` and orchestrates `load → mutate → save`.
+ *
+ * Substrate-agnostic by construction: nothing here references chrome.storage,
+ * Cloudflare, or any concrete persistence layer. The audit-specific shape
+ * (journeyId, projectId, ...) is lifted into the caller's `I` parameter.
+ *
+ * Importable two ways. The `createQueue(...)` adapter in `./index.ts` binds
+ * these ops to a `Store` for in-process use (same one-shape-per-package rule
+ * as `@demlik/tea/do`). L2 compositions that own their own Model slice
+ * (`monitored-run`, `idempotent-intake`, …) instead reach these ops directly
+ * via the `@demlik/tea/work-queue/ops` subpath, so a status flip is delegated
+ * here rather than re-rolled per call site.
+ */
+
+/** Append a new pending item. Returns the new queue and the created item. */
+declare function enqueueOp<I>(queue: readonly QueueItem<I>[], input: I, now: number, id: string): {
+    next: QueueItem<I>[];
+    item: QueueItem<I>;
+};
+/**
+ * Claim the first pending item by flipping it to `running` and stamping
+ * `startedAt`. Returns the new queue and the claimed item, or `null` if no
+ * pending item exists.
+ */
+declare function claimNextOp<I>(queue: readonly QueueItem<I>[], now: number): {
+    next: QueueItem<I>[];
+    claimed: QueueItem<I>;
+} | null;
+/**
+ * Done items leave the queue — completed runs live wherever the caller
+ * persists their output. Returns the new queue (or the original reference if
+ * no item matched, so the adapter can skip a save).
+ */
+declare function markDoneOp<I>(queue: readonly QueueItem<I>[], id: string): {
+    next: QueueItem<I>[];
+    changed: boolean;
+};
+/**
+ * Generic single-item status transition. Used by `markFailed`,
+ * `markCancelled`, `retryItem`, `bindOutput`. The patch closure receives the
+ * matched item and returns its replacement; returning the same reference is
+ * fine (the adapter only saves on `changed`).
+ */
+declare function patchItemOp<I>(queue: readonly QueueItem<I>[], id: string, patch: (item: QueueItem<I>) => QueueItem<I>): {
+    next: QueueItem<I>[];
+    changed: boolean;
+};
+/** Reset every `running` item back to `pending`, clearing `startedAt`. */
+declare function resetRunningOp<I>(queue: readonly QueueItem<I>[]): {
+    next: QueueItem<I>[];
+    changed: boolean;
+};
+/** Hard-delete an item regardless of status. */
+declare function removeOp<I>(queue: readonly QueueItem<I>[], id: string): {
+    next: QueueItem<I>[];
+    changed: boolean;
+};
+
+export { claimNextOp, enqueueOp, markDoneOp, patchItemOp, removeOp, resetRunningOp };

package/dist/work-queue/ops.js

@@ -0,0 +1,3 @@
+export { claimNextOp, enqueueOp, markDoneOp, patchItemOp, removeOp, resetRunningOp } from '../chunk-TGG26XMK.js';
+//# sourceMappingURL=ops.js.map
+//# sourceMappingURL=ops.js.map

package/dist/work-queue/ops.js.map

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

package/dist/workflow/index.d.ts

@@ -0,0 +1,444 @@
+import { D as DeliveryId, E as EffectLedgerEvent } from '../durable-effects-2MDxDs45.js';
+export { a as EffectConfirmed, b as EffectOwed, e as emptyLedger } from '../durable-effects-2MDxDs45.js';
+import { C as Cmd } from '../core-CymXZCeY.js';
+
+/**
+ * @demlik/tea/workflow — the durable-workflow runtime core (#124, the first
+ * Phase-1 slice of the Temporal-style durable-workflow engine, epic #118).
+ *
+ * A workflow is a long-running, multi-step transaction whose every step (an
+ * **activity**) is a side effect that may evict the actor mid-flight. The
+ * substrate already solves "a state survives eviction" (the event-sourced
+ * store) and "an owed effect survives eviction" (the `do/` pending-effects
+ * ledger, #67). This module composes those two into the third primitive: a
+ * **pure TEA reducer over a workflow's progress**, where each step is dispatched
+ * as a durable owed effect and the next step is decided only after the previous
+ * one's result is folded back in. That is exactly Temporal's contract — a
+ * deterministic workflow function whose activities are the only impurity, so a
+ * replay of the event log re-decides every step identically.
+ *
+ * The mapping onto TEA, mirroring `../raft`:
+ *
+ *   - **Reducer** — {@link createWorkflow}'s verbs (`init`, `onActivityOk`,
+ *     `onActivityErr`) are the transition function over {@link WorkflowState}.
+ *     PURE: they read no clock and no RNG. Wall time, randomness, retries — all
+ *     impurity lives in the consumer's injected *interpret cell* (the thing that
+ *     actually performs the activity `Cmd` and dispatches its result `Msg`).
+ *     A workflow driven by a recorded result schedule re-decides bit-for-bit —
+ *     the headline replay-determinism payoff (acceptance criterion 4).
+ *   - **Cmd** — the activity dispatch is an {@link ActivityCmd}, recorded on the
+ *     #67 ledger as an `effect_owed` BEFORE it is performed and `effect_confirmed`
+ *     on its result. This module emits the Cmd literals; it performs NO side
+ *     effects. The owed/confirmed events are persisted into the same log the
+ *     reducer folds, so the ledger (and thus "which activity is still owed")
+ *     rebuilds for free on cold wake — re-emit-on-wake is idempotent by the
+ *     ledger's monotonic delivery id (acceptance criterion 3).
+ *   - **Msg** — an activity result (`activity_ok` / `activity_err`) is a `Msg`
+ *     the consumer routes back into a verb. The verb folds the result, records
+ *     the completed step, and advances to the next activity (or to `completed`
+ *     when the sequence is exhausted).
+ *
+ * **Invalid states unrepresentable.** The in-flight activity (`current`, with
+ * its delivery id) lives ONLY on the `running` variant of {@link WorkflowState}.
+ * A `completed` workflow carries its final output and no current activity; a
+ * `failed` one carries its failure and no current activity. So "the current
+ * activity exists only while running" is a type-level guarantee, not a runtime
+ * convention (acceptance criterion 1).
+ *
+ * **Forward-only (#124 scope).** This core advances FORWARD on success. A step
+ * failure transitions to `failed` — a deliberate placeholder. Compensation /
+ * Saga rollback (the reverse-ordered sequence of compensating activities) is
+ * #125; the `// #125:` seam in {@link Workflow.onActivityErr} marks exactly
+ * where that slice hooks in. DO-grain host wrapping is #126; the Saga demo is
+ * #127.
+ * This module is the pure reducer only — like `../raft/index.ts` is the pure
+ * Raft reducer with the DO grain deferred to its `./do` sibling.
+ *
+ * Generic over three opaque payloads, like raft's command generic: the activity
+ * descriptor `A` (what a step asks to do — the consumer's interpret cell knows
+ * how to perform it), the activity result `R`, and the failure `F`. The reducer
+ * never inspects them; it only sequences them.
+ *
+ * NOT a substrate primitive: it depends only on the core `Cmd` type and the
+ * sibling `../do` durable-effects ledger. Consumers reach it via the
+ * `@demlik/tea/workflow` subpath.
+ */
+
+/**
+ * One step of a workflow: a named activity descriptor. `A` is the opaque
+ * payload the consumer's interpret cell knows how to perform (an HTTP call, a
+ * sibling-grain message, a tool round-trip). The reducer never inspects
+ * `activity` — it only sequences the steps and correlates results.
+ *
+ * A step may declare a **compensation** — the inverse activity that undoes the
+ * forward one (cancel the reservation, refund the charge). Compensation is the
+ * `{ do, undo }` pair of `@demlik/tea/saga` mapped onto the workflow: the step's
+ * `activity` is the `do`, its `compensation` is the `undo`. The pair is the unit
+ * of reversibility — a step that completed (its forward activity succeeded) is
+ * exactly a step whose `compensation` must run, in reverse order, if a LATER
+ * step fails (#125). A step WITHOUT a compensation contributes nothing to the
+ * unwind: it is skipped during the reverse walk (an irreversible step — a sent
+ * email — that the saga model treats as a no-op `undo`).
+ */
+interface WorkflowStep<A> {
+    /** Stable, human-readable step name — appears in the completed-step record. */
+    readonly name: string;
+    /** The opaque activity this step performs. Interpreted by the consumer. */
+    readonly activity: A;
+    /**
+     * The opaque compensating (inverse) activity, performed in reverse order on a
+     * downstream failure (#125). Optional: a step with no compensation is skipped
+     * during the unwind. Interpreted by the consumer's interpret cell, exactly
+     * like {@link activity}.
+     */
+    readonly compensation?: A;
+}
+/**
+ * A completed step: the step that ran plus the result its activity produced.
+ * The `running` state accumulates these in execution order, so the full
+ * forward history is available to the consumer (and to #125's compensation,
+ * which will walk it in reverse).
+ */
+interface CompletedStep<A, R> {
+    readonly step: WorkflowStep<A>;
+    readonly result: R;
+}
+/** The activity currently in flight on a `running` workflow. */
+interface InFlightActivity<A> {
+    /** The 0-based index of this step in the workflow's step sequence. */
+    readonly index: number;
+    /** The step whose activity is in flight. */
+    readonly step: WorkflowStep<A>;
+    /** The #67 ledger delivery id this activity was owed under (the dedup key). */
+    readonly id: DeliveryId;
+}
+/**
+ * The compensation currently in flight on a `compensating` workflow (#125). The
+ * mirror of {@link InFlightActivity} for the reverse walk: exactly one
+ * compensation is owed at a time, on the SAME #67 ledger, with its own monotonic
+ * delivery id. `index` is the index (into `completed`/`steps`) of the step being
+ * undone — the unwind walks these from high to low (strict reverse order).
+ */
+interface InFlightCompensation<A> {
+    /** The 0-based index (into the step sequence) of the step being compensated. */
+    readonly index: number;
+    /** The step whose compensation is in flight. */
+    readonly step: WorkflowStep<A>;
+    /** The #67 ledger delivery id this compensation was owed under (the dedup key). */
+    readonly id: DeliveryId;
+}
+/**
+ * A workflow in progress. Carries the ordered `completed` steps (forward
+ * history), the `steps` it is sequencing, and the `current` in-flight activity
+ * (with its ledger delivery id). `completed.length === current.index` always
+ * holds — the current activity is the next step after the last completed one.
+ */
+interface RunningWorkflow<A, R> {
+    readonly status: "running";
+    /** The full, static step sequence this workflow runs. */
+    readonly steps: readonly WorkflowStep<A>[];
+    /** Steps that have produced a result, in execution order. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The single activity in flight right now. */
+    readonly current: InFlightActivity<A>;
+}
+/**
+ * A workflow that ran every step to completion. `output` is the result of the
+ * final step — the workflow's overall output. No activity is in flight.
+ */
+interface CompletedWorkflow<A, R> {
+    readonly status: "completed";
+    readonly steps: readonly WorkflowStep<A>[];
+    /** Every step, in execution order, with its result. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The final step's result — the workflow's output. */
+    readonly output: R;
+}
+/**
+ * A workflow that failed on an activity with NOTHING to compensate — the
+ * forward failure happened with zero completed steps (the first activity
+ * failed). `failedStep` is the step whose activity reported the failure;
+ * `failure` is the opaque failure payload. `completed` is empty by construction:
+ * a failure WITH completed steps pivots into {@link CompensatingWorkflow}
+ * instead, so `failed` is precisely the empty-rollback terminal (the analogue
+ * of saga's `aborted` reached straight from the first step). No activity is in
+ * flight; this is terminal (#125 acceptance criterion 3).
+ */
+interface FailedWorkflow<A, R, F> {
+    readonly status: "failed";
+    readonly steps: readonly WorkflowStep<A>[];
+    /** Empty by construction — a failure with completed steps compensates instead. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The step whose activity failed. */
+    readonly failedStep: WorkflowStep<A>;
+    /** The opaque failure the activity reported. */
+    readonly failure: F;
+}
+/**
+ * A workflow unwinding after a forward failure (#125): the compensations of the
+ * `completed` steps are being emitted in STRICT REVERSE order, one at a time, on
+ * the same #67 ledger. The analogue of saga's `compensating` phase.
+ *
+ * `current` is the single compensation in flight (the mirror of `running`'s
+ * in-flight activity). `compensated` records, in unwind order, the completed
+ * steps whose compensation has confirmed — the reverse-walk's progress log, so
+ * a cold wake resumes mid-rollback exactly. `failedStep`/`failure` carry the
+ * forward failure that triggered the unwind (verbatim, never interpreted),
+ * preserved for the consumer to read and to fold onto the terminal state.
+ *
+ * Invariant: the unwind walks `completed` from its tail toward index 0, skipping
+ * steps with no compensation, so `current.index` is strictly below the index of
+ * every entry in `compensated`.
+ */
+interface CompensatingWorkflow<A, R, F> {
+    readonly status: "compensating";
+    readonly steps: readonly WorkflowStep<A>[];
+    /** The completed forward steps, in execution order — the history being unwound. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The step whose forward activity failed, triggering the unwind. */
+    readonly failedStep: WorkflowStep<A>;
+    /** The opaque forward failure that triggered the unwind. Carried, never interpreted. */
+    readonly failure: F;
+    /** The single compensation in flight right now. */
+    readonly current: InFlightCompensation<A>;
+    /** Completed steps whose compensation has confirmed, in unwind (reverse) order. */
+    readonly compensated: readonly CompletedStep<A, R>[];
+}
+/**
+ * A workflow that failed forward and then fully unwound: every completed step's
+ * compensation confirmed, in reverse order. Terminal. The analogue of saga's
+ * `aborted` (fully unwound) — named `failed_compensated` to align with #125's
+ * vocabulary. No activity or compensation is in flight.
+ */
+interface FailedCompensatedWorkflow<A, R, F> {
+    readonly status: "failed_compensated";
+    readonly steps: readonly WorkflowStep<A>[];
+    /** The forward steps that completed (and were each compensated), in execution order. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The step whose forward activity failed, triggering the (now-finished) unwind. */
+    readonly failedStep: WorkflowStep<A>;
+    /** The opaque forward failure that triggered compensation. Carried, never interpreted. */
+    readonly failure: F;
+}
+/**
+ * A workflow whose ROLLBACK itself failed: a compensation activity reported a
+ * failure mid-unwind. Terminal, PARTIALLY unwound — the analogue of saga's
+ * `compensation_failed`. A failed compensation is a real-world fact (a refund
+ * that bounced, a hold that won't release) that must become visible terminal
+ * state, never a workflow wedged in `compensating` forever.
+ *
+ * `compensated` is left intact (the steps already rolled back); `uncompensated`
+ * is the step whose compensation bounced PLUS the steps still owed a
+ * compensation behind it — exactly what the consumer must reconcile by hand.
+ * `compensationFailure` is the rollback failure (distinct from `failure`, the
+ * forward failure that started the unwind), carried verbatim.
+ */
+interface CompensationFailedWorkflow<A, R, F> {
+    readonly status: "compensation_failed";
+    readonly steps: readonly WorkflowStep<A>[];
+    /** The full completed-forward history, in execution order. */
+    readonly completed: readonly CompletedStep<A, R>[];
+    /** The step whose forward activity failed, triggering the unwind. */
+    readonly failedStep: WorkflowStep<A>;
+    /** The opaque forward failure that triggered compensation. Carried, never interpreted. */
+    readonly failure: F;
+    /** Completed steps successfully compensated before the rollback broke, in unwind order. */
+    readonly compensated: readonly CompletedStep<A, R>[];
+    /** The step whose compensation bounced. Its forward effect stands un-reversed. */
+    readonly failedCompensationStep: WorkflowStep<A>;
+    /** The opaque rollback failure (distinct from {@link failure}). Carried, never interpreted. */
+    readonly compensationFailure: F;
+}
+/**
+ * The workflow's state — a discriminated union on `status`. The current
+ * in-flight activity is reachable ONLY through `running`, and the in-flight
+ * compensation ONLY through `compensating`, making "an in-flight effect exists
+ * only while the workflow is actively driving one" unrepresentable to violate.
+ */
+type WorkflowState<A, R, F> = RunningWorkflow<A, R> | CompletedWorkflow<A, R> | FailedWorkflow<A, R, F> | CompensatingWorkflow<A, R, F> | FailedCompensatedWorkflow<A, R, F> | CompensationFailedWorkflow<A, R, F>;
+/**
+ * Dispatch the in-flight activity. Routed through the consumer's `interpret`
+ * over an injected activity port. The reducer emits this literal; it performs
+ * no side effect. The result MUST be dispatched back as a Msg carrying `id`.
+ */
+interface ActivityCmd<A> extends Cmd<"workflow_activity"> {
+    /** The 0-based step index this activity belongs to. */
+    readonly index: number;
+    /** The #67 delivery id the result Msg must echo (the dedup key). */
+    readonly id: DeliveryId;
+    /** The opaque activity to perform. */
+    readonly activity: A;
+}
+/**
+ * Dispatch a compensation (#125). Same shape + ledger discipline as
+ * {@link ActivityCmd} — a compensation is just another durable owed effect on
+ * the same #67 ledger, with its own delivery id — but the consumer's interpret
+ * cell performs the inverse `compensation` payload, and the result is dispatched
+ * back as a {@link CompensationOk}/{@link CompensationErr} carrying the SAME id.
+ * Distinguished by `type` so the consumer routes forward vs. inverse work to the
+ * right port, and the re-emit-on-wake stays type-correct.
+ */
+interface CompensationCmd<A> extends Cmd<"workflow_compensation"> {
+    /** The 0-based step index whose compensation this is. */
+    readonly index: number;
+    /** The #67 delivery id the result Msg must echo (the dedup key). */
+    readonly id: DeliveryId;
+    /** The opaque compensating (inverse) activity to perform. */
+    readonly compensation: A;
+}
+/** The Cmd union this module emits: forward activity dispatches AND (#125)
+ *  reverse compensation dispatches. The owed/confirmed ledger events are not
+ *  `WorkflowCmd`s — they are Msg variants persisted into the event log (see
+ *  {@link EffectLedgerEvent}); the {@link WorkflowStep0} tuple carries them out
+ *  alongside the dispatch Cmd so the host persists owed-before-dispatch. Both
+ *  Cmd kinds are owed effects on the same ledger, so `survivingActivities`
+ *  re-emits either kind on cold wake. */
+type WorkflowCmd<A> = ActivityCmd<A> | CompensationCmd<A>;
+/** An activity succeeded: `id` echoes the {@link ActivityCmd} it answers; the
+ *  reducer matches it against `current.id`, records the completed step, and
+ *  advances. */
+interface ActivityOk<R> {
+    readonly type: "activity_ok";
+    readonly id: DeliveryId;
+    readonly result: R;
+}
+/** An activity failed (retries already exhausted by the consumer's interpret
+ *  cell — this module does not retry). `id` echoes the {@link ActivityCmd};
+ *  the reducer begins compensation (or settles `failed` when nothing has
+ *  completed). */
+interface ActivityErr<F> {
+    readonly type: "activity_err";
+    readonly id: DeliveryId;
+    readonly failure: F;
+}
+/** A compensation succeeded (#125): the inverse activity took. `id` echoes the
+ *  {@link CompensationCmd} it answers; the reducer matches it against the
+ *  in-flight compensation's id, records the step as compensated, and either
+ *  emits the next compensation (continuing in reverse) or settles
+ *  `failed_compensated` when the unwind is complete. A compensation produces no
+ *  result the workflow carries — its only signal is "the undo took". */
+interface CompensationOk {
+    readonly type: "compensation_ok";
+    readonly id: DeliveryId;
+}
+/** A compensation itself failed (#125): the inverse activity bounced (a refund
+ *  that won't go through). `id` echoes the {@link CompensationCmd}; the reducer
+ *  halts the rollback at the terminal `compensation_failed` state — never wedged
+ *  in `compensating` forever. */
+interface CompensationErr<F> {
+    readonly type: "compensation_err";
+    readonly id: DeliveryId;
+    readonly failure: F;
+}
+/** The Msg union the reducer folds: forward activity results AND (#125) reverse
+ *  compensation results. */
+type WorkflowMsg<R, F> = ActivityOk<R> | ActivityErr<F> | CompensationOk | CompensationErr<F>;
+/** A workflow reducer step: the next state, the ledger events to persist
+ *  (owed-before-dispatch), and the activity Cmds to dispatch. */
+interface WorkflowStep0<A, R, F> {
+    readonly state: WorkflowState<A, R, F>;
+    /** Ledger events to persist into the event log, in order, BEFORE `cmds`. */
+    readonly ledger: readonly EffectLedgerEvent<WorkflowCmd<A>>[];
+    /** Activity dispatch Cmds, after the ledger events are durable. */
+    readonly cmds: readonly WorkflowCmd<A>[];
+}
+/** The hook bag returned by {@link createWorkflow}. Spread its verbs into a
+ *  machine; `init(steps)` seeds a fresh workflow and emits the first activity,
+ *  the verbs fold results and advance, and `survivingActivities` re-emits the
+ *  owed-but-unconfirmed dispatch on cold wake (idempotent by delivery id). */
+interface Workflow<A, R, F> {
+    /**
+     * Seed a fresh workflow over `steps` and dispatch its first activity.
+     *
+     * - Empty `steps` ⇒ a workflow with nothing to do completes only when it has
+     *   an output; with no steps there is no output, so an empty sequence is
+     *   rejected as a misuse (a workflow must have at least one step). The reducer
+     *   never reaches `completed` without a final result to carry.
+     * - Otherwise → `running` with `current` = step 0, owed on the ledger.
+     */
+    init(steps: readonly WorkflowStep<A>[]): WorkflowStep0<A, R, F>;
+    /**
+     * Fold an activity success. If `msg.id` does not match the in-flight
+     * activity's id (a stale/duplicate result from re-emit-on-wake, or a result
+     * for an already-advanced step), the state is returned UNCHANGED with no
+     * effects — idempotent by delivery id (acceptance criterion 3). Otherwise:
+     * record the completed step, confirm the owed activity on the ledger, and
+     * either advance to the next step (owing its activity) or transition to
+     * `completed` carrying the final result.
+     *
+     * Only meaningful on `running`; a result arriving for a terminal workflow is
+     * a no-op (the workflow is done — at-least-once tolerates the late echo).
+     */
+    onActivityOk(state: WorkflowState<A, R, F>, msg: ActivityOk<R>): WorkflowStep0<A, R, F>;
+    /**
+     * Fold an activity failure (#125). Same id-match idempotency guard as
+     * {@link onActivityOk}. On a match: confirm the owed activity on the ledger,
+     * then PIVOT into compensation — walk the completed-step history in strict
+     * reverse and owe the first declared compensation as a durable effect on the
+     * same ledger, transitioning to `compensating`. If NO completed step declares
+     * a compensation (the empty-rollback edge — the first activity failed, or
+     * every completed step is irreversible), settle `failed` directly with
+     * nothing to unwind.
+     */
+    onActivityErr(state: WorkflowState<A, R, F>, msg: ActivityErr<F>): WorkflowStep0<A, R, F>;
+    /**
+     * Fold a compensation success (#125). Same id-match idempotency guard against
+     * the in-flight compensation. On a match: confirm the owed compensation,
+     * record the step as compensated, and continue the reverse walk — owe the
+     * next declared compensation strictly below the step just undone, or settle
+     * `failed_compensated` when the unwind is complete. Only meaningful on
+     * `compensating`; a result for a terminal/forward workflow is a no-op.
+     */
+    onCompensationOk(state: WorkflowState<A, R, F>, msg: CompensationOk): WorkflowStep0<A, R, F>;
+    /**
+     * Fold a compensation failure (#125). Same id-match idempotency guard. On a
+     * match: confirm the owed compensation and HALT the rollback at the terminal
+     * `compensation_failed` state — a bounced compensation is visible terminal
+     * state to reconcile by hand, never a workflow wedged in `compensating`
+     * forever. Mirrors `@demlik/tea/saga`'s `undoErr`.
+     */
+    onCompensationErr(state: WorkflowState<A, R, F>, msg: CompensationErr<F>): WorkflowStep0<A, R, F>;
+    /**
+     * The owed-but-unconfirmed dispatch(es) to re-emit on activation — a forward
+     * activity OR (#125) a compensation, rebuilt by folding the persisted ledger
+     * events. On a fresh / fully-settled workflow this is empty. The re-fired Cmd
+     * carries the SAME delivery id, so a duplicate result is a no-op at the
+     * reducer (the id-match guard). This is the cold-wake re-emit that makes both
+     * activities AND compensations exactly-once-observable despite the
+     * at-least-once transport (acceptance criterion 2 & 3) — including a
+     * compensation owed mid-rollback when the actor was evicted.
+     */
+    survivingActivities(ledgerEvents: Iterable<EffectLedgerEvent<WorkflowCmd<A>>>): readonly WorkflowCmd<A>[];
+}
+/**
+ * Build a workflow hook bag. The factory captures NO clock and NO RNG — pure
+ * bookkeeping over the injected #67 recorder, exactly like
+ * `pendingEffectsLedger`. `restore` rehydrates the monotonic delivery-id
+ * counter from the persisted ledger events on cold wake, so re-dispatched
+ * activities resume their ids without gaps.
+ *
+ * @param restore - the persisted ledger events (read back from the log) and/or
+ *   the last issued delivery id, so the id counter resumes gap-free. Omit for a
+ *   fresh workflow.
+ */
+declare function createWorkflow<A, R, F>(restore?: {
+    readonly events?: Iterable<EffectLedgerEvent<WorkflowCmd<A>>>;
+    readonly lastId?: DeliveryId;
+}): Workflow<A, R, F>;
+/**
+ * Replay a workflow from its event log: seed over `steps`, then fold each
+ * activity-result `Msg` in order. Returns the final {@link WorkflowState}.
+ *
+ * Determinism: a freshly-constructed {@link createWorkflow} reissues delivery
+ * ids monotonically from 0, and the reducer reads no ambient state — so two
+ * calls with the same `steps` + `msgs` return deeply-equal states (and equal
+ * `JSON.stringify`). This is the byte-identity property #124 pins.
+ *
+ * Note this folds ONLY the result Msgs; the `init` dispatch + per-step
+ * owe/confirm ledger events are an internal effect channel reconstructed by the
+ * fresh recorder, not part of the replayed Msg log — exactly as the activity
+ * results are the only thing the consumer records and replays.
+ */
+declare function foldWorkflow<A, R, F>(steps: readonly WorkflowStep<A>[], msgs: Iterable<WorkflowMsg<R, F>>): WorkflowState<A, R, F>;
+
+export { type ActivityCmd, type ActivityErr, type ActivityOk, type CompensatingWorkflow, type CompensationCmd, type CompensationErr, type CompensationFailedWorkflow, type CompensationOk, type CompletedStep, type CompletedWorkflow, DeliveryId, EffectLedgerEvent, type FailedCompensatedWorkflow, type FailedWorkflow, type InFlightActivity, type InFlightCompensation, type RunningWorkflow, type Workflow, type WorkflowCmd, type WorkflowMsg, type WorkflowState, type WorkflowStep, type WorkflowStep0, createWorkflow, foldWorkflow };