@demlik/tea 0.1.0 → 0.1.1

package/dist/recorder/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/recorder/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// recorder — capture a Runtime's Msg sequence for later replay.\n//\n// `historyTracker` (in ../index) is the exemplar: a BOUNDED, in-memory ring\n// buffer over `runtime.observe`. The recorder is its UNBOUNDED, SERIALIZABLE\n// cousin. Where historyTracker exists to answer \"what were the last N\n// transitions?\", the recorder exists to answer \"reproduce this entire run\n// locally against the current reducer.\"\n//\n// The killer feature this enables: record a prod Msg sequence, dump it as\n// JSONL, ship the file home, and feed it to `../trace-replay`'s `replayTrace`\n// — which folds the SAME msgs through `replay(machine, ...)` and diffs the\n// resulting state against the recorded final state. If they diverge, the\n// reducer changed behavior for that input. Regression-as-a-trace.\n//\n// What `replay` needs to reproduce a run (see `replay` in ../index):\n//   - `loaded`   — the value `init` was booted with. Captured at the boot\n//                  observe, where `msg === null` and `state` is the post-init\n//                  initial state. (We capture the post-init state, not the raw\n//                  storage value, because replay re-runs `init(loaded, ctx)`\n//                  itself — and for a faithful re-run we feed it that initial\n//                  state as `loaded` so `init` returns `[loaded, []]`. This is\n//                  the rehydrate path, which the substrate guarantees is a pure\n//                  passthrough; see Invariant 2.)\n//   - `msgs`     — every non-null msg, in dispatch order.\n//   - `ctx`      — NOT captured here. Ctx is host wiring (sibling runtimes,\n//                  clients), supplied fresh at replay time. The trace is the\n//                  INPUT (loaded + msgs); ctx is the ENVIRONMENT.\n//\n// This module OWNS the `Trace` type. `../trace-replay` imports it.\n// ---------------------------------------------------------------------------\n\nimport type { Runtime } from \"../index\";\n\n/**\n * A recorded run, sufficient to reproduce it via `../trace-replay`.\n *\n * The recorder OWNS this type; `../trace-replay` imports it. It is the wire\n * contract between the two halves of the record/replay feature.\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport interface Trace<S, M> {\n  /**\n   * The initial state captured at the boot observe (the transition where\n   * `msg === null`). Fed back to replay as `loaded` so `init(loaded, ctx)`\n   * reproduces the exact starting point. `null` only if the recorder attached\n   * AFTER boot (it missed the boot observe) — replay then re-runs fresh `init`.\n   */\n  loaded: S | null;\n  /** The ordered, non-null msgs as observed. The replay input sequence. */\n  msgs: readonly M[];\n  /**\n   * The last observed state. The oracle: `replayTrace` deep-compares its\n   * recomputed final state against this. Equal ⇒ the reducer still produces\n   * the same result for this input.\n   */\n  finalState: S;\n  /**\n   * Per-transition `(msg, post-state)` pairs, in dispatch order, for human\n   * inspection (e.g. \"show me the state after step 3\"). When present, there\n   * is exactly one entry per recorded msg and `state` is the POST-transition\n   * state for that msg (so `steps[i].msg === msgs[i]` and `steps.at(-1).state`\n   * deep-equals `finalState`). NOT required for replay — replay only needs\n   * `loaded` + `msgs` + `finalState`.\n   *\n   * Present iff the recorder was created with `captureSteps: true`, OR the\n   * Trace was re-hydrated from JSONL via {@link parseJSONL} (the JSONL format\n   * carries per-step state, so the parser populates `steps` whenever a step\n   * line had a non-null state). A trace dumped with `captureSteps: false` has\n   * `steps === undefined`.\n   */\n  steps?: readonly { msg: M; state: S }[];\n}\n\n/** Options for {@link recorder}. */\nexport interface RecorderOptions {\n  /**\n   * Fraction of msgs to record, in `(0, 1]`. Default `1` (record everything).\n   *\n   * IMPORTANT — sampling breaks replay fidelity. A sampled trace DROPS msgs,\n   * so its `msgs` array is no longer the complete input sequence and\n   * `replayTrace` will NOT reproduce `finalState`. Sampling exists for\n   * VOLUME STATISTICS (how much traffic, msg-type distribution), not for\n   * faithful replay. Use the default `1` for any trace you intend to replay.\n   *\n   * The boot observe (`msg === null`) is ALWAYS recorded regardless of\n   * `sampleRate` — `loaded` and `finalState` are anchors, not samples.\n   */\n  sampleRate?: number;\n  /**\n   * When `true`, retain a per-transition `(msg, post-state)` pair in\n   * {@link Trace.steps} for EVERY recorded transition. Default `false`.\n   *\n   * Size vs. fidelity — the precise trade-off:\n   *\n   *   - `captureSteps: false` (default) — the MINIMAL replay-faithful trace.\n   *     The recorder keeps `loaded` (boot state), the ordered `msgs`, and\n   *     `finalState`. That is exactly what `../trace-replay` needs to refold\n   *     the run and diff the result. Memory is O(msgs) — one msg ref each, no\n   *     per-step state snapshot. `dump().steps` is `undefined`; in JSONL,\n   *     interior step lines carry `state: null` (the post-states were never\n   *     retained) and only the LAST step line carries `finalState`. A trace\n   *     dumped this way REPLAYS correctly but cannot answer \"what was the\n   *     state after step 3?\".\n   *\n   *   - `captureSteps: true` — the FULL-fidelity trace. The recorder also\n   *     snapshots the post-transition state for every msg, so `dump().steps`\n   *     holds `{ msg, state }` for every transition (post-state) and\n   *     `toJSONL()` emits a non-null `state` on every step line. Memory is\n   *     O(msgs × |state|) — a state ref per transition (refs, not deep\n   *     copies; TEA states are conventionally immutable, so the runtime's\n   *     post-transition state object is retained by reference). This is the\n   *     mode for per-step inspection and for a JSONL file that round-trips\n   *     `steps` exactly via {@link parseJSONL}.\n   *\n   * Replay fidelity is identical in both modes — `../trace-replay` reads\n   * `loaded` + `msgs` + `finalState` only and never touches `steps`. The\n   * choice is purely \"do I also want to inspect intermediate states?\".\n   */\n  captureSteps?: boolean;\n}\n\n/**\n * A live recorder attached to a Runtime. Mirrors `historyTracker`'s\n * stop/snapshot semantics: `dump()` works at any time (including after\n * `stop()`), `stop()` is idempotent and detaches the observer.\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport interface Recorder<S, M> {\n  /**\n   * Snapshot the recording so far as a {@link Trace}. Returns a fresh object\n   * with copied arrays on every call (callers may slice/replay without\n   * affecting the recorder's buffers). Entry values are references to the\n   * originals (TEA states/msgs are conventionally immutable).\n   *\n   * Throws only if called before the boot observe has fired AND no msgs have\n   * been recorded — i.e. there is no `finalState` yet. In practice callers\n   * `await runtime.ready` before `dump()`, after which boot has fired.\n   */\n  dump(): Trace<S, M>;\n  /**\n   * Serialize the recording as JSONL (one JSON object per line) — a streamable\n   * format that appends cleanly and survives truncation (a partial tail line\n   * is the only loss). The first line is the boot header\n   * `{ kind: \"boot\", state }`; each subsequent line is\n   * `{ kind: \"step\", msg, state }` for one recorded transition.\n   *\n   * Re-hydrate with {@link parseJSONL}.\n   *\n   * Round-trip fidelity depends on `captureSteps`:\n   *   - `captureSteps: true` — every step line carries its non-null\n   *     post-state, so `parseJSONL(rec.toJSONL())` reconstructs `steps`\n   *     EXACTLY and deep-equals `rec.dump()` (which also has `steps`). Full\n   *     per-step fidelity round-trips.\n   *   - `captureSteps: false` (default) — interior step lines carry\n   *     `state: null` (those post-states were never retained); only the last\n   *     step line carries `finalState`. `parseJSONL` then populates `steps`\n   *     with just the entries that had a non-null state (the final one), so\n   *     the re-hydrated Trace is NOT deep-equal to `rec.dump()` (which has no\n   *     `steps`). It is still fully replay-faithful: `loaded`, `msgs`, and\n   *     `finalState` are intact. Record with `captureSteps: true` if you need\n   *     interior states to survive the round-trip.\n   */\n  toJSONL(): string;\n  /**\n   * Detach the underlying observer. After `stop()`:\n   *   - no new transitions are recorded;\n   *   - `dump()` / `toJSONL()` keep working against the buffered contents;\n   *   - the recorder holds no observer reference into the runtime.\n   *\n   * Idempotent — subsequent calls are no-ops.\n   */\n  stop(): void;\n}\n\n/**\n * Attach a recorder to a Runtime. Subscribes via `runtime.observe`, capturing\n * the boot state as `loaded` and every subsequent non-null msg in order.\n *\n * One-line creation, mirroring `historyTracker`:\n *\n *     const rec = recorder(runtime);\n *     // ... drive the runtime ...\n *     await runtime.ready;            // boot observe has fired\n *     const trace = rec.dump();       // { loaded, msgs, finalState }\n *\n * @param runtime - any `Runtime<S, M>`. The recorder uses only `observe`.\n * @param opts    - see {@link RecorderOptions}. Default records everything,\n *                  no step retention.\n */\nexport function recorder<S, M extends { type: string }>(\n  runtime: Runtime<S, M>,\n  opts?: RecorderOptions,\n): Recorder<S, M> {\n  // Clamp sampleRate into (0, 1]. A non-positive or NaN rate would record\n  // nothing (and break replay anchors); default it to 1 (record all). Rates\n  // above 1 are meaningless — clamp to 1.\n  const rawRate = opts?.sampleRate;\n  const sampleRate =\n    rawRate === undefined || Number.isNaN(rawRate) || rawRate <= 0\n      ? 1\n      : Math.min(rawRate, 1);\n  const captureSteps = opts?.captureSteps ?? false;\n\n  // `loaded` is the post-init state captured at the boot observe. `undefined`\n  // sentinel = boot not yet seen; resolved to `S | null` in dump() (null when\n  // the recorder attached after boot and never observed msg === null).\n  let loaded: S | undefined;\n  let sawBoot = false;\n  // The ordered, recorded msgs. Unbounded (the recorder's whole point vs the\n  // bounded historyTracker).\n  const msgs: M[] = [];\n  // Per-step (msg, state) pairs — only populated when captureSteps is on.\n  const steps: { msg: M; state: S }[] = [];\n  // The last observed state — boot state until the first step, then advances\n  // with every recorded OR dropped transition (finalState must reflect the\n  // true latest state even under sampling, so it stays a valid replay oracle\n  // for the unsampled case and an honest \"where the run ended\" marker).\n  let finalState: S | undefined;\n  let stopped = false;\n\n  const unobserve = runtime.observe((msg, state) => {\n    // finalState tracks the latest state regardless of sampling — it is the\n    // run's endpoint, an anchor, not a sample.\n    finalState = state;\n\n    if (msg === null) {\n      // Boot observe: the post-init initial state. Always captured.\n      loaded = state;\n      sawBoot = true;\n      return;\n    }\n\n    // Sampling decision. sampleRate === 1 short-circuits to always-record so\n    // the common (faithful) path pays no RNG cost. Math.random() < rate keeps\n    // a `rate` fraction in expectation.\n    if (sampleRate < 1 && Math.random() >= sampleRate) return;\n\n    msgs.push(msg);\n    if (captureSteps) steps.push({ msg, state });\n  });\n\n  return {\n    dump(): Trace<S, M> {\n      if (finalState === undefined) {\n        throw new Error(\n          \"@demlik/tea/recorder: dump() called before any transition was observed. \" +\n            \"Await `runtime.ready` (boot fires the first observe) before dumping.\",\n        );\n      }\n      return {\n        // sawBoot ⇒ `loaded` is the captured boot state; otherwise the\n        // recorder attached post-boot and replay must re-run fresh init.\n        loaded: sawBoot ? (loaded as S) : null,\n        msgs: msgs.slice(),\n        finalState,\n        // Only attach `steps` when captureSteps was requested — keeps the\n        // dumped Trace shape honest about what was retained.\n        ...(captureSteps ? { steps: steps.slice() } : {}),\n      };\n    },\n    toJSONL(): string {\n      if (finalState === undefined) {\n        throw new Error(\n          \"@demlik/tea/recorder: toJSONL() called before any transition was observed. \" +\n            \"Await `runtime.ready` (boot fires the first observe) before serializing.\",\n        );\n      }\n      // Serialize the live snapshot via the shared Trace→JSONL writer so the\n      // recorder and the standalone `traceAttachment` path emit byte-identical\n      // wire format. `dump()` resolves the captureSteps logic (steps present\n      // iff captureSteps was on); `traceToJSONL` then emits a non-null state\n      // on every step line when steps exist, or `null` interior + finalState\n      // on the last line when they don't. The replay path never reads step\n      // states, so the captureSteps:false null-interiors never affect replay.\n      return traceToJSONL(this.dump());\n    },\n    stop(): void {\n      if (stopped) return;\n      stopped = true;\n      unobserve();\n    },\n  };\n}\n\n/** One line of the JSONL format produced by {@link Recorder.toJSONL}. */\ntype JsonlLine<S, M> =\n  | { kind: \"boot\"; state: S | null }\n  | { kind: \"step\"; msg: M; state: S | null };\n\n/**\n * Re-hydrate a {@link Trace} from the JSONL produced by\n * {@link Recorder.toJSONL}. The inverse of `toJSONL`, so\n * `parseJSONL(rec.toJSONL())` deep-equals `rec.dump()`.\n *\n * Parsing rules:\n *   - The first non-blank line MUST be the boot header `{ kind: \"boot\", state }`.\n *     Its `state` becomes `Trace.loaded`.\n *   - Each `{ kind: \"step\", msg, state }` line contributes `msg` to\n *     `Trace.msgs` and `(msg, state)` to `Trace.steps`.\n *   - `Trace.finalState` is the `state` of the LAST step line, or the boot\n *     `state` when there are no steps (a boot-only trace).\n *\n * Blank lines are skipped (tolerant of trailing newlines / hand-edited files).\n * A malformed line, a missing/duplicate boot header, or a step with `null`\n * final state throws — the trace is unusable for replay and silent corruption\n * is worse than a loud parse error (errors are data; surface them).\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport function parseJSONL<S, M>(jsonl: string): Trace<S, M> {\n  const rawLines = jsonl.split(\"\\n\");\n  let loaded: S | null = null;\n  let sawBoot = false;\n  const msgs: M[] = [];\n  const steps: { msg: M; state: S }[] = [];\n  let finalState: S | null = null;\n  let finalKnown = false;\n\n  for (const [i, rawLine] of rawLines.entries()) {\n    const line = rawLine.trim();\n    if (line === \"\") continue; // tolerate blank / trailing-newline lines\n\n    let parsed: JsonlLine<S, M>;\n    try {\n      parsed = JSON.parse(line) as JsonlLine<S, M>;\n    } catch (err) {\n      throw new Error(\n        `@demlik/tea/recorder: parseJSONL failed on line ${i + 1}: not valid JSON. ${String(err)}`,\n      );\n    }\n\n    if (parsed.kind === \"boot\") {\n      if (sawBoot) {\n        throw new Error(\n          `@demlik/tea/recorder: parseJSONL saw a second boot header on line ${i + 1}. ` +\n            \"A trace has exactly one boot line.\",\n        );\n      }\n      sawBoot = true;\n      loaded = parsed.state;\n      // The boot state is the finalState until a step supersedes it (boot-only\n      // trace case).\n      finalState = parsed.state;\n      finalKnown = parsed.state !== null;\n    } else if (parsed.kind === \"step\") {\n      if (!sawBoot) {\n        throw new Error(\n          `@demlik/tea/recorder: parseJSONL saw a step line before the boot header on line ${i + 1}.`,\n        );\n      }\n      msgs.push(parsed.msg);\n      if (parsed.state !== null) {\n        steps.push({ msg: parsed.msg, state: parsed.state });\n        finalState = parsed.state;\n        finalKnown = true;\n      }\n    } else {\n      throw new Error(\n        `@demlik/tea/recorder: parseJSONL saw an unknown line kind on line ${i + 1}: ` +\n          JSON.stringify((parsed as { kind?: unknown }).kind),\n      );\n    }\n  }\n\n  if (!sawBoot) {\n    throw new Error(\n      \"@demlik/tea/recorder: parseJSONL found no boot header. A trace must start with \" +\n        '{ kind: \"boot\", state }.',\n    );\n  }\n  if (!finalKnown || finalState === null) {\n    throw new Error(\n      \"@demlik/tea/recorder: parseJSONL could not determine finalState — the boot state \" +\n        \"was null and no step carried a non-null state. The trace is unusable for replay.\",\n    );\n  }\n\n  return { loaded, msgs, finalState, steps };\n}\n\n// ---------------------------------------------------------------------------\n// Sentry crash→trace adapters — pure, zero-dependency, Sentry-SHAPED.\n//\n// The killer DevX flow: a machine crashes in prod → its recorded Trace rides\n// along on the Sentry event → one click later you `parseJSONL` it and replay\n// the exact run locally against the (possibly fixed) reducer. These two\n// adapters are the bridge from a `Trace` to the two Sentry surfaces that carry\n// it: an Attachment (the full replayable trace) and Breadcrumbs (a human-\n// readable timeline of the msgs that led to the crash).\n//\n// They take NO dependency on `@sentry/*`. They emit PLAIN OBJECTS whose shapes\n// match Sentry's public `Attachment` and `Breadcrumb` types, and the consumer\n// wires them at their own Sentry boundary (browser or node). This keeps the\n// recorder runnable anywhere a machine runs (a Worker, a Node script, a test)\n// and lets the consumer pin whatever Sentry SDK version they already ship.\n// ---------------------------------------------------------------------------\n\n/**\n * A Sentry-shaped attachment carrying the full {@link Trace} as JSONL. The\n * shape matches Sentry's `Attachment` type so the consumer can hand it\n * straight to `addAttachment(...)` without any adaptation.\n *\n * - `filename`    — `\"tea-trace.jsonl\"`. The name Sentry shows in the UI and\n *                   uses for download; `.jsonl` signals the streamable format.\n * - `data`        — the trace serialized via {@link Recorder.toJSONL}'s format\n *                   (re-hydrate downstream with {@link parseJSONL}).\n * - `contentType` — `\"application/x-ndjson\"`, the standard MIME for\n *                   newline-delimited JSON.\n */\nexport interface TraceAttachment {\n  filename: string;\n  data: string;\n  contentType: string;\n}\n\n/**\n * Serialize a {@link Trace} into a Sentry-shaped attachment so a crash event\n * carries the full, replayable run. Pure — no Sentry import, no I/O. The\n * returned object matches Sentry's `Attachment` shape exactly.\n *\n * The `data` field is JSONL in the same format {@link Recorder.toJSONL}\n * produces, so the home-side flow is `parseJSONL(attachment.data)` →\n * `replayTrace(machine, trace, ctx)`.\n *\n * Consumer wiring (no Sentry import here — the consumer owns the boundary):\n *\n * ```ts\n * import * as Sentry from \"@sentry/browser\"; // or \"@sentry/node\"\n * import { traceAttachment } from \"@demlik/tea/recorder\";\n * Sentry.getCurrentScope().addAttachment(traceAttachment(rec.dump()));\n * ```\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport function traceAttachment<S, M extends { type: string }>(\n  trace: Trace<S, M>,\n): TraceAttachment {\n  return {\n    filename: \"tea-trace.jsonl\",\n    data: traceToJSONL(trace),\n    contentType: \"application/x-ndjson\",\n  };\n}\n\n/** A Sentry-shaped breadcrumb. Matches the fields of Sentry's `Breadcrumb`. */\nexport interface TraceBreadcrumb {\n  category: string;\n  type: string;\n  level: string;\n  message: string;\n  data?: Record<string, unknown>;\n}\n\n/** Options for {@link breadcrumbsFromTrace}. */\nexport interface BreadcrumbsOptions<M> {\n  /**\n   * Max breadcrumbs to emit. Default `100` (Sentry's own default breadcrumb\n   * cap). When the trace has more msgs than `limit`, the OLDEST are dropped —\n   * the returned list is the newest-last tail, matching how a Sentry\n   * breadcrumb ring buffer behaves (the crash context is the recent past).\n   */\n  limit?: number;\n  /**\n   * Customize each breadcrumb's `message`. Default uses `msg.type`. Provide a\n   * serializer to surface a richer one-liner (e.g. include an id). The msg is\n   * ALSO always attached verbatim under `data.msg` regardless of this option,\n   * so the structured payload is never lost to the string rendering.\n   */\n  serialize?: (msg: M) => string;\n}\n\n/**\n * Project a {@link Trace}'s recorded msgs into Sentry-shaped breadcrumbs — a\n * human-readable timeline of \"what happened before the crash\". Pure — no\n * Sentry import, no I/O. Each returned object matches Sentry's `Breadcrumb`\n * shape, so the consumer can loop and call `addBreadcrumb(...)`.\n *\n * One breadcrumb per recorded msg, in dispatch order (NEWEST LAST — Sentry\n * renders breadcrumbs oldest-first and the crash is the most recent event).\n * Each breadcrumb:\n *   - `category` — `\"tea\"` (groups them in the Sentry breadcrumb panel).\n *   - `type`     — `\"default\"` (the generic Sentry breadcrumb type).\n *   - `level`    — `\"info\"` (msgs are normal flow; the crash is the event).\n *   - `message`  — `msg.type`, or `serialize(msg)` when provided.\n *   - `data.msg` — the full msg object (structured detail kept verbatim).\n *\n * Capped at `opts.limit` (default 100). When the trace has more msgs than the\n * cap, the OLDEST are dropped and the newest `limit` are kept — the recent\n * lead-up to the crash is the useful context.\n *\n * Consumer wiring (no Sentry import here — the consumer owns the boundary):\n *\n * ```ts\n * import * as Sentry from \"@sentry/browser\"; // or \"@sentry/node\"\n * import { breadcrumbsFromTrace } from \"@demlik/tea/recorder\";\n * for (const b of breadcrumbsFromTrace(rec.dump())) Sentry.addBreadcrumb(b);\n * ```\n *\n * @typeParam S - the machine's State type.\n * @typeParam M - the machine's Msg union.\n */\nexport function breadcrumbsFromTrace<S, M extends { type: string }>(\n  trace: Trace<S, M>,\n  opts?: BreadcrumbsOptions<M>,\n): TraceBreadcrumb[] {\n  const rawLimit = opts?.limit;\n  // Clamp limit to a non-negative integer. `undefined`/NaN → 100 (Sentry's\n  // default). A negative or zero limit yields an empty list (the caller asked\n  // for no breadcrumbs); fractional values floor (you can't emit half a crumb).\n  const limit =\n    rawLimit === undefined || Number.isNaN(rawLimit)\n      ? 100\n      : Math.max(0, Math.floor(rawLimit));\n  const serialize = opts?.serialize;\n\n  // Keep the NEWEST `limit` msgs (the recent lead-up to the crash). Slicing\n  // from `length - limit` (clamped to 0) preserves dispatch order within the\n  // kept window. Note we do NOT use `slice(-limit)`: `slice(-0)` is `slice(0)`\n  // (JS treats -0 as 0), which would return the WHOLE array for `limit: 0`.\n  const start = Math.max(0, trace.msgs.length - limit);\n  const kept = start === 0 ? trace.msgs : trace.msgs.slice(start);\n\n  const crumbs: TraceBreadcrumb[] = [];\n  for (const msg of kept) {\n    crumbs.push({\n      category: \"tea\",\n      type: \"default\",\n      level: \"info\",\n      message: serialize ? serialize(msg) : msg.type,\n      // Full msg kept verbatim so the structured payload survives even when\n      // `message` is a terse one-liner. Cast: a Msg is a `{ type: string }`\n      // record, which is a `Record<string, unknown>` for Sentry's `data`.\n      data: { msg: msg as unknown as Record<string, unknown> },\n    });\n  }\n  return crumbs;\n}\n\n// ---------------------------------------------------------------------------\n// traceToJSONL — serialize a STANDALONE Trace to JSONL (the dump→file path).\n//\n// `Recorder.toJSONL()` serializes the recorder's live buffers. `traceAttachment`\n// works over a plain `Trace` value (a `dump()` snapshot or a `parseJSONL`\n// result), which has no recorder behind it — so it needs a Trace→JSONL\n// function. This is the same wire format `Recorder.toJSONL` emits and\n// `parseJSONL` reads, so `parseJSONL(traceToJSONL(trace))` round-trips.\n//\n// When `trace.steps` is present (captureSteps was on, or the trace came from\n// parseJSONL), every step line carries its post-state. When absent, interior\n// step states are unknown — emitted as `null`, with `finalState` on the LAST\n// step line (identical to the captureSteps:false path in `Recorder.toJSONL`).\n// ---------------------------------------------------------------------------\nfunction traceToJSONL<S, M>(trace: Trace<S, M>): string {\n  const lines: string[] = [];\n  lines.push(JSON.stringify({ kind: \"boot\", state: trace.loaded }));\n\n  const steps = trace.steps;\n  for (let i = 0; i < trace.msgs.length; i++) {\n    const msg = trace.msgs[i];\n    const stepState = steps\n      ? steps[i]?.state\n      : i === trace.msgs.length - 1\n        ? trace.finalState\n        : null;\n    lines.push(JSON.stringify({ kind: \"step\", msg, state: stepState }));\n  }\n  return lines.join(\"\\n\");\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/resilient-call/index.d.ts

@@ -0,0 +1,251 @@
+import { TtlCache } from '../cache/index.js';
+import { CircuitState } from '../circuit-breaker/index.js';
+import { DeadlineExceeded, DeadlineSub } from '../deadline/index.js';
+export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
+import { C as Cmd } from '../core-CymXZCeY.js';
+import { M as MsgType } from '../protocol-B5YmJr0d.js';
+import { TokenBucket } from '../rate-limit/index.js';
+import { RetryState, RetryPolicy } from '../retry-backoff/index.js';
+import '../types-N9LZbdnr.js';
+
+/**
+ * @demlik/tea/resilient-call — the ROOT composition: a single resilience knob
+ * that bundles cache → circuit-breaker → rate-limit → exponential-backoff retry
+ * (with a deadline-driven retry timer) around any fallible `(input) => Promise`
+ * port.
+ *
+ * This is `examples/resilient-fetch.ts`'s hand-wired `attempt()` generalized:
+ *
+ *   - It is **keyed**. The example tracked one URL at a time; this tracks N
+ *     concurrent logical calls, each under a string `key`. The cache, the
+ *     waiting-retry bookkeeping, and the retry timers are all per-key, while the
+ *     circuit breaker and token bucket are shared (one downstream target, one
+ *     breaker / one bucket — the example's implicit single-target assumption
+ *     made explicit).
+ *   - It is **config-driven**, not hand-wired. You hand `createResilientCall`
+ *     a `ResilientConfig` and get back the uniform knob contract every L2
+ *     composition exposes: `init()`, the four verbs (`attempt` / `succeed` /
+ *     `fail` / `onTimer`), `subs(state)`, and `handlers(ports)`.
+ *   - Every brick is **optional**. Omit `cache` and the cache gate disappears
+ *     (`get` is never consulted); omit `circuit` and every call passes the
+ *     breaker; omit `rateLimit` and the bucket never throttles; omit `retry`
+ *     and a failure is terminal (no backoff, no timer); omit `deadline` and no
+ *     overall wall-clock cap is armed. "Omit a brick → omit its gate" is the
+ *     whole config story — there are no other modes.
+ *
+ * Four later compositions (`llm-call`, `paginated-walk`, `authed-call`,
+ * `reconciler`) inherit THIS slice + verb shape, so the contract here is
+ * load-bearing: the slice is a flat record of brick states, every verb returns
+ * `readonly [State, Cmd[]]`, time is always an `at` / `now` parameter, and the
+ * RNG used for jitter is injected on the config (never read inside a verb).
+ *
+ * ## The two non-negotiables (canon)
+ *
+ *   - **Durable** — the slice is a plain-data Model field (brick states are all
+ *     JSON-serializable), so it survives DO eviction / reload.
+ *   - **Replayable** — every transition is a verb returning new state + Cmds;
+ *     `replay` reconstructs it exactly. Nothing here closes over time or RNG.
+ *
+ * ## Where the clock / RNG live
+ *
+ * Inside the verbs: nowhere. Time arrives as `at` on `attempt` / `onTimer` and
+ * is carried on the result / timer Msgs the consumer dispatches. Jitter RNG is
+ * injected once at `createResilientCall(config, rng)` and threaded into
+ * `nextDelayMs` at the verb boundary — deterministic in tests, `Math.random`
+ * by default. The ONLY clock read is `Date.now()` inside the `handlers` port
+ * (the effect boundary), exactly as `resilient-fetch.ts` stamps its result Msgs.
+ *
+ * ## Typical wiring
+ *
+ *   const rc = createResilientCall<string, Result>({
+ *     cache: { ttlMs: 60_000 },
+ *     circuit: { threshold: 5, cooldownMs: 30_000 },
+ *     rateLimit: { capacity: 10, refillPerSec: 5 },
+ *     retry: defaultRetryPolicy,
+ *     deadline: { ms: 5_000 },
+ *   });
+ *
+ *   // in the machine:
+ *   init: () => [{ resilience: rc.init() }, []],
+ *   update: {
+ *     fetch:   (s, m) => lift(s, rc.attempt(s.resilience, m.key, m.input, m.at)),
+ *     call_ok: (s, m) => lift(s, rc.succeed(s.resilience, m.key, m)),
+ *     call_err:(s, m) => lift(s, rc.fail(s.resilience, m.key, m)),
+ *     retry_due:(s, m) => lift(s, rc.onTimer(s.resilience, m)),
+ *   },
+ *   subscriptions: (s) => rc.subs(s.resilience),
+ *   subscribe: { deadline: subscribeDeadline },
+ *   interpret: rc.handlers({ run: ctx.call }),
+ */
+
+/** Circuit-breaker knob — only the two numbers a consumer ever tunes. */
+interface CircuitConfig {
+    /** Consecutive failures that trip the breaker open. */
+    readonly threshold: number;
+    /** How long the breaker stays open before admitting a probe, in ms. */
+    readonly cooldownMs: number;
+    /**
+     * Probes admitted in `half_open` before fast-failing the rest of the round.
+     * Defaults to 1 (a single probe decides recovery) — matches the circuit-
+     * breaker module's `defaultCircuitPolicy`.
+     */
+    readonly halfOpenMaxProbes?: number;
+}
+/** Token-bucket rate-limit knob. */
+interface RateLimitConfig {
+    /** Burst size — the bucket starts full at `capacity`. */
+    readonly capacity: number;
+    /** Steady-state refill rate, tokens per second. */
+    readonly refillPerSec: number;
+}
+/** Per-entry TTL cache knob. */
+interface CacheConfig {
+    /** How long a cached success stays fresh, in ms. */
+    readonly ttlMs: number;
+}
+/** Overall wall-clock deadline knob — an absolute cap per in-flight call. */
+interface DeadlineConfig {
+    /** Budget from the moment a call starts, in ms. */
+    readonly ms: number;
+}
+/**
+ * The resilience knob. EVERY field is optional: omit a brick and its gate is
+ * skipped entirely (the slice still carries a default brick state so the shape
+ * stays uniform across configs, but the gate is never consulted). An empty
+ * config `{}` is a valid pass-through — a bare effect with no resilience at all.
+ */
+interface ResilientConfig {
+    readonly retry?: RetryPolicy;
+    readonly circuit?: CircuitConfig;
+    readonly rateLimit?: RateLimitConfig;
+    readonly cache?: CacheConfig;
+    readonly deadline?: DeadlineConfig;
+}
+/**
+ * Per-key call phase. `key` indexes a logical call; several can be in flight at
+ * once (the generalization of the example's single `url`). Discriminated on
+ * `phase` so each phase carries only its own data (pattern 11):
+ *
+ *   - `idle`          — never attempted, or fully settled and forgotten.
+ *   - `running`       — the effect Cmd is out; awaiting `succeed` / `fail`.
+ *                       Carries `deadlineAtMs` (absolute cap, `0` if no deadline
+ *                       brick) and the last `input` so a retry can re-issue it.
+ *   - `waiting_retry` — a transient failure backed off; the retry timer is armed
+ *                       for `retryAtMs`. Carries `input` for the re-attempt.
+ *   - `circuit_open`  — the breaker fast-failed this attempt. Terminal for this
+ *                       call until the consumer re-attempts after cooldown.
+ *   - `succeeded`     — settled OK. `result` is the value the port produced.
+ *   - `failed`        — settled Err (out of retries, or no retry brick). `error`
+ *                       carries the last failure.
+ */
+type CallPhase<I, R> = {
+    readonly phase: "idle";
+} | {
+    readonly phase: "running";
+    readonly input: I;
+    readonly deadlineAtMs: number;
+} | {
+    readonly phase: "waiting_retry";
+    readonly input: I;
+    readonly retryAtMs: number;
+    readonly deadlineAtMs: number;
+} | {
+    readonly phase: "circuit_open";
+} | {
+    readonly phase: "succeeded";
+    readonly result: R;
+} | {
+    readonly phase: "failed";
+    readonly error: unknown;
+};
+/**
+ * The slice. `circuit` / `bucket` are SHARED across keys (one downstream target
+ * → one breaker, one bucket). `retry` and `cache` are PER KEY (each logical call
+ * has its own backoff count + cached result), as is the per-call `CallPhase`.
+ * Every field is plain data → the whole slice serializes into a `Store<S>`.
+ *
+ * `retry` / `cache` keep a default brick value even when the corresponding
+ * config brick is omitted, so the slice shape is identical regardless of which
+ * bricks the consumer enabled — the verbs simply never consult the unused brick.
+ */
+interface ResilientState<I, R> {
+    readonly circuit: CircuitState;
+    readonly bucket: TokenBucket;
+    readonly retry: Readonly<Record<string, RetryState>>;
+    readonly cache: TtlCache<R>;
+    readonly calls: Readonly<Record<string, CallPhase<I, R>>>;
+}
+/**
+ * The one effect this knob emits: "run the port for `key` with `input`". The
+ * consumer's `handlers(ports)` interprets it; it carries no closure — `input`
+ * is plain data (invariant 3).
+ */
+type RunCmd<I> = Cmd<typeof MsgType.ResilientRun> & {
+    readonly key: string;
+    readonly input: I;
+};
+/** Settle Msgs the `handlers` port dispatches back. `at` is stamped at the boundary. */
+type SucceedMsg<R> = {
+    readonly type: typeof MsgType.ResilientOk;
+    readonly key: string;
+    readonly result: R;
+    readonly at: number;
+};
+type FailMsg = {
+    readonly type: typeof MsgType.ResilientErr;
+    readonly key: string;
+    readonly error: unknown;
+    readonly at: number;
+};
+/** The retry / deadline timer Msg — `DeadlineExceeded`, keyed by the call `key`. */
+type ResilientTimerMsg = DeadlineExceeded;
+/**
+ * The plain-data error a deadline-failed call settles with. A `{_tag, ...}`
+ * sentinel — NEVER a `new Error(...)` — so the slice stays JSON-serializable
+ * (Error objects round-trip to `{}` and carry a stack trace, both of which break
+ * the slice's durability invariant). `id` / `atMs` echo the timer that fired so
+ * a consumer can attribute the failure to its deadline.
+ */
+type DeadlineExceededError = {
+    readonly _tag: "deadline_exceeded";
+    readonly id: string;
+    readonly atMs: number;
+};
+/** Ports the consumer supplies to `handlers`. */
+interface ResilientPorts<I, R> {
+    /** The fallible work this knob wraps. Throws on failure → routed to `fail`. */
+    readonly run: (input: I, key: string) => Promise<R>;
+}
+/**
+ * Build a resilient-call knob from `config`. `rng` is injected for retry
+ * jitter — pass a fixed `() => 0.5` in tests to pin backoff; defaults to
+ * `Math.random` (read at the verb boundary, never inside a brick op). It is
+ * curried onto the factory rather than threaded through every verb so callers
+ * spell the determinism choice once.
+ *
+ * Returns the uniform L2 knob contract. `I` is the port input type, `R` the
+ * port result type.
+ */
+declare function createResilientCall<I, R>(config: ResilientConfig, rng?: () => number): {
+    init: () => ResilientState<I, R>;
+    attempt: (s: ResilientState<I, R>, key: string, input: I, at: number) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
+    succeed: (s: ResilientState<I, R>, key: string, msg: SucceedMsg<R>) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
+    fail: (s: ResilientState<I, R>, key: string, msg: FailMsg) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
+    settleFailed: (s: ResilientState<I, R>, key: string, error: unknown) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
+    onTimer: (s: ResilientState<I, R>, msg: ResilientTimerMsg) => readonly [ResilientState<I, R>, readonly RunCmd<I>[]];
+    subs: (s: ResilientState<I, R>) => readonly DeadlineSub[];
+    handlers: (ports: ResilientPorts<I, R>) => {
+        resilient_run: (cmd: RunCmd<I>, ctx: Readonly<Record<never, never>>) => Promise<FailMsg | SucceedMsg<R>>;
+    };
+};
+/**
+ * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the
+ * slice lives at `state.resilience`. A convenience for the common single-slice
+ * host; consumers with a differently-named field spread by hand. Pure — a thin
+ * record rebuild, no clock / RNG.
+ */
+declare function liftResilience<S extends {
+    resilience: ResilientState<I, R>;
+}, I, R, C extends Cmd>(state: S, [slice, cmds]: readonly [ResilientState<I, R>, readonly C[]]): readonly [S, readonly C[]];
+
+export { type CacheConfig, type CallPhase, type CircuitConfig, type DeadlineConfig, DeadlineExceeded, type DeadlineExceededError, DeadlineSub, type FailMsg, type RateLimitConfig, type ResilientConfig, type ResilientPorts, type ResilientState, type ResilientTimerMsg, type RunCmd, type SucceedMsg, createResilientCall, liftResilience };

package/dist/resilient-call/index.js

@@ -0,0 +1,13 @@
+export { createResilientCall, liftResilience } from '../chunk-RVJFGRGK.js';
+import '../chunk-JELSZN25.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-QGZW4W3E.js';
+import '../chunk-5VNWZADP.js';
+import '../chunk-2YOE5PIS.js';
+import '../chunk-SC3FAFZN.js';
+import '../chunk-IN33Q4VJ.js';
+import '../chunk-NSDFA6M6.js';
+import '../chunk-2YFLOCWX.js';
+import '../chunk-2WZHS4P2.js';
+import '../chunk-BNJYE4AU.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/resilient-call/index.js.map

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

package/dist/retry-backoff/index.d.ts

@@ -45,6 +45,42 @@
  *                 still de-correlating clients. A common default.
  */
 type Jitter = "none" | "full" | "equal";
+declare const RngBrand: unique symbol;
+/**
+ * A source of uniform randomness in `[0, 1)` — the `Math.random` contract.
+ *
+ * Nominally branded so the `[0, 1)` range is enforced at *construction*, not
+ * by a comment. A raw `() => number` does NOT satisfy `Rng`: a stray `() => 5`
+ * or `() => -1` is rejected by the type before it can ever feed the jitter
+ * math and breach the `0 <= delay <= capMs` postcondition. The only way to
+ * mint an `Rng` is {@link asRng} (or the {@link defaultRng} const), so the
+ * range obligation lives at the boundary where randomness enters the module —
+ * "parse, don't validate" applied to a function value.
+ */
+type Rng = (() => number) & {
+    readonly [RngBrand]: true;
+};
+/**
+ * Brand a `[0, 1)` generator as an {@link Rng}. The single entry point for
+ * randomness into this module: callers (production wiring and tests alike)
+ * pass their raw generator through here, which optionally asserts the contract
+ * and tags the value. The probe is a cheap guard against the most common
+ * misuse (returning a non-unit value); it does not — and cannot — prove
+ * uniformity.
+ *
+ * PURE with respect to the module: it neither reads the clock nor calls the
+ * generator on the module's behalf unless `probe` is set. The probe is opt-in
+ * (default off) so wrapping a hot generator stays allocation- and call-free.
+ *
+ * @throws RangeError if `probe` is enabled and a sampled value is outside `[0, 1)`.
+ */
+declare function asRng(fn: () => number, probe?: boolean): Rng;
+/**
+ * The production default: `Math.random`, branded. Used wherever an `Rng` is
+ * required but the caller omits one — at the effect boundary, never inside a
+ * reducer.
+ */
+declare const defaultRng: Rng;
 /**
  * A retry policy is pure configuration — the knobs of the backoff curve. It
  * carries no mutable state; `RetryState` does. One policy is shared across all
@@ -80,8 +116,9 @@ declare const defaultRetryPolicy: RetryPolicy;
  * default reads `Math.random` only when the caller omits it (at the effect
  * boundary, never inside a reducer).
  *
- * `rng` must return a value in `[0, 1)` (the `Math.random` contract). The
- * returned delay is always in `[0, capMs]` regardless of jitter strategy:
+ * `rng` is an {@link Rng} — a `[0, 1)` generator branded at construction via
+ * {@link asRng}, so a raw `() => 5` can't be passed here. The returned delay
+ * is always in `[0, capMs]` regardless of jitter strategy:
  *   - `"none"`  → exactly the capped exponential `d`.
  *   - `"full"`  → `rng() * d`, uniform in `[0, d]`.
  *   - `"equal"` → `d/2 + rng() * d/2`, uniform in `[d/2, d]`.
@@ -91,7 +128,7 @@ declare const defaultRetryPolicy: RetryPolicy;
  * `baseMs`. `capMs` is also the floor of the clamp, so a misconfigured
  * `capMs < baseMs` still yields a delay within `[0, capMs]`.
  */
-declare function backoffDelay(attempt: number, policy: RetryPolicy, rng?: () => number): number;
+declare function backoffDelay(attempt: number, policy: RetryPolicy, rng?: Rng): number;
 /**
  * Per-operation retry state: how many attempts have failed so far, and the most
  * recent error. `lastError` is `unknown` because the failure can be anything a
@@ -126,6 +163,6 @@ declare function shouldRetry(state: RetryState, policy: RetryPolicy): boolean;
  * attempt index, so the delay grows with each recorded failure. `rng` is
  * injected for determinism, same contract as `backoffDelay`.
  */
-declare function nextDelayMs(state: RetryState, policy: RetryPolicy, rng?: () => number): number;
+declare function nextDelayMs(state: RetryState, policy: RetryPolicy, rng?: Rng): number;
 
-export { type Jitter, type RetryPolicy, type RetryState, backoffDelay, defaultRetryPolicy, initRetry, nextDelayMs, recordFailure, shouldRetry };
+export { type Jitter, type RetryPolicy, type RetryState, type Rng, asRng, backoffDelay, defaultRetryPolicy, defaultRng, initRetry, nextDelayMs, recordFailure, shouldRetry };

package/dist/retry-backoff/index.js

@@ -1,37 +1,3 @@
-// src/retry-backoff/index.ts
-var defaultRetryPolicy = {
-  baseMs: 100,
-  factor: 2,
-  capMs: 3e4,
-  maxAttempts: 5,
-  jitter: "full"
-};
-function backoffDelay(attempt, policy, rng = Math.random) {
-  const safeAttempt = attempt < 0 ? 0 : attempt;
-  const exponential = policy.baseMs * policy.factor ** safeAttempt;
-  const d = Number.isNaN(exponential) ? 0 : Math.min(policy.capMs, exponential);
-  switch (policy.jitter) {
-    case "none":
-      return d;
-    case "full":
-      return Math.min(d, rng() * d);
-    case "equal":
-      return Math.min(d, d / 2 + rng() * (d / 2));
-  }
-}
-function initRetry() {
-  return { attempt: 0 };
-}
-function recordFailure(state, error) {
-  return { attempt: state.attempt + 1, lastError: error };
-}
-function shouldRetry(state, policy) {
-  return state.attempt < policy.maxAttempts;
-}
-function nextDelayMs(state, policy, rng = Math.random) {
-  return backoffDelay(state.attempt, policy, rng);
-}
-
-export { backoffDelay, defaultRetryPolicy, initRetry, nextDelayMs, recordFailure, shouldRetry };
+export { asRng, backoffDelay, defaultRetryPolicy, defaultRng, initRetry, nextDelayMs, recordFailure, shouldRetry } from '../chunk-5VNWZADP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/retry-backoff/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/retry-backoff/index.ts"],"names":[],"mappings":";AA2EO,IAAM,kBAAA,GAAkC;AAAA,EAC7C,MAAA,EAAQ,GAAA;AAAA,EACR,MAAA,EAAQ,CAAA;AAAA,EACR,KAAA,EAAO,GAAA;AAAA,EACP,WAAA,EAAa,CAAA;AAAA,EACb,MAAA,EAAQ;AACV;AAsBO,SAAS,YAAA,CACd,OAAA,EACA,MAAA,EACA,GAAA,GAAoB,KAAK,MAAA,EACjB;AAIR,EAAA,MAAM,WAAA,GAAc,OAAA,GAAU,CAAA,GAAI,CAAA,GAAI,OAAA;AACtC,EAAA,MAAM,WAAA,GAAc,MAAA,CAAO,MAAA,GAAS,MAAA,CAAO,MAAA,IAAU,WAAA;AAMrD,EAAA,MAAM,CAAA,GAAI,MAAA,CAAO,KAAA,CAAM,WAAW,CAAA,GAAI,IAAI,IAAA,CAAK,GAAA,CAAI,MAAA,CAAO,KAAA,EAAO,WAAW,CAAA;AAE5E,EAAA,QAAQ,OAAO,MAAA;AAAQ,IACrB,KAAK,MAAA;AACH,MAAA,OAAO,CAAA;AAAA,IACT,KAAK,MAAA;AAKH,MAAA,OAAO,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,GAAA,KAAQ,CAAC,CAAA;AAAA,IAC9B,KAAK,OAAA;AAGH,MAAA,OAAO,IAAA,CAAK,IAAI,CAAA,EAAG,CAAA,GAAI,IAAI,GAAA,EAAI,IAAK,IAAI,CAAA,CAAE,CAAA;AAAA;AAEhD;AAgBO,SAAS,SAAA,GAAwB;AACtC,EAAA,OAAO,EAAE,SAAS,CAAA,EAAE;AACtB;AAMO,SAAS,aAAA,CAAc,OAAmB,KAAA,EAA4B;AAC3E,EAAA,OAAO,EAAE,OAAA,EAAS,KAAA,CAAM,OAAA,GAAU,CAAA,EAAG,WAAW,KAAA,EAAM;AACxD;AASO,SAAS,WAAA,CAAY,OAAmB,MAAA,EAA8B;AAC3E,EAAA,OAAO,KAAA,CAAM,UAAU,MAAA,CAAO,WAAA;AAChC;AASO,SAAS,WAAA,CACd,KAAA,EACA,MAAA,EACA,GAAA,GAAoB,KAAK,MAAA,EACjB;AACR,EAAA,OAAO,YAAA,CAAa,KAAA,CAAM,OAAA,EAAS,MAAA,EAAQ,GAAG,CAAA;AAChD","file":"index.js","sourcesContent":["/**\n * @demlik/tea/retry-backoff — exponential backoff with jitter + cap, and the\n * retry-attempt state every fallible `interpret` handler folds over.\n *\n * This is a \"pure state + ops\" module in the same mold as\n * `@demlik/tea/work-queue`: a state type plus pure transition functions,\n * storage- and host-agnostic, that a consumer wires into their own reducer /\n * interpret. Nothing here reads the clock or the RNG on its own behalf —\n * randomness is *injected* (`rng`) and time is *computed by the caller* from\n * the millisecond delays this module returns. That keeps every function\n * deterministic and unit-testable, and keeps the substrate's purity invariants\n * intact when the result is threaded through `update` (invariant 2) and the\n * delay is realized as a `Cmd` the runtime performs (invariant 3).\n *\n * Typical wiring:\n *\n *   // in `update`, on a failure Msg:\n *   const retry = recordFailure(state.retry, msg.error);\n *   if (!shouldRetry(retry, policy)) return [toGaveUp(state), []];\n *   const delayMs = nextDelayMs(retry, policy);              // pure: rng injected at call site\n *   return [{ ...state, retry }, [{ type: \"ScheduleRetry\", delayMs, into: TimerFiredRetry }]];\n *\n * The reducer stays pure: `nextDelayMs` is called with the runtime's RNG only\n * at the emit boundary (or the caller defers the whole delay computation to the\n * `interpret` handler and passes `rng` there). Either way the substrate never\n * sees `Math.random()` inside a transition body.\n *\n * NOT a substrate primitive: it depends on nothing from `../index`. It is a\n * leaf utility consumers reach via the `@demlik/tea/retry-backoff` subpath.\n */\n\n/**\n * Jitter strategy applied to the computed backoff delay.\n *\n * Names follow the AWS \"Exponential Backoff And Jitter\" taxonomy (Brooker,\n * 2015), the same vocabulary used by the AWS SDKs and most retry libraries:\n *\n *   - `\"none\"`  — no jitter; the delay is the raw capped exponential `d`.\n *                 Deterministic, but synchronizes retries across clients\n *                 (thundering herd). Use only when callers are already\n *                 de-correlated by other means.\n *   - `\"full\"`  — uniform random in `[0, d]`. Maximum spread; best herd\n *                 avoidance, highest variance in latency.\n *   - `\"equal\"` — `d/2 + random(0, d/2)`, i.e. uniform in `[d/2, d]`. Half the\n *                 delay is fixed, half is jittered: keeps a latency floor while\n *                 still de-correlating clients. A common default.\n */\nexport type Jitter = \"none\" | \"full\" | \"equal\";\n\n/**\n * A retry policy is pure configuration — the knobs of the backoff curve. It\n * carries no mutable state; `RetryState` does. One policy is shared across all\n * the attempts of one logical operation (often a module-scope const).\n */\nexport interface RetryPolicy {\n  /** Delay for attempt 0, in milliseconds, before any jitter or cap. */\n  readonly baseMs: number;\n  /** Geometric growth factor. `2` doubles the delay each attempt. */\n  readonly factor: number;\n  /** Hard ceiling, in milliseconds. The capped exponential never exceeds this. */\n  readonly capMs: number;\n  /**\n   * Maximum number of attempts. `shouldRetry` allows attempts `0 .. maxAttempts-1`,\n   * so `maxAttempts: 3` means \"try once, then retry at most twice\" (attempts 0, 1, 2).\n   */\n  readonly maxAttempts: number;\n  /** Jitter strategy applied to the capped exponential delay. */\n  readonly jitter: Jitter;\n}\n\n/**\n * Sensible defaults: 100ms base, doubling, capped at 30s, up to 5 attempts,\n * full jitter (the herd-avoidance default). Tuned for network calls; override\n * per call site rather than mutating this shared const.\n */\nexport const defaultRetryPolicy: RetryPolicy = {\n  baseMs: 100,\n  factor: 2,\n  capMs: 30_000,\n  maxAttempts: 5,\n  jitter: \"full\",\n};\n\n/**\n * Compute the delay for a given 0-based `attempt` under `policy`.\n *\n * PURE. The exponential is `baseMs * factor ** attempt`, clamped to `capMs`,\n * then jittered. `rng` is injected so the result is deterministic in tests —\n * pass an `rng` returning a fixed value to pin the jitter; the production\n * default reads `Math.random` only when the caller omits it (at the effect\n * boundary, never inside a reducer).\n *\n * `rng` must return a value in `[0, 1)` (the `Math.random` contract). The\n * returned delay is always in `[0, capMs]` regardless of jitter strategy:\n *   - `\"none\"`  → exactly the capped exponential `d`.\n *   - `\"full\"`  → `rng() * d`, uniform in `[0, d]`.\n *   - `\"equal\"` → `d/2 + rng() * d/2`, uniform in `[d/2, d]`.\n *\n * `attempt` is treated as `>= 0`; a negative attempt is clamped to 0 so a\n * caller's off-by-one never produces a fractional exponent or a delay below\n * `baseMs`. `capMs` is also the floor of the clamp, so a misconfigured\n * `capMs < baseMs` still yields a delay within `[0, capMs]`.\n */\nexport function backoffDelay(\n  attempt: number,\n  policy: RetryPolicy,\n  rng: () => number = Math.random,\n): number {\n  // Clamp the attempt to >= 0 so factor ** attempt is never a fractional /\n  // negative exponent. The exponential can overflow to Infinity for large\n  // attempts; Math.min with capMs collapses that back to the ceiling.\n  const safeAttempt = attempt < 0 ? 0 : attempt;\n  const exponential = policy.baseMs * policy.factor ** safeAttempt;\n  // `factor ** attempt` overflows to Infinity for large attempts. With\n  // `baseMs > 0` that's `Infinity`, which Math.min collapses back to `capMs`.\n  // With `baseMs === 0` it's `0 * Infinity === NaN`; a zero base means zero\n  // delay, so treat NaN as 0 (otherwise NaN poisons the comparison and breaks\n  // the `0 <= delay <= capMs` postcondition).\n  const d = Number.isNaN(exponential) ? 0 : Math.min(policy.capMs, exponential);\n\n  switch (policy.jitter) {\n    case \"none\":\n      return d;\n    case \"full\":\n      // Uniform in [0, d]. Math.min re-pins the upper bound: at subnormal /\n      // extreme-precision `d`, `rng() * d` can round one ULP above `d`, which\n      // would breach the documented `delay <= capMs` postcondition. Clamping to\n      // `d` (already <= capMs) makes the invariant hold by construction.\n      return Math.min(d, rng() * d);\n    case \"equal\":\n      // Fixed half + jittered half → uniform in [d/2, d]. Same FP-rounding clamp\n      // as \"full\": `d/2 + rng()*(d/2)` can round above `d` for subnormal `d`.\n      return Math.min(d, d / 2 + rng() * (d / 2));\n  }\n}\n\n/**\n * Per-operation retry state: how many attempts have failed so far, and the most\n * recent error. `lastError` is `unknown` because the failure can be anything a\n * boundary surfaces (an `Error`, a tagged result, a string) — this module never\n * inspects it, it only carries it forward for the consumer's reducer to read.\n */\nexport interface RetryState {\n  /** Count of failures recorded so far. Also the 0-based index of the next attempt. */\n  readonly attempt: number;\n  /** The error from the most recent failure, if any. Carried, never interpreted. */\n  readonly lastError?: unknown;\n}\n\n/** The starting state: zero attempts, no error yet. */\nexport function initRetry(): RetryState {\n  return { attempt: 0 };\n}\n\n/**\n * Record a failed attempt. PURE — returns a *new* state with `attempt`\n * incremented and `lastError` set; the input `state` is never mutated.\n */\nexport function recordFailure(state: RetryState, error: unknown): RetryState {\n  return { attempt: state.attempt + 1, lastError: error };\n}\n\n/**\n * Whether another attempt is permitted under `policy`. PURE.\n *\n * `attempt` is the number of failures recorded so far (= the index of the next\n * attempt). We may retry while that index is below `maxAttempts`, i.e. attempts\n * `0 .. maxAttempts-1` are allowed and the `maxAttempts`-th is refused.\n */\nexport function shouldRetry(state: RetryState, policy: RetryPolicy): boolean {\n  return state.attempt < policy.maxAttempts;\n}\n\n/**\n * The delay to wait before the next attempt, given the current state. PURE.\n *\n * Bridges `RetryState` → `backoffDelay` by using `state.attempt` as the 0-based\n * attempt index, so the delay grows with each recorded failure. `rng` is\n * injected for determinism, same contract as `backoffDelay`.\n */\nexport function nextDelayMs(\n  state: RetryState,\n  policy: RetryPolicy,\n  rng: () => number = Math.random,\n): number {\n  return backoffDelay(state.attempt, policy, rng);\n}\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}