@demlik/tea 0.12.0 → 0.14.0

package/dist/{chunk-FV3Z5MBE.js → chunk-TXN2KFHF.js}

@@ -3,7 +3,7 @@ function at(arr, index) {
   return index < 0 || index >= arr.length ? void 0 : arr[index];
 }
 
-// src/work-queue/ops.ts
+// src/internal/work-queue/ops.ts
 function enqueueOp(queue, input, now, id) {
   const item = {
     id,
@@ -52,6 +52,16 @@ function removeOp(queue, id) {
   return { next, changed: next.length !== queue.length };
 }
 
-export { at, claimNextOp, enqueueOp, markDoneOp, patchItemOp, removeOp, resetRunningOp };
-//# sourceMappingURL=chunk-FV3Z5MBE.js.map
-//# sourceMappingURL=chunk-FV3Z5MBE.js.map
+// src/internal/work-queue/adapter.ts
+function queueAdapter() {
+  return {
+    enqueue: (queue, input, now, id) => enqueueOp(queue, input, now, id),
+    claim: (queue, now) => claimNextOp(queue, now),
+    markDone: (queue, id) => markDoneOp(queue, id),
+    patch: (queue, id, patch) => patchItemOp(queue, id, patch)
+  };
+}
+
+export { at, claimNextOp, enqueueOp, markDoneOp, patchItemOp, queueAdapter, removeOp, resetRunningOp };
+//# sourceMappingURL=chunk-TXN2KFHF.js.map
+//# sourceMappingURL=chunk-TXN2KFHF.js.map

package/dist/chunk-TXN2KFHF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/at.ts","../src/internal/work-queue/ops.ts","../src/internal/work-queue/adapter.ts"],"names":[],"mappings":"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","file":"chunk-TXN2KFHF.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 * from `internal/work-queue/ops`, 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","/**\n * internal/work-queue/adapter — the verb seam over the pure queue ops.\n *\n * The pure ops in `./ops` are the BLESSED transitions, but their names and\n * argument tuples (`enqueueOp(queue, input, now, id)`, `claimNextOp(queue,\n * now)`, …) and their `{ next, item }` / `{ next, changed }` result shapes are\n * the STORE's vocabulary, not the consumer's. An L2 composition that owns a\n * `QueueItem<I>[]` slice (`monitored-run`, `saga`, `idempotent-intake`,\n * `fan-out`) used to import those ops by name and call them directly, so a\n * change to the op surface — or to `QueueItem`'s fields — cascaded to every\n * call site.\n *\n * `QueueAdapter<I>` is the insulating interface: four VERBS (`enqueue` /\n * `claim` / `markDone` / `patch`) that consumers depend on instead of the raw\n * ops. The verbs keep the ops' pure `(queue, …) => { next, … }` contract — they\n * are pure array transforms, no I/O, no `Date.now` (the clock is injected as\n * `now`, exactly as the ops require it) — so a consumer folding the adapter\n * through its reducer stays inside invariant 2 (pure transitions).\n *\n * `queueAdapter<I>()` is the canonical implementation, a thin binding of the\n * blessed ops. Because the verbs are the only surface consumers touch, a\n * `QueueItem` shape change (a new field, a renamed status, a different op\n * signature) is now absorbed HERE — re-bind the verb once — rather than at the\n * 4 consumer call sites. The `patch` verb deliberately takes the same\n * `(item) => item` closure `patchItemOp` does, so the one place a `QueueItem`\n * literal is spread stays the consumer's patch closure, never a re-rolled\n * record.\n *\n * This is an INTERNAL seam (no public-API port): consumers import the adapter\n * from this subpath the same way they imported the ops. The ops remain\n * exported for the in-process `createQueue` adapter (`./index`) and for any\n * call site that genuinely wants the op directly.\n */\n\nimport type { QueueItem } from \"./index\";\nimport { claimNextOp, enqueueOp, markDoneOp, patchItemOp } from \"./ops\";\n\n/**\n * The verb interface over a `QueueItem<I>[]` slice. Each verb mirrors a blessed\n * op's pure contract but speaks the consumer's lifecycle vocabulary, so the\n * consumer never names a `*Op` function or reaches into a `QueueItem` field it\n * did not put there.\n */\nexport interface QueueAdapter<I> {\n  /** Append a new `pending` item stamped `now` under `id`. */\n  enqueue(\n    queue: readonly QueueItem<I>[],\n    input: I,\n    now: number,\n    id: string,\n  ): { next: QueueItem<I>[]; item: QueueItem<I> };\n\n  /**\n   * Claim the first `pending` item — flip it `running`, stamp `startedAt` to\n   * `now` — or `null` if nothing is pending.\n   */\n  claim(\n    queue: readonly QueueItem<I>[],\n    now: number,\n  ): { next: QueueItem<I>[]; claimed: QueueItem<I> } | null;\n\n  /** Drop the item `id` from the queue (completed runs leave the queue). */\n  markDone(\n    queue: readonly QueueItem<I>[],\n    id: string,\n  ): { next: QueueItem<I>[]; changed: boolean };\n\n  /**\n   * Single-item transition: replace the item `id` with `patch(item)`. The\n   * closure is the only place a `QueueItem` literal is constructed, so the\n   * field shape stays out of the consumer's hands except through this verb.\n   */\n  patch(\n    queue: readonly QueueItem<I>[],\n    id: string,\n    patch: (item: QueueItem<I>) => QueueItem<I>,\n  ): { next: QueueItem<I>[]; changed: boolean };\n}\n\n/**\n * The canonical `QueueAdapter<I>`, binding each verb to its blessed op. Pure\n * and stateless — call once at module scope in a consumer and fold its verbs\n * through the reducer. A `QueueItem` shape change is absorbed by re-binding a\n * verb here, not at the consumers.\n */\nexport function queueAdapter<I>(): QueueAdapter<I> {\n  return {\n    enqueue: (queue, input, now, id) => enqueueOp<I>(queue, input, now, id),\n    claim: (queue, now) => claimNextOp<I>(queue, now),\n    markDone: (queue, id) => markDoneOp<I>(queue, id),\n    patch: (queue, id, patch) => patchItemOp<I>(queue, id, patch),\n  };\n}\n"]}

package/dist/{chunk-Q2UM7BXU.js → chunk-VBDU4JL6.js}

@@ -56,5 +56,5 @@ function nextDelayMs(state, policy, rng = defaultRng) {
 }
 
 export { asRng, backoffDelay, defaultRetryPolicy, defaultRng, initRetry, nextDelayMs, recordFailure, retryElapsedMs, shouldRetry };
-//# sourceMappingURL=chunk-Q2UM7BXU.js.map
-//# sourceMappingURL=chunk-Q2UM7BXU.js.map
+//# sourceMappingURL=chunk-VBDU4JL6.js.map
+//# sourceMappingURL=chunk-VBDU4JL6.js.map

package/dist/chunk-VBDU4JL6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/retry-backoff/index.ts"],"names":[],"mappings":"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","file":"chunk-VBDU4JL6.js","sourcesContent":["/**\n * @packageDocumentation\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 * the internal work queue (`src/internal/work-queue/ops.ts`): a state type\n * 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 * and the same wiring under a wall-clock outage budget, where the failure Msg\n * carries the instant it was observed:\n *\n *   // policy: { baseMs: 250, factor: 2, capMs: 4_000, maxElapsedMs: 1_050_000, jitter: \"full\" }\n *   const retry = recordFailure(state.retry, msg.error, msg.at);\n *   if (!shouldRetry(retry, policy, msg.at)) return [toGaveUp(state, retryElapsedMs(retry, msg.at)), []];\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 * ── THE BOUND MAY BE A DURATION, NOT ONLY A COUNT ──────────────────────────\n * `maxAttempts` was the module's only terminal bound, and a count is the wrong\n * bound whenever this ladder nests inside somebody else's ladder. A downstream\n * consumer proved it in production: 4 restarts over a 250ms→4s ladder is ~3.75s\n * of backoff, which nested under a client's own ~2.5s ladder came to roughly\n * SIXTEEN SECONDS of total patience — against a peer that waits ~17.5 MINUTES\n * before it gives up on the other side. A routine deploy outran the budget and\n * killed 170 runs in 7 days that the peer would have resumed from a checkpoint.\n *\n * The failure a count cannot express is that the QUESTION is temporal. \"How\n * long do we tolerate an unreachable peer\" has an answer in seconds, usually\n * derived from the peer's own give-up window; what a count of attempts costs in\n * seconds depends on how long each attempt takes, which is the carrier's\n * business and not the policy's. So a policy may now declare `maxElapsedMs` —\n * a wall-clock outage budget measured from the FIRST failure of the streak —\n * instead of, or in addition to, `maxAttempts`. When both are declared, retry\n * continues only while EVERY declared bound still permits it.\n *\n * TIME IS AN INPUT, NOT AN AMBIENT READ (invariant 2). The streak's origin is\n * supplied by the caller to `recordFailure`, and `shouldRetry` is told `nowMs`;\n * this module still never reads a clock, exactly as it never reads the RNG.\n * The types make the wiring the only wiring that compiles: a duration-bounded\n * policy only satisfies the `shouldRetry` overload that demands a\n * {@link TimedRetryState} *and* a `nowMs`, so \"declared an outage budget, never\n * fed it a clock\" is a type error rather than a bound that quietly never fires.\n *\n * A policy with NO bound at all is likewise unrepresentable by accident — the\n * {@link RetryBudget} union has no \"neither\" arm; forever-retry must be spelled\n * `unbounded: true` ({@link UnboundedRetryPolicy}).\n *\n * Strengthens invariant 2 (transitions are pure — the clock enters as an\n * argument, never as a `Date.now()` inside the fold) and invariant 5\n * (composition is by reduction — the new bound is an additive arm on the policy\n * union and an optional argument on the verbs, so every existing count-bounded\n * call site keeps compiling untouched).\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\ndeclare const RngBrand: unique symbol;\n\n/**\n * A source of uniform randomness in `[0, 1)` — the `Math.random` contract.\n *\n * Nominally branded so the `[0, 1)` range is enforced at *construction*, not\n * by a comment. A raw `() => number` does NOT satisfy `Rng`: a stray `() => 5`\n * or `() => -1` is rejected by the type before it can ever feed the jitter\n * math and breach the `0 <= delay <= capMs` postcondition. The only way to\n * mint an `Rng` is {@link asRng} (or the {@link defaultRng} const), so the\n * range obligation lives at the boundary where randomness enters the module —\n * \"parse, don't validate\" applied to a function value.\n */\nexport type Rng = (() => number) & { readonly [RngBrand]: true };\n\n/**\n * Brand a `[0, 1)` generator as an {@link Rng}. The single entry point for\n * randomness into this module: callers (production wiring and tests alike)\n * pass their raw generator through here, which optionally asserts the contract\n * and tags the value. The probe is a cheap guard against the most common\n * misuse (returning a non-unit value); it does not — and cannot — prove\n * uniformity.\n *\n * PURE with respect to the module: it neither reads the clock nor calls the\n * generator on the module's behalf unless `probe` is set. The probe is opt-in\n * (default off) so wrapping a hot generator stays allocation- and call-free.\n *\n * @throws RangeError if `probe` is enabled and a sampled value is outside `[0, 1)`.\n */\nexport function asRng(fn: () => number, probe = false): Rng {\n  if (probe) {\n    const sample = fn();\n    if (!(sample >= 0 && sample < 1)) {\n      throw new RangeError(\n        `asRng: generator returned ${sample}, outside the [0, 1) contract`,\n      );\n    }\n  }\n  return fn as Rng;\n}\n\n/**\n * The production default: `Math.random`, branded. Used wherever an `Rng` is\n * required but the caller omits one — at the effect boundary, never inside a\n * reducer.\n */\nexport const defaultRng: Rng = Math.random as Rng;\n\n/**\n * The shape of the delay ladder, with no terminal bound attached — `baseMs`,\n * `factor`, `capMs`, `jitter`. Split out from the policy because the curve and\n * the bound answer different questions: the curve is \"how fast do we come\n * back\", the bound is \"when do we stop\". `backoffDelay` needs only the curve.\n */\nexport interface BackoffCurve {\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  /** Jitter strategy applied to the capped exponential delay. */\n  readonly jitter: Jitter;\n}\n\n/**\n * Bound by ATTEMPT COUNT — the original bound, and the right one when each\n * attempt costs about the same and the caller is the outermost ladder.\n *\n * `maxElapsedMs: never` is what keeps this arm honest: a count-bounded policy\n * is *declared* to have no outage budget, so it satisfies the clock-free\n * `shouldRetry` overload. Add `maxElapsedMs` and it becomes a\n * {@link DurationRetryPolicy}, which no longer does.\n */\nexport interface CountBound {\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  readonly maxElapsedMs?: never;\n  readonly unbounded?: never;\n}\n\n/**\n * Bound by WALL-CLOCK OUTAGE DURATION, optionally also by count.\n *\n * `maxElapsedMs` is measured from the FIRST failure of the current streak\n * ({@link TimedRetryState.firstFailureAtMs}), not from the last attempt: the\n * question it answers is \"how long has the far side been unreachable\", which is\n * the question a nesting caller's own patience is denominated in. Derive it\n * from the peer's give-up window rather than restating a guess — two sides\n * holding different answers to one ordered fact is the defect this bound\n * exists to prevent.\n *\n * `maxAttempts` stays available here, and when both are present retry continues\n * only while BOTH still permit it (see {@link shouldRetry}). Adding a count to a\n * duration budget is a belt-and-braces guard against a pathologically fast\n * failure loop, not a substitute for the duration.\n */\nexport interface DurationBound {\n  /**\n   * Outage budget in wall-clock milliseconds. `shouldRetry` permits another\n   * attempt while `nowMs - firstFailureAtMs < maxElapsedMs`, however many\n   * attempts that takes.\n   */\n  readonly maxElapsedMs: number;\n  /** Optional secondary count bound; omitted means \"no count bound\". */\n  readonly maxAttempts?: number;\n  readonly unbounded?: never;\n}\n\n/**\n * No bound at all — retry forever. Deliberately verbose and deliberately the\n * only way to say it: {@link RetryBudget} has no \"neither bound declared\" arm,\n * so an infinite retry loop is something a policy author must write down, never\n * something a forgotten field produces.\n */\nexport interface Unbounded {\n  readonly unbounded: true;\n  readonly maxAttempts?: never;\n  readonly maxElapsedMs?: never;\n}\n\n/**\n * The terminal bound a policy declares: a count, a duration (optionally with a\n * count), or an explicit opt-in to neither. Exactly one arm applies, and there\n * is no arm for \"I forgot\".\n */\nexport type RetryBudget = CountBound | DurationBound | Unbounded;\n\n/**\n * A retry policy is pure configuration — the shape of the backoff curve plus\n * the bound that ends the retrying. It carries no mutable state; `RetryState`\n * does. One policy is shared across all the attempts of one logical operation\n * (often a module-scope const).\n *\n * `RetryPolicy` is the COUNT-bounded shape, unchanged since the module's first\n * release: every existing `{ baseMs, factor, capMs, maxAttempts, jitter }`\n * literal still satisfies it, `policy.maxAttempts` is still a `number` (not\n * `number | undefined`), and `shouldRetry(state, policy)` still takes no clock.\n * Reach for {@link DurationRetryPolicy} when the bound should be temporal, or\n * {@link AnyRetryPolicy} when writing code generic over the bound.\n */\nexport type RetryPolicy = BackoffCurve & CountBound;\n\n/** A curve bounded by wall-clock outage duration (and optionally by count). */\nexport type DurationRetryPolicy = BackoffCurve & DurationBound;\n\n/** A curve with the explicit opt-in to unbounded retry. */\nexport type UnboundedRetryPolicy = BackoffCurve & Unbounded;\n\n/**\n * Any well-formed policy. The parameter type for code that must work whatever\n * bound the caller declared — `shouldRetry`'s implementation, wrappers, and\n * consumers that take a policy from configuration.\n */\nexport type AnyRetryPolicy = BackoffCurve & RetryBudget;\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` is an {@link Rng} — a `[0, 1)` generator branded at construction via\n * {@link asRng}, so a raw `() => 5` can't be passed here. The returned delay\n * 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: BackoffCurve,\n  rng: Rng = defaultRng,\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/**\n * A retry state that also knows WHEN its failure streak began — the origin a\n * duration bound is measured from. Minted by passing the observation instant to\n * {@link recordFailure}; there is no other way to obtain one, so a streak with\n * an outage budget but no origin is not a value that can be written down.\n *\n * The origin is the FIRST failure of the streak and is preserved across\n * subsequent failures. A success resets the streak the way it always did — by\n * returning to `initRetry()` — which drops the origin with it, so an operation\n * that fails occasionally never accumulates outage and pays nothing for a wide\n * `maxElapsedMs`; only an unbroken run of failures grows toward the bound.\n */\nexport interface TimedRetryState extends RetryState {\n  /** When the streak's first failure was observed (caller's clock, epoch ms). */\n  readonly firstFailureAtMs: number;\n}\n\n/** The starting state: zero attempts, no error yet, no streak. */\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 *\n * `atMs` is the instant the failure was OBSERVED, supplied by the caller (the\n * `interpret` handler owns the clock; this module never reads one — invariant\n * 2). Passing it starts the streak clock on the first failure and preserves the\n * original origin on every failure after it, yielding a {@link TimedRetryState}\n * that a duration-bounded policy can be evaluated against. Omit it and the\n * count-bounded behaviour is bit-for-bit what it always was.\n */\nexport function recordFailure(\n  state: TimedRetryState,\n  error: unknown,\n  atMs?: number,\n): TimedRetryState;\nexport function recordFailure(\n  state: RetryState,\n  error: unknown,\n  atMs: number,\n): TimedRetryState;\nexport function recordFailure(state: RetryState, error: unknown): RetryState;\nexport function recordFailure(\n  state: RetryState & { readonly firstFailureAtMs?: number },\n  error: unknown,\n  atMs?: number,\n): RetryState | TimedRetryState {\n  const attempt = state.attempt + 1;\n  // The streak's origin is set once, by whichever failure started it.\n  const firstFailureAtMs = state.firstFailureAtMs ?? atMs;\n  return firstFailureAtMs === undefined\n    ? { attempt, lastError: error }\n    : { attempt, lastError: error, firstFailureAtMs };\n}\n\n/**\n * How long the current failure streak has lasted, in milliseconds. PURE.\n *\n * The honest number for a give-up log — a count of attempts says nothing about\n * how much patience it actually spent. Clamped at 0 so a caller's clock going\n * backwards (NTP step, a rehydrated state whose origin is from a different\n * host) reads as \"no outage yet\" rather than a negative duration.\n */\nexport function retryElapsedMs(state: TimedRetryState, nowMs: number): number {\n  const elapsed = nowMs - state.firstFailureAtMs;\n  return elapsed > 0 ? elapsed : 0;\n}\n\n/**\n * Whether another attempt is permitted under `policy`. PURE.\n *\n * Every bound the policy DECLARES must still permit the attempt; a bound it\n * does not declare is not consulted. Concretely:\n *\n *   - `maxAttempts` — `attempt` is the number of failures recorded so far (= the\n *     index of the next attempt); we may retry while that index is below\n *     `maxAttempts`, i.e. attempts `0 .. maxAttempts-1` are allowed and the\n *     `maxAttempts`-th is refused. Unchanged.\n *   - `maxElapsedMs` — we may retry while `nowMs - firstFailureAtMs` is below\n *     the budget, *however many attempts that takes*. A streak's first failure\n *     measures a zero-length outage and is therefore always retried, unless the\n *     budget is itself `0` (the \"no patience\" setting).\n *   - `unbounded: true` — always permitted.\n *\n * The overloads are the wiring contract. A count-bounded or explicitly\n * unbounded policy needs no clock, so the two-argument call every existing\n * caller already writes keeps type-checking. A policy carrying `maxElapsedMs`\n * matches only the second overload, which demands a {@link TimedRetryState} and\n * a `nowMs` — so declaring an outage budget and then never feeding it a clock\n * fails to compile instead of silently producing a bound that never fires.\n */\nexport function shouldRetry(\n  state: RetryState,\n  policy: BackoffCurve & (CountBound | Unbounded),\n  nowMs?: number,\n): boolean;\nexport function shouldRetry(\n  state: TimedRetryState,\n  policy: AnyRetryPolicy,\n  nowMs: number,\n): boolean;\nexport function shouldRetry(\n  state: RetryState & { readonly firstFailureAtMs?: number },\n  policy: AnyRetryPolicy,\n  nowMs?: number,\n): boolean {\n  if (policy.maxAttempts !== undefined && state.attempt >= policy.maxAttempts) {\n    return false;\n  }\n  if (policy.maxElapsedMs === undefined) return true;\n  // Reachable only from JS callers or an `as`-cast: the overloads make the\n  // origin and the clock mandatory whenever `maxElapsedMs` is declared. Fail to\n  // the visibly-broken side — refuse the retry — rather than treating an\n  // unmeasurable outage as \"still inside the budget\" and retrying forever.\n  if (state.firstFailureAtMs === undefined || nowMs === undefined) return false;\n  return nowMs - state.firstFailureAtMs < policy.maxElapsedMs;\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: BackoffCurve,\n  rng: Rng = defaultRng,\n): number {\n  return backoffDelay(state.attempt, policy, rng);\n}\n"]}