@demlik/tea 0.1.2 → 0.3.0

package/dist/work-queue/adapter.js

@@ -1,4 +1,4 @@
-export { queueAdapter } from '../chunk-HJO6VNQI.js';
-import '../chunk-TGG26XMK.js';
+export { queueAdapter } from '../chunk-MU6MCIAC.js';
+import '../chunk-FV3Z5MBE.js';
 //# sourceMappingURL=adapter.js.map
 //# sourceMappingURL=adapter.js.map

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

@@ -1,7 +1,8 @@
-import { Store } from '../index.js';
-import '../core-BoB6t7dB.js';
+import { S as Store } from '../runtime-types-gsog27b6.js';
+import '../core-42kapW0n.js';
 
 /**
+ * @packageDocumentation
  * @demlik/tea/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.
  *
  * Two public surfaces, one shape:

package/dist/work-queue/index.js

@@ -1,4 +1,4 @@
-import { enqueueOp, claimNextOp, markDoneOp, patchItemOp, resetRunningOp, removeOp } from '../chunk-TGG26XMK.js';
+import { enqueueOp, claimNextOp, markDoneOp, patchItemOp, resetRunningOp, removeOp } from '../chunk-FV3Z5MBE.js';
 
 // src/work-queue/index.ts
 function genId() {

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

@@ -1 +1 @@
-{"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"]}
+{"version":3,"sources":["../../src/work-queue/index.ts"],"names":[],"mappings":";;;AAsCA,SAAS,KAAA,GAAgB;AACvB,EAAA,OACE,WAAW,MAAA,EAAQ,UAAA,IAAa,IAChC,CAAA,EAAA,EAAK,KAAK,GAAA,EAAK,CAAA,CAAA,EAAI,IAAA,CAAK,QAAO,CAAE,QAAA,CAAS,EAAE,CAAA,CAAE,KAAA,CAAM,CAAC,CAAC,CAAA,CAAA;AAE1D;AA2CO,SAAS,YAAe,KAAA,EAA8B;AAM3D,EAAA,eAAe,UAAA,GAA6C;AAC1D,IAAA,MAAM,GAAA,GAAM,MAAM,KAAA,CAAM,IAAA,EAAK;AAC7B,IAAA,OAAO,KAAA,CAAM,QAAQ,GAAG,CAAA;AAAA,EAC1B;AAEA,EAAA,eAAe,IAAA,GAAgC;AAC7C,IAAA,OAAQ,MAAM,UAAA,EAAW,IAAM,EAAC;AAAA,EAClC;AAEA,EAAA,eAAe,QAAQ,KAAA,EAA+C;AACpE,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,EAAK;AACzB,IAAA,MAAM,EAAE,IAAA,EAAM,IAAA,EAAK,GAAI,SAAA,CAAa,KAAA,EAAO,KAAA,EAAO,IAAA,CAAK,GAAA,EAAI,EAAG,KAAA,EAAO,CAAA;AACrE,IAAA,MAAM,KAAA,CAAM,KAAK,IAAI,CAAA;AACrB,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,eAAe,SAAA,GAA0C;AACvD,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,EAAK;AACzB,IAAA,MAAM,MAAA,GAAS,WAAA,CAAe,KAAA,EAAO,IAAA,CAAK,KAAK,CAAA;AAC/C,IAAA,IAAI,CAAC,QAAQ,OAAO,IAAA;AACpB,IAAA,MAAM,KAAA,CAAM,IAAA,CAAK,MAAA,CAAO,IAAI,CAAA;AAC5B,IAAA,OAAO,MAAA,CAAO,OAAA;AAAA,EAChB;AAMA,EAAA,eAAe,SAAS,EAAA,EAA2B;AACjD,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,EAAK;AACzB,IAAA,MAAM,EAAE,IAAA,EAAM,OAAA,EAAQ,GAAI,UAAA,CAAc,OAAO,EAAE,CAAA;AACjD,IAAA,IAAI,OAAA,EAAS,MAAM,KAAA,CAAM,IAAA,CAAK,IAAI,CAAA;AAAA,EACpC;AAEA,EAAA,eAAe,UAAA,CAAW,IAAY,KAAA,EAA8B;AAClE,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,EAAK;AACzB,IAAA,MAAM,EAAE,MAAM,OAAA,EAAQ,GAAI,YAAe,KAAA,EAAO,EAAA,EAAI,CAAC,IAAA,MAAU;AAAA,MAC7D,GAAG,IAAA;AAAA,MACH,MAAA,EAAQ,QAAA;AAAA,MACR,UAAA,EAAY,KAAK,GAAA,EAAI;AAAA,MACrB;AAAA,KACF,CAAE,CAAA;AACF,IAAA,IAAI,OAAA,EAAS,MAAM,KAAA,CAAM,IAAA,CAAK,IAAI,CAAA;AAAA,EACpC;AAEA,EAAA,eAAe,cAAc,EAAA,EAA2B;AACtD,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,EAAK;AACzB,IAAA,MAAM,EAAE,MAAM,OAAA,EAAQ,GAAI,YAAe,KAAA,EAAO,EAAA,EAAI,CAAC,IAAA,MAAU;AAAA,MAC7D,GAAG,IAAA;AAAA,MACH,MAAA,EAAQ,WAAA;AAAA,MACR,UAAA,EAAY,KAAK,GAAA;AAAI,KACvB,CAAE,CAAA;AACF,IAAA,IAAI,OAAA,EAAS,MAAM,KAAA,CAAM,IAAA,CAAK,IAAI,CAAA;AAAA,EACpC;AAEA,EAAA,eAAe,qBAAA,GAAuC;AACpD,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,EAAK;AACzB,IAAA,MAAM,EAAE,IAAA,EAAM,OAAA,EAAQ,GAAI,eAAkB,KAAK,CAAA;AACjD,IAAA,IAAI,OAAA,EAAS,MAAM,KAAA,CAAM,IAAA,CAAK,IAAI,CAAA;AAAA,EACpC;AAEA,EAAA,eAAe,WAAW,EAAA,EAA2B;AACnD,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,EAAK;AACzB,IAAA,MAAM,EAAE,IAAA,EAAM,OAAA,EAAQ,GAAI,QAAA,CAAY,OAAO,EAAE,CAAA;AAC/C,IAAA,IAAI,OAAA,EAAS,MAAM,KAAA,CAAM,IAAA,CAAK,IAAI,CAAA;AAAA,EACpC;AAEA,EAAA,eAAe,UAAU,EAAA,EAA2B;AAClD,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,EAAK;AACzB,IAAA,MAAM,EAAE,MAAM,OAAA,EAAQ,GAAI,YAAe,KAAA,EAAO,EAAA,EAAI,CAAC,IAAA,MAAU;AAAA,MAC7D,GAAG,IAAA;AAAA,MACH,MAAA,EAAQ,SAAA;AAAA,MACR,SAAA,EAAW,MAAA;AAAA,MACX,UAAA,EAAY,MAAA;AAAA,MACZ,KAAA,EAAO,MAAA;AAAA,MACP,MAAA,EAAQ;AAAA,KACV,CAAE,CAAA;AACF,IAAA,IAAI,OAAA,EAAS,MAAM,KAAA,CAAM,IAAA,CAAK,IAAI,CAAA;AAAA,EACpC;AAQA,EAAA,eAAe,UAAA,CAAW,IAAY,KAAA,EAA8B;AAClE,IAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,EAAK;AACzB,IAAA,MAAM,EAAE,MAAM,OAAA,EAAQ,GAAI,YAAe,KAAA,EAAO,EAAA,EAAI,CAAC,IAAA,MAAU;AAAA,MAC7D,GAAG,IAAA;AAAA,MACH,MAAA,EAAQ;AAAA,KACV,CAAE,CAAA;AACF,IAAA,IAAI,OAAA,EAAS,MAAM,KAAA,CAAM,IAAA,CAAK,IAAI,CAAA;AAAA,EACpC;AAEA,EAAA,OAAO;AAAA,IACL,OAAA;AAAA,IACA,SAAA;AAAA,IACA,QAAA;AAAA,IACA,UAAA;AAAA,IACA,aAAA;AAAA,IACA,qBAAA;AAAA,IACA,UAAA;AAAA,IACA,SAAA;AAAA,IACA,UAAA;AAAA,IACA;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * @packageDocumentation\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

@@ -1,6 +1,6 @@
 import { QueueItem } from './index.js';
-import '../index.js';
-import '../core-BoB6t7dB.js';
+import '../runtime-types-gsog27b6.js';
+import '../core-42kapW0n.js';
 
 /**
  * Pure queue-lifecycle ops over `QueueItem<I>[]` — the BLESSED delegation

package/dist/work-queue/ops.js

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

package/dist/workflow/index.d.ts

@@ -1,8 +1,9 @@
-import { D as DeliveryId, E as EffectLedgerEvent } from '../durable-effects-CO9Uh971.js';
-export { a as EffectConfirmed, b as EffectOwed, e as emptyLedger } from '../durable-effects-CO9Uh971.js';
-import { C as Cmd } from '../core-BoB6t7dB.js';
+import { D as DeliveryId, E as EffectLedgerEvent } from '../durable-effects-CFRngTNA.js';
+export { a as EffectConfirmed, b as EffectOwed, e as emptyLedger } from '../durable-effects-CFRngTNA.js';
+import { C as Cmd } from '../core-42kapW0n.js';
 
 /**
+ * @packageDocumentation
  * @demlik/tea/workflow — the durable-workflow runtime core (#124, the first
  * Phase-1 slice of the Temporal-style durable-workflow engine, epic #118).
  *
@@ -99,6 +100,16 @@ interface WorkflowStep<A> {
      */
     readonly compensation?: A;
 }
+/**
+ * A workflow's step sequence at construction — a NON-EMPTY tuple. A workflow
+ * with nothing to do reaches `completed` only by carrying a final result, and an
+ * empty sequence produces none, so "≥ 1 step" is a precondition. Encoding it as
+ * `readonly [WorkflowStep<A>, ...WorkflowStep<A>[]]` makes the empty case a
+ * COMPILE error at every construction boundary (`init`, `foldWorkflow`,
+ * `workflowGrain`) — parse-don't-validate, so the reducer never needs a runtime
+ * throw to reject a resultless workflow.
+ */
+type WorkflowSteps<A> = readonly [WorkflowStep<A>, ...WorkflowStep<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
@@ -262,6 +273,17 @@ interface CompensationFailedWorkflow<A, R, F> {
  * 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>;
+/** Every `status` discriminant of the {@link WorkflowState} union. */
+type WorkflowStatus = WorkflowState<unknown, unknown, unknown>["status"];
+/**
+ * The runtime accept-set of every {@link WorkflowStatus} — the single source of
+ * truth the boundary snapshot parse keys off (see `do.ts`). Built from an
+ * exhaustive `Record<WorkflowStatus, true>`, so adding a variant to the union
+ * above without listing it here is a COMPILE error: the set can never silently
+ * drift from the union again (the #312 regression, where the #125 compensation
+ * statuses were missing and evicted-mid-rollback grains re-seeded fresh).
+ */
+declare const WORKFLOW_STATUSES: ReadonlySet<string>;
 /**
  * Dispatch the in-flight activity. Routed through the consumer's `interpret`
  * over an injected activity port. The reducer emits this literal; it performs
@@ -295,7 +317,7 @@ interface CompensationCmd<A> extends Cmd<"workflow_compensation"> {
 /** 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
+ *  {@link EffectLedgerEvent}); the {@link WorkflowReducerStep} 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. */
@@ -339,9 +361,20 @@ interface CompensationErr<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>;
+/** Every `type` discriminant tag of the {@link WorkflowMsg} union. */
+type WorkflowMsgType = WorkflowMsg<unknown, unknown>["type"];
+/**
+ * The runtime accept-set of every {@link WorkflowMsgType} — the single source of
+ * truth the boundary replay parse keys off (see `do.ts`). Built from an
+ * exhaustive `Record<WorkflowMsgType, true>`, so adding a Msg variant to the
+ * union above without listing it here is a COMPILE error: the set can never
+ * silently drift from the union again (the #312 regression, where the #125
+ * compensation result tags were missing and dropped from replay).
+ */
+declare const WORKFLOW_MSG_TYPES: ReadonlySet<string>;
 /** 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> {
+interface WorkflowReducerStep<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>>[];
@@ -354,15 +387,14 @@ interface WorkflowStep0<A, R, F> {
  *  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.
+     * Seed a fresh workflow over `steps` (a NON-EMPTY {@link WorkflowSteps}) and
+     * dispatch its first activity → `running` with `current` = step 0, owed on the
+     * ledger. The "≥ 1 step" precondition is carried by the tuple type: an empty
+     * sequence is a compile error at the call site, not a runtime throw here — a
+     * workflow with nothing to do could never reach `completed` (no final result
+     * to carry), so it is unrepresentable by construction.
      */
-    init(steps: readonly WorkflowStep<A>[]): WorkflowStep0<A, R, F>;
+    init(steps: WorkflowSteps<A>): WorkflowReducerStep<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
@@ -375,7 +407,7 @@ interface Workflow<A, R, F> {
      * 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>;
+    onActivityOk(state: WorkflowState<A, R, F>, msg: ActivityOk<R>): WorkflowReducerStep<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,
@@ -386,7 +418,7 @@ interface Workflow<A, R, F> {
      * 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>;
+    onActivityErr(state: WorkflowState<A, R, F>, msg: ActivityErr<F>): WorkflowReducerStep<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,
@@ -395,7 +427,7 @@ interface Workflow<A, R, F> {
      * `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>;
+    onCompensationOk(state: WorkflowState<A, R, F>, msg: CompensationOk): WorkflowReducerStep<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
@@ -403,7 +435,7 @@ interface Workflow<A, R, F> {
      * 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>;
+    onCompensationErr(state: WorkflowState<A, R, F>, msg: CompensationErr<F>): WorkflowReducerStep<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
@@ -445,6 +477,6 @@ declare function createWorkflow<A, R, F>(restore?: {
  * 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>;
+declare function foldWorkflow<A, R, F>(steps: WorkflowSteps<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 };
+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, WORKFLOW_MSG_TYPES, WORKFLOW_STATUSES, type Workflow, type WorkflowCmd, type WorkflowMsg, type WorkflowMsgType, type WorkflowReducerStep, type WorkflowState, type WorkflowStatus, type WorkflowStep, type WorkflowSteps, createWorkflow, foldWorkflow };

package/dist/workflow/index.js

@@ -1,7 +1,39 @@
-import { pendingEffectsLedger, foldLedger, survivingEffects } from '../chunk-3545BOYL.js';
-export { emptyLedger } from '../chunk-3545BOYL.js';
+import { pendingEffectsLedger, foldLedger, survivingEffects } from '../chunk-25LBDCBC.js';
+export { emptyLedger } from '../chunk-25LBDCBC.js';
+
+// src/workflow/route.ts
+function routeWorkflowMsg(wf, state, msg) {
+  switch (msg.type) {
+    case "activity_ok":
+      return wf.onActivityOk(state, msg);
+    case "activity_err":
+      return wf.onActivityErr(state, msg);
+    case "compensation_ok":
+      return wf.onCompensationOk(state, msg);
+    case "compensation_err":
+      return wf.onCompensationErr(state, msg);
+  }
+}
 
 // src/workflow/index.ts
+var WORKFLOW_STATUSES = new Set(
+  Object.keys({
+    running: true,
+    completed: true,
+    failed: true,
+    compensating: true,
+    failed_compensated: true,
+    compensation_failed: true
+  })
+);
+var WORKFLOW_MSG_TYPES = new Set(
+  Object.keys({
+    activity_ok: true,
+    activity_err: true,
+    compensation_ok: true,
+    compensation_err: true
+  })
+);
 function createWorkflow(restore) {
   const recorder = pendingEffectsLedger(restore);
   function stepAt(steps, index) {
@@ -53,13 +85,19 @@ function createWorkflow(restore) {
     }
     return null;
   }
+  function continueCompensating(base, next, confirmed) {
+    const compensating = {
+      ...base,
+      current: next.current
+    };
+    return {
+      state: compensating,
+      ledger: [confirmed, next.owed],
+      cmds: [next.cmd]
+    };
+  }
   return {
     init(steps) {
-      if (steps.length === 0) {
-        throw new Error(
-          "createWorkflow.init: a workflow must have at least one step. An empty step sequence has no final result to carry into `completed`, so it is unrepresentable as a completed workflow \u2014 reject it at the boundary rather than admit a resultless terminal state."
-        );
-      }
       const { current, owed, cmd } = oweActivity(stepAt(steps, 0), 0);
       const state = {
         status: "running",
@@ -117,20 +155,18 @@ function createWorkflow(restore) {
         };
         return { state: failed, ledger: [confirmed], cmds: [] };
       }
-      const compensating = {
-        status: "compensating",
-        steps: state.steps,
-        completed: state.completed,
-        failedStep: state.current.step,
-        failure: msg.failure,
-        current: next.current,
-        compensated: []
-      };
-      return {
-        state: compensating,
-        ledger: [confirmed, next.owed],
-        cmds: [next.cmd]
-      };
+      return continueCompensating(
+        {
+          status: "compensating",
+          steps: state.steps,
+          completed: state.completed,
+          failedStep: state.current.step,
+          failure: msg.failure,
+          compensated: []
+        },
+        next,
+        confirmed
+      );
     },
     onCompensationOk(state, msg) {
       if (state.status !== "compensating" || msg.id !== state.current.id) {
@@ -155,20 +191,18 @@ function createWorkflow(restore) {
         };
         return { state: settled, ledger: [confirmed], cmds: [] };
       }
-      const compensating = {
-        status: "compensating",
-        steps: state.steps,
-        completed: state.completed,
-        failedStep: state.failedStep,
-        failure: state.failure,
-        current: next.current,
-        compensated
-      };
-      return {
-        state: compensating,
-        ledger: [confirmed, next.owed],
-        cmds: [next.cmd]
-      };
+      return continueCompensating(
+        {
+          status: "compensating",
+          steps: state.steps,
+          completed: state.completed,
+          failedStep: state.failedStep,
+          failure: state.failure,
+          compensated
+        },
+        next,
+        confirmed
+      );
     },
     onCompensationErr(state, msg) {
       if (state.status !== "compensating" || msg.id !== state.current.id) {
@@ -200,26 +234,11 @@ function foldWorkflow(steps, msgs) {
   const wf = createWorkflow();
   let { state } = wf.init(steps);
   for (const msg of msgs) {
-    let step;
-    switch (msg.type) {
-      case "activity_ok":
-        step = wf.onActivityOk(state, msg);
-        break;
-      case "activity_err":
-        step = wf.onActivityErr(state, msg);
-        break;
-      case "compensation_ok":
-        step = wf.onCompensationOk(state, msg);
-        break;
-      case "compensation_err":
-        step = wf.onCompensationErr(state, msg);
-        break;
-    }
-    state = step.state;
+    state = routeWorkflowMsg(wf, state, msg).state;
   }
   return state;
 }
 
-export { createWorkflow, foldWorkflow };
+export { WORKFLOW_MSG_TYPES, WORKFLOW_STATUSES, createWorkflow, foldWorkflow };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map