@gkoos/caracal 0.1.0

package/dist/redis.js

@@ -0,0 +1,549 @@
+import { Redis, Cluster } from 'ioredis';
+import { createHash } from 'crypto';
+
+// src/coordination/redis/client.ts
+var CoordinatorUnavailableError = class extends Error {
+  coordination = "distributed";
+  constructor(cause) {
+    super("Redis coordination unavailable; command outcome may be unknown", {
+      cause
+    });
+    this.name = "CoordinatorUnavailableError";
+  }
+};
+function attachErrorSink(emitter) {
+  emitter.on("error", () => {
+  });
+}
+function createCoordinationClient(url, commandTimeout = 1e3) {
+  if (!Number.isSafeInteger(commandTimeout) || commandTimeout < 1)
+    throw new RangeError("commandTimeout must be a positive integer");
+  const client = new Redis(url, {
+    lazyConnect: true,
+    enableOfflineQueue: false,
+    maxRetriesPerRequest: 0,
+    autoResendUnfulfilledCommands: false,
+    commandTimeout,
+    connectTimeout: commandTimeout,
+    retryStrategy: (attempt) => Math.min(attempt * 50, 1e3)
+  });
+  attachErrorSink(client);
+  return client;
+}
+function createCoordinationClusterClient(nodes, commandTimeout = 1e3) {
+  if (!Number.isSafeInteger(commandTimeout) || commandTimeout < 1)
+    throw new RangeError("commandTimeout must be a positive integer");
+  if (!Array.isArray(nodes) || nodes.length === 0)
+    throw new RangeError("nodes must be a non-empty array of { host, port }");
+  const cluster = new Cluster([...nodes], {
+    lazyConnect: true,
+    enableOfflineQueue: false,
+    clusterRetryStrategy: (attempt) => Math.min(attempt * 50, 1e3),
+    redisOptions: {
+      commandTimeout,
+      connectTimeout: commandTimeout,
+      maxRetriesPerRequest: 0,
+      autoResendUnfulfilledCommands: false
+    }
+  });
+  attachErrorSink(cluster);
+  return cluster;
+}
+var scriptHashes = /* @__PURE__ */ new Map();
+function scriptSha(script) {
+  const cached = scriptHashes.get(script);
+  if (cached !== void 0) return cached;
+  const sha = createHash("sha1").update(script).digest("hex");
+  scriptHashes.set(script, sha);
+  return sha;
+}
+function errorMessage(error) {
+  if (typeof error === "string") return error;
+  if (error instanceof Error) return error.message;
+  return "";
+}
+async function evalScript(client, script, numberOfKeys, ...args) {
+  const evalsha = client.evalsha;
+  if (typeof evalsha !== "function") {
+    return client.eval(script, numberOfKeys, ...args);
+  }
+  try {
+    return await evalsha.call(client, scriptSha(script), numberOfKeys, ...args);
+  } catch (error) {
+    if (!errorMessage(error).includes("NOSCRIPT")) throw error;
+    return client.eval(script, numberOfKeys, ...args);
+  }
+}
+function coordinationKey(namespace, policy, operation, scope, suffix = "leases") {
+  for (const value of [namespace, policy, operation, scope, suffix]) {
+    if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value) > 1024)
+      throw new TypeError(
+        "Coordination identities must be nonempty strings of at most 1024 UTF-8 bytes"
+      );
+  }
+  const identity = createHash("sha256").update(JSON.stringify([namespace, policy, operation, scope])).digest("hex");
+  return `caracal:v1:{${identity}}:${suffix}`;
+}
+
+// src/coordination/redis/scripts.ts
+var leaseV1 = `
+local action = ARGV[1]
+local token = ARGV[2]
+local ttl = tonumber(ARGV[3])
+local limit = tonumber(ARGV[4])
+local time = redis.call('TIME')
+local now = time[1] * 1000 + math.floor(time[2] / 1000)
+redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', now)
+local existing = redis.call('ZSCORE', KEYS[1], token)
+if action == 'release' then
+  return redis.call('ZREM', KEYS[1], token)
+end
+if action == 'renew' and not existing then return 0 end
+if action == 'acquire' and existing then return 1 end
+if action == 'acquire' and redis.call('ZCARD', KEYS[1]) >= limit then return 0 end
+redis.call('ZADD', KEYS[1], now + ttl, token)
+local latest = redis.call('ZREVRANGE', KEYS[1], 0, 0, 'WITHSCORES')
+redis.call('PEXPIREAT', KEYS[1], math.ceil(tonumber(latest[2])))
+return 1
+`;
+var bulkheadLeaseV1 = `local function transition()
+${leaseV1}
+end
+local allowed = transition()
+return {allowed, redis.call('ZCARD', KEYS[1])}`;
+var breakerObserveV1 = `
+local outcome    = ARGV[1]
+local expectGen  = tonumber(ARGV[2])
+local windowTtl  = tonumber(ARGV[3])
+local minTP      = tonumber(ARGV[4])
+local threshNum  = tonumber(ARGV[5])
+local windowSize = tonumber(ARGV[6])
+local openMs     = tonumber(ARGV[7])
+local uuid       = ARGV[8]
+local t   = redis.call('TIME')
+local now = t[1] * 1000 + math.floor(t[2] / 1000)
+local f   = redis.call('HMGET', KEYS[1], 'state', 'generation')
+local state = f[1] or 'closed'
+local gen   = tonumber(f[2]) or 0
+if state ~= 'closed' then
+  local sc = (state == 'open' and 1) or (state == 'half-open' and 2) or 0
+  return {0, sc, gen, 0, 0}
+end
+if redis.call('EXISTS', KEYS[1]) == 0 then
+  -- No live state hash: a scope we have never seen, or a hash that was lost
+  -- while its window survived.
+  if expectGen ~= 0 then
+    -- The caller holds a generation this key cannot confirm.
+    return {0, 0, 0, 0, 0}
+  end
+  if redis.call('EXISTS', KEYS[2]) == 1 then
+    -- Members from a superseded epoch are still here.  Mint an epoch that has
+    -- never been used for this key (derived from the observation's own uuid, so
+    -- no clock is involved) instead of restarting at a value those members
+    -- would match.
+    --
+    -- Bounded to 11 hex digits (44 bits, <= 14 decimal digits) so the value
+    -- prints exactly with stock Lua number formatting: the epoch is read back
+    -- from the hash as a decimal string by both this script and the client, and
+    -- a larger value could be written in scientific notation and break the
+    -- round-trip.
+    gen = tonumber(string.sub(redis.sha1hex(uuid), 1, 11), 16)
+    if not gen or gen == 0 then gen = 1 end
+  else
+    gen = 0
+  end
+  redis.call('HSET', KEYS[1], 'state', 'closed', 'generation', gen,
+             'openedAt', 0, 'probeCount', 0, 'probeSuccesses', 0)
+elseif gen ~= expectGen then
+  return {0, 0, gen, 0, 0}
+end
+redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now - windowTtl)
+local member = tostring(gen) .. ':' .. uuid .. ':' .. outcome
+redis.call('ZADD', KEYS[2], 'NX', now, member)
+local cnt = redis.call('ZCARD', KEYS[2])
+if cnt > windowSize then
+  redis.call('ZREMRANGEBYRANK', KEYS[2], 0, cnt - windowSize - 1)
+end
+redis.call('PEXPIREAT', KEYS[2], now + windowTtl)
+local all     = redis.call('ZRANGE', KEYS[2], 0, -1)
+local prefix  = tostring(gen) .. ':'
+local wTotal  = 0
+local wFail   = 0
+for _, m in ipairs(all) do
+  if string.sub(m, 1, #prefix) == prefix then
+    wTotal = wTotal + 1
+    if string.sub(m, -8) == ':failure' then wFail = wFail + 1 end
+  end
+end
+if wTotal >= minTP and wFail * 1000 >= threshNum * wTotal then
+  gen = gen + 1
+  redis.call('HSET', KEYS[1], 'state', 'open', 'generation', gen,
+             'openedAt', now, 'probeCount', 0, 'probeSuccesses', 0)
+  -- OPEN state must never expire: a missing key is treated as closed,
+  -- which would silently admit unrestricted traffic and reset the generation.
+  redis.call('PERSIST', KEYS[1])
+  return {2, 1, gen, wTotal, wFail}
+end
+if redis.call('EXISTS', KEYS[1]) == 1 then
+  -- Still CLOSED.  The cleanup TTL must not expire the state before the window
+  -- it governs, otherwise retained members would survive their epoch.
+  redis.call('PEXPIRE', KEYS[1], math.max(openMs * 2, windowTtl))
+end
+return {1, 0, gen, wTotal, wFail}
+`;
+var breakerAdmitProbeV1 = `
+local probeToken    = ARGV[1]
+local openMs        = tonumber(ARGV[2])
+local maxProbes     = tonumber(ARGV[3])
+local probeLeaseTtl = tonumber(ARGV[4])
+local t   = redis.call('TIME')
+local now = t[1] * 1000 + math.floor(t[2] / 1000)
+local f = redis.call('HMGET', KEYS[1], 'state', 'generation', 'openedAt',
+                     'probeCount', 'probeSuccesses')
+local state     = f[1] or 'closed'
+local gen       = tonumber(f[2]) or 0
+local openedAt  = tonumber(f[3]) or 0
+local transitioned = 0
+if state == 'closed' then
+  return {0, 0, gen, 0, 0}
+end
+if state == 'open' then
+  if now - openedAt < openMs then
+    return {0, 1, gen, 0, 0}
+  end
+  state = 'half-open'
+  transitioned = 1
+  redis.call('HSET', KEYS[1], 'state', 'half-open', 'probeSuccesses', 0, 'probeCount', 0)
+  -- OPEN/HALF_OPEN must never expire; PERSIST removes any prior cleanup TTL.
+  redis.call('PERSIST', KEYS[1])
+  -- Tokens from the superseded recovery window must not consume slots in this
+  -- one; their settle is dropped by the generation check anyway.
+  redis.call('DEL', KEYS[2])
+end
+redis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)
+local activeProbes = redis.call('ZCARD', KEYS[2])
+if activeProbes >= maxProbes then
+  return {0, 2, gen, activeProbes, transitioned}
+end
+redis.call('ZADD', KEYS[2], 'NX', now + probeLeaseTtl, probeToken)
+activeProbes = activeProbes + 1
+redis.call('HSET', KEYS[1], 'probeCount', activeProbes)
+-- State hash must not expire while recovery probes are in flight.
+redis.call('PERSIST', KEYS[1])
+-- Probes sorted set expires naturally once the last lease elapses.
+redis.call('PEXPIREAT', KEYS[2], now + probeLeaseTtl + 1000)
+return {1, 2, gen, activeProbes, transitioned}
+`;
+var breakerSettleProbeV1 = `
+local probeToken  = ARGV[1]
+local outcome     = ARGV[2]
+local expectGen   = tonumber(ARGV[3])
+local halfOpenSucc = tonumber(ARGV[4])
+local openMs      = tonumber(ARGV[5])
+local windowTtl   = tonumber(ARGV[6])
+local t   = redis.call('TIME')
+local now = t[1] * 1000 + math.floor(t[2] / 1000)
+local f = redis.call('HMGET', KEYS[1], 'state', 'generation', 'probeSuccesses', 'probeCount')
+local state     = f[1] or 'closed'
+local gen       = tonumber(f[2]) or 0
+local probeSucc = tonumber(f[3]) or 0
+local probeCnt  = tonumber(f[4]) or 0
+local sc = (state == 'open' and 1) or (state == 'half-open' and 2) or 0
+local deadline = redis.call('ZSCORE', KEYS[2], probeToken)
+if not deadline then
+  -- Never admitted, already settled, or dropped with its recovery window.
+  return {0, sc, gen}
+end
+redis.call('ZREM', KEYS[2], probeToken)
+if tonumber(deadline) <= now then
+  -- The lease elapsed while the probe was still running: its slot was
+  -- recoverable, so the result cannot be counted.  Release the slot it still
+  -- occupied so the probe count keeps matching the token set.
+  probeCnt = math.max(0, probeCnt - 1)
+  redis.call('HSET', KEYS[1], 'probeCount', probeCnt)
+  return {0, sc, gen}
+end
+if state ~= 'half-open' or gen ~= expectGen then
+  return {0, sc, gen}
+end
+probeCnt = math.max(0, probeCnt - 1)
+if outcome == 'failure' then
+  gen = gen + 1
+  redis.call('HSET', KEYS[1], 'state', 'open', 'generation', gen,
+             'openedAt', now, 'probeCount', 0, 'probeSuccesses', 0)
+  -- Re-opened: OPEN must not expire (see breakerObserveV1 TTL policy).
+  redis.call('PERSIST', KEYS[1])
+  -- In-flight probes belong to the dead generation; free their slots so the
+  -- next recovery window starts with full capacity.
+  redis.call('DEL', KEYS[2])
+  return {2, 1, gen}
+end
+probeSucc = probeSucc + 1
+if probeSucc >= halfOpenSucc then
+  gen = gen + 1
+  redis.call('HSET', KEYS[1], 'state', 'closed', 'generation', gen,
+             'probeCount', 0, 'probeSuccesses', 0)
+  -- Newly CLOSED: expire for cleanup, but never before the window it governs.
+  redis.call('PEXPIRE', KEYS[1], math.max(openMs * 2, windowTtl))
+  redis.call('DEL', KEYS[2])
+  return {2, 0, gen}
+end
+redis.call('HSET', KEYS[1], 'probeSuccesses', probeSucc, 'probeCount', probeCnt)
+-- Still HALF_OPEN: must not expire while recovery is in progress.
+redis.call('PERSIST', KEYS[1])
+return {1, 2, gen}
+`;
+
+// src/coordination/redis/bulkhead.ts
+function redisCoordinator(client, options) {
+  const namespace = options.namespace;
+  coordinationKey(namespace, "bulkhead", "validate", "validate");
+  const coordinator = {
+    async command(identity, action, token, leaseMs, limit) {
+      if (!["acquire", "renew", "release"].includes(action) || typeof token !== "string" || !token || token.length > 256)
+        throw new TypeError("Invalid bulkhead lease action or token");
+      if (![leaseMs, limit].every(
+        (value) => Number.isSafeInteger(value) && value > 0
+      ) || leaseMs > 864e5)
+        throw new RangeError("Invalid bulkhead lease duration or limit");
+      const key = coordinationKey(
+        namespace,
+        `bulkhead:${identity.name}`,
+        identity.operation,
+        identity.scope
+      );
+      try {
+        const result = await evalScript(
+          client,
+          bulkheadLeaseV1,
+          1,
+          key,
+          action,
+          token,
+          leaseMs,
+          limit
+        );
+        if (!Array.isArray(result) || result.length !== 2 || ![0, 1].includes(result[0]) || !Number.isSafeInteger(result[1]) || result[1] < 0)
+          throw new Error("Invalid bulkhead reply");
+        return { allowed: result[0] === 1, occupancy: result[1] };
+      } catch (error) {
+        throw new CoordinatorUnavailableError(error);
+      }
+    }
+  };
+  return Object.freeze(coordinator);
+}
+
+// src/coordination/redis/circuit-breaker.ts
+function breakerKeys(namespace, identity) {
+  const policy = `breaker:${identity.name}`;
+  const hash = coordinationKey(
+    namespace,
+    policy,
+    identity.operation,
+    identity.scope,
+    "breaker"
+  );
+  const obs = coordinationKey(
+    namespace,
+    policy,
+    identity.operation,
+    identity.scope,
+    "observations"
+  );
+  const prob = coordinationKey(
+    namespace,
+    policy,
+    identity.operation,
+    identity.scope,
+    "probes"
+  );
+  return [hash, obs, prob];
+}
+function assertArray(reply, minLen, label) {
+  if (!Array.isArray(reply) || reply.length < minLen || reply.some((v) => typeof v !== "number" || !Number.isSafeInteger(v))) {
+    throw new Error(
+      `Invalid ${label} reply from Redis: ${JSON.stringify(reply)}`
+    );
+  }
+  return reply;
+}
+var STATE_CODES = ["closed", "open", "half-open"];
+function decodeState(code) {
+  const s = STATE_CODES[code];
+  if (!s) throw new Error(`Unknown breaker state code: ${code}`);
+  return s;
+}
+function redisCircuitBreakerCoordinator(client, options) {
+  const { namespace } = options;
+  coordinationKey(
+    namespace,
+    "breaker:validate",
+    "validate",
+    "validate",
+    "breaker"
+  );
+  const coordinator = {
+    async readState(identity) {
+      const [hashKey] = breakerKeys(namespace, identity);
+      try {
+        const fields = await client.hmget(hashKey, "state", "generation");
+        const rawState = fields[0];
+        if (!rawState) return null;
+        const state = rawState;
+        if (!STATE_CODES.includes(state))
+          throw new Error(`Unknown breaker state: ${rawState}`);
+        const generation = parseInt(fields[1] ?? "0", 10);
+        return { state, generation };
+      } catch (error) {
+        throw new CoordinatorUnavailableError(error);
+      }
+    },
+    async observe(identity, params) {
+      const [hashKey, obsKey] = breakerKeys(namespace, identity);
+      const {
+        generation,
+        outcome,
+        uuid,
+        windowTtlMs,
+        minimumThroughput,
+        failureThresholdNumerator,
+        windowSize,
+        openMs
+      } = params;
+      try {
+        const reply = await evalScript(
+          client,
+          breakerObserveV1,
+          2,
+          hashKey,
+          obsKey,
+          outcome,
+          generation,
+          windowTtlMs,
+          minimumThroughput,
+          failureThresholdNumerator,
+          windowSize,
+          openMs,
+          uuid
+        );
+        const r = assertArray(reply, 5, "breakerObserveV1");
+        const [status, , newGen, windowTotal, windowFailures] = r;
+        if (status === 0) {
+          return {
+            type: "stale",
+            currentGeneration: newGen
+          };
+        }
+        if (status === 2) {
+          return {
+            type: "opened",
+            newGeneration: newGen,
+            windowTotal,
+            windowFailures
+          };
+        }
+        return {
+          type: "observed",
+          generation: newGen,
+          windowTotal,
+          windowFailures
+        };
+      } catch (error) {
+        throw new CoordinatorUnavailableError(error);
+      }
+    },
+    async admitProbe(identity, params) {
+      const [hashKey, , probeKey] = breakerKeys(namespace, identity);
+      const { probeToken, openMs, halfOpenProbes, probeLeaseTtlMs } = params;
+      try {
+        const reply = await evalScript(
+          client,
+          breakerAdmitProbeV1,
+          2,
+          hashKey,
+          probeKey,
+          probeToken,
+          openMs,
+          halfOpenProbes,
+          probeLeaseTtlMs
+        );
+        const r = assertArray(reply, 5, "breakerAdmitProbeV1");
+        const [status, stateCode, gen, probeCount, transitioned] = r;
+        if (status === 0) {
+          const reason = stateCode === 0 ? "closed" : stateCode === 1 ? "open" : "probe-limit";
+          return {
+            type: "rejected",
+            reason,
+            generation: gen
+          };
+        }
+        return {
+          type: "admitted",
+          generation: gen,
+          probeCount,
+          stateChanged: transitioned === 1
+        };
+      } catch (error) {
+        throw new CoordinatorUnavailableError(error);
+      }
+    },
+    async settleProbe(identity, params) {
+      const [hashKey, , probeKey] = breakerKeys(namespace, identity);
+      const {
+        probeToken,
+        outcome,
+        generation,
+        halfOpenSuccesses,
+        openMs,
+        windowTtlMs
+      } = params;
+      try {
+        const reply = await evalScript(
+          client,
+          breakerSettleProbeV1,
+          2,
+          hashKey,
+          probeKey,
+          probeToken,
+          outcome,
+          generation,
+          halfOpenSuccesses,
+          openMs,
+          // Floor for the CLOSED cleanup TTL; older callers that do not pass it
+          // keep the historical openMs x 2 behaviour.
+          windowTtlMs ?? openMs * 2
+        );
+        const r = assertArray(reply, 3, "breakerSettleProbeV1");
+        const [status, stateCode, newGen] = r;
+        if (status === 0) {
+          return {
+            type: "stale",
+            generation: newGen
+          };
+        }
+        const state = decodeState(stateCode);
+        if (status === 2) {
+          return {
+            type: "transitioned",
+            newState: state,
+            newGeneration: newGen,
+            previousState: "half-open"
+          };
+        }
+        return {
+          type: "settled",
+          state,
+          generation: newGen
+        };
+      } catch (error) {
+        throw new CoordinatorUnavailableError(error);
+      }
+    }
+  };
+  return Object.freeze(coordinator);
+}
+
+export { CoordinatorUnavailableError, createCoordinationClient, createCoordinationClusterClient, redisCircuitBreakerCoordinator, redisCoordinator };
+//# sourceMappingURL=redis.js.map
+//# sourceMappingURL=redis.js.map

package/dist/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/coordination/redis/client.ts","../src/coordination/redis/eval-script.ts","../src/coordination/redis/keys.ts","../src/coordination/redis/scripts.ts","../src/coordination/redis/bulkhead.ts","../src/coordination/redis/circuit-breaker.ts"],"names":["createHash"],"mappings":"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","file":"redis.js","sourcesContent":["import { Cluster, Redis } from \"ioredis\"\n\nexport class CoordinatorUnavailableError extends Error {\n  readonly coordination = \"distributed\"\n  constructor(cause: unknown) {\n    super(\"Redis coordination unavailable; command outcome may be unknown\", {\n      cause,\n    })\n    this.name = \"CoordinatorUnavailableError\"\n  }\n}\n\nfunction attachErrorSink(emitter: {\n  on(event: \"error\", listener: () => void): void\n}): void {\n  emitter.on(\"error\", () => {\n    /* Commands surface errors; never crash on an unhandled EventEmitter error. */\n  })\n}\n\n/** Standalone Redis client. Caller owns it and must disconnect at shutdown. */\nexport function createCoordinationClient(\n  url: string,\n  commandTimeout = 1000,\n): Redis {\n  if (!Number.isSafeInteger(commandTimeout) || commandTimeout < 1)\n    throw new RangeError(\"commandTimeout must be a positive integer\")\n  const client = new Redis(url, {\n    lazyConnect: true,\n    enableOfflineQueue: false,\n    maxRetriesPerRequest: 0,\n    autoResendUnfulfilledCommands: false,\n    commandTimeout,\n    connectTimeout: commandTimeout,\n    retryStrategy: (attempt) => Math.min(attempt * 50, 1000),\n  })\n  attachErrorSink(client)\n  return client\n}\n\nexport interface ClusterNode {\n  readonly host: string\n  readonly port: number\n}\n\n/**\n * Redis Cluster client. Caller owns it and must disconnect at shutdown.\n *\n * All coordination keys use a hash-tag so that every key for a given\n * policy+operation+scope lands on the same cluster slot. Multi-key Lua\n * scripts (circuit breaker) are therefore cluster-safe without cross-slot\n * concerns.\n *\n * Call `connect()` before use and `disconnect()` at shutdown, matching the\n * standalone client contract.\n */\nexport function createCoordinationClusterClient(\n  nodes: ReadonlyArray<ClusterNode>,\n  commandTimeout = 1000,\n): Cluster {\n  if (!Number.isSafeInteger(commandTimeout) || commandTimeout < 1)\n    throw new RangeError(\"commandTimeout must be a positive integer\")\n  if (!Array.isArray(nodes) || nodes.length === 0)\n    throw new RangeError(\"nodes must be a non-empty array of { host, port }\")\n  const cluster = new Cluster([...nodes], {\n    lazyConnect: true,\n    enableOfflineQueue: false,\n    clusterRetryStrategy: (attempt) => Math.min(attempt * 50, 1000),\n    redisOptions: {\n      commandTimeout,\n      connectTimeout: commandTimeout,\n      maxRetriesPerRequest: 0,\n      autoResendUnfulfilledCommands: false,\n    },\n  })\n  attachErrorSink(cluster)\n  return cluster\n}\n","import { createHash } from \"node:crypto\"\n\n/**\n * Minimal Lua-script capability required by the Redis coordinators.\n *\n * `eval` is always required.  `evalsha` is optional so structural test doubles\n * and clients that only expose `eval` keep working; when it is missing the\n * script body is sent with `eval`.\n */\nexport interface ScriptClient {\n  eval(\n    script: string,\n    numberOfKeys: number,\n    ...args: (string | number)[]\n  ): Promise<unknown>\n  evalsha?(\n    sha: string,\n    numberOfKeys: number,\n    ...args: (string | number)[]\n  ): Promise<unknown>\n}\n\nconst scriptHashes = new Map<string, string>()\n\n/** SHA1 of a script body.  Redis keys its script cache by exactly this value. */\nexport function scriptSha(script: string): string {\n  const cached = scriptHashes.get(script)\n  if (cached !== undefined) return cached\n  const sha = createHash(\"sha1\").update(script).digest(\"hex\")\n  scriptHashes.set(script, sha)\n  return sha\n}\n\nfunction errorMessage(error: unknown): string {\n  if (typeof error === \"string\") return error\n  if (error instanceof Error) return error.message\n  return \"\"\n}\n\n/**\n * Executes a Lua script, sending the body only when it has to.\n *\n * The script cache is keyed by SHA1, so the steady state is `EVALSHA` - a\n * 40-byte hash instead of kilobytes of Lua on every call.  The full body goes\n * out with `EVAL` only when the client cannot send `EVALSHA`, or when the\n * server answers `NOSCRIPT`: the script cache lost the script to a restart, a\n * `SCRIPT FLUSH`, or (Redis 7.4 and later) LRU eviction under memory pressure.\n *\n * Retrying through `EVAL` is safe because Redis rejects an unknown SHA1 before\n * executing anything, so the failed command is known not to have run.  This is\n * deliberately narrower than the coordinator's command-timeout rule, where the\n * outcome is unknown and a replay is never allowed.  A timeout error is not a\n * `NOSCRIPT` error and propagates unchanged.\n */\nexport async function evalScript(\n  client: ScriptClient,\n  script: string,\n  numberOfKeys: number,\n  ...args: (string | number)[]\n): Promise<unknown> {\n  const evalsha = client.evalsha\n  if (typeof evalsha !== \"function\") {\n    return client.eval(script, numberOfKeys, ...args)\n  }\n  try {\n    return await evalsha.call(client, scriptSha(script), numberOfKeys, ...args)\n  } catch (error) {\n    if (!errorMessage(error).includes(\"NOSCRIPT\")) throw error\n    return client.eval(script, numberOfKeys, ...args)\n  }\n}\n","import { createHash } from \"node:crypto\"\n\n/**\n * Build a namespaced Redis key for a policy-scoped coordination slot.\n *\n * The SHA-256 hash of `[namespace, policy, operation, scope]` forms the\n * stable identity; `suffix` distinguishes multiple keys that share the\n * same identity (e.g. `:leases`, `:breaker`, `:observations`, `:probes`).\n * Default suffix is `\"leases\"` for backward compatibility with the bulkhead.\n */\nexport function coordinationKey(\n  namespace: string,\n  policy: string,\n  operation: string,\n  scope: string,\n  suffix = \"leases\",\n): string {\n  for (const value of [namespace, policy, operation, scope, suffix]) {\n    if (\n      typeof value !== \"string\" ||\n      !value.trim() ||\n      Buffer.byteLength(value) > 1024\n    )\n      throw new TypeError(\n        \"Coordination identities must be nonempty strings of at most 1024 UTF-8 bytes\",\n      )\n  }\n  const identity = createHash(\"sha256\")\n    .update(JSON.stringify([namespace, policy, operation, scope]))\n    .digest(\"hex\")\n  return `caracal:v1:{${identity}}:${suffix}`\n}\n","// ---------------------------------------------------------------------------\n// Versioned atomic operations, internal to the Redis policy capabilities.\n// ---------------------------------------------------------------------------\n\n// ---------------------------------------------------------------------------\n// Bulkhead scripts\n// ---------------------------------------------------------------------------\n\nexport const leaseV1 = `\nlocal action = ARGV[1]\nlocal token = ARGV[2]\nlocal ttl = tonumber(ARGV[3])\nlocal limit = tonumber(ARGV[4])\nlocal time = redis.call('TIME')\nlocal now = time[1] * 1000 + math.floor(time[2] / 1000)\nredis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', now)\nlocal existing = redis.call('ZSCORE', KEYS[1], token)\nif action == 'release' then\n  return redis.call('ZREM', KEYS[1], token)\nend\nif action == 'renew' and not existing then return 0 end\nif action == 'acquire' and existing then return 1 end\nif action == 'acquire' and redis.call('ZCARD', KEYS[1]) >= limit then return 0 end\nredis.call('ZADD', KEYS[1], now + ttl, token)\nlocal latest = redis.call('ZREVRANGE', KEYS[1], 0, 0, 'WITHSCORES')\nredis.call('PEXPIREAT', KEYS[1], math.ceil(tonumber(latest[2])))\nreturn 1\n`\n\n/** Returns the decision and occupancy from the same atomic transition. */\nexport const bulkheadLeaseV1 = `local function transition()\\n${leaseV1}\\nend\\nlocal allowed = transition()\\nreturn {allowed, redis.call('ZCARD', KEYS[1])}`\n\n// ---------------------------------------------------------------------------\n// Circuit-breaker scripts\n//\n// Return arrays use fixed positions so the TypeScript caller can validate\n// and decode without field names (which Lua/Redis cannot return).\n//\n// stateCode encoding:  0=closed  1=open  2=half-open\n// ---------------------------------------------------------------------------\n\n/**\n * Record one attempt outcome into the distributed sliding window.\n * Atomically opens the breaker when the failure ratio meets the threshold.\n *\n * KEYS[1] = breaker state hash         (:breaker)\n * KEYS[2] = observations sorted set    (:observations)\n *\n * ARGV[1] = outcome               \"success\" | \"failure\"\n * ARGV[2] = expectedGeneration    integer\n * ARGV[3] = windowTtlMs           observation retention window in ms\n * ARGV[4] = minimumThroughput     min observations before opening\n * ARGV[5] = failureThresholdNum   failure threshold × 1000 (e.g. 500 = 0.5)\n * ARGV[6] = windowSize            max observations retained by count\n * ARGV[7] = openMs                how long to stay OPEN; closed hash TTL = openMs×2\n * ARGV[8] = uuid                  unique string for member deduplication\n *\n * Returns: {status, stateCode, generation, windowTotal, windowFailures}\n *   status 0 = stale  (dropped; generation or state mismatch)\n *   status 1 = observed, no transition  (remained closed)\n *   status 2 = observed, breaker opened (stateCode=1, generation incremented)\n *\n * TTL policy:\n *   OPEN state  → PERSIST (no expiry).  A missing key is treated as closed by\n *                 all scripts, so expiring an open breaker would silently admit\n *                 unrestricted traffic and reset the generation counter.\n *   CLOSED state → max(openMs×2, windowTtlMs) TTL for eventual cleanup of idle\n *                 scopes.  Expiring a closed key is safe *only* because the TTL\n *                 outlives the observation window: the window is scoped by an\n *                 epoch, and an epoch that outlives its members is what keeps\n *                 cleanup from resurrecting them.\n *\n * Epochs:\n *   `generation` increments on every transition, and a brand new value is minted\n *   whenever the state hash has to be recreated while observation members from a\n *   previous epoch are still present (state lost to eviction or admin cleanup).\n *   Window membership is decided by comparing the stored epoch, so members from\n *   a superseded epoch can never be counted again, and an attempt holding a\n *   pre-loss generation can never pass the staleness check.  A scope that has\n *   never been observed keeps generation 0.\n */\nexport const breakerObserveV1 = `\nlocal outcome    = ARGV[1]\nlocal expectGen  = tonumber(ARGV[2])\nlocal windowTtl  = tonumber(ARGV[3])\nlocal minTP      = tonumber(ARGV[4])\nlocal threshNum  = tonumber(ARGV[5])\nlocal windowSize = tonumber(ARGV[6])\nlocal openMs     = tonumber(ARGV[7])\nlocal uuid       = ARGV[8]\nlocal t   = redis.call('TIME')\nlocal now = t[1] * 1000 + math.floor(t[2] / 1000)\nlocal f   = redis.call('HMGET', KEYS[1], 'state', 'generation')\nlocal state = f[1] or 'closed'\nlocal gen   = tonumber(f[2]) or 0\nif state ~= 'closed' then\n  local sc = (state == 'open' and 1) or (state == 'half-open' and 2) or 0\n  return {0, sc, gen, 0, 0}\nend\nif redis.call('EXISTS', KEYS[1]) == 0 then\n  -- No live state hash: a scope we have never seen, or a hash that was lost\n  -- while its window survived.\n  if expectGen ~= 0 then\n    -- The caller holds a generation this key cannot confirm.\n    return {0, 0, 0, 0, 0}\n  end\n  if redis.call('EXISTS', KEYS[2]) == 1 then\n    -- Members from a superseded epoch are still here.  Mint an epoch that has\n    -- never been used for this key (derived from the observation's own uuid, so\n    -- no clock is involved) instead of restarting at a value those members\n    -- would match.\n    --\n    -- Bounded to 11 hex digits (44 bits, <= 14 decimal digits) so the value\n    -- prints exactly with stock Lua number formatting: the epoch is read back\n    -- from the hash as a decimal string by both this script and the client, and\n    -- a larger value could be written in scientific notation and break the\n    -- round-trip.\n    gen = tonumber(string.sub(redis.sha1hex(uuid), 1, 11), 16)\n    if not gen or gen == 0 then gen = 1 end\n  else\n    gen = 0\n  end\n  redis.call('HSET', KEYS[1], 'state', 'closed', 'generation', gen,\n             'openedAt', 0, 'probeCount', 0, 'probeSuccesses', 0)\nelseif gen ~= expectGen then\n  return {0, 0, gen, 0, 0}\nend\nredis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now - windowTtl)\nlocal member = tostring(gen) .. ':' .. uuid .. ':' .. outcome\nredis.call('ZADD', KEYS[2], 'NX', now, member)\nlocal cnt = redis.call('ZCARD', KEYS[2])\nif cnt > windowSize then\n  redis.call('ZREMRANGEBYRANK', KEYS[2], 0, cnt - windowSize - 1)\nend\nredis.call('PEXPIREAT', KEYS[2], now + windowTtl)\nlocal all     = redis.call('ZRANGE', KEYS[2], 0, -1)\nlocal prefix  = tostring(gen) .. ':'\nlocal wTotal  = 0\nlocal wFail   = 0\nfor _, m in ipairs(all) do\n  if string.sub(m, 1, #prefix) == prefix then\n    wTotal = wTotal + 1\n    if string.sub(m, -8) == ':failure' then wFail = wFail + 1 end\n  end\nend\nif wTotal >= minTP and wFail * 1000 >= threshNum * wTotal then\n  gen = gen + 1\n  redis.call('HSET', KEYS[1], 'state', 'open', 'generation', gen,\n             'openedAt', now, 'probeCount', 0, 'probeSuccesses', 0)\n  -- OPEN state must never expire: a missing key is treated as closed,\n  -- which would silently admit unrestricted traffic and reset the generation.\n  redis.call('PERSIST', KEYS[1])\n  return {2, 1, gen, wTotal, wFail}\nend\nif redis.call('EXISTS', KEYS[1]) == 1 then\n  -- Still CLOSED.  The cleanup TTL must not expire the state before the window\n  -- it governs, otherwise retained members would survive their epoch.\n  redis.call('PEXPIRE', KEYS[1], math.max(openMs * 2, windowTtl))\nend\nreturn {1, 0, gen, wTotal, wFail}\n`\n\n/**\n * Admit a probe attempt.  Transitions OPEN→HALF_OPEN when openMs has elapsed,\n * then atomically allocates a probe token slot.\n *\n * KEYS[1] = breaker state hash         (:breaker)\n * KEYS[2] = probe tokens sorted set    (:probes)\n *\n * ARGV[1] = probeToken        unique UUID for this probe attempt\n * ARGV[2] = openMs            determines OPEN→HALF_OPEN transition and TTL\n * ARGV[3] = halfOpenProbes    maximum concurrent probe tokens\n * ARGV[4] = probeLeaseTtlMs   probe token TTL in ms\n *\n * Returns: {status, stateCode, generation, probeCount, transitioned}\n *   status 0 = rejected\n *     stateCode 0 = breaker already CLOSED (no probe needed)\n *     stateCode 1 = still OPEN (openMs not yet elapsed)\n *     stateCode 2 = HALF_OPEN but probe limit reached\n *   status 1 = admitted (probe token stored)\n *     transitioned 1 = OPEN→HALF_OPEN transition happened in this call\n *     transitioned 0 = was already HALF_OPEN\n */\nexport const breakerAdmitProbeV1 = `\nlocal probeToken    = ARGV[1]\nlocal openMs        = tonumber(ARGV[2])\nlocal maxProbes     = tonumber(ARGV[3])\nlocal probeLeaseTtl = tonumber(ARGV[4])\nlocal t   = redis.call('TIME')\nlocal now = t[1] * 1000 + math.floor(t[2] / 1000)\nlocal f = redis.call('HMGET', KEYS[1], 'state', 'generation', 'openedAt',\n                     'probeCount', 'probeSuccesses')\nlocal state     = f[1] or 'closed'\nlocal gen       = tonumber(f[2]) or 0\nlocal openedAt  = tonumber(f[3]) or 0\nlocal transitioned = 0\nif state == 'closed' then\n  return {0, 0, gen, 0, 0}\nend\nif state == 'open' then\n  if now - openedAt < openMs then\n    return {0, 1, gen, 0, 0}\n  end\n  state = 'half-open'\n  transitioned = 1\n  redis.call('HSET', KEYS[1], 'state', 'half-open', 'probeSuccesses', 0, 'probeCount', 0)\n  -- OPEN/HALF_OPEN must never expire; PERSIST removes any prior cleanup TTL.\n  redis.call('PERSIST', KEYS[1])\n  -- Tokens from the superseded recovery window must not consume slots in this\n  -- one; their settle is dropped by the generation check anyway.\n  redis.call('DEL', KEYS[2])\nend\nredis.call('ZREMRANGEBYSCORE', KEYS[2], '-inf', now)\nlocal activeProbes = redis.call('ZCARD', KEYS[2])\nif activeProbes >= maxProbes then\n  return {0, 2, gen, activeProbes, transitioned}\nend\nredis.call('ZADD', KEYS[2], 'NX', now + probeLeaseTtl, probeToken)\nactiveProbes = activeProbes + 1\nredis.call('HSET', KEYS[1], 'probeCount', activeProbes)\n-- State hash must not expire while recovery probes are in flight.\nredis.call('PERSIST', KEYS[1])\n-- Probes sorted set expires naturally once the last lease elapses.\nredis.call('PEXPIREAT', KEYS[2], now + probeLeaseTtl + 1000)\nreturn {1, 2, gen, activeProbes, transitioned}\n`\n\n/**\n * Record a probe attempt outcome.  Removes the probe token and applies the\n * result: failure re-opens; sufficient successes close the breaker.\n *\n * KEYS[1] = breaker state hash         (:breaker)\n * KEYS[2] = probe tokens sorted set    (:probes)\n *\n * ARGV[1] = probeToken          the token issued by admitProbe\n * ARGV[2] = outcome             \"success\" | \"failure\"\n * ARGV[3] = expectedGeneration  generation captured at admission time\n * ARGV[4] = halfOpenSuccesses   consecutive probe successes needed to close\n * ARGV[5] = openMs              how long the breaker stays OPEN (TTL floor)\n * ARGV[6] = windowTtlMs         observation retention (TTL floor): the CLOSED\n *                               hash must outlive the window it governs\n *\n * Returns: {status, stateCode, generation}\n *   status 0 = stale  (token missing, lease elapsed, or generation mismatch;\n *              the result is dropped and any consumed token is released)\n *   status 1 = settled, no state transition  (still HALF_OPEN)\n *   status 2 = settled, state transition occurred\n *     stateCode 0 = transitioned to CLOSED\n *     stateCode 1 = transitioned back to OPEN  (probe failure)\n *\n * A token carries its own deadline as its sorted-set score.  When the lease has\n * elapsed the slot is already recoverable - admitProbe prunes expired tokens\n * and re-issues the slot - so the result must not count even while the member is\n * still present.  The deadline is therefore checked under the same atomic call.\n */\nexport const breakerSettleProbeV1 = `\nlocal probeToken  = ARGV[1]\nlocal outcome     = ARGV[2]\nlocal expectGen   = tonumber(ARGV[3])\nlocal halfOpenSucc = tonumber(ARGV[4])\nlocal openMs      = tonumber(ARGV[5])\nlocal windowTtl   = tonumber(ARGV[6])\nlocal t   = redis.call('TIME')\nlocal now = t[1] * 1000 + math.floor(t[2] / 1000)\nlocal f = redis.call('HMGET', KEYS[1], 'state', 'generation', 'probeSuccesses', 'probeCount')\nlocal state     = f[1] or 'closed'\nlocal gen       = tonumber(f[2]) or 0\nlocal probeSucc = tonumber(f[3]) or 0\nlocal probeCnt  = tonumber(f[4]) or 0\nlocal sc = (state == 'open' and 1) or (state == 'half-open' and 2) or 0\nlocal deadline = redis.call('ZSCORE', KEYS[2], probeToken)\nif not deadline then\n  -- Never admitted, already settled, or dropped with its recovery window.\n  return {0, sc, gen}\nend\nredis.call('ZREM', KEYS[2], probeToken)\nif tonumber(deadline) <= now then\n  -- The lease elapsed while the probe was still running: its slot was\n  -- recoverable, so the result cannot be counted.  Release the slot it still\n  -- occupied so the probe count keeps matching the token set.\n  probeCnt = math.max(0, probeCnt - 1)\n  redis.call('HSET', KEYS[1], 'probeCount', probeCnt)\n  return {0, sc, gen}\nend\nif state ~= 'half-open' or gen ~= expectGen then\n  return {0, sc, gen}\nend\nprobeCnt = math.max(0, probeCnt - 1)\nif outcome == 'failure' then\n  gen = gen + 1\n  redis.call('HSET', KEYS[1], 'state', 'open', 'generation', gen,\n             'openedAt', now, 'probeCount', 0, 'probeSuccesses', 0)\n  -- Re-opened: OPEN must not expire (see breakerObserveV1 TTL policy).\n  redis.call('PERSIST', KEYS[1])\n  -- In-flight probes belong to the dead generation; free their slots so the\n  -- next recovery window starts with full capacity.\n  redis.call('DEL', KEYS[2])\n  return {2, 1, gen}\nend\nprobeSucc = probeSucc + 1\nif probeSucc >= halfOpenSucc then\n  gen = gen + 1\n  redis.call('HSET', KEYS[1], 'state', 'closed', 'generation', gen,\n             'probeCount', 0, 'probeSuccesses', 0)\n  -- Newly CLOSED: expire for cleanup, but never before the window it governs.\n  redis.call('PEXPIRE', KEYS[1], math.max(openMs * 2, windowTtl))\n  redis.call('DEL', KEYS[2])\n  return {2, 0, gen}\nend\nredis.call('HSET', KEYS[1], 'probeSuccesses', probeSucc, 'probeCount', probeCnt)\n-- Still HALF_OPEN: must not expire while recovery is in progress.\nredis.call('PERSIST', KEYS[1])\nreturn {1, 2, gen}\n`\n","import type { BulkheadCoordinator } from \"../../core/bulkhead.js\"\nimport { CoordinatorUnavailableError } from \"./client.js\"\nimport { evalScript } from \"./eval-script.js\"\nimport { coordinationKey } from \"./keys.js\"\nimport type { RedisScriptClient } from \"./leases.js\"\nimport { bulkheadLeaseV1 } from \"./scripts.js\"\nexport function redisCoordinator(\n  client: RedisScriptClient,\n  options: { namespace: string },\n): BulkheadCoordinator {\n  const namespace = options.namespace\n  coordinationKey(namespace, \"bulkhead\", \"validate\", \"validate\")\n  const coordinator: BulkheadCoordinator = {\n    async command(identity, action, token, leaseMs, limit) {\n      if (\n        ![\"acquire\", \"renew\", \"release\"].includes(action) ||\n        typeof token !== \"string\" ||\n        !token ||\n        token.length > 256\n      )\n        throw new TypeError(\"Invalid bulkhead lease action or token\")\n      if (\n        ![leaseMs, limit].every(\n          (value) => Number.isSafeInteger(value) && value > 0,\n        ) ||\n        leaseMs > 86400000\n      )\n        throw new RangeError(\"Invalid bulkhead lease duration or limit\")\n      const key = coordinationKey(\n        namespace,\n        `bulkhead:${identity.name}`,\n        identity.operation,\n        identity.scope,\n      )\n      try {\n        const result = await evalScript(\n          client,\n          bulkheadLeaseV1,\n          1,\n          key,\n          action,\n          token,\n          leaseMs,\n          limit,\n        )\n        if (\n          !Array.isArray(result) ||\n          result.length !== 2 ||\n          ![0, 1].includes(result[0]) ||\n          !Number.isSafeInteger(result[1]) ||\n          result[1] < 0\n        )\n          throw new Error(\"Invalid bulkhead reply\")\n        return { allowed: result[0] === 1, occupancy: result[1] as number }\n      } catch (error) {\n        throw new CoordinatorUnavailableError(error)\n      }\n    },\n  }\n  return Object.freeze(coordinator)\n}\n","import type {\n  AdmitProbeResult,\n  BreakerCoordinator,\n  BreakerIdentity,\n  BreakerState,\n  ObserveResult,\n  SettleProbeResult,\n} from \"../../core/circuit-breaker.js\"\nimport { CoordinatorUnavailableError } from \"./client.js\"\nimport { evalScript } from \"./eval-script.js\"\nimport { coordinationKey } from \"./keys.js\"\nimport type { RedisScriptClient } from \"./leases.js\"\nimport {\n  breakerAdmitProbeV1,\n  breakerObserveV1,\n  breakerSettleProbeV1,\n} from \"./scripts.js\"\n\n// ---------------------------------------------------------------------------\n// Key helpers\n// ---------------------------------------------------------------------------\n\nfunction breakerKeys(\n  namespace: string,\n  identity: BreakerIdentity,\n): [hashKey: string, obsKey: string, probeKey: string] {\n  const policy = `breaker:${identity.name}`\n  const hash = coordinationKey(\n    namespace,\n    policy,\n    identity.operation,\n    identity.scope,\n    \"breaker\",\n  )\n  const obs = coordinationKey(\n    namespace,\n    policy,\n    identity.operation,\n    identity.scope,\n    \"observations\",\n  )\n  const prob = coordinationKey(\n    namespace,\n    policy,\n    identity.operation,\n    identity.scope,\n    \"probes\",\n  )\n  return [hash, obs, prob]\n}\n\n// ---------------------------------------------------------------------------\n// Reply validation helpers\n// ---------------------------------------------------------------------------\n\nfunction assertArray(reply: unknown, minLen: number, label: string): unknown[] {\n  if (\n    !Array.isArray(reply) ||\n    reply.length < minLen ||\n    reply.some((v) => typeof v !== \"number\" || !Number.isSafeInteger(v))\n  ) {\n    throw new Error(\n      `Invalid ${label} reply from Redis: ${JSON.stringify(reply)}`,\n    )\n  }\n  return reply as unknown[]\n}\n\nconst STATE_CODES: BreakerState[] = [\"closed\", \"open\", \"half-open\"]\n\nfunction decodeState(code: number): BreakerState {\n  const s = STATE_CODES[code]\n  if (!s) throw new Error(`Unknown breaker state code: ${code}`)\n  return s\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Policy-specific Redis coordinator for `circuitBreaker.distributed()`.\n *\n * The caller owns `client` and must connect/disconnect it independently.\n * `namespace` is prepended to every key; use a per-service, per-environment\n * value to avoid cross-deployment state collisions.\n */\nexport function redisCircuitBreakerCoordinator(\n  client: RedisScriptClient,\n  options: { readonly namespace: string },\n): BreakerCoordinator {\n  const { namespace } = options\n  // Validate namespace eagerly (coordinationKey throws on bad input).\n  coordinationKey(\n    namespace,\n    \"breaker:validate\",\n    \"validate\",\n    \"validate\",\n    \"breaker\",\n  )\n\n  const coordinator: BreakerCoordinator = {\n    async readState(identity) {\n      const [hashKey] = breakerKeys(namespace, identity)\n      try {\n        const fields = await client.hmget(hashKey, \"state\", \"generation\")\n        const rawState = fields[0]\n        if (!rawState) return null\n        const state = rawState as BreakerState\n        if (!STATE_CODES.includes(state))\n          throw new Error(`Unknown breaker state: ${rawState}`)\n        const generation = parseInt(fields[1] ?? \"0\", 10)\n        return { state, generation }\n      } catch (error) {\n        throw new CoordinatorUnavailableError(error)\n      }\n    },\n\n    async observe(identity, params) {\n      const [hashKey, obsKey] = breakerKeys(namespace, identity)\n      const {\n        generation,\n        outcome,\n        uuid,\n        windowTtlMs,\n        minimumThroughput,\n        failureThresholdNumerator,\n        windowSize,\n        openMs,\n      } = params\n      try {\n        const reply = await evalScript(\n          client,\n          breakerObserveV1,\n          2,\n          hashKey,\n          obsKey,\n          outcome,\n          generation,\n          windowTtlMs,\n          minimumThroughput,\n          failureThresholdNumerator,\n          windowSize,\n          openMs,\n          uuid,\n        )\n        const r = assertArray(reply, 5, \"breakerObserveV1\") as number[]\n        const [status, , newGen, windowTotal, windowFailures] = r\n        if (status === 0) {\n          return {\n            type: \"stale\",\n            currentGeneration: newGen,\n          } satisfies ObserveResult\n        }\n        if (status === 2) {\n          return {\n            type: \"opened\",\n            newGeneration: newGen,\n            windowTotal,\n            windowFailures,\n          } satisfies ObserveResult\n        }\n        return {\n          type: \"observed\",\n          generation: newGen,\n          windowTotal,\n          windowFailures,\n        } satisfies ObserveResult\n      } catch (error) {\n        throw new CoordinatorUnavailableError(error)\n      }\n    },\n\n    async admitProbe(identity, params) {\n      const [hashKey, , probeKey] = breakerKeys(namespace, identity)\n      const { probeToken, openMs, halfOpenProbes, probeLeaseTtlMs } = params\n      try {\n        const reply = await evalScript(\n          client,\n          breakerAdmitProbeV1,\n          2,\n          hashKey,\n          probeKey,\n          probeToken,\n          openMs,\n          halfOpenProbes,\n          probeLeaseTtlMs,\n        )\n        const r = assertArray(reply, 5, \"breakerAdmitProbeV1\") as number[]\n        const [status, stateCode, gen, probeCount, transitioned] = r\n        if (status === 0) {\n          const reason =\n            stateCode === 0\n              ? \"closed\"\n              : stateCode === 1\n                ? \"open\"\n                : \"probe-limit\"\n          return {\n            type: \"rejected\",\n            reason,\n            generation: gen,\n          } satisfies AdmitProbeResult\n        }\n        return {\n          type: \"admitted\",\n          generation: gen,\n          probeCount,\n          stateChanged: transitioned === 1,\n        } satisfies AdmitProbeResult\n      } catch (error) {\n        throw new CoordinatorUnavailableError(error)\n      }\n    },\n\n    async settleProbe(identity, params) {\n      const [hashKey, , probeKey] = breakerKeys(namespace, identity)\n      const {\n        probeToken,\n        outcome,\n        generation,\n        halfOpenSuccesses,\n        openMs,\n        windowTtlMs,\n      } = params\n      try {\n        const reply = await evalScript(\n          client,\n          breakerSettleProbeV1,\n          2,\n          hashKey,\n          probeKey,\n          probeToken,\n          outcome,\n          generation,\n          halfOpenSuccesses,\n          openMs,\n          // Floor for the CLOSED cleanup TTL; older callers that do not pass it\n          // keep the historical openMs x 2 behaviour.\n          windowTtlMs ?? openMs * 2,\n        )\n        const r = assertArray(reply, 3, \"breakerSettleProbeV1\") as number[]\n        const [status, stateCode, newGen] = r\n        if (status === 0) {\n          return {\n            type: \"stale\",\n            generation: newGen,\n          } satisfies SettleProbeResult\n        }\n        const state = decodeState(stateCode)\n        if (status === 2) {\n          return {\n            type: \"transitioned\",\n            newState: state,\n            newGeneration: newGen,\n            previousState: \"half-open\",\n          } satisfies SettleProbeResult\n        }\n        return {\n          type: \"settled\",\n          state,\n          generation: newGen,\n        } satisfies SettleProbeResult\n      } catch (error) {\n        throw new CoordinatorUnavailableError(error)\n      }\n    },\n  }\n\n  return Object.freeze(coordinator)\n}\n"]}

package/dist/retry-BFP_k3Hg.d.ts

@@ -0,0 +1,26 @@
+import { h as Outcome, O as OperationCapabilities, e as ExecutionMetadata, P as Policy } from './types-Tf9T76C7.js';
+
+/**
+ * Settled-attempt information passed to a custom `delay` function.
+ *
+ * `result` and `error` are conveniences over `outcome`; the core never
+ * interprets them, so an adapter-specific helper can pace retries from
+ * protocol feedback (for example an HTTP `Retry-After` header) without
+ * leaking protocol types into the core.
+ */
+interface RetryContext {
+    readonly outcome: Outcome<unknown>;
+    readonly result: unknown;
+    readonly error: unknown;
+    readonly capabilities: OperationCapabilities;
+    readonly metadata: ExecutionMetadata;
+}
+type RetryDelay = number | ((attempt: number, context: RetryContext) => number);
+interface RetryOptions {
+    readonly maxAttempts: number;
+    readonly delay?: RetryDelay;
+}
+/** Retries adapter-classified failures within a single logical invocation. */
+declare function retry(options: RetryOptions): Policy;
+
+export { type RetryContext as R, type RetryDelay as a, type RetryOptions as b, retry as r };