@demlik/tea 0.13.0 → 0.15.0

package/dist/chunk-COS5MSTO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/llm-call/index.ts"],"names":["msg"],"mappings":"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","file":"chunk-COS5MSTO.js","sourcesContent":["/**\n * @packageDocumentation\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 { describeError } from \"../describe-error\";\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`, which hardcoded its\n      // `key` to `purpose` (the port receives no key). Re-key it to `cmd.key` —\n      // the fan-out key `attempt` threaded in — so a fanned-out success carries\n      // the SAME key its failure would (`settleOf`'s err path below uses\n      // `cmd.key`), never the collapsed purpose. `settle.key` is already\n      // `cmd.key`; this aligns the enriched `LlmOk.key` inside it.\n      return { ...settle, result: { ...settle.result, key: cmd.key } };\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: describeError(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-CRPZJVD2.js

@@ -1,71 +0,0 @@
-import { replay } from './chunk-ZSUUOEPL.js';
-import { applyCell } from './chunk-OOYD44JI.js';
-import * as fc from 'fast-check';
-
-// src/pbt/runners/replay-fold.ts
-function foldEvents(machine, ctx, loaded, msgs) {
-  const { state: initialState } = replay(machine, {
-    msgs: [],
-    ctx,
-    loaded: loaded ?? null
-  });
-  const states = [initialState];
-  const steps = [];
-  let current = initialState;
-  for (const msg of msgs) {
-    const [next, emitted] = applyCell(machine, current, msg);
-    steps.push({ prev: current, msg, next, cmds: [...emitted] });
-    states.push(next);
-    current = next;
-  }
-  return { states, steps, finalState: current };
-}
-
-// src/pbt/runners/property.ts
-function resolveFcParams(opts) {
-  return {
-    numRuns: opts?.numRuns ?? 200,
-    ...opts?.seed !== void 0 ? { seed: opts.seed } : {}
-  };
-}
-function runProperty(machine, ctx, seqArb, opts, check) {
-  fc.assert(
-    fc.property(seqArb, (msgs) => {
-      check(foldEvents(machine, ctx, opts?.loaded ?? null, msgs));
-    }),
-    resolveFcParams(opts)
-  );
-}
-function propertyTerminates(machine, ctx, seqArb, terminal, opts) {
-  runProperty(machine, ctx, seqArb, opts, ({ finalState }) => {
-    if (!terminal(finalState)) {
-      throw new Error(
-        `propertyTerminates: final state did not match terminal predicate. Final: ${JSON.stringify(finalState)}`
-      );
-    }
-  });
-}
-function propertyInvariant(machine, ctx, seqArb, invariant, opts) {
-  runProperty(machine, ctx, seqArb, opts, ({ steps }) => {
-    for (const step of steps) {
-      if (!invariant(step)) {
-        throw new Error(
-          `propertyInvariant: failed at step msg=${JSON.stringify(step.msg)} prev=${JSON.stringify(step.prev)} next=${JSON.stringify(step.next)} cmds=${JSON.stringify(step.cmds)}`
-        );
-      }
-    }
-  });
-}
-function propertyTrace(machine, ctx, seqArb, predicate, opts) {
-  runProperty(machine, ctx, seqArb, opts, ({ steps, finalState }) => {
-    if (!predicate(steps, finalState)) {
-      throw new Error(
-        `propertyTrace: predicate failed on trace length=${steps.length}, final=${JSON.stringify(finalState)}`
-      );
-    }
-  });
-}
-
-export { foldEvents, propertyInvariant, propertyTerminates, propertyTrace };
-//# sourceMappingURL=chunk-CRPZJVD2.js.map
-//# sourceMappingURL=chunk-CRPZJVD2.js.map

package/dist/chunk-CRPZJVD2.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/pbt/runners/replay-fold.ts","../src/pbt/runners/property.ts"],"names":[],"mappings":";;;;;AAiEO,SAAS,UAAA,CAOd,OAAA,EACA,GAAA,EACA,MAAA,EACA,IAAA,EAKA;AAKA,EAAA,MAAM,EAAE,KAAA,EAAO,YAAA,EAAa,GAAI,OAAO,OAAA,EAAS;AAAA,IAC9C,MAAM,EAAC;AAAA,IACP,GAAA;AAAA,IACA,QAAQ,MAAA,IAAU;AAAA,GACnB,CAAA;AAKD,EAAA,MAAM,MAAA,GAAc,CAAC,YAAY,CAAA;AACjC,EAAA,MAAM,QAAyB,EAAC;AAChC,EAAA,IAAI,OAAA,GAAU,YAAA;AAEd,EAAA,KAAA,MAAW,OAAO,IAAA,EAAM;AACtB,IAAA,MAAM,CAAC,IAAA,EAAM,OAAO,IAAI,SAAA,CAAmB,OAAA,EAAS,SAAS,GAAG,CAAA;AAChE,IAAA,KAAA,CAAM,IAAA,CAAK,EAAE,IAAA,EAAM,OAAA,EAAS,GAAA,EAAK,IAAA,EAAM,IAAA,EAAM,CAAC,GAAG,OAAO,CAAA,EAAG,CAAA;AAC3D,IAAA,MAAA,CAAO,KAAK,IAAI,CAAA;AAChB,IAAA,OAAA,GAAU,IAAA;AAAA,EACZ;AAEA,EAAA,OAAO,EAAE,MAAA,EAAQ,KAAA,EAAO,UAAA,EAAY,OAAA,EAAQ;AAC9C;;;AC5DA,SAAS,gBACP,IAAA,EAC+B;AAC/B,EAAA,OAAO;AAAA,IACL,OAAA,EAAS,MAAM,OAAA,IAAW,GAAA;AAAA,IAC1B,GAAI,MAAM,IAAA,KAAS,MAAA,GAAY,EAAE,IAAA,EAAM,IAAA,CAAK,IAAA,EAAK,GAAI;AAAC,GACxD;AACF;AAQA,SAAS,WAAA,CAOP,OAAA,EACA,GAAA,EACA,MAAA,EACA,MACA,KAAA,EACM;AACN,EAAG,EAAA,CAAA,MAAA;AAAA,IACE,EAAA,CAAA,QAAA,CAAS,MAAA,EAAQ,CAAC,IAAA,KAAS;AAC5B,MAAA,KAAA,CAAM,WAAW,OAAA,EAAS,GAAA,EAAK,MAAM,MAAA,IAAU,IAAA,EAAM,IAAI,CAAC,CAAA;AAAA,IAC5D,CAAC,CAAA;AAAA,IACD,gBAAmB,IAAI;AAAA,GACzB;AACF;AAoBO,SAAS,kBAAA,CAOd,OAAA,EACA,GAAA,EACA,MAAA,EACA,UACA,IAAA,EACM;AACN,EAAA,WAAA,CAAY,SAAS,GAAA,EAAK,MAAA,EAAQ,MAAM,CAAC,EAAE,YAAW,KAAM;AAC1D,IAAA,IAAI,CAAC,QAAA,CAAS,UAAU,CAAA,EAAG;AAIzB,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,yEAAA,EACY,IAAA,CAAK,SAAA,CAAU,UAAU,CAAC,CAAA;AAAA,OACxC;AAAA,IACF;AAAA,EACF,CAAC,CAAA;AACH;AAuBO,SAAS,iBAAA,CAOd,OAAA,EACA,GAAA,EACA,MAAA,EACA,WACA,IAAA,EACM;AACN,EAAA,WAAA,CAAY,SAAS,GAAA,EAAK,MAAA,EAAQ,MAAM,CAAC,EAAE,OAAM,KAAM;AACrD,IAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,MAAA,IAAI,CAAC,SAAA,CAAU,IAAI,CAAA,EAAG;AACpB,QAAA,MAAM,IAAI,KAAA;AAAA,UACR,CAAA,sCAAA,EAAyC,KAAK,SAAA,CAAU,IAAA,CAAK,GAAG,CAAC,CAAA,MAAA,EACvD,IAAA,CAAK,SAAA,CAAU,IAAA,CAAK,IAAI,CAAC,CAAA,MAAA,EAAS,IAAA,CAAK,SAAA,CAAU,IAAA,CAAK,IAAI,CAAC,SAC3D,IAAA,CAAK,SAAA,CAAU,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,SACrC;AAAA,MACF;AAAA,IACF;AAAA,EACF,CAAC,CAAA;AACH;AAiBO,SAAS,aAAA,CAOd,OAAA,EACA,GAAA,EACA,MAAA,EACA,WAIA,IAAA,EACM;AACN,EAAA,WAAA,CAAY,OAAA,EAAS,KAAK,MAAA,EAAQ,IAAA,EAAM,CAAC,EAAE,KAAA,EAAO,YAAW,KAAM;AACjE,IAAA,IAAI,CAAC,SAAA,CAAU,KAAA,EAAO,UAAU,CAAA,EAAG;AACjC,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,mDAAmD,KAAA,CAAM,MAAM,WACpD,IAAA,CAAK,SAAA,CAAU,UAAU,CAAC,CAAA;AAAA,OACvC;AAAA,IACF;AAAA,EACF,CAAC,CAAA;AACH","file":"chunk-CRPZJVD2.js","sourcesContent":["// ---------------------------------------------------------------------------\n// `foldEvents` — pure deterministic fold over a Msg sequence.\n//\n// PBT needs the per-step (prev/msg/next/cmds) structure to assert\n// step-shaped invariants. The substrate's `replay(machine, opts)` returns\n// only final state + cumulative cmds — insufficient. We use `replay` for\n// the boot step (calls `machine.init(loaded, ctx)` faithfully) then walk\n// msgs ourselves through `applyCell`, the substrate's own cell dispatch.\n//\n// Why walk cells directly instead of looping `replay` once per msg with\n// `loaded: prevState`? Because `init(loaded)` runs every call, and on\n// machines with non-trivial init transforms (e.g. the audit machine's\n// `auditing → attach_debugger` resume cell) that would either (a) re-fire\n// the transform on every step, or (b) require fragile cmd-subtraction to\n// isolate this step's cmds. Calling the cells directly keeps the fold pure\n// and the cmds per-step exactly.\n//\n// Dispatches through `applyCell` — the single primitive `run`/`replay` use —\n// so form classification agrees with production by construction (#275).\n//\n// `foldEvents` does NOT call `interpret`, does NOT touch a Store, does NOT\n// start Subs. The reducer surface is the contract.\n// ---------------------------------------------------------------------------\n\nimport {\n  applyCell,\n  type Cmd,\n  type Machine,\n  replay,\n  type Sub,\n} from \"../../index\";\n\n/**\n * One unit in a fold trace — the four pieces of data a property\n * invariant typically asserts on. `prev` is the state before the msg\n * applied; `next` is the state after; `cmds` is the cmds emitted by this\n * single step (NOT the running total).\n */\nexport interface Step<S, M, C> {\n  readonly prev: S;\n  readonly msg: M;\n  readonly next: S;\n  readonly cmds: readonly C[];\n}\n\n/**\n * Fold a Msg sequence through a machine's pure reducer, returning the\n * per-step trace, every state in order, and the final state. Initial\n * state comes from `replay(machine, { msgs: [], ctx, loaded })` — i.e.\n * `machine.init(loaded ?? null, ctx)` faithfully. Init's emitted cmds\n * are NOT included in any `Step` (they're the boot moment, not a Msg).\n *\n * @param machine  The machine under test.\n * @param ctx      The Ctx — typically `stubCtxThrowingProxy<Ctx>()` when\n *                 init is pure. Pass a real ctx if init reads from it.\n * @param loaded   Optional pre-init snapshot (the `loaded` arg to\n *                 `machine.init`). Defaults to `null` (fresh boot).\n * @param msgs     The Msg sequence to fold.\n *\n * @example\n *   const { states, steps, finalState } = foldEvents(machine, ctx, null, [\n *     { type: \"start\" }, { type: \"tick\" }, { type: \"stop\" },\n *   ]);\n *   // steps[1] = { prev: { type: \"counting\", n: 0 }, msg: { type: \"tick\" }, ... }\n */\nexport function foldEvents<\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  ctx: NoInfer<Ctx>,\n  loaded: NoInfer<S> | null,\n  msgs: readonly NoInfer<M>[],\n): {\n  readonly states: readonly S[];\n  readonly steps: readonly Step<S, M, C>[];\n  readonly finalState: S;\n} {\n  // Boot through `replay` so `init` runs faithfully and we honor the\n  // substrate's loaded-snapshot contract (init may transform the loaded\n  // value before the first Msg lands — e.g. the audit machine flips\n  // `debuggerAttached: false` on resume).\n  const { state: initialState } = replay(machine, {\n    msgs: [],\n    ctx,\n    loaded: loaded ?? null,\n  });\n\n  // Per-msg dispatch goes through `applyCell` — the same primitive `run` and\n  // `replay` use — so this runner classifies the update form identically to\n  // production (`formOf` honors the `__form` tag; #275).\n  const states: S[] = [initialState];\n  const steps: Step<S, M, C>[] = [];\n  let current = initialState;\n\n  for (const msg of msgs) {\n    const [next, emitted] = applyCell<S, M, C>(machine, current, msg);\n    steps.push({ prev: current, msg, next, cmds: [...emitted] });\n    states.push(next);\n    current = next;\n  }\n\n  return { states, steps, finalState: current };\n}\n","// ---------------------------------------------------------------------------\n// Property runners — three thin wrappers over `fc.assert(fc.property(...))`\n// that fold a generated Msg sequence through the machine via `foldEvents`\n// and pipe the result into a TEA-shaped predicate.\n//\n//   - `propertyTerminates` — every sequence ends in a terminal state.\n//   - `propertyInvariant`  — predicate holds on every (prev, msg, next, cmds) step.\n//   - `propertyTrace`      — predicate holds on the full (trace, final) shape.\n//\n// Each runner accepts `numRuns` (passed through to fast-check), an optional\n// `loaded` snapshot (forwarded to `foldEvents`), and the Msg-sequence\n// arbitrary. They return `void`; failures throw via fast-check's standard\n// shrinking output.\n//\n// Default shrinker is fast-check's built-in (open question 4): drop-msg /\n// prefix shrinkers can be layered later but are opt-in, not default. The\n// built-in shrinker handles array-shape shrinking + per-element variant\n// shrinking automatically.\n// ---------------------------------------------------------------------------\n\nimport * as fc from \"fast-check\";\nimport type { Cmd, Machine, Sub } from \"../../index\";\nimport { foldEvents, type Step } from \"./replay-fold\";\n\n/** Common options shared by every property runner. */\ninterface PropertyOpts<S> {\n  /** Pre-init snapshot — passed to `machine.init(loaded, ctx)`. Default `null`. */\n  readonly loaded?: S | null;\n  /** Number of generated sequences to test. Forwarded to `fc.assert`. */\n  readonly numRuns?: number;\n  /** Optional fast-check seed for reproducibility. */\n  readonly seed?: number;\n}\n\n/** The `foldEvents` result a runner's `check` inspects. */\ntype FoldResult<S, M, C> = {\n  readonly states: readonly S[];\n  readonly steps: readonly Step<S, M, C>[];\n  readonly finalState: S;\n};\n\n/**\n * Build the fast-check parameters shared by every runner: the 200-default\n * `numRuns` plus an optional `seed`. Single source of truth so a change to\n * the default lands in one place.\n */\nfunction resolveFcParams<M>(\n  opts: PropertyOpts<unknown> | undefined,\n): fc.Parameters<[readonly M[]]> {\n  return {\n    numRuns: opts?.numRuns ?? 200,\n    ...(opts?.seed !== undefined ? { seed: opts.seed } : {}),\n  };\n}\n\n/**\n * The fold+assert core every runner shares: assert `check` over each\n * generated Msg sequence, folded once through the machine via `foldEvents`.\n * `check` throws on failure so the error message carries the offending\n * shape into fast-check's shrunk counter-example.\n */\nfunction runProperty<\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  ctx: Ctx,\n  seqArb: fc.Arbitrary<readonly M[]>,\n  opts: PropertyOpts<S> | undefined,\n  check: (result: FoldResult<S, M, C>) => void,\n): void {\n  fc.assert(\n    fc.property(seqArb, (msgs) => {\n      check(foldEvents(machine, ctx, opts?.loaded ?? null, msgs));\n    }),\n    resolveFcParams<M>(opts),\n  );\n}\n\n/**\n * Assert every generated Msg sequence ends in a terminal state. `terminal`\n * is the predicate that names the acceptable final states (often\n * `(s) => s.type === \"done\" || s.type === \"idle\"`).\n *\n * The \"every sequence\" property catches stuck states (machine gets to a\n * non-terminal state and no further msg can escape) AND silent loops\n * (every msg variant is a noop from a given state).\n *\n * @example\n *   propertyTerminates(\n *     auditBackgroundMachine,\n *     stubCtxThrowingProxy<BackgroundCtx>(),\n *     arbMsgSequence(msgArb, { minLength: 1, maxLength: 30 }),\n *     (s) => s.type === \"done\" || s.type === \"idle\",\n *     { loaded: auditingState, numRuns: 500 },\n *   );\n */\nexport function propertyTerminates<\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  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  terminal: (state: NoInfer<S>) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ finalState }) => {\n    if (!terminal(finalState)) {\n      // Throwing here (vs returning false) lets the error message carry\n      // the offending final state — fast-check pretty-prints it inside\n      // the shrunk counter-example.\n      throw new Error(\n        `propertyTerminates: final state did not match terminal predicate. ` +\n          `Final: ${JSON.stringify(finalState)}`,\n      );\n    }\n  });\n}\n\n/**\n * Assert a predicate holds on EVERY transition step in a generated\n * sequence. The predicate sees `{ prev, msg, next, cmds }` per step;\n * return true to accept, false (or throw) to fail.\n *\n * Use to pin a \"when X happens in state Y, cmd Z must be emitted\" rule.\n * The shrinker minimizes the offending sequence to the smallest Msg list\n * that still violates the predicate.\n *\n * @example\n *   // Pin the resume-handshake fix: `ws:client:hello` in auditing must\n *   // emit `send_ws { client:ready }`.\n *   propertyInvariant(\n *     auditBackgroundMachine, ctx,\n *     arbMsgSequence(msgArb, { prefix: [{ type: \"ws:client:hello\" }] }),\n *     ({ prev, msg, cmds }) =>\n *       !(prev.type === \"auditing\" && msg.type === \"ws:client:hello\") ||\n *       cmds.some((c) => c.type === \"send_ws\" && c.msg.type === \"client:ready\"),\n *     { loaded: auditingState, numRuns: 200 },\n *   );\n */\nexport function propertyInvariant<\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  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  invariant: (step: Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ steps }) => {\n    for (const step of steps) {\n      if (!invariant(step)) {\n        throw new Error(\n          `propertyInvariant: failed at step msg=${JSON.stringify(step.msg)} ` +\n            `prev=${JSON.stringify(step.prev)} next=${JSON.stringify(step.next)} ` +\n            `cmds=${JSON.stringify(step.cmds)}`,\n        );\n      }\n    }\n  });\n}\n\n/**\n * Assert a predicate over the full trace plus the final state. Use when\n * the property is \"some Msg appeared in the trace before reaching the\n * final state\" or \"no two consecutive steps had the same state.type\" —\n * predicates that need the full sequence, not a single step.\n *\n * @example\n *   propertyTrace(\n *     machine, ctx, seqArb,\n *     (steps, final) =>\n *       final.type !== \"done\" ||\n *       steps.some((step) => step.msg.type === \"ws:audit:done\"),\n *     { loaded: auditingState, numRuns: 500 },\n *   );\n */\nexport function propertyTrace<\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  ctx: NoInfer<Ctx>,\n  seqArb: fc.Arbitrary<readonly NoInfer<M>[]>,\n  predicate: (\n    steps: readonly Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>[],\n    finalState: NoInfer<S>,\n  ) => boolean,\n  opts?: NoInfer<PropertyOpts<S>>,\n): void {\n  runProperty(machine, ctx, seqArb, opts, ({ steps, finalState }) => {\n    if (!predicate(steps, finalState)) {\n      throw new Error(\n        `propertyTrace: predicate failed on trace length=${steps.length}, ` +\n          `final=${JSON.stringify(finalState)}`,\n      );\n    }\n  });\n}\n"]}

package/dist/chunk-D62FDQKE.js

@@ -1,53 +0,0 @@
-import { replay } from './chunk-ZSUUOEPL.js';
-import { typeOf, indexPath, unionKeys, keyPath } from './chunk-EWJP3YYP.js';
-
-// src/trace-replay/index.ts
-function replayTrace(machine, trace, ctx) {
-  const result = replay(machine, {
-    msgs: trace.msgs,
-    ctx,
-    loaded: trace.loaded
-  });
-  const actual = result.state;
-  const expected = trace.finalState;
-  const divergence = firstDivergence(expected, actual, "state");
-  if (divergence === null) {
-    return { matches: true, expected, actual };
-  }
-  return { matches: false, expected, actual, divergence };
-}
-function deepEqual(a, b) {
-  return firstDivergence(a, b, "state") === null;
-}
-function firstDivergence(expected, actual, path) {
-  if (Object.is(expected, actual)) return null;
-  const te = typeOf(expected);
-  const ta = typeOf(actual);
-  if (te !== ta) return { path, expected, actual };
-  if (te === "array") {
-    const ae = expected;
-    const aa = actual;
-    if (ae.length !== aa.length) {
-      return { path, expected, actual };
-    }
-    for (let i = 0; i < ae.length; i++) {
-      const d = firstDivergence(ae[i], aa[i], indexPath(path, i));
-      if (d !== null) return d;
-    }
-    return null;
-  }
-  if (te === "object") {
-    const oe = expected;
-    const oa = actual;
-    for (const key of unionKeys(oe, oa)) {
-      const d = firstDivergence(oe[key], oa[key], keyPath(path, key));
-      if (d !== null) return d;
-    }
-    return null;
-  }
-  return { path, expected, actual };
-}
-
-export { deepEqual, replayTrace };
-//# sourceMappingURL=chunk-D62FDQKE.js.map
-//# sourceMappingURL=chunk-D62FDQKE.js.map

package/dist/chunk-D62FDQKE.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/trace-replay/index.ts"],"names":[],"mappings":";;;;AAqEO,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;AAcO,SAAS,SAAA,CAAU,GAAY,CAAA,EAAqB;AACzD,EAAA,OAAO,eAAA,CAAgB,CAAA,EAAG,CAAA,EAAG,OAAO,CAAA,KAAM,IAAA;AAC5C;AA2BA,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,SAAA,CAAU,IAAA,EAAM,CAAC,CAAC,CAAA;AAC1D,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,KAAA,MAAW,GAAA,IAAO,SAAA,CAAU,EAAA,EAAI,EAAE,CAAA,EAAG;AACnC,MAAA,MAAM,CAAA,GAAI,eAAA,CAAgB,EAAA,CAAG,GAAG,CAAA,EAAG,EAAA,CAAG,GAAG,CAAA,EAAG,OAAA,CAAQ,IAAA,EAAM,GAAG,CAAC,CAAA;AAC9D,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","file":"chunk-D62FDQKE.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\";\nimport { indexPath, keyPath, typeOf, unionKeys } from \"./state-walk\";\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 comparator the\n * record/replay lane owns, exposed so consumers (e.g. `@demlik/tea/parity`'s\n * `parityEqual`) reuse it rather than adding a fourth deep-compare. It is one\n * of three structural walkers in the package, divergent on purpose:\n * this `deepEqual` returns a boolean verdict (order-insensitive, for\n * replay/parity equality), `devtools`'s `diffState` returns a change list (for\n * a human-readable diff view), and `testing`'s `__deepEqual` is the assertion\n * helpers' internal compare — same shape, three jobs, not one to collapse.\n * `true` iff `a` and `b` are structurally equal under {@link firstDivergence}'s\n * walk (object keys 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// === 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// The path grammar (`typeOf`, `indexPath`/`keyPath` segments, `unionKeys`\n// order) is shared with devtools' `diffState` via `./state-walk`, so the two\n// walkers print the SAME path for the same cell by construction. Only the leaf\n// policy differs, on purpose: first-hit here, collect-all there.\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], indexPath(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    // Sorted union of keys 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    for (const key of unionKeys(oe, oa)) {\n      const d = firstDivergence(oe[key], oa[key], keyPath(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"]}

package/dist/chunk-D736QUGF.js.map

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

package/dist/chunk-DGE4PV4A.js

@@ -1,26 +0,0 @@
-import { fromTimeout } from './chunk-2YFLOCWX.js';
-import { subId } from './chunk-OOYD44JI.js';
-
-// src/deadline/index.ts
-function deadlineSub(id, atMs, opts) {
-  return { ...opts, id: subId(id), type: "deadline", atMs };
-}
-function subscribeWith(armTimer) {
-  return (sub, _ctx, dispatch) => armTimer(sub.id, sub.atMs, deadlineExceeded(sub.id, sub.atMs), dispatch);
-}
-function setTimeoutArmTimer() {
-  return (id, atMs, msg, dispatch) => {
-    const delayMs = Math.max(0, atMs - Date.now());
-    return fromTimeout(
-      () => msg
-    )({ id, type: "deadline", delayMs }, void 0, dispatch);
-  };
-}
-var subscribeDeadline = subscribeWith(setTimeoutArmTimer());
-function deadlineExceeded(id, atMs) {
-  return { type: "deadline_exceeded", id, atMs };
-}
-
-export { deadlineExceeded, deadlineSub, setTimeoutArmTimer, subscribeDeadline, subscribeWith };
-//# sourceMappingURL=chunk-DGE4PV4A.js.map
-//# sourceMappingURL=chunk-DGE4PV4A.js.map

package/dist/chunk-DGE4PV4A.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/deadline/index.ts"],"names":[],"mappings":";;;;AA6HO,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;AA6CO,SAAS,cACd,QAAA,EAC0D;AAC1D,EAAA,OAAO,CAAC,GAAA,EAAK,IAAA,EAAM,QAAA,KACjB,SAAS,GAAA,CAAI,EAAA,EAAI,GAAA,CAAI,IAAA,EAAM,iBAAiB,GAAA,CAAI,EAAA,EAAI,GAAA,CAAI,IAAI,GAAG,QAAQ,CAAA;AAC3E;AAeO,SAAS,kBAAA,GAAiD;AAC/D,EAAA,OAAO,CAAC,EAAA,EAAI,IAAA,EAAM,GAAA,EAAK,QAAA,KAAa;AAGlC,IAAA,MAAM,UAAU,IAAA,CAAK,GAAA,CAAI,GAAG,IAAA,GAAO,IAAA,CAAK,KAAK,CAAA;AAC7C,IAAA,OAAO,WAAA;AAAA,MACL,MAAM;AAAA,KACR,CAAE,EAAE,EAAA,EAAI,IAAA,EAAM,YAAY,OAAA,EAAQ,EAAG,QAAW,QAAQ,CAAA;AAAA,EAC1D,CAAA;AACF;AAkBO,IAAM,iBAAA,GAIT,aAAA,CAAc,kBAAA,EAAoB;AAO/B,SAAS,gBAAA,CAAiB,IAAY,IAAA,EAAgC;AAC3E,EAAA,OAAO,EAAE,IAAA,EAAM,mBAAA,EAAqB,EAAA,EAAI,IAAA,EAAK;AAC/C","file":"chunk-DGE4PV4A.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 * WHAT BACKS THE TIMER IS THE HOST'S CHOICE. `setTimeout` is the universal\n * default, but it is not universal: a Durable Object that hibernates has no\n * live `setTimeout` to wake it, so its deadline must be backed by a `do_alarm`\n * registered on the alarm registry; a test host wants a fake-timer schedule.\n * That backing is the `ArmTimer` seam — `subscribeWith(armTimer)` builds the\n * `subscribe.deadline` cell from a host-plugged timer, and `subscribeDeadline`\n * IS `subscribeWith(setTimeoutArmTimer())`. One deadline surface, three hosts;\n * there is no second Sub type and no second `atMs` anchor to keep in sync.\n *\n * The anchor is what makes the seam safe. `atMs` is ABSOLUTE, so whatever backs\n * it arms to a fixed wall-clock instant: the host computes the gap itself\n * (`atMs - Date.now()`), and on a host that just rehydrated after hibernation\n * that gap is the SHRUNKEN remainder — the deadline honours the original target\n * rather than resetting to a fresh full-length window.\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, type SubId, 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 host-plugged timer backing. Given the deadline's stable `id`, its\n * absolute `atMs`, and the Msg to fire, arm the platform-appropriate timer\n * (DO alarm registry, `setTimeout`, fake timer) and return a cleanup that\n * cancels the pending fire.\n *\n * `id` is the Sub's reconcile id — a registry-backed host (the DO alarm slot)\n * keys its entry on `id` so the cleanup deletes the EXACT entry the substrate\n * reconciled. A `setTimeout`-backed host ignores `id` (the closure holds the\n * handle).\n *\n * The host computes the gap itself: `atMs - Date.now()` is the REMAINING time.\n * On a host that just rehydrated after hibernation that gap is the shrunken\n * remainder — the deadline is NOT reset to its full length. That recomputation\n * is the reason `atMs` rides on the Sub as an absolute instant rather than a\n * delay: the anchor is what every backing agrees on.\n */\nexport type ArmTimer<M> = (\n  id: SubId,\n  atMs: number,\n  msg: M,\n  dispatch: (msg: M) => void,\n) => () => void;\n\n/**\n * Build the `subscribe[\"deadline\"]` cell from a host-plugged `armTimer`. This\n * module owns the Sub shape, the anchor, and the Msg; the HOST owns what backs\n * the timer. The returned handler reads `id` + `atMs` off the Sub, builds the\n * `deadlineExceeded(...)` Msg, and hands all three to `armTimer`.\n *\n * Use it when `setTimeout` is the wrong backing — most concretely a Durable\n * Object, which hibernates and must register a `do_alarm` instead:\n *\n *   subscribe: {\n *     deadline: subscribeWith((id, atMs, msg, dispatch) =>\n *       alarms.register(id, atMs, () => dispatch(msg)),\n *     ),\n *   }\n *\n * For the `setTimeout` default, use {@link subscribeDeadline} — it is exactly\n * `subscribeWith(setTimeoutArmTimer())`, so there is one deadline surface and\n * one anchor, not a second one per host.\n */\nexport function subscribeWith(\n  armTimer: ArmTimer<DeadlineExceeded>,\n): SubscribeHandler<DeadlineSub, DeadlineExceeded, unknown> {\n  return (sub, _ctx, dispatch) =>\n    armTimer(sub.id, sub.atMs, deadlineExceeded(sub.id, sub.atMs), dispatch);\n}\n\n/**\n * The `setTimeout` timer backing — for node / browser / any host whose timer is\n * a plain `setTimeout`. Arms for the REMAINING time (`max(0, atMs - Date.now())`,\n * floored at 0 so an already-past deadline fires on the NEXT tick rather than\n * synchronously inside the reconcile pass), so a deadline re-derived after a\n * rehydrate fires at the original instant, not a fresh full window.\n *\n * Composes on `fromTimeout` rather than redrawing `setTimeout` /\n * `clearTimeout`: this package has ONE timer lifecycle, and the arm-timer seam\n * plugs into it instead of forking it. A hibernating host does NOT use this —\n * it plugs its own `armTimer` (a `do_alarm` registration) into\n * {@link subscribeWith}.\n */\nexport function setTimeoutArmTimer(): ArmTimer<DeadlineExceeded> {\n  return (id, atMs, msg, dispatch) => {\n    // Recompute the remaining delay from the CURRENT clock so a late subscribe\n    // (post-rehydrate) still targets the correct absolute moment.\n    const delayMs = Math.max(0, atMs - Date.now());\n    return fromTimeout<Sub<\"deadline\"> & { delayMs: number }, DeadlineExceeded>(\n      () => msg,\n    )({ id, type: \"deadline\", delayMs }, undefined, dispatch);\n  };\n}\n\n/**\n * The `subscribe[\"deadline\"]` cell for the DEFAULT `setTimeout` backing. Arms a\n * one-shot timer for the remaining delay `max(0, atMs - Date.now())` and\n * dispatches `deadlineExceeded(...)` when it fires; returns a cleanup that\n * clears the pending timer.\n *\n * It is `subscribeWith(setTimeoutArmTimer())` — the default backing named, not\n * a separate implementation, so the host-plugged path and the default path can\n * never disagree about the anchor.\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> = subscribeWith(setTimeoutArmTimer());\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-DMYGQB4O.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/monitored-run/index.ts"],"names":[],"mappings":"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","file":"chunk-DMYGQB4O.js","sourcesContent":["/**\n * @demlik/tea/monitored-run — a long-running operation that is BOTH staged and\n * watched: an ordered stage pipeline whose POSITION survives eviction, wrapped\n * by a no-progress safety deadline and (optionally) a periodic durable\n * checkpoint.\n *\n * This is the merge of two field-guide concerns the audit-agent machine\n * hand-wired together (`seed/audit-agent-machine`): the OUTER pipeline position\n * (`RunStage` — planning → testing → summarizing → reporting, replayed on cold\n * wake by re-emitting the one outstanding effect) and the no-progress safety\n * alarm (`subs.ts`, keyed on `progressSeq` so every progress event retires the\n * old alarm and arms a fresh one). `monitored-run` lifts both into one config-\n * driven knob with the uniform L2 contract `resilient-call` established:\n * `init()`, the verbs (`start` / `advance` / `progress` / `onDeadline` /\n * `boot`), `subs(state)`, and `handlers(ports)`.\n *\n *   - It is **staged, optionally**. Omit `stages` and the run is single-shot:\n *     `start` enters `running`, `advance` finishes it to `done`. Provide\n *     `stages` and it becomes an ordered pipeline — each `advance` retires the\n *     current stage and claims the next, finishing to `done` only when the last\n *     stage is retired. The pipeline POSITION lives in the Model (a\n *     `work-queue` of stage items), so an eviction mid-pipeline resumes at the\n *     same stage via `boot` — the audit machine's \"pipeline position survives\n *     eviction\" property, generalized.\n *   - It is **watched**. While `running`, a no-progress deadline is armed at\n *     `lastProgressAt + deadlineMs` and keyed on `progressSeq`. Every\n *     `progress` / `advance` bumps the seq, so the substrate retires the old\n *     alarm and arms a new one — a self-rearming watchdog. If the alarm fires\n *     (`onDeadline`) the run goes `failed` with a deadline reason. Omit\n *     `deadlineMs` → no watchdog (the `stale` phase is never reachable).\n *   - It **checkpoints, optionally**. Provide `snapshotEvery` and every\n *     progress unit is accounted to a `../snapshot` slice; once the cadence is\n *     reached a checkpoint Cmd is emitted (interpreted by the spliced snapshot\n *     `handlers`), so a crashed run restarts from the last durable checkpoint\n *     rather than from zero. Omit it → no checkpointing.\n *\n * ## Why the run lifecycle is INLINE (run-tracker not extracted)\n *\n * The phase union (`idle` / `running` / `stale` / `done` / `failed`, a\n * discriminated union carrying only each phase's own data) and its bookkeeping\n * (`runId`, `startedAt`, `lastProgressAt`, `progressSeq`) live directly on this\n * slice rather than behind a `run-tracker` sub-knob.\n * Extraction earns its keep when two independent axes vary; here the lifecycle\n * has exactly one anchoring axis (this run), so a separate module would be a\n * premature seam. The two genuinely independent axes — the safety DEADLINE and\n * the periodic SNAPSHOT — ARE extracted (`../deadline`, `../snapshot`), and the\n * stage list is a `../work-queue` slice (`QueueItem<Stage>[]`) whose every\n * status flip is DELEGATED to the blessed `../work-queue/ops` (`enqueueOp` /\n * `claimNextOp` / `markDoneOp`) — never re-rolled here. The lifecycle is the\n * glue between them.\n *\n * ## The two non-negotiables (canon)\n *\n *   - **Durable** — the slice is plain data (the stage queue is a\n *     JSON-serializable `QueueItem<Stage>[]`, the snapshot slice is plain\n *     numbers), so it survives DO eviction / reload.\n *   - **Replayable** — every transition is a pure verb returning new state +\n *     Cmds; nothing here reads the clock or RNG. Time arrives as an `at` / `atMs`\n *     parameter; the only clock read is `Date.now()` inside the snapshot\n *     `handlers` port (the effect boundary), exactly as `../snapshot` stamps it.\n *\n * ## Typical wiring\n *\n *   const run = createMonitoredRun<MyStage, MyState>({\n *     stages: [\"plan\", \"test\", \"report\"],\n *     deadlineMs: 10 * 60_000,\n *     snapshotEvery: 25,\n *   });\n *\n *   init: (loaded) => loaded ? [loaded, []] : [{ run: run.init() }, []],\n *   update: {\n *     begin:    (s, m) => lift(s, run.start(s.run, m.runId, m.at)),\n *     advance:  (s, m) => lift(s, run.advance(s.run, checkpoint(s), m.result, m.at)),\n *     progress: (s, m) => lift(s, run.progress(s.run, checkpoint(s), m.at)),\n *     run_deadline: (s, m) => lift(s, run.onDeadline(s.run, m)),\n *     boot:     (s, m) => lift(s, run.boot(s.run, m.at)),\n *   },\n *   subscriptions: (s) => run.subs(s.run),\n *   subscribe: { deadline: subscribeDeadline },\n *   interpret: run.handlers({ store: r2 }),\n */\n\nimport {\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineSub,\n  subscribeDeadline,\n} from \"../deadline\";\nimport type { Cmd, Interpret } from \"../index\";\nimport {\n  createSnapshot,\n  type SnapshotFailedMsg,\n  type SnapshotLoadCmd,\n  type SnapshotLoadedMsg,\n  type SnapshotLoadFailedMsg,\n  type SnapshotSavedMsg,\n  type SnapshotState,\n  type SnapshotStore,\n  type SnapshotWriteCmd,\n} from \"../snapshot\";\nimport type { QueueItem } from \"../work-queue\";\nimport { queueAdapter } from \"../work-queue/adapter\";\n\n// ===========================================================================\n// Config — the knob. Every field optional; omit a field → omit its gate.\n// ===========================================================================\n\n/**\n * The monitored-run knob. EVERY field is optional:\n *   - omit `stages`       → single-shot run (no pipeline; one `advance` finishes).\n *   - omit `deadlineMs`   → no no-progress watchdog (the run is never auto-failed).\n *   - omit `snapshotEvery`→ no periodic checkpoint (no `snapshot_write` Cmds).\n *\n * An empty config `{}` is a valid single-shot, unwatched, uncheckpointed run.\n *\n * `Stage` is the consumer's stage identifier — any JSON-serializable value\n * (a string id, a `{ kind, ... }` record). It rides through the stage queue\n * unchanged so the consumer's reducer can branch on the current stage to emit\n * that stage's outstanding effect (the audit machine's `outstandingEffect`).\n */\nexport interface MonitoredRunConfig<Stage> {\n  /**\n   * The ordered stages of the pipeline. Position survives eviction (lives in\n   * the Model's stage queue). Omit for a single-shot run. An empty array is\n   * treated as single-shot too — there is nothing to pipeline through.\n   */\n  readonly stages?: readonly Stage[];\n  /**\n   * No-progress watchdog budget, in ms. The safety deadline is armed at\n   * `lastProgressAt + deadlineMs` and re-armed on every progress event. Omit\n   * for no watchdog.\n   */\n  readonly deadlineMs?: number;\n  /**\n   * Checkpoint cadence — write a durable snapshot once this many progress\n   * units have accumulated. Threaded straight into `../snapshot`'s `every`.\n   * Omit for no checkpointing.\n   */\n  readonly snapshotEvery?: number;\n  /**\n   * Store key the rolling checkpoint is written under. Forwarded to\n   * `../snapshot`'s `key`; defaults to that module's `@@snapshot`. Ignored\n   * when `snapshotEvery` is omitted.\n   */\n  readonly snapshotKey?: string;\n}\n\n// ===========================================================================\n// Slice — the Model field this knob owns. Run lifecycle INLINE + composed bricks.\n// ===========================================================================\n\n/**\n * Why a run terminated as `failed`. Discriminated so each reason carries only\n * its own data (pattern 11):\n *   - `deadline`  — the no-progress watchdog fired (`onDeadline`).\n *   - `stage`     — the consumer reported a stage failure via `advance(..., fail)`.\n *\n * `stale` is a SEPARATE phase (not a fail reason): a run is `stale` only by an\n * explicit consumer signal that progress has wedged WITHOUT the deadline having\n * fired — a soft, recoverable observation. The deadline firing is a hard\n * terminal (`failed { reason: \"deadline\" }`).\n *\n * The `stage` variant carries the FAILING STAGE VALUE (the `Stage` itself), not\n * a positional index: done stages leave the queue (`markDoneOp` filters them),\n * so a residual index drifts as the pipeline advances. The stage value is the\n * stable, meaningful identifier — `undefined` for a single-shot run (no stage).\n */\nexport type RunFailure<Stage> =\n  | { readonly reason: \"deadline\"; readonly at: number }\n  | {\n      readonly reason: \"stage\";\n      readonly stage: Stage | undefined;\n      readonly error: unknown;\n    };\n\n/**\n * The run bookkeeping every phase carries in common, split out so each arm of\n * the `MonitoredRunState` discriminated union names only the data it ADDS\n * (`runId` on started phases, `failure` on `failed`) — the same discipline the\n * sibling `PaginatorState` uses for its shared `seen` / `pages` counters. Plain\n * data end to end so the whole slice survives DO eviction / reload:\n *\n *   - `stepStates`     — the stage pipeline as a `work-queue` of stage items.\n *                        Empty for a single-shot run. The ONE `running` item is\n *                        the current stage; `done` items are retired stages\n *                        (they leave the queue via `markDoneOp`, so the queue\n *                        shrinks as the pipeline advances and is empty at\n *                        `done`). POSITION survives eviction because this list\n *                        is durable.\n *   - `startedAt`      — `at` of `start`. Observability; never compared in a verb.\n *   - `lastProgressAt` — `at` of the most recent progress event; the watchdog\n *                        base. Re-armed by `progress` / `advance`.\n *   - `progressSeq`    — monotonic progress counter; keys the safety alarm Sub\n *                        id so every bump retires the old alarm and arms a new\n *                        one (the audit subs' `safety:{progressSeq}` discipline).\n *   - `snapshot`       — the `../snapshot` slice (cadence counter + durable\n *                        watermark). Always present (uniform shape); the gate\n *                        is simply never driven when `snapshotEvery` is omitted.\n */\ninterface RunCore<Stage> {\n  readonly stepStates: readonly QueueItem<Stage>[];\n  readonly startedAt: number;\n  readonly lastProgressAt: number;\n  readonly progressSeq: number;\n  readonly snapshot: SnapshotState;\n}\n\n/**\n * The slice — a discriminated union on `phase` so each phase carries ONLY its\n * own data and impossible combinations are unrepresentable (pattern 11), the\n * same idiom the sibling `CircuitState` / `PaginatorState` / `RunFailure` follow:\n *\n *   - `idle`    — created but never started. Carries no `runId` (identity is\n *                 host-minted at `start`) and no `failure`: \"not started\" is its\n *                 OWN phase, not a `running` run wearing an empty-string `runId`\n *                 sentinel. `start` is the only transition out, so no verb has to\n *                 guard \"has this actually started?\" — `phase === \"idle\"` says it.\n *   - `running` — the run is live. Carries the host-minted `runId` and the\n *                 `RunCore` pipeline position + watchdog bookkeeping.\n *   - `stale`   — a soft \"no progress observed\" mark the consumer can set and\n *                 clear; still resumable (a `progress` clears it back to\n *                 `running`). Distinct from a fired deadline, which is terminal.\n *   - `done`    — every stage retired (or the single-shot `advance` landed).\n *   - `failed`  — terminal failure; the typed `failure` reason rides ONLY this\n *                 arm, so it is present iff `phase === \"failed\"` BY CONSTRUCTION —\n *                 there is no nullable side field to keep in sync.\n *\n * `runId` is the host-minted run identity, stamped at `start` (the machine never\n * mints — see the audit seed's \"run identity is host-minted\"). It rides every\n * started phase, but not `idle`.\n */\nexport type MonitoredRunState<Stage> =\n  | (RunCore<Stage> & { readonly phase: \"idle\" })\n  | (RunCore<Stage> & { readonly phase: \"running\"; readonly runId: string })\n  | (RunCore<Stage> & { readonly phase: \"stale\"; readonly runId: string })\n  | (RunCore<Stage> & { readonly phase: \"done\"; readonly runId: string })\n  | (RunCore<Stage> & {\n      readonly phase: \"failed\";\n      readonly runId: string;\n      readonly failure: RunFailure<Stage>;\n    });\n\n/**\n * The live (still-timed) phases — `running` or `stale`. The verbs narrow to this\n * before touching the watchdog bookkeeping (`runId` / `progressSeq`), so a\n * settled (`done` / `failed`) or never-started (`idle`) slice can never be bumped\n * — the narrow replaces the old `runId === \"\"` born-live guard.\n */\ntype LiveRun<Stage> = Extract<\n  MonitoredRunState<Stage>,\n  { readonly phase: \"running\" | \"stale\" }\n>;\n\n/**\n * The outcome a consumer reports to `advance`: the current stage either\n * succeeded (retire it, claim the next) or failed (terminate the run). Plain\n * data — the consumer parses its stage result at its own boundary and hands a\n * settled outcome here.\n */\nexport type StageResult =\n  | { readonly kind: \"ok\" }\n  | { readonly kind: \"fail\"; readonly error: unknown };\n\n// ===========================================================================\n// Cmd + Msg — re-exported from the composed bricks so consumers wire one import.\n// ===========================================================================\n\n/** The checkpoint-write Cmd, generic over the consumer's checkpoint value `V`. */\nexport type MonitoredRunCmd<V> = SnapshotWriteCmd<V>;\n\n/** The deadline Msg the safety alarm dispatches when the watchdog fires. */\nexport type MonitoredRunTimerMsg = DeadlineExceeded;\n\n/** Ports the consumer supplies to `handlers` — just the checkpoint store. */\nexport interface MonitoredRunPorts<V> {\n  /** Where periodic checkpoints are written (R2 / KV / DO sub-key / Map). */\n  readonly store: SnapshotStore<V>;\n}\n\n// ===========================================================================\n// Sub-id family. The safety alarm is keyed on `progressSeq` so a progress\n// event retires the old alarm and arms a new one (single-shot, re-armed by id\n// bump — the audit subs discipline).\n// ===========================================================================\n\nfunction safetyTimerId(runId: string, progressSeq: number): string {\n  return `monitored:safety:${runId}:${progressSeq}`;\n}\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build a monitored-run knob from `config`. `Stage` is the consumer's stage\n * identifier type; `V` is the consumer's checkpoint value type (what\n * `snapshotEvery` checkpoints). Returns the uniform L2 knob contract.\n *\n * No `rng` parameter: unlike `resilient-call`, nothing here jitters — the only\n * external inputs are time (an `at` / `atMs` parameter) and the consumer's\n * stage outcomes. The clock is read only inside the snapshot `handlers` port.\n */\nexport function createMonitoredRun<Stage, V = unknown>(\n  config: MonitoredRunConfig<Stage> = {},\n) {\n  const stages = config.stages ?? [];\n  const isPipeline = stages.length > 0;\n\n  // The stage-queue seam, bound once. Every stage status flip delegates to the\n  // `QueueAdapter` verbs (`wq.enqueue` / `wq.claim` / `wq.markDone`), so the\n  // `QueueItem<Stage>` shape stays insulated behind them.\n  const wq = queueAdapter<Stage>();\n\n  // The snapshot sub-knob is built only when `snapshotEvery` is configured;\n  // absence is `null` so the progress gate short-circuits to \"no checkpoint\".\n  // When present, the slice still carries a default SnapshotState so the shape\n  // is uniform across configs — the gate simply never records into it.\n  const snap =\n    config.snapshotEvery !== undefined\n      ? createSnapshot<V>({\n          every: config.snapshotEvery,\n          ...(config.snapshotKey !== undefined\n            ? { key: config.snapshotKey }\n            : {}),\n        })\n      : null;\n\n  // The snapshot knob to actually drive: `snap` when configured, else a single\n  // inert default (`every: 1`) bound ONCE here. Its `record` is never invoked\n  // (the progress gate short-circuits when `snap` is null), so the cadence value\n  // is immaterial — one shared stateless knob of pure functions stands in for\n  // the disabled-checkpoint case across init/boot/handlers.\n  const activeSnap = snap ?? createSnapshot<V>({ every: 1 });\n\n  /** The starting slice for a never-started run: the `idle` phase, no `runId`. */\n  function init(): MonitoredRunState<Stage> {\n    return {\n      phase: \"idle\",\n      stepStates: [],\n      startedAt: 0,\n      lastProgressAt: 0,\n      progressSeq: 0,\n      // A default snapshot slice even without the brick → uniform shape. When\n      // `snap` is null the inert `activeSnap` default supplies the slice; its\n      // `record` is never called, so the cadence value is immaterial.\n      snapshot: activeSnap.init(),\n    };\n  }\n\n  /**\n   * Seed the stage queue from the configured stages: every stage enqueued\n   * `pending`, then the first claimed `running`. `at` stamps the claim. PURE —\n   * the work-queue ops are pure array transforms; ids are positional (`stage:i`)\n   * so they are deterministic and replayable (no `crypto`, no `Math.random`).\n   */\n  function seedStages(at: number): readonly QueueItem<Stage>[] {\n    let queue: readonly QueueItem<Stage>[] = [];\n    stages.forEach((stage, i) => {\n      queue = wq.enqueue(queue, stage, at, `stage:${i}`).next;\n    });\n    // Claim the first stage as the running position. A non-empty pipeline always\n    // has a pending head here, so the claim succeeds.\n    const claimed = wq.claim(queue, at);\n    return claimed ? claimed.next : queue;\n  }\n\n  /** The current (running) stage item, or `undefined` for a single-shot run. */\n  function currentStage(\n    s: MonitoredRunState<Stage>,\n  ): QueueItem<Stage> | undefined {\n    return s.stepStates.find((i) => i.status === \"running\");\n  }\n\n  // === Verb: start =========================================================\n\n  /**\n   * Start (or restart) the run for `runId` at time `at`. Seeds the stage queue\n   * (if a pipeline) and enters `running` with the watchdog clock primed. Stamps\n   * `runId` from the host — the machine never mints (invariant: identity is\n   * host-minted, parsed at the boundary). PURE.\n   */\n  function start(\n    s: MonitoredRunState<Stage>,\n    runId: string,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    // Build the `running` arm explicitly rather than spreading `...s`: a restart\n    // from `failed` must NOT carry the old `failure` field forward (the `running`\n    // arm has none), and a start from `idle` has no `runId` to preserve. Only the\n    // snapshot slice threads through.\n    const next: MonitoredRunState<Stage> = {\n      phase: \"running\",\n      runId,\n      stepStates: isPipeline ? seedStages(at) : [],\n      startedAt: at,\n      lastProgressAt: at,\n      progressSeq: 0,\n      snapshot: s.snapshot,\n    };\n    return [next, []];\n  }\n\n  /**\n   * Bump the watchdog clock: set `lastProgressAt`/`progressSeq` so the safety\n   * alarm Sub id changes and the substrate re-arms a fresh deadline. Shared by\n   * `progress` and `advance`. PURE.\n   */\n  function bumpProgress(s: LiveRun<Stage>, at: number): LiveRun<Stage> {\n    return { ...s, lastProgressAt: at, progressSeq: s.progressSeq + 1 };\n  }\n\n  /**\n   * Account one progress unit to the snapshot slice (when the brick is\n   * configured), returning the new slice + any checkpoint Cmd. `payload` is the\n   * consumer's checkpoint value to persist. PURE — `snap.record` is pure, the\n   * write is realized only when the runtime performs the emitted Cmd.\n   */\n  function recordSnapshot(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (snap === null) return [s, []];\n    const [snapshot, cmds] = snap.record(s.snapshot, payload, at);\n    // `snap.record` only ever emits `SnapshotWriteCmd<V>` (its sole Cmd), but\n    // its signature widens to `readonly Cmd[]`. Narrow back to this knob's\n    // precise Cmd union so a consumer's host Cmd type can stay exact.\n    return [{ ...s, snapshot }, cmds as readonly MonitoredRunCmd<V>[]];\n  }\n\n  // === Verb: progress ======================================================\n\n  /**\n   * Record forward progress: bump the watchdog (re-arming the safety alarm),\n   * clear any `stale` mark back to `running`, and account a snapshot unit\n   * (emitting a checkpoint Cmd on a cadence hit). A no-op unless the run is live\n   * (`running` / `stale`) — a late progress event on a settled (`done` /\n   * `failed`) or never-started (`idle`) run is ignored. PURE.\n   */\n  function progress(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    const bumped: MonitoredRunState<Stage> = {\n      ...bumpProgress(s, at),\n      phase: \"running\",\n    };\n    return recordSnapshot(bumped, payload, at);\n  }\n\n  // === Verb: markStale =====================================================\n\n  /**\n   * Mark the run `stale` — a soft \"no progress observed\" signal the consumer\n   * raises WITHOUT the deadline having fired (e.g. an upstream heartbeat gap).\n   * Recoverable: the next `progress` flips it back to `running`. A no-op unless\n   * the run is currently `running` (a settled run cannot go stale). Does NOT\n   * touch `progressSeq` — going stale is not progress, so the armed deadline\n   * keeps counting toward the hard terminal. PURE.\n   */\n  function markStale(\n    s: MonitoredRunState<Stage>,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\") return [s, []];\n    return [{ ...s, phase: \"stale\" }, []];\n  }\n\n  // === Verb: advance =======================================================\n\n  /**\n   * Advance the pipeline on a stage outcome:\n   *\n   *   - `result.kind === \"fail\"` → terminate `failed { reason: \"stage\" }`,\n   *     carrying the failing stage index + error. No further stages run.\n   *   - `result.kind === \"ok\"`:\n   *       - single-shot run → finish to `done` (and force a final checkpoint\n   *         when checkpointing, so the last durable snapshot is the terminal\n   *         state).\n   *       - pipeline → retire the current stage (`markDoneOp`) and claim the\n   *         next (`claimNextOp`). If none remain, finish to `done`. The new\n   *         position survives eviction.\n   *\n   * An advance is itself a progress event, so it bumps the watchdog (re-arming\n   * the alarm at the new stage) and accounts a snapshot unit. A no-op on a\n   * settled (`done` / `failed`) or never-started (`idle`) run. PURE — `at` is the\n   * only clock, ids are positional.\n   */\n  function advance(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    result: StageResult,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n\n    // Stage failure → hard terminal. Carry the failing stage VALUE (stable),\n    // `undefined` for a single-shot run with no stage.\n    if (result.kind === \"fail\") {\n      const failed: MonitoredRunState<Stage> = {\n        ...s,\n        phase: \"failed\",\n        failure: {\n          reason: \"stage\",\n          stage: currentStage(s)?.input,\n          error: result.error,\n        },\n      };\n      return [failed, []];\n    }\n\n    // Success: bump the watchdog first (an advance is progress), then move the\n    // pipeline position.\n    const bumped = bumpProgress(s, at);\n\n    // Single-shot: one advance finishes the run.\n    if (!isPipeline) {\n      const done: MonitoredRunState<Stage> = { ...bumped, phase: \"done\" };\n      // Force a terminal checkpoint so the last durable snapshot is `done`,\n      // not whatever the cadence happened to land on.\n      return finishWithSnapshot(done, payload, at);\n    }\n\n    // Pipeline: retire the running stage, claim the next.\n    const current = currentStage(s);\n    const afterDone =\n      current !== undefined\n        ? wq.markDone(s.stepStates, current.id).next\n        : s.stepStates;\n    const claimed = wq.claim(afterDone, at);\n\n    if (claimed === null) {\n      // No more stages — the pipeline is complete.\n      const done: MonitoredRunState<Stage> = {\n        ...bumped,\n        phase: \"done\",\n        stepStates: afterDone,\n      };\n      return finishWithSnapshot(done, payload, at);\n    }\n\n    // Advance to the next stage — POSITION now points at the claimed item.\n    const moved: MonitoredRunState<Stage> = {\n      ...bumped,\n      stepStates: claimed.next,\n    };\n    return recordSnapshot(moved, payload, at);\n  }\n\n  /**\n   * Finish helper: force a terminal checkpoint when checkpointing is enabled\n   * (so the durable snapshot is the terminal state), else just settle. Shared\n   * by single-shot finish and pipeline completion. PURE.\n   */\n  function finishWithSnapshot(\n    s: MonitoredRunState<Stage>,\n    payload: V,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (snap === null) return [s, []];\n    const [snapshot, cmds] = snap.force(s.snapshot, payload, at);\n    // Same narrowing as `recordSnapshot`: `snap.force` emits only the write Cmd.\n    return [{ ...s, snapshot }, cmds as readonly MonitoredRunCmd<V>[]];\n  }\n\n  // === Verb: onDeadline ====================================================\n\n  /**\n   * The safety alarm fired. Two outcomes by Sub-id match:\n   *\n   *   - the alarm matches the CURRENT `progressSeq` (no progress since it was\n   *     armed) → the run is wedged → terminate `failed { reason: \"deadline\" }`.\n   *   - the alarm matches an OLDER seq → a stale fire racing a progress event\n   *     that already re-armed the alarm → no-op (the substrate retired this id;\n   *     tolerate a fire still in flight defensively).\n   *\n   * A no-op on a settled run (its alarm was reconciled away; tolerate a stale\n   * fire) and on a NEVER-STARTED (`idle`) run (`subs` armed nothing for it, so\n   * any alarm reaching it is a rogue fire that must not un-start it). PURE —\n   * `msg.atMs` stamps the failure.\n   */\n  function onDeadline(\n    s: MonitoredRunState<Stage>,\n    msg: MonitoredRunTimerMsg,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    // Only a live (`running` / `stale`) run is watched. A settled (`done` /\n    // `failed`) run's alarm was reconciled away, and a never-started (`idle`) run\n    // — which has no host-minted `runId` and armed nothing — must not be\n    // un-started by a born-live/rogue fire. The phase narrow IS the guard the old\n    // `runId === \"\"` sentinel stood in for.\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    // Only the alarm armed against the current progressSeq is live. A bumped\n    // seq means progress re-armed it; an older fire is stale.\n    if (msg.id !== safetyTimerId(s.runId, s.progressSeq)) return [s, []];\n    const failed: MonitoredRunState<Stage> = {\n      ...s,\n      phase: \"failed\",\n      failure: { reason: \"deadline\", at: msg.atMs },\n    };\n    return [failed, []];\n  }\n\n  // === Verb: boot ==========================================================\n\n  /**\n   * Resume after a reload (cold wake). Re-seeds the watchdog clock to `at` so\n   * the safety alarm re-arms from NOW (the pre-crash `lastProgressAt` would\n   * immediately fire a deadline that already elapsed during downtime — a cold\n   * wake is not a no-progress wedge). Bumps `progressSeq` so the alarm gets a\n   * fresh id, and resets the snapshot cadence counter (un-checkpointed\n   * pre-crash progress is moot — recovery resumes from the last durable\n   * checkpoint). The pipeline POSITION (`stepStates`) is preserved untouched —\n   * that is the whole point of staging: resume at the same stage.\n   *\n   * A no-op on a settled (`done` / `failed`) or never-started (`idle`) run. Emits\n   * NO Cmd — re-emitting the current stage's outstanding effect is the CONSUMER's\n   * job (it knows the per-stage Cmd), the audit machine's `outstandingEffect(stage)`\n   * pattern. PURE.\n   */\n  function boot(\n    s: MonitoredRunState<Stage>,\n    at: number,\n  ): readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]] {\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [s, []];\n    // `snap.boot` returns the reducer-cell shape `[SnapshotState, Cmd[]]`\n    // (uniform across every sibling knob); a boot emits no Cmd, so take only the\n    // slice. Assigning the tuple itself would put an ARRAY where a SnapshotState\n    // belongs — a type error AND a non-round-trippable slice.\n    const [bootedSnapshot] = activeSnap.boot(s.snapshot);\n    const reseeded: MonitoredRunState<Stage> = {\n      ...s,\n      phase: \"running\",\n      lastProgressAt: at,\n      progressSeq: s.progressSeq + 1,\n      snapshot: bootedSnapshot,\n      // Any stage left `running` mid-flight stays the running position; the\n      // queue is already correct (a single in-flight stage). resetRunningOp is\n      // NOT applied — unlike a work pool, a monitored run has exactly one\n      // in-flight stage and resuming it (not re-queuing it) is the correct\n      // cold-wake behavior.\n    };\n    return [reseeded, []];\n  }\n\n  // === Subs ================================================================\n\n  /**\n   * Pre-wired subscriptions: the no-progress safety deadline, armed only while\n   * the run is live (`running` / `stale`) AND a `deadlineMs` is configured. The\n   * Sub id is keyed on `progressSeq`, so every progress event retires the old\n   * alarm and the substrate arms a fresh one at the new `lastProgressAt +\n   * deadlineMs` — a self-rearming watchdog with no manual `clearTimeout`. A\n   * settled run desires no subs. Wire `subscribe: { deadline: subscribeDeadline }`.\n   *\n   * A NEVER-STARTED slice (`init()`) is its OWN `idle` phase, not a `running` run\n   * with an empty `runId`. The `phase !== \"running\" && phase !== \"stale\"` narrow\n   * therefore excludes it structurally — no separate `runId === \"\"` sentinel gate\n   * is needed. Were `idle` armed, it would fire a deadline at `0 + deadlineMs`\n   * (already in the past) and auto-fail a run that never began — the \"born live\"\n   * defect. `start` is the only transition out of `idle`, so the watchdog exists\n   * exactly once a real run is in flight.\n   */\n  function subs(s: MonitoredRunState<Stage>): readonly DeadlineSub[] {\n    if (config.deadlineMs === undefined) return [];\n    if (s.phase !== \"running\" && s.phase !== \"stale\") return [];\n    return [\n      deadlineSub(\n        safetyTimerId(s.runId, s.progressSeq),\n        s.lastProgressAt + config.deadlineMs,\n      ),\n    ];\n  }\n\n  // === Handlers ============================================================\n\n  /**\n   * Pre-wired interpret handler for the checkpoint write. Delegates wholesale to\n   * `../snapshot`'s `handlers` (which performs the `put` and routes Ok →\n   * `snapshot_saved` / Err → `snapshot_failed` via Railway — the write never\n   * rejects into the runtime). When checkpointing is disabled (`snapshotEvery`\n   * omitted), no `snapshot_write` Cmd is ever emitted, so the returned map is an\n   * inert no-op handler — kept for a uniform `handlers(ports)` call shape.\n   *\n   * Fold the `snapshot_saved` Msg back through this knob's `confirmSnapshot`\n   * verb to advance the durable watermark.\n   */\n  function handlers(\n    ports: MonitoredRunPorts<V>,\n  ): Interpret<\n    | SnapshotSavedMsg\n    | SnapshotFailedMsg\n    | SnapshotLoadedMsg<V>\n    | SnapshotLoadFailedMsg,\n    SnapshotWriteCmd<V> | SnapshotLoadCmd,\n    unknown\n  > {\n    return activeSnap.handlers({ store: ports.store });\n  }\n\n  /**\n   * Fold a confirmed checkpoint write into the slice — advances the snapshot\n   * watermark (forward-only). A no-op pass-through when checkpointing is\n   * disabled. PURE. Fold the `snapshot_saved` Msg here.\n   */\n  function confirmSnapshot(\n    s: MonitoredRunState<Stage>,\n    msg: SnapshotSavedMsg,\n  ): MonitoredRunState<Stage> {\n    if (snap === null) return s;\n    // `snap.confirm` returns the reducer-cell shape `[SnapshotState, Cmd[]]`\n    // (an ack emits nothing). Take only the slice — folding the whole tuple into\n    // `snapshot` would store an ARRAY where a SnapshotState belongs (a type error\n    // and a non-round-trippable slice).\n    const [confirmed] = snap.confirm(s.snapshot, msg);\n    return { ...s, snapshot: confirmed };\n  }\n\n  return {\n    init,\n    start,\n    progress,\n    markStale,\n    advance,\n    onDeadline,\n    boot,\n    confirmSnapshot,\n    subs,\n    handlers,\n  };\n}\n\n/**\n * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the\n * slice lives at `state.run`. Convenience for the common single-slice host;\n * hosts with a differently-named field spread by hand. PURE — a thin record\n * rebuild, no clock / RNG.\n */\nexport function liftRun<\n  S extends { run: MonitoredRunState<Stage> },\n  Stage,\n  C extends Cmd,\n>(\n  state: S,\n  [slice, cmds]: readonly [MonitoredRunState<Stage>, readonly C[]],\n): readonly [S, readonly C[]] {\n  return [{ ...state, run: slice }, cmds];\n}\n\n/**\n * Re-export the deadline Sub primitives so consumers (and tests) wire one\n * import: `subscribeDeadline` is the `subscribe` cell, `deadlineSub` builds the\n * Sub literal this knob's `subs` emits.\n */\nexport { subscribeDeadline, deadlineSub };\nexport type {\n  DeadlineSub,\n  DeadlineExceeded,\n  SnapshotSavedMsg,\n  SnapshotWriteCmd,\n};\n"]}

package/dist/chunk-EWJP3YYP.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/trace-replay/state-walk.ts"],"names":[],"mappings":";AAoBO,SAAS,OACd,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;AAGO,SAAS,SAAA,CAAU,MAAc,CAAA,EAAmB;AACzD,EAAA,OAAO,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,CAAC,CAAA,CAAA,CAAA;AACrB;AAGO,SAAS,OAAA,CAAQ,MAAc,GAAA,EAAqB;AACzD,EAAA,OAAO,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,GAAG,CAAA,CAAA;AACvB;AAQO,SAAS,SAAA,CACd,GACA,CAAA,EACU;AACV,EAAA,OAAO,CAAC,mBAAG,IAAI,IAAI,CAAC,GAAG,OAAO,IAAA,CAAK,CAAC,CAAA,EAAG,GAAG,OAAO,IAAA,CAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAA,EAAK;AACnE","file":"chunk-EWJP3YYP.js","sourcesContent":["// ---------------------------------------------------------------------------\n// state-walk — the structural-walk primitives the record/replay lane owns and\n// devtools' `diffState` reuses.\n//\n// Two walkers cross this substrate: `trace-replay`'s `firstDivergence` (first\n// differing cell, for a regression verdict) and `devtools`' `diffState` (EVERY\n// differing cell, classified add/remove/change, for a human diff). They diverge\n// on PURPOSE at the leaf — first-hit vs collect-all, length-mismatch-at-node vs\n// per-element — but they MUST agree on the path grammar: the same cell has to\n// print the same path in both, so a `divergence.path` from a replay result\n// indexes straight into a `StateChange[]`.\n//\n// That agreement used to be enforced by copy-paste discipline plus a comment.\n// Here it is enforced by construction: both walkers import the same `typeOf`,\n// the same `indexPath`/`keyPath` segment builders, and the same `unionKeys`\n// sorted-union order, so key-sorting and leaf equality cannot silently drift\n// between the two. Pure + zero-dep — it runs anywhere a machine runs.\n// ---------------------------------------------------------------------------\n\n/** Coarse type tag both walkers use to decide how to recurse. */\nexport function 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\n/** Path to the `i`-th element of an array node, e.g. `state.queue[2]`. */\nexport function indexPath(path: string, i: number): string {\n  return `${path}[${i}]`;\n}\n\n/** Path to a keyed child of an object node, e.g. `state.user.name`. */\nexport function keyPath(path: string, key: string): string {\n  return `${path}.${key}`;\n}\n\n/**\n * Sorted union of both sides' own keys — the deterministic, insertion-order-\n * independent child order both walkers traverse. Shared so two states with the\n * same data in different key order compare equal in BOTH, and the reported path\n * for a real mismatch is reproducible run-to-run and identical across walkers.\n */\nexport function unionKeys(\n  a: Record<string, unknown>,\n  b: Record<string, unknown>,\n): string[] {\n  return [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();\n}\n"]}

package/dist/chunk-FV3Z5MBE.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/at.ts","../src/work-queue/ops.ts"],"names":[],"mappings":";AAcO,SAAS,EAAA,CAAM,KAAmB,KAAA,EAA8B;AACrE,EAAA,OAAO,QAAQ,CAAA,IAAK,KAAA,IAAS,IAAI,MAAA,GAAS,MAAA,GAAY,IAAI,KAAK,CAAA;AACjE;;;ACQO,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;AAIzD,EAAA,MAAM,MAAA,GAAS,EAAA,CAAG,KAAA,EAAO,GAAG,CAAA;AAC5B,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;AAI9C,EAAA,MAAM,MAAA,GAAS,EAAA,CAAG,KAAA,EAAO,GAAG,CAAA;AAC5B,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-FV3Z5MBE.js","sourcesContent":["// ---------------------------------------------------------------------------\n// at — indexed array read that returns `T | undefined`, stating this package's\n// findIndex-narrowing convention once.\n//\n// Without `noUncheckedIndexedAccess`, `arr[idx]` is typed `T` even when `idx`\n// is `-1` (findIndex's \"no match\") or past the end — so the recurring\n// \"locate by findIndex, then use the element\" pattern has to hand-collapse\n// `idx === -1 ? undefined : arr[idx]` to get an honest `T | undefined` and\n// early-out without a non-null assertion. That collapse (plus a justifying\n// comment) was re-derived at every such site (work-queue/ops, fan-out). `at`\n// owns the convention: pass the `findIndex` result straight in, branch on the\n// `undefined` it returns, and keep `idx` around for any subsequent splice.\n// ---------------------------------------------------------------------------\n\nexport function at<T>(arr: readonly T[], index: number): T | undefined {\n  return index < 0 || index >= arr.length ? undefined : arr[index];\n}\n","/**\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 { at } from \"../at\";\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  // `at` collapses \"no pending item\" (idx === -1) into the same `undefined`\n  // early-out, so the element is typed `QueueItem<I>` below without a non-null\n  // assertion; `idx` stays around for the write.\n  const target = at(queue, idx);\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  // `at` collapses the no-match case into an `undefined` early-out, narrowing\n  // `target` to `QueueItem<I>` for `patch` without a non-null assertion; `idx`\n  // stays around for the write.\n  const target = at(queue, idx);\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"]}

package/dist/chunk-HCEVHFJ7.js

@@ -1,54 +0,0 @@
-// src/throttle/index.ts
-function throttle(fn, ms, opts) {
-  const leading = opts?.leading ?? true;
-  const trailing = opts?.trailing ?? true;
-  let handle = null;
-  let pendingArgs = null;
-  function clearHandle() {
-    if (handle !== null) {
-      clearTimeout(handle);
-      handle = null;
-    }
-  }
-  function onWindowExpired() {
-    if (trailing && pendingArgs !== null) {
-      const args = pendingArgs;
-      pendingArgs = null;
-      handle = setTimeout(onWindowExpired, ms);
-      fn(...args);
-    } else {
-      handle = null;
-    }
-  }
-  const throttled = (...args) => {
-    if (handle === null) {
-      if (leading) {
-        fn(...args);
-      } else if (trailing) {
-        pendingArgs = args;
-      }
-      handle = setTimeout(onWindowExpired, ms);
-    } else if (trailing) {
-      pendingArgs = args;
-    }
-  };
-  throttled.cancel = () => {
-    clearHandle();
-    pendingArgs = null;
-  };
-  throttled.flush = () => {
-    if (pendingArgs !== null) {
-      const args = pendingArgs;
-      pendingArgs = null;
-      clearHandle();
-      fn(...args);
-    } else {
-      clearHandle();
-    }
-  };
-  return throttled;
-}
-
-export { throttle };
-//# sourceMappingURL=chunk-HCEVHFJ7.js.map
-//# sourceMappingURL=chunk-HCEVHFJ7.js.map