@demlik/tea 0.1.0 → 0.1.1

package/dist/chunk-RVJFGRGK.js

@@ -0,0 +1,222 @@
+import { MsgType } from './chunk-JELSZN25.js';
+import { deadlineSub } from './chunk-QGZW4W3E.js';
+import { asRng, recordFailure, shouldRetry, nextDelayMs, initRetry } from './chunk-5VNWZADP.js';
+import { initBucket, tryConsume } from './chunk-2YOE5PIS.js';
+import { initCircuit, onSuccess, onFailure, canPass } from './chunk-SC3FAFZN.js';
+import { initCache, set, get } from './chunk-IN33Q4VJ.js';
+import { tryInterpret } from './chunk-2WZHS4P2.js';
+
+// src/resilient-call/index.ts
+function circuitPolicy(config) {
+  if (config.circuit === void 0) return null;
+  return {
+    failureThreshold: config.circuit.threshold,
+    cooldownMs: config.circuit.cooldownMs,
+    halfOpenMaxProbes: config.circuit.halfOpenMaxProbes ?? 1
+  };
+}
+function retryTimerId(key) {
+  return `resilient:retry:${key}`;
+}
+function deadlineTimerId(key) {
+  return `resilient:deadline:${key}`;
+}
+function createResilientCall(config, rng = Math.random) {
+  const cPolicy = circuitPolicy(config);
+  const rngBranded = asRng(rng);
+  function init() {
+    return {
+      circuit: initCircuit(),
+      // The bucket carries a default value even without the rateLimit brick so
+      // the slice shape is uniform, but the rate-limit GATE is skipped entirely
+      // when the brick is absent (see `gate`) — the bucket is simply never
+      // consulted. A `0/0` placeholder bucket would be touched by `tryConsume`;
+      // a `1-cap` default is harmless because the gate never calls it.
+      bucket: config.rateLimit ? initBucket(
+        config.rateLimit.capacity,
+        config.rateLimit.refillPerSec,
+        0
+      ) : initBucket(1, 1, 0),
+      retry: {},
+      cache: initCache(),
+      calls: {}
+    };
+  }
+  function retryOf(s, key) {
+    return s.retry[key] ?? initRetry();
+  }
+  function deadlineAt(at) {
+    return config.deadline ? at + config.deadline.ms : 0;
+  }
+  function gate(s, key, input, at, deadlineAtMs) {
+    if (config.cache !== void 0) {
+      const cached = get(s.cache, key, at);
+      if (cached !== void 0) {
+        return [setCall(s, key, { phase: "succeeded", result: cached }), []];
+      }
+    }
+    let bucket = s.bucket;
+    if (config.rateLimit !== void 0) {
+      const [next, hasToken] = tryConsume(bucket, at);
+      bucket = next;
+      if (!hasToken) {
+        return backoff(
+          { ...s, bucket },
+          key,
+          input,
+          "rate_limited",
+          at,
+          deadlineAtMs
+        );
+      }
+    }
+    let circuit = s.circuit;
+    if (cPolicy !== null) {
+      const [next, ok] = canPass(circuit, cPolicy, at);
+      circuit = next;
+      if (!ok) {
+        return [
+          { ...setCall(s, key, { phase: "circuit_open" }), bucket, circuit },
+          []
+        ];
+      }
+    }
+    return [
+      {
+        ...setCall(s, key, { phase: "running", input, deadlineAtMs }),
+        circuit,
+        bucket
+      },
+      [{ type: MsgType.ResilientRun, key, input }]
+    ];
+  }
+  function backoff(s, key, input, error, at, deadlineAtMs) {
+    if (config.retry === void 0) {
+      return [setCall(s, key, { phase: "failed", error }), []];
+    }
+    const retry = recordFailure(retryOf(s, key), error);
+    const withRetry = { ...s, retry: { ...s.retry, [key]: retry } };
+    if (!shouldRetry(retry, config.retry)) {
+      return [setCall(withRetry, key, { phase: "failed", error }), []];
+    }
+    const retryAtMs = at + nextDelayMs(retry, config.retry, rngBranded);
+    return [
+      setCall(withRetry, key, {
+        phase: "waiting_retry",
+        input,
+        retryAtMs,
+        deadlineAtMs
+      }),
+      []
+    ];
+  }
+  function setCall(s, key, phase) {
+    return { ...s, calls: { ...s.calls, [key]: phase } };
+  }
+  function attempt(s, key, input, at) {
+    return gate(s, key, input, at, deadlineAt(at));
+  }
+  function succeed(s, key, msg) {
+    const circuit = cPolicy !== null ? onSuccess(s.circuit, cPolicy) : s.circuit;
+    const cache = config.cache !== void 0 ? set(s.cache, key, msg.result, msg.at, config.cache.ttlMs) : s.cache;
+    const { [key]: _dropped, ...retry } = s.retry;
+    return [
+      {
+        ...setCall(s, key, { phase: "succeeded", result: msg.result }),
+        circuit,
+        cache,
+        retry
+      },
+      []
+    ];
+  }
+  function fail(s, key, msg) {
+    const circuit = cPolicy !== null ? onFailure(s.circuit, cPolicy, msg.at) : s.circuit;
+    const withCircuit = { ...s, circuit };
+    const call = s.calls[key];
+    const input = call?.phase === "running" ? call.input : void 0;
+    const deadlineAtMs = call?.phase === "running" ? call.deadlineAtMs : deadlineAt(msg.at);
+    if (input === void 0) {
+      return [
+        setCall(withCircuit, key, { phase: "failed", error: msg.error }),
+        []
+      ];
+    }
+    return backoff(withCircuit, key, input, msg.error, msg.at, deadlineAtMs);
+  }
+  function settleFailed(s, key, error) {
+    return [setCall(s, key, { phase: "failed", error }), []];
+  }
+  function onTimer(s, msg) {
+    for (const [key, call] of Object.entries(s.calls)) {
+      if (msg.id === retryTimerId(key)) {
+        if (call.phase !== "waiting_retry") return [s, []];
+        return gate(s, key, call.input, msg.atMs, call.deadlineAtMs);
+      }
+      if (msg.id === deadlineTimerId(key)) {
+        if (call.phase !== "running" && call.phase !== "waiting_retry")
+          return [s, []];
+        return [
+          setCall(s, key, {
+            phase: "failed",
+            error: {
+              _tag: "deadline_exceeded",
+              id: msg.id,
+              atMs: msg.atMs
+            }
+          }),
+          []
+        ];
+      }
+    }
+    return [s, []];
+  }
+  function subs(s) {
+    const out = [];
+    for (const [key, call] of Object.entries(s.calls)) {
+      if (call.phase === "waiting_retry") {
+        out.push(deadlineSub(retryTimerId(key), call.retryAtMs));
+      }
+      if (config.deadline !== void 0 && (call.phase === "running" || call.phase === "waiting_retry") && call.deadlineAtMs > 0) {
+        out.push(deadlineSub(deadlineTimerId(key), call.deadlineAtMs));
+      }
+    }
+    return out;
+  }
+  function handlers(ports) {
+    return {
+      resilient_run: tryInterpret(
+        (cmd) => ports.run(cmd.input, cmd.key),
+        (result, cmd) => ({
+          type: MsgType.ResilientOk,
+          key: cmd.key,
+          result,
+          at: Date.now()
+        }),
+        (error, cmd) => ({
+          type: MsgType.ResilientErr,
+          key: cmd.key,
+          error,
+          at: Date.now()
+        })
+      )
+    };
+  }
+  return {
+    init,
+    attempt,
+    succeed,
+    fail,
+    settleFailed,
+    onTimer,
+    subs,
+    handlers
+  };
+}
+function liftResilience(state, [slice, cmds]) {
+  return [{ ...state, resilience: slice }, cmds];
+}
+
+export { createResilientCall, liftResilience };
+//# sourceMappingURL=chunk-RVJFGRGK.js.map
+//# sourceMappingURL=chunk-RVJFGRGK.js.map

package/dist/chunk-RVJFGRGK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/resilient-call/index.ts"],"names":[],"mappings":"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","file":"chunk-RVJFGRGK.js","sourcesContent":["/**\n * @demlik/tea/resilient-call — the ROOT composition: a single resilience knob\n * that bundles cache → circuit-breaker → rate-limit → exponential-backoff retry\n * (with a deadline-driven retry timer) around any fallible `(input) => Promise`\n * port.\n *\n * This is `examples/resilient-fetch.ts`'s hand-wired `attempt()` generalized:\n *\n *   - It is **keyed**. The example tracked one URL at a time; this tracks N\n *     concurrent logical calls, each under a string `key`. The cache, the\n *     waiting-retry bookkeeping, and the retry timers are all per-key, while the\n *     circuit breaker and token bucket are shared (one downstream target, one\n *     breaker / one bucket — the example's implicit single-target assumption\n *     made explicit).\n *   - It is **config-driven**, not hand-wired. You hand `createResilientCall`\n *     a `ResilientConfig` and get back the uniform knob contract every L2\n *     composition exposes: `init()`, the four verbs (`attempt` / `succeed` /\n *     `fail` / `onTimer`), `subs(state)`, and `handlers(ports)`.\n *   - Every brick is **optional**. Omit `cache` and the cache gate disappears\n *     (`get` is never consulted); omit `circuit` and every call passes the\n *     breaker; omit `rateLimit` and the bucket never throttles; omit `retry`\n *     and a failure is terminal (no backoff, no timer); omit `deadline` and no\n *     overall wall-clock cap is armed. \"Omit a brick → omit its gate\" is the\n *     whole config story — there are no other modes.\n *\n * Four later compositions (`llm-call`, `paginated-walk`, `authed-call`,\n * `reconciler`) inherit THIS slice + verb shape, so the contract here is\n * load-bearing: the slice is a flat record of brick states, every verb returns\n * `readonly [State, Cmd[]]`, time is always an `at` / `now` parameter, and the\n * RNG used for jitter is injected on the config (never read inside a verb).\n *\n * ## The two non-negotiables (canon)\n *\n *   - **Durable** — the slice is a plain-data Model field (brick states are all\n *     JSON-serializable), so it survives DO eviction / reload.\n *   - **Replayable** — every transition is a verb returning new state + Cmds;\n *     `replay` reconstructs it exactly. Nothing here closes over time or RNG.\n *\n * ## Where the clock / RNG live\n *\n * Inside the verbs: nowhere. Time arrives as `at` on `attempt` / `onTimer` and\n * is carried on the result / timer Msgs the consumer dispatches. Jitter RNG is\n * injected once at `createResilientCall(config, rng)` and threaded into\n * `nextDelayMs` at the verb boundary — deterministic in tests, `Math.random`\n * by default. The ONLY clock read is `Date.now()` inside the `handlers` port\n * (the effect boundary), exactly as `resilient-fetch.ts` stamps its result Msgs.\n *\n * ## Typical wiring\n *\n *   const rc = createResilientCall<string, Result>({\n *     cache: { ttlMs: 60_000 },\n *     circuit: { threshold: 5, cooldownMs: 30_000 },\n *     rateLimit: { capacity: 10, refillPerSec: 5 },\n *     retry: defaultRetryPolicy,\n *     deadline: { ms: 5_000 },\n *   });\n *\n *   // in the machine:\n *   init: () => [{ resilience: rc.init() }, []],\n *   update: {\n *     fetch:   (s, m) => lift(s, rc.attempt(s.resilience, m.key, m.input, m.at)),\n *     call_ok: (s, m) => lift(s, rc.succeed(s.resilience, m.key, m)),\n *     call_err:(s, m) => lift(s, rc.fail(s.resilience, m.key, m)),\n *     retry_due:(s, m) => lift(s, rc.onTimer(s.resilience, m)),\n *   },\n *   subscriptions: (s) => rc.subs(s.resilience),\n *   subscribe: { deadline: subscribeDeadline },\n *   interpret: rc.handlers({ run: ctx.call }),\n */\n\nimport {\n  get as cacheGet,\n  set as cacheSet,\n  initCache,\n  type TtlCache,\n} from \"../cache\";\nimport {\n  type CircuitState,\n  canPass,\n  initCircuit,\n  onFailure,\n  onSuccess,\n} from \"../circuit-breaker\";\nimport {\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineSub,\n  subscribeDeadline,\n} from \"../deadline\";\nimport { type Cmd, type NoCtx, tryInterpret } from \"../index\";\nimport { MsgType } from \"../protocol\";\nimport { initBucket, type TokenBucket, tryConsume } from \"../rate-limit\";\nimport {\n  asRng,\n  initRetry,\n  nextDelayMs,\n  type RetryPolicy,\n  type RetryState,\n  recordFailure,\n  shouldRetry,\n} from \"../retry-backoff\";\n\n// ===========================================================================\n// Config — the knob. Every brick optional; omit a brick → omit its gate.\n// ===========================================================================\n\n/** Circuit-breaker knob — only the two numbers a consumer ever tunes. */\nexport interface CircuitConfig {\n  /** Consecutive failures that trip the breaker open. */\n  readonly threshold: number;\n  /** How long the breaker stays open before admitting a probe, in ms. */\n  readonly cooldownMs: number;\n  /**\n   * Probes admitted in `half_open` before fast-failing the rest of the round.\n   * Defaults to 1 (a single probe decides recovery) — matches the circuit-\n   * breaker module's `defaultCircuitPolicy`.\n   */\n  readonly halfOpenMaxProbes?: number;\n}\n\n/** Token-bucket rate-limit knob. */\nexport interface RateLimitConfig {\n  /** Burst size — the bucket starts full at `capacity`. */\n  readonly capacity: number;\n  /** Steady-state refill rate, tokens per second. */\n  readonly refillPerSec: number;\n}\n\n/** Per-entry TTL cache knob. */\nexport interface CacheConfig {\n  /** How long a cached success stays fresh, in ms. */\n  readonly ttlMs: number;\n}\n\n/** Overall wall-clock deadline knob — an absolute cap per in-flight call. */\nexport interface DeadlineConfig {\n  /** Budget from the moment a call starts, in ms. */\n  readonly ms: number;\n}\n\n/**\n * The resilience knob. EVERY field is optional: omit a brick and its gate is\n * skipped entirely (the slice still carries a default brick state so the shape\n * stays uniform across configs, but the gate is never consulted). An empty\n * config `{}` is a valid pass-through — a bare effect with no resilience at all.\n */\nexport interface ResilientConfig {\n  readonly retry?: RetryPolicy;\n  readonly circuit?: CircuitConfig;\n  readonly rateLimit?: RateLimitConfig;\n  readonly cache?: CacheConfig;\n  readonly deadline?: DeadlineConfig;\n}\n\n// ===========================================================================\n// Slice — the Model field this knob owns. A flat record of brick states.\n// ===========================================================================\n\n/**\n * Per-key call phase. `key` indexes a logical call; several can be in flight at\n * once (the generalization of the example's single `url`). Discriminated on\n * `phase` so each phase carries only its own data (pattern 11):\n *\n *   - `idle`          — never attempted, or fully settled and forgotten.\n *   - `running`       — the effect Cmd is out; awaiting `succeed` / `fail`.\n *                       Carries `deadlineAtMs` (absolute cap, `0` if no deadline\n *                       brick) and the last `input` so a retry can re-issue it.\n *   - `waiting_retry` — a transient failure backed off; the retry timer is armed\n *                       for `retryAtMs`. Carries `input` for the re-attempt.\n *   - `circuit_open`  — the breaker fast-failed this attempt. Terminal for this\n *                       call until the consumer re-attempts after cooldown.\n *   - `succeeded`     — settled OK. `result` is the value the port produced.\n *   - `failed`        — settled Err (out of retries, or no retry brick). `error`\n *                       carries the last failure.\n */\nexport type CallPhase<I, R> =\n  | { readonly phase: \"idle\" }\n  | {\n      readonly phase: \"running\";\n      readonly input: I;\n      readonly deadlineAtMs: number;\n    }\n  | {\n      readonly phase: \"waiting_retry\";\n      readonly input: I;\n      readonly retryAtMs: number;\n      readonly deadlineAtMs: number;\n    }\n  | { readonly phase: \"circuit_open\" }\n  | { readonly phase: \"succeeded\"; readonly result: R }\n  | { readonly phase: \"failed\"; readonly error: unknown };\n\n/**\n * The slice. `circuit` / `bucket` are SHARED across keys (one downstream target\n * → one breaker, one bucket). `retry` and `cache` are PER KEY (each logical call\n * has its own backoff count + cached result), as is the per-call `CallPhase`.\n * Every field is plain data → the whole slice serializes into a `Store<S>`.\n *\n * `retry` / `cache` keep a default brick value even when the corresponding\n * config brick is omitted, so the slice shape is identical regardless of which\n * bricks the consumer enabled — the verbs simply never consult the unused brick.\n */\nexport interface ResilientState<I, R> {\n  readonly circuit: CircuitState;\n  readonly bucket: TokenBucket;\n  readonly retry: Readonly<Record<string, RetryState>>;\n  readonly cache: TtlCache<R>;\n  readonly calls: Readonly<Record<string, CallPhase<I, R>>>;\n}\n\n// ===========================================================================\n// Cmds + Msgs the knob speaks. Generic over the port input `I`.\n// ===========================================================================\n\n/**\n * The one effect this knob emits: \"run the port for `key` with `input`\". The\n * consumer's `handlers(ports)` interprets it; it carries no closure — `input`\n * is plain data (invariant 3).\n */\nexport type RunCmd<I> = Cmd<typeof MsgType.ResilientRun> & {\n  readonly key: string;\n  readonly input: I;\n};\n\n/** Settle Msgs the `handlers` port dispatches back. `at` is stamped at the boundary. */\nexport type SucceedMsg<R> = {\n  readonly type: typeof MsgType.ResilientOk;\n  readonly key: string;\n  readonly result: R;\n  readonly at: number;\n};\nexport type FailMsg = {\n  readonly type: typeof MsgType.ResilientErr;\n  readonly key: string;\n  readonly error: unknown;\n  readonly at: number;\n};\n\n/** The retry / deadline timer Msg — `DeadlineExceeded`, keyed by the call `key`. */\nexport type ResilientTimerMsg = DeadlineExceeded;\n\n/**\n * The plain-data error a deadline-failed call settles with. A `{_tag, ...}`\n * sentinel — NEVER a `new Error(...)` — so the slice stays JSON-serializable\n * (Error objects round-trip to `{}` and carry a stack trace, both of which break\n * the slice's durability invariant). `id` / `atMs` echo the timer that fired so\n * a consumer can attribute the failure to its deadline.\n */\nexport type DeadlineExceededError = {\n  readonly _tag: \"deadline_exceeded\";\n  readonly id: string;\n  readonly atMs: number;\n};\n\n/** Ports the consumer supplies to `handlers`. */\nexport interface ResilientPorts<I, R> {\n  /** The fallible work this knob wraps. Throws on failure → routed to `fail`. */\n  readonly run: (input: I, key: string) => Promise<R>;\n}\n\n// ===========================================================================\n// Internal brick-policy derivation — config → the L1 policy shapes.\n// ===========================================================================\n\n// A circuit policy is only built when the brick is configured; absence is\n// represented as `null` so the gate can short-circuit to \"always pass\".\nfunction circuitPolicy(config: ResilientConfig) {\n  if (config.circuit === undefined) return null;\n  return {\n    failureThreshold: config.circuit.threshold,\n    cooldownMs: config.circuit.cooldownMs,\n    halfOpenMaxProbes: config.circuit.halfOpenMaxProbes ?? 1,\n  };\n}\n\n// Sub-id families. Each call's retry timer is a deadline keyed by `key`, so a\n// machine running many concurrent calls reconciles each independently.\nfunction retryTimerId(key: string): string {\n  return `resilient:retry:${key}`;\n}\nfunction deadlineTimerId(key: string): string {\n  return `resilient:deadline:${key}`;\n}\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build a resilient-call knob from `config`. `rng` is injected for retry\n * jitter — pass a fixed `() => 0.5` in tests to pin backoff; defaults to\n * `Math.random` (read at the verb boundary, never inside a brick op). It is\n * curried onto the factory rather than threaded through every verb so callers\n * spell the determinism choice once.\n *\n * Returns the uniform L2 knob contract. `I` is the port input type, `R` the\n * port result type.\n */\nexport function createResilientCall<I, R>(\n  config: ResilientConfig,\n  rng: () => number = Math.random,\n) {\n  const cPolicy = circuitPolicy(config);\n  // Re-affirm the `[0, 1)` contract at the seam where the injected generator\n  // feeds the backoff math (brand from `../retry-backoff`). The factory's\n  // public param stays a plain `() => number` so transitive callers are\n  // unchanged; `asRng` is the single point it's branded for `nextDelayMs`.\n  const rngBranded = asRng(rng);\n\n  /** The starting slice. Bricks not in `config` still get a default value. */\n  function init(): ResilientState<I, R> {\n    return {\n      circuit: initCircuit(),\n      // The bucket carries a default value even without the rateLimit brick so\n      // the slice shape is uniform, but the rate-limit GATE is skipped entirely\n      // when the brick is absent (see `gate`) — the bucket is simply never\n      // consulted. A `0/0` placeholder bucket would be touched by `tryConsume`;\n      // a `1-cap` default is harmless because the gate never calls it.\n      bucket: config.rateLimit\n        ? initBucket(\n            config.rateLimit.capacity,\n            config.rateLimit.refillPerSec,\n            0,\n          )\n        : initBucket(1, 1, 0),\n      retry: {},\n      cache: initCache<R>(),\n      calls: {},\n    };\n  }\n\n  /** Read this key's retry state, defaulting to a fresh one. */\n  function retryOf(s: ResilientState<I, R>, key: string): RetryState {\n    return s.retry[key] ?? initRetry();\n  }\n\n  /** Compute the absolute deadline for a call starting at `at` (0 = no cap). */\n  function deadlineAt(at: number): number {\n    return config.deadline ? at + config.deadline.ms : 0;\n  }\n\n  /**\n   * The shared decision: cache → rate-limit → circuit gate, then either emit\n   * the effect or schedule a retry. `deadlineAtMs` is threaded so a re-attempt\n   * (from `onTimer`) keeps the ORIGINAL overall deadline rather than restarting\n   * it. PURE — `at` is the only clock; `rng` is the injected jitter source.\n   *\n   * Used by both `attempt` (fresh call) and `onTimer` (retry timer fired) so\n   * the gate logic lives in exactly one place — the example's shared `attempt`\n   * helper, lifted to a keyed knob.\n   *\n   * ## Why rate-limit is gated BEFORE the circuit probe\n   *\n   * The circuit-breaker's `canPass` is not a passive read: in `half_open` it\n   * *consumes* a probe slot (advancing `probes`), and the consumed slot is only\n   * released when a probe RESOLVES via `onSuccess` / `onFailure`. So a probe\n   * slot may only be taken when this attempt is actually going to reach the\n   * backend (i.e. emit the `resilient_run` Cmd). The rate-limit gate can reject\n   * an attempt and return a backoff WITHOUT any Cmd — no backend call, so no\n   * settle Msg ever comes back. If the circuit probe were consumed first, that\n   * rate-limited attempt would burn the half-open probe budget on a call that\n   * never happened, wedging the breaker `half_open` at its probe cap forever\n   * (nothing moves it out of `half_open` but a resolved probe). Running the\n   * rate-limit gate first means the circuit probe is consumed ONLY on the path\n   * that emits the effect.\n   */\n  function gate(\n    s: ResilientState<I, R>,\n    key: string,\n    input: I,\n    at: number,\n    deadlineAtMs: number,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    // 1) Serve from cache if fresh — no effect at all. Skipped when no cache brick.\n    if (config.cache !== undefined) {\n      const cached = cacheGet(s.cache, key, at);\n      if (cached !== undefined) {\n        return [setCall(s, key, { phase: \"succeeded\", result: cached }), []];\n      }\n    }\n\n    // 2) Rate-limit gate FIRST — it may reject with no Cmd, so it must run\n    // before any circuit probe is consumed (see header note). Skipped entirely\n    // when no rateLimit brick — the bucket is never consulted, so the default\n    // placeholder bucket stays untouched.\n    let bucket = s.bucket;\n    if (config.rateLimit !== undefined) {\n      const [next, hasToken] = tryConsume(bucket, at);\n      bucket = next;\n      if (!hasToken) {\n        // Rate-limited: treat as a transient failure and back off via retry.\n        // The circuit is untouched — no probe is spent on a call that never ran.\n        return backoff(\n          { ...s, bucket },\n          key,\n          input,\n          \"rate_limited\",\n          at,\n          deadlineAtMs,\n        );\n      }\n    }\n\n    // 3) Circuit-breaker gate. `null` policy → no breaker → always pass. Reached\n    // only once a token is secured, so a half-open probe is consumed exclusively\n    // on the path that emits the effect below.\n    let circuit = s.circuit;\n    if (cPolicy !== null) {\n      const [next, ok] = canPass(circuit, cPolicy, at);\n      circuit = next;\n      if (!ok) {\n        return [\n          { ...setCall(s, key, { phase: \"circuit_open\" }), bucket, circuit },\n          [],\n        ];\n      }\n    }\n\n    // 4) All gates passed — emit the effect as data.\n    return [\n      {\n        ...setCall(s, key, { phase: \"running\", input, deadlineAtMs }),\n        circuit,\n        bucket,\n      },\n      [{ type: MsgType.ResilientRun, key, input }],\n    ];\n  }\n\n  /**\n   * Back off after a transient failure: record it, and if `retry` permits\n   * another attempt, enter `waiting_retry` with the retry timer armed; else\n   * settle `failed`. When no `retry` brick is configured the call fails on the\n   * first failure (no backoff, no timer). PURE.\n   */\n  function backoff(\n    s: ResilientState<I, R>,\n    key: string,\n    input: I,\n    error: unknown,\n    at: number,\n    deadlineAtMs: number,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    if (config.retry === undefined) {\n      return [setCall(s, key, { phase: \"failed\", error }), []];\n    }\n    const retry = recordFailure(retryOf(s, key), error);\n    const withRetry = { ...s, retry: { ...s.retry, [key]: retry } };\n    if (!shouldRetry(retry, config.retry)) {\n      return [setCall(withRetry, key, { phase: \"failed\", error }), []];\n    }\n    const retryAtMs = at + nextDelayMs(retry, config.retry, rngBranded);\n    return [\n      setCall(withRetry, key, {\n        phase: \"waiting_retry\",\n        input,\n        retryAtMs,\n        deadlineAtMs,\n      }),\n      [],\n    ];\n  }\n\n  // Set the phase for one key, leaving every other field untouched.\n  function setCall(\n    s: ResilientState<I, R>,\n    key: string,\n    phase: CallPhase<I, R>,\n  ): ResilientState<I, R> {\n    return { ...s, calls: { ...s.calls, [key]: phase } };\n  }\n\n  // === Verb: attempt =======================================================\n\n  /**\n   * Start (or restart) the call for `key` with `input` at time `at`. Runs the\n   * cache → circuit → rate-limit gate and either emits the `resilient_run`\n   * effect, schedules a retry, fast-fails (circuit open), or serves the cache.\n   * PURE.\n   */\n  function attempt(\n    s: ResilientState<I, R>,\n    key: string,\n    input: I,\n    at: number,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    return gate(s, key, input, at, deadlineAt(at));\n  }\n\n  // === Verb: succeed =======================================================\n\n  /**\n   * Record a success for `key`: close the breaker, fill the cache (if a cache\n   * brick exists), reset this key's retry count, and settle `succeeded`. PURE —\n   * `msg.at` is the cache write clock.\n   */\n  function succeed(\n    s: ResilientState<I, R>,\n    key: string,\n    msg: SucceedMsg<R>,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    const circuit =\n      cPolicy !== null ? onSuccess(s.circuit, cPolicy) : s.circuit;\n    const cache =\n      config.cache !== undefined\n        ? cacheSet(s.cache, key, msg.result, msg.at, config.cache.ttlMs)\n        : s.cache;\n    // Drop this key's retry counter — a success ends the retry run.\n    const { [key]: _dropped, ...retry } = s.retry;\n    return [\n      {\n        ...setCall(s, key, { phase: \"succeeded\", result: msg.result }),\n        circuit,\n        cache,\n        retry,\n      },\n      [],\n    ];\n  }\n\n  // === Verb: fail ==========================================================\n\n  /**\n   * Record a failure for `key`: trip the breaker (it may open), then back off —\n   * schedule a retry if `retry` permits, else settle `failed`. PURE — `msg.at`\n   * stamps the breaker trip + the retry delay base. Re-issues from the call's\n   * remembered `input` and preserves the original overall `deadlineAtMs`.\n   */\n  function fail(\n    s: ResilientState<I, R>,\n    key: string,\n    msg: FailMsg,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    const circuit =\n      cPolicy !== null ? onFailure(s.circuit, cPolicy, msg.at) : s.circuit;\n    const withCircuit = { ...s, circuit };\n    const call = s.calls[key];\n    const input = call?.phase === \"running\" ? call.input : undefined;\n    const deadlineAtMs =\n      call?.phase === \"running\" ? call.deadlineAtMs : deadlineAt(msg.at);\n    // No remembered input (e.g. a stray fail for a key not running) → just\n    // settle failed after tripping the breaker; nothing to re-issue.\n    if (input === undefined) {\n      return [\n        setCall(withCircuit, key, { phase: \"failed\", error: msg.error }),\n        [],\n      ];\n    }\n    return backoff(withCircuit, key, input, msg.error, msg.at, deadlineAtMs);\n  }\n\n  // === Verb: settleFailed ==================================================\n\n  /**\n   * Settle `key` to terminal `failed` with `error` WITHOUT touching the circuit\n   * breaker or this key's retry counter. PURE.\n   *\n   * This is the verb for a failure that is NOT a downstream-health signal: the\n   * call must end now, but the breaker must not trip and the backoff run must\n   * not advance. `fail` is the opposite — it records the failure against the\n   * breaker (it may open) and feeds the retry policy (it may back off). Use\n   * `settleFailed` when the *reason* the call cannot proceed has nothing to do\n   * with downstream health:\n   *\n   *   - `authed-call` settles a 401 it cannot fix (e.g. the refresh budget is\n   *     spent): a bad token is the caller's problem, not the backend's —\n   *     tripping the breaker on it would punish a healthy target, and backing\n   *     off would just retry a request that will 401 again.\n   *   - `paginated-walk` settles a terminal walk error (e.g. a malformed page\n   *     the consumer rejects) that should stop the walk without poisoning the\n   *     shared breaker the next page fetch passes through.\n   *\n   * Because it leaves `circuit` and `retry[key]` untouched, the breaker keeps\n   * its health view of the actual backend and a later `attempt` for this key\n   * starts a fresh retry run. Both sibling knobs previously hand-rolled this by\n   * splicing `calls` directly; this verb gives them one named, tested entry\n   * point so the slice's settle invariants live in exactly one place.\n   */\n  function settleFailed(\n    s: ResilientState<I, R>,\n    key: string,\n    error: unknown,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    return [setCall(s, key, { phase: \"failed\", error }), []];\n  }\n\n  // === Verb: onTimer =======================================================\n\n  /**\n   * A timer fired for some key. Two kinds, disambiguated by the Sub id:\n   *\n   *   - retry timer    → re-run the gate for that key's remembered input,\n   *                      re-checking the circuit + bucket at THIS time.\n   *   - deadline timer → the overall budget elapsed → settle `failed` with a\n   *                      deadline error, no matter the current phase.\n   *\n   * A timer for a key no longer `waiting_retry` (retry) / no longer in flight\n   * (deadline) is a no-op — the reconcile pass races the result; the verb must\n   * tolerate a stale fire. PURE.\n   */\n  function onTimer(\n    s: ResilientState<I, R>,\n    msg: ResilientTimerMsg,\n  ): readonly [ResilientState<I, R>, readonly RunCmd<I>[]] {\n    for (const [key, call] of Object.entries(s.calls)) {\n      if (msg.id === retryTimerId(key)) {\n        if (call.phase !== \"waiting_retry\") return [s, []];\n        return gate(s, key, call.input, msg.atMs, call.deadlineAtMs);\n      }\n      if (msg.id === deadlineTimerId(key)) {\n        // Deadline only fires for a still-active call. A settled call has no\n        // armed deadline Sub, but tolerate a stale fire defensively.\n        if (call.phase !== \"running\" && call.phase !== \"waiting_retry\")\n          return [s, []];\n        // Plain-data sentinel, NOT a `new Error(...)`: an Error object is not\n        // JSON-serializable (it round-trips to `{}`) and captures a stack trace,\n        // both of which break the slice's durability invariant once it is\n        // persisted into a `Store<S>` and reloaded. A `{_tag, ...}` record keeps\n        // the slice round-trip-equal under JSON.parse(JSON.stringify(...)).\n        return [\n          setCall(s, key, {\n            phase: \"failed\",\n            error: {\n              _tag: \"deadline_exceeded\",\n              id: msg.id,\n              atMs: msg.atMs,\n            } satisfies DeadlineExceededError,\n          }),\n          [],\n        ];\n      }\n    }\n    return [s, []];\n  }\n\n  // === Subs ================================================================\n\n  /**\n   * Pre-wired subscriptions: a retry timer for every `waiting_retry` call, and\n   * (when the `deadline` brick is configured) an overall deadline timer for\n   * every still-active call. Both are `DeadlineSub`s reconciled by id, so a\n   * phase change cancels the matching timer automatically — no manual\n   * `clearTimeout`. Wire `subscribe: { deadline: subscribeDeadline }`.\n   */\n  function subs(s: ResilientState<I, R>): readonly DeadlineSub[] {\n    const out: DeadlineSub[] = [];\n    for (const [key, call] of Object.entries(s.calls)) {\n      if (call.phase === \"waiting_retry\") {\n        out.push(deadlineSub(retryTimerId(key), call.retryAtMs));\n      }\n      if (\n        config.deadline !== undefined &&\n        (call.phase === \"running\" || call.phase === \"waiting_retry\") &&\n        call.deadlineAtMs > 0\n      ) {\n        out.push(deadlineSub(deadlineTimerId(key), call.deadlineAtMs));\n      }\n    }\n    return out;\n  }\n\n  // === Handlers ============================================================\n\n  /**\n   * Pre-wired interpret handler for `resilient_run`. Wraps the consumer's\n   * `run` port via `tryInterpret` (Railway): success → `resilient_ok`, failure\n   * → `resilient_err`, each stamped with `Date.now()` at the effect boundary —\n   * the ONE permitted clock read (interpret is impure; the reducer never reads\n   * the clock). Assign to the machine's `interpret`:\n   *\n   *   interpret: rc.handlers({ run: (input, key) => ctx.callBackend(input) })\n   */\n  function handlers(ports: ResilientPorts<I, R>) {\n    return {\n      resilient_run: tryInterpret<\n        RunCmd<I>,\n        R,\n        SucceedMsg<R> | FailMsg,\n        // The work fn reads nothing from ctx — it forwards `cmd.input` to the\n        // consumer-supplied `run` port. `NoCtx` (not `unknown`) marks this as a\n        // DELIBERATE context-free seam, so callers see intent, not looseness.\n        NoCtx\n      >(\n        (cmd) => ports.run(cmd.input, cmd.key),\n        (result, cmd): SucceedMsg<R> => ({\n          type: MsgType.ResilientOk,\n          key: cmd.key,\n          result,\n          at: Date.now(),\n        }),\n        (error, cmd): FailMsg => ({\n          type: MsgType.ResilientErr,\n          key: cmd.key,\n          error,\n          at: Date.now(),\n        }),\n      ),\n    };\n  }\n\n  return {\n    init,\n    attempt,\n    succeed,\n    fail,\n    settleFailed,\n    onTimer,\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.resilience`. A convenience for the common single-slice\n * host; consumers with a differently-named field spread by hand. Pure — a thin\n * record rebuild, no clock / RNG.\n */\nexport function liftResilience<\n  S extends { resilience: ResilientState<I, R> },\n  I,\n  R,\n  C extends Cmd,\n>(\n  state: S,\n  [slice, cmds]: readonly [ResilientState<I, R>, readonly C[]],\n): readonly [S, readonly C[]] {\n  return [{ ...state, resilience: 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 { DeadlineSub, DeadlineExceeded };\n"]}

package/dist/chunk-RVU3RBE6.js

@@ -0,0 +1,31 @@
+import { foldMsgs } from './chunk-BNJYE4AU.js';
+
+// src/prediction/index.ts
+var tagSeq = (seq, value) => ({ seq, value });
+var ack = (lastAppliedSeq) => ({ lastAppliedSeq });
+var partitionByAck = (buffer, ackOrSeq) => {
+  const lastAppliedSeq = typeof ackOrSeq === "number" ? ackOrSeq : ackOrSeq.lastAppliedSeq;
+  const acked = [];
+  const pending = [];
+  for (const item of buffer) {
+    if (item.seq <= lastAppliedSeq) {
+      acked.push(item);
+    } else {
+      pending.push(item);
+    }
+  }
+  return { acked, pending };
+};
+var nextSeq = (buffer) => buffer.reduce((max, item) => item.seq > max ? item.seq : max, -1) + 1;
+function reconcile(machine, authoritativeState, lastAppliedSeq, pending) {
+  const { pending: unacked } = partitionByAck(pending, lastAppliedSeq);
+  return foldMsgs(
+    machine,
+    authoritativeState,
+    unacked.map((tagged) => tagged.value)
+  );
+}
+
+export { ack, nextSeq, partitionByAck, reconcile, tagSeq };
+//# sourceMappingURL=chunk-RVU3RBE6.js.map
+//# sourceMappingURL=chunk-RVU3RBE6.js.map

package/dist/chunk-RVU3RBE6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/prediction/index.ts"],"names":[],"mappings":";;;AAgDO,IAAM,SAAS,CAAI,GAAA,EAAU,KAAA,MAA4B,EAAE,KAAK,KAAA,EAAM;AActE,IAAM,GAAA,GAAM,CAAC,cAAA,MAA8B,EAAE,cAAA,EAAe;AAmB5D,IAAM,cAAA,GAAiB,CAC5B,MAAA,EACA,QAAA,KACoB;AACpB,EAAA,MAAM,cAAA,GACJ,OAAO,QAAA,KAAa,QAAA,GAAW,WAAW,QAAA,CAAS,cAAA;AACrD,EAAA,MAAM,QAAwB,EAAC;AAC/B,EAAA,MAAM,UAA0B,EAAC;AACjC,EAAA,KAAA,MAAW,QAAQ,MAAA,EAAQ;AACzB,IAAA,IAAI,IAAA,CAAK,OAAO,cAAA,EAAgB;AAC9B,MAAA,KAAA,CAAM,KAAK,IAAI,CAAA;AAAA,IACjB,CAAA,MAAO;AACL,MAAA,OAAA,CAAQ,KAAK,IAAI,CAAA;AAAA,IACnB;AAAA,EACF;AACA,EAAA,OAAO,EAAE,OAAO,OAAA,EAAQ;AAC1B;AAQO,IAAM,OAAA,GAAU,CAAI,MAAA,KACzB,MAAA,CAAO,OAAO,CAAC,GAAA,EAAK,IAAA,KAAU,IAAA,CAAK,MAAM,GAAA,GAAM,IAAA,CAAK,GAAA,GAAM,GAAA,EAAM,EAAE,CAAA,GAAI;AAwBjE,SAAS,SAAA,CAOd,OAAA,EACA,kBAAA,EACA,cAAA,EACA,OAAA,EACG;AACH,EAAA,MAAM,EAAE,OAAA,EAAS,OAAA,EAAQ,GAAI,cAAA,CAAe,SAAS,cAAc,CAAA;AACnE,EAAA,OAAO,QAAA;AAAA,IACL,OAAA;AAAA,IACA,kBAAA;AAAA,IACA,OAAA,CAAQ,GAAA,CAAI,CAAC,MAAA,KAAW,OAAO,KAAK;AAAA,GACtC;AACF","file":"chunk-RVU3RBE6.js","sourcesContent":["/**\n * @demlik/tea/prediction — the client-prediction ack primitive (epic #186, facet 2).\n *\n * The contract the Gambetta/Valve authoritative-server netcode loop needs:\n * **command-seq-in → last-applied-seq-out.** A client tags each predicted\n * command/`Msg` with a monotonic `seq`; the authoritative side replies with the\n * `lastAppliedSeq` it has processed. `partitionByAck` then splits the client's\n * pending buffer into the inputs the server has ACKED (`seq <= lastAppliedSeq`)\n * and those still PENDING (`seq > lastAppliedSeq`) — the un-acked tail the\n * reconciliation pass (#214) replays over the authoritative snapshot via\n * `foldMsgs` (#211, `@demlik/tea/pure`).\n *\n * Deliberately **Model-shape-agnostic** (ADR 0006): the ack is a standalone\n * value, NOT a field this module requires on the consumer's `State`. It\n * generalizes the `lastAckedSeq`-on-the-Model + `seq`-threaded-through-the-Msg\n * pattern vortex hand-rolled (epic #186). It is a LEAF module — pure and\n * runtime-free, importing nothing from the tea core or host, so it can never\n * drag `run`/the host into a client bundle.\n *\n * This is the read/ack side of the primitive; `tagSeq`/`nextSeq` are the write\n * side, letting a client mint monotonic seqs from its pending buffer alone —\n * again with no counter field on the Model.\n *\n * `reconcile` (the read side's payoff, #214) composes this ack partition with\n * the pure fold seam `foldMsgs` (#211) to perform the whole Gambetta/Valve\n * reconciliation step in one call. The `foldMsgs` import is the ONLY dependency\n * this leaf takes, and it reaches into the pure-core leaf (`../pure/core`) — NOT\n * the runtime root — so the module stays runtime-free and the `@demlik/tea/pure`\n * import-graph guard (ADR 0006, #213) still holds.\n */\n\nimport type { Cmd, Machine, Sub } from \"../pure/core\";\nimport { foldMsgs } from \"../pure/core\";\n\n/**\n * A monotonic, non-negative sequence number tagging one client-predicted\n * command. Monotonicity is the client's contract (mint successive seqs with\n * `nextSeq`); this module only ever *compares* seqs.\n */\nexport type Seq = number;\n\n/** A command (or `Msg`) tagged with the `seq` the client assigned it. */\nexport interface SeqTagged<T> {\n  readonly seq: Seq;\n  readonly value: T;\n}\n\n/** Tag a command/`Msg` with its sequence number. */\nexport const tagSeq = <T>(seq: Seq, value: T): SeqTagged<T> => ({ seq, value });\n\n/**\n * The authoritative side's acknowledgement: the highest `seq` it has applied.\n * Everything with `seq <= lastAppliedSeq` is settled; everything above is still\n * in flight. This *is* the whole \"ack from the authoritative side\" — a value\n * the consumer carries however it likes (a wire field, a message payload),\n * never a shape this module imposes on the Model.\n */\nexport interface Ack {\n  readonly lastAppliedSeq: Seq;\n}\n\n/** Construct an `Ack` for a last-applied sequence number. */\nexport const ack = (lastAppliedSeq: Seq): Ack => ({ lastAppliedSeq });\n\n/** The result of splitting a seq-tagged buffer against an ack. */\nexport interface AckPartition<T> {\n  /** Inputs the authoritative side has applied (`seq <= lastAppliedSeq`). */\n  readonly acked: readonly SeqTagged<T>[];\n  /** Inputs still in flight / un-acked (`seq > lastAppliedSeq`) — the replay tail. */\n  readonly pending: readonly SeqTagged<T>[];\n}\n\n/**\n * Partition a buffer of seq-tagged commands into ACKED and PENDING against the\n * authoritative `lastAppliedSeq`. Pure and total: every item lands in exactly\n * one bucket, input order is preserved within each bucket, and the boundary\n * `seq == lastAppliedSeq` is ACKED (inclusive `<=`). Routing is by `seq` value,\n * not buffer position, so an out-of-order or duplicate-seq buffer partitions\n * correctly. Accepts either an {@link Ack} or a bare `lastAppliedSeq` number, so\n * a caller passes whichever it holds.\n */\nexport const partitionByAck = <T>(\n  buffer: readonly SeqTagged<T>[],\n  ackOrSeq: Ack | Seq,\n): AckPartition<T> => {\n  const lastAppliedSeq =\n    typeof ackOrSeq === \"number\" ? ackOrSeq : ackOrSeq.lastAppliedSeq;\n  const acked: SeqTagged<T>[] = [];\n  const pending: SeqTagged<T>[] = [];\n  for (const item of buffer) {\n    if (item.seq <= lastAppliedSeq) {\n      acked.push(item);\n    } else {\n      pending.push(item);\n    }\n  }\n  return { acked, pending };\n};\n\n/**\n * The next sequence number to assign: one past the highest `seq` in the buffer,\n * or `0` for an empty buffer. Lets a client mint monotonic seqs from its pending\n * buffer alone — no counter field on the Model — and is tolerant of an unordered\n * buffer (it takes the max, not the last element).\n */\nexport const nextSeq = <T>(buffer: readonly SeqTagged<T>[]): Seq =>\n  buffer.reduce((max, item) => (item.seq > max ? item.seq : max), -1) + 1;\n\n/**\n * The client prediction/reconciliation helper — the Gambetta/Valve\n * authoritative-server loop's reconcile step, generalized (#214, epic #186).\n *\n * Given the latest `authoritativeState` from the server, the server's\n * `lastAppliedSeq` ack, and the client's `pending` buffer of seq-tagged inputs,\n * it returns the corrected predicted state: drop the inputs the server has\n * already applied (`seq <= lastAppliedSeq`) and replay ONLY the un-acked tail\n * (`seq > lastAppliedSeq`) over the authoritative snapshot.\n *\n * It is **composed, not re-derived** (ADR 0006): the drop is {@link partitionByAck}\n * (the ack primitive, #212) and the replay is `foldMsgs` (the pure fold seam,\n * #211) — there is no second copy of the partition logic and no second copy of\n * the fold. `lastAppliedSeq` accepts either an {@link Ack} or a bare `Seq`, so a\n * caller passes whichever it holds, matching `partitionByAck`.\n *\n * Pure and host-agnostic: it takes the `machine` (which `foldMsgs` needs to\n * dispatch `update`) but touches no `Store`, `interpret`, or subscription, and\n * imports nothing from the runtime — so it ships on `@demlik/tea/prediction`\n * and the client-safe `@demlik/tea/pure` umbrella without dragging `run` into a\n * client bundle.\n */\nexport function reconcile<\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  authoritativeState: S,\n  lastAppliedSeq: Ack | Seq,\n  pending: readonly SeqTagged<M>[],\n): S {\n  const { pending: unacked } = partitionByAck(pending, lastAppliedSeq);\n  return foldMsgs(\n    machine,\n    authoritativeState,\n    unacked.map((tagged) => tagged.value),\n  );\n}\n"]}

package/dist/chunk-SC3FAFZN.js

@@ -0,0 +1,53 @@
+// src/circuit-breaker/index.ts
+var defaultCircuitPolicy = {
+  failureThreshold: 5,
+  cooldownMs: 3e4,
+  halfOpenMaxProbes: 1
+};
+function initCircuit() {
+  return { phase: "closed", failures: 0 };
+}
+function onSuccess(state, _policy) {
+  switch (state.phase) {
+    case "closed":
+      return state.failures === 0 ? state : { phase: "closed", failures: 0 };
+    case "half_open":
+      return { phase: "closed", failures: 0 };
+    case "open":
+      return state;
+  }
+}
+function onFailure(state, policy, nowMs) {
+  switch (state.phase) {
+    case "closed": {
+      const failures = state.failures + 1;
+      return failures >= policy.failureThreshold ? { phase: "open", openedAtMs: nowMs } : { phase: "closed", failures };
+    }
+    case "half_open":
+      return { phase: "open", openedAtMs: nowMs };
+    case "open":
+      return state;
+  }
+}
+function canPass(state, policy, nowMs) {
+  switch (state.phase) {
+    case "closed":
+      return [state, true];
+    case "open": {
+      const elapsed = nowMs - state.openedAtMs;
+      if (elapsed >= policy.cooldownMs) {
+        return [{ phase: "half_open", probes: 1 }, true];
+      }
+      return [state, false];
+    }
+    case "half_open":
+      if (state.probes < policy.halfOpenMaxProbes) {
+        return [{ phase: "half_open", probes: state.probes + 1 }, true];
+      }
+      return [state, false];
+  }
+}
+
+export { canPass, defaultCircuitPolicy, initCircuit, onFailure, onSuccess };
+//# sourceMappingURL=chunk-SC3FAFZN.js.map
+//# sourceMappingURL=chunk-SC3FAFZN.js.map

package/dist/chunk-SC3FAFZN.js.map

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

package/dist/chunk-SINXE47Y.js

@@ -0,0 +1,55 @@
+// src/paginator/index.ts
+var defaultPaginatorPolicy = {
+  firstCursor: 0,
+  highWaterMark: 1e3
+};
+function initPaginator() {
+  return { phase: "idle", seen: 0, pages: 0 };
+}
+function start(state, policy) {
+  if (state.phase !== "idle") return state;
+  return {
+    phase: "fetching",
+    cursor: policy.firstCursor,
+    seen: state.seen,
+    pages: state.pages
+  };
+}
+function recordPage(state, count, next, policy) {
+  if (state.phase !== "fetching") return state;
+  const safeCount = Number.isFinite(count) ? Math.max(0, count) : 0;
+  const seen = state.seen + safeCount;
+  const pages = state.pages + 1;
+  if (next == null) {
+    return { phase: "done", seen, pages };
+  }
+  if (policy.highWaterMark > 0 && seen >= policy.highWaterMark) {
+    return { phase: "paused", cursor: next, seen, pages };
+  }
+  return { phase: "fetching", cursor: next, seen, pages };
+}
+function drain(state, n) {
+  if (n <= 0) return state;
+  const seen = Math.max(0, state.seen - n);
+  if (seen === state.seen) return state;
+  return { ...state, seen };
+}
+function resume(state, policy) {
+  if (state.phase !== "paused") return state;
+  if (state.seen < policy.highWaterMark) {
+    return {
+      phase: "fetching",
+      cursor: state.cursor,
+      seen: state.seen,
+      pages: state.pages
+    };
+  }
+  return state;
+}
+function isDone(state) {
+  return state.phase === "done";
+}
+
+export { defaultPaginatorPolicy, drain, initPaginator, isDone, recordPage, resume, start };
+//# sourceMappingURL=chunk-SINXE47Y.js.map
+//# sourceMappingURL=chunk-SINXE47Y.js.map

package/dist/chunk-SINXE47Y.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/paginator/index.ts"],"names":[],"mappings":";AAmJO,IAAM,sBAAA,GAAkD;AAAA,EAC7D,WAAA,EAAa,CAAA;AAAA,EACb,aAAA,EAAe;AACjB;AAqCO,SAAS,aAAA,GAAgD;AAC9D,EAAA,OAAO,EAAE,KAAA,EAAO,MAAA,EAAQ,IAAA,EAAM,CAAA,EAAG,OAAO,CAAA,EAAE;AAC5C;AAWO,SAAS,KAAA,CACd,OACA,MAAA,EACwB;AACxB,EAAA,IAAI,KAAA,CAAM,KAAA,KAAU,MAAA,EAAQ,OAAO,KAAA;AACnC,EAAA,OAAO;AAAA,IACL,KAAA,EAAO,UAAA;AAAA,IACP,QAAQ,MAAA,CAAO,WAAA;AAAA,IACf,MAAM,KAAA,CAAM,IAAA;AAAA,IACZ,OAAO,KAAA,CAAM;AAAA,GACf;AACF;AAgCO,SAAS,UAAA,CACd,KAAA,EACA,KAAA,EACA,IAAA,EACA,MAAA,EACwB;AACxB,EAAA,IAAI,KAAA,CAAM,KAAA,KAAU,UAAA,EAAY,OAAO,KAAA;AAcvC,EAAA,MAAM,SAAA,GAAY,OAAO,QAAA,CAAS,KAAK,IAAI,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,KAAK,CAAA,GAAI,CAAA;AAChE,EAAA,MAAM,IAAA,GAAO,MAAM,IAAA,GAAO,SAAA;AAC1B,EAAA,MAAM,KAAA,GAAQ,MAAM,KAAA,GAAQ,CAAA;AAM5B,EAAA,IAAI,QAAQ,IAAA,EAAM;AAChB,IAAA,OAAO,EAAE,KAAA,EAAO,MAAA,EAAQ,IAAA,EAAM,KAAA,EAAM;AAAA,EACtC;AAKA,EAAA,IAAI,MAAA,CAAO,aAAA,GAAgB,CAAA,IAAK,IAAA,IAAQ,OAAO,aAAA,EAAe;AAC5D,IAAA,OAAO,EAAE,KAAA,EAAO,QAAA,EAAU,MAAA,EAAQ,IAAA,EAAM,MAAM,KAAA,EAAM;AAAA,EACtD;AACA,EAAA,OAAO,EAAE,KAAA,EAAO,UAAA,EAAY,MAAA,EAAQ,IAAA,EAAM,MAAM,KAAA,EAAM;AACxD;AAkBO,SAAS,KAAA,CACd,OACA,CAAA,EACwB;AACxB,EAAA,IAAI,CAAA,IAAK,GAAG,OAAO,KAAA;AACnB,EAAA,MAAM,OAAO,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,KAAA,CAAM,OAAO,CAAC,CAAA;AACvC,EAAA,IAAI,IAAA,KAAS,KAAA,CAAM,IAAA,EAAM,OAAO,KAAA;AAChC,EAAA,OAAO,EAAE,GAAG,KAAA,EAAO,IAAA,EAAK;AAC1B;AAoBO,SAAS,MAAA,CACd,OACA,MAAA,EACwB;AACxB,EAAA,IAAI,KAAA,CAAM,KAAA,KAAU,QAAA,EAAU,OAAO,KAAA;AACrC,EAAA,IAAI,KAAA,CAAM,IAAA,GAAO,MAAA,CAAO,aAAA,EAAe;AACrC,IAAA,OAAO;AAAA,MACL,KAAA,EAAO,UAAA;AAAA,MACP,QAAQ,KAAA,CAAM,MAAA;AAAA,MACd,MAAM,KAAA,CAAM,IAAA;AAAA,MACZ,OAAO,KAAA,CAAM;AAAA,KACf;AAAA,EACF;AACA,EAAA,OAAO,KAAA;AACT;AAQO,SAAS,OAAe,KAAA,EAAwC;AACrE,EAAA,OAAO,MAAM,KAAA,KAAU,MAAA;AACzB","file":"chunk-SINXE47Y.js","sourcesContent":["/**\n * @demlik/tea/paginator — the cursor/offset/page-token walk loop as pure\n * state + ops.\n *\n * Same shape as `@demlik/tea/retry-backoff`, `@demlik/tea/circuit-breaker`,\n * and `@demlik/tea/rate-limit`: a state type plus pure transition functions,\n * host-agnostic by construction. Nothing here reads the clock, the RNG, or any\n * I/O on its own behalf — the consumer fetches a page out-of-band and folds the\n * *result* back in through `recordPage`. That keeps every function inside TEA's\n * invariant 2 (transitions are pure: same inputs → same outputs) so a consumer\n * can thread the walk through `update` and exercise it with `replay` / the pbt\n * fold without a fake network.\n *\n * Every op returns a NEW state value and never mutates its input (invariant 1 —\n * state is a value, not a place). All fields are `readonly` and plain data, so\n * the whole walk is trivially JSON-serializable into a consumer's `Store<S>`\n * and survives a Durable-Object eviction / reload mid-walk: the cursor lives in\n * the Model, not a closure (the durability + replay non-negotiables every TEA\n * knob preserves).\n *\n * ## The cursor is opaque, and the consumer advances it\n *\n * A paginated API hands back a *next cursor* however it likes: an offset\n * (`?offset=40`), a page token (`?pageToken=ey…`), a \"next\" URL, or `null` at\n * the end. This module is generic in `Cursor` and never inspects it — it only\n * carries it forward. The consumer (who alone knows the API's shape) reads the\n * next cursor off the just-fetched page and passes it to `recordPage`:\n *\n *   const next = page.nextPageToken ?? null;   // consumer-specific extraction\n *   const walk = recordPage(state.walk, page.items.length, next);\n *\n * Passing `next: null` (or a missing `undefined` cursor — the op compares with\n * loose `== null`) means \"the API said there is no next page\" → the walk\n * finishes (`done`). Passing a `Cursor` means \"fetch this one next\" → the walk\n * either keeps `fetching` or `pauses` for backpressure (below). Decoupling the\n * extraction from the op is the same discipline `circuit-breaker` uses for the\n * clock: the impure / domain-specific bit (`nextCursor(page)`) lives at the\n * call site; the op stays a pure fold over the extracted value.\n *\n * ## The phase machine\n *\n * Four phases, each a discriminated-union arm carrying ONLY the data that phase\n * needs so impossible states are unrepresentable (pattern 11):\n *\n *   - **idle** — created, not started. No cursor is armed yet; `start` arms the\n *     first one. Carries the running `seen` / `pages` counters (both 0 here, but\n *     present on every phase so a consumer reads them uniformly).\n *\n *   - **fetching** — a page request for `cursor` is outstanding. The walk sits\n *     here while the consumer's fetch is in flight; `recordPage` resolves it.\n *     Carries the `cursor` being fetched so a post-eviction resume re-issues the\n *     SAME request (idempotent retry) rather than skipping a page.\n *\n *   - **paused** — backpressure tripped. The API still has more pages (a non-null\n *     next cursor), but `seen` has reached `highWaterMark` and the consumer has\n *     not drained yet. Carries the `cursor` to resume from. No fetch is\n *     outstanding — the loop is deliberately idle until `resume`. This is the\n *     valve that stops a fast producer (the API) from outrunning a slow consumer\n *     (whatever processes each page) and blowing memory.\n *\n *   - **done** — the API returned a null next cursor; the walk is exhausted. A\n *     terminal phase: `start` / `recordPage` / `resume` are all no-ops on it\n *     (idempotent completion — a late duplicate result can't un-finish a walk).\n *\n * ### Transition table\n *\n * Rows are the current phase; columns are the op. `→` denotes the next phase;\n * `self` means unchanged (a no-op for that (phase × op) pair). `next` is the\n * cursor the consumer extracted from the page; `hwm` is `highWaterMark`.\n *\n * | from \\ op   | start          | recordPage(count, next)                                              | resume                         |\n * | ----------- | -------------- | -------------------------------------------------------------------- | ------------------------------ |\n * | idle        | → fetching(c0) | self *(¹)*                                                            | self                           |\n * | fetching    | self           | seen=max(0,seen+count), pages+=1; next==null → done; seen≥hwm → paused(next); else → fetching(next) | self                           |\n * | paused      | self           | self *(¹)*                                                            | seen<hwm → fetching(cursor) *(²)* |\n * | done        | self           | self                                                                  | self                           |\n *\n * *(¹)* `recordPage` only makes sense while `fetching` (a page was outstanding).\n * On any other phase it is a no-op: a result that arrives when no fetch was in\n * flight (a late duplicate, a double-dispatch) must not advance the cursor or\n * double-count `seen`. The walk is a coordination aid, not a correctness gate —\n * it absorbs the stray rather than corrupting the count.\n *\n * *(²)* `resume` re-arms the paused cursor ONLY once `seen` has dropped below\n * `highWaterMark` (the consumer drained, lowering `seen` via `drain`). Calling\n * `resume` while still over the mark is a no-op — the valve stays shut until\n * there is real headroom, so a consumer that resumes optimistically can't\n * defeat the backpressure. Resuming a walk that isn't `paused` is likewise a\n * no-op.\n *\n * ## Backpressure\n *\n * `seen` is the count of items the API has produced that the consumer has not\n * yet acknowledged as processed. `recordPage` adds each page's item count to it;\n * `drain(n)` subtracts what the consumer finished. When `seen` reaches\n * `highWaterMark`, `recordPage` parks the walk in `paused` instead of issuing\n * the next fetch — the producer stops until `drain` + `resume` re-open the\n * valve. A `highWaterMark` of `0` (or any non-positive value) disables\n * backpressure: the comparison `seen >= hwm` is satisfied vacuously only when\n * `hwm <= 0` would pause immediately, so we treat `hwm <= 0` as \"unbounded\" and\n * never pause. The walk then runs flat-out, `fetching → fetching` until `done`.\n *\n * NOT exported from the package root — reached via the `@demlik/tea/paginator`\n * subpath, same one-shape-per-package rule as `work-queue`, `retry-backoff`,\n * `circuit-breaker`, and `rate-limit`. It is the L1 escape hatch the\n * `paginated-walk` composition builds its walk loop on.\n */\n\n/**\n * Paginator policy — pure configuration, no mutable state. One policy is shared\n * across the whole walk (often a module-scope const). `PaginatorState` carries\n * the cursor + counters; this carries the knobs they're compared against.\n *\n * Generic in `Cursor` so `firstCursor` matches whatever the API's cursor shape\n * is — an offset `number`, a page-token `string`, a `{ after: string }` record,\n * etc. The module never inspects the cursor; the type just threads through.\n */\nexport interface PaginatorPolicy<Cursor> {\n  /**\n   * The cursor the walk fetches first, armed by `start`. For an offset API this\n   * is typically `0`; for a token API, `null`-or-empty-meaning-\"first page\" is\n   * the API's call, so pass whatever sentinel the API treats as page one.\n   */\n  readonly firstCursor: Cursor;\n  /**\n   * Backpressure threshold: the number of un-drained items at which the walk\n   * pauses instead of fetching the next page. `recordPage` parks in `paused`\n   * once `seen >= highWaterMark`; `drain` + `resume` re-open the valve.\n   *\n   * A non-positive value (`<= 0`) disables backpressure — the walk never pauses\n   * and runs `fetching → fetching` until the API exhausts. Use that when the\n   * consumer processes each page synchronously inside `recordPage` and there is\n   * nothing to back up.\n   */\n  readonly highWaterMark: number;\n}\n\n/**\n * Sensible defaults: start from a numeric offset of `0`, pause after 1000\n * un-drained items. Tuned for an offset-paginated REST API whose consumer\n * processes pages asynchronously; override per call site (especially\n * `firstCursor`, which is API-specific) rather than mutating this shared const.\n *\n * Typed as `PaginatorPolicy<number>` because the only honest default cursor is\n * the numeric offset `0`; a token-based API supplies its own `firstCursor` and\n * its own `PaginatorPolicy<string>`.\n */\nexport const defaultPaginatorPolicy: PaginatorPolicy<number> = {\n  firstCursor: 0,\n  highWaterMark: 1000,\n};\n\n/**\n * The walk's phase. A discriminated union on `phase` so each phase carries ONLY\n * its own data and impossible combinations are unrepresentable (pattern 11):\n * there is no `done` state that still holds a pending cursor, no `idle` state\n * mid-fetch. Every field is `readonly` so the whole value is trivially\n * JSON-serializable into a consumer's `Store<S>` and safe to thread through a\n * pure reducer / a Durable-Object reload.\n *\n * Two counters ride on every phase so a consumer reads them uniformly without\n * narrowing first:\n *   - `seen`  — items produced by the API but not yet drained (backpressure gauge).\n *   - `pages` — total pages recorded so far (progress / observability).\n *\n *   - `idle`     — not started; `start` arms `firstCursor`.\n *   - `fetching` — a page request for `cursor` is outstanding.\n *   - `paused`   — backpressure tripped; `cursor` is the page to resume from.\n *   - `done`     — API exhausted (null next cursor); terminal.\n */\nexport type PaginatorState<Cursor> =\n  | { readonly phase: \"idle\"; readonly seen: number; readonly pages: number }\n  | {\n      readonly phase: \"fetching\";\n      readonly cursor: Cursor;\n      readonly seen: number;\n      readonly pages: number;\n    }\n  | {\n      readonly phase: \"paused\";\n      readonly cursor: Cursor;\n      readonly seen: number;\n      readonly pages: number;\n    }\n  | { readonly phase: \"done\"; readonly seen: number; readonly pages: number };\n\n/** The starting state: idle, nothing seen, no pages recorded. */\nexport function initPaginator<Cursor>(): PaginatorState<Cursor> {\n  return { phase: \"idle\", seen: 0, pages: 0 };\n}\n\n/**\n * Arm the first fetch. PURE — returns a new state; the input is never mutated.\n *\n *   - `idle` → `fetching(firstCursor)`. This is the only phase `start` acts on.\n *   - any other phase → unchanged. Re-arming a walk that has already begun (or\n *     finished) would skip back to page one and double-count; a stray `start`\n *     after launch is absorbed, not honored. Use `initPaginator()` to begin a\n *     genuinely fresh walk.\n */\nexport function start<Cursor>(\n  state: PaginatorState<Cursor>,\n  policy: PaginatorPolicy<Cursor>,\n): PaginatorState<Cursor> {\n  if (state.phase !== \"idle\") return state;\n  return {\n    phase: \"fetching\",\n    cursor: policy.firstCursor,\n    seen: state.seen,\n    pages: state.pages,\n  };\n}\n\n/**\n * Record the result of the outstanding fetch and decide what comes next. PURE —\n * returns a new state; the input is never mutated.\n *\n * `count` is how many items the just-fetched page yielded (added to `seen` for\n * backpressure accounting). `next` is the cursor the consumer extracted from the\n * page — a `Cursor` to fetch next, or `null`/`undefined` (a missing optional\n * cursor field) if the API signalled the end.\n *\n *   - `fetching` → `seen = max(0, seen + count)`, `pages += 1`, then branch on\n *     `next`:\n *       - `next == null`            → `done` (API exhausted; loose-null so a\n *                                      missing/`undefined` cursor also finishes).\n *       - `seen >= highWaterMark`   → `paused(next)` (backpressure; `hwm <= 0`\n *                                      disables this branch — see policy docs).\n *       - otherwise                 → `fetching(next)` (keep walking).\n *   - any other phase → unchanged. A result with no fetch outstanding (a late\n *     duplicate, a double-dispatch) must not advance the cursor or double-count;\n *     it is absorbed. See the module header's note ¹.\n *\n * `count` is floored into the gauge: a non-finite `count` (`NaN`/`Infinity`) is\n * treated as `0`, and the additive sum is clamped at `0`. A record can only hold\n * or raise `seen`; only `drain` lowers it. This keeps a stray negative or\n * non-finite count from poisoning the `seen >= highWaterMark` comparison and\n * silently defeating backpressure.\n *\n * The new `seen` total — not the pre-page value — is what the backpressure check\n * reads, so a single page large enough to cross the mark pauses immediately\n * rather than fetching one more first.\n */\nexport function recordPage<Cursor>(\n  state: PaginatorState<Cursor>,\n  count: number,\n  next: Cursor | null | undefined,\n  policy: PaginatorPolicy<Cursor>,\n): PaginatorState<Cursor> {\n  if (state.phase !== \"fetching\") return state;\n  // A page's item count must be a finite, non-negative addition to `seen`. A\n  // negative count would drive `seen` down (a record can never lower the gauge —\n  // only `drain` does) and a non-finite count (`NaN` / `Infinity`) would poison\n  // every later `seen >= highWaterMark` comparison, permanently defeating\n  // backpressure (NaN compares false, so the valve never trips). Floor the\n  // CONTRIBUTION (not just the sum) at 0: clamp a non-finite count to 0\n  // (mirroring retry-backoff's `Number.isNaN` discipline at backoffDelay ~:119)\n  // and a negative count to 0. Flooring the contribution — rather than the sum —\n  // is what makes a record strictly monotonic: `Math.max(0, seen + count)` only\n  // catches a count that drags the *sum* below zero, so a small negative count\n  // (e.g. `seen=10, count=-3 → 7`) would still silently lower the gauge and\n  // break \"only `drain` lowers `seen`\". Clamping `count` first guarantees the\n  // additive step can only hold or raise the gauge.\n  const safeCount = Number.isFinite(count) ? Math.max(0, count) : 0;\n  const seen = state.seen + safeCount;\n  const pages = state.pages + 1;\n  // Loose `== null` so a *missing* next cursor (`undefined`, common for an\n  // optional API field the consumer extracted as `page.nextPageToken`) finishes\n  // the walk exactly like an explicit `null`. Strict `=== null` would route an\n  // `undefined` cursor into the fetching/paused branch and carry a cursor-less\n  // (malformed) state forward.\n  if (next == null) {\n    return { phase: \"done\", seen, pages };\n  }\n  // `hwm <= 0` disables backpressure entirely (unbounded walk); only a positive\n  // mark can park the loop. `seen >= hwm` is the half-open edge — reaching the\n  // mark exactly pauses, matching the `>=` window edges `rate-limit` /\n  // `circuit-breaker` use.\n  if (policy.highWaterMark > 0 && seen >= policy.highWaterMark) {\n    return { phase: \"paused\", cursor: next, seen, pages };\n  }\n  return { phase: \"fetching\", cursor: next, seen, pages };\n}\n\n/**\n * Acknowledge that the consumer finished processing `n` items, lowering the\n * backpressure gauge. PURE — returns a new state; the input is never mutated.\n *\n * Subtracts `n` from `seen`, floored at 0 (a consumer that over-acks, or acks a\n * page recorded before a reload, can never drive `seen` negative). `n <= 0` is a\n * no-op on the count. `drain` does NOT change the phase — it only frees\n * headroom; `resume` is the separate, explicit decision to re-issue a fetch once\n * the headroom exists. Splitting \"I drained\" from \"I want to continue\" lets a\n * consumer drain in several steps and resume once.\n *\n * Works on every phase: a consumer may drain while still `fetching` (the gauge\n * just drops, no pause was reached) or while `paused` (freeing room for a later\n * `resume`). On `done` the gauge can still be drained for accurate final\n * accounting, though it no longer gates anything.\n */\nexport function drain<Cursor>(\n  state: PaginatorState<Cursor>,\n  n: number,\n): PaginatorState<Cursor> {\n  if (n <= 0) return state;\n  const seen = Math.max(0, state.seen - n);\n  if (seen === state.seen) return state;\n  return { ...state, seen };\n}\n\n/**\n * Re-open the backpressure valve after a `drain`. PURE — returns a new state;\n * the input is never mutated.\n *\n *   - `paused` AND `seen < highWaterMark` → `fetching(cursor)`: the consumer has\n *     drained below the mark, so re-issue the parked fetch.\n *   - `paused` but `seen >= highWaterMark` → unchanged. There is still no\n *     headroom; the valve stays shut until a `drain` lowers `seen`. A consumer\n *     that resumes optimistically can't defeat the backpressure. (When `hwm <=\n *     0` backpressure is disabled, so the walk never reaches `paused` and this\n *     branch is unreachable — but the guard reads `< hwm` consistently, and a\n *     non-positive `hwm` makes `seen < hwm` false for any non-negative `seen`,\n *     correctly refusing to resume a state that should never have paused.)\n *   - any other phase → unchanged. Resuming a walk that isn't paused (idle,\n *     fetching, done) is a no-op.\n *\n * See the module header's note ².\n */\nexport function resume<Cursor>(\n  state: PaginatorState<Cursor>,\n  policy: PaginatorPolicy<Cursor>,\n): PaginatorState<Cursor> {\n  if (state.phase !== \"paused\") return state;\n  if (state.seen < policy.highWaterMark) {\n    return {\n      phase: \"fetching\",\n      cursor: state.cursor,\n      seen: state.seen,\n      pages: state.pages,\n    };\n  }\n  return state;\n}\n\n/**\n * Whether the walk has finished (the API returned a null next cursor). PURE,\n * read-only. A derived predicate so a consumer's reducer can branch\n * (`if (isDone(walk)) return [doneState, [joinCmd]]`) without re-checking the\n * `phase` discriminant by hand at every call site.\n */\nexport function isDone<Cursor>(state: PaginatorState<Cursor>): boolean {\n  return state.phase === \"done\";\n}\n"]}

package/dist/chunk-TAO4YOLO.js

@@ -0,0 +1,87 @@
+import { createResilientCall, liftResilience } from './chunk-RVJFGRGK.js';
+import { MsgType } from './chunk-JELSZN25.js';
+
+// src/llm-call/index.ts
+function createLlmCall(config, rng = Math.random) {
+  const resilientConfig = {
+    ...config.retry === void 0 ? {} : { retry: config.retry }
+  };
+  const rc = createResilientCall(resilientConfig, rng);
+  function init() {
+    return rc.init();
+  }
+  function attempt(s, input, at, key = input.purpose) {
+    return rc.attempt(s, key, input, at);
+  }
+  function succeed(s, key, msg) {
+    return rc.succeed(s, key, msg);
+  }
+  function fail(s, key, msg) {
+    return rc.fail(s, key, msg);
+  }
+  function onTimer(s, msg) {
+    return rc.onTimer(s, msg);
+  }
+  function subs(s) {
+    return rc.subs(s);
+  }
+  async function invokeOne(input) {
+    const model = config.model(input.model);
+    const messages = config.loadMessages ? await config.loadMessages(input) : [];
+    const schema = config.schemas[input.purpose];
+    const structured = model.withStructuredOutput(schema);
+    const raw = await structured.invoke(messages);
+    const output = schema.parse(raw);
+    return { key: input.purpose, purpose: input.purpose, output };
+  }
+  const resilientRunHandler = rc.handlers({
+    run: (input) => invokeOne(input)
+  }).resilient_run;
+  async function settleOf(cmd) {
+    const settle = await resilientRunHandler(cmd, {});
+    if (settle.type === MsgType.ResilientOk) {
+      return settle;
+    }
+    const rawError = settle.error;
+    const err = {
+      key: cmd.key,
+      purpose: cmd.input.purpose,
+      reason: rawError instanceof Error ? rawError.message : String(rawError),
+      error: rawError
+    };
+    return {
+      type: MsgType.ResilientErr,
+      key: settle.key,
+      error: err,
+      at: settle.at
+    };
+  }
+  function handlers(ports) {
+    if (ports === void 0) {
+      return { resilient_run: (cmd) => settleOf(cmd) };
+    }
+    return {
+      resilient_run: (cmd, ctx) => {
+        const fired = (async () => {
+          const settle = await settleOf(cmd);
+          if (settle.type === MsgType.ResilientOk) {
+            const msg2 = ports.onOk(settle.result);
+            if (msg2 !== void 0) await ctx.dispatch(msg2);
+            return;
+          }
+          const msg = ports.onErr(settle.error);
+          if (msg !== void 0) await ctx.dispatch(msg);
+        })();
+        ctx.waitUntil(fired);
+      }
+    };
+  }
+  return { init, attempt, succeed, fail, onTimer, subs, handlers, invokeOne };
+}
+function liftLlmCall(state, result) {
+  return liftResilience(state, result);
+}
+
+export { createLlmCall, liftLlmCall };
+//# sourceMappingURL=chunk-TAO4YOLO.js.map
+//# sourceMappingURL=chunk-TAO4YOLO.js.map