@demlik/tea 0.13.0 → 0.14.0

package/dist/{chunk-ZVJZ72HY.js → chunk-LYLTKJWM.js}

@@ -1,11 +1,28 @@
-import { idempotencyMemory } from './chunk-BYQUGDD3.js';
-import { queueAdapter } from './chunk-MU6MCIAC.js';
+import { idempotencyMemory } from './chunk-PR6TB3BL.js';
+import { queueAdapter } from './chunk-TXN2KFHF.js';
+import { Cmd } from './chunk-RQULHGYH.js';
+import { z } from 'zod';
 
-// src/idempotent-intake/index.ts
+function intakeProcessDef() {
+  return Cmd.define("intake:process", {
+    input: z.custom(),
+    ok: z.void(),
+    err: []
+  });
+}
+function intakeReplayDef() {
+  return Cmd.define("intake:replay", {
+    input: z.custom(),
+    ok: z.void(),
+    err: []
+  });
+}
 function createIntake(config) {
   const { keyOf, ttlMs } = config;
   const queue = queueAdapter();
   const memory = idempotencyMemory();
+  const intakeProcess = intakeProcessDef();
+  const intakeReplay = intakeReplayDef();
   function init() {
     return {
       seen: memory.init(),
@@ -28,7 +45,7 @@ function createIntake(config) {
     const entry = liveEntry(state.seen, key, at);
     if (entry !== void 0) {
       if (entry.phase === "done") {
-        return [state, [{ type: "intake:replay", key, result: entry.result }]];
+        return [state, [intakeReplay({ key, result: entry.result })]];
       }
       return [state, []];
     }
@@ -40,10 +57,7 @@ function createIntake(config) {
       id
     );
     const nextState = { seen: seenNext, queue: queueNext };
-    return [
-      nextState,
-      [{ type: "intake:process", key, itemId: item.id, payload }]
-    ];
+    return [nextState, [intakeProcess({ key, itemId: item.id, payload })]];
   }
   function complete(state, key, result, at) {
     const seenNext = memory.remember(
@@ -86,6 +100,6 @@ function createIntake(config) {
   return { init, receive, complete, boot, claimNext };
 }
 
-export { createIntake };
-//# sourceMappingURL=chunk-ZVJZ72HY.js.map
-//# sourceMappingURL=chunk-ZVJZ72HY.js.map
+export { createIntake, intakeProcessDef, intakeReplayDef };
+//# sourceMappingURL=chunk-LYLTKJWM.js.map
+//# sourceMappingURL=chunk-LYLTKJWM.js.map

package/dist/chunk-LYLTKJWM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/idempotency/idempotent-intake/index.ts"],"names":[],"mappings":"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","file":"chunk-LYLTKJWM.js","sourcesContent":["/**\n * internal/idempotency/idempotent-intake — receive-once intake for webhooks / queue\n * messages: dedupe by key, enqueue the new ones, replay the cached result to\n * the duplicates. The \"process this payload exactly once even though it\n * arrives N times\" knob.\n *\n * **The recipe.** This is a Level-2 composition — it owns no primitive\n * queue/cache logic of its own, it *splices two L1 bricks into one Model slice*\n * and DELEGATES every transition to their VERB SEAMS — `IdempotencyMemory`\n * (`../idempotency/adapter`) and `QueueAdapter` (`../work-queue/adapter`) —\n * so the store ops and the `QueueItem` / `IdempotencyStore` shapes stay\n * insulated behind verbs the intake calls:\n *\n *   - `../idempotency/adapter` — the dedupe-by-key + last-result cache. The\n *     `seen` half of the slice is its `IdempotencyStore`, keyed by\n *     `keyOf(payload)`. A key is recorded once `receive` calls `memory.remember`;\n *     `complete` calls `memory.remember` again to swap its cached value from\n *     `pending` to the finished `result`. The cache write is the brick's, never\n *     re-rolled here.\n *   - `../work-queue/adapter` — the pending-work list. The `queue` half of the\n *     slice is its `QueueItem<P>[]`. Every status flip routes through the\n *     adapter verbs: `receive` enqueues via `queue.enqueue`, `claimNext` stamps\n *     the `running` claim via `queue.patch`, `boot` re-arms a dead worker's\n *     claim via `queue.patch`. Intake owns only the SELECTION (which item,\n *     gated on the done-cache reconcile below) — the array transition is the\n *     brick's. The consumer drains it (claim → process → `complete`) at its own\n *     pace.\n *\n * Both bricks are pure-state + pure-ops, host- and clock-agnostic by\n * construction, so the combined slice inherits TEA's two non-negotiables:\n *\n *   - **Durable** — the slice is a plain serializable value (a record-backed\n *     idempotency store + an array of queue items, no `Map`, no closures), so\n *     it survives a Durable-Object eviction / reload and rehydrates whole.\n *   - **Replayable** — every verb is a pure `(state, …) => [state, Cmd[]]`\n *     transition; no `Date.now()`, no `Math.random()`, no I/O inside a verb.\n *     `at` (the clock) and `id` (the queue-item id) are *injected* at the call\n *     site, so `trace-replay` reconstructs each transition exactly.\n *\n * **The decision lives in a Cmd, not in a return shape.** `receive` cannot\n * \"return\" what it decided (the knob contract pins the shape to\n * `[State, Cmd[]]`), so the decision is *reified as a Cmd* the runtime\n * performs:\n *\n *   - first sighting of a key  → mark it `pending`, enqueue the payload, emit\n *     `IntakeProcess` (go run the work).\n *   - a key already `pending`  → drop silently (the original is in flight);\n *     emit nothing.\n *   - a key already `done`     → emit `IntakeReplay` carrying the cached\n *     result so the duplicate caller gets the SAME response the first one\n *     produced, with zero re-execution of the side effect.\n *\n * **Two crash-safety guarantees the verbs enforce (and the unit specs alone\n * missed — see the wired-machine test):**\n *\n *   - *A slow worker is never double-enqueued.* The TTL clock starts at\n *     `complete`, not at `receive`: a `pending` entry NEVER ages out, so a\n *     duplicate of an in-flight key is always dropped no matter how long the\n *     worker takes. Only a `done` entry expires (see `liveEntry`).\n *   - *A complete-then-crash never re-runs.* `boot` and `claimNext` reconcile\n *     the queue against the done cache: a queue item whose key already resolved\n *     to `done` in `seen` is skipped (never reset to pending, never claimed),\n *     so a worker that finished and cached its result before the DO evicted is\n *     not re-executed on resume.\n *\n * Typical wiring (the combinator form — splice ~3 hooks into a host machine):\n *\n *   const intake = createIntake<StripeEvent, ChargeResult>({\n *     keyOf: (e) => e.id,          // Stripe's idempotency key\n *     ttlMs: 24 * 60 * 60 * 1000,  // a replayed webhook 24h after it COMPLETED is re-run\n *   });\n *\n *   // in `init`:\n *   intake: intake.init(),\n *   // in `update`, on the inbound-webhook Msg:\n *   const [next, cmds] = intake.receive(state.intake, payload, at, id);\n *   // …route `IntakeProcess` to your worker, `IntakeReplay` to the responder.\n *   // on the worker's done Msg:\n *   const [next, _] = intake.complete(state.intake, key, result, at);\n *   // once, after boot (DO reload), before resuming the drain:\n *   const [next, _] = intake.boot(state.intake);\n *\n * Escape hatch: reach the raw L1 ops via `../idempotency` and `../../work-queue`\n * and thread them by hand.\n */\n\nimport { z } from \"zod\";\nimport { Cmd, type CmdOf } from \"../../../index\";\nimport type { QueueItem } from \"../../work-queue\";\nimport { queueAdapter } from \"../../work-queue/adapter\";\nimport type { IdempotencyStore } from \"../idempotency\";\nimport { idempotencyMemory } from \"../idempotency/adapter\";\n\n/**\n * A cached intake entry: either a key whose work is still in flight\n * (`pending`) or one whose work has finished and whose `result` is held for\n * replay to later duplicates (`done`). Discriminated on `phase` — `pending`\n * carries no payload, `done` carries the result `R`.\n *\n * Lives inside the `seen` half of the slice (`IdempotencyStore<IntakeEntry<R>>`).\n * It is the dedupe ledger's *value*; the ledger's *key* is `keyOf(payload)`.\n */\nexport type IntakeEntry<R> =\n  | { readonly phase: \"pending\" }\n  | { readonly phase: \"done\"; readonly result: R };\n\n/**\n * The intake knob's config — `keyOf` derives the idempotency key from a\n * payload, `ttlMs` (optional) ages a *completed* cached key out so a webhook\n * replayed long after the work finished is treated as new and re-processed.\n *\n * **The TTL clock starts at `complete`, not at `receive`.** A `pending` entry\n * (work still in flight) NEVER ages out, no matter how slow the worker is —\n * ageing a pending key would let the duplicate re-enqueue the in-flight\n * payload and double-process it. Only a `done` entry expires, measured from\n * the `at` passed to `complete` (the moment the result was cached). Inside the\n * window a duplicate replays the cached result; at/after the window it is\n * re-accepted and re-processed.\n *\n * Omit `ttlMs` for a cache whose `done` entries never expire by age (keys live\n * forever — fine for a bounded universe of ids, unbounded growth otherwise).\n *\n * The TTL is owned HERE, not delegated to the composed `IdempotencyStore`: the\n * store's uniform per-entry TTL cannot tell `pending` from `done`, so intake\n * keeps the store TTL-free and applies the phase-aware rule itself (see\n * `liveEntry`).\n */\nexport interface IntakeConfig<P> {\n  /** Derive the idempotency key from a payload. Must be pure + deterministic. */\n  readonly keyOf: (payload: P) => string;\n  /**\n   * Age a *completed* key out after this many ms, measured from the `at`\n   * passed to `complete`. Pending keys never age out.\n   */\n  readonly ttlMs?: number;\n}\n\n/**\n * The Model slice this knob owns. `seen` is the dedupe + last-result cache\n * (the `../idempotency` brick); `queue` is the pending-work list (the\n * `../work-queue` brick). Both are plain serializable values — the whole slice\n * round-trips through `JSON` so it survives eviction and replays exactly.\n */\nexport interface IntakeState<P, R> {\n  readonly seen: IdempotencyStore<IntakeEntry<R>>;\n  readonly queue: readonly QueueItem<P>[];\n}\n\n// === Cmds the verbs reify ===\n//\n// The knob contract pins verbs to `(state, …) => [State, Cmd[]]`, so a verb's\n// *decision* (new vs. duplicate-pending vs. duplicate-done) cannot be a return\n// value — it is emitted as a Cmd the runtime's interpret handler performs.\n// Each Cmd is plain data (invariant 1): the payload / key / result it carries\n// are values, never closures.\n//\n// Both are `Cmd.define`d (ADR 0014). The payload `P` / result `R` are the\n// knob's own type parameters, so each def is minted per knob by a factory\n// (`createIntake` calls it once) rather than a module-scope constant — the\n// same shape `resilient-call`'s `runCmdDef<I, R>()` takes. The host performs\n// them and settles nothing back through intake, hence `ok: z.void()` and an\n// empty `err` list.\n\n/** A genuinely-new payload was accepted and enqueued — go run the work. */\nexport function intakeProcessDef<P>() {\n  return Cmd.define(\"intake:process\", {\n    input: z.custom<{\n      /** The dedupe key the payload was filed under. */\n      readonly key: string;\n      /** The enqueued queue-item id (the same `id` passed to `receive`). */\n      readonly itemId: string;\n      /** The original payload, for the worker to process. */\n      readonly payload: P;\n    }>(),\n    ok: z.void(),\n    err: [],\n  });\n}\nexport type IntakeProcessCmd<P> = CmdOf<ReturnType<typeof intakeProcessDef<P>>>;\n\n/**\n * A duplicate of an already-completed key arrived — replay the cached result\n * to the caller instead of re-running the side effect.\n */\nexport function intakeReplayDef<R>() {\n  return Cmd.define(\"intake:replay\", {\n    input: z.custom<{\n      /** The dedupe key whose cached result is being replayed. */\n      readonly key: string;\n      /** The result the ORIGINAL request produced, recalled from the cache. */\n      readonly result: R;\n    }>(),\n    ok: z.void(),\n    err: [],\n  });\n}\nexport type IntakeReplayCmd<R> = CmdOf<ReturnType<typeof intakeReplayDef<R>>>;\n\n/** The Cmd union the intake verbs emit. */\nexport type IntakeCmd<P, R> = IntakeProcessCmd<P> | IntakeReplayCmd<R>;\n\n/**\n * Build an idempotent-intake knob from `config`. Returns the uniform L2\n * contract — `init()` + the verbs (`receive`, `complete`, `boot`, `claimNext`).\n * No `subs` / `handlers`: intake owns no timers and does no I/O of its own (the\n * composed bricks are pure-ops; the worker that runs `IntakeProcess` and the\n * responder that runs `IntakeReplay` live in the host's interpret map).\n */\nexport function createIntake<P, R>(config: IntakeConfig<P>) {\n  const { keyOf, ttlMs } = config;\n\n  // The two store seams, bound once for this knob's `P`/`R`. The intake\n  // delegates every queue status flip to `queue.*` and every dedupe-cache\n  // transition to `memory.*`, so the `QueueItem<P>` / `IdempotencyStore` shapes\n  // are insulated behind the verbs rather than reached by raw ops.\n  const queue = queueAdapter<P>();\n  const memory = idempotencyMemory<IntakeEntry<R>>();\n\n  // The two Cmd constructors, minted once for this knob's `P`/`R`.\n  const intakeProcess = intakeProcessDef<P>();\n  const intakeReplay = intakeReplayDef<R>();\n\n  /**\n   * The empty slice: a TTL-free idempotency store (intake owns the TTL itself —\n   * see `liveEntry`, because the store cannot tell `pending` from `done`) plus\n   * an empty work queue. The rehydrate path is the host's `init(loaded)` — it\n   * passes the persisted slice straight back, this is only the fresh-boot value.\n   */\n  function init(): IntakeState<P, R> {\n    return {\n      seen: memory.init(),\n      queue: [],\n    };\n  }\n\n  /**\n   * The live cached entry for `key` at clock reading `at`, or `undefined` if\n   * the key is absent or its `done` window has elapsed. This is intake's\n   * phase-aware expiry rule, applied HERE rather than by the store's uniform\n   * per-entry TTL:\n   *\n   *   - **`pending`** — work is in flight; NEVER expires. Ageing a pending key\n   *     would let a slow worker's payload be re-enqueued and double-processed.\n   *   - **`done`** — expires `ttlMs` after the `atMs` the result was cached at\n   *     (the `at` passed to `complete`). Half-open, matching the store /\n   *     rate-limit window edge: `at - atMs >= ttlMs` reads as expired. No\n   *     `ttlMs` ⇒ a `done` entry never expires by age.\n   *\n   * PURE — reads `state.seen.entries` directly (no `Date.now`), never mutates.\n   */\n  function liveEntry(\n    store: IdempotencyStore<IntakeEntry<R>>,\n    key: string,\n    at: number,\n  ): IntakeEntry<R> | undefined {\n    const cached = store.entries[key];\n    if (cached === undefined) return undefined;\n    const entry = cached.value;\n    if (entry.phase === \"pending\") return entry; // in flight — never ages out\n    if (ttlMs !== undefined && at - cached.atMs >= ttlMs) return undefined;\n    return entry;\n  }\n\n  /**\n   * Whether the queue item `it`'s key has already resolved to a live `done`\n   * entry in `seen` (the work completed and its result is cached). Such an\n   * item must NOT be re-armed by `boot` or claimed by `claimNext` — doing so\n   * re-runs work whose result is already known (the complete-then-crash bug).\n   *\n   * `at = +Infinity` is the right reading for the reconcile check: a `done`\n   * entry counts as done for reconciliation regardless of how far past its\n   * replay TTL it is. (TTL governs whether a *duplicate receive* re-processes,\n   * not whether a *queued, already-completed* item should re-run — that one\n   * never should.)\n   */\n  function isAlreadyDone(state: IntakeState<P, R>, it: QueueItem<P>): boolean {\n    return state.seen.entries[keyOf(it.input)]?.value.phase === \"done\";\n  }\n\n  /**\n   * Receive a payload at clock reading `at`, filing it under the queue-item\n   * id `id`. PURE — returns a NEW slice; the input is untouched.\n   *\n   * Three outcomes, each reified as a Cmd (see the Cmd union above):\n   *\n   *   1. **New key** (`liveEntry` is absent at `at`) — `remember` the key as\n   *      `pending`, `enqueue` the payload onto the work queue, and emit\n   *      `intake:process`. The only path that grows either half of the slice.\n   *   2. **Duplicate, still pending** — the original is in flight. Drop\n   *      silently: the slice is returned unchanged and no Cmd is emitted, so\n   *      the duplicate neither re-enqueues nor double-processes. A pending\n   *      entry never ages out, so this holds no matter how slow the worker is.\n   *   3. **Duplicate, already done (within TTL)** — emit `intake:replay`\n   *      carrying the cached `result` so the caller gets the original response.\n   *      The slice is unchanged (a replay touches neither cache nor queue). A\n   *      `done` key past its `ttlMs` window reads as absent and falls to (1).\n   *\n   * `id` is injected (work-queue's `genId` reads `Date.now()` / `crypto`, so\n   * it cannot be called inside a pure verb). Generate it at the effect\n   * boundary and thread it in; it becomes the enqueued item's id AND the\n   * `itemId` on the emitted `intake:process` Cmd, so the worker can address the\n   * exact queue item it must `complete`.\n   */\n  function receive(\n    state: IntakeState<P, R>,\n    payload: P,\n    at: number,\n    id: string,\n  ): readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]] {\n    const key = keyOf(payload);\n\n    // Duplicate path — the key has a live entry at `at` (pending never ages;\n    // done ages only past `ttlMs` measured from `complete`).\n    const entry = liveEntry(state.seen, key, at);\n    if (entry !== undefined) {\n      if (entry.phase === \"done\") {\n        // Replay the original result; touch nothing.\n        return [state, [intakeReplay({ key, result: entry.result })]];\n      }\n      // phase === \"pending\": original is in flight — drop silently.\n      return [state, []];\n    }\n\n    // New path — record the key as pending, enqueue the payload, process it.\n    const seenNext = memory.remember(state.seen, key, { phase: \"pending\" }, at);\n    const { next: queueNext, item } = queue.enqueue(\n      state.queue,\n      payload,\n      at,\n      id,\n    );\n    const nextState: IntakeState<P, R> = { seen: seenNext, queue: queueNext };\n    return [nextState, [intakeProcess({ key, itemId: item.id, payload })]];\n  }\n\n  /**\n   * Record the finished `result` for `key` at clock reading `at`. PURE —\n   * returns a NEW slice; the input is untouched. Emits no Cmds (completion is\n   * a pure cache write; the host marks the queue item done via the work-queue\n   * adapter at the effect boundary).\n   *\n   * Swaps the key's cached entry from `pending` to `done` so every subsequent\n   * `receive` of the same key replays this `result`. `remember` stamps the\n   * entry's `atMs` to `at`, which is the moment intake's `done`-TTL clock\n   * starts (see `liveEntry`): a completed key stays replayable for `ttlMs`\n   * past completion, not past first receipt.\n   *\n   * `complete` does NOT remove the queue item — the queue is the host's drain\n   * ledger, and which items leave it (and when) is the host's call via the\n   * work-queue adapter. `complete` owns the cache half only.\n   */\n  function complete(\n    state: IntakeState<P, R>,\n    key: string,\n    result: R,\n    at: number,\n  ): readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]] {\n    const seenNext = memory.remember(\n      state.seen,\n      key,\n      { phase: \"done\", result },\n      at,\n    );\n    return [{ ...state, seen: seenNext }, []];\n  }\n\n  /**\n   * Resume after a boot (Durable-Object reload / process restart). PURE —\n   * returns a NEW slice; the input is untouched. Emits no Cmds.\n   *\n   * Resets every `running` queue item back to `pending` so the host's drain\n   * re-claims it — EXCEPT an item whose key already resolved to `done` in\n   * `seen`. That item's worker finished and cached its result before the crash;\n   * re-arming it would re-run completed work (the complete-then-crash bug). It\n   * is left as-is (and `claimNext` will likewise skip it), so the host drains\n   * it via `markDone` without ever re-executing the side effect.\n   *\n   * A `running` item still `pending` in the cache is one a now-dead worker\n   * claimed but never finished — that one IS reset, so it gets re-claimed.\n   *\n   * Returns the same reference when nothing changed (no running item needed\n   * re-arming) so the host can skip a redundant save.\n   *\n   * Call once from a `boot` Msg the host dispatches after `run(...)` returns —\n   * never from `init`'s rehydrate branch (that branch must be a pure\n   * passthrough; see the substrate's `init` contract).\n   */\n  function boot(\n    state: IntakeState<P, R>,\n  ): readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]] {\n    // Selection lives HERE (the done-cache reconcile is intake's own rule); the\n    // status FLIP is delegated to the `QueueAdapter`. A blanket reset would\n    // re-arm completed-then-crashed items (it cannot see the done cache), so\n    // intake picks the items and `queue.patch` performs each transition — the\n    // same spread the work-queue lifecycle uses, not a re-rolled one.\n    let items = state.queue;\n    let changed = false;\n    for (const it of state.queue) {\n      if (it.status !== \"running\") continue;\n      // Reconcile against the done cache: a completed-then-crashed item must\n      // NOT be re-armed (it would re-run already-cached work).\n      if (isAlreadyDone(state, it)) continue;\n      const flip = queue.patch(items, it.id, (item) => ({\n        ...item,\n        status: \"pending\",\n        startedAt: undefined,\n      }));\n      items = flip.next;\n      changed = changed || flip.changed;\n    }\n    if (!changed) return [state, []];\n    return [{ ...state, queue: items }, []];\n  }\n\n  /**\n   * Claim the next pending queue item, flipping it `running` and stamping\n   * `startedAt` to `at`. PURE — returns a NEW slice plus the claimed item, or\n   * `null` if nothing claimable remains.\n   *\n   * \"Claimable\" is a pending item WHOSE KEY IS NOT ALREADY `done` in `seen`.\n   * An item whose key completed before a crash (its `intake:process` ran, work\n   * finished, result cached, but the item never left the queue) is skipped —\n   * claiming it would re-run already-cached work. Such items are inert here;\n   * the host drains them via `markDone`.\n   *\n   * This is the drain side of the intake, the mirror of `receive`'s enqueue.\n   * It is a pure helper (not a verb that emits Cmds) because \"what to do with\n   * the claimed item\" is the host's decision — typically: dispatch the worker,\n   * await it, then call `complete`. Threading it through the slice keeps the\n   * claim durable: the `running` stamp survives eviction, and `boot` re-arms\n   * it if the worker died.\n   */\n  function claimNext(\n    state: IntakeState<P, R>,\n    at: number,\n  ): {\n    readonly state: IntakeState<P, R>;\n    readonly claimed: QueueItem<P>;\n  } | null {\n    // Selection lives HERE (skip an item whose key already resolved `done`);\n    // the status FLIP is delegated to the `QueueAdapter`. A blind `queue.claim`\n    // would take the first PENDING item regardless of the done cache, which\n    // would re-run already-cached work — so intake selects the eligible item and\n    // `queue.patch` performs the running-stamp transition (the work-queue\n    // lifecycle's own spread, not a re-rolled one).\n    const target = state.queue.find(\n      (it) => it.status === \"pending\" && !isAlreadyDone(state, it),\n    );\n    if (target === undefined) return null;\n    // The patch closure is the single place the claimed item is materialized;\n    // capture it here so the result needs no re-scan of the new queue.\n    let claimed: QueueItem<P> = target;\n    const { next } = queue.patch(state.queue, target.id, (item) => {\n      claimed = { ...item, status: \"running\", startedAt: at };\n      return claimed;\n    });\n    return { state: { ...state, queue: next }, claimed };\n  }\n\n  return { init, receive, complete, boot, claimNext };\n}\n"]}

package/dist/{chunk-D736QUGF.js → chunk-MYXFNWAJ.js}

@@ -1,7 +1,6 @@
-import { queueAdapter } from './chunk-MU6MCIAC.js';
-import { at } from './chunk-FV3Z5MBE.js';
+import { queueAdapter, at } from './chunk-TXN2KFHF.js';
 
-// src/fan-out/index.ts
+// src/internal/flow/fan-out/index.ts
 function launchBudget(concurrency) {
   return concurrency < 1 ? 1 : Math.floor(concurrency);
 }
@@ -144,5 +143,5 @@ function createFanOut(config) {
 }
 
 export { createFanOut, initFanOut, isComplete };
-//# sourceMappingURL=chunk-D736QUGF.js.map
-//# sourceMappingURL=chunk-D736QUGF.js.map
+//# sourceMappingURL=chunk-MYXFNWAJ.js.map
+//# sourceMappingURL=chunk-MYXFNWAJ.js.map

package/dist/chunk-MYXFNWAJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/flow/fan-out/index.ts"],"names":[],"mappings":"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","file":"chunk-MYXFNWAJ.js","sourcesContent":["/**\n * internal/flow/fan-out — scatter-gather over a bounded-concurrency work list.\n *\n * The Level-2 combinator that fans a batch of items out across at most\n * `concurrency` in-flight effects, gathers each item's result (or error), and\n * — once every item has settled — fires an optional `join` over the collected\n * results. It is the \"map a list through an effect, but never run more than N\n * at once\" knob.\n *\n * The recipe (which bricks it composes):\n *   - `../work-queue` — fan-out's tracked items ARE work-queue items. Each\n *     item carries the same `{ id, status, input }` lifecycle vocabulary\n *     (`pending → running → done | failed`). The slice this knob owns is four\n *     partitions over that one lifecycle, so the work-queue's status taxonomy\n *     is the substrate rather than a parallel invention. We reuse its\n *     `QueueItem<I>` / `QueueItemStatus` TYPES and delegate the ledger\n *     transitions to the `QueueAdapter` verbs (`../work-queue/adapter`):\n *     `scatter` mints each pending record with `queue.enqueue`, and `launchUpTo`\n *     flips `pending → running` with `queue.claim` (one positional claim per\n *     launch). The lone exception is `settleOne`'s `running → done|failed`\n *     flip — it must match \"first id-match that is still `running`\" to settle\n *     exactly one of a DUPLICATE id, a status predicate the adapter verbs can't\n *     express, so fan-out owns that one index (see `settleOne`). The async\n *     `createQueue(store)` adapter is NOT used here because its `load → mutate\n *     → save` reads the clock and lives at an I/O boundary, while a combinator's\n *     verbs must be pure (invariant 2) — fan-out binds the pure `QueueAdapter`\n *     to its in-Model ledger instead, the same route `monitored-run` /\n *     `idempotent-intake` / `saga` take. The slice lives in the Model instead —\n *     durable + replayable, the two non-negotiables every knob preserves.\n *\n * Typical wiring (combinator form — splice the hooks into your machine):\n *\n *   const fan = createFanOut<Url, Report>({\n *     concurrency: 4,\n *     idOf: (url) => url,                                 // stable, pure identity\n *     of: (url) => ({ type: \"crawl\", url }),              // the per-item effect, as data\n *     join: (results) => ({ type: \"report_done\", results }),\n *   });\n *\n *   // in `update`:\n *   start_crawl:  (s, m) => { const [fanOut, cmds] = fan.scatter(s.fanOut, m.urls);\n *                             return [{ ...s, fanOut }, cmds]; },\n *   crawl_ok:     (s, m) => { const [fanOut, cmds] = fan.itemOk(s.fanOut, m.id, m.report);\n *                             return [{ ...s, fanOut }, cmds]; },\n *   crawl_err:    (s, m) => { const [fanOut, cmds] = fan.itemErr(s.fanOut, m.id, m.error);\n *                             return [{ ...s, fanOut }, cmds]; },\n *\n * Every verb is PURE: it returns a NEW slice plus the Cmds to perform (the\n * `of(item)` effects for newly-launched items, and at most one `join` Cmd when\n * the batch completes). The reducer never reads a clock or RNG — item identity\n * is supplied by the caller's `idOf` so `scatter` is deterministic, and the\n * launch effects are plain data the runtime performs (invariant 3).\n *\n * `handlers(ports)` is the I/O splice: it wires the runtime side that actually\n * runs each launched `of(item)` Cmd. Because `of` already produces a fully\n * caller-defined Cmd, fan-out does NOT own the interpret handler for it — the\n * consumer's own `interpret` performs the effect and routes Ok/Err back to the\n * `itemOk` / `itemErr` verbs (the same shape resilient-fetch uses with\n * `tryInterpret`). `handlers` therefore exposes the one piece fan-out CAN\n * pre-wire generically: emitting the gathered batch onto a typed Port when the\n * batch completes, for consumers that observe completion out-of-band rather\n * than through the `join` Cmd.\n *\n * NOT a substrate primitive: it depends only on `../work-queue`'s pure types +\n * blessed ops and the core `Cmd` / `Port` types. Internal since #48 — not\n * published on any subpath; reached from inside the package as\n * `internal/flow/fan-out`.\n */\n\nimport { at } from \"../../../at\";\nimport type { Cmd, Port } from \"../../../index\";\nimport type { QueueItem, QueueItemStatus } from \"../../work-queue\";\nimport { queueAdapter } from \"../../work-queue/adapter\";\n\n/**\n * One settled-OK item: the original `input` and the `result` its effect\n * produced. Mirrors the spec slice's `done: {item, result}[]` — `item` is the\n * caller's input value (not the internal `QueueItem` envelope), so a consumer\n * reading `done` gets back exactly what it scattered.\n */\nexport interface FanOutDone<I, R> {\n  /** The original scattered input value. */\n  readonly item: I;\n  /** The result the item's effect produced, routed in via `itemOk`. */\n  readonly result: R;\n}\n\n/**\n * One settled-error item: the original `input` and the `error` its effect\n * surfaced. `error` is `unknown` — fan-out carries it forward verbatim (an\n * `Error`, a tagged result, a string) for the consumer's reducer to read,\n * never interpreting it (same discipline as `retry-backoff`'s `lastError`).\n */\nexport interface FanOutFailed<I> {\n  /** The original scattered input value. */\n  readonly item: I;\n  /** The error the item's effect surfaced, routed in via `itemErr`. Carried, never interpreted. */\n  readonly error: unknown;\n}\n\n/**\n * The slice this knob owns — four partitions over the work-queue item\n * lifecycle, plus the work-queue records the verbs thread the lifecycle\n * through.\n *\n * Why both the spec's four arrays AND `items`:\n *   - The four arrays (`pending` / `running` / `done` / `failed`) are the\n *     SPEC's public read surface — what a consumer's view renders and what\n *     `isComplete` reads. They hold caller-facing values (`I`, or\n *     `FanOutDone` / `FanOutFailed`), not the internal id-bearing envelope.\n *   - `items` is the work-queue ledger: one `QueueItem<I>` per scattered item,\n *     carrying the stable `id` (from `config.idOf`) that `itemOk` / `itemErr`\n *     address and the `status` that decides launch-eligibility. It is the\n *     single source of truth; the four arrays are a derived projection kept in\n *     lockstep so consumers never re-scan `items` to render a partition.\n *\n * Every field is `readonly` and the whole slice is JSON-serializable (plain\n * arrays + the work-queue's plain `QueueItem` records), so it round-trips\n * through a consumer's `Store<S>` unchanged — durable across DO eviction.\n */\nexport interface FanOutState<I, R> {\n  /** Items accepted but not yet launched (queue back-pressure beyond `concurrency`). */\n  readonly pending: readonly I[];\n  /** Items whose `of(item)` effect is in flight (size never exceeds `concurrency`). */\n  readonly running: readonly I[];\n  /** Items whose effect resolved OK, with the result it produced. */\n  readonly done: readonly FanOutDone<I, R>[];\n  /** Items whose effect failed, with the error it surfaced. */\n  readonly failed: readonly FanOutFailed<I>[];\n  /**\n   * The work-queue ledger: one record per scattered item, keyed by the\n   * caller's `idOf`. The single source of truth the four arrays project from.\n   */\n  readonly items: readonly QueueItem<I>[];\n  /**\n   * Index into `done` where the CURRENT wave's OK results begin. `done` is\n   * append-only and accumulates across every wave (so a consumer reading\n   * `done` sees the full history), but `join` must fold only the wave that\n   * just drained — not the cumulative total. A wave opens when `scatter`\n   * enqueues into a slice with nothing in flight; this marks `done.length` at\n   * that moment so `join` receives exactly `done.slice(waveDoneFrom)`.\n   */\n  readonly waveDoneFrom: number;\n  /**\n   * Index into `failed` where the current wave's failures begin. Symmetric to\n   * `waveDoneFrom` — the wave boundary over the failure partition. Carried for\n   * a consumer that wants to read only the current wave's failures; `join`\n   * itself folds only OK results.\n   */\n  readonly waveFailedFrom: number;\n  /**\n   * Whether the current wave has already fired its `join`. `join` fires at most\n   * once per wave — set `true` at the completion edge so a stale settle that\n   * re-reaches `isComplete` cannot re-fire it. A new `scatter` that opens a wave\n   * resets it to `false`.\n   */\n  readonly joined: boolean;\n}\n\n/**\n * The knob. `concurrency` caps how many `of(item)` effects are in flight at\n * once; `idOf` mints a stable, PURE identity per item (so `scatter` is\n * deterministic and `itemOk` / `itemErr` can address an item by id); `of`\n * turns an item into the launch Cmd; `join` (optional) turns the gathered\n * results into a single completion Cmd fired exactly once when every item has\n * settled.\n *\n * Field optionality follows the resilient-call rule — omit `join`, omit the\n * completion Cmd (a consumer that observes `isComplete` itself, or wires the\n * `handlers` Port, doesn't need one).\n */\nexport interface FanOutConfig<I, R, C extends Cmd, J extends Cmd> {\n  /** Max in-flight `of(item)` effects. Clamped to `>= 1` (a 0/negative cap would deadlock). */\n  readonly concurrency: number;\n  /**\n   * Stable, deterministic identity for an item. PURE — no clock, no RNG. The\n   * id is what `itemOk` / `itemErr` address, so it must survive a round-trip\n   * through the durable slice and match across the launch → settle gap. For\n   * value-unique inputs (URLs, ids) this is often the identity function; for\n   * structural inputs, a content hash or a caller-assigned key.\n   */\n  readonly idOf: (item: I) => string;\n  /** The per-item effect, as data. Performed by the consumer's own `interpret`. */\n  readonly of: (item: I) => C;\n  /**\n   * Optional: fold the gathered done-results into a single completion Cmd,\n   * fired exactly once at the transition that empties `pending` + `running`.\n   * Omit to drive completion off `isComplete` (or the `handlers` Port) instead.\n   */\n  readonly join?: (results: readonly R[]) => J;\n}\n\n/**\n * Clamp the configured concurrency to a usable launch budget. A cap of 0 or\n * negative would launch nothing and the batch would deadlock with items stuck\n * `pending` forever; clamping to 1 degrades gracefully to fully-serial\n * fan-out (still correct, just no parallelism) rather than hanging.\n */\nfunction launchBudget(concurrency: number): number {\n  return concurrency < 1 ? 1 : Math.floor(concurrency);\n}\n\n/** The starting slice: nothing scattered yet. */\nexport function initFanOut<I, R>(): FanOutState<I, R> {\n  return {\n    pending: [],\n    running: [],\n    done: [],\n    failed: [],\n    items: [],\n    waveDoneFrom: 0,\n    waveFailedFrom: 0,\n    joined: false,\n  };\n}\n\n/**\n * Whether every scattered item has settled (no `pending`, no `running`).\n * Derived — reads the slice, never mutates. The verbs use it to decide when to\n * fire `join`; consumers can read it directly to branch their own phase.\n *\n * An empty fan-out (nothing ever scattered) is NOT complete: completion is \"a\n * non-empty batch fully drained,\" so `isComplete(initFanOut())` is `false` and\n * a `scatter([])` of zero items also reads `false` (there was no batch to\n * complete). This keeps `join` from firing on a degenerate empty scatter.\n */\nexport function isComplete<I, R>(state: FanOutState<I, R>): boolean {\n  if (state.items.length === 0) return false;\n  return state.pending.length === 0 && state.running.length === 0;\n}\n\n/**\n * Count of items currently in flight. `running.length`, named for the launch\n * arithmetic below (and readable at a call site).\n */\nfunction inFlight<I, R>(state: FanOutState<I, R>): number {\n  return state.running.length;\n}\n\n/**\n * Move up to `budget - inFlight` items from `pending` to `running`, emitting\n * `of(item)` for each launched item. PURE — returns the new slice and the\n * launch Cmds. The work-queue `items` ledger flips each launched item's status\n * `pending → running` via the `QueueAdapter`'s `claim`, in lockstep with the\n * projected arrays.\n *\n * Delegation, not re-rolling: each launch is one `queue.claim` call — the same\n * `pending → running` transition `src/internal/work-queue/` owns. `queue.claim`\n * flips the FIRST pending ledger record positionally, and fan-out's `pending`\n * array is appended in lockstep with the ledger, so the first `slots` pending\n * inputs map to the first `slots` pending records — claiming one-per-launch\n * settles exactly those. This also makes a DUPLICATE id correct: a positional\n * claim flips ONE record per launch, where a blanket id-set flip would promote\n * every pending record sharing the launched id (over-flipping the ledger past\n * `running.length`). The `at` stamp is `0` — fan-out's verbs are pure and never\n * read a clock; positional order, not the timestamp, drives every decision\n * (same convention as `scatter`'s `enqueuedAt: 0`).\n *\n * Shared by `scatter` (launch on enqueue) and `itemOk` / `itemErr` (launch the\n * next pending item as a slot frees). Factoring it here keeps the concurrency\n * invariant — `running.length <= budget` — in ONE place.\n */\nfunction launchUpTo<I, R, C extends Cmd>(\n  state: FanOutState<I, R>,\n  config: {\n    concurrency: number;\n    of: (item: I) => C;\n  },\n): readonly [FanOutState<I, R>, readonly C[]] {\n  const budget = launchBudget(config.concurrency);\n  const slots = budget - inFlight(state);\n  if (slots <= 0 || state.pending.length === 0) return [state, []];\n\n  const toLaunch = state.pending.slice(0, slots);\n  const stillPending = state.pending.slice(slots);\n\n  // Flip the ledger records `pending → running` one launch at a time via the\n  // `QueueAdapter` (positional first-pending claim per call).\n  const queue = queueAdapter<I>();\n  let items: readonly QueueItem<I>[] = state.items;\n  for (let i = 0; i < toLaunch.length; i++) {\n    const claimed = queue.claim(items, 0);\n    if (claimed === null) break;\n    items = claimed.next;\n  }\n\n  const next: FanOutState<I, R> = {\n    ...state,\n    pending: stillPending,\n    running: [...state.running, ...toLaunch],\n    items,\n  };\n  const cmds = toLaunch.map((item) => config.of(item));\n  return [next, cmds];\n}\n\n/**\n * Settle EXACTLY ONE running entry for `id`: remove the first `running` item\n * whose `idOf` matches, and flip the first ledger record for `id` that is still\n * `running` to `status`. Returns the input that was settled plus the new\n * `running` / `items` arrays, or `undefined` if no running item carries that id\n * (a stale / unknown settle Msg → caller treats as a no-op rather than a crash).\n *\n * Why \"exactly one\": when two scattered items share an `idOf` (a duplicate id),\n * the ledger holds two `running` records under the same id and `running` holds\n * two inputs. A settle Msg carries one result, so it must close out exactly one\n * of them — not all matches. A blanket `filter((x) => idOf(x) !== id)` would\n * drop BOTH running entries while recording only ONE result, silently losing a\n * unit of work and corrupting the done/failed partition. find-index + splice\n * removes a single `running` entry; the matching `findIndex` over the ledger\n * flips a single record. The OTHER duplicate stays `running`, awaiting its own\n * settle Msg.\n *\n * This flip is NOT delegated to the `QueueAdapter`'s `patch`: the verb matches\n * the FIRST record by id, but the record fan-out must flip is \"first id-match\n * that is still `running`\" — and after a dup-id's first settle the first id-match\n * is the already-terminal record. The status predicate is load-bearing here and\n * the adapter verbs can't express it, so fan-out owns this one index. The flipped\n * record is still built the work-queue way (spread + new `status`), and there\n * is no `as` cast: `status` arrives already typed `QueueItemStatus`.\n */\nfunction settleOne<I, R>(\n  state: FanOutState<I, R>,\n  id: string,\n  status: QueueItemStatus,\n  idOf: (item: I) => string,\n):\n  | { input: I; running: readonly I[]; items: readonly QueueItem<I>[] }\n  | undefined {\n  const runIdx = state.running.findIndex((item) => idOf(item) === id);\n  // `at` collapses \"no running entry for this id\" into an `undefined` early-out,\n  // narrowing `input` to `I` below without a non-null assertion (the pattern\n  // `ops.ts` uses); `runIdx` stays around for the splice.\n  const input = at(state.running, runIdx);\n  if (input === undefined) return undefined;\n\n  const running = [\n    ...state.running.slice(0, runIdx),\n    ...state.running.slice(runIdx + 1),\n  ];\n\n  const ledgerIdx = state.items.findIndex(\n    (item) => item.id === id && item.status === \"running\",\n  );\n  // Same early-out via `at`: `ledger === undefined` narrows the record to\n  // `QueueItem<I>` for the spread below without a non-null assertion.\n  const ledger = at(state.items, ledgerIdx);\n  const items =\n    ledger === undefined\n      ? state.items\n      : [\n          ...state.items.slice(0, ledgerIdx),\n          { ...ledger, status },\n          ...state.items.slice(ledgerIdx + 1),\n        ];\n\n  return { input, running, items };\n}\n\n/**\n * Optional Port for observing batch completion out-of-band. When a consumer\n * passes `handlers(ports)` a `complete` Port, the runtime side can emit the\n * gathered results onto it the moment `isComplete` flips true — distinct from\n * the in-band `join` Cmd (which threads back through `update`). Use the Port\n * for \"tell the outside world the batch finished\" without folding a completion\n * signal into the consumer's Msg union.\n */\nexport interface FanOutPorts<R> {\n  /** Fires once with every gathered done-result when the batch completes. */\n  readonly complete: Port<readonly R[]>;\n}\n\n/**\n * Build the fan-out knob from `config`. Returns the uniform combinator\n * contract: `init` for the owned slice, the three settle verbs + the derived\n * `isComplete`, and `handlers` for the optional out-of-band completion Port.\n *\n * No `subs` — fan-out runs no timers (the spec pins \"Subs: none\"). The\n * per-item effect's lifetime is owned by the consumer's `interpret`, and\n * completion is a pure function of the settle Msgs, so there is nothing\n * continuous to subscribe to.\n */\nexport function createFanOut<I, R, C extends Cmd = Cmd, J extends Cmd = Cmd>(\n  config: FanOutConfig<I, R, C, J>,\n) {\n  /**\n   * Enqueue `items` and launch up to `concurrency` of them. PURE.\n   *\n   * Each item gets a ledger record (`status: \"pending\"`, its `idOf` id) and is\n   * appended to `pending`; `launchUpTo` then promotes as many as the free\n   * concurrency budget allows, emitting `of(item)` per launch. The returned\n   * Cmds are exactly the launch effects — `scatter` never fires `join` (a batch\n   * can't complete on the same transition it starts unless it launches zero\n   * effects, which `isComplete`'s empty-batch rule already declines to treat as\n   * completion).\n   *\n   * Each pending ledger record is minted by the `QueueAdapter`'s `enqueue` — the\n   * same `pending` append `src/internal/work-queue/` owns — rather than re-rolled\n   * inline, so the `status: \"pending\"` literal lives in exactly one place (no\n   * `as QueueItemStatus` cast here).\n   *\n   * `enqueuedAt` is stamped `0` rather than read from a clock: fan-out's verbs\n   * are pure, and fan-out does not use the timestamp for any decision (ordering\n   * is positional via the arrays). A consumer that needs real enqueue times\n   * threads them through its own Msg `at` and stores them alongside.\n   */\n  function scatter(\n    state: FanOutState<I, R>,\n    items: readonly I[],\n  ): readonly [FanOutState<I, R>, readonly C[]] {\n    // Append one pending ledger record per item via the `QueueAdapter`.\n    // `queue.enqueue` returns `status: \"pending\"` already typed — no cast — and\n    // the lifecycle's \"new work is pending\" rule stays in work-queue's hands.\n    const queue = queueAdapter<I>();\n    let ledger: readonly QueueItem<I>[] = state.items;\n    for (const input of items) {\n      ledger = queue.enqueue(ledger, input, 0, config.idOf(input)).next;\n    }\n    // A scatter OPENS A FRESH WAVE when nothing is in flight — either the very\n    // first scatter, or a re-scatter after the previous wave fully drained. The\n    // wave boundary advances to the current `done` / `failed` length so `join`\n    // folds only THIS wave's results, never the cumulative history, and\n    // `joined` resets so the new wave can fire its own `join` exactly once.\n    //\n    // A scatter that adds to a wave still in flight (pending or running\n    // non-empty — e.g. enqueuing more work mid-batch) does NOT open a wave:\n    // those items join the current wave and settle under its single `join`.\n    const opensWave = state.pending.length === 0 && state.running.length === 0;\n\n    const enqueued: FanOutState<I, R> = {\n      ...state,\n      pending: [...state.pending, ...items],\n      items: ledger,\n      ...(opensWave\n        ? {\n            waveDoneFrom: state.done.length,\n            waveFailedFrom: state.failed.length,\n            joined: false,\n          }\n        : {}),\n    };\n    return launchUpTo(enqueued, config);\n  }\n\n  /**\n   * Record `id`'s effect as succeeded with `result`, then launch the next\n   * pending item to backfill the freed slot. PURE.\n   *\n   * Moves the item out of `running` into `done` (carrying the original input +\n   * its result), flips its ledger record `running → done`, and runs\n   * `launchUpTo` to keep the pipeline full. If this transition empties both\n   * `pending` and `running` AND a `join` is configured, the returned Cmds also\n   * include the single `join(results)` Cmd — fired exactly once at the\n   * completion edge.\n   *\n   * A settle for an unknown / already-settled `id` is a no-op (returns the\n   * slice unchanged, no Cmds): the runtime's serial dispatch makes a true\n   * double-settle impossible, but a stale Msg after a boot/replay is real, and\n   * swallowing it is the safe direction (the result is already recorded).\n   */\n  function itemOk(\n    state: FanOutState<I, R>,\n    id: string,\n    result: R,\n  ): readonly [FanOutState<I, R>, readonly (C | J)[]] {\n    const settled = settleOne(state, id, \"done\", config.idOf);\n    if (settled === undefined) return [state, []];\n\n    const next: FanOutState<I, R> = {\n      ...state,\n      running: settled.running,\n      done: [...state.done, { item: settled.input, result }],\n      items: settled.items,\n    };\n    return finishOrLaunch(next);\n  }\n\n  /**\n   * Record `id`'s effect as failed with `error`, then launch the next pending\n   * item to backfill the freed slot. PURE.\n   *\n   * Symmetric to `itemOk`: moves the item out of `running` into `failed`\n   * (carrying the original input + the error), flips its ledger record\n   * `running → failed`, backfills via `launchUpTo`, and fires `join` at the\n   * completion edge if configured. A failed item still counts toward completion\n   * — the batch is \"done\" when every item has settled, success or failure;\n   * `join` receives only the OK results (failures are read off `failed`).\n   *\n   * Same unknown-`id` no-op contract as `itemOk`.\n   */\n  function itemErr(\n    state: FanOutState<I, R>,\n    id: string,\n    error: unknown,\n  ): readonly [FanOutState<I, R>, readonly (C | J)[]] {\n    const settled = settleOne(state, id, \"failed\", config.idOf);\n    if (settled === undefined) return [state, []];\n\n    const next: FanOutState<I, R> = {\n      ...state,\n      running: settled.running,\n      failed: [...state.failed, { item: settled.input, error }],\n      items: settled.items,\n    };\n    return finishOrLaunch(next);\n  }\n\n  /**\n   * Shared tail of `itemOk` / `itemErr`: backfill the freed slot, then — if the\n   * CURRENT wave is now complete, a `join` is configured, and this wave has not\n   * already joined — append the single completion Cmd and mark the wave joined.\n   *\n   * Two guards keep `join` firing exactly once per wave:\n   *   - `isComplete(next)` is the completion edge (the transition that drains\n   *     the last in-flight item; `launchUpTo` cannot re-fill from an empty\n   *     `pending`, so `running` stays empty and the edge is reached once).\n   *   - `!next.joined` makes it idempotent even if a stale settle re-reaches a\n   *     completed slice, and — critically — combined with the per-wave reset in\n   *     `scatter` it stops `join` re-firing across waves. Without the wave\n   *     boundary, `done` is append-only, so a SECOND wave draining would see\n   *     `isComplete` true and re-fold the WHOLE cumulative `done` (wave 1 +\n   *     wave 2). The fix folds only `done.slice(waveDoneFrom)` — exactly the\n   *     results this wave produced.\n   */\n  function finishOrLaunch(\n    settled: FanOutState<I, R>,\n  ): readonly [FanOutState<I, R>, readonly (C | J)[]] {\n    const [launched, launchCmds] = launchUpTo(settled, config);\n    if (config.join !== undefined && !launched.joined && isComplete(launched)) {\n      const results = launched.done\n        .slice(launched.waveDoneFrom)\n        .map((d) => d.result);\n      const next: FanOutState<I, R> = { ...launched, joined: true };\n      return [next, [...launchCmds, config.join(results)]];\n    }\n    return [launched, launchCmds];\n  }\n\n  /**\n   * The out-of-band completion splice. Returns an observer-shaped function the\n   * consumer calls after every settle: when the batch has just completed it\n   * emits the gathered results onto `ports.complete`. This is the Port-side\n   * analogue of the `join` Cmd — use it when completion should leave the\n   * runtime as a typed signal rather than re-enter `update`.\n   *\n   * Returns the emit-on-complete callback so the consumer wires it into its own\n   * runtime `observe` (e.g. `runtime.observe((_, s) => emit(s.fanOut))`); fan-out\n   * stays out of the dispatch loop, matching `historyTracker`'s discipline.\n   */\n  function handlers(ports: FanOutPorts<R>) {\n    return {\n      /**\n       * Emit the gathered done-results onto `ports.complete` iff `state` is a\n       * just-completed batch. Idempotency is the caller's concern (call it once\n       * per transition via `observe`); emitting to a Port with no subscribers\n       * is a no-op at the runtime, so an extra call is harmless.\n       */\n      emitOnComplete(\n        emit: <T>(port: Port<T>, value: T) => void,\n        state: FanOutState<I, R>,\n      ): void {\n        if (!isComplete(state)) return;\n        emit(\n          ports.complete,\n          state.done.slice(state.waveDoneFrom).map((d) => d.result),\n        );\n      },\n    };\n  }\n\n  return {\n    init: initFanOut<I, R>,\n    scatter,\n    itemOk,\n    itemErr,\n    isComplete,\n    handlers,\n  };\n}\n"]}

package/dist/{chunk-K575PT4S.js → chunk-PR6TB3BL.js}

@@ -1,4 +1,4 @@
-// src/idempotency/index.ts
+// src/internal/idempotency/idempotency/index.ts
 function initStore(opts) {
   return {
     entries: {},
@@ -53,6 +53,17 @@ function remember(store, key, value, nowMs) {
   return { ...store, entries: nextEntries, order: nextOrder };
 }
 
-export { evictExpired, initStore, recall, remember, seen };
-//# sourceMappingURL=chunk-K575PT4S.js.map
-//# sourceMappingURL=chunk-K575PT4S.js.map
+// src/internal/idempotency/idempotency/adapter.ts
+function idempotencyMemory() {
+  return {
+    init: (opts) => initStore(opts),
+    isSeen: (store, key, now) => seen(store, key, now),
+    recall: (store, key, now) => recall(store, key, now),
+    remember: (store, key, value, now) => remember(store, key, value, now),
+    evict: (store, now) => evictExpired(store, now)
+  };
+}
+
+export { evictExpired, idempotencyMemory, initStore, recall, remember, seen };
+//# sourceMappingURL=chunk-PR6TB3BL.js.map
+//# sourceMappingURL=chunk-PR6TB3BL.js.map

package/dist/chunk-PR6TB3BL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/idempotency/idempotency/index.ts","../src/internal/idempotency/idempotency/adapter.ts"],"names":[],"mappings":"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","file":"chunk-PR6TB3BL.js","sourcesContent":["/**\n * internal/idempotency/idempotency — dedupe-by-key + last-result cache as pure state + ops.\n *\n * Same shape as `../../work-queue`'s `ops.ts` and `../../resilience/rate-limit`:\n * a state type plus pure transition functions. Host-agnostic by construction —\n * no `Date.now()`, no timers, no I/O. The caller injects the clock (`nowMs`)\n * and wires the result into its own reducer / interpret. This keeps the store\n * inside TEA's invariant 2 (transitions are pure: same inputs → same outputs,\n * no `Date.now`) so a consumer can fold it through `update` and exercise it\n * with `replay` / the pbt fold without a fake clock.\n *\n * Every op returns a NEW store value and never mutates its input (invariant 1 —\n * state is a value, not a place). `seen` / `recall` are read-shaped predicates;\n * `remember` / `evictExpired` return a new store.\n *\n * The use case: a webhook receiver, a retried queue message, or a repeated user\n * action arrives carrying an idempotency key. `seen(store, key, now)` answers\n * \"did I already process this?\"; `recall(store, key, now)` returns the cached\n * result so the duplicate request gets the SAME response the original produced\n * rather than re-running the side effect. `remember(store, key, value, now)`\n * records the key + its result after the first run.\n *\n * Two eviction policies keep the store bounded, both injected at `initStore`:\n *\n *   - **`ttlMs`** — an entry expires `ttlMs` after the `atMs` it was remembered\n *     at. `seen` / `recall` treat an expired entry as absent; `evictExpired`\n *     (and every `remember`) physically drops it. Without a TTL, entries live\n *     until evicted by capacity. The cutoff is half-open: an entry exactly\n *     `ttlMs` old is expired (`age >= ttlMs` drops it), matching `rate-limit`'s\n *     window edge — a key remembered at `t` no longer counts at `t + ttlMs`.\n *   - **`capacity`** — at most `capacity` entries are retained. When a\n *     `remember` would push the count past `capacity` (after expiry eviction),\n *     the OLDEST entries by insertion `order` are dropped until the count fits.\n *     Without a capacity, the store grows unbounded (TTL alone bounds it).\n *\n * `order` is the insertion-order index that capacity eviction reads — the keys\n * oldest-first. It is the store's own LRU-by-insertion ledger, kept in lockstep\n * with `entries` so `entries` never needs to be sorted to find the oldest.\n *\n * **Overwrite semantics** (decided + pinned by tests): re-`remember`ing an\n * existing key is an UPDATE, not a no-op. It (1) overwrites `value`, (2)\n * refreshes `atMs` to the new `nowMs` — so the TTL clock restarts and a\n * frequently-seen key never expires — and (3) moves the key to the NEWEST\n * position in `order` — so capacity eviction treats a re-remembered key as\n * fresh, not as a stale candidate for eviction. This makes `remember` behave\n * like \"touch\": a key actively being re-seen is kept alive on both the TTL and\n * capacity axes.\n *\n * Internal since #47 — not published on any subpath; reached from inside the\n * package as `internal/idempotency/idempotency`. Same one-shape-per-package rule\n * as `work-queue`, `rate-limit`, and `do`.\n */\n\n/**\n * A cached entry: the result `value` the original request produced and the\n * clock reading `atMs` it was remembered at. `atMs` is the TTL anchor — expiry\n * is measured from here, and a re-`remember` refreshes it. Both fields are\n * plain data so the whole store is trivially JSON-serializable into a\n * consumer's `Store<S>`.\n */\nexport interface IdempotencyEntry<V> {\n  readonly value: V;\n  readonly atMs: number;\n}\n\n/**\n * The dedupe store: a map of `key → entry`, an insertion-`order` ledger\n * (oldest-first) that capacity eviction reads, and the two optional bounds.\n *\n * `entries` and `order` are kept in lockstep — every key in `order` has an\n * entry and vice versa. `capacity` / `ttlMs` are carried on the store (not\n * passed per-op) so a single value fully describes the policy; a consumer\n * persists the store and rehydrates the same bounds without re-deriving them.\n */\nexport interface IdempotencyStore<V> {\n  readonly entries: Readonly<Record<string, IdempotencyEntry<V>>>;\n  readonly order: readonly string[];\n  readonly capacity?: number;\n  readonly ttlMs?: number;\n}\n\n/**\n * Create an empty store. `capacity` and `ttlMs` are both optional — omit both\n * for an unbounded cache, supply either or both to bound by count, age, or\n * both. Stored on the returned value so every later op reads the policy off\n * the store rather than from a re-passed argument.\n */\nexport function initStore<V>(opts?: {\n  capacity?: number;\n  ttlMs?: number;\n}): IdempotencyStore<V> {\n  return {\n    entries: {},\n    order: [],\n    capacity: opts?.capacity,\n    ttlMs: opts?.ttlMs,\n  };\n}\n\n/**\n * Whether `entry` (remembered at `entry.atMs`) is expired at `nowMs` under\n * `ttlMs`. Half-open: an entry exactly `ttlMs` old is expired (`age >= ttlMs`),\n * matching `rate-limit`'s window-edge cutoff. A `nowMs` before `atMs` (clock\n * skewed backwards) yields a negative age — never expired, the safe direction\n * (a duplicate is still deduped rather than re-run). When `ttlMs` is undefined\n * the entry never expires by age.\n */\nfunction isExpired<V>(\n  entry: IdempotencyEntry<V>,\n  nowMs: number,\n  ttlMs: number | undefined,\n): boolean {\n  if (ttlMs === undefined) return false;\n  return nowMs - entry.atMs >= ttlMs;\n}\n\n/**\n * True iff `key` is present AND not expired at `nowMs`. This is the dedupe\n * predicate: a webhook / retried message / repeated action whose key returns\n * `true` has already been processed and should be short-circuited (paired with\n * `recall` to return the original result). PURE — reads only, never mutates.\n */\nexport function seen<V>(\n  store: IdempotencyStore<V>,\n  key: string,\n  nowMs: number,\n): boolean {\n  const entry = store.entries[key];\n  if (entry === undefined) return false;\n  return !isExpired(entry, nowMs, store.ttlMs);\n}\n\n/**\n * The cached `value` for `key` if present and unexpired at `nowMs`, else\n * `undefined`. Use after `seen` returns `true` to replay the original result to\n * a duplicate request. An expired entry reads as absent (returns `undefined`)\n * even though it is physically still in `entries` until the next `remember` /\n * `evictExpired` drops it. PURE — reads only, never mutates.\n */\nexport function recall<V>(\n  store: IdempotencyStore<V>,\n  key: string,\n  nowMs: number,\n): V | undefined {\n  const entry = store.entries[key];\n  if (entry === undefined || isExpired(entry, nowMs, store.ttlMs))\n    return undefined;\n  return entry.value;\n}\n\n/**\n * Drop every entry expired at `nowMs` (older than `ttlMs`). Returns a NEW store\n * with the survivors; `order` is rebuilt to drop the same keys, preserving the\n * relative insertion order of the survivors. A no-TTL store returns an\n * equivalent store (nothing ages out). PURE — the input store is never mutated.\n */\nexport function evictExpired<V>(\n  store: IdempotencyStore<V>,\n  nowMs: number,\n): IdempotencyStore<V> {\n  if (store.ttlMs === undefined) return store;\n  const nextEntries: Record<string, IdempotencyEntry<V>> = {};\n  const nextOrder: string[] = [];\n  // Walk `order` (not `Object.keys`) so the surviving order ledger keeps the\n  // exact relative insertion order capacity eviction depends on.\n  for (const key of store.order) {\n    const entry = store.entries[key];\n    if (entry === undefined) continue; // defensive: order/entries kept in lockstep\n    if (isExpired(entry, nowMs, store.ttlMs)) continue;\n    nextEntries[key] = entry;\n    nextOrder.push(key);\n  }\n  return { ...store, entries: nextEntries, order: nextOrder };\n}\n\n/**\n * Record `key → value` at `nowMs`, then enforce both bounds. PURE — returns a\n * new store; the input is untouched.\n *\n * Order of operations (each step matters):\n *   1. **Expiry eviction** — drop everything older than `ttlMs` first, so an\n *      expired key never occupies a capacity slot the new entry could take, and\n *      a stale entry under the same `key` is cleared before the overwrite.\n *   2. **Insert / overwrite** — write the new entry. If `key` already exists,\n *      this is an UPDATE: `value` is overwritten, `atMs` is refreshed to\n *      `nowMs` (restarting the TTL clock), and the key is moved to the NEWEST\n *      position in `order` (removed from wherever it sat, appended at the end).\n *      See the module-level \"Overwrite semantics\" note.\n *   3. **Capacity eviction** — if the entry count now exceeds `capacity`, drop\n *      the OLDEST keys by `order` until the count fits. Because step 2 moves a\n *      re-remembered key to the newest position, an actively re-seen key is\n *      never the eviction victim.\n */\nexport function remember<V>(\n  store: IdempotencyStore<V>,\n  key: string,\n  value: V,\n  nowMs: number,\n): IdempotencyStore<V> {\n  // Step 1 — expire first so stale entries free capacity slots before insert.\n  const pruned = evictExpired(store, nowMs);\n\n  // Step 2 — insert/overwrite. Drop any prior position of `key` from order,\n  // then append it as newest. `delete` on a fresh shallow copy keeps the input\n  // store untouched (invariant 1).\n  const nextEntries: Record<string, IdempotencyEntry<V>> = {\n    ...pruned.entries,\n  };\n  nextEntries[key] = { value, atMs: nowMs };\n  const nextOrder = pruned.order.filter((k) => k !== key);\n  nextOrder.push(key);\n\n  // Step 3 — capacity eviction. Drop oldest (front of `order`) until the count\n  // fits. `capacity <= 0` evicts everything just inserted down to the bound;\n  // `undefined` capacity skips eviction entirely.\n  if (store.capacity !== undefined) {\n    while (nextOrder.length > store.capacity) {\n      const oldest = nextOrder.shift();\n      if (oldest === undefined) break; // order emptied — nothing left to evict\n      delete nextEntries[oldest];\n    }\n  }\n\n  return { ...store, entries: nextEntries, order: nextOrder };\n}\n","/**\n * internal/idempotency/idempotency/adapter — the verb seam over the pure idempotency ops.\n *\n * The functions in `./index` (`seen` / `recall` / `remember` / `evictExpired`\n * / `initStore`) are the BLESSED transitions, but their names and the\n * `IdempotencyStore<V>` shape they read/return are the STORE's vocabulary. A\n * consumer that owns an `IdempotencyStore<V>` slice (`idempotent-intake`,\n * `poller`) used to import those functions by name and call them directly, so\n * a change to the op surface — or to `IdempotencyStore`'s fields — cascaded to\n * every call site.\n *\n * `IdempotencyMemory<V>` is the insulating interface: five VERBS (`isSeen` /\n * `recall` / `remember` / `evict` / `init`) consumers depend on instead of the\n * raw functions. The verbs keep the ops' pure contract — no I/O, no `Date.now`\n * (the clock is injected as `now`) — so a consumer folding the adapter through\n * its reducer stays inside invariant 2 (pure transitions). `isSeen` renames the\n * blessed `seen` predicate (a noun-y `seen` reads ambiguously as a slice field;\n * the verb form states the question it answers), and `evict` is the verb form\n * of `evictExpired`.\n *\n * `idempotencyMemory<V>()` is the canonical implementation, a thin binding of\n * the blessed ops. Because the verbs are the only surface consumers touch, an\n * `IdempotencyStore` shape change is absorbed HERE rather than at the consumer\n * call sites.\n *\n * INTERNAL seam (no public-API port): consumers import the adapter from this\n * subpath the same way they imported the ops. The ops remain exported from\n * `./index` for any call site that genuinely wants a function directly.\n */\n\nimport {\n  evictExpired,\n  type IdempotencyStore,\n  initStore,\n  recall,\n  remember,\n  seen,\n} from \"./index\";\n\n/**\n * The verb interface over an `IdempotencyStore<V>`. Each verb mirrors a blessed\n * op's pure contract but speaks the consumer's dedupe vocabulary, so the\n * consumer never names a store function or reaches into an `IdempotencyStore`\n * field it did not put there.\n */\nexport interface IdempotencyMemory<V> {\n  /** Create an empty store, optionally bounded by `capacity` and/or `ttlMs`. */\n  init(opts?: { capacity?: number; ttlMs?: number }): IdempotencyStore<V>;\n\n  /** True iff `key` is present AND not expired at `now`. Read-only. */\n  isSeen(store: IdempotencyStore<V>, key: string, now: number): boolean;\n\n  /** The cached value for `key` if present and unexpired at `now`. Read-only. */\n  recall(store: IdempotencyStore<V>, key: string, now: number): V | undefined;\n\n  /** Record `key → value` at `now`, enforcing the store's bounds. Returns a new store. */\n  remember(\n    store: IdempotencyStore<V>,\n    key: string,\n    value: V,\n    now: number,\n  ): IdempotencyStore<V>;\n\n  /** Drop every entry expired at `now`. Returns a new store. */\n  evict(store: IdempotencyStore<V>, now: number): IdempotencyStore<V>;\n}\n\n/**\n * The canonical `IdempotencyMemory<V>`, binding each verb to its blessed op.\n * Pure and stateless — call once at module scope in a consumer and fold its\n * verbs through the reducer. An `IdempotencyStore` shape change is absorbed by\n * re-binding a verb here, not at the consumers.\n */\nexport function idempotencyMemory<V>(): IdempotencyMemory<V> {\n  return {\n    init: (opts) => initStore<V>(opts),\n    isSeen: (store, key, now) => seen<V>(store, key, now),\n    recall: (store, key, now) => recall<V>(store, key, now),\n    remember: (store, key, value, now) => remember<V>(store, key, value, now),\n    evict: (store, now) => evictExpired<V>(store, now),\n  };\n}\n"]}