@demlik/tea 0.2.0 → 0.3.0

package/dist/chunk-FOGL3TC7.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/paginated-walk/index.ts"],"names":["start","drain","resume"],"mappings":"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","file":"chunk-FOGL3TC7.js","sourcesContent":["/**\n * @demlik/tea/paginated-walk — traverse a paginated API / sitemap end to end\n * WITHOUT a fake clock, without 429s, and resumable across a Durable-Object\n * eviction. The L2 composition that bolts `../resilient-call`'s resilience onto\n * `../paginator`'s cursor walk: each page is fetched as ONE keyed resilient\n * call (retry + backoff + rate-limit gate), and the cursor advances only once a\n * page settles `ok`.\n *\n * ## The recipe (the two siblings it composes)\n *\n *   - **`../paginator`** owns the walk loop: the opaque `Cursor`, the `seen` /\n *     `pages` counters, and the `idle → fetching → … → done` phase machine.\n *     `paginated-walk` never re-implements cursor advancement — it folds each\n *     settled page through `recordPage`, letting the paginator decide\n *     `done` / `fetching(next)` / `paused`. Backpressure is a TWO-way valve:\n *     `recordPage` parks the walk in `paused` once `seen >= highWaterMark`, and\n *     the `drain` / `resume` verbs (delegating to the paginator's own\n *     `drain` / `resume`) lower the gauge and re-open the parked fetch — without\n *     them `highWaterMark` would be a one-way valve that strands a paused walk.\n *   - **`../resilient-call`** owns the page fetch: the single `resilient_run`\n *     effect per page is gated through that knob's cache → circuit → rate-limit\n *     → retry pipeline. A transient page failure backs off and re-issues the\n *     SAME cursor (idempotent retry); the walk does not advance until the page\n *     genuinely settles.\n *\n * Those are the only two siblings this module calls into. The resilience knobs\n * (`retry` / `circuit` / `rateLimit` / `deadline`) are NOT separate bricks\n * `paginated-walk` composes — they belong to `resilient-call`, which owns the\n * rate-limit gate internally. This module merely passes them through to\n * `createResilientCall` and re-uses two config TYPES at the boundary:\n * `RateLimitConfig` (re-exported by `resilient-call`) and `RetryPolicy` (from\n * `../retry-backoff`). Pass a `rateLimit` and `resilient-call`'s token bucket\n * throttles page fetches (\"don't 429 the upstream\"); omit it and the walk runs\n * as fast as the upstream answers.\n *\n * Because the page-fetch resilience IS a `resilient-call` slice, this knob\n * **inherits that knob's contract verbatim**: the slice is a flat record, every\n * verb returns `readonly [State, Cmd[]]`, time is always an `at` parameter, and\n * the jitter RNG is injected once at `createPaginatedWalk(config, rng)` — never\n * read inside a verb (per the spec, `paginated-walk` *extends* `resilient-call`).\n *\n * ## The two non-negotiables (canon)\n *\n *   - **Durable** — the slice is plain data: the paginator phase + counters, and\n *     the resilient-call brick states (all JSON-serializable). The cursor lives\n *     in the Model, not a closure, so a walk survives eviction mid-traversal and\n *     resumes from the exact page it was fetching.\n *   - **Replayable** — every transition is a verb returning new state + Cmds.\n *     `nextCursor` / `onPage` are pure config functions applied at the verb\n *     boundary; the Cmds they yield are plain data. `replay` reconstructs the\n *     whole walk exactly.\n *\n * ## Where the clock / RNG live\n *\n * Inside the verbs: nowhere. `at` arrives on `start` / `pageOk` / `pageErr` /\n * `onTimer` and is threaded straight into the underlying resilient-call gate (so\n * a rate-limited or retried page measures backoff from that `at`). The jitter\n * RNG is injected at construction. The only clock read is `Date.now()` inside\n * the resilient-call `handlers` port (the effect boundary), inherited unchanged.\n *\n * ## The fixed fetch key\n *\n * A walk fetches one page at a time, so the resilient-call layer tracks exactly\n * one logical call under the constant key `PAGE_KEY`. The cursor being fetched\n * is the resilient call's `input`, so a post-eviction resume re-issues the same\n * page request. (`resilient-call` is keyed to support N concurrent calls; a walk\n * deliberately uses a single key — the paginator is the sequencer.)\n *\n * ## Typical wiring\n *\n *   const walk = createPaginatedWalk<PageToken, ApiPage>({\n *     firstPage: null,                          // the API's \"page one\" sentinel\n *     nextCursor: (page) => page.nextToken ?? null,\n *     onPage: (page) => [{ type: \"index_rows\", rows: page.items }],\n *     rateLimit: { capacity: 10, refillPerSec: 5 },\n *     retry: defaultRetryPolicy,\n *   });\n *\n *   // in the machine:\n *   init: () => [{ walk: walk.init() }, []],\n *   update: {\n *     start:    (s, m)  => lift(s, walk.start(s.walk, m.at)),\n *     page_ok:  (s, m)  => lift(s, walk.pageOk(s.walk, m.result, m.at)),\n *     page_err: (s, m)  => lift(s, walk.pageErr(s.walk, m.error, m.at)),\n *     retry_due:(s, m)  => lift(s, walk.onTimer(s.walk, m)),\n *     drained:  (s, m)  => lift(s, walk.drain(s.walk, m.n)),\n *     resume:   (s, m)  => lift(s, walk.resume(s.walk, m.at)),\n *   },\n *   subscriptions: (s) => walk.subs(s.walk),\n *   subscribe: { deadline: subscribeDeadline },\n *   interpret: walk.handlers({ run: (cursor) => api.fetchPage(cursor) }),\n */\n\nimport type { Cmd } from \"../index\";\nimport {\n  drain as drainWalk,\n  initPaginator,\n  isDone,\n  type PaginatorPolicy,\n  type PaginatorState,\n  recordPage,\n  resume as resumeWalk,\n  start as startWalk,\n} from \"../paginator\";\nimport { MsgType } from \"../protocol\";\nimport {\n  type CircuitConfig,\n  createResilientCall,\n  type DeadlineConfig,\n  type DeadlineSub,\n  deadlineSub,\n  type FailMsg,\n  type RateLimitConfig,\n  type ResilientPorts,\n  type ResilientState,\n  type ResilientTimerMsg,\n  type RunCmd,\n  type SucceedMsg,\n  subscribeDeadline,\n} from \"../resilient-call\";\nimport type { RetryPolicy } from \"../retry-backoff\";\n\n// ===========================================================================\n// Config — the knob. `firstPage` / `nextCursor` / `onPage` describe the walk;\n// the resilience bricks are inherited from resilient-call (every one optional —\n// omit a brick, omit its gate).\n// ===========================================================================\n\n/**\n * The paginated-walk knob. Generic in `Cursor` (the opaque page handle the\n * upstream API hands back — offset, page token, \"next\" URL, …) and `Page` (the\n * shape your fetch port resolves with).\n *\n * `nextCursor` and `onPage` are PURE config functions applied at the verb\n * boundary, never stored in the slice or in a Cmd (invariant 3 — Cmds are\n * plain data, not closures). `nextCursor(page)` extracts the API's next-page\n * handle (or `null` at the end); `onPage(page)` yields the Cmds the consumer\n * wants emitted for each successfully fetched page (index rows, write to R2,\n * dispatch a downstream Msg — whatever; an empty array is fine).\n *\n * The resilience bricks (`retry` / `circuit` / `rateLimit` / `deadline`) are\n * the SAME optional knobs `resilient-call` exposes — paginated-walk extends it.\n * `rateLimit` is the brick that keeps the walk from 429-ing the upstream.\n */\nexport interface PaginatedWalkConfig<Cursor, Page, EmittedCmd extends Cmd> {\n  /**\n   * The cursor the walk fetches first. For an offset API this is typically `0`;\n   * for a token API, whatever sentinel the API treats as \"page one\" (often\n   * `null` or `\"\"`). Threaded into `paginator`'s `firstCursor`.\n   */\n  readonly firstPage: Cursor;\n  /**\n   * Extract the next cursor from a just-fetched page. Return a `Cursor` to keep\n   * walking, or `null` when the API signalled the end (the walk finishes). PURE\n   * + consumer-specific (only the consumer knows the API's pagination shape).\n   */\n  readonly nextCursor: (page: Page) => Cursor | null;\n  /**\n   * The Cmds to emit for each successfully fetched page — the consumer's work\n   * per page (index, persist, fan out, …). Returns plain-data Cmds; `[]` is a\n   * valid \"I process the page synchronously elsewhere\" answer. PURE.\n   */\n  readonly onPage: (page: Page) => readonly EmittedCmd[];\n  /**\n   * How many items a page contributes to the paginator's backpressure gauge\n   * (`seen`). Defaults to `1` per page (count pages, not items) when omitted; a\n   * consumer that wants per-item backpressure returns `page.items.length`. PURE.\n   */\n  readonly pageSize?: (page: Page) => number;\n  /**\n   * Backpressure threshold handed to the paginator. `seen >= highWaterMark`\n   * parks the walk in `paused` instead of fetching the next page. Non-positive\n   * (the default `0`) disables backpressure — the walk runs flat out until the\n   * API exhausts. See `../paginator`'s `highWaterMark` docs.\n   */\n  readonly highWaterMark?: number;\n\n  // --- resilience bricks, inherited from resilient-call (all optional) ---\n  /** Exponential-backoff retry policy for a transient page-fetch failure. */\n  readonly retry?: RetryPolicy;\n  /** Circuit breaker around the page fetch (one upstream → one breaker). */\n  readonly circuit?: CircuitConfig;\n  /** Token-bucket rate limit — the \"don't 429 the upstream\" knob. */\n  readonly rateLimit?: RateLimitConfig;\n  /** Overall wall-clock deadline per individual page fetch. */\n  readonly deadline?: DeadlineConfig;\n}\n\n// ===========================================================================\n// Slice — the Model field this knob owns. The paginator walk state + the\n// resilient-call slice for the page fetch. Both are flat plain data.\n// ===========================================================================\n\n/**\n * The slice. `walk` is the cursor/phase/counters from `../paginator`;\n * `resilience` is the `../resilient-call` slice that gates the page fetch.\n * Every field is JSON-serializable, so the whole walk survives a reload.\n *\n * The two move in lockstep: `walk` decides WHICH cursor to fetch next, while\n * `resilience` decides HOW that fetch is attempted (gated, retried, backed\n * off). `pageOk` advances `walk`; `pageErr` defers to `resilience` and leaves\n * `walk` parked on the same cursor until the page truly settles.\n */\nexport interface PaginatedWalkState<Cursor, Page> {\n  readonly walk: PaginatorState<Cursor>;\n  readonly resilience: ResilientState<Cursor, Page>;\n}\n\n// ===========================================================================\n// Cmds + Msgs the knob speaks.\n// ===========================================================================\n\n/**\n * The page-fetch effect this knob emits: the inherited `resilient_run` Cmd from\n * resilient-call, whose `input` is the `Cursor` to fetch and whose `key` is the\n * fixed `PAGE_KEY`. The consumer's `handlers(ports)` interprets it.\n */\nexport type FetchPageCmd<Cursor> = RunCmd<Cursor>;\n\n/** Page-settled Msgs the `handlers` port dispatches back (inherited verbatim). */\nexport type PageOkMsg<Page> = SucceedMsg<Page>;\nexport type PageErrMsg = FailMsg;\n\n/** The retry / deadline timer Msg — inherited from resilient-call. */\nexport type PaginatedWalkTimerMsg = ResilientTimerMsg;\n\n/**\n * Ports the consumer supplies to `handlers`. `run(cursor)` fetches ONE page for\n * the given cursor; throwing routes to `pageErr` (and thus the resilience\n * backoff). Same shape as resilient-call's port, specialized to the page fetch.\n */\nexport interface PaginatedWalkPorts<Cursor, Page>\n  extends ResilientPorts<Cursor, Page> {}\n\n// ===========================================================================\n// The fixed key. A walk fetches one page at a time → exactly one logical\n// resilient call. The paginator is the sequencer; resilient-call's keying is\n// pinned to this single key.\n// ===========================================================================\n\n/** The single resilient-call key every page fetch runs under. */\nexport const PAGE_KEY = \"page\";\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build a paginated-walk knob from `config`. `rng` is injected for the\n * underlying retry jitter — pass a fixed `() => 0` in tests to pin backoff;\n * defaults to `Math.random` (read at the verb boundary inside resilient-call,\n * never in a `paginated-walk` verb). Inherited straight from resilient-call.\n *\n * Returns the uniform L2 knob contract: `init()`, the verbs `start` / `pageOk`\n * / `pageErr` / `onTimer`, `subs(state)`, and `handlers(ports)`. `Cursor` is\n * the page handle, `Page` the fetch result, `EmittedCmd` the consumer's\n * per-page Cmds plus the inherited `FetchPageCmd`.\n */\nexport function createPaginatedWalk<Cursor, Page, EmittedCmd extends Cmd = Cmd>(\n  config: PaginatedWalkConfig<Cursor, Page, EmittedCmd>,\n  rng: () => number = Math.random,\n) {\n  // The page fetch is a resilient call keyed by Cursor input → Page result.\n  // We feed it only the resilience bricks; the walk-loop knobs are ours.\n  const rc = createResilientCall<Cursor, Page>(\n    {\n      retry: config.retry,\n      circuit: config.circuit,\n      rateLimit: config.rateLimit,\n      deadline: config.deadline,\n    },\n    rng,\n  );\n\n  // The paginator policy: our firstPage is the paginator's firstCursor; the\n  // high-water mark gates backpressure (0 / omitted → unbounded).\n  const paginatorPolicy: PaginatorPolicy<Cursor> = {\n    firstCursor: config.firstPage,\n    highWaterMark: config.highWaterMark ?? 0,\n  };\n\n  // The combined Cmd type the verbs can emit: the inherited page-fetch effect\n  // plus whatever `onPage` yields.\n  type OutCmd = FetchPageCmd<Cursor> | EmittedCmd;\n\n  /** Replace the resilience slice, leaving `walk` untouched. */\n  function withResilience(\n    s: PaginatedWalkState<Cursor, Page>,\n    resilience: ResilientState<Cursor, Page>,\n  ): PaginatedWalkState<Cursor, Page> {\n    return { ...s, resilience };\n  }\n\n  /** The starting slice: an idle paginator + a fresh resilient-call slice. */\n  function init(): PaginatedWalkState<Cursor, Page> {\n    return {\n      walk: initPaginator<Cursor>(),\n      resilience: rc.init(),\n    };\n  }\n\n  /**\n   * Issue a resilient page fetch for `cursor` at `at`. The cursor is the\n   * resilient call's `input` (so a retry / resume re-fetches the same page) and\n   * `PAGE_KEY` is the fixed key. Returns the advanced resilience slice + the\n   * `resilient_run` Cmd (or none, if the gate cached / fast-failed / backed off).\n   * PURE — `at` is the only clock. Shared by `start` and `pageOk`'s advance.\n   */\n  function fetch(\n    s: PaginatedWalkState<Cursor, Page>,\n    cursor: Cursor,\n    at: number,\n  ): readonly [\n    PaginatedWalkState<Cursor, Page>,\n    readonly FetchPageCmd<Cursor>[],\n  ] {\n    const [resilience, cmds] = rc.attempt(s.resilience, PAGE_KEY, cursor, at);\n    return [withResilience(s, resilience), cmds];\n  }\n\n  // === Verb: start =========================================================\n\n  /**\n   * Begin the walk: arm the paginator's first cursor and issue the first page\n   * fetch (gated through resilience). On any non-`idle` paginator phase this is\n   * a no-op — re-starting a walk in flight would skip back to page one and\n   * double-count, so a stray `start` after launch is absorbed (the paginator's\n   * own `start` guard). PURE — `at` threads into the fetch gate.\n   */\n  function start(\n    s: PaginatedWalkState<Cursor, Page>,\n    at: number,\n  ): readonly [PaginatedWalkState<Cursor, Page>, readonly OutCmd[]] {\n    const walk = startWalk(s.walk, paginatorPolicy);\n    // `startWalk` is a pure no-op on any non-`idle` phase: it returns the SAME\n    // state object. Reference identity (not phase) is the honest \"did anything\n    // arm?\" check — a walk already `fetching` would also satisfy\n    // `phase === \"fetching\"` yet must NOT re-issue a fetch (page-one skip /\n    // double-fetch). So we proceed ONLY when start produced a fresh state. The\n    // `phase === \"fetching\"` narrow that follows is therefore always true here\n    // (start only ever produces a `fetching` arm), and also narrows `.cursor`\n    // for the type checker.\n    if (walk === s.walk || walk.phase !== \"fetching\") {\n      return [s, []];\n    }\n    // Armed `fetching(firstCursor)` → issue the first page fetch.\n    return fetch({ ...s, walk }, walk.cursor, at);\n  }\n\n  // === Verb: pageOk ========================================================\n\n  /**\n   * Record a successfully fetched `page` and decide what comes next. PURE —\n   * `at` is the cache / next-fetch clock.\n   *\n   *   1. Settle the resilient call OK (closes the breaker, fills the cache,\n   *      resets the page-fetch retry counter) — inherited from resilient-call.\n   *   2. Fold the page through the paginator: add `pageSize(page)` to `seen`,\n   *      bump `pages`, and branch on `nextCursor(page)`:\n   *        - `null`     → the API is exhausted → paginator goes `done`.\n   *        - a cursor   → advance, then either fetch it (backpressure room) or\n   *                       park in `paused` (high-water mark reached).\n   *   3. Emit the consumer's `onPage(page)` Cmds either way, PLUS the next\n   *      page-fetch effect when the paginator stays `fetching`.\n   *\n   * A `pageOk` that arrives when the paginator is not `fetching` (a late\n   * duplicate, a double-dispatch) is absorbed by `recordPage` — the cursor does\n   * not advance and `seen` is not double-counted; only the resilient settle +\n   * `onPage` Cmds happen. The walk is a coordination aid, not a correctness\n   * gate.\n   */\n  function pageOk(\n    s: PaginatedWalkState<Cursor, Page>,\n    page: Page,\n    at: number,\n  ): readonly [PaginatedWalkState<Cursor, Page>, readonly OutCmd[]] {\n    // 1) Settle the underlying resilient call as a success.\n    const [resilience] = rc.succeed(s.resilience, PAGE_KEY, {\n      type: MsgType.ResilientOk,\n      key: PAGE_KEY,\n      result: page,\n      at,\n    });\n\n    // 2) Advance the paginator with the page's contribution + the next cursor.\n    const count = config.pageSize ? config.pageSize(page) : 1;\n    const next = config.nextCursor(page);\n    const walk = recordPage(s.walk, count, next, paginatorPolicy);\n\n    const advanced: PaginatedWalkState<Cursor, Page> = { walk, resilience };\n\n    // 3) The consumer's per-page work, always emitted on a successful page.\n    const pageCmds: readonly EmittedCmd[] = config.onPage(page);\n\n    // If the paginator stayed `fetching`, issue the next page fetch (gated).\n    if (walk.phase === \"fetching\") {\n      const [withFetch, fetchCmds] = fetch(advanced, walk.cursor, at);\n      return [withFetch, [...pageCmds, ...fetchCmds]];\n    }\n\n    // `done` (exhausted) or `paused` (backpressure) → no further fetch now.\n    return [advanced, pageCmds];\n  }\n\n  // === Verb: pageErr =======================================================\n\n  /**\n   * Record a failed page fetch and back off via resilience. PURE — `at` stamps\n   * the breaker trip + the retry-delay base.\n   *\n   * Defers to the resilient-call `fail` verb: it trips the breaker and either\n   * schedules a retry (paginator stays parked on the SAME cursor — no advance)\n   * or settles the resilient call `failed` once retries are exhausted. The\n   * paginator is deliberately untouched: a failed fetch must NOT advance the\n   * cursor or skip a page. When the retry timer later fires, `onTimer` re-issues\n   * the same page fetch.\n   *\n   * GUARDED by the paginator phase, exactly as `pageOk` is guarded by\n   * `recordPage`'s `fetching`-only check. A `pageErr` only makes sense while a\n   * page fetch is outstanding (`walk.phase === \"fetching\"`). A stray `pageErr`\n   * that arrives after the walk has settled — `done` (exhausted), `paused`\n   * (backpressure), or `idle` (not started) — has NO outstanding fetch to fail.\n   * Without this guard it would still call `rc.fail`, which trips the SHARED\n   * circuit breaker (dinging a healthy upstream) and overwrites the settled\n   * `PAGE_KEY` resilient slot with `failed` (clobbering the succeeded result a\n   * resume would otherwise observe). So a stray `pageErr` is absorbed as a pure\n   * no-op — identity preserved — matching `pageOk`'s \"the walk is a coordination\n   * aid, not a correctness gate\" stance.\n   */\n  function pageErr(\n    s: PaginatedWalkState<Cursor, Page>,\n    error: unknown,\n    at: number,\n  ): readonly [PaginatedWalkState<Cursor, Page>, readonly OutCmd[]] {\n    // Only a `fetching` paginator has an outstanding page fetch to fail. On any\n    // other phase the fail would corrupt shared resilience state for a fetch\n    // that is not in flight — absorb it as a pure no-op.\n    if (s.walk.phase !== \"fetching\") {\n      return [s, []];\n    }\n    const [resilience, cmds] = rc.fail(s.resilience, PAGE_KEY, {\n      type: MsgType.ResilientErr,\n      key: PAGE_KEY,\n      error,\n      at,\n    });\n    return [withResilience(s, resilience), cmds];\n  }\n\n  // === Verb: onTimer =======================================================\n\n  /**\n   * A retry / deadline timer fired. Defers to resilient-call's `onTimer`: a\n   * retry timer re-runs the gate for the page-fetch's remembered cursor (re-\n   * issuing the SAME page); a deadline timer settles the resilient call failed.\n   * The paginator stays parked on its cursor throughout — only `pageOk` advances\n   * it. A stale fire is a no-op (inherited). PURE.\n   *\n   * GUARDED by the paginator phase, for the same reason as `pageErr`. A timer is\n   * only meaningful while a page fetch is outstanding (`walk.phase ===\n   * \"fetching\"`). A stray timer that fires after the walk has settled (`done` /\n   * `paused` / `idle`) would otherwise re-enter `rc.onTimer` — re-issuing a fetch\n   * the paginator no longer wants (a deadline timer could even overwrite the\n   * settled `PAGE_KEY` slot with a deadline `failed`). On any non-`fetching`\n   * phase the timer is absorbed as a pure no-op.\n   */\n  function onTimer(\n    s: PaginatedWalkState<Cursor, Page>,\n    msg: PaginatedWalkTimerMsg,\n  ): readonly [PaginatedWalkState<Cursor, Page>, readonly OutCmd[]] {\n    if (s.walk.phase !== \"fetching\") {\n      return [s, []];\n    }\n    const [resilience, cmds] = rc.onTimer(s.resilience, msg);\n    if (resilience === s.resilience) {\n      // Inherited no-op identity → keep our slice identity too (pure no-op).\n      return [s, []];\n    }\n    return [withResilience(s, resilience), cmds];\n  }\n\n  // === Verb: drain =========================================================\n\n  /**\n   * Acknowledge that the consumer finished processing `n` items, lowering the\n   * paginator's backpressure gauge (`seen`). PURE — no clock. Delegates to\n   * `paginator.drain`: subtracts `n` (floored at 0), leaves the phase untouched.\n   *\n   * The OTHER half of the backpressure valve `highWaterMark` opens: `recordPage`\n   * parks the walk in `paused` once `seen >= highWaterMark`, and `drain` is how a\n   * consumer lowers `seen` back below the mark so `resume` can re-open the fetch.\n   * Without it `highWaterMark` would be a one-way valve — a walk could pause but\n   * never continue. Emits no Cmds: draining only frees headroom; `resume` is the\n   * separate, explicit \"continue now\" decision.\n   */\n  function drain(\n    s: PaginatedWalkState<Cursor, Page>,\n    n: number,\n  ): readonly [PaginatedWalkState<Cursor, Page>, readonly OutCmd[]] {\n    const walk = drainWalk(s.walk, n);\n    if (walk === s.walk) {\n      // Pure no-op identity (n <= 0, or seen already at floor).\n      return [s, []];\n    }\n    return [{ ...s, walk }, []];\n  }\n\n  // === Verb: resume ========================================================\n\n  /**\n   * Re-open the backpressure valve after a `drain`: if the walk is `paused` and\n   * `seen` has dropped below `highWaterMark`, re-arm the parked cursor and issue\n   * its page fetch (gated through resilience). PURE — `at` threads into the fetch\n   * gate. Delegates the phase decision to `paginator.resume`:\n   *\n   *   - `paused` AND `seen < highWaterMark` → `fetching(cursor)` → emit the fetch.\n   *   - `paused` but still over the mark    → no-op (the valve stays shut until a\n   *                                           further `drain` frees real headroom).\n   *   - any other phase                     → no-op (nothing to resume).\n   *\n   * Together with `drain` this completes the valve: `recordPage` shuts it\n   * (`paused`), `drain` lowers the gauge, `resume` re-opens it and fires the next\n   * page fetch — the same `fetch` helper `start` / `pageOk` use, so a resumed\n   * fetch is gated identically (cache / circuit / rate-limit / retry).\n   */\n  function resume(\n    s: PaginatedWalkState<Cursor, Page>,\n    at: number,\n  ): readonly [PaginatedWalkState<Cursor, Page>, readonly OutCmd[]] {\n    const walk = resumeWalk(s.walk, paginatorPolicy);\n    // `resumeWalk` is a pure no-op (same reference) on any phase but `paused`, or\n    // when `seen` is still at/over the mark. Only a fresh `fetching` arm means\n    // the valve actually re-opened — issue the page fetch only then.\n    if (walk === s.walk || walk.phase !== \"fetching\") {\n      return [s, []];\n    }\n    return fetch({ ...s, walk }, walk.cursor, at);\n  }\n\n  // === Derived predicates ==================================================\n\n  /**\n   * Whether the walk has finished — the API returned a null next cursor and the\n   * paginator is `done`. PURE, read-only. Lets a consumer's reducer fire a\n   * \"walk complete\" Cmd (`if (walk.isDone(s.walk)) …`) without re-checking the\n   * paginator phase by hand.\n   */\n  function isComplete(s: PaginatedWalkState<Cursor, Page>): boolean {\n    return isDone(s.walk);\n  }\n\n  /**\n   * The terminal page-fetch failure that stranded the walk, or `undefined` if no\n   * page has terminally failed. PURE, read-only. Errors are data: a page that\n   * exhausts its retries (or trips the deadline) settles the `PAGE_KEY` resilient\n   * slot to `failed` while the paginator stays parked on its cursor — the walk is\n   * stuck and will never advance on its own. Without a way to read that phase the\n   * failure is unobservable: the walk simply stops emitting fetches with no\n   * signal. `failure(s)` surfaces the settled error (the same plain-data sentinel\n   * resilient-call records) so a consumer can fire a \"walk dead\" Cmd, alert, or\n   * re-`start` a fresh walk.\n   */\n  function failure(s: PaginatedWalkState<Cursor, Page>): unknown {\n    const call = s.resilience.calls[PAGE_KEY];\n    return call?.phase === \"failed\" ? call.error : undefined;\n  }\n\n  /**\n   * Whether the walk is STUCK: a page fetch has terminally `failed` yet the\n   * paginator is still parked on a cursor (not `done`), so no further fetch will\n   * ever be issued without intervention. PURE, read-only.\n   *\n   * This is the dead-walk predicate the consumer polls (`if (walk.isStuck(s)) …`)\n   * to distinguish a healthy finish (`isComplete`) from a silent death. A walk is\n   * stuck precisely when the resilient slot settled `failed` AND the paginator\n   * has NOT reached `done` — a terminal failure on the final page that also\n   * finished the walk is `isComplete`, not stuck. Pairs with `failure(s)`, which\n   * hands back the error that stuck it.\n   */\n  function isStuck(s: PaginatedWalkState<Cursor, Page>): boolean {\n    return s.resilience.calls[PAGE_KEY]?.phase === \"failed\" && !isDone(s.walk);\n  }\n\n  // === Subs ================================================================\n\n  /**\n   * Pre-wired subscriptions: exactly the resilient-call subs for the page\n   * fetch — a retry timer while the fetch is `waiting_retry`, and (with the\n   * `deadline` brick) a per-fetch deadline timer while it is active. Reconciled\n   * by id, so a phase change cancels the matching timer automatically. Wire\n   * `subscribe: { deadline: subscribeDeadline }` (re-exported below).\n   */\n  function subs(s: PaginatedWalkState<Cursor, Page>): readonly DeadlineSub[] {\n    return rc.subs(s.resilience);\n  }\n\n  // === Handlers ============================================================\n\n  /**\n   * Pre-wired interpret handler for the page-fetch effect. Inherited from\n   * resilient-call (`resilient_run`): wraps the consumer's `run(cursor)` port\n   * via `tryInterpret` (Railway) — success → `resilient_ok` (handled by\n   * `pageOk`), failure → `resilient_err` (handled by `pageErr`), each stamped\n   * with `Date.now()` at the effect boundary (the ONE permitted clock read).\n   *\n   *   interpret: walk.handlers({ run: (cursor) => api.fetchPage(cursor) })\n   *\n   * The consumer maps the inherited Msg types to their `pageOk` / `pageErr`\n   * reducer cells (the wire shape is `resilient_ok` / `resilient_err`).\n   */\n  function handlers(ports: PaginatedWalkPorts<Cursor, Page>) {\n    return rc.handlers(ports);\n  }\n\n  return {\n    init,\n    start,\n    pageOk,\n    pageErr,\n    onTimer,\n    drain,\n    resume,\n    isComplete,\n    failure,\n    isStuck,\n    subs,\n    handlers,\n  };\n}\n\n/**\n * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the slice\n * lives at `state.walk`. A convenience for the common single-slice host;\n * consumers with a differently-named field spread by hand. Pure — a thin record\n * rebuild, no clock / RNG.\n */\nexport function liftWalk<\n  S extends { walk: PaginatedWalkState<Cursor, Page> },\n  Cursor,\n  Page,\n  C extends Cmd,\n>(\n  state: S,\n  [slice, cmds]: readonly [PaginatedWalkState<Cursor, Page>, readonly C[]],\n): readonly [S, readonly C[]] {\n  return [{ ...state, walk: slice }, cmds];\n}\n\n/**\n * Re-export the deadline Sub primitives (inherited from resilient-call) so\n * consumers wire one import: `subscribeDeadline` is the `subscribe` cell,\n * `deadlineSub` builds the Sub literal this knob's `subs` emits.\n */\nexport { subscribeDeadline, deadlineSub };\nexport type { DeadlineSub };\n"]}

package/dist/chunk-IK4S5DJN.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/trace-replay/index.ts"],"names":[],"mappings":";;;AAoEO,SAAS,WAAA,CAOd,OAAA,EACA,KAAA,EACA,GAAA,EACiB;AACjB,EAAA,MAAM,MAAA,GAAS,OAAO,OAAA,EAAS;AAAA,IAC7B,MAAM,KAAA,CAAM,IAAA;AAAA,IACZ,GAAA;AAAA,IACA,QAAQ,KAAA,CAAM;AAAA,GACf,CAAA;AACD,EAAA,MAAM,SAAS,MAAA,CAAO,KAAA;AACtB,EAAA,MAAM,WAAW,KAAA,CAAM,UAAA;AAEvB,EAAA,MAAM,UAAA,GAAa,eAAA,CAAgB,QAAA,EAAU,MAAA,EAAQ,OAAO,CAAA;AAC5D,EAAA,IAAI,eAAe,IAAA,EAAM;AACvB,IAAA,OAAO,EAAE,OAAA,EAAS,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAAA,EAC3C;AACA,EAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,QAAA,EAAU,QAAQ,UAAA,EAAW;AACxD;AASO,SAAS,SAAA,CAAU,GAAY,CAAA,EAAqB;AACzD,EAAA,OAAO,eAAA,CAAgB,CAAA,EAAG,CAAA,EAAG,OAAO,CAAA,KAAM,IAAA;AAC5C;AAsBA,SAAS,eAAA,CACP,QAAA,EACA,MAAA,EACA,IAAA,EACY;AAIZ,EAAA,IAAI,MAAA,CAAO,EAAA,CAAG,QAAA,EAAU,MAAM,GAAG,OAAO,IAAA;AAExC,EAAA,MAAM,EAAA,GAAK,OAAO,QAAQ,CAAA;AAC1B,EAAA,MAAM,EAAA,GAAK,OAAO,MAAM,CAAA;AAGxB,EAAA,IAAI,OAAO,EAAA,EAAI,OAAO,EAAE,IAAA,EAAM,UAAU,MAAA,EAAO;AAE/C,EAAA,IAAI,OAAO,OAAA,EAAS;AAClB,IAAA,MAAM,EAAA,GAAK,QAAA;AACX,IAAA,MAAM,EAAA,GAAK,MAAA;AACX,IAAA,IAAI,EAAA,CAAG,MAAA,KAAW,EAAA,CAAG,MAAA,EAAQ;AAG3B,MAAA,OAAO,EAAE,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAAA,IAClC;AACA,IAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,EAAA,CAAG,QAAQ,CAAA,EAAA,EAAK;AAClC,MAAA,MAAM,CAAA,GAAI,eAAA,CAAgB,EAAA,CAAG,CAAC,CAAA,EAAG,EAAA,CAAG,CAAC,CAAA,EAAG,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,CAAC,CAAA,CAAA,CAAG,CAAA;AACvD,MAAA,IAAI,CAAA,KAAM,MAAM,OAAO,CAAA;AAAA,IACzB;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,IAAI,OAAO,QAAA,EAAU;AACnB,IAAA,MAAM,EAAA,GAAK,QAAA;AACX,IAAA,MAAM,EAAA,GAAK,MAAA;AAIX,IAAA,MAAM,OAAO,CAAC,uBAAO,GAAA,CAAI,CAAC,GAAG,MAAA,CAAO,IAAA,CAAK,EAAE,CAAA,EAAG,GAAG,OAAO,IAAA,CAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAA,EAAK;AACzE,IAAA,KAAA,MAAW,OAAO,IAAA,EAAM;AACtB,MAAA,MAAM,CAAA,GAAI,eAAA,CAAgB,EAAA,CAAG,GAAG,CAAA,EAAG,EAAA,CAAG,GAAG,CAAA,EAAG,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,GAAG,CAAA,CAAE,CAAA;AAC5D,MAAA,IAAI,CAAA,KAAM,MAAM,OAAO,CAAA;AAAA,IACzB;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AAIA,EAAA,OAAO,EAAE,IAAA,EAAM,QAAA,EAAU,MAAA,EAAO;AAClC;AAGA,SAAS,OACP,CAAA,EACyD;AACzD,EAAA,IAAI,CAAA,KAAM,MAAM,OAAO,MAAA;AACvB,EAAA,IAAI,CAAA,KAAM,QAAW,OAAO,WAAA;AAC5B,EAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,CAAC,CAAA,EAAG,OAAO,OAAA;AAC7B,EAAA,IAAI,OAAO,CAAA,KAAM,QAAA,EAAU,OAAO,QAAA;AAClC,EAAA,OAAO,WAAA;AACT","file":"chunk-IK4S5DJN.js","sourcesContent":["// ---------------------------------------------------------------------------\n// trace-replay — replay a recorded Trace against a machine and diff the state.\n//\n// This is the back half of the record/replay feature. `../recorder` captures\n// a run (`loaded` + `msgs` + `finalState`); this module feeds that input\n// through the core `replay(machine, { msgs, ctx, loaded })` fold and asks:\n//\n//     does the current reducer still produce the SAME final state for this\n//     recorded input?\n//\n// Equal ⇒ the reducer is behavior-compatible with the recording. Diverged ⇒\n// the reducer changed for that input, and the divergence path\n// (`state.queue[2].status`) points at exactly the cell that drifted. This is\n// the regression / production-repro tool: record a prod incident, replay it\n// against the fixed reducer locally, confirm the fix changes the state at the\n// path you expected — or catch an unintended drift before it ships.\n//\n// Standalone by design. It imports ONLY the `Trace` type from `../recorder`\n// and the `replay` engine from `../index`. The deep-equal + first-divergence\n// path finder is self-contained (no external diff lib) — a richer pretty-diff\n// lands in `../devtools` later; trace-replay stays dependency-free so it can\n// run anywhere a machine runs (CI, a Worker, a Node script).\n// ---------------------------------------------------------------------------\n\nimport { type Cmd, type Machine, replay, type Sub } from \"../index\";\nimport type { Trace } from \"../recorder\";\n\n/**\n * The outcome of {@link replayTrace}.\n *\n * @typeParam S - the machine's State type.\n */\nexport interface ReplayResult<S> {\n  /** `true` iff the recomputed final state deep-equals the trace's `finalState`. */\n  matches: boolean;\n  /** The trace's recorded `finalState` — what the run originally produced. */\n  expected: S;\n  /** The state the current reducer produced for the same input. */\n  actual: S;\n  /**\n   * Present iff `matches` is `false`. The FIRST point of divergence found by\n   * a deterministic pre-order walk:\n   *   - `path`     — a dotted/indexed access path from the state root, e.g.\n   *                  `state.queue[2].status` or `state` for a root-level\n   *                  scalar mismatch.\n   *   - `expected` — the recorded value at that path.\n   *   - `actual`   — the recomputed value at that path.\n   */\n  divergence?: { path: string; expected: unknown; actual: unknown };\n}\n\n/**\n * Replay a recorded {@link Trace} against `machine` and diff the recomputed\n * final state against the recorded one.\n *\n * Runs the core pure fold `replay(machine, { msgs: trace.msgs, ctx,\n * loaded: trace.loaded })` — init + update only, never `interpret`, never a\n * `Store`, never a live subscription (see `replay` in ../index). The `ctx` is\n * supplied fresh by the caller: the trace is the INPUT (loaded + msgs); ctx is\n * the ENVIRONMENT the reducer runs against now.\n *\n * @param machine - the machine to replay against. Mutating its reducer (the\n *                  whole point of a regression check) is what makes a recorded\n *                  trace diverge.\n * @param trace   - a Trace from `../recorder` (live `dump()` or a re-hydrated\n *                  `parseJSONL(...)`).\n * @param ctx     - the runtime ctx, supplied fresh at replay time.\n */\nexport function replayTrace<\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  trace: Trace<S, M>,\n  ctx: Ctx,\n): ReplayResult<S> {\n  const result = replay(machine, {\n    msgs: trace.msgs,\n    ctx,\n    loaded: trace.loaded,\n  });\n  const actual = result.state;\n  const expected = trace.finalState;\n\n  const divergence = firstDivergence(expected, actual, \"state\");\n  if (divergence === null) {\n    return { matches: true, expected, actual };\n  }\n  return { matches: false, expected, actual, divergence };\n}\n\n/**\n * Order-insensitive structural deep-equality — the single comparator this\n * package owns, exposed so consumers (e.g. `@demlik/tea/parity`'s `diff`)\n * reuse it rather than adding a second deep-compare. `true` iff `a` and `b`\n * are structurally equal under {@link firstDivergence}'s walk (object keys\n * compared order-insensitively, arrays index-by-index).\n */\nexport function deepEqual(a: unknown, b: unknown): boolean {\n  return firstDivergence(a, b, \"state\") === null;\n}\n\n// === self-contained deep-equal + first-divergence path finder ===\n//\n// One walk does both jobs: it returns the FIRST point where `expected` and\n// `actual` differ (as a path + the two values), or `null` when they are\n// deeply equal. \"First\" is defined by a deterministic pre-order traversal:\n// the node itself, then its children in a stable key order (array index\n// order; object keys sorted so the result does not depend on insertion\n// order — two states with the same data but different key order are equal,\n// and the reported path for a real mismatch is reproducible run-to-run).\n//\n// Scope: TEA state is plain JSON-shaped data (the substrate's __DEV__ guards\n// reject closures in Cmds, and states are conventionally serializable). So\n// the walk handles: primitives, null/undefined, arrays, and plain objects.\n// It treats other object kinds (Date, Map, Set, class instances) by reference\n// identity + a structural fallback via Object.entries — sufficient for the\n// JSON-shaped states this tool targets; a richer differ lives in ../devtools.\n\n/** A divergence record, or `null` when the two values are deeply equal. */\ntype Divergence = { path: string; expected: unknown; actual: unknown } | null;\n\nfunction firstDivergence(\n  expected: unknown,\n  actual: unknown,\n  path: string,\n): Divergence {\n  // Identity / primitive fast path. Handles same-reference, and equal\n  // primitives. `Object.is` so NaN === NaN and +0 ≠ -0 (matches structural\n  // equality intent better than ===).\n  if (Object.is(expected, actual)) return null;\n\n  const te = typeOf(expected);\n  const ta = typeOf(actual);\n  // Different kinds at this node (e.g. object vs array, number vs string,\n  // present vs null) — this node IS the divergence.\n  if (te !== ta) return { path, expected, actual };\n\n  if (te === \"array\") {\n    const ae = expected as unknown[];\n    const aa = actual as unknown[];\n    if (ae.length !== aa.length) {\n      // Length mismatch reported at the array node itself — the shape differs,\n      // which is more informative than an arbitrary element index.\n      return { path, expected, actual };\n    }\n    for (let i = 0; i < ae.length; i++) {\n      const d = firstDivergence(ae[i], aa[i], `${path}[${i}]`);\n      if (d !== null) return d;\n    }\n    return null;\n  }\n\n  if (te === \"object\") {\n    const oe = expected as Record<string, unknown>;\n    const oa = actual as Record<string, unknown>;\n    // Union of keys, sorted for deterministic traversal. A key present in one\n    // but absent in the other diverges at that child path (its value is\n    // `undefined` on the missing side).\n    const keys = [...new Set([...Object.keys(oe), ...Object.keys(oa)])].sort();\n    for (const key of keys) {\n      const d = firstDivergence(oe[key], oa[key], `${path}.${key}`);\n      if (d !== null) return d;\n    }\n    return null;\n  }\n\n  // Primitives (string/number/boolean/bigint/symbol/function) that failed the\n  // Object.is fast path, or null/undefined that differ — this node diverges.\n  return { path, expected, actual };\n}\n\n/** Coarse type tag used by the divergence walk to decide how to recurse. */\nfunction typeOf(\n  v: unknown,\n): \"null\" | \"undefined\" | \"array\" | \"object\" | \"primitive\" {\n  if (v === null) return \"null\";\n  if (v === undefined) return \"undefined\";\n  if (Array.isArray(v)) return \"array\";\n  if (typeof v === \"object\") return \"object\";\n  return \"primitive\";\n}\n"]}

package/dist/chunk-M6UZT7HS.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/llm-call/index.ts"],"names":["msg"],"mappings":"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","file":"chunk-M6UZT7HS.js","sourcesContent":["/**\n * @demlik/tea/llm-call — `resilient-call` + structured-output parse + a typed\n * failure variant, around a purpose-discriminated LLM invocation.\n *\n * This is the ~60-line `call_llm` handler from the audit-agent seed\n * (`interpret.ts` / `effects.ts`) collapsed into the uniform L2 knob: a config\n * object, the resilient-call slice it inherits, and one interpret handler that\n * assembles messages, binds the structured-output schema for the call's\n * `purpose`, invokes the model (retry composed from `../resilient-call`, NOT\n * reinvented), parses the output, and RETURNS the enriched resilient settle Msg\n * (`resilient_ok` / `resilient_err`) so it re-enters the host reducer and drives\n * the inherited succeed/fail → backoff → onTimer loop.\n *\n * ## What it adds over `../resilient-call`\n *\n *   - **Two DI ports** (the seed's two seams):\n *       1. `model: (modelId) => LLM` — the model factory. Tests pass a fake so\n *          the handler runs end-to-end without touching a real provider; the\n *          production worker wires `createChatModel(env, …)`.\n *       2. `loadMessages: Loader` — the SDK / message loader. The seed lazy-\n *          imports `@langchain/core/messages` (a top-level `import type` blows\n *          up the workers test runner); the loader keeps that import lazy and\n *          stubbable. It produces the `BaseMessage[]` for a given call.\n *   - **Structured-output parse** — each `purpose` maps to a `Schema` in\n *     `config.schemas`. The handler binds `model.withStructuredOutput(schema)`\n *     so the invoke resolves to a typed object; a `Schema.parse` that throws\n *     becomes a `resilient_err` carrying an `LlmErr` (a parse failure is a\n *     failure, not a stall — \"errors are data\"). `withStructuredOutput` is the\n *     seed's brain-only path; the fake model in tests returns the typed object\n *     directly.\n *   - **A typed failure variant** — every failure (model throw, timeout-via-\n *     retry-exhaustion, schema parse) is surfaced as the `LlmErr` carried on the\n *     enriched `resilient_err` settle Msg, tagged with the `purpose` so the\n *     consumer's reducer routes per-stage. The seed dispatched\n *     `llm_failed{purpose}`; the consumer rebuilds that shape in its reducer arm\n *     from `m.error: LlmErr`.\n *\n * ## Inheriting resilient-call by composition (not reinvention)\n *\n * The retry / backoff lives in `../resilient-call`: `createLlmCall` builds a\n * `createResilientCall` knob over the model-invoke port and DELEGATES `init`,\n * `attempt`, `succeed`, `fail`, `onTimer`, `subs` to it verbatim — the slice is\n * literally resilient-call's slice (the spec's \"retry lives here\"). There is no\n * second backoff implementation here. The handler runs the invoke through the\n * resilient-call handler so a transient model failure backs off exactly as a\n * resilient HTTP call would; the `purpose`-branch + structured parse wrap the\n * port the resilient handler drives.\n *\n * ## The two non-negotiables (canon, inherited)\n *\n *   - **Durable** — the slice is resilient-call's plain-data slice (a Model\n *     field). Input carried on the `resilient_run` Cmd is the plain\n *     `LlmCall` request (purpose + modelId + payload) — no closures.\n *   - **Replayable** — every transition is a resilient-call verb; the handler\n *     is the only impurity, and the one clock read is `Date.now()` at the\n *     effect boundary (inside the handler), exactly as the seed stamped its\n *     `llm_responded` / `llm_failed` Msgs.\n *\n * ## Typical wiring\n *\n *   const llm = createLlmCall<MyPurpose, MyOutputs>({\n *     model: (id) => createChatModel(env, id),\n *     schemas: { plan: planSchema, report: reportSchema },\n *     retry: defaultRetryPolicy,\n *     loadMessages: defaultMessagesLoader,\n *   });\n *\n *   // in the machine:\n *   init: () => [{ resilience: llm.init() }, []],\n *   update: {\n *     call_llm:  (s, m) => lift(s, llm.attempt(s.resilience, m.input, m.at)),\n *     // `resilient_ok` / `resilient_err` RE-ENTER from `handlers` (the settle\n *     // Msg the interpret handler returns). Run the inherited verb FIRST so the\n *     // succeed/fail → backoff → onTimer loop advances, THEN fold the enriched\n *     // payload (`m.result: LlmOk` / `m.error: LlmErr`) into the host's own\n *     // state — the enrichment lives in the reducer arm, not the handler.\n *     resilient_ok:  (s, m) => {\n *       const [slice, cmds] = llm.succeed(s.resilience, m.key, m);\n *       return [{ ...s, resilience: slice, output: m.result.output }, cmds];\n *     },\n *     resilient_err: (s, m) => {\n *       const [slice, cmds] = llm.fail(s.resilience, m.key, m);\n *       return [{ ...s, resilience: slice, failure: m.error }, cmds];\n *     },\n *     deadline_exceeded: (s, m) => lift(s, llm.onTimer(s.resilience, m)),\n *   },\n *   subscriptions: (s) => llm.subs(s.resilience),\n *   subscribe: { deadline: subscribeDeadline },\n *   interpret: llm.handlers(),\n */\n\nimport type { Cmd } from \"../index\";\nimport { MsgType } from \"../protocol\";\nimport {\n  createResilientCall,\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineSub,\n  type FailMsg,\n  liftResilience,\n  type ResilientConfig,\n  type ResilientState,\n  type RunCmd,\n  type SucceedMsg,\n  subscribeDeadline,\n} from \"../resilient-call\";\nimport type { RetryPolicy } from \"../retry-backoff\";\n\n// ===========================================================================\n// The DI port surfaces — model factory + structured output + message loader.\n// ===========================================================================\n\n/**\n * The minimal structured-output schema contract: `parse(unknown) => T`, the\n * zod-style call the handler uses to validate the model's output before it\n * settles `resilient_ok`. A throwing `parse` (the zod contract on invalid\n * input) propagates out of `invokeOne` and is caught by the resilient handler,\n * which settles `resilient_err` (enriched to `LlmErr`) — a parse failure is a\n * failure, never a silent pass. Structural so a real `z.ZodType<T>` satisfies\n * it without an import.\n */\nexport interface Schema<T> {\n  /** Validate + narrow `value` to `T`, or throw on mismatch (the zod contract). */\n  parse(value: unknown): T;\n}\n\n/**\n * The minimal chat-model contract every model the handler talks to must\n * satisfy — the seed's `InjectableChatModel`, trimmed to the one operation\n * llm-call drives for brain-only stages:\n *\n *   `withStructuredOutput(schema)` → a runnable whose `invoke(messages)`\n *   resolves to a typed object matching `schema`.\n *\n * `BaseChatModel` from `@langchain/core` is the runtime type; this surface\n * names only what llm-call calls so a test fake can ignore the rest. Generic\n * over the message shape `Msg` so a consumer's loader and model agree on it\n * without llm-call inspecting messages.\n */\nexport interface Llm<Msg> {\n  withStructuredOutput<T>(schema: Schema<T>): {\n    invoke(messages: readonly Msg[]): Promise<T>;\n  };\n}\n\n/**\n * Build the `Msg[]` the handler hands to the bound model for a given call. The\n * SDK / message-assembly seam — the seed's `buildBaseMessages` + the lazy\n * `loadMessages` loader rolled into one injected port. Async because the seed\n * lazy-imports the SDK (a top-level `import type` of the langchain messages\n * package explodes the workers test runner). Receives the full `LlmCall` so it\n * can branch on `purpose` exactly as the seed's `buildBaseMessages` did.\n */\nexport type MessageLoader<P extends string, Msg> = (\n  call: LlmCall<P>,\n) => Promise<readonly Msg[]>;\n\n/**\n * The model factory — the first DI port. `(modelId) => Llm`. Tests pass a fake\n * builder; production wires `createChatModel(env, getModelConfig(id))`. `null`\n * means \"the host's default model\" (the seed's `string | null`).\n */\nexport type ModelFactory<Msg> = (modelId: string | null) => Llm<Msg>;\n\n// ===========================================================================\n// Config — the knob. `model` + `schemas` required (the two DI ports + the\n// per-purpose parse target); `retry` + `loadMessages` optional.\n// ===========================================================================\n\n/**\n * The llm-call knob. `model` and `schemas` are the load-bearing pair — the\n * model factory DI port and the per-purpose structured-output targets; the\n * rest is optional, exactly the resilient-call \"omit a brick → omit its gate\"\n * story for `retry`:\n *\n *   - `model`        — DI port 1: the model factory.\n *   - `schemas`      — one `Schema` per `Purpose`. The handler binds\n *                      `schemas[call.purpose]` as the structured-output target.\n *   - `retry`        — backoff policy, composed straight into `../resilient-\n *                      call`. Omit it and a model failure is terminal (no\n *                      backoff), exactly as resilient-call with no retry brick.\n *   - `loadMessages` — DI port 2: the SDK / message loader. Omit it and the\n *                      handler invokes the bound model with `[]` (a degenerate\n *                      but valid call) — provide it to assemble real messages.\n *\n * `P` is the purpose union (e.g. `\"plan\" | \"report\"`); `O` maps each purpose to\n * its parsed output type; `Msg` is the model's message shape (threaded through\n * the loader + model so llm-call never inspects a message).\n */\nexport interface LlmCallConfig<\n  P extends string,\n  O extends Record<P, unknown>,\n  Msg = unknown,\n> {\n  /** DI port 1 — the model factory. `(modelId) => Llm`. */\n  readonly model: ModelFactory<Msg>;\n  /** One structured-output schema per purpose; the parse target the handler binds. */\n  readonly schemas: { readonly [K in P]: Schema<O[K]> };\n  /** Backoff policy, composed into `../resilient-call`. Omit → no backoff. */\n  readonly retry?: RetryPolicy;\n  /** DI port 2 — the SDK / message loader. Omit → the handler invokes with `[]`. */\n  readonly loadMessages?: MessageLoader<P, Msg>;\n}\n\n// ===========================================================================\n// The request / response shapes the knob speaks.\n// ===========================================================================\n\n/**\n * One LLM call request — the resilient-call `input` for this knob, carried on\n * the `resilient_run` Cmd as plain data (no closures, invariant 3). Mirrors the\n * seed's purpose-discriminated `CallLlmCmd`: a `purpose` selecting the schema +\n * prompt assembly, the `model` id, and the opaque per-purpose `payload` the\n * loader consumes.\n *\n * `key` defaults to `purpose` when the consumer calls `attempt(s, purpose, …)`,\n * so one in-flight call per purpose is tracked under the resilient-call slice —\n * the common single-call-per-stage shape. A consumer that fans out many calls\n * of one purpose passes a distinct `key`.\n */\nexport interface LlmCall<P extends string> {\n  /** The stage / schema selector — drives both `schemas[purpose]` and message assembly. */\n  readonly purpose: P;\n  /** The model id to invoke; `null` = the host's default model. */\n  readonly model: string | null;\n  /** The per-purpose prompt payload the `MessageLoader` consumes. Opaque to the knob. */\n  readonly payload: unknown;\n}\n\n/** The parsed, typed success carried on the `resilient_ok` settle Msg, tagged with its purpose. */\nexport interface LlmOk<P extends string, O extends Record<P, unknown>> {\n  readonly key: string;\n  readonly purpose: P;\n  readonly output: O[P];\n}\n\n/** The typed failure variant — every failure path surfaces this, tagged by purpose. */\nexport interface LlmErr<P extends string> {\n  readonly key: string;\n  readonly purpose: P;\n  /** A human-readable cause (model throw, retry-exhaustion, or schema parse). */\n  readonly reason: string;\n  /** The original error, carried untouched for the consumer to inspect. */\n  readonly error: unknown;\n}\n\n/**\n * The settle Msgs llm-call's handler RETURNS from `interpret` so the substrate\n * enqueues them as follow-up Msgs (re-entry) into the host reducer — exactly as\n * `../resilient-call` does. They are the resilient-call settle Msgs with the\n * payloads ENRICHED to llm-call's typed variants: `result` is the parsed,\n * purpose-tagged `LlmOk`; `error` is the typed `LlmErr` (purpose + reason +\n * raw). The host wires `resilient_ok` → `succeed` and `resilient_err` → `fail`\n * reducer arms (the doc-comment wiring), and folds the enriched payload into its\n * own state there — llm-call never forces a Msg vocabulary on the host, and the\n * settle Msg drives the inherited succeed/fail → backoff → onTimer loop instead\n * of bypassing it.\n */\n//\n// The success Msg is `../resilient-call`'s `SucceedMsg` specialized to the parsed\n// `LlmOk` result — NOT a re-declared shape — so the verb returns (`succeed`'s\n// argument, the handler's resolve) thread through with no cast. The failure Msg\n// is the resilient `FailMsg` with its `error: unknown` NARROWED to the typed\n// `LlmErr`: every value the handler enriches is an `LlmErr`, and `LlmErr` is\n// assignable to `unknown`, so `LlmFailMsg` flows into `rc.fail` (which takes the\n// wide `FailMsg`) directly while the host reducer reads the narrow `error` type.\nexport type LlmSucceedMsg<\n  P extends string,\n  O extends Record<P, unknown>,\n> = SucceedMsg<LlmOk<P, O>>;\nexport type LlmFailMsg<P extends string> = Omit<FailMsg, \"error\"> & {\n  readonly error: LlmErr<P>;\n};\n\n/** The retry / deadline timer Msg — `DeadlineExceeded`, inherited from resilient-call. */\nexport type LlmTimerMsg = DeadlineExceeded;\n\n/**\n * The ports the LEGACY detached `handlers(ports)` form takes. Two outbound Msg\n * builders the handler hands the typed Ok / Err; the consumer returns its own\n * Msg (or `undefined`). KEPT only for `../agent`, which still inherits the\n * detached shape; that path does NOT drive the retry loop (it dispatches the\n * consumer's Msg directly and never re-enters the resilient settle Msg). New\n * consumers use the no-arg `handlers()` form, which RETURNS the settle Msg for\n * re-entry and drives the inherited succeed/fail → backoff → onTimer loop.\n * `../agent` carries the same retry-loop gap and is fixed separately.\n *\n * The builders return `M | undefined` — `undefined` is the \"dispatch nothing\"\n * sentinel the detached form checks (`!== undefined`), spelled as `undefined`\n * rather than `void` so the union is unambiguous (a `void` member of a union is\n * confusing and reads as \"may return anything\").\n */\nexport interface LlmCallPorts<\n  P extends string,\n  O extends Record<P, unknown>,\n  M,\n> {\n  /** Build the Msg dispatched on a parsed success. Return `undefined` to dispatch nothing. */\n  readonly onOk: (ok: LlmOk<P, O>) => M | undefined;\n  /** Build the Msg dispatched on any failure (throw / retry-exhausted / parse). */\n  readonly onErr: (err: LlmErr<P>) => M | undefined;\n}\n\n/**\n * The effect Cmd the knob emits: run the LLM call for `key` with `input`. The\n * `input` is the plain `LlmCall` request — the handler reads `purpose` /\n * `model` / `payload` off it (invariant 3: Cmds are data).\n *\n * It is `../resilient-call`'s `RunCmd` specialized to the `LlmCall` input — NOT a\n * re-declared shape — so the resilient verbs' return tuples (`[State, RunCmd[]]`)\n * are this exact type and thread through `attempt` / `succeed` / `fail` /\n * `onTimer` with no cast.\n */\nexport type LlmRunCmd<P extends string> = RunCmd<LlmCall<P>>;\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build an llm-call knob from `config`. `rng` is injected for the inherited\n * retry jitter (pass a fixed `() => 0.5` in tests to pin backoff; defaults to\n * `Math.random`, read only at the resilient-call verb boundary).\n *\n * Returns the uniform L2 knob contract. The slice + verbs (`init`, `attempt`,\n * `succeed`, `fail`, `onTimer`, `subs`) are DELEGATED to a `../resilient-call`\n * knob built over the structured-output model-invoke port — no second backoff\n * here. `handlers` is the one new piece: the purpose-branching, schema-parsing\n * wrapper that returns the enriched resilient settle Msg for re-entry.\n *\n * `P` is the purpose union, `O` the purpose→output map, `Msg` the model's\n * message shape.\n */\nexport function createLlmCall<\n  P extends string,\n  O extends Record<P, unknown>,\n  Msg = unknown,\n>(config: LlmCallConfig<P, O, Msg>, rng: () => number = Math.random) {\n  // ---- The composed resilient-call knob ----------------------------------\n  //\n  // The resilient-call input is the full `LlmCall` request; its result is the\n  // PARSED, typed `LlmOk`. Only the `retry` brick is forwarded — llm-call does\n  // not expose circuit / rate-limit / cache / deadline knobs (a stage call is\n  // a single brain invocation, not a keyed downstream target). Omitting those\n  // bricks omits their gates, exactly as resilient-call documents.\n  const resilientConfig: ResilientConfig = {\n    ...(config.retry === undefined ? {} : { retry: config.retry }),\n  };\n  const rc = createResilientCall<LlmCall<P>, LlmOk<P, O>>(resilientConfig, rng);\n\n  /** The slice this knob owns — resilient-call's slice verbatim. */\n  type State = ResilientState<LlmCall<P>, LlmOk<P, O>>;\n\n  /** The starting slice — resilient-call's. */\n  function init(): State {\n    return rc.init();\n  }\n\n  /**\n   * Start (or restart) an LLM call. `keyOrPurpose` defaults the resilient-call\n   * `key` to the call's `purpose` so one in-flight call per stage is tracked\n   * under the slice (the common shape); pass a distinct key to fan out. PURE —\n   * delegates straight to resilient-call's gate.\n   */\n  function attempt(\n    s: State,\n    input: LlmCall<P>,\n    at: number,\n    key: string = input.purpose,\n  ): readonly [State, readonly LlmRunCmd<P>[]] {\n    return rc.attempt(s, key, input, at);\n  }\n\n  /** Record a parsed success for `key`. PURE — resilient-call's `succeed`. */\n  function succeed(\n    s: State,\n    key: string,\n    msg: LlmSucceedMsg<P, O>,\n  ): readonly [State, readonly LlmRunCmd<P>[]] {\n    return rc.succeed(s, key, msg);\n  }\n\n  /**\n   * Record a failure for `key`: back off via the inherited retry, or settle\n   * `failed`. PURE — resilient-call's `fail`. The `error` is the typed\n   * `LlmErr`, carried on the call's `failed` phase for the consumer to read.\n   */\n  function fail(\n    s: State,\n    key: string,\n    msg: LlmFailMsg<P>,\n  ): readonly [State, readonly LlmRunCmd<P>[]] {\n    return rc.fail(s, key, msg);\n  }\n\n  /** A retry / deadline timer fired. PURE — resilient-call's `onTimer`. */\n  function onTimer(\n    s: State,\n    msg: LlmTimerMsg,\n  ): readonly [State, readonly LlmRunCmd<P>[]] {\n    return rc.onTimer(s, msg);\n  }\n\n  /** Pre-wired subs — resilient-call's retry-timer subscriptions. */\n  function subs(s: State): readonly DeadlineSub[] {\n    return rc.subs(s);\n  }\n\n  // ---- The model-invoke port the resilient handler drives ----------------\n\n  /**\n   * Run ONE LLM call: assemble messages via the loader, bind the purpose's\n   * structured-output schema, invoke, and parse. Returns the typed `LlmOk` on\n   * success; throws on any failure (model throw OR schema parse) so the\n   * resilient-call handler routes it to a failure Msg + backoff. This is the\n   * single port resilient-call wraps — the retry / timeout machinery lives in\n   * resilient-call, never here (\"do NOT reinvent backoff\").\n   *\n   * The seed's two paths collapse to one: every brain-only purpose goes through\n   * `withStructuredOutput(schema)`. The `parse` re-validates the output (a fake\n   * model might skip validation, and a real provider can drift) so a malformed\n   * structured response is a failure, not a corrupt success.\n   */\n  async function invokeOne(input: LlmCall<P>): Promise<LlmOk<P, O>> {\n    const model = config.model(input.model);\n    const messages = config.loadMessages\n      ? await config.loadMessages(input)\n      : [];\n    const schema = config.schemas[input.purpose];\n    const structured = model.withStructuredOutput(schema);\n    const raw = await structured.invoke(messages);\n    // Re-validate at the boundary — a parse throw becomes a `resilient_err`\n    // (enriched to `LlmErr`) settle Msg upstream, never a corrupt success.\n    const output = schema.parse(raw);\n    return { key: input.purpose, purpose: input.purpose, output };\n  }\n\n  // ---- Handlers — the one new piece, composed onto resilient-call --------\n\n  /**\n   * Pre-wired interpret handler for `resilient_run`. Composes\n   * `../resilient-call`'s `resilient_run` handler over the `invokeOne` port and\n   * RETURNS the resilient settle Msg — it does NOT dispatch the consumer's Msg\n   * itself. Returning the settle Msg is the whole point: the substrate enqueues\n   * an interpret handler's returned Msg as a FOLLOW-UP (re-entry) onto the\n   * dispatch tail, so the host reducer's `resilient_ok` / `resilient_err` arms\n   * run `succeed` / `fail`, which advances the inherited retry loop\n   * (succeed/fail → backoff → onTimer → re-issue). A handler that instead\n   * `dispatch`ed an enriched Msg directly would settle ONE invoke and bypass\n   * that loop entirely — the slice would never leave `running`, the breaker\n   * would never trip/close, and the retry counter would never reset.\n   *\n   * Resilience is composed, not reimplemented: the body delegates to the\n   * resilient-call handler's Railway-routed invoke (Ok → `resilient_ok`, Err →\n   * `resilient_err`), so a transient model failure backs off via the inherited\n   * retry exactly as resilient-call decides. The ONE enrichment llm-call adds is\n   * mapping the settle PAYLOADS into its typed variants:\n   *\n   *   - success → `result` is already the parsed `LlmOk` (`invokeOne` returns\n   *     it), so the resilient `resilient_ok` Msg is the llm-call `LlmSucceedMsg`\n   *     as-is.\n   *   - failure → the resilient `resilient_err` carries the RAW throw (a model\n   *     503 or a `schema.parse` throw). We rebuild it into the typed `LlmErr`\n   *     (purpose + reason + raw) so the host reducer routes per-stage.\n   *\n   * The host folds the enriched payload into its own state in the reducer arm\n   * (the doc-comment wiring), NOT here — the handler stays the one impurity\n   * (the `invokeOne` await + the `Date.now()` stamp the resilient handler makes)\n   * and the reducer stays pure.\n   */\n  // The resilient-call `resilient_run` handler over `invokeOne` — the shared\n  // Railway-routed invoke (Ok → resilient_ok Msg, Err → resilient_err Msg). Both\n  // handler forms below build on it; the settle shape is composed, not reinvented.\n  const resilientRunHandler = rc.handlers({\n    run: (input) => invokeOne(input),\n  }).resilient_run;\n\n  /**\n   * Await one composed invoke and resolve to the ENRICHED resilient settle Msg\n   * (`resilient_ok` carrying the parsed `LlmOk`, or `resilient_err` carrying the\n   * typed `LlmErr`). The shared core both handler forms reuse.\n   */\n  async function settleOf(\n    cmd: LlmRunCmd<P>,\n  ): Promise<LlmSucceedMsg<P, O> | LlmFailMsg<P>> {\n    // `resilientRunHandler` never rejects (tryInterpret contract) — it resolves\n    // to a `resilient_ok` / `resilient_err` settle Msg stamped with `Date.now()`.\n    // Its `ctx` slot is `NoCtx` (the resilient-call work fn reads no ctx — a\n    // DELIBERATE context-free seam, not accidental `unknown`), so the empty\n    // record satisfies it without a cast.\n    const settle = await resilientRunHandler(cmd, {});\n    if (settle.type === MsgType.ResilientOk) {\n      // `result` is the parsed `LlmOk` from `invokeOne`, and the narrowed\n      // `SucceedMsg<LlmOk>` IS `LlmSucceedMsg` — returned as-is, no cast.\n      return settle;\n    }\n    // resilient_err — enrich the raw throw into the typed `LlmErr`, keeping the\n    // resilient Msg's `key` / `at` so the host reducer's `fail` verb re-issues\n    // from the remembered input and backs off on schedule.\n    const rawError: unknown = settle.error;\n    const err: LlmErr<P> = {\n      key: cmd.key,\n      purpose: cmd.input.purpose,\n      reason: rawError instanceof Error ? rawError.message : String(rawError),\n      error: rawError,\n    };\n    return {\n      type: MsgType.ResilientErr,\n      key: settle.key,\n      error: err,\n      at: settle.at,\n    };\n  }\n\n  /**\n   * Pre-wired interpret handler for `resilient_run`. TWO forms:\n   *\n   *   - `handlers()` (no args, the FIXED primary) — RETURNS the enriched\n   *     resilient settle Msg. The substrate enqueues an interpret handler's\n   *     returned Msg as a FOLLOW-UP (re-entry) onto the dispatch tail, so the\n   *     host reducer's `resilient_ok` / `resilient_err` arms run `succeed` /\n   *     `fail`, advancing the inherited retry loop (succeed/fail → backoff →\n   *     onTimer → re-issue). This is the correct wiring; the module doc shows it.\n   *\n   *   - `handlers(ports)` (LEGACY, detached) — runs the invoke inside\n   *     `ctx.waitUntil` and dispatches the consumer's `onOk` / `onErr` Msg\n   *     directly. KEPT only for `../agent`, which still inherits this shape. It\n   *     does NOT drive the retry loop (it never re-enters the settle Msg, so\n   *     `succeed` / `fail` never run) — `../agent` carries the same gap and is\n   *     fixed in its own pass. New consumers MUST use the no-arg form.\n   *\n   * Resilience is composed, not reimplemented: both forms delegate to the\n   * resilient-call handler's Railway-routed invoke and add only the typed\n   * `LlmOk` / `LlmErr` enrichment. The ONE impurity is the `invokeOne` await +\n   * the `Date.now()` stamp the resilient handler makes; the reducer stays pure.\n   */\n  function handlers(): {\n    resilient_run: (\n      cmd: LlmRunCmd<P>,\n    ) => Promise<LlmSucceedMsg<P, O> | LlmFailMsg<P>>;\n  };\n  function handlers<M>(ports: LlmCallPorts<P, O, M>): {\n    resilient_run: (\n      cmd: LlmRunCmd<P>,\n      ctx: { waitUntil(p: Promise<unknown>): void; dispatch(msg: M): unknown },\n    ) => void;\n  };\n  function handlers<M>(ports?: LlmCallPorts<P, O, M>) {\n    if (ports === undefined) {\n      // FIXED primary: return the settle Msg for re-entry — drives the loop.\n      return { resilient_run: (cmd: LlmRunCmd<P>) => settleOf(cmd) };\n    }\n    // LEGACY detached form — kept for `../agent` (see doc above). Dispatches the\n    // consumer's Msg directly; does not re-enter the settle Msg.\n    return {\n      resilient_run: (\n        cmd: LlmRunCmd<P>,\n        ctx: {\n          waitUntil(p: Promise<unknown>): void;\n          dispatch(msg: M): unknown;\n        },\n      ): void => {\n        const fired = (async () => {\n          const settle = await settleOf(cmd);\n          if (settle.type === MsgType.ResilientOk) {\n            const msg = ports.onOk(settle.result);\n            if (msg !== undefined) await ctx.dispatch(msg);\n            return;\n          }\n          const msg = ports.onErr(settle.error);\n          if (msg !== undefined) await ctx.dispatch(msg);\n        })();\n        ctx.waitUntil(fired);\n      },\n    };\n  }\n\n  return { init, attempt, succeed, fail, onTimer, subs, handlers, invokeOne };\n}\n\n/**\n * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the\n * slice lives at `state.resilience` — the same convenience `../resilient-call`\n * ships, re-typed for the llm-call slice so consumers wire one import. Pure.\n */\nexport function liftLlmCall<\n  S extends { resilience: ResilientState<LlmCall<P>, LlmOk<P, O>> },\n  P extends string,\n  O extends Record<P, unknown>,\n  C extends Cmd,\n>(\n  state: S,\n  result: readonly [ResilientState<LlmCall<P>, LlmOk<P, O>>, readonly C[]],\n): readonly [S, readonly C[]] {\n  return liftResilience(state, result);\n}\n\n/**\n * Re-export the deadline Sub primitives (inherited from resilient-call) so\n * consumers wire one import: `subscribeDeadline` is the `subscribe` cell,\n * `deadlineSub` builds the Sub literal `subs` emits.\n */\nexport { subscribeDeadline, deadlineSub };\nexport type { DeadlineSub, DeadlineExceeded, ResilientState };\n"]}

package/dist/chunk-NSDFA6M6.js

@@ -1,198 +0,0 @@
-// src/subs/from-broadcast-channel.ts
-function fromBroadcastChannel(msgFn) {
-  return (sub, _ctx, dispatch) => {
-    const channel = new BroadcastChannel(sub.channelName);
-    const listener = (event) => {
-      const msg = msgFn(event, sub);
-      if (msg !== null) dispatch(msg);
-    };
-    channel.addEventListener("message", listener);
-    return () => {
-      channel.removeEventListener("message", listener);
-      channel.close();
-    };
-  };
-}
-
-// src/subs/from-event-source.ts
-function fromEventSource(opts) {
-  return (sub, _ctx, dispatch) => {
-    const source = new EventSource(sub.url);
-    const messageListener = (event) => {
-      const msg = opts.onMessage(event.data, sub);
-      if (msg !== null) dispatch(msg);
-    };
-    source.addEventListener("message", messageListener);
-    const onError = opts.onError;
-    const errorListener = onError ? (event) => {
-      const msg = onError(event, sub);
-      if (msg !== null) dispatch(msg);
-    } : void 0;
-    if (errorListener) source.addEventListener("error", errorListener);
-    const onOpen = opts.onOpen;
-    const openListener = onOpen ? () => {
-      const msg = onOpen(sub);
-      if (msg !== null) dispatch(msg);
-    } : void 0;
-    if (openListener) source.addEventListener("open", openListener);
-    return () => {
-      source.removeEventListener("message", messageListener);
-      if (errorListener) source.removeEventListener("error", errorListener);
-      if (openListener) source.removeEventListener("open", openListener);
-      source.close();
-    };
-  };
-}
-
-// src/subs/from-event-target.ts
-function fromEventTarget(getTarget, eventName, msgFn) {
-  return (sub, _ctx, dispatch) => {
-    const target = getTarget();
-    const listener = (event) => {
-      const msg = msgFn(event, sub);
-      if (msg !== null) dispatch(msg);
-    };
-    target.addEventListener(eventName, listener);
-    return () => {
-      target.removeEventListener(eventName, listener);
-    };
-  };
-}
-
-// src/subs/from-interval.ts
-function fromInterval(msgFn) {
-  return (sub, _ctx, dispatch) => {
-    const handle = setInterval(() => {
-      dispatch(msgFn(sub));
-    }, sub.intervalMs);
-    return () => {
-      clearInterval(handle);
-    };
-  };
-}
-
-// src/subs/from-port.ts
-function fromPort(selectRuntime, port, msgFn) {
-  return (sub, ctx, dispatch) => {
-    const runtime = selectRuntime(ctx);
-    return runtime.subscribePort(port, (value) => {
-      const msg = msgFn(value, sub);
-      if (msg !== null) dispatch(msg);
-    });
-  };
-}
-
-// src/subs/from-reconnecting-web-socket.ts
-var defaultConnect = (url) => new WebSocket(url);
-var defaultSchedule = (fn, ms) => {
-  const handle = setTimeout(fn, ms);
-  return () => clearTimeout(handle);
-};
-function fromReconnectingWebSocket(opts) {
-  const backoffBaseMs = opts.backoffBaseMs ?? 250;
-  const backoffMaxMs = opts.backoffMaxMs ?? 5e3;
-  const connect = opts.connect ?? defaultConnect;
-  const schedule = opts.schedule ?? defaultSchedule;
-  const { onMessage, onOpen, onError, onClose, onReconnect } = opts;
-  return (sub, _ctx, dispatch) => {
-    let ws = null;
-    let attempt = 0;
-    let opened = false;
-    let closedByCaller = false;
-    let cancelReconnect = null;
-    const emit = (msg) => {
-      if (msg !== null) dispatch(msg);
-    };
-    const handleClose = (code, reason) => {
-      ws = null;
-      if (onClose) emit(onClose(code, reason, sub));
-      if (closedByCaller) return;
-      const delay = Math.min(backoffBaseMs * 2 ** attempt, backoffMaxMs);
-      attempt += 1;
-      cancelReconnect = schedule(() => {
-        cancelReconnect = null;
-        if (!closedByCaller) open();
-      }, delay);
-    };
-    function open() {
-      const socket = connect(sub.wsUrl);
-      ws = socket;
-      socket.onopen = () => {
-        const reconnected = opened;
-        const reconnectCount = attempt;
-        attempt = 0;
-        opened = true;
-        if (onOpen) emit(onOpen(sub));
-        if (reconnected && onReconnect) emit(onReconnect(reconnectCount, sub));
-      };
-      socket.onmessage = (event) => {
-        emit(onMessage(event.data, sub));
-      };
-      socket.onerror = onError ? (event) => emit(onError(event, sub)) : () => {
-      };
-      socket.onclose = (event) => {
-        handleClose(event.code, event.reason);
-      };
-    }
-    open();
-    return () => {
-      closedByCaller = true;
-      if (cancelReconnect !== null) {
-        cancelReconnect();
-        cancelReconnect = null;
-      }
-      const socket = ws;
-      ws = null;
-      if (socket !== null) {
-        socket.onopen = null;
-        socket.onmessage = null;
-        socket.onerror = null;
-        socket.onclose = null;
-        socket.close(1e3);
-      }
-    };
-  };
-}
-
-// src/subs/from-web-socket.ts
-function fromWebSocket(opts) {
-  return (sub, _ctx, dispatch) => {
-    const ws = new WebSocket(sub.wsUrl);
-    ws.onmessage = (event) => {
-      const msg = opts.onMessage(event.data, sub);
-      if (msg !== null) dispatch(msg);
-    };
-    const onOpen = opts.onOpen;
-    if (onOpen) {
-      ws.onopen = () => {
-        const msg = onOpen(sub);
-        if (msg !== null) dispatch(msg);
-      };
-    }
-    const onError = opts.onError;
-    if (onError) {
-      ws.onerror = (event) => {
-        const msg = onError(event, sub);
-        if (msg !== null) dispatch(msg);
-      };
-    }
-    const onClose = opts.onClose;
-    if (onClose) {
-      ws.onclose = (event) => {
-        const msg = onClose(event.code, event.reason, sub);
-        if (msg !== null) dispatch(msg);
-      };
-    }
-    return () => {
-      ws.onmessage = null;
-      ws.onopen = null;
-      ws.onerror = null;
-      ws.onclose = null;
-      ws.close(1e3);
-    };
-  };
-}
-
-export { fromBroadcastChannel, fromEventSource, fromEventTarget, fromInterval, fromPort, fromReconnectingWebSocket, fromWebSocket };
-//# sourceMappingURL=chunk-NSDFA6M6.js.map
-//# sourceMappingURL=chunk-NSDFA6M6.js.map

package/dist/chunk-NSDFA6M6.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/subs/from-broadcast-channel.ts","../src/subs/from-event-source.ts","../src/subs/from-event-target.ts","../src/subs/from-interval.ts","../src/subs/from-port.ts","../src/subs/from-reconnecting-web-socket.ts","../src/subs/from-web-socket.ts"],"names":[],"mappings":"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","file":"chunk-NSDFA6M6.js","sourcesContent":["// ---------------------------------------------------------------------------\n// fromBroadcastChannel — universal `BroadcastChannel`-shaped Sub factory.\n//\n// `BroadcastChannel` is a same-origin pub/sub primitive available in\n// every modern browser context (window, worker, service worker) AND in\n// Cloudflare Workers (with origin scoped to the worker isolate). The\n// constructor opens the channel; the `message` event fires whenever\n// another participant on the same channel name posts a message; the\n// `close()` method releases the OS resource.\n//\n// The factory carries `channelName` on the Sub itself (not in the\n// closure) so the same factory instance handles every BroadcastChannel\n// Sub in a machine — one Sub per channel, named by id, sharing the\n// factory's lifecycle code. Renaming a channel requires a new Sub.id\n// (the reconcile pass otherwise leaves the existing channel open).\n//\n// `msgFn` returns `M | null` — same drop-on-null pattern as\n// `fromEventTarget`. The MessageEvent's `data` is `unknown` from the\n// platform's perspective; the caller decides whether the payload is a\n// recognizable shape, and returns `null` to drop unknown messages\n// without polluting the reducer with parse-discard cells.\n//\n// Cleanup calls `channel.close()`, which removes the listener AND\n// releases the channel reference — `removeEventListener` alone would\n// leak the BroadcastChannel handle. The pair is intentional.\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../index\";\nimport type {\n  MinimalBroadcastChannelCtor,\n  MinimalMessageEvent,\n} from \"./platform\";\nimport type { SubscribeHandler } from \"./types\";\n\ntype BroadcastSubData = { channelName: string };\n\ndeclare const BroadcastChannel: MinimalBroadcastChannelCtor;\n\nexport function fromBroadcastChannel<S extends Sub & BroadcastSubData, M>(\n  msgFn: (event: MinimalMessageEvent, sub: S) => M | null,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const channel = new BroadcastChannel(sub.channelName);\n    const listener = (event: MinimalMessageEvent): void => {\n      const msg = msgFn(event, sub);\n      if (msg !== null) dispatch(msg);\n    };\n    channel.addEventListener(\"message\", listener);\n    return () => {\n      channel.removeEventListener(\"message\", listener);\n      channel.close();\n    };\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromEventSource — universal `EventSource` (server-sent events) Sub\n// factory.\n//\n// SSE is the asymmetric streaming protocol used by the agent log /\n// audit log pipelines: HTTP-shaped open, server pushes events forever,\n// client receives until close. `EventSource` is the standard browser\n// API; the constructor opens the connection, `message` fires per\n// server-pushed event, `error` fires on disconnect or non-2xx, `open`\n// fires once on initial handshake, `close()` tears the connection\n// down.\n//\n// Three callbacks because three observable events ARE three concerns\n// the caller routinely cares about:\n//\n//   - `onMessage(data, sub)` — required. The SSE payload's `data` field\n//     is `string` from the platform; the caller decides parse + Msg\n//     shape. Returns `M | null`; null drops the dispatch.\n//\n//   - `onError(event, sub)` — optional. SSE's `error` event fires both\n//     on transient network drops (the browser auto-reconnects) AND on\n//     permanent failures. Most consumers want to surface ONE of these\n//     as a Msg (e.g. \"stream-disconnected\") without folding both into\n//     `onMessage`'s discriminant. Omitting the callback drops error\n//     events silently.\n//\n//   - `onOpen(sub)` — optional. The connection's initial handshake\n//     succeeded. Useful for \"show 'connected' indicator\" Msgs. Omitting\n//     drops open events silently. NOT fired on auto-reconnect by every\n//     browser implementation — treat the event as best-effort.\n//\n// `url` lives on the Sub itself (`EventSourceSubData`). Same id +\n// different url = the substrate's reconcile pass leaves the existing\n// connection alone (the URL change is silent). Changing the URL\n// requires a new Sub.id.\n//\n// Cleanup is `close()` + `removeEventListener` for all three —\n// belt-and-suspenders against EventSource implementations that\n// dispatch events into already-closed sources.\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../index\";\nimport type {\n  MinimalEvent,\n  MinimalEventSourceCtor,\n  MinimalMessageEvent,\n} from \"./platform\";\nimport type { SubscribeHandler } from \"./types\";\n\ntype EventSourceSubData = { url: string };\n\ndeclare const EventSource: MinimalEventSourceCtor;\n\nexport interface EventSourceFactoryOpts<S, M> {\n  onMessage: (data: string, sub: S) => M | null;\n  onError?: (event: MinimalEvent, sub: S) => M | null;\n  onOpen?: (sub: S) => M | null;\n}\n\nexport function fromEventSource<S extends Sub & EventSourceSubData, M>(\n  opts: EventSourceFactoryOpts<S, M>,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const source = new EventSource(sub.url);\n\n    const messageListener = (event: MinimalMessageEvent): void => {\n      // The SSE `data` payload is a string per the platform contract.\n      // Cast at the boundary: callers express `(data: string) => M | null`\n      // and never see `unknown` flowing in from the platform global.\n      const msg = opts.onMessage(event.data as string, sub);\n      if (msg !== null) dispatch(msg);\n    };\n    source.addEventListener(\"message\", messageListener);\n\n    const onError = opts.onError;\n    const errorListener = onError\n      ? (event: MinimalEvent): void => {\n          const msg = onError(event, sub);\n          if (msg !== null) dispatch(msg);\n        }\n      : undefined;\n    if (errorListener) source.addEventListener(\"error\", errorListener);\n\n    const onOpen = opts.onOpen;\n    const openListener = onOpen\n      ? (): void => {\n          const msg = onOpen(sub);\n          if (msg !== null) dispatch(msg);\n        }\n      : undefined;\n    if (openListener) source.addEventListener(\"open\", openListener);\n\n    return () => {\n      source.removeEventListener(\"message\", messageListener);\n      if (errorListener) source.removeEventListener(\"error\", errorListener);\n      if (openListener) source.removeEventListener(\"open\", openListener);\n      source.close();\n    };\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromEventTarget — universal addEventListener/removeEventListener Sub\n// factory over any `EventTarget` (DOM nodes, `window`, `document`,\n// `BroadcastChannel`, `MessagePort`, `Worker`, `ServiceWorker`, etc.).\n//\n// Two non-obvious shape choices:\n//\n//   - `getTarget: () => EventTarget` is a thunk, not a direct value. The\n//     factory MUST work in environments where the target is not available\n//     at module-load time — service workers run before any `document`\n//     exists; some targets are constructed lazily from `ctx`. Deferring\n//     the lookup to subscribe time also means a state-driven swap of the\n//     target requires only a new Sub.id; the factory pulls the current\n//     target on subscribe.\n//\n//   - `msgFn` may return `null` — that emission is *dropped*. The event\n//     fired, the factory called `msgFn`, but the caller decided \"this\n//     event is not interesting given current state.\" No dispatch is made;\n//     the listener stays armed for the next event. This is the explicit\n//     filter point at the Sub boundary — the alternative (filtering inside\n//     the reducer via a noop cell) costs a transition + reconcile pass per\n//     filtered event.\n//\n// Cleanup uses the SAME `getTarget()` instance captured at subscribe time\n// so a target swap mid-Sub doesn't leak the listener on the old target.\n// We close over the resolved target rather than calling `getTarget()`\n// again at cleanup — the alternative (re-resolving) is the cause of\n// silent listener leaks in long-lived runtimes.\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../index\";\nimport type { MinimalEvent, MinimalEventTarget } from \"./platform\";\nimport type { SubscribeHandler } from \"./types\";\n\nexport function fromEventTarget<S extends Sub, M>(\n  getTarget: () => MinimalEventTarget,\n  eventName: string,\n  msgFn: (event: MinimalEvent, sub: S) => M | null,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const target = getTarget();\n    const listener = (event: MinimalEvent): void => {\n      const msg = msgFn(event, sub);\n      if (msg !== null) dispatch(msg);\n    };\n    target.addEventListener(eventName, listener);\n    return () => {\n      target.removeEventListener(eventName, listener);\n    };\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromInterval — universal `setInterval`-shaped Sub factory.\n//\n// The recurring shape at every `subscribe[type]` cell that wraps a periodic\n// timer is the same five lines: `setInterval` the dispatch, return a\n// `clearInterval` cleanup. The factory absorbs both halves of the lifecycle\n// (subscribe + cleanup); the caller keeps the intent — which Sub variant,\n// which Msg to dispatch.\n//\n// Timing data (`intervalMs`) lives on the Sub itself, not in the closure.\n// The substrate already reconciles Subs by id on every transition; carrying\n// the period on the Sub means a `subscriptions(state)` function that\n// returns `{ id, type, intervalMs: 30_000 }` in one state and the same id\n// with `intervalMs: 60_000` later... will NOT re-wire the interval (the id\n// is unchanged, the reconcile pass leaves it running). That's a tradeoff\n// the substrate's reconcile contract pins, not this factory — if you want\n// the interval to change, change the Sub's id too.\n//\n// Strengthens invariant 9 (named, small surface) and invariant 2 (the Sub\n// carries the data; the lifecycle is in the factory; the reducer never\n// sees the timer).\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../index\";\nimport type { SubscribeHandler } from \"./types\";\n\ntype IntervalSubData = { intervalMs: number };\n\nexport function fromInterval<S extends Sub & IntervalSubData, M>(\n  msgFn: (sub: S) => M,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const handle = setInterval(() => {\n      dispatch(msgFn(sub));\n    }, sub.intervalMs);\n    return () => {\n      clearInterval(handle);\n    };\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromPort — universal `Runtime.subscribePort`-shaped Sub factory.\n//\n// The canonical cross-runtime coordination pattern in @demlik/tea: one\n// runtime emits to a typed Port; another runtime's machine declares an\n// `audit-idle`-shaped Sub whose subscribe handler attaches to the\n// publisher's Port. The recurring 4-line shape at every such cell:\n//\n//   \"audit-idle\": (_sub, ctx, dispatch) =>\n//     ctx.auditRuntime.subscribePort(auditIdlePort, (value) => {\n//       dispatch(buildMsg(value));\n//     });\n//\n// The factory absorbs the cleanup-returning subscribePort call AND the\n// dispatch-on-emit wiring. The caller keeps the three pieces of intent:\n//\n//   1. `selectRuntime(ctx)` — which sibling Runtime publishes the Port.\n//      This is a selector (not a direct ctx.auditRuntime reference) so\n//      the factory does NOT pin the ctx shape — any machine whose ctx\n//      exposes some Runtime<...> reference is compatible by selecting it.\n//      A direct `Runtime` parameter would have made the factory shape\n//      depend on having that Runtime in scope at machine-definition\n//      time, which is a worse match for the \"ctx is the boundary\"\n//      contract this substrate already commits to.\n//\n//   2. `port: Port<T>` — the typed channel itself. Identity is by\n//      reference (the substrate enforces unique names at definePort\n//      time); pass the same `Port<T>` value the publisher emits to.\n//\n//   3. `msgFn(value, sub) => M | null` — the value-to-Msg mapping, with\n//      drop-on-null semantics matching every other factory in this\n//      subpath. The published value's type `T` flows through to `msgFn`'s\n//      first param so the caller never re-asserts the payload shape.\n//\n// Strengthens invariant 9 (the cross-runtime Port topology is named at\n// one factory site instead of redrawn at every subscribe cell).\n// ---------------------------------------------------------------------------\n\nimport type { Port, Runtime, Sub } from \"../index\";\nimport type { SubscribeHandler } from \"./types\";\n\n// `RS` / `RM` carry the sibling Runtime's concrete State and Msg through the\n// selector: a caller that selects a `Runtime<AuditState, AuditMsg>` keeps that\n// type at the seam instead of collapsing it to `Runtime<unknown, {type:string}>`.\n// They default to the prior broad pair so existing call sites that select a\n// less-specific Runtime still compile — the factory still only ever calls\n// `subscribePort`, so it does not read RS/RM, but the boundary no longer\n// hardcodes the widest type when the caller knows a narrower one.\nexport function fromPort<\n  S extends Sub,\n  M,\n  Ctx,\n  T,\n  RS = unknown,\n  RM extends { type: string } = { type: string },\n>(\n  selectRuntime: (ctx: Ctx) => Runtime<RS, RM>,\n  port: Port<T>,\n  msgFn: (value: T, sub: S) => M | null,\n): SubscribeHandler<S, M, Ctx> {\n  return (sub, ctx, dispatch) => {\n    const runtime = selectRuntime(ctx);\n    return runtime.subscribePort(port, (value) => {\n      const msg = msgFn(value, sub);\n      if (msg !== null) dispatch(msg);\n    });\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromReconnectingWebSocket — a `WebSocket` Sub factory that survives drops.\n//\n// `fromWebSocket` is the SSE-sibling ONE-SHOT factory: its cleanup `close()`s\n// the socket and it never re-opens on an unexpected drop (issue #188). That is\n// the right shape for a connection the caller manages, but any tea client over\n// an unreliable transport — games, presence, collab — needs the connection to\n// recover transparently, without a page reload. Rather than re-roll a backoff\n// loop in every consumer (vortex's `ReconnectingSocket` is the proven shape,\n// services/vortex/src/reconnecting-socket.ts), this is the reconnecting variant\n// folded into the substrate's Sub surface.\n//\n// The reconnect contract, mirroring vortex's wrapper:\n//\n//   - On an UNEXPECTED close (`onclose` the substrate didn't initiate) it\n//     re-opens after a CAPPED exponential backoff: `min(base * 2^attempt, max)`.\n//     A successful handshake resets `attempt` to 0, so the next drop retries\n//     fast again.\n//\n//   - A CALLER-INITIATED close (the Sub's cleanup, e.g. the machine\n//     transitioned the Sub away) suppresses reconnect: handlers are detached\n//     BEFORE `close(1000)` so the teardown can't fire `onClose` or schedule a\n//     reconnect. After cleanup the factory never re-opens.\n//\n//   - `connect` and `schedule` are INJECTABLE (defaulting to the global\n//     `WebSocket` and `setTimeout`/`clearTimeout`), the test seam that lets the\n//     reconnect/backoff behavior be unit-tested with a fake socket + a manual\n//     clock — no DOM, no real network, no timers — exactly as vortex's wrapper\n//     is tested.\n//\n// Callback contract (same `M | null` \"null drops the dispatch\" shape as\n// `fromWebSocket`, plus one reconnect-specific hook):\n//\n//   - `onMessage(data, sub)` — required. Raw `unknown` frame; the caller parses.\n//   - `onOpen(sub)` — optional. Fires on EVERY successful handshake — the first\n//     open AND every reconnect — so a \"connected\" indicator stays accurate.\n//   - `onError(event, sub)` — optional. The `error` event; `close` still drives\n//     the reconnect (one path), so this is purely a notification.\n//   - `onClose(code, reason, sub)` — optional. Fires on every close the\n//     substrate observes (a drop that will be retried, too) — NOT on the\n//     caller's own teardown, whose handlers are detached first.\n//   - `onReconnect(attempt, sub)` — optional. Fires when a RE-open (any open\n//     after the first) succeeds, carrying the 1-based reconnect count. This is\n//     the resync hook: the place to dispatch a \"re-fetch the authoritative\n//     snapshot, discard predicted state\" Msg after the transport recovered.\n//\n// Like `fromWebSocket`, `wsUrl` lives on the Sub (`WebSocketSubData`); every\n// reconnect reads `sub.wsUrl` afresh, so a reconcile that re-subscribes with a\n// new url reconnects to the new endpoint.\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../index\";\nimport type { WebSocketSubData } from \"./from-web-socket\";\nimport type {\n  MinimalEvent,\n  MinimalWebSocket,\n  MinimalWebSocketCtor,\n} from \"./platform\";\nimport type { SubscribeHandler } from \"./types\";\n\ndeclare const WebSocket: MinimalWebSocketCtor;\n\n/** Cancels a scheduled reconnect timer (the inverse of `schedule`). */\nexport type CancelTimer = () => void;\n\nexport interface ReconnectingWebSocketFactoryOpts<S, M> {\n  onMessage: (data: unknown, sub: S) => M | null;\n  onOpen?: (sub: S) => M | null;\n  onError?: (event: MinimalEvent, sub: S) => M | null;\n  onClose?: (code: number, reason: string, sub: S) => M | null;\n  /**\n   * Fires when a reconnection (any open after the first) succeeds, carrying the\n   * 1-based reconnect count — the resync hook. Omitting drops reconnect events\n   * silently.\n   */\n  onReconnect?: (attempt: number, sub: S) => M | null;\n  /** First backoff delay in ms (doubles each failed attempt). Default 250. */\n  backoffBaseMs?: number;\n  /** Backoff ceiling in ms. Default 5000. */\n  backoffMaxMs?: number;\n  /** Inject the socket constructor (defaults to the global `WebSocket`); the test seam. */\n  connect?: (url: string) => MinimalWebSocket;\n  /** Inject the timer (defaults to `setTimeout`/`clearTimeout`); the test seam. */\n  schedule?: (fn: () => void, ms: number) => CancelTimer;\n}\n\nconst defaultConnect = (url: string): MinimalWebSocket => new WebSocket(url);\n\nconst defaultSchedule = (fn: () => void, ms: number): CancelTimer => {\n  const handle = setTimeout(fn, ms);\n  return () => clearTimeout(handle);\n};\n\nexport function fromReconnectingWebSocket<S extends Sub & WebSocketSubData, M>(\n  opts: ReconnectingWebSocketFactoryOpts<S, M>,\n): SubscribeHandler<S, M, unknown> {\n  const backoffBaseMs = opts.backoffBaseMs ?? 250;\n  const backoffMaxMs = opts.backoffMaxMs ?? 5000;\n  const connect = opts.connect ?? defaultConnect;\n  const schedule = opts.schedule ?? defaultSchedule;\n\n  const { onMessage, onOpen, onError, onClose, onReconnect } = opts;\n\n  return (sub, _ctx, dispatch) => {\n    let ws: MinimalWebSocket | null = null;\n    let attempt = 0;\n    let opened = false;\n    let closedByCaller = false;\n    let cancelReconnect: CancelTimer | null = null;\n\n    const emit = (msg: M | null): void => {\n      if (msg !== null) dispatch(msg);\n    };\n\n    const handleClose = (code: number, reason: string): void => {\n      ws = null;\n      if (onClose) emit(onClose(code, reason, sub));\n      // A teardown the substrate initiated detaches handlers first, so this\n      // path only runs for an UNEXPECTED close — reconnect with capped backoff.\n      if (closedByCaller) return;\n      const delay = Math.min(backoffBaseMs * 2 ** attempt, backoffMaxMs);\n      attempt += 1;\n      cancelReconnect = schedule(() => {\n        cancelReconnect = null;\n        if (!closedByCaller) open();\n      }, delay);\n    };\n\n    function open(): void {\n      const socket = connect(sub.wsUrl);\n      ws = socket;\n\n      socket.onopen = (): void => {\n        // `opened` BEFORE this open marks it a reconnect; `attempt` is the\n        // pending count for the drop that triggered it (1-based once we reset).\n        const reconnected = opened;\n        const reconnectCount = attempt;\n        attempt = 0;\n        opened = true;\n        if (onOpen) emit(onOpen(sub));\n        if (reconnected && onReconnect) emit(onReconnect(reconnectCount, sub));\n      };\n\n      socket.onmessage = (event): void => {\n        emit(onMessage(event.data, sub));\n      };\n\n      // `error` precedes `close`; let `close` drive the reconnect so there is\n      // one path. The handler is still wired (as a no-op when the caller didn't\n      // supply `onError`) so a platform error event has a sink.\n      socket.onerror = onError\n        ? (event): void => emit(onError(event, sub))\n        : (): void => {};\n\n      socket.onclose = (event): void => {\n        handleClose(event.code, event.reason);\n      };\n    }\n\n    open();\n\n    return () => {\n      // Deliberate teardown: cancel any pending reconnect, detach handlers so\n      // the cleanup `close()` can't fire `onClose` or schedule a reconnect,\n      // then close the live socket. After this the factory never re-opens.\n      closedByCaller = true;\n      if (cancelReconnect !== null) {\n        cancelReconnect();\n        cancelReconnect = null;\n      }\n      const socket = ws;\n      ws = null;\n      if (socket !== null) {\n        socket.onopen = null;\n        socket.onmessage = null;\n        socket.onerror = null;\n        socket.onclose = null;\n        // 1000 = \"normal closure\" per RFC 6455 §7.4.1.\n        socket.close(1000);\n      }\n    };\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromWebSocket — universal `WebSocket` Sub factory. The symmetric sibling\n// of `fromEventSource`.\n//\n// WebSocket is the bidirectional streaming protocol used wherever the\n// server pushes events AND the client pushes commands on the same\n// connection. The constructor opens the connection, `onopen` fires once\n// on handshake, `onmessage` fires per server-pushed frame, `onerror`\n// fires on transient or permanent failure, `onclose` fires once on\n// teardown carrying `code` + `reason`. `close(code)` initiates a clean\n// shutdown from the client side.\n//\n// Four callbacks because four observable events ARE four concerns the\n// caller routinely cares about. The Sub's `wsUrl` lives on the Sub itself\n// (`WebSocketSubData`) — same id + different `wsUrl` is silent under the\n// reconcile pass, identical to `fromEventSource`'s `url` contract.\n//\n//   - `onMessage(data, sub)` — required. The platform delivers `data` as\n//     `string | Blob | ArrayBuffer` depending on `binaryType` and the\n//     server's frame type. The factory does NOT bake in a parse contract:\n//     the callback receives the raw `unknown` and decides parse + Msg\n//     shape. Returns `M | null`; null drops the dispatch.\n//\n//   - `onOpen(sub)` — optional. Connection handshake succeeded. Useful\n//     for \"show 'connected' indicator\" Msgs. Omitting drops open events\n//     silently.\n//\n//   - `onError(event, sub)` — optional. WebSocket's `error` event fires\n//     on transient drops AND permanent failures; like SSE, most consumers\n//     want one Msg (\"connection-errored\") without folding both into\n//     `onMessage`'s discriminant. Omitting drops error events silently.\n//\n//   - `onClose(code, reason, sub)` — optional. The connection is gone.\n//     `code` is the WebSocket close code (1000 = clean, 1006 = abnormal,\n//     etc.). `reason` is the server-supplied string (often empty).\n//     Omitting drops close events silently.\n//\n// Cleanup is `close(1000)` — the IANA-registered clean-shutdown code.\n// The factory intentionally does NOT bake in registry semantics (e.g.\n// the extension's `ctx.wsRegistry` so `interpret.send_ws` can reach the\n// live socket): that's consumer glue. A consumer that needs the live\n// socket for outbound sends wires it from inside the subscribe handler\n// or keeps a hand-written Sub alongside this factory.\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../index\";\nimport type {\n  MinimalCloseEvent,\n  MinimalEvent,\n  MinimalMessageEvent,\n  MinimalWebSocketCtor,\n} from \"./platform\";\nimport type { SubscribeHandler } from \"./types\";\n\nexport type WebSocketSubData = { wsUrl: string };\n\ndeclare const WebSocket: MinimalWebSocketCtor;\n\nexport interface WebSocketFactoryOpts<S, M> {\n  onMessage: (data: unknown, sub: S) => M | null;\n  onOpen?: (sub: S) => M | null;\n  onError?: (event: MinimalEvent, sub: S) => M | null;\n  onClose?: (code: number, reason: string, sub: S) => M | null;\n}\n\nexport function fromWebSocket<S extends Sub & WebSocketSubData, M>(\n  opts: WebSocketFactoryOpts<S, M>,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const ws = new WebSocket(sub.wsUrl);\n\n    ws.onmessage = (event: MinimalMessageEvent): void => {\n      // The platform delivers `data` as `unknown` — the factory hands it\n      // through untouched and the caller chooses the parse strategy.\n      const msg = opts.onMessage(event.data, sub);\n      if (msg !== null) dispatch(msg);\n    };\n\n    const onOpen = opts.onOpen;\n    if (onOpen) {\n      ws.onopen = (): void => {\n        const msg = onOpen(sub);\n        if (msg !== null) dispatch(msg);\n      };\n    }\n\n    const onError = opts.onError;\n    if (onError) {\n      ws.onerror = (event: MinimalEvent): void => {\n        const msg = onError(event, sub);\n        if (msg !== null) dispatch(msg);\n      };\n    }\n\n    const onClose = opts.onClose;\n    if (onClose) {\n      ws.onclose = (event: MinimalCloseEvent): void => {\n        const msg = onClose(event.code, event.reason, sub);\n        if (msg !== null) dispatch(msg);\n      };\n    }\n\n    return () => {\n      // Detach the lifecycle handlers BEFORE close() so the consumer's\n      // `onClose` Msg isn't fired from a teardown the substrate initiated.\n      // Mirrors fromEventSource's removeEventListener pass.\n      ws.onmessage = null;\n      ws.onopen = null;\n      ws.onerror = null;\n      ws.onclose = null;\n      // 1000 = \"normal closure\" per RFC 6455 §7.4.1.\n      ws.close(1000);\n    };\n  };\n}\n"]}

package/dist/chunk-SC3FAFZN.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/circuit-breaker/index.ts"],"names":[],"mappings":";AAwHO,IAAM,oBAAA,GAAsC;AAAA,EACjD,gBAAA,EAAkB,CAAA;AAAA,EAClB,UAAA,EAAY,GAAA;AAAA,EACZ,iBAAA,EAAmB;AACrB;AAoBO,SAAS,WAAA,GAA4B;AAC1C,EAAA,OAAO,EAAE,KAAA,EAAO,QAAA,EAAU,QAAA,EAAU,CAAA,EAAE;AACxC;AAYO,SAAS,SAAA,CACd,OACA,OAAA,EACc;AACd,EAAA,QAAQ,MAAM,KAAA;AAAO,IACnB,KAAK,QAAA;AAGH,MAAA,OAAO,KAAA,CAAM,aAAa,CAAA,GAAI,KAAA,GAAQ,EAAE,KAAA,EAAO,QAAA,EAAU,UAAU,CAAA,EAAE;AAAA,IACvE,KAAK,WAAA;AACH,MAAA,OAAO,EAAE,KAAA,EAAO,QAAA,EAAU,QAAA,EAAU,CAAA,EAAE;AAAA,IACxC,KAAK,MAAA;AACH,MAAA,OAAO,KAAA;AAAA;AAEb;AAgBO,SAAS,SAAA,CACd,KAAA,EACA,MAAA,EACA,KAAA,EACc;AACd,EAAA,QAAQ,MAAM,KAAA;AAAO,IACnB,KAAK,QAAA,EAAU;AACb,MAAA,MAAM,QAAA,GAAW,MAAM,QAAA,GAAW,CAAA;AAGlC,MAAA,OAAO,QAAA,IAAY,MAAA,CAAO,gBAAA,GACtB,EAAE,KAAA,EAAO,MAAA,EAAQ,UAAA,EAAY,KAAA,EAAM,GACnC,EAAE,KAAA,EAAO,QAAA,EAAU,QAAA,EAAS;AAAA,IAClC;AAAA,IACA,KAAK,WAAA;AAEH,MAAA,OAAO,EAAE,KAAA,EAAO,MAAA,EAAQ,UAAA,EAAY,KAAA,EAAM;AAAA,IAC5C,KAAK,MAAA;AACH,MAAA,OAAO,KAAA;AAAA;AAEb;AA0BO,SAAS,OAAA,CACd,KAAA,EACA,MAAA,EACA,KAAA,EACkC;AAClC,EAAA,QAAQ,MAAM,KAAA;AAAO,IACnB,KAAK,QAAA;AACH,MAAA,OAAO,CAAC,OAAO,IAAI,CAAA;AAAA,IACrB,KAAK,MAAA,EAAQ;AACX,MAAA,MAAM,OAAA,GAAU,QAAQ,KAAA,CAAM,UAAA;AAG9B,MAAA,IAAI,OAAA,IAAW,OAAO,UAAA,EAAY;AAChC,QAAA,OAAO,CAAC,EAAE,KAAA,EAAO,aAAa,MAAA,EAAQ,CAAA,IAAK,IAAI,CAAA;AAAA,MACjD;AACA,MAAA,OAAO,CAAC,OAAO,KAAK,CAAA;AAAA,IACtB;AAAA,IACA,KAAK,WAAA;AACH,MAAA,IAAI,KAAA,CAAM,MAAA,GAAS,MAAA,CAAO,iBAAA,EAAmB;AAC3C,QAAA,OAAO,CAAC,EAAE,KAAA,EAAO,WAAA,EAAa,QAAQ,KAAA,CAAM,MAAA,GAAS,CAAA,EAAE,EAAG,IAAI,CAAA;AAAA,MAChE;AACA,MAAA,OAAO,CAAC,OAAO,KAAK,CAAA;AAAA;AAE1B","file":"chunk-SC3FAFZN.js","sourcesContent":["/**\n * @demlik/tea/circuit-breaker — per-target failure tracking as pure state + ops.\n *\n * Same shape as `@demlik/tea/work-queue`'s `ops.ts`, `@demlik/tea/rate-limit`,\n * and `@demlik/tea/idempotency`: a state type plus pure transition functions.\n * Host-agnostic by construction — no `Date.now()`, no timers, no I/O. The\n * caller injects the clock (`nowMs`) and wires the result into its own reducer\n * / interpret. This keeps the breaker inside TEA's invariant 2 (transitions are\n * pure: same inputs → same outputs, no `Date.now`) so a consumer can fold it\n * through `update` and exercise it with `replay` / the pbt fold without a fake\n * clock.\n *\n * Every op returns a NEW state value and never mutates its input (invariant 1 —\n * state is a value, not a place). `canPass` returns a `[next, allowed]` tuple so\n * the caller branches on the decision while threading the advanced state forward\n * — same convention as `rate-limit`'s `tryConsume` / `record`. `onSuccess` /\n * `onFailure` are the outcome-recording transitions the caller folds in once the\n * guarded call resolves.\n *\n * ## The phase machine\n *\n * A circuit breaker guards a fallible downstream target (an HTTP backend, a DB,\n * a flaky tool call). Instead of hammering a target that is already failing, it\n * trips OPEN after enough failures and fast-fails subsequent calls for a\n * cooldown, then probes with a few trial calls before fully closing again.\n * Three phases, each carrying ONLY its own data so impossible states are\n * unrepresentable (pattern 11):\n *\n *   - **closed** — the healthy steady state. Calls pass through. Carries\n *     `failures`: the count of *consecutive* failures since the last success.\n *     A success resets it to 0; the `failureThreshold`-th failure trips the\n *     breaker OPEN. Only `closed` has a failure counter — `open` and\n *     `half_open` don't, because in those phases the count is irrelevant\n *     (the breaker has already tripped / is already probing).\n *\n *   - **open** — the tripped state. All calls fast-fail (no downstream load).\n *     Carries `openedAtMs`: the clock reading at which the breaker tripped.\n *     `canPass` compares `nowMs - openedAtMs` against `cooldownMs` to decide\n *     when to start probing. Only `open` carries a timestamp — neither other\n *     phase is timing anything.\n *\n *   - **half_open** — the probing state. A limited number of trial calls are\n *     allowed through to test whether the target has recovered. Carries\n *     `probes`: the count of probes admitted so far this probing round.\n *     `canPass` admits while `probes < halfOpenMaxProbes`, then fast-fails the\n *     rest (so a slow target can't be flooded by every queued caller at once).\n *     A probe success closes the breaker; a probe failure re-opens it (and\n *     resets the cooldown clock). Only `half_open` counts in-flight probes.\n *\n * ### Transition table\n *\n * Rows are the current phase; columns are the event. `→` denotes the next\n * phase; `self` means unchanged. `nowMs` is the injected clock.\n *\n * | from \\ event | onSuccess      | onFailure                              | canPass (→ allowed?)                                                                 |\n * | ------------ | -------------- | -------------------------------------- | ------------------------------------------------------------------------------------ |\n * | closed       | closed(0)      | failures+1; trip → open(nowMs) at thr. | self → true (always)                                                                  |\n * | open         | self *(¹)*     | self                                   | elapsed ≥ cooldown → half_open(1), true; else self → false                            |\n * | half_open    | → closed(0)    | → open(nowMs) (probe failed)           | probes < max → half_open(probes+1), true; else self → false                          |\n *\n * *(¹)* `onSuccess` on `open` \"shouldn't happen\": no call was admitted while\n * open, so no success can be reported for one. We leave the state unchanged\n * rather than throw — the breaker is a coordination aid, not a correctness\n * gate, and a spurious success report (e.g. a late-arriving result from before\n * the trip) must not silently un-trip the breaker. `onFailure` on `open` is\n * likewise a no-op: the breaker is already tripped; the `open` clock is anchored\n * at the trip, not bumped by late failures.\n *\n * ### The probe-admission asymmetry\n *\n * Entering `half_open` happens inside `canPass`, not `onSuccess` / `onFailure`,\n * because the cooldown is a *time* condition and only `canPass` reads the clock\n * against `openedAtMs`. The first `canPass` after the cooldown elapses both\n * transitions the phase AND admits the probe (`[half_open(1), true]`) — one\n * caller drives the recovery attempt. Subsequent `canPass` calls in the same\n * round admit up to `halfOpenMaxProbes` total, then fast-fail until a probe\n * resolves and `onSuccess` / `onFailure` moves the phase out of `half_open`.\n *\n * This module is a textbook three-state machine — a clean `/machine-viz` demo.\n *\n * NOT exported from the package root — reached via the\n * `@demlik/tea/circuit-breaker` subpath, same one-shape-per-package rule as\n * `work-queue`, `rate-limit`, and `idempotency`.\n */\n\n/**\n * Circuit-breaker policy — pure configuration, no mutable state. One policy is\n * shared across all the calls guarded by one logical breaker (often a\n * module-scope const). `CircuitState` carries the mutable counts; this carries\n * the thresholds those counts are compared against.\n */\nexport interface CircuitPolicy {\n  /**\n   * Consecutive failures in `closed` that trip the breaker `open`. The\n   * `failureThreshold`-th failure is the one that trips — with a threshold of\n   * 5, the breaker survives 4 failures and opens on the 5th.\n   */\n  readonly failureThreshold: number;\n  /**\n   * How long the breaker stays `open` before `canPass` starts admitting\n   * probes, in milliseconds. Measured from `openedAtMs`; the cutoff is\n   * half-open (`elapsed >= cooldownMs` admits), matching `rate-limit` /\n   * `idempotency` window edges — a breaker opened at `t` first probes at\n   * `t + cooldownMs`.\n   */\n  readonly cooldownMs: number;\n  /**\n   * How many probe calls `half_open` admits before fast-failing the rest of\n   * the round. Caps the load on a recovering target — a single slow probe\n   * can't be joined by every queued caller. The round ends when a probe\n   * resolves: success closes the breaker, failure re-opens it.\n   */\n  readonly halfOpenMaxProbes: number;\n}\n\n/**\n * Sensible defaults: trip after 5 consecutive failures, cool down for 30s,\n * admit a single probe before deciding. Tuned for guarding a network backend;\n * override per call site rather than mutating this shared const.\n */\nexport const defaultCircuitPolicy: CircuitPolicy = {\n  failureThreshold: 5,\n  cooldownMs: 30_000,\n  halfOpenMaxProbes: 1,\n};\n\n/**\n * The breaker's phase. A discriminated union on `phase` so each phase carries\n * ONLY its own data and impossible combinations are unrepresentable (pattern\n * 11): there is no state with both a failure count AND an open timestamp,\n * because such a state is meaningless. `phase` is the discriminant; every field\n * is `readonly` so the whole value is trivially JSON-serializable into a\n * consumer's `Store<S>` and safe to thread through a pure reducer.\n *\n *   - `closed`    carries `failures`   — consecutive failures since last success.\n *   - `open`      carries `openedAtMs` — clock reading when it tripped.\n *   - `half_open` carries `probes`     — probes admitted this round.\n */\nexport type CircuitState =\n  | { readonly phase: \"closed\"; readonly failures: number }\n  | { readonly phase: \"open\"; readonly openedAtMs: number }\n  | { readonly phase: \"half_open\"; readonly probes: number };\n\n/** The starting state: closed with zero recorded failures. */\nexport function initCircuit(): CircuitState {\n  return { phase: \"closed\", failures: 0 };\n}\n\n/**\n * Record a successful guarded call. PURE — returns a new state; the input is\n * never mutated.\n *\n *   - `closed`    → reset `failures` to 0 (a success breaks the consecutive run).\n *   - `half_open` → the probe succeeded; the target has recovered → `closed`.\n *   - `open`      → unchanged. A success \"shouldn't happen\" while open (no call\n *                   was admitted to produce one); a late/spurious success must\n *                   not silently un-trip the breaker. See module header note ¹.\n */\nexport function onSuccess(\n  state: CircuitState,\n  _policy: CircuitPolicy,\n): CircuitState {\n  switch (state.phase) {\n    case \"closed\":\n      // Already closed at 0 → return the same shape (cheap; the consumer's\n      // store only re-persists on a real change if it dedupes).\n      return state.failures === 0 ? state : { phase: \"closed\", failures: 0 };\n    case \"half_open\":\n      return { phase: \"closed\", failures: 0 };\n    case \"open\":\n      return state;\n  }\n}\n\n/**\n * Record a failed guarded call. PURE — returns a new state; the input is never\n * mutated. `nowMs` is the injected clock, stamped onto the `open` phase when the\n * breaker trips so `canPass` can measure the cooldown later.\n *\n *   - `closed`    → `failures + 1`; if that reaches `failureThreshold`, trip to\n *                   `open(nowMs)`. The threshold-th failure is the one that trips.\n *   - `half_open` → the probe failed; the target is still unhealthy →\n *                   `open(nowMs)`, restarting the cooldown clock so a fresh\n *                   cooldown elapses before the next probe round.\n *   - `open`      → unchanged. The breaker is already tripped; the `open` clock\n *                   is anchored at the original trip, not bumped by late\n *                   failures. See module header note ¹.\n */\nexport function onFailure(\n  state: CircuitState,\n  policy: CircuitPolicy,\n  nowMs: number,\n): CircuitState {\n  switch (state.phase) {\n    case \"closed\": {\n      const failures = state.failures + 1;\n      // `>=` not `===`: a threshold of 0 (or any already-exceeded count from a\n      // policy change) trips immediately rather than over-counting forever.\n      return failures >= policy.failureThreshold\n        ? { phase: \"open\", openedAtMs: nowMs }\n        : { phase: \"closed\", failures };\n    }\n    case \"half_open\":\n      // A failed probe re-opens and resets the cooldown clock to nowMs.\n      return { phase: \"open\", openedAtMs: nowMs };\n    case \"open\":\n      return state;\n  }\n}\n\n/**\n * Decide whether a call may pass, advancing the phase as a side effect of the\n * decision. PURE — returns `[next, allowed]`; the input is never mutated.\n * Branch on the boolean, thread the state forward regardless:\n *\n *   const [c1, allowed] = canPass(state.circuit, policy, nowMs);\n *   if (!allowed) return [{ ...state, circuit: c1 }, [fastFailCmd]];\n *   return [{ ...state, circuit: c1 }, [doGuardedCallCmd]];\n *\n *   - `closed`    → `[state, true]` — always passes; failures are recorded by\n *                   `onFailure` once the call resolves, not gated here.\n *   - `open`      → if `nowMs - openedAtMs >= cooldownMs` the cooldown has\n *                   elapsed → enter `half_open` and admit this caller as the\n *                   first probe: `[half_open(1), true]`. Otherwise still cooling\n *                   down → `[state, false]` (fast-fail, no downstream load).\n *   - `half_open` → admit while `probes < halfOpenMaxProbes`, incrementing the\n *                   count: `[half_open(probes+1), true]`. Once the cap is hit →\n *                   `[state, false]` until a probe resolves and `onSuccess` /\n *                   `onFailure` moves the phase out of `half_open`.\n *\n * Entering `half_open` lives here (not in `onSuccess` / `onFailure`) because the\n * cooldown is a time condition and only `canPass` reads `nowMs` against\n * `openedAtMs`. See the module header's probe-admission note.\n */\nexport function canPass(\n  state: CircuitState,\n  policy: CircuitPolicy,\n  nowMs: number,\n): readonly [CircuitState, boolean] {\n  switch (state.phase) {\n    case \"closed\":\n      return [state, true];\n    case \"open\": {\n      const elapsed = nowMs - state.openedAtMs;\n      // Half-open cutoff: elapsed exactly == cooldownMs admits the first probe,\n      // matching the >= edge `rate-limit` / `idempotency` use for their windows.\n      if (elapsed >= policy.cooldownMs) {\n        return [{ phase: \"half_open\", probes: 1 }, true];\n      }\n      return [state, false];\n    }\n    case \"half_open\":\n      if (state.probes < policy.halfOpenMaxProbes) {\n        return [{ phase: \"half_open\", probes: state.probes + 1 }, true];\n      }\n      return [state, false];\n  }\n}\n"]}

package/dist/chunk-SKAMZKTE.js

@@ -1,20 +0,0 @@
-import { fromTimeout } from './chunk-2YFLOCWX.js';
-import { subId } from './chunk-DYRKDCJI.js';
-
-// src/deadline/index.ts
-function deadlineSub(id, atMs, opts) {
-  return { ...opts, id: subId(id), type: "deadline", atMs };
-}
-var subscribeDeadline = (sub, ctx, dispatch) => {
-  const remainingMs = Math.max(0, sub.atMs - Date.now());
-  return fromTimeout(
-    (armed) => deadlineExceeded(armed.id, armed.atMs)
-  )({ ...sub, delayMs: remainingMs }, ctx, dispatch);
-};
-function deadlineExceeded(id, atMs) {
-  return { type: "deadline_exceeded", id, atMs };
-}
-
-export { deadlineExceeded, deadlineSub, subscribeDeadline };
-//# sourceMappingURL=chunk-SKAMZKTE.js.map
-//# sourceMappingURL=chunk-SKAMZKTE.js.map

package/dist/chunk-SKAMZKTE.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/deadline/index.ts"],"names":[],"mappings":";;;;AA8GO,SAAS,WAAA,CACd,EAAA,EACA,IAAA,EACA,IAAA,EACa;AACb,EAAA,OAAO,EAAE,GAAG,IAAA,EAAM,EAAA,EAAI,MAAM,EAAE,CAAA,EAAG,IAAA,EAAM,UAAA,EAAY,IAAA,EAAK;AAC1D;AAmBO,IAAM,iBAAA,GAIT,CAAC,GAAA,EAAK,GAAA,EAAK,QAAA,KAAa;AAK1B,EAAA,MAAM,WAAA,GAAc,KAAK,GAAA,CAAI,CAAA,EAAG,IAAI,IAAA,GAAO,IAAA,CAAK,KAAK,CAAA;AAMrD,EAAA,OAAO,WAAA;AAAA,IACL,CAAC,KAAA,KAAU,gBAAA,CAAiB,KAAA,CAAM,EAAA,EAAI,MAAM,IAAI;AAAA,GAClD,CAAE,EAAE,GAAG,GAAA,EAAK,SAAS,WAAA,EAAY,EAAG,KAAK,QAAQ,CAAA;AACnD;AAOO,SAAS,gBAAA,CAAiB,IAAY,IAAA,EAAgC;AAC3E,EAAA,OAAO,EAAE,IAAA,EAAM,mBAAA,EAAqB,EAAA,EAAI,IAAA,EAAK;AAC/C","file":"chunk-SKAMZKTE.js","sourcesContent":["/**\n * @demlik/tea/deadline — a one-shot Sub that fires when an ABSOLUTE wall-clock\n * deadline is reached.\n *\n * Generalizes the recurring \"auto-fail a machine at T+N\" / \"15-minute stale\n * guard\" pattern: a Sub whose `subscriptions(state)` returns it only while the\n * deadline should be armed, and which dispatches a single `DeadlineExceeded`\n * Msg when the wall clock crosses `atMs`.\n *\n * Difference from `fromTimeout` (relative — \"fire after N ms\"): a deadline is\n * an ABSOLUTE target. The delay is computed at subscribe time as\n * `max(0, atMs - Date.now())`. The consequence that matters: subscribing LATE —\n * e.g. after a `Store` rehydrate that resumes a machine whose deadline was set\n * before the page reloaded — still fires at the correct absolute moment,\n * because the remaining delay is recomputed from the current clock, not stored\n * in the Sub. A deadline already in the past at subscribe time yields delay `0`,\n * so `setTimeout(fn, 0)` fires on the NEXT tick (never synchronously inside the\n * reconcile pass — the substrate must finish wiring all subs before any Msg\n * lands).\n *\n * Composition over reinvention: the timer lifecycle is `fromTimeout`'s, not\n * redrawn here. `deadlineSub` produces the Sub literal carrying `atMs`; the\n * `subscribe` cell (`subscribeDeadline`) translates `atMs` → a relative delay\n * and delegates the `setTimeout` / `clearTimeout` to `fromTimeout`. The clock\n * read (`Date.now()`) lives only in the subscribe handler — never in a reducer\n * (invariant 2) — and is exercised in tests via vitest fake timers, matching\n * the no-injection convention of the `fromTimeout` / `fromInterval` exemplars.\n *\n * Strengthens invariant 4 (external time is a subscription — the deadline is a\n * `Sub` the runtime reconciles, never a `setTimeout` leaked into a reducer) and\n * invariant 7 (identity is explicit — the Sub carries a stable `SubId`, so the\n * reconcile pass leaves it running across transitions instead of churning it).\n */\n\nimport { type Sub, subId } from \"../index\";\nimport { fromTimeout } from \"../subs/from-timeout\";\nimport type { SubscribeHandler } from \"../subs/types\";\n\n/**\n * The Sub variant a deadline produces. `atMs` is the absolute target — epoch\n * milliseconds (the `Date.now()` / `Date.parse(...)` scale), NOT a relative\n * delay. It rides on the Sub so the reconcile pass keys identity by `id`\n * alone: the same `id` across transitions means the same armed timer, even if\n * a later `subscriptions(state)` recomputes the literal.\n *\n * Lowercase `\"deadline\"` discriminant per the Sub naming convention (a source\n * noun that doubles as the SubId family); same shape family as the\n * `TimeoutSubData` the `fromTimeout` factory consumes.\n */\nexport type DeadlineSub = Sub<\"deadline\"> & {\n  readonly atMs: number;\n} & DeadlineOpts;\n\n/**\n * Additive options the `deadlineSub` factory folds onto the Sub literal. This\n * is the extension seam (invariant 5 — composition by reduction): future fields\n * — `repeatMs` for a re-arming deadline, `jitterMs` for spread, etc. — land HERE\n * as optional members, and every existing call site keeps compiling because the\n * factory's third parameter is optional and the fields are `readonly` optionals\n * on `DeadlineSub`. Callers are insulated from the concrete `DeadlineSub` shape:\n * they ask for what they need by name, never positionally, so a shape extension\n * never rewrites the ~13 `deadlineSub(id, atMs)` call sites.\n *\n * Empty today on purpose — the seam exists before the first extension does, so\n * the first field is a one-line additive change, not a 13-site migration.\n */\n// biome-ignore lint/complexity/noBannedTypes: intentional empty extension seam — fields are added additively (see doc above).\nexport type DeadlineOpts = {};\n\n/**\n * The Msg the deadline dispatches when the wall clock crosses `atMs`. Exported\n * as a tagged shape so consumers can union it into their machine's Msg type and\n * handle it in a reducer cell. `id` lets a reducer disambiguate WHICH deadline\n * fired when a machine arms several at once; `atMs` echoes the target the timer\n * was scheduled against (useful for assertions / observability).\n *\n * Snake-shaped `\"deadline_exceeded\"` matches the tagged-Msg style this module's\n * orchestrator requested; the actor-in-name PascalCase convention\n * (`TimerFiredDeadline`) is the consumer's to apply at their own boundary if\n * they prefer — `deadlineExceeded(...)` only fixes the wire shape, not the\n * consumer's local dialect.\n */\nexport type DeadlineExceeded = {\n  readonly type: \"deadline_exceeded\";\n  readonly id: string;\n  readonly atMs: number;\n};\n\n/**\n * Build a deadline Sub literal. Pure data — no clock read, no timer; the timer\n * is armed later by the `subscribe` cell. `id` is branded via `subId(...)` so\n * accidental raw-string drift fails at the type level (invariant 7).\n *\n * Return the result directly from `subscriptions(state)` while the deadline\n * should be armed; drop it (return `[]`, or stop returning this id) to disarm —\n * the reconcile pass calls the cleanup, clearing the pending timer before it\n * fires. That is the \"cancel on state exit\" lifecycle, identical to\n * `fromTimeout`'s.\n *\n * @param id   Stable identity for this deadline. Same `id` across transitions =\n *             same armed timer (no churn). Use distinct ids for distinct\n *             deadlines on the same machine.\n * @param atMs Absolute target in epoch milliseconds (e.g. `Date.now() + 900_000`\n *             for a 15-minute guard, or a persisted `expiresAt`).\n * @param opts Optional additive fields folded onto the Sub literal (see\n *             {@link DeadlineOpts}). Omit it for the common case; pass it when a\n *             future field (e.g. `repeatMs`) needs to ride on the deadline. The\n *             optionality is the future-proofing seam — extending the shape\n *             never breaks an existing `deadlineSub(id, atMs)` call site.\n */\nexport function deadlineSub(\n  id: string,\n  atMs: number,\n  opts?: DeadlineOpts,\n): DeadlineSub {\n  return { ...opts, id: subId(id), type: \"deadline\", atMs };\n}\n\n/**\n * The `subscribe[\"deadline\"]` cell. Arms a one-shot timer for the remaining\n * delay `max(0, atMs - Date.now())` and dispatches `deadlineExceeded(...)` when\n * it fires; returns a cleanup that clears the pending timer.\n *\n * Composes on `fromTimeout`: it adapts the absolute `atMs` on the Sub to the\n * relative `delayMs` that `fromTimeout` schedules against, then hands off the\n * `setTimeout` / `clearTimeout` lifecycle wholesale. A past deadline collapses\n * to `delayMs: 0`, so `fromTimeout` fires on the next tick — asynchronously,\n * never inside the reconcile pass.\n *\n * Assign directly to a `Subscribe` cell:\n *\n *   subscribe: {\n *     deadline: subscribeDeadline,\n *   }\n */\nexport const subscribeDeadline: SubscribeHandler<\n  DeadlineSub,\n  DeadlineExceeded,\n  unknown\n> = (sub, ctx, dispatch) => {\n  // Recompute the remaining delay from the CURRENT clock so a late subscribe\n  // (post-rehydrate) still targets the correct absolute moment. `max(0, …)`\n  // keeps a past deadline at delay 0 → setTimeout(fn, 0) → fires next tick, not\n  // synchronously.\n  const remainingMs = Math.max(0, sub.atMs - Date.now());\n\n  // Delegate the timer lifecycle to fromTimeout: build the relative-delay Sub\n  // shape it consumes (`{ ...sub, delayMs }`) and let it own setTimeout /\n  // clearTimeout. The msgFn closes over the deadline's identity + target so the\n  // dispatched Msg carries both.\n  return fromTimeout<DeadlineSub & { delayMs: number }, DeadlineExceeded>(\n    (armed) => deadlineExceeded(armed.id, armed.atMs),\n  )({ ...sub, delayMs: remainingMs }, ctx, dispatch);\n};\n\n/**\n * Construct the Msg the deadline dispatches. Exported so consumers can build /\n * assert the same shape (and so the subscribe cell and tests share one\n * constructor rather than two literals that can drift).\n */\nexport function deadlineExceeded(id: string, atMs: number): DeadlineExceeded {\n  return { type: \"deadline_exceeded\", id, atMs };\n}\n"]}

package/dist/chunk-TGG26XMK.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/work-queue/ops.ts"],"names":[],"mappings":";AAuBO,SAAS,SAAA,CACd,KAAA,EACA,KAAA,EACA,GAAA,EACA,EAAA,EAC8C;AAC9C,EAAA,MAAM,IAAA,GAAqB;AAAA,IACzB,EAAA;AAAA,IACA,MAAA,EAAQ,SAAA;AAAA,IACR,KAAA;AAAA,IACA,UAAA,EAAY;AAAA,GACd;AACA,EAAA,OAAO,EAAE,IAAA,EAAM,CAAC,GAAG,KAAA,EAAO,IAAI,GAAG,IAAA,EAAK;AACxC;AAOO,SAAS,WAAA,CACd,OACA,GAAA,EACwD;AACxD,EAAA,MAAM,MAAM,KAAA,CAAM,SAAA,CAAU,CAAC,CAAA,KAAM,CAAA,CAAE,WAAW,SAAS,CAAA;AACzD,EAAA,MAAM,MAAA,GAAS,GAAA,KAAQ,EAAA,GAAK,MAAA,GAAY,MAAM,GAAG,CAAA;AAIjD,EAAA,IAAI,MAAA,KAAW,QAAW,OAAO,IAAA;AACjC,EAAA,MAAM,OAAA,GAAwB;AAAA,IAC5B,GAAG,MAAA;AAAA,IACH,MAAA,EAAQ,SAAA;AAAA,IACR,SAAA,EAAW;AAAA,GACb;AACA,EAAA,MAAM,IAAA,GAAO,MAAM,KAAA,EAAM;AACzB,EAAA,IAAA,CAAK,GAAG,CAAA,GAAI,OAAA;AACZ,EAAA,OAAO,EAAE,MAAM,OAAA,EAAQ;AACzB;AAOO,SAAS,UAAA,CACd,OACA,EAAA,EAC4C;AAC5C,EAAA,MAAM,OAAO,KAAA,CAAM,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,EAAE,CAAA;AAC5C,EAAA,OAAO,EAAE,IAAA,EAAM,OAAA,EAAS,IAAA,CAAK,MAAA,KAAW,MAAM,MAAA,EAAO;AACvD;AAQO,SAAS,WAAA,CACd,KAAA,EACA,EAAA,EACA,KAAA,EAC4C;AAC5C,EAAA,MAAM,MAAM,KAAA,CAAM,SAAA,CAAU,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,EAAE,CAAA;AAC9C,EAAA,MAAM,MAAA,GAAS,GAAA,KAAQ,EAAA,GAAK,MAAA,GAAY,MAAM,GAAG,CAAA;AAIjD,EAAA,IAAI,MAAA,KAAW,QAAW,OAAO,EAAE,MAAM,KAAA,CAAM,KAAA,EAAM,EAAG,OAAA,EAAS,KAAA,EAAM;AACvE,EAAA,MAAM,IAAA,GAAO,MAAM,KAAA,EAAM;AACzB,EAAA,IAAA,CAAK,GAAG,CAAA,GAAI,KAAA,CAAM,MAAM,CAAA;AACxB,EAAA,OAAO,EAAE,IAAA,EAAM,OAAA,EAAS,IAAA,EAAK;AAC/B;AAGO,SAAS,eAAkB,KAAA,EAGhC;AACA,EAAA,IAAI,OAAA,GAAU,KAAA;AACd,EAAA,MAAM,IAAA,GAAO,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA,KAAoB;AAC1C,IAAA,IAAI,CAAA,CAAE,MAAA,KAAW,SAAA,EAAW,OAAO,CAAA;AACnC,IAAA,OAAA,GAAU,IAAA;AACV,IAAA,OAAO,EAAE,GAAG,CAAA,EAAG,MAAA,EAAQ,SAAA,EAAW,WAAW,MAAA,EAAU;AAAA,EACzD,CAAC,CAAA;AACD,EAAA,OAAO,EAAE,MAAM,OAAA,EAAQ;AACzB;AAGO,SAAS,QAAA,CACd,OACA,EAAA,EAC4C;AAC5C,EAAA,MAAM,OAAO,KAAA,CAAM,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,EAAE,CAAA;AAC5C,EAAA,OAAO,EAAE,IAAA,EAAM,OAAA,EAAS,IAAA,CAAK,MAAA,KAAW,MAAM,MAAA,EAAO;AACvD","file":"chunk-TGG26XMK.js","sourcesContent":["/**\n * Pure queue-lifecycle ops over `QueueItem<I>[]` — the BLESSED delegation\n * surface for this package.\n *\n * Each op is `(queue, ...args) => { next, result? }`. No I/O, no Date.now\n * indirection beyond a plain call site — the adapter in `./index.ts` injects\n * `Store<QueueItem<I>[]>` and orchestrates `load → mutate → save`.\n *\n * Substrate-agnostic by construction: nothing here references chrome.storage,\n * Cloudflare, or any concrete persistence layer. The audit-specific shape\n * (journeyId, projectId, ...) is lifted into the caller's `I` parameter.\n *\n * Importable two ways. The `createQueue(...)` adapter in `./index.ts` binds\n * these ops to a `Store` for in-process use (same one-shape-per-package rule\n * as `@demlik/tea/do`). L2 compositions that own their own Model slice\n * (`monitored-run`, `idempotent-intake`, …) instead reach these ops directly\n * via the `@demlik/tea/work-queue/ops` subpath, so a status flip is delegated\n * here rather than re-rolled per call site.\n */\n\nimport type { QueueItem } from \"./index\";\n\n/** Append a new pending item. Returns the new queue and the created item. */\nexport function enqueueOp<I>(\n  queue: readonly QueueItem<I>[],\n  input: I,\n  now: number,\n  id: string,\n): { next: QueueItem<I>[]; item: QueueItem<I> } {\n  const item: QueueItem<I> = {\n    id,\n    status: \"pending\",\n    input,\n    enqueuedAt: now,\n  };\n  return { next: [...queue, item], item };\n}\n\n/**\n * Claim the first pending item by flipping it to `running` and stamping\n * `startedAt`. Returns the new queue and the claimed item, or `null` if no\n * pending item exists.\n */\nexport function claimNextOp<I>(\n  queue: readonly QueueItem<I>[],\n  now: number,\n): { next: QueueItem<I>[]; claimed: QueueItem<I> } | null {\n  const idx = queue.findIndex((i) => i.status === \"pending\");\n  const target = idx === -1 ? undefined : queue[idx];\n  // `target === undefined` collapses \"no pending item\" and the (impossible\n  // post-`findIndex`) hole into one early-out, so the element is typed\n  // `QueueItem<I>` below without a non-null assertion.\n  if (target === undefined) return null;\n  const claimed: QueueItem<I> = {\n    ...target,\n    status: \"running\",\n    startedAt: now,\n  };\n  const next = queue.slice();\n  next[idx] = claimed;\n  return { next, claimed };\n}\n\n/**\n * Done items leave the queue — completed runs live wherever the caller\n * persists their output. Returns the new queue (or the original reference if\n * no item matched, so the adapter can skip a save).\n */\nexport function markDoneOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const next = queue.filter((i) => i.id !== id);\n  return { next, changed: next.length !== queue.length };\n}\n\n/**\n * Generic single-item status transition. Used by `markFailed`,\n * `markCancelled`, `retryItem`, `bindOutput`. The patch closure receives the\n * matched item and returns its replacement; returning the same reference is\n * fine (the adapter only saves on `changed`).\n */\nexport function patchItemOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n  patch: (item: QueueItem<I>) => QueueItem<I>,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const idx = queue.findIndex((i) => i.id === id);\n  const target = idx === -1 ? undefined : queue[idx];\n  // `target === undefined` collapses the no-match case and the (impossible\n  // post-`findIndex`) hole, narrowing `target` to `QueueItem<I>` for `patch`\n  // without a non-null assertion.\n  if (target === undefined) return { next: queue.slice(), changed: false };\n  const next = queue.slice();\n  next[idx] = patch(target);\n  return { next, changed: true };\n}\n\n/** Reset every `running` item back to `pending`, clearing `startedAt`. */\nexport function resetRunningOp<I>(queue: readonly QueueItem<I>[]): {\n  next: QueueItem<I>[];\n  changed: boolean;\n} {\n  let changed = false;\n  const next = queue.map((i): QueueItem<I> => {\n    if (i.status !== \"running\") return i;\n    changed = true;\n    return { ...i, status: \"pending\", startedAt: undefined };\n  });\n  return { next, changed };\n}\n\n/** Hard-delete an item regardless of status. */\nexport function removeOp<I>(\n  queue: readonly QueueItem<I>[],\n  id: string,\n): { next: QueueItem<I>[]; changed: boolean } {\n  const next = queue.filter((i) => i.id !== id);\n  return { next, changed: next.length !== queue.length };\n}\n"]}