nexus-ai-pro 2.1.0 → 2.2.0

package/dist/operations/adapters.d.ts

@@ -3,7 +3,8 @@ import type { OperationDispatcher, OperationRecord, OperationStore, OperationSto
  * The Redis commands the operation store needs.
  *
  * Structural rather than tied to one client, so `ioredis`, `node-redis`, or a cluster proxy all
- * satisfy it without this package depending on any of them.
+ * satisfy it without this package depending on any of them. The sorted-set commands are needed only
+ * with `index: true`; `ioredis` has them all.
  */
 export interface RedisOperationLikeClient {
     /** Reads a hash field. */
@@ -16,6 +17,14 @@ export interface RedisOperationLikeClient {
     hvals(key: string): Promise<string[]> | string[];
     /** Optional CAS primitive. When absent the store falls back to a read-compare-write. */
     eval?(script: string, numKeys: number, ...args: string[]): Promise<unknown> | unknown;
+    /** Reads several hash fields in one round trip. Used by the index when present. */
+    hmget?(key: string, ...fields: string[]): Promise<Array<string | null>> | Array<string | null>;
+    /** Adds a sorted-set member. Needed with `index: true`. */
+    zadd?(key: string, score: number, member: string): Promise<unknown> | unknown;
+    /** Removes a sorted-set member. Needed with `index: true`. */
+    zrem?(key: string, member: string): Promise<unknown> | unknown;
+    /** Members by score, as `ZRANGEBYSCORE key min max LIMIT offset count`. Needed with `index: true`. */
+    zrangebyscore?(key: string, min: number | string, max: number | string, limit: 'LIMIT', offset: number, count: number): Promise<string[]> | string[];
 }
 /** Options for the Redis operation store. */
 export interface RedisOperationStoreOptions {
@@ -23,6 +32,19 @@ export interface RedisOperationStoreOptions {
     prefix?: string;
     /** Disables the Lua compare-and-set even when the client exposes `eval`. */
     useEval?: boolean;
+    /**
+     * Keeps queued work in a sorted set by age, and leased work in one by lease expiry, so
+     * `listQueued()` and `claimExpired()` read the oldest few records instead of every one: a claim
+     * costs the same with 100,000 operations queued as with 1,000. The records stay the source of
+     * truth; an index entry only says where to look, and one that no longer matches its record is
+     * skipped and removed.
+     *
+     * Off by default, because a 2.1 worker writes records without index entries. Turn it on once every
+     * worker sharing the prefix runs 2.2, then call `reindex()` once to index what is already there.
+     * Needs `zadd`, `zrem`, and `zrangebyscore`; with `eval`, a record and its index entries change in
+     * one step.
+     */
+    index?: boolean;
 }
 /**
  * Redis-backed operation storage, so a submitted operation survives a restart.
@@ -36,8 +58,13 @@ export declare class RedisOperationStore<TResult = unknown> implements Operation
     private readonly client;
     private readonly prefix;
     private readonly useEval;
+    private readonly indexed;
     constructor(client: RedisOperationLikeClient, options?: RedisOperationStoreOptions);
-    /** Stores a new record and indexes its idempotency key. Refuses records carrying raw bytes. */
+    /**
+     * Stores a new record and indexes its idempotency key. Throws `OperationDuplicateError` when another
+     * record holds the key, checked in the same Lua call as the write when the client has `eval`.
+     * Refuses records carrying raw bytes.
+     */
     create(record: OperationRecord<TResult>): Promise<void>;
     /** Reads a record. */
     read(id: string): Promise<OperationRecord<TResult> | undefined>;
@@ -50,19 +77,40 @@ export declare class RedisOperationStore<TResult = unknown> implements Operation
     delete(id: string): Promise<boolean>;
     /**
      * Records whose lease has expired, or running records without one, up to `limit`, for another
-     * worker to take over.
+     * worker to take over. With the index, reads only records whose lease has lapsed.
      */
     claimExpired(now: string, limit: number): Promise<Array<OperationRecord<TResult>>>;
     /** Finds the record that claimed an idempotency key. */
     findByIdempotencyKey(key: string): Promise<OperationRecord<TResult> | undefined>;
     /** Every record. */
     list(): Promise<Array<OperationRecord<TResult>>>;
-    /** Queued records no worker holds, oldest first. Reads every record, as `list()` does. */
+    /**
+     * Queued records no worker holds, oldest first. With the index, reads them oldest first from the
+     * sorted set and stops at `limit`; without it, reads every record, as `list()` does.
+     */
     listQueued(limit: number, filter?: OperationStoreFilter): Promise<Array<OperationRecord<TResult>>>;
     /** Counts unfinished records by status. Reads every record, as `list()` does. */
     stats(now: string, filter?: OperationStoreFilter): Promise<OperationStoreStats>;
+    /**
+     * Indexes every record already stored, for turning `index` on over existing data. Safe to run
+     * while workers are busy, and to run again: it only adds entries, then removes those that no
+     * longer match their record, checking each record as it does. Resolves to how many records it read.
+     */
+    reindex(): Promise<number>;
+    /**
+     * Reads one index in score order up to `max`, a page at a time, keeping records that pass `keep`
+     * until `limit`. Entries whose record is gone or no longer `belongs` are removed afterwards.
+     */
+    private scanIndex;
+    private readMany;
+    /** Removes index entries that no longer describe their record. Only with `eval`, where the check is atomic. */
+    private prune;
+    /** Writes a record's index entries without `eval`, after the record itself. */
+    private place;
     private recordsKey;
     private idempotencyKey;
+    private queuedKey;
+    private leasesKey;
 }
 /** The part of a BullMQ `Queue` the dispatcher needs. */
 export interface BullMQLikeOperationQueue {

package/dist/operations/adapters.js

@@ -1,4 +1,5 @@
-import { isTerminalOperationStatus } from '../types/operations.js';
+import { isTerminalOperationStatus, TERMINAL_OPERATION_STATUSES } from '../types/operations.js';
+import { OperationDuplicateError } from './errors.js';
 import { assertSerializableRecord } from './serialization.js';
 import { countRecords, isUnheldQueued, matchesFilter } from './stats.js';
 const CAS_SCRIPT = `
@@ -9,21 +10,102 @@ if tonumber(decoded.sequence) ~= tonumber(ARGV[2]) then return 0 end
 redis.call('HSET', KEYS[1], ARGV[1], ARGV[3])
 return 1
 `;
+const PLACE_LUA = `
+local function place(key, score, id)
+  if score ~= '' then redis.call('ZADD', key, score, id) else redis.call('ZREM', key, id) end
+end
+`;
+const UNIQUE_KEY_LUA = `
+if ARGV[3] ~= '' then
+  local owner = redis.call('HGET', KEYS[2], ARGV[3])
+  if owner and owner ~= ARGV[1] and redis.call('HEXISTS', KEYS[1], owner) == 1 then return 0 end
+end
+`;
+const CREATE_SCRIPT = `${UNIQUE_KEY_LUA}
+redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
+if ARGV[3] ~= '' then redis.call('HSET', KEYS[2], ARGV[3], ARGV[1]) end
+return 1
+`;
+const INDEXED_CREATE_SCRIPT = `${PLACE_LUA}${UNIQUE_KEY_LUA}
+redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
+if ARGV[3] ~= '' then redis.call('HSET', KEYS[2], ARGV[3], ARGV[1]) end
+place(KEYS[3], ARGV[4], ARGV[1])
+place(KEYS[4], ARGV[5], ARGV[1])
+return 1
+`;
+const INDEXED_CAS_SCRIPT = `${PLACE_LUA}
+local current = redis.call('HGET', KEYS[1], ARGV[1])
+if current == false then return 0 end
+local decoded = cjson.decode(current)
+if tonumber(decoded.sequence) ~= tonumber(ARGV[2]) then return 0 end
+redis.call('HSET', KEYS[1], ARGV[1], ARGV[3])
+place(KEYS[2], ARGV[4], ARGV[1])
+place(KEYS[3], ARGV[5], ARGV[1])
+return 1
+`;
+const PRUNE_SCRIPT = `
+local terminal = { ${TERMINAL_OPERATION_STATUSES.map((status) => `${status} = true`).join(', ')} }
+local removed = 0
+for i = 2, #ARGV do
+  local raw = redis.call('HGET', KEYS[1], ARGV[i])
+  local keep = false
+  if raw then
+    local record = cjson.decode(raw)
+    if ARGV[1] == 'queued' then
+      keep = record.status == 'queued'
+    else
+      keep = (not terminal[record.status]) and (record.lease ~= nil or record.status == 'running')
+    end
+  end
+  if not keep then
+    redis.call('ZREM', KEYS[2], ARGV[i])
+    removed = removed + 1
+  end
+end
+return removed
+`;
 export class RedisOperationStore {
     client;
     prefix;
     useEval;
+    indexed;
     constructor(client, options = {}) {
         this.client = client;
         this.prefix = options.prefix ?? 'nexus-ai-pro:operations:';
         this.useEval = options.useEval !== false && typeof client.eval === 'function';
+        this.indexed = options.index === true;
+        if (this.indexed && !(client.zadd && client.zrem && client.zrangebyscore)) {
+            throw new TypeError('A Redis operation store with index: true needs zadd, zrem, and zrangebyscore');
+        }
     }
     async create(record) {
         assertSerializableRecord(record);
-        await this.client.hset(this.recordsKey(), record.id, JSON.stringify(record));
+        const encoded = JSON.stringify(record);
+        const duplicate = () => new OperationDuplicateError(record.idempotencyKey);
+        if (this.useEval && this.client.eval && !this.indexed) {
+            const created = await this.client.eval(CREATE_SCRIPT, 2, this.recordsKey(), this.idempotencyKey(), record.id, encoded, record.idempotencyKey ?? '');
+            if (Number(created) !== 1)
+                throw duplicate();
+            return;
+        }
+        if (this.indexed && this.useEval && this.client.eval) {
+            const { queued, lease } = indexScores(record);
+            const created = await this.client.eval(INDEXED_CREATE_SCRIPT, 4, this.recordsKey(), this.idempotencyKey(), this.queuedKey(), this.leasesKey(), record.id, encoded, record.idempotencyKey ?? '', queued, lease);
+            if (Number(created) !== 1)
+                throw duplicate();
+            return;
+        }
+        if (record.idempotencyKey) {
+            const owner = await this.client.hget(this.idempotencyKey(), record.idempotencyKey);
+            if (owner && owner !== record.id && (await this.client.hget(this.recordsKey(), owner)))
+                throw duplicate();
+        }
+        await this.client.hset(this.recordsKey(), record.id, encoded);
         if (record.idempotencyKey) {
             await this.client.hset(this.idempotencyKey(), record.idempotencyKey, record.id);
         }
+        if (this.indexed)
+            await this.place(record);
     }
     async read(id) {
         const raw = await this.client.hget(this.recordsKey(), id);
@@ -33,6 +115,11 @@ export class RedisOperationStore {
         assertSerializableRecord(record);
         const encoded = JSON.stringify(record);
         if (this.useEval && this.client.eval) {
+            if (this.indexed) {
+                const { queued, lease } = indexScores(record);
+                const result = await this.client.eval(INDEXED_CAS_SCRIPT, 3, this.recordsKey(), this.queuedKey(), this.leasesKey(), record.id, String(expectedSequence), encoded, queued, lease);
+                return Number(result) === 1;
+            }
             const result = await this.client.eval(CAS_SCRIPT, 1, this.recordsKey(), record.id, String(expectedSequence), encoded);
             return Number(result) === 1;
         }
@@ -40,6 +127,8 @@ export class RedisOperationStore {
         if (!current || current.sequence !== expectedSequence)
             return false;
         await this.client.hset(this.recordsKey(), record.id, encoded);
+        if (this.indexed)
+            await this.place(record);
         return true;
     }
     async delete(id) {
@@ -47,19 +136,22 @@ export class RedisOperationStore {
         if (record?.idempotencyKey)
             await this.client.hdel(this.idempotencyKey(), record.idempotencyKey);
         await this.client.hdel(this.recordsKey(), id);
+        if (this.indexed) {
+            await this.client.zrem?.(this.queuedKey(), id);
+            await this.client.zrem?.(this.leasesKey(), id);
+        }
         return record !== undefined;
     }
     async claimExpired(now, limit) {
+        if (this.indexed) {
+            return this.scanIndex('leases', Date.parse(now), limit, (record) => isExpired(record, now), isLeased);
+        }
         const records = await this.list();
         const expired = [];
         for (const record of records) {
             if (expired.length >= limit)
                 break;
-            if (isTerminalOperationStatus(record.status))
-                continue;
-            if (record.lease && record.lease.expiresAt > now)
-                continue;
-            if (record.status === 'running' || record.lease)
+            if (isExpired(record, now))
                 expired.push(record);
         }
         return expired;
@@ -74,6 +166,9 @@ export class RedisOperationStore {
     }
     async listQueued(limit, filter) {
         const now = new Date().toISOString();
+        if (this.indexed) {
+            return this.scanIndex('queued', Number.POSITIVE_INFINITY, limit, (record) => isUnheldQueued(record, now) && matchesFilter(record, filter), (record) => record.status === 'queued');
+        }
         return (await this.list())
             .filter((record) => isUnheldQueued(record, now) && matchesFilter(record, filter))
             .sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0))
@@ -82,12 +177,104 @@ export class RedisOperationStore {
     async stats(now, filter) {
         return countRecords(await this.list(), now, filter);
     }
+    async reindex() {
+        if (!this.indexed)
+            throw new TypeError('reindex() needs a store created with index: true');
+        const records = await this.list();
+        for (const record of records) {
+            const { queued, lease } = indexScores(record);
+            if (queued !== '')
+                await this.client.zadd?.(this.queuedKey(), Number(queued), record.id);
+            if (lease !== '')
+                await this.client.zadd?.(this.leasesKey(), Number(lease), record.id);
+        }
+        await this.prune('queued', records.filter((record) => record.status !== 'queued').map((record) => record.id));
+        await this.prune('leases', records.filter((record) => !isLeased(record)).map((record) => record.id));
+        return records.length;
+    }
+    async scanIndex(index, max, limit, keep, belongs) {
+        const found = [];
+        if (limit <= 0)
+            return found;
+        const stale = [];
+        const key = index === 'queued' ? this.queuedKey() : this.leasesKey();
+        const upper = max === Number.POSITIVE_INFINITY ? '+inf' : max;
+        const page = Math.max(16, limit * 4);
+        for (let offset = 0; found.length < limit; offset += page) {
+            const ids = (await this.client.zrangebyscore?.(key, '-inf', upper, 'LIMIT', offset, page)) ?? [];
+            const records = await this.readMany(ids);
+            for (const [position, id] of ids.entries()) {
+                const record = records[position];
+                if (!record || !belongs(record)) {
+                    stale.push(id);
+                    continue;
+                }
+                if (keep(record))
+                    found.push(record);
+                if (found.length >= limit)
+                    break;
+            }
+            if (ids.length < page)
+                break;
+        }
+        await this.prune(index, stale);
+        return found;
+    }
+    async readMany(ids) {
+        if (ids.length === 0)
+            return [];
+        const raws = this.client.hmget
+            ? await this.client.hmget(this.recordsKey(), ...ids)
+            : await Promise.all(ids.map((id) => this.client.hget(this.recordsKey(), id)));
+        return raws.map((raw) => (raw ? JSON.parse(raw) : undefined));
+    }
+    async prune(index, ids) {
+        if (ids.length === 0 || !this.useEval || !this.client.eval)
+            return;
+        const key = index === 'queued' ? this.queuedKey() : this.leasesKey();
+        for (let start = 0; start < ids.length; start += 500) {
+            await this.client.eval(PRUNE_SCRIPT, 2, this.recordsKey(), key, index, ...ids.slice(start, start + 500));
+        }
+    }
+    async place(record) {
+        const { queued, lease } = indexScores(record);
+        if (queued !== '')
+            await this.client.zadd?.(this.queuedKey(), Number(queued), record.id);
+        else
+            await this.client.zrem?.(this.queuedKey(), record.id);
+        if (lease !== '')
+            await this.client.zadd?.(this.leasesKey(), Number(lease), record.id);
+        else
+            await this.client.zrem?.(this.leasesKey(), record.id);
+    }
     recordsKey() {
         return `${this.prefix}records`;
     }
     idempotencyKey() {
         return `${this.prefix}idempotency`;
     }
+    queuedKey() {
+        return `${this.prefix}queued`;
+    }
+    leasesKey() {
+        return `${this.prefix}leases`;
+    }
+}
+function isExpired(record, now) {
+    if (isTerminalOperationStatus(record.status))
+        return false;
+    if (record.lease && record.lease.expiresAt > now)
+        return false;
+    return record.status === 'running' || record.lease !== undefined;
+}
+function isLeased(record) {
+    return !isTerminalOperationStatus(record.status) && (record.lease !== undefined || record.status === 'running');
+}
+function indexScores(record) {
+    return {
+        queued: record.status === 'queued' ? String(Date.parse(record.createdAt)) : '',
+        lease: isLeased(record) ? String(record.lease ? Date.parse(record.lease.expiresAt) : 0) : '',
+    };
 }
 export class BullMQOperationDispatcher {
     queue;

package/dist/operations/runner.js

@@ -93,6 +93,7 @@ export class OperationRunner {
             expiresAt: options.expiresAt,
             idempotencyKey: options.idempotencyKey,
             kind: options.kind,
+            ...(options.tenantId ? { tenantId: options.tenantId } : {}),
             traceContext: options.traceContext,
             metadata: options.metadata,
         };

package/dist/operations/stats.js

@@ -3,6 +3,8 @@ export function isUnheldQueued(record, now) {
     return record.status === 'queued' && (!record.lease || record.lease.expiresAt <= now);
 }
 export function matchesFilter(record, filter) {
+    if (filter?.tenantId !== undefined && record.tenantId !== filter.tenantId)
+        return false;
     return !filter?.kindPrefix || (record.kind ?? '').startsWith(filter.kindPrefix);
 }
 export function countRecords(records, now, filter) {
@@ -23,7 +25,12 @@ export function countRecords(records, now, filter) {
 }
 export async function operationStats(store, options = {}) {
     const now = (options.now ?? new Date()).toISOString();
-    const filter = options.kindPrefix ? { kindPrefix: options.kindPrefix } : undefined;
+    const filter = options.kindPrefix || options.tenantId !== undefined
+        ? {
+            ...(options.kindPrefix ? { kindPrefix: options.kindPrefix } : {}),
+            ...(options.tenantId !== undefined ? { tenantId: options.tenantId } : {}),
+        }
+        : undefined;
     if (store.stats)
         return store.stats(now, filter);
     if (store.list)

package/dist/operations/store.d.ts

@@ -19,7 +19,11 @@ export declare class MemoryOperationStore<TResult = unknown> implements Operatio
     private readonly byIdempotencyKey;
     private readonly maxRecords;
     constructor(options?: MemoryOperationStoreOptions);
-    /** Stores a new record. Refuses records carrying raw bytes. */
+    /**
+     * Stores a new record. Throws `OperationDuplicateError` when another record already holds its
+     * idempotency key, as every shared store does, so two submissions racing under one key cannot both
+     * start. Refuses records carrying raw bytes.
+     */
     create(record: OperationRecord<TResult>): void;
     /** Reads a record. */
     read(id: string): OperationRecord<TResult> | undefined;

package/dist/operations/store.js

@@ -1,4 +1,5 @@
 import { isTerminalOperationStatus } from '../types/operations.js';
+import { OperationDuplicateError } from './errors.js';
 import { assertSerializableRecord } from './serialization.js';
 import { countRecords, isUnheldQueued, matchesFilter } from './stats.js';
 export { assertSerializableRecord };
@@ -12,6 +13,12 @@ export class MemoryOperationStore {
     }
     create(record) {
         assertSerializableRecord(record);
+        if (record.idempotencyKey) {
+            const owner = this.byIdempotencyKey.get(record.idempotencyKey);
+            if (owner !== undefined && owner !== record.id && this.records.has(owner)) {
+                throw new OperationDuplicateError(record.idempotencyKey);
+            }
+        }
         this.records.set(record.id, clone(record));
         if (record.idempotencyKey)
             this.byIdempotencyKey.set(record.idempotencyKey, record.id);

package/dist/ops/circuit-breaker.d.ts

@@ -41,6 +41,15 @@ export interface CircuitBreakerConfig {
      * `nexus-ai-pro/ops/circuit-store` and `nexus-ai-pro/postgres/circuits`.
      */
     store?: CircuitStateStore;
+    /**
+     * Counts every worker's calls together, so nine failures spread over three workers count as nine.
+     * Each worker adds the calls it saw to a rolling window in the `store` when it syncs, and opens the
+     * circuit everywhere once the shared count crosses `failureThreshold` (failures since any worker's
+     * last success) or `failureRateThreshold`. Checks stay synchronous: a worker learns the shared count
+     * on its next sync, at most `syncIntervalMs` late. Needs a store with `observe()`; every bundled one
+     * has it. Off by default, when each worker counts only its own calls.
+     */
+    shareObservations?: boolean;
     /** Names this worker in shared state. Defaults to a random id. */
     workerId?: string;
     /** Shared state is refreshed at most this often, on the next check that needs it. Defaults to 1 second. */
@@ -85,6 +94,41 @@ export interface CircuitSnapshot {
     retryAt?: string;
     /** The most recent error, as text. */
     lastError?: string;
+    /** Every worker's calls together, as of this worker's last sync, with `shareObservations`. */
+    shared?: CircuitWindow;
+}
+/** Calls one worker saw since it last reported, which `CircuitStateStore.observe()` adds to the shared window. */
+export interface CircuitObservation {
+    /** Calls and failures per window bucket, by the bucket's start in epoch milliseconds. */
+    buckets: Array<{
+        at: number;
+        calls: number;
+        failures: number;
+    }>;
+    /** Whether any of the calls succeeded, which ends the shared failure streak before `trailingFailures` is added. */
+    succeeded: boolean;
+    /** Failures after the last success, or every failure when none succeeded. */
+    trailingFailures: number;
+    /** The rolling window, in milliseconds. */
+    windowMs: number;
+    /** The width of one bucket. A bucket that ended before `now - windowMs` is dropped. */
+    bucketMs: number;
+    /** Epoch milliseconds now, by the breaker's clock. */
+    now: number;
+    /**
+     * Epoch milliseconds of the circuit's last close. Buckets that started before it are not counted, so
+     * failures that opened a circuit do not reopen it the moment a probe closes it.
+     */
+    since?: number;
+}
+/** A provider's calls across every worker, inside the rolling window. */
+export interface CircuitWindow {
+    /** Calls counted. */
+    calls: number;
+    /** Of those, failures. */
+    failures: number;
+    /** Failures since any worker last reported a success. */
+    consecutiveFailures: number;
 }
 /** A circuit decision as every worker sees it. */
 export interface SharedCircuitState {
@@ -119,6 +163,12 @@ export interface CircuitStateStore {
      * recovering provider is probed once rather than by every replica at the same moment.
      */
     claimProbe(providerName: string, owner: string, ttlMs: number): Promise<boolean> | boolean;
+    /**
+     * Adds one worker's calls to a provider's shared window, and returns the window across every
+     * worker. Optional; `shareObservations` needs it. Each call must add atomically, so two workers
+     * reporting at once both count.
+     */
+    observe?(providerName: string, observation: CircuitObservation): Promise<CircuitWindow> | CircuitWindow;
 }
 /** @internal A circuit's local state. Shared with the coordinator module, never exported publicly. */
 export interface CircuitEntry {
@@ -139,6 +189,8 @@ export interface CircuitEntry {
     probeClaimed: boolean;
     /** Why the circuit last changed state. */
     reason?: string;
+    /** The shared window from the last sync, with `shareObservations`. */
+    shared?: CircuitWindow;
 }
 /**
  * Trips routing away from a provider that is failing.

package/dist/ops/circuit-breaker.js

@@ -69,6 +69,7 @@ export class CircuitBreaker {
         this.refreshState(providerName, entry);
         this.pushWindow(entry, false);
         entry.consecutiveFailures = 0;
+        this.coordinator?.observed(providerName, false);
         if (entry.state === 'half-open') {
             entry.halfOpenInFlight = Math.max(0, entry.halfOpenInFlight - 1);
             entry.halfOpenSuccesses += 1;
@@ -90,6 +91,7 @@ export class CircuitBreaker {
         }
         this.pushWindow(entry, true);
         entry.consecutiveFailures += 1;
+        this.coordinator?.observed(providerName, true);
         entry.lastError = error instanceof Error ? error.message : error === undefined ? undefined : String(error);
         if (entry.state === 'half-open') {
             entry.halfOpenInFlight = Math.max(0, entry.halfOpenInFlight - 1);
@@ -126,6 +128,7 @@ export class CircuitBreaker {
                     ? new Date(entry.openedAt + resetTimeoutMs).toISOString()
                     : undefined,
                 lastError: entry.lastError,
+                ...(entry.shared ? { shared: { ...entry.shared } } : {}),
             };
         });
     }
@@ -176,6 +179,7 @@ export class CircuitBreaker {
             entry.openedAt = undefined;
             entry.consecutiveFailures = 0;
             entry.window = [];
+            entry.shared = undefined;
             entry.halfOpenInFlight = 0;
             entry.halfOpenSuccesses = 0;
             entry.probeClaimed = false;

package/dist/ops/circuit-store.d.ts

@@ -1,5 +1,5 @@
-import type { CircuitStateStore, SharedCircuitState } from './circuit-breaker.js';
-export type { CircuitStateStore, SharedCircuitState } from './circuit-breaker.js';
+import type { CircuitObservation, CircuitStateStore, CircuitWindow, SharedCircuitState } from './circuit-breaker.js';
+export type { CircuitObservation, CircuitStateStore, CircuitWindow, SharedCircuitState, } from './circuit-breaker.js';
 /**
  * Shared circuit state in one process.
  *
@@ -10,7 +10,10 @@ export declare class MemoryCircuitStateStore implements CircuitStateStore {
     private readonly now;
     private readonly states;
     private readonly probes;
+    private readonly windows;
     constructor(now?: () => number);
+    /** Adds one worker's calls to a provider's window and returns the window across every worker. */
+    observe(providerName: string, observation: CircuitObservation): CircuitWindow;
     /** Every provider's shared circuit state. */
     read(): SharedCircuitState[];
     /**
@@ -66,7 +69,15 @@ export declare class RedisCircuitStateStore implements CircuitStateStore {
     private readonly client;
     private readonly prefix;
     private readonly useEval;
+    /**
+     * Adds one worker's calls to a provider's shared window in one Lua call, and returns the window
+     * across every worker. Present only when the client has `eval`, since the add and the sum must
+     * happen together; without it, `shareObservations` has nothing to call and each worker counts
+     * its own calls.
+     */
+    readonly observe?: (providerName: string, observation: CircuitObservation) => Promise<CircuitWindow>;
     constructor(client: RedisCircuitLikeClient, options?: RedisCircuitStateStoreOptions);
+    private observeWithEval;
     /** Every provider's shared circuit state. Unreadable entries are skipped. */
     read(): Promise<SharedCircuitState[]>;
     /**