@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/utils/resilience/index.cjs

@@ -0,0 +1,1617 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/utils/resilience/index.ts
+var resilience_exports = {};
+__export(resilience_exports, {
+  CircuitOpenError: () => CircuitOpenError,
+  NS_PER_SEC: () => NS_PER_SEC,
+  RateLimiterOverflowError: () => RateLimiterOverflowError,
+  TimeoutError: () => TimeoutError,
+  adaptiveRateLimiter: () => adaptiveRateLimiter,
+  budgetGate: () => budgetGate,
+  circuitBreaker: () => circuitBreaker,
+  fallback: () => fallback,
+  rateLimiter: () => rateLimiter,
+  retry: () => retry,
+  tokenBucket: () => tokenBucket,
+  withBreaker: () => withBreaker,
+  withStatus: () => withStatus,
+  withTimeout: () => withTimeout
+});
+module.exports = __toCommonJS(resilience_exports);
+
+// src/base/resilience/retry.ts
+var import_core2 = require("@graphrefly/pure-ts/core");
+
+// src/base/resilience/_internal.ts
+var import_core = require("@graphrefly/pure-ts/core");
+function operatorOpts(opts) {
+  return { describeKind: "derived", ...opts };
+}
+function clampNonNegative(value) {
+  return value < 0 ? 0 : value;
+}
+function msgVal(m) {
+  return m[1];
+}
+function coerceDelayNs(raw) {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) {
+    throw new TypeError("backoff strategy must return a finite number");
+  }
+  return raw < 0 ? 0 : raw;
+}
+function isNode(x) {
+  return x != null && typeof x === "object" && "cache" in x && typeof x.subscribe === "function";
+}
+function resolveReactiveOption(arg, onChange) {
+  if (!isNode(arg)) {
+    return { current: () => arg, unsub: () => void 0 };
+  }
+  const node9 = arg;
+  let latest = node9.cache;
+  const unsub = node9.subscribe((msgs) => {
+    for (const m of msgs) {
+      if (m[0] === import_core.DATA) {
+        latest = m[1];
+        if (onChange) onChange(latest);
+      }
+    }
+  });
+  return {
+    current: () => latest,
+    unsub
+  };
+}
+function isThenable(x) {
+  return x != null && typeof x.then === "function";
+}
+function isAsyncIterable(x) {
+  return x != null && typeof x === "object" && typeof x[Symbol.asyncIterator] === "function";
+}
+
+// src/base/resilience/backoff.ts
+var NS_PER_MS = 1e6;
+var NS_PER_SEC = 1e9;
+function clampNonNegative2(value) {
+  return value < 0 ? 0 : value;
+}
+function applyJitter(delay, jitter) {
+  if (jitter === "none") return delay;
+  if (jitter === "full") return Math.random() * delay;
+  return delay / 2 + Math.random() * (delay / 2);
+}
+function randomBetween(min, max) {
+  return min + Math.random() * (max - min);
+}
+function constant(delayNs) {
+  const safe = clampNonNegative2(delayNs);
+  return () => safe;
+}
+function linear(baseNs, stepNs) {
+  const safeBase = clampNonNegative2(baseNs);
+  const safeStep = stepNs === void 0 ? safeBase : clampNonNegative2(stepNs);
+  return (attempt) => safeBase + safeStep * Math.max(0, attempt);
+}
+function exponential(options) {
+  const baseNs = clampNonNegative2(options?.baseNs ?? 100 * NS_PER_MS);
+  const factor = options?.factor !== void 0 && options.factor < 1 ? 1 : options?.factor ?? 2;
+  const maxDelayNs = clampNonNegative2(options?.maxDelayNs ?? 30 * NS_PER_SEC);
+  const jitter = options?.jitter ?? "none";
+  return (attempt) => {
+    let delay;
+    if (baseNs === 0) {
+      delay = 0;
+    } else if (factor === 1) {
+      delay = baseNs;
+    } else {
+      const capRatio = maxDelayNs / baseNs;
+      let growth = 1;
+      for (let i = 0; i < Math.max(0, attempt); i++) {
+        if (growth >= capRatio) {
+          growth = capRatio;
+          break;
+        }
+        growth *= factor;
+      }
+      delay = baseNs * growth;
+      if (delay > maxDelayNs) delay = maxDelayNs;
+    }
+    return applyJitter(delay, jitter);
+  };
+}
+function fibonacci(baseNs = 100 * NS_PER_MS, maxDelayNs = 30 * NS_PER_SEC) {
+  const safeBase = clampNonNegative2(baseNs);
+  const safeMax = clampNonNegative2(maxDelayNs);
+  function fibUnit(attempt) {
+    if (attempt <= 0) return 1;
+    let prev = 1;
+    let cur = 2;
+    for (let i = 1; i < attempt; i++) {
+      const next = prev + cur;
+      prev = cur;
+      cur = next;
+    }
+    return cur;
+  }
+  return (attempt) => {
+    const raw = fibUnit(attempt) * safeBase;
+    return raw <= safeMax ? raw : safeMax;
+  };
+}
+function decorrelatedJitter(baseNs = 100 * NS_PER_MS, maxNs = 30 * NS_PER_SEC) {
+  return (_attempt, _error, prevDelayNs) => {
+    const last = prevDelayNs ?? baseNs;
+    const ceiling = Math.min(maxNs, last * 3);
+    return randomBetween(baseNs, ceiling);
+  };
+}
+function resolveBackoffPreset(name) {
+  if (name === "constant") return constant(1 * NS_PER_SEC);
+  if (name === "linear") return linear(1 * NS_PER_SEC);
+  if (name === "exponential") return exponential();
+  if (name === "fibonacci") return fibonacci();
+  if (name === "decorrelatedJitter") return decorrelatedJitter();
+  throw new Error(
+    `Unknown backoff preset: "${String(name)}". Use one of: constant, linear, exponential, fibonacci, decorrelatedJitter`
+  );
+}
+
+// src/base/resilience/retry.ts
+function resolveRetryConfig(opts) {
+  const count = opts?.count;
+  const backoffOpt = opts?.backoff;
+  if (backoffOpt !== void 0 && count === void 0) {
+    throw new RangeError(
+      "retry({ backoff }) requires explicit count to prevent unbounded retries; pass { count: <n>, backoff: ... }"
+    );
+  }
+  const maxRetries = count !== void 0 ? count : 0;
+  if (maxRetries < 0) throw new RangeError("retry count must be >= 0");
+  const strategy = backoffOpt === void 0 ? null : typeof backoffOpt === "string" ? resolveBackoffPreset(backoffOpt) : backoffOpt;
+  return { maxRetries, strategy };
+}
+function retryFactoryArgs(opts) {
+  const args = {};
+  if (opts?.count !== void 0) args.count = opts.count;
+  if (typeof opts?.backoff === "string") args.backoff = opts.backoff;
+  return Object.keys(args).length > 0 ? args : void 0;
+}
+function _runRetryStateMachine(getCfg, acquireSource, a, emitState) {
+  let attempt = 0;
+  let stopped = false;
+  let prevDelay = null;
+  let unsub;
+  const timer = new import_core2.ResettableTimer();
+  const publish = (status) => {
+    emitState?.({ status, attempt, lastDelay_ns: prevDelay });
+  };
+  publish("pending");
+  function disconnectUpstream() {
+    unsub?.();
+    unsub = void 0;
+  }
+  function scheduleRetryOrFinish(err) {
+    if (stopped) return;
+    const cfg = getCfg();
+    if (attempt >= cfg.maxRetries) {
+      disconnectUpstream();
+      publish("errored");
+      a.down([[import_core2.ERROR, err]]);
+      return;
+    }
+    const raw = cfg.strategy === null ? 0 : cfg.strategy(attempt, err, prevDelay);
+    if (raw === null || raw === void 0) {
+      disconnectUpstream();
+      publish("errored");
+      a.down([[import_core2.ERROR, err]]);
+      return;
+    }
+    let delayNs;
+    try {
+      delayNs = coerceDelayNs(raw);
+    } catch {
+      disconnectUpstream();
+      publish("errored");
+      a.down([[import_core2.ERROR, err]]);
+      return;
+    }
+    prevDelay = delayNs;
+    attempt += 1;
+    disconnectUpstream();
+    publish("paused");
+    const delayMs = delayNs > 0 ? delayNs / NS_PER_MS : 1;
+    timer.start(delayMs, () => {
+      if (stopped) return;
+      connect();
+    });
+  }
+  function connect() {
+    timer.cancel();
+    disconnectUpstream();
+    let src;
+    try {
+      src = acquireSource();
+    } catch (err) {
+      scheduleRetryOrFinish(err);
+      return;
+    }
+    publish("running");
+    unsub = src.subscribe((msgs) => {
+      if (stopped) return;
+      for (const m of msgs) {
+        const t = m[0];
+        if (t === import_core2.DIRTY) a.down([[import_core2.DIRTY]]);
+        else if (t === import_core2.DATA) {
+          attempt = 0;
+          prevDelay = null;
+          a.emit(m[1]);
+          publish("running");
+        } else if (t === import_core2.RESOLVED) a.down([[import_core2.RESOLVED]]);
+        else if (t === import_core2.COMPLETE) {
+          stopped = true;
+          disconnectUpstream();
+          publish("completed");
+          a.down([[import_core2.COMPLETE]]);
+        } else if (t === import_core2.ERROR) {
+          scheduleRetryOrFinish(msgVal(m));
+          return;
+        } else a.down([m]);
+      }
+    });
+  }
+  connect();
+  return () => {
+    const wasStopped = stopped;
+    stopped = true;
+    timer.cancel();
+    disconnectUpstream();
+    if (!wasStopped) publish("cancelled");
+  };
+}
+function retry(input, opts) {
+  const retryState = (0, import_core2.node)([], {
+    name: "retryState",
+    describeKind: "state",
+    initial: { status: "pending", attempt: 0, lastDelay_ns: null },
+    equals: (a, b) => a === b || a != null && b != null && typeof a === "object" && typeof b === "object" && JSON.stringify(a) === JSON.stringify(b)
+  });
+  const emit = (s) => {
+    retryState.down([[import_core2.DIRTY], [import_core2.DATA, s]]);
+  };
+  if (typeof input === "function") {
+    return {
+      node: _retryFactory(input, opts, emit),
+      retryState
+    };
+  }
+  return {
+    node: _retrySource(input, opts, emit),
+    retryState
+  };
+}
+function makeMergedOptsMirror(arg) {
+  if (arg === void 0) {
+    return { current: () => void 0, unsub: () => void 0 };
+  }
+  if (!isNode(arg)) {
+    return { current: () => arg, unsub: () => void 0 };
+  }
+  const optsNode = arg;
+  let merged = optsNode.cache ?? void 0;
+  const unsub = optsNode.subscribe((msgs) => {
+    for (const m of msgs) {
+      if (m[0] !== import_core2.DATA) continue;
+      const next = m[1];
+      if (next == null || typeof next !== "object") continue;
+      if (Object.keys(next).length === 0) continue;
+      merged = { ...merged ?? {}, ...next };
+    }
+  });
+  return { current: () => merged, unsub };
+}
+var _retrySourceNonResubscribableWarned = /* @__PURE__ */ new WeakSet();
+function _retrySource(source, opts, emitState) {
+  const sourceWithFlag = source;
+  if (sourceWithFlag._resubscribable === false && !_retrySourceNonResubscribableWarned.has(source)) {
+    _retrySourceNonResubscribableWarned.add(source);
+    console.warn(
+      "retry(source, opts): source-mode requires `resubscribable: true` on the upstream node. Retries will be silent no-ops after the first ERROR. Either pass `resubscribable: true` to the source factory, OR use factory-mode retry `retry(() => buildSource(), opts)` so each attempt builds a fresh node."
+    );
+  }
+  const staticOpts = isNode(opts) ? void 0 : opts;
+  if (!isNode(opts)) resolveRetryConfig(staticOpts);
+  return (0, import_core2.node)(
+    (_data, a) => {
+      const merged = makeMergedOptsMirror(opts);
+      const getCfg = () => resolveRetryConfig(merged.current());
+      const inner = _runRetryStateMachine(getCfg, () => source, a, emitState);
+      return () => {
+        inner();
+        merged.unsub();
+      };
+    },
+    {
+      ...operatorOpts(),
+      initial: source.cache,
+      meta: {
+        ...staticOpts?.meta ?? {},
+        ...(0, import_core2.factoryTag)(
+          "retry",
+          isNode(opts) ? { reactiveOpts: true } : retryFactoryArgs(staticOpts)
+        )
+      }
+    }
+  );
+}
+function _retryFactory(factory, opts, emitState) {
+  const staticOpts = isNode(opts) ? void 0 : opts;
+  if (!isNode(opts)) resolveRetryConfig(staticOpts);
+  return (0, import_core2.node)(
+    (_data, a) => {
+      const merged = makeMergedOptsMirror(opts);
+      const getCfg = () => resolveRetryConfig(merged.current());
+      const inner = _runRetryStateMachine(getCfg, factory, a, emitState);
+      return () => {
+        inner();
+        merged.unsub();
+      };
+    },
+    {
+      ...operatorOpts(),
+      initial: staticOpts?.initial,
+      meta: {
+        ...staticOpts?.meta ?? {},
+        ...(0, import_core2.factoryTag)(
+          "retry",
+          isNode(opts) ? { reactiveOpts: true } : retryFactoryArgs(staticOpts)
+        )
+      }
+    }
+  );
+}
+
+// src/base/resilience/status.ts
+var import_core3 = require("@graphrefly/pure-ts/core");
+function withStatus(src, options) {
+  const initialStatus = options?.initialStatus ?? "pending";
+  const callerMeta = options?.meta;
+  const out = (0, import_core3.node)(
+    [],
+    (_deps, a) => {
+      let currentStatus = initialStatus;
+      out.meta.status.down([[import_core3.DATA, initialStatus]]);
+      out.meta.error.down([[import_core3.DATA, null]]);
+      const unsub = src.subscribe((msgs) => {
+        for (const m of msgs) {
+          const t = m[0];
+          if (t === import_core3.DIRTY) a.down([[import_core3.DIRTY]]);
+          else if (t === import_core3.DATA) {
+            if (currentStatus === "errored") {
+              (0, import_core3.batch)(() => {
+                out.meta.error.down([[import_core3.DATA, null]]);
+                out.meta.status.down([[import_core3.DATA, "running"]]);
+                a.emit(m[1]);
+              });
+              currentStatus = "running";
+            } else if (currentStatus !== "running") {
+              (0, import_core3.batch)(() => {
+                out.meta.status.down([[import_core3.DATA, "running"]]);
+                a.emit(m[1]);
+              });
+              currentStatus = "running";
+            } else {
+              a.emit(m[1]);
+            }
+          } else if (t === import_core3.RESOLVED) a.down([[import_core3.RESOLVED]]);
+          else if (t === import_core3.COMPLETE) {
+            out.meta.status.down([[import_core3.DATA, "completed"]]);
+            currentStatus = "completed";
+            a.down([[import_core3.COMPLETE]]);
+          } else if (t === import_core3.ERROR) {
+            const err = msgVal(m);
+            (0, import_core3.batch)(() => {
+              out.meta.error.down([[import_core3.DATA, err]]);
+              out.meta.status.down([[import_core3.DATA, "errored"]]);
+            });
+            currentStatus = "errored";
+            a.down([m]);
+          } else a.down([m]);
+        }
+      });
+      return unsub;
+    },
+    {
+      ...operatorOpts(),
+      meta: {
+        ...callerMeta ?? {},
+        status: initialStatus,
+        error: null,
+        ...(0, import_core3.factoryTag)("withStatus", { initialStatus })
+      },
+      completeWhenDepsComplete: false,
+      resubscribable: true,
+      initial: src.cache
+    }
+  );
+  return {
+    node: out,
+    status: out.meta.status,
+    error: out.meta.error
+  };
+}
+
+// src/base/resilience/timeout.ts
+var import_core4 = require("@graphrefly/pure-ts/core");
+var TimeoutError = class extends Error {
+  name = "TimeoutError";
+  constructor(ns) {
+    super(`Timed out after ${ns / NS_PER_MS}ms`);
+  }
+};
+function withTimeout(source, opts, extraOpts) {
+  const isReactive = isNode(opts);
+  let latestOpts = null;
+  if (!isReactive) {
+    const staticOpts = opts;
+    if (staticOpts.ns === void 0 || typeof staticOpts.ns !== "number" || !Number.isFinite(staticOpts.ns) || staticOpts.ns <= 0) {
+      throw new RangeError("withTimeout: opts.ns must be a positive finite number");
+    }
+    latestOpts = {
+      ns: staticOpts.ns,
+      ...staticOpts.meta != null ? { meta: staticOpts.meta } : {}
+    };
+  } else {
+    const cached = opts.cache;
+    if (cached !== void 0) {
+      if (cached.ns === void 0 || typeof cached.ns !== "number" || !Number.isFinite(cached.ns) || cached.ns <= 0) {
+        throw new RangeError(
+          "withTimeout: opts.ns must be a positive finite number on first settle"
+        );
+      }
+      latestOpts = {
+        ns: cached.ns,
+        ...cached.meta != null ? { meta: cached.meta } : {}
+      };
+    }
+  }
+  const callerMeta = extraOpts?.meta;
+  const factoryArgs = isReactive ? { ns: "Node<Partial<TimeoutOptions>>" } : { ns: latestOpts.ns };
+  const timeoutState = (0, import_core4.node)([], {
+    name: "timeoutState",
+    describeKind: "state",
+    initial: { status: "pending" },
+    equals: (a, b) => a === b || a != null && b != null && typeof a === "object" && typeof b === "object" && a.status === b.status && JSON.stringify(a) === JSON.stringify(b)
+  });
+  const out = (0, import_core4.node)(
+    (_data, a) => {
+      let stopped = false;
+      let lastDeadlineNs = 0;
+      const timer = new import_core4.ResettableTimer();
+      let optsUnsub = null;
+      let srcUnsub = null;
+      function emitState(next) {
+        timeoutState.down([[import_core4.DIRTY], [import_core4.DATA, next]]);
+      }
+      function startTimer() {
+        if (stopped) return;
+        if (latestOpts == null || typeof latestOpts.ns !== "number" || !Number.isFinite(latestOpts.ns) || latestOpts.ns <= 0) {
+          return;
+        }
+        const ns = latestOpts.ns;
+        lastDeadlineNs = ns;
+        const startedAt = (0, import_core4.monotonicNs)();
+        const delayMs = ns / NS_PER_MS;
+        emitState({
+          status: "running",
+          startedAt_ns: startedAt,
+          deadline_ns: ns
+        });
+        timer.start(delayMs, () => {
+          if (stopped) return;
+          stopped = true;
+          srcUnsub?.();
+          emitState({
+            status: "errored",
+            firedAt_ns: (0, import_core4.monotonicNs)(),
+            deadline_ns: ns
+          });
+          a.down([[import_core4.ERROR, new TimeoutError(ns)]]);
+        });
+      }
+      function attachSource() {
+        if (srcUnsub != null || stopped) return;
+        srcUnsub = source.subscribe((msgs) => {
+          for (const m of msgs) {
+            if (stopped) return;
+            const t = m[0];
+            if (t === import_core4.DIRTY) a.down([[import_core4.DIRTY]]);
+            else if (t === import_core4.DATA) {
+              startTimer();
+              a.emit(m[1]);
+            } else if (t === import_core4.RESOLVED) a.down([[import_core4.RESOLVED]]);
+            else if (t === import_core4.COMPLETE) {
+              timer.cancel();
+              stopped = true;
+              emitState({
+                status: "completed",
+                settledAt_ns: (0, import_core4.monotonicNs)()
+              });
+              a.down([[import_core4.COMPLETE]]);
+              return;
+            } else if (t === import_core4.ERROR) {
+              timer.cancel();
+              stopped = true;
+              emitState({
+                status: "errored",
+                firedAt_ns: (0, import_core4.monotonicNs)(),
+                deadline_ns: lastDeadlineNs
+              });
+              a.down([m]);
+              return;
+            } else if (t === import_core4.TEARDOWN) {
+              timer.cancel();
+              stopped = true;
+              a.down([m]);
+              return;
+            } else a.down([m]);
+          }
+        });
+        if (latestOpts != null && latestOpts.ns > 0) {
+          startTimer();
+        }
+      }
+      if (isReactive) {
+        const optsNode = opts;
+        optsUnsub = optsNode.subscribe((msgs) => {
+          for (const m of msgs) {
+            if (m[0] !== import_core4.DATA) continue;
+            const next = m[1];
+            if (next == null || typeof next !== "object") continue;
+            const keys = Object.keys(next);
+            if (keys.length === 0) continue;
+            if ("ns" in next) {
+              if (typeof next.ns !== "number" || !Number.isFinite(next.ns) || next.ns <= 0) {
+                if (latestOpts == null) {
+                  stopped = true;
+                  a.down([
+                    [
+                      import_core4.ERROR,
+                      new RangeError(
+                        "withTimeout: opts.ns must be a positive finite number on first settle"
+                      )
+                    ]
+                  ]);
+                  return;
+                }
+                continue;
+              }
+            }
+            const wasNull = latestOpts == null;
+            latestOpts = {
+              ...latestOpts ?? { ns: 0 },
+              ...next
+            };
+            if (wasNull && latestOpts.ns > 0) {
+              attachSource();
+            }
+          }
+        });
+      }
+      if (latestOpts != null) {
+        attachSource();
+      }
+      return () => {
+        stopped = true;
+        timer.cancel();
+        if (srcUnsub) srcUnsub();
+        if (optsUnsub) optsUnsub();
+      };
+    },
+    {
+      ...operatorOpts(),
+      initial: source.cache,
+      meta: { ...callerMeta ?? {}, ...(0, import_core4.factoryTag)("withTimeout", factoryArgs) }
+    }
+  );
+  return { node: out, timeoutState };
+}
+
+// src/utils/resilience/breaker.ts
+var import_core5 = require("@graphrefly/pure-ts/core");
+var CircuitOpenError = class extends Error {
+  name = "CircuitOpenError";
+  constructor() {
+    super("Circuit breaker is open");
+  }
+};
+function circuitBreaker(options) {
+  let threshold = 5;
+  let baseCooldownNs = 30 * NS_PER_SEC;
+  let cooldownStrategy = null;
+  let halfOpenMax = 1;
+  let now = import_core5.monotonicNs;
+  function applyOptions(o) {
+    threshold = Math.max(1, o?.failureThreshold ?? 5);
+    baseCooldownNs = clampNonNegative(o?.cooldownNs ?? 30 * NS_PER_SEC);
+    cooldownStrategy = o?.cooldown ?? null;
+    halfOpenMax = Math.max(1, o?.halfOpenMax ?? 1);
+    now = o?.now ?? import_core5.monotonicNs;
+  }
+  let _state = "closed";
+  let _failureCount = 0;
+  let _openCycle = 0;
+  let _lastOpenedAt = 0;
+  let _lastCooldownNs = baseCooldownNs;
+  let _halfOpenAttempts = 0;
+  let initialOpts;
+  let optsUnsub;
+  if (isNode(options)) {
+    const optsNode = options;
+    initialOpts = optsNode.cache;
+    applyOptions(initialOpts);
+    const lockedNow = initialOpts?.now;
+    const hadInitialCache = initialOpts !== void 0;
+    let firstEmit = hadInitialCache;
+    optsUnsub = optsNode.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] !== import_core5.DATA) continue;
+        if (firstEmit) {
+          firstEmit = false;
+          continue;
+        }
+        const next = m[1];
+        if (next == null || typeof next !== "object") continue;
+        if (Object.keys(next).length === 0) continue;
+        if ("now" in next && next.now !== lockedNow) {
+          console.error(
+            "circuitBreaker: ignoring mid-flight `now` change \u2014 clock override is mode-locked at construction. Prior `now` preserved."
+          );
+          continue;
+        }
+        const merged = {
+          ...initialOpts ?? {},
+          ...next,
+          ...lockedNow !== void 0 ? { now: lockedNow } : {}
+        };
+        applyOptions(merged);
+        initialOpts = merged;
+      }
+    });
+  } else {
+    applyOptions(options);
+  }
+  _lastCooldownNs = baseCooldownNs;
+  function getCooldownNs() {
+    if (!cooldownStrategy) return baseCooldownNs;
+    const delayNs = cooldownStrategy(_openCycle);
+    return delayNs !== null ? delayNs : baseCooldownNs;
+  }
+  function transitionToOpen() {
+    _state = "open";
+    _lastCooldownNs = getCooldownNs();
+    _lastOpenedAt = now();
+    _halfOpenAttempts = 0;
+  }
+  const breaker = {
+    canExecute() {
+      if (_state === "closed") return true;
+      if (_state === "open") {
+        const elapsed = now() - _lastOpenedAt;
+        if (elapsed >= _lastCooldownNs) {
+          _state = "half-open";
+          _halfOpenAttempts = 1;
+          return true;
+        }
+        return false;
+      }
+      if (_halfOpenAttempts < halfOpenMax) {
+        _halfOpenAttempts++;
+        return true;
+      }
+      return false;
+    },
+    recordSuccess() {
+      if (_state === "half-open") {
+        _state = "closed";
+        _failureCount = 0;
+        _openCycle = 0;
+      } else if (_state === "closed") {
+        _failureCount = 0;
+      }
+    },
+    recordFailure(_error) {
+      if (_state === "half-open") {
+        _openCycle++;
+        transitionToOpen();
+        return;
+      }
+      if (_state === "closed") {
+        _failureCount++;
+        if (_failureCount >= threshold) {
+          transitionToOpen();
+        }
+      }
+    },
+    get state() {
+      return _state;
+    },
+    get failureCount() {
+      return _failureCount;
+    },
+    reset() {
+      _state = "closed";
+      _failureCount = 0;
+      _openCycle = 0;
+      _halfOpenAttempts = 0;
+    },
+    dispose() {
+      optsUnsub?.();
+    }
+    // Internal accessors used by withBreaker for the BreakerState
+    // companion (DS-13.5.B). Not part of the public CircuitBreaker
+    // interface but exposed for the bundle wiring.
+  };
+  breaker._stateSnapshot = () => ({
+    status: _state,
+    failureCount: _failureCount,
+    openCycle: _openCycle,
+    lastOpenedAtNs: _lastOpenedAt,
+    halfOpenAttempts: _halfOpenAttempts,
+    lastCooldownNs: _lastCooldownNs
+  });
+  return breaker;
+}
+function withBreaker(breaker, options) {
+  const onOpen = options?.onOpen ?? "skip";
+  const callerMeta = options?.meta;
+  return (source) => {
+    const snapshot = breaker._stateSnapshot;
+    const initialSnapshot = snapshot ? snapshot() : {
+      status: breaker.state,
+      failureCount: breaker.failureCount,
+      openCycle: 0,
+      lastOpenedAtNs: 0,
+      halfOpenAttempts: 0,
+      lastCooldownNs: 0
+    };
+    const wrapped = (0, import_core5.node)(
+      [],
+      (_deps, a) => {
+        function syncState() {
+          const s = snapshot ? snapshot() : {
+            status: breaker.state,
+            failureCount: breaker.failureCount,
+            openCycle: 0,
+            lastOpenedAtNs: 0,
+            halfOpenAttempts: 0,
+            lastCooldownNs: 0
+          };
+          wrapped.meta.breakerState.down([[import_core5.DIRTY], [import_core5.DATA, s]]);
+        }
+        const unsub = source.subscribe((msgs) => {
+          for (const m of msgs) {
+            const t = m[0];
+            if (t === import_core5.DIRTY) a.down([[import_core5.DIRTY]]);
+            else if (t === import_core5.DATA) {
+              if (breaker.canExecute()) {
+                syncState();
+                a.emit(m[1]);
+              } else {
+                syncState();
+                if (onOpen === "error") a.down([[import_core5.ERROR, new CircuitOpenError()]]);
+                else a.down([[import_core5.RESOLVED]]);
+              }
+            } else if (t === import_core5.RESOLVED) a.down([[import_core5.RESOLVED]]);
+            else if (t === import_core5.COMPLETE) {
+              breaker.recordSuccess();
+              syncState();
+              a.down([[import_core5.COMPLETE]]);
+            } else if (t === import_core5.ERROR) {
+              breaker.recordFailure(msgVal(m));
+              syncState();
+              a.down([m]);
+            } else a.down([m]);
+          }
+        });
+        syncState();
+        return unsub;
+      },
+      {
+        ...operatorOpts(),
+        meta: {
+          ...callerMeta ?? {},
+          breakerState: initialSnapshot,
+          ...(0, import_core5.factoryTag)("withBreaker", { onOpen })
+        },
+        completeWhenDepsComplete: false,
+        initial: source.cache
+      }
+    );
+    return { node: wrapped, breakerState: wrapped.meta.breakerState };
+  };
+}
+
+// src/utils/resilience/budget-gate.ts
+var import_core6 = require("@graphrefly/pure-ts/core");
+
+// src/base/meta/domain-meta.ts
+function domainMeta(domain, kind, extra) {
+  return {
+    [domain]: true,
+    [`${domain}_type`]: kind,
+    ...extra ?? {}
+  };
+}
+
+// src/utils/resilience/budget-gate.ts
+var HeadIndexQueue = class {
+  buf = [];
+  head = 0;
+  get size() {
+    return this.buf.length - this.head;
+  }
+  push(item) {
+    this.buf.push(item);
+  }
+  /** O(1) — removes and returns the oldest item, or `undefined` when empty. */
+  shift() {
+    if (this.head >= this.buf.length) return void 0;
+    const item = this.buf[this.head];
+    this.buf[this.head] = void 0;
+    this.head++;
+    if (this.head > 32 && this.head * 2 > this.buf.length) {
+      this.buf = this.buf.slice(this.head);
+      this.head = 0;
+    }
+    return item;
+  }
+  clear() {
+    this.buf = [];
+    this.head = 0;
+  }
+};
+function budgetGate(source, constraints, opts) {
+  if (constraints.length === 0) throw new RangeError("budgetGate requires at least one constraint");
+  const constraintNodes = constraints.map((c) => c.node);
+  const allDeps = [source, ...constraintNodes];
+  const buffer = new HeadIndexQueue();
+  let paused = false;
+  let pendingResolved = false;
+  const lockId = /* @__PURE__ */ Symbol("budget-gate");
+  const latestValues = new Array(constraints.length);
+  function checkBudget() {
+    return constraints.every((c, i) => c.check(latestValues[i]));
+  }
+  function budgetGateStateEqual(a, b) {
+    if (a === b) return true;
+    if (a.status !== b.status) return false;
+    const sa = a.constraintsSnapshot;
+    const sb = b.constraintsSnapshot;
+    if (sa.length !== sb.length) return false;
+    for (let i = 0; i < sa.length; i++) {
+      const ai = sa[i];
+      const bi = sb[i];
+      if (ai === void 0 || bi === void 0) return false;
+      if (ai.name !== bi.name) return false;
+      if (ai.satisfied !== bi.satisfied) return false;
+      if (!Object.is(ai.value, bi.value)) return false;
+    }
+    return true;
+  }
+  const budgetGateState = (0, import_core6.node)([], {
+    name: "budgetGateState",
+    describeKind: "state",
+    initial: {
+      status: "closed",
+      constraintsSnapshot: constraints.map((c) => ({
+        name: c.name ?? c.node.name ?? "",
+        satisfied: false,
+        value: void 0
+      }))
+    },
+    equals: budgetGateStateEqual
+  });
+  let lastEmittedState = null;
+  function publishState() {
+    const snapshot = constraints.map((c, i) => {
+      const v = latestValues[i];
+      let satisfied = false;
+      try {
+        satisfied = c.check(v);
+      } catch (err) {
+        console.error(
+          `budgetGate: constraint "${c.name ?? c.node.name ?? `[${i}]`}" check threw; treating as not satisfied.`,
+          err
+        );
+        satisfied = false;
+      }
+      return {
+        name: c.name ?? c.node.name ?? "",
+        satisfied,
+        value: v
+      };
+    });
+    const status = snapshot.every((s) => s.satisfied) ? "open" : "closed";
+    const next = { status, constraintsSnapshot: snapshot };
+    if (lastEmittedState != null && budgetGateStateEqual(lastEmittedState, next)) {
+      return;
+    }
+    lastEmittedState = next;
+    budgetGateState.down([[import_core6.DIRTY], [import_core6.DATA, next]]);
+  }
+  function flushBuffer(actions) {
+    while (buffer.size > 0 && checkBudget()) {
+      const item = buffer.shift();
+      actions.emit(item);
+    }
+    if (buffer.size === 0 && pendingResolved) {
+      pendingResolved = false;
+      actions.down([[import_core6.RESOLVED]]);
+    }
+  }
+  const out = (0, import_core6.node)(
+    [],
+    (_data, gateActions) => {
+      for (let i = 0; i < constraints.length; i++) {
+        latestValues[i] = constraints[i].node.cache;
+      }
+      publishState();
+      const unsubs = [];
+      for (let depIdx = 0; depIdx < allDeps.length; depIdx++) {
+        const dep = allDeps[depIdx];
+        unsubs.push(
+          dep.subscribe((msgs) => {
+            for (const msg of msgs) {
+              _handleBudgetMessage(msg, depIdx, gateActions);
+            }
+          })
+        );
+      }
+      return () => {
+        for (const u of unsubs) u();
+      };
+    },
+    {
+      ...opts,
+      describeKind: "derived",
+      meta: domainMeta("resilience", "budget_gate", opts?.meta)
+    }
+  );
+  return { node: out, budgetGateState };
+  function _handleBudgetMessage(msg, depIndex, actions) {
+    const t = msg[0];
+    if (depIndex === 0) {
+      if (t === import_core6.DATA) {
+        if (checkBudget() && buffer.size === 0) {
+          actions.emit(msg[1]);
+        } else {
+          buffer.push(msg[1]);
+          if (!paused) {
+            paused = true;
+            actions.up([[import_core6.PAUSE, lockId]]);
+          }
+        }
+        return true;
+      }
+      if (t === import_core6.DIRTY) {
+        actions.down([[import_core6.DIRTY]]);
+        return true;
+      }
+      if (t === import_core6.RESOLVED) {
+        if (buffer.size === 0) {
+          actions.down([[import_core6.RESOLVED]]);
+        } else {
+          pendingResolved = true;
+        }
+        return true;
+      }
+      if (t === import_core6.COMPLETE || t === import_core6.ERROR) {
+        while (buffer.size > 0) {
+          actions.emit(buffer.shift());
+        }
+        pendingResolved = false;
+        if (paused) {
+          paused = false;
+          actions.up([[import_core6.RESUME, lockId]]);
+        }
+        actions.down([msg]);
+        return true;
+      }
+      return false;
+    }
+    if (t === import_core6.DATA) {
+      latestValues[depIndex - 1] = msg[1];
+    }
+    if (t === import_core6.DATA || t === import_core6.RESOLVED) {
+      const ok = checkBudget();
+      if (ok && buffer.size > 0) {
+        flushBuffer(actions);
+        if (buffer.size === 0 && paused) {
+          paused = false;
+          actions.up([[import_core6.RESUME, lockId]]);
+        }
+      } else if (!ok && !paused && buffer.size > 0) {
+        paused = true;
+        actions.up([[import_core6.PAUSE, lockId]]);
+      }
+      if (t === import_core6.DATA) publishState();
+      return true;
+    }
+    if (t === import_core6.DIRTY) {
+      return true;
+    }
+    if (t === import_core6.ERROR) {
+      actions.down([msg]);
+      return true;
+    }
+    if (t === import_core6.COMPLETE) {
+      return true;
+    }
+    return false;
+  }
+}
+
+// src/utils/resilience/fallback.ts
+var import_core7 = require("@graphrefly/pure-ts/core");
+var import_extra = require("@graphrefly/pure-ts/extra");
+function fallback(source, fb, options) {
+  const callerMeta = options?.meta;
+  return (0, import_core7.node)(
+    (_data, a) => {
+      let fallbackUnsub;
+      let sourceUnsub;
+      function switchToFallback() {
+        sourceUnsub?.();
+        sourceUnsub = void 0;
+        if (isNode(fb) || isThenable(fb) || isAsyncIterable(fb)) {
+          const fbNode = (0, import_extra.fromAny)(fb);
+          fallbackUnsub = fbNode.subscribe((fMsgs) => {
+            a.down(fMsgs);
+            for (const fm of fMsgs) {
+              const ft = fm[0];
+              if (ft === import_core7.COMPLETE || ft === import_core7.ERROR || ft === import_core7.TEARDOWN) {
+                fallbackUnsub = void 0;
+                return;
+              }
+            }
+          });
+        } else {
+          a.emit(fb);
+          a.down([[import_core7.COMPLETE]]);
+        }
+      }
+      sourceUnsub = source.subscribe((msgs) => {
+        for (const m of msgs) {
+          const t = m[0];
+          if (t === import_core7.DIRTY) a.down([[import_core7.DIRTY]]);
+          else if (t === import_core7.DATA) a.emit(m[1]);
+          else if (t === import_core7.RESOLVED) a.down([[import_core7.RESOLVED]]);
+          else if (t === import_core7.COMPLETE) a.down([[import_core7.COMPLETE]]);
+          else if (t === import_core7.ERROR) {
+            switchToFallback();
+            return;
+          } else if (t === import_core7.TEARDOWN) {
+            fallbackUnsub?.();
+            a.down([m]);
+            return;
+          } else a.down([m]);
+        }
+      });
+      return () => {
+        sourceUnsub?.();
+        fallbackUnsub?.();
+      };
+    },
+    {
+      ...operatorOpts(),
+      initial: source.cache,
+      meta: { ...callerMeta ?? {}, ...(0, import_core7.factoryTag)("fallback") }
+    }
+  );
+}
+
+// src/utils/resilience/rate-limiter.ts
+var import_core9 = require("@graphrefly/pure-ts/core");
+
+// src/utils/resilience/adaptive-rate-limiter.ts
+var import_core8 = require("@graphrefly/pure-ts/core");
+var import_extra2 = require("@graphrefly/pure-ts/extra");
+function makeAbortError(reason) {
+  const err = new Error(reason);
+  err.name = "AbortError";
+  return err;
+}
+function adaptiveRateLimiter(opts = {}) {
+  const burst = Math.max(1, opts.burstMultiplier ?? 1);
+  const clampCooldownMs = opts.clampCooldownMs ?? 6e4;
+  const rpmInputNode = opts.rpm != null ? (0, import_extra2.fromAny)(opts.rpm) : (0, import_core8.node)([], { initial: Number.POSITIVE_INFINITY });
+  const tpmInputNode = opts.tpm != null ? (0, import_extra2.fromAny)(opts.tpm) : (0, import_core8.node)([], { initial: Number.POSITIVE_INFINITY });
+  const signalRpmCap = (0, import_core8.node)([], {
+    initial: Number.POSITIVE_INFINITY,
+    name: "adaptiveRateLimiter/signalRpmCap"
+  });
+  const signalTpmCap = (0, import_core8.node)([], {
+    initial: Number.POSITIVE_INFINITY,
+    name: "adaptiveRateLimiter/signalTpmCap"
+  });
+  const lastSignal = (0, import_core8.node)([], {
+    initial: {},
+    name: "adaptiveRateLimiter/lastSignal"
+  });
+  const effectiveRpm = (0, import_core8.node)(
+    [rpmInputNode, signalRpmCap],
+    (batchData, actions, ctx) => {
+      const data = batchData.map(
+        (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+      );
+      actions.emit(Math.min(Number(data[0] ?? Infinity), Number(data[1] ?? Infinity)));
+    },
+    { name: "adaptiveRateLimiter/effectiveRpm", describeKind: "derived" }
+  );
+  const effectiveTpm = (0, import_core8.node)(
+    [tpmInputNode, signalTpmCap],
+    (batchData, actions, ctx) => {
+      const data = batchData.map(
+        (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+      );
+      actions.emit(Math.min(Number(data[0] ?? Infinity), Number(data[1] ?? Infinity)));
+    },
+    { name: "adaptiveRateLimiter/effectiveTpm", describeKind: "derived" }
+  );
+  let rpmBucket = makeBucket(
+    Number(rpmInputNode.cache ?? Number.POSITIVE_INFINITY),
+    burst
+  );
+  let tpmBucket = makeBucket(
+    Number(tpmInputNode.cache ?? Number.POSITIVE_INFINITY),
+    burst
+  );
+  let rpmHardStop = false;
+  let tpmHardStop = false;
+  const unsubRpm = effectiveRpm.subscribe((msgs) => {
+    for (const msg of msgs) {
+      if (msg[0] === import_core8.DATA) {
+        const v = Number(msg[1]);
+        if (Number.isFinite(v) && v > 0) {
+          rpmBucket = makeBucket(v, burst);
+          rpmHardStop = false;
+        } else if (v === Infinity) {
+          rpmBucket = makeBucket(Infinity, burst);
+          rpmHardStop = false;
+        } else if (v <= 0) {
+          rpmHardStop = true;
+        }
+      }
+    }
+  });
+  const unsubTpm = effectiveTpm.subscribe((msgs) => {
+    for (const msg of msgs) {
+      if (msg[0] === import_core8.DATA) {
+        const v = Number(msg[1]);
+        if (Number.isFinite(v) && v > 0) {
+          tpmBucket = makeBucket(v, burst);
+          tpmHardStop = false;
+        } else if (v === Infinity) {
+          tpmBucket = makeBucket(Infinity, burst);
+          tpmHardStop = false;
+        } else if (v <= 0) {
+          tpmHardStop = true;
+        }
+      }
+    }
+  });
+  let throttleUntilNs = 0;
+  const rpmDecayTimer = new import_core8.ResettableTimer();
+  const tpmDecayTimer = new import_core8.ResettableTimer();
+  let unsubAdapt;
+  if (opts.adaptation != null) {
+    const adaptNode = (0, import_extra2.fromAny)(opts.adaptation);
+    unsubAdapt = adaptNode.subscribe((msgs) => {
+      for (const msg of msgs) {
+        if (msg[0] === import_core8.DATA) applySignal(msg[1]);
+      }
+    });
+  }
+  function applySignal(sig) {
+    lastSignal.emit(sig);
+    if (sig.rpmCap != null && Number.isFinite(sig.rpmCap) && sig.rpmCap >= 0) {
+      signalRpmCap.emit(sig.rpmCap);
+      if (Number.isFinite(clampCooldownMs) && clampCooldownMs > 0) {
+        rpmDecayTimer.start(clampCooldownMs, () => signalRpmCap.emit(Number.POSITIVE_INFINITY));
+      }
+    }
+    if (sig.tpmCap != null && Number.isFinite(sig.tpmCap) && sig.tpmCap >= 0) {
+      signalTpmCap.emit(sig.tpmCap);
+      if (Number.isFinite(clampCooldownMs) && clampCooldownMs > 0) {
+        tpmDecayTimer.start(clampCooldownMs, () => signalTpmCap.emit(Number.POSITIVE_INFINITY));
+      }
+    }
+    if (sig.retryAfterMs != null && sig.retryAfterMs > 0) {
+      const resumeAt = (0, import_core8.monotonicNs)() + sig.retryAfterMs * 1e6;
+      if (resumeAt > throttleUntilNs) throttleUntilNs = resumeAt;
+    }
+  }
+  const pending = (0, import_core8.node)([], { initial: 0, name: "adaptiveRateLimiter/pending" });
+  const rpmAvailableNode = (0, import_core8.node)([], {
+    initial: Number.POSITIVE_INFINITY,
+    name: "adaptiveRateLimiter/rpmAvailable"
+  });
+  const tpmAvailableNode = (0, import_core8.node)([], {
+    initial: Number.POSITIVE_INFINITY,
+    name: "adaptiveRateLimiter/tpmAvailable"
+  });
+  const bumpPending = (delta) => {
+    pending.emit((pending.cache ?? 0) + delta);
+  };
+  const refreshAvailable = () => {
+    rpmAvailableNode.emit(rpmBucket.available());
+    tpmAvailableNode.emit(tpmBucket.available());
+  };
+  async function acquire(acquireOpts = {}) {
+    const requestCost = acquireOpts.requestCost ?? 1;
+    const tokenCost = acquireOpts.tokenCost ?? 0;
+    const abortSignal = acquireOpts.signal;
+    bumpPending(1);
+    try {
+      while (true) {
+        if (abortSignal?.aborted) throw makeAbortError("AdaptiveRateLimiter.acquire aborted");
+        const now = (0, import_core8.monotonicNs)();
+        if (throttleUntilNs > now) {
+          const waitMs = Math.ceil((throttleUntilNs - now) / 1e6);
+          await sleepReactive(waitMs, abortSignal);
+          continue;
+        }
+        if (requestCost > 0 && rpmHardStop || tokenCost > 0 && tpmHardStop) {
+          await sleepReactive(250, abortSignal);
+          continue;
+        }
+        const rpmAtAcquire = rpmBucket;
+        const tpmAtAcquire = tpmBucket;
+        const gotRpm = rpmAtAcquire.tryConsume(requestCost);
+        if (!gotRpm) {
+          await sleepReactive(estimateWaitMs(rpmAtAcquire, requestCost), abortSignal);
+          continue;
+        }
+        const gotTpm = tokenCost > 0 ? tpmAtAcquire.tryConsume(tokenCost) : true;
+        if (!gotTpm) {
+          rpmAtAcquire.putBack(requestCost);
+          await sleepReactive(estimateWaitMs(tpmAtAcquire, tokenCost), abortSignal);
+          continue;
+        }
+        refreshAvailable();
+        return;
+      }
+    } finally {
+      bumpPending(-1);
+    }
+  }
+  function recordUsage(delta) {
+    if (delta > 0) {
+      tpmBucket.tryConsume(delta);
+    } else if (delta < 0) {
+      tpmBucket.putBack(-delta);
+    }
+    refreshAvailable();
+  }
+  function dispose() {
+    unsubRpm();
+    unsubTpm();
+    unsubAdapt?.();
+    rpmDecayTimer.cancel();
+    tpmDecayTimer.cancel();
+  }
+  return {
+    effectiveRpm,
+    effectiveTpm,
+    lastSignal,
+    pending,
+    rpmAvailable: rpmAvailableNode,
+    tpmAvailable: tpmAvailableNode,
+    acquire,
+    recordUsage,
+    recordSignal: applySignal,
+    dispose
+  };
+}
+function makeBucket(perMinute, burst) {
+  if (!Number.isFinite(perMinute) || perMinute === Infinity) {
+    return tokenBucket(Number.MAX_SAFE_INTEGER, Number.MAX_SAFE_INTEGER);
+  }
+  const capacity = Math.max(1, perMinute * burst);
+  const refillPerSecond = perMinute / 60;
+  return tokenBucket(capacity, refillPerSecond);
+}
+function estimateWaitMs(bucket, needed) {
+  const have = bucket.available();
+  const deficit = Math.max(0, needed - have);
+  if (deficit <= 0) return 25;
+  return Math.min(5e3, Math.max(50, deficit * 100));
+}
+function sleepReactive(ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  if (signal?.aborted) return Promise.reject(makeAbortError("AdaptiveRateLimiter.acquire aborted"));
+  return new Promise((resolve, reject) => {
+    const timer = new import_core8.ResettableTimer();
+    let onAbort;
+    const cleanup = () => {
+      timer.cancel();
+      if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+    };
+    timer.start(ms, () => {
+      cleanup();
+      resolve();
+    });
+    if (signal) {
+      onAbort = () => {
+        cleanup();
+        reject(makeAbortError("AdaptiveRateLimiter.acquire aborted"));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+
+// src/utils/resilience/rate-limiter.ts
+function tokenBucket(capacity, refillPerSecond, opts) {
+  if (capacity <= 0) throw new RangeError("capacity must be > 0");
+  if (refillPerSecond < 0) throw new RangeError("refillPerSecond must be >= 0");
+  const clock = opts?.clock ?? import_core9.monotonicNs;
+  let tokens = capacity;
+  let updatedAt = clock();
+  function refill(now) {
+    if (refillPerSecond > 0) {
+      const elapsedNs = now - updatedAt;
+      tokens = Math.min(capacity, tokens + elapsedNs / NS_PER_SEC * refillPerSecond);
+    }
+    updatedAt = now;
+  }
+  return {
+    available() {
+      refill(clock());
+      return tokens;
+    },
+    tryConsume(cost = 1) {
+      if (cost <= 0) return true;
+      const now = clock();
+      refill(now);
+      if (tokens >= cost) {
+        tokens -= cost;
+        return true;
+      }
+      return false;
+    },
+    putBack(cost = 1) {
+      if (cost <= 0) return;
+      refill(clock());
+      tokens = Math.min(capacity, tokens + cost);
+    }
+  };
+}
+var RateLimiterOverflowError = class extends Error {
+  name = "RateLimiterOverflowError";
+  constructor(maxBuffer) {
+    super(`rateLimiter buffer overflow (maxBuffer=${maxBuffer})`);
+  }
+};
+function rateLimiterStateEqual(a, b) {
+  return a.status === b.status && a.droppedCount === b.droppedCount && a.pendingCount === b.pendingCount && a.paused === b.paused;
+}
+var RATE_LIMITER_INITIAL_STATE = Object.freeze({
+  status: "open",
+  droppedCount: 0,
+  pendingCount: 0,
+  paused: false
+});
+function rateLimiter(source, opts) {
+  const isReactive = isNode(opts);
+  if (!isReactive) {
+    const o = opts;
+    if (o.maxEvents <= 0) throw new RangeError("maxEvents must be > 0");
+    if (o.windowNs <= 0) throw new RangeError("windowNs must be > 0");
+    if (o.maxBuffer === void 0) {
+      throw new RangeError(
+        "rateLimiter requires explicit maxBuffer (use Infinity to opt in to unbounded)"
+      );
+    }
+    const isUnbounded0 = o.maxBuffer === Infinity;
+    if (!isUnbounded0 && (!Number.isInteger(o.maxBuffer) || o.maxBuffer < 1)) {
+      throw new RangeError("maxBuffer must be a positive integer (or Infinity for unbounded)");
+    }
+  }
+  const initialOpts = isReactive ? opts.cache : opts;
+  const initialMaxBuffer = initialOpts?.maxBuffer;
+  const isUnbounded = initialMaxBuffer === Infinity;
+  const out = (0, import_core9.node)(
+    (_data, a) => {
+      let maxEvents = initialOpts?.maxEvents ?? 1;
+      let windowNs = initialOpts?.windowNs ?? NS_PER_SEC;
+      let maxBuffer = initialMaxBuffer ?? 1;
+      let onOverflow = initialOpts?.onOverflow ?? "drop-newest";
+      let refillPerSec = maxEvents * NS_PER_SEC / windowNs;
+      let tokenTimeNs = NS_PER_SEC / refillPerSec;
+      let bucket = tokenBucket(maxEvents, refillPerSec);
+      const pending = isUnbounded ? makeArrayQueue() : ringBufferQueue(Math.max(1, maxBuffer));
+      const timer = new import_core9.ResettableTimer();
+      let terminated = false;
+      let dropped = 0;
+      const droppedNode = out.meta.droppedCount;
+      const stateNode = out.meta.rateLimitState;
+      let lastState = RATE_LIMITER_INITIAL_STATE;
+      function syncState() {
+        droppedNode.emit(dropped);
+        const isPaused = pending.size > 0;
+        const next = {
+          status: isPaused ? "throttled" : "open",
+          droppedCount: dropped,
+          pendingCount: pending.size,
+          paused: isPaused
+        };
+        if (!rateLimiterStateEqual(lastState, next)) {
+          lastState = next;
+          stateNode.emit(next);
+        }
+      }
+      lastState = RATE_LIMITER_INITIAL_STATE;
+      droppedNode.emit(0);
+      stateNode.emit(RATE_LIMITER_INITIAL_STATE);
+      const optMirror = resolveReactiveOption(
+        opts,
+        (next) => {
+          if (terminated) return;
+          if (next == null) return;
+          if (typeof next === "object" && Object.keys(next).length === 0) return;
+          if (!(next.maxEvents > 0) || !(next.windowNs > 0)) return;
+          const nextBuf = next.maxBuffer;
+          if (nextBuf === void 0) return;
+          const nextUnbounded = nextBuf === Infinity;
+          if (nextUnbounded !== isUnbounded) {
+            return;
+          }
+          if (!nextUnbounded && (!Number.isInteger(nextBuf) || nextBuf < 1)) return;
+          if (!nextUnbounded && nextBuf > maxBuffer) {
+            console.warn(
+              `rateLimiter: reactive maxBuffer grow (${maxBuffer} \u2192 ${nextBuf}) rejected. The pending ring buffer is allocated at construction; reactive maxBuffer is monotonically non-increasing. Recreate the rateLimiter with the larger cap if growth is required.`
+            );
+            return;
+          }
+          maxEvents = next.maxEvents;
+          windowNs = next.windowNs;
+          maxBuffer = nextBuf;
+          onOverflow = next.onOverflow ?? "drop-newest";
+          refillPerSec = maxEvents * NS_PER_SEC / windowNs;
+          tokenTimeNs = NS_PER_SEC / refillPerSec;
+          bucket = tokenBucket(maxEvents, refillPerSec);
+          if (!nextUnbounded) {
+            while (pending.size > maxBuffer) {
+              pending.shift();
+              dropped += 1;
+            }
+          }
+          syncState();
+        }
+      );
+      function tryEmit() {
+        while (pending.size > 0) {
+          if (bucket.tryConsume(1)) {
+            a.emit(pending.shift());
+            syncState();
+          } else {
+            timer.start(Math.max(1, tokenTimeNs / NS_PER_MS), tryEmit);
+            return;
+          }
+        }
+      }
+      function recordDrop() {
+        dropped += 1;
+        syncState();
+      }
+      function resetForTerminal() {
+        terminated = true;
+        timer.cancel();
+        while (pending.size > 0) pending.shift();
+        dropped = 0;
+      }
+      const unsub = source.subscribe((msgs) => {
+        for (const m of msgs) {
+          if (terminated) return;
+          const t = m[0];
+          if (t === import_core9.DIRTY) a.down([[import_core9.DIRTY]]);
+          else if (t === import_core9.DATA) {
+            if (!isUnbounded && pending.size >= maxBuffer) {
+              if (onOverflow === "drop-newest") {
+                recordDrop();
+              } else if (onOverflow === "drop-oldest") {
+                pending.shift();
+                pending.push(m[1]);
+                recordDrop();
+              } else {
+                recordDrop();
+                resetForTerminal();
+                a.down([[import_core9.ERROR, new RateLimiterOverflowError(maxBuffer)]]);
+                return;
+              }
+            } else {
+              pending.push(m[1]);
+              syncState();
+            }
+            tryEmit();
+          } else if (t === import_core9.RESOLVED) a.down([[import_core9.RESOLVED]]);
+          else if (t === import_core9.COMPLETE) {
+            resetForTerminal();
+            a.down([[import_core9.COMPLETE]]);
+          } else if (t === import_core9.ERROR) {
+            resetForTerminal();
+            a.down([m]);
+          } else if (t === import_core9.TEARDOWN) {
+            resetForTerminal();
+            a.down([m]);
+            return;
+          } else a.down([m]);
+        }
+      });
+      return () => {
+        terminated = true;
+        timer.cancel();
+        unsub();
+        optMirror.unsub();
+      };
+    },
+    {
+      ...operatorOpts(),
+      initial: source.cache,
+      meta: {
+        // Caller-supplied meta first; companion seeds + factoryTag
+        // override below so they always win.
+        ...isReactive ? {} : opts.meta ?? {},
+        droppedCount: 0,
+        rateLimitState: RATE_LIMITER_INITIAL_STATE,
+        ...(0, import_core9.factoryTag)("rateLimiter", isReactive ? { reactiveOpts: true } : opts)
+      }
+    }
+  );
+  return {
+    node: out,
+    droppedCount: out.meta.droppedCount,
+    rateLimitState: out.meta.rateLimitState
+  };
+}
+function ringBufferQueue(capacity) {
+  const buf = new import_core9.RingBuffer(capacity);
+  return {
+    push: (v) => buf.push(v),
+    shift: () => buf.shift(),
+    get size() {
+      return buf.size;
+    }
+  };
+}
+function makeArrayQueue() {
+  const arr = [];
+  return {
+    push: (v) => {
+      arr.push(v);
+    },
+    shift: () => arr.shift(),
+    get size() {
+      return arr.length;
+    }
+  };
+}
+//# sourceMappingURL=index.cjs.map