nexus-ai-pro 2.0.0 → 2.2.0

package/dist-cjs/ops/circuit-sync.d.ts

@@ -26,6 +26,8 @@ export declare class CircuitCoordinator {
     private lastSyncAt;
     /** False after a store failure, until a sync succeeds; the breaker then decides locally. */
     private reachable;
+    /** Calls not yet added to the shared window, per provider, with `shareObservations`. */
+    private readonly unreported;
     constructor(host: CircuitHost);
     /**
      * Whether this worker may go half-open once a cooldown has elapsed. With a reachable store only
@@ -35,6 +37,11 @@ export declare class CircuitCoordinator {
     /** Starts a background sync when the last one is older than the interval. Never waits. */
     tick(): void;
     sync(): Promise<void>;
+    /**
+     * Counts one call toward the shared window, to be added on the next sync. Cheap and synchronous:
+     * a check never waits for the store.
+     */
+    observed(providerName: string, failed: boolean): void;
     /** Publishes a transition this worker made. */
     published(providerName: string, entry: CircuitEntry, to: 'open' | 'closed', reason: string): void;
     /** Publishes an operator reset, so every worker closes the circuit rather than only this one. */
@@ -45,6 +52,14 @@ export declare class CircuitCoordinator {
      */
     reconcile(): void;
     flush(): Promise<void>;
+    /**
+     * Adds this worker's unreported calls to each provider's shared window, then opens a closed circuit
+     * whose shared count crossed a threshold. The batch is taken before the first await, so calls made
+     * while it is in flight wait for the next sync rather than being lost or counted twice.
+     */
+    private report;
+    /** Opens a closed circuit whose shared window crossed the breaker's thresholds. */
+    private judge;
     /** Takes a decision another worker published, when it is newer than what this worker knows. */
     private adopt;
     /**
@@ -55,3 +70,5 @@ export declare class CircuitCoordinator {
     private publish;
     private failed;
 }
+/** The width of one shared-window bucket: a twelfth of the window, so a bucket rolling out moves the count by little. */
+export declare function bucketWidth(windowMs: number): number;

package/dist-cjs/ops/circuit-sync.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CircuitCoordinator = void 0;
+exports.bucketWidth = bucketWidth;
 class CircuitCoordinator {
     host;
     pending = new Set();
     syncing;
     lastSyncAt = Number.NEGATIVE_INFINITY;
     reachable = true;
+    unreported = new Map();
     constructor(host) {
         this.host = host;
     }
@@ -29,6 +31,8 @@ class CircuitCoordinator {
         this.syncing = (async () => {
             try {
                 this.lastSyncAt = this.host.now();
+                if (this.unreported.size > 0)
+                    await this.report(store);
                 for (const shared of await store.read())
                     this.adopt(shared);
                 const resetTimeoutMs = this.host.config.resetTimeoutMs ?? 30_000;
@@ -54,6 +58,29 @@ class CircuitCoordinator {
         })();
         return this.syncing;
     }
+    observed(providerName, failed) {
+        if (!this.host.config.shareObservations || !this.host.config.store?.observe)
+            return;
+        const bucketMs = bucketWidth(this.host.config.windowMs ?? 60_000);
+        const at = Math.floor(this.host.now() / bucketMs) * bucketMs;
+        let pending = this.unreported.get(providerName);
+        if (!pending) {
+            pending = { buckets: new Map(), succeeded: false, trailing: 0 };
+            this.unreported.set(providerName, pending);
+        }
+        const bucket = pending.buckets.get(at) ?? { calls: 0, failures: 0 };
+        bucket.calls += 1;
+        if (failed)
+            bucket.failures += 1;
+        pending.buckets.set(at, bucket);
+        if (failed)
+            pending.trailing += 1;
+        else {
+            pending.succeeded = true;
+            pending.trailing = 0;
+        }
+        this.tick();
+    }
     published(providerName, entry, to, reason) {
         entry.changedAt = this.stampAfter(entry.changedAt);
         this.publish({
@@ -75,6 +102,23 @@ class CircuitCoordinator {
     reconcile() {
         for (const name of [...this.host.names()]) {
             const entry = this.host.entry(name);
+            if (this.host.config.shareObservations && this.host.config.store?.observe && entry.window.length > 0) {
+                const bucketMs = bucketWidth(this.host.config.windowMs ?? 60_000);
+                const buckets = new Map();
+                for (const call of entry.window) {
+                    const at = Math.floor(call.at / bucketMs) * bucketMs;
+                    const bucket = buckets.get(at) ?? { calls: 0, failures: 0 };
+                    bucket.calls += 1;
+                    if (call.failed)
+                        bucket.failures += 1;
+                    buckets.set(at, bucket);
+                }
+                this.unreported.set(name, {
+                    buckets,
+                    succeeded: entry.window.some((call) => !call.failed),
+                    trailing: entry.consecutiveFailures,
+                });
+            }
             if (entry.state === 'open' && entry.changedAt === Number.NEGATIVE_INFINITY) {
                 this.published(name, entry, 'open', entry.reason ?? 'opened while shared state was loading');
             }
@@ -84,6 +128,46 @@ class CircuitCoordinator {
     async flush() {
         await Promise.all([...this.pending]);
     }
+    async report(store) {
+        if (!store.observe || this.unreported.size === 0)
+            return;
+        const batches = [...this.unreported];
+        this.unreported.clear();
+        const windowMs = this.host.config.windowMs ?? 60_000;
+        for (const [name, pending] of batches) {
+            const entry = this.host.entry(name);
+            const window = await store.observe(name, {
+                buckets: [...pending.buckets].map(([at, bucket]) => ({ at, calls: bucket.calls, failures: bucket.failures })),
+                succeeded: pending.succeeded,
+                trailingFailures: pending.trailing,
+                windowMs,
+                bucketMs: bucketWidth(windowMs),
+                now: this.host.now(),
+                ...(entry.state === 'closed' && Number.isFinite(entry.changedAt) ? { since: entry.changedAt } : {}),
+            });
+            entry.shared = {
+                calls: window.calls,
+                failures: window.failures,
+                consecutiveFailures: window.consecutiveFailures,
+            };
+            this.judge(name, entry, window);
+        }
+    }
+    judge(name, entry, window) {
+        if (entry.state !== 'closed')
+            return;
+        const config = this.host.config;
+        if (window.consecutiveFailures >= (config.failureThreshold ?? 5)) {
+            this.host.transition(name, entry, 'open', 'shared failure threshold reached');
+            return;
+        }
+        const rate = config.failureRateThreshold;
+        if (rate !== undefined &&
+            window.calls >= (config.minimumThroughput ?? 10) &&
+            window.failures / window.calls >= rate) {
+            this.host.transition(name, entry, 'open', 'shared failure rate threshold reached');
+        }
+    }
     adopt(shared) {
         const entry = this.host.entry(shared.providerName);
         if (shared.updatedAt <= entry.changedAt)
@@ -124,3 +208,6 @@ class CircuitCoordinator {
     }
 }
 exports.CircuitCoordinator = CircuitCoordinator;
+function bucketWidth(windowMs) {
+    return Math.max(1, Math.floor(windowMs / 12));
+}

package/dist-cjs/ops/health.d.ts

@@ -21,7 +21,18 @@ export interface ProviderHealthSnapshot {
      * latency up to 30.
      */
     score: number;
+    /**
+     * `unknown` with no recent calls to judge by, `unhealthy` past the failure threshold or under the
+     * minimum score, `degraded` when calls are failing or slow but not enough to stop routing to it,
+     * and `healthy` otherwise. Always set by `ProviderHealthMonitor`; optional so a hand-built snapshot
+     * still type-checks.
+     */
+    status?: ProviderHealthStatus;
+    /** True when the last call is older than `observationTtlMs`, so the figures above are old news. */
+    stale?: boolean;
 }
+/** Where a provider stands, by what its recent calls say. */
+export type ProviderHealthStatus = 'healthy' | 'degraded' | 'unhealthy' | 'unknown';
 /** Health tracking for providers, used to route around unhealthy ones. */
 export interface HealthConfig {
     /** Turns tracking on. Off by default, and then nothing is recorded. */
@@ -30,12 +41,22 @@ export interface HealthConfig {
     failureThreshold?: number;
     /** Score below which a provider is unhealthy. Defaults to 20. */
     minScore?: number;
+    /**
+     * How long a call's outcome counts, in milliseconds. A provider whose last call is older is
+     * `unknown`, and is routed to as a provider never seen is, rather than kept down for a failure
+     * hours ago or kept up for a success days ago. `checkProviders({ staleOnly: true })` refreshes it.
+     * Defaults to never expiring, as before.
+     */
+    observationTtlMs?: number;
+    /** Replaces the system clock, for tests. */
+    now?: () => Date;
 }
 /** Tracks provider health from call outcomes and scores each provider for routing. */
 export declare class ProviderHealthMonitor {
     private config;
     private states;
     constructor(config?: HealthConfig);
+    private nowDate;
     /** Records a successful call and its latency. */
     recordSuccess(providerName: string, latencyMs: number): void;
     /** Records a failed call. */
@@ -46,6 +67,9 @@ export declare class ProviderHealthMonitor {
     score(providerName: string): number;
     /** Whether a provider is healthy. */
     isHealthy(providerName: string): boolean;
+    /** Whether a provider's figures are too old to judge by, or there are none. */
+    isUnknown(providerName: string): boolean;
+    private isStale;
     private snapshotOne;
     private state;
 }

package/dist-cjs/ops/health.js

@@ -7,23 +7,30 @@ class ProviderHealthMonitor {
     constructor(config = {}) {
         this.config = config;
     }
+    nowDate() {
+        return this.config.now?.() ?? new Date();
+    }
     recordSuccess(providerName, latencyMs) {
         if (!this.config.enabled)
             return;
         const state = this.state(providerName);
         state.successes += 1;
         state.consecutiveFailures = 0;
+        if (this.isStale(state))
+            Object.assign(state, freshState());
         state.avgLatencyMs = state.avgLatencyMs ? state.avgLatencyMs * 0.7 + latencyMs * 0.3 : latencyMs;
-        state.lastCheckedAt = new Date().toISOString();
+        state.lastCheckedAt = this.nowDate().toISOString();
     }
     recordFailure(providerName, error) {
         if (!this.config.enabled)
             return;
         const state = this.state(providerName);
+        if (this.isStale(state))
+            state.consecutiveFailures = 0;
         state.failures += 1;
         state.consecutiveFailures += 1;
         state.lastError = error instanceof Error ? error.message : String(error);
-        state.lastCheckedAt = new Date().toISOString();
+        state.lastCheckedAt = this.nowDate().toISOString();
     }
     snapshot(providerName) {
         const names = providerName ? [providerName] : [...this.states.keys()];
@@ -35,16 +42,39 @@ class ProviderHealthMonitor {
     isHealthy(providerName) {
         return this.snapshotOne(providerName).healthy;
     }
+    isUnknown(providerName) {
+        return this.snapshotOne(providerName).status === 'unknown';
+    }
+    isStale(state) {
+        const ttl = this.config.observationTtlMs;
+        if (ttl === undefined || !state.lastCheckedAt)
+            return false;
+        return this.nowDate().getTime() - Date.parse(state.lastCheckedAt) > ttl;
+    }
     snapshotOne(providerName) {
-        const state = this.state(providerName);
+        const recorded = this.state(providerName);
+        const stale = this.isStale(recorded);
+        const state = stale
+            ? { ...freshState(), lastError: recorded.lastError, lastCheckedAt: recorded.lastCheckedAt }
+            : recorded;
         const failureThreshold = this.config.failureThreshold || 3;
         const failurePenalty = Math.min(60, state.consecutiveFailures * 20);
         const latencyPenalty = Math.min(30, state.avgLatencyMs / 1000);
         const score = Math.max(0, 100 - failurePenalty - latencyPenalty);
         const minScore = this.config.minScore ?? 20;
+        const healthy = state.consecutiveFailures < failureThreshold && score >= minScore;
+        const seen = recorded.successes + recorded.failures > 0;
         return {
             providerName,
-            healthy: state.consecutiveFailures < failureThreshold && score >= minScore,
+            healthy,
+            status: stale || !seen
+                ? 'unknown'
+                : !healthy
+                    ? 'unhealthy'
+                    : state.consecutiveFailures > 0 || score < 70
+                        ? 'degraded'
+                        : 'healthy',
+            stale,
             successes: state.successes,
             failures: state.failures,
             consecutiveFailures: state.consecutiveFailures,
@@ -57,15 +87,13 @@ class ProviderHealthMonitor {
     state(providerName) {
         let state = this.states.get(providerName);
         if (!state) {
-            state = {
-                successes: 0,
-                failures: 0,
-                consecutiveFailures: 0,
-                avgLatencyMs: 0,
-            };
+            state = freshState();
             this.states.set(providerName, state);
         }
         return state;
     }
 }
 exports.ProviderHealthMonitor = ProviderHealthMonitor;
+function freshState() {
+    return { successes: 0, failures: 0, consecutiveFailures: 0, avgLatencyMs: 0 };
+}

package/dist-cjs/ops/index.d.ts

@@ -6,7 +6,7 @@
  */
 export { AuditLogger } from './audit-logger.js';
 export { type FamilyCallDescriptor, type FamilyRuntime, FamilyTelemetry } from './family-telemetry.js';
-export { type HealthConfig, ProviderHealthMonitor, type ProviderHealthSnapshot } from './health.js';
+export { type HealthConfig, ProviderHealthMonitor, type ProviderHealthSnapshot, type ProviderHealthStatus, } from './health.js';
 export { InMemoryMetrics, type MetricsConfig, MetricsCollector, type MetricsSink, type OpenTelemetryLikeMeter, OpenTelemetryMetricsSink, } from './metrics.js';
 export { type OpenTelemetryLikeSpan, type OpenTelemetryLikeTracer, OpenTelemetryTraceExporter, } from './otel-tracing.js';
 export { NexusRateLimitError, type RateLimitedRequest, RateLimiter } from './rate-limiter.js';

package/dist-cjs/ops/rate-limit-adapters.d.ts

@@ -1,3 +1,5 @@
+import { gcraDecide } from './rate-limiter.js';
+export { gcraDecide };
 /** A rate-limit window after counting one call. */
 export interface RateLimitHit {
     /** Calls counted in the current window, including this one. */
@@ -5,6 +7,13 @@ export interface RateLimitHit {
     /** Epoch milliseconds when the window resets. */
     resetAt: number;
 }
+/** The verdict on one call under GCRA. */
+export interface RateLimitDecision {
+    /** Whether the call may go. */
+    allowed: boolean;
+    /** Epoch milliseconds from which a refused call would be allowed. */
+    retryAt: number;
+}
 /**
  * Where rate-limit counters live.
  *
@@ -16,14 +25,22 @@ export interface RateLimitStore {
     hit(key: string, windowMs: number): Promise<RateLimitHit> | RateLimitHit;
     /** Resets a key's window. */
     reset?(key: string): Promise<void> | void;
+    /**
+     * Decides one call under GCRA: one call per `emissionMs` on average, with up to `burst` at once,
+     * atomically. Needed for `algorithm: 'gcra'`; both bundled stores have it.
+     */
+    gcra?(key: string, emissionMs: number, burst: number): Promise<RateLimitDecision> | RateLimitDecision;
 }
 /** Process-local counters. The default, and equivalent to the limiter's built-in behavior. */
 export declare class MemoryRateLimitStore implements RateLimitStore {
     private readonly now;
     private readonly buckets;
+    private readonly arrivals;
     constructor(now?: () => number);
     /** Counts one call, starting a new window when the last has ended. */
     hit(key: string, windowMs: number): RateLimitHit;
+    /** Decides one call under GCRA. */
+    gcra(key: string, emissionMs: number, burst: number): RateLimitDecision;
     /** Resets a key's window. */
     reset(key: string): void;
     /** Resets every window. */
@@ -65,11 +82,17 @@ export interface RedisRateLimitStoreOptions {
  */
 export declare class RedisRateLimitStore implements RateLimitStore {
     private readonly client;
+    private readonly options;
     private readonly prefix;
     private readonly useEval;
     constructor(client: RedisRateLimitLikeClient, options?: RedisRateLimitStoreOptions);
     /** Counts one call, in one atomic step when the client has `eval`. */
     hit(key: string, windowMs: number): Promise<RateLimitHit>;
+    /**
+     * Decides one call under GCRA, atomically, on Redis's own clock. Needs a client with `eval`: the
+     * read and the write cannot be split without letting two workers both take the last slot.
+     */
+    gcra(key: string, emissionMs: number, burst: number): Promise<RateLimitDecision>;
     /** Resets a key's window. Does nothing when the client has no `del`. */
     reset(key: string): Promise<void>;
 }

package/dist-cjs/ops/rate-limit-adapters.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RedisRateLimitStore = exports.MemoryRateLimitStore = void 0;
+exports.RedisRateLimitStore = exports.MemoryRateLimitStore = exports.gcraDecide = void 0;
+const rate_limiter_js_1 = require("./rate-limiter.js");
+Object.defineProperty(exports, "gcraDecide", { enumerable: true, get: function () { return rate_limiter_js_1.gcraDecide; } });
 class MemoryRateLimitStore {
     now;
     buckets = new Map();
+    arrivals = new Map();
     constructor(now = () => Date.now()) {
         this.now = now;
     }
@@ -18,11 +21,19 @@ class MemoryRateLimitStore {
         bucket.count += 1;
         return bucket;
     }
+    gcra(key, emissionMs, burst) {
+        const decided = (0, rate_limiter_js_1.gcraDecide)(this.arrivals.get(key), this.now(), emissionMs, burst);
+        if (decided.allowed)
+            this.arrivals.set(key, decided.tat);
+        return { allowed: decided.allowed, retryAt: decided.retryAt };
+    }
     reset(key) {
         this.buckets.delete(key);
+        this.arrivals.delete(key);
     }
     clear() {
         this.buckets.clear();
+        this.arrivals.clear();
     }
 }
 exports.MemoryRateLimitStore = MemoryRateLimitStore;
@@ -39,12 +50,27 @@ if ttl < 0 then
 end
 return {count, ttl}
 `;
+const GCRA_SCRIPT = `
+local time = redis.call('TIME')
+local now = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
+local emission = tonumber(ARGV[1])
+local burst = tonumber(ARGV[2])
+local tat = tonumber(redis.call('GET', KEYS[1]) or now)
+if tat < now then tat = now end
+local next = tat + emission
+local allowAt = next - burst * emission
+if allowAt > now then return {0, allowAt - now} end
+redis.call('SET', KEYS[1], next, 'PX', math.max(1, math.ceil(next - now)))
+return {1, 0}
+`;
 class RedisRateLimitStore {
     client;
+    options;
     prefix;
     useEval;
     constructor(client, options = {}) {
         this.client = client;
+        this.options = options;
         this.prefix = options.prefix ?? 'nexus-ai-pro:ratelimit:';
         this.useEval = options.useEval !== false && typeof client.eval === 'function';
     }
@@ -68,6 +94,14 @@ class RedisRateLimitStore {
         }
         return { count, resetAt: Date.now() + ttl };
     }
+    async gcra(key, emissionMs, burst) {
+        if (!this.client.eval || this.options.useEval === false) {
+            throw new Error('GCRA rate limiting through Redis needs a client with eval');
+        }
+        const raw = (await this.client.eval(GCRA_SCRIPT, 1, `${this.prefix}gcra:${key}`, String(emissionMs), String(burst)));
+        const allowed = Number(raw?.[0]) === 1;
+        return { allowed, retryAt: Date.now() + Math.max(0, Number(raw?.[1] ?? 0)) };
+    }
     async reset(key) {
         await this.client.del?.(this.prefix + key);
     }

package/dist-cjs/ops/rate-limiter.d.ts

@@ -10,6 +10,8 @@ export interface RateLimitedRequest {
     model?: string;
     /** Caller, for per-user limits. */
     userId?: string;
+    /** Tenant, for per-tenant limits. */
+    tenantId?: string;
 }
 /** Raised when a caller exceeds its rate limit. */
 export declare class NexusRateLimitError extends Error {
@@ -26,11 +28,12 @@ export declare class NexusRateLimitError extends Error {
     get retryAfterSeconds(): number | undefined;
 }
 /**
- * Fixed-window rate limiting, per user, per model, or globally, in memory or through a shared
- * store.
+ * Rate limiting per user, per model, or globally, in memory or through a shared store, by fixed
+ * windows or by GCRA.
  */
 export declare class RateLimiter {
     private buckets;
+    private arrivals;
     /**
      * Counts one call against a distributed store.
      *
@@ -43,3 +46,12 @@ export declare class RateLimiter {
     check(request: RateLimitedRequest, config?: RateLimitConfig): void;
     private getKey;
 }
+/**
+ * GCRA on one key's theoretical arrival time: the time the key would be idle again at the allowed
+ * rate. A call is allowed when that time, after counting it, is no more than `burst` intervals ahead.
+ */
+export declare function gcraDecide(tat: number | undefined, now: number, emissionMs: number, burst: number): {
+    allowed: boolean;
+    retryAt: number;
+    tat: number;
+};

package/dist-cjs/ops/rate-limiter.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RateLimiter = exports.NexusRateLimitError = void 0;
+exports.gcraDecide = gcraDecide;
 class NexusRateLimitError extends Error {
     key;
     resetAt;
@@ -19,6 +20,7 @@ class NexusRateLimitError extends Error {
 exports.NexusRateLimitError = NexusRateLimitError;
 class RateLimiter {
     buckets = new Map();
+    arrivals = new Map();
     async checkAsync(request, config) {
         if (!config?.enabled)
             return;
@@ -28,6 +30,14 @@ class RateLimiter {
             return;
         }
         const key = this.getKey(request, config);
+        if (config.algorithm === 'gcra') {
+            if (!store.gcra)
+                throw new Error('This rate-limit store cannot decide GCRA; give it gcra(), or use fixed windows');
+            const decided = await store.gcra(key, emissionOf(config), burstOf(config));
+            if (!decided.allowed)
+                throw new NexusRateLimitError(key, decided.retryAt);
+            return;
+        }
         const hit = await store.hit(key, config.windowMs);
         if (hit.count > config.maxRequests) {
             throw new NexusRateLimitError(key, hit.resetAt);
@@ -38,6 +48,13 @@ class RateLimiter {
             return;
         const key = this.getKey(request, config);
         const now = Date.now();
+        if (config.algorithm === 'gcra') {
+            const decided = gcraDecide(this.arrivals.get(key), now, emissionOf(config), burstOf(config));
+            if (!decided.allowed)
+                throw new NexusRateLimitError(key, decided.retryAt);
+            this.arrivals.set(key, decided.tat);
+            return;
+        }
         const bucket = this.buckets.get(key);
         if (!bucket || bucket.resetAt <= now) {
             this.buckets.set(key, { count: 1, resetAt: now + config.windowMs });
@@ -51,9 +68,24 @@ class RateLimiter {
     getKey(request, config) {
         if (config.key === 'model')
             return `model:${request.model}`;
+        if (config.key === 'tenantId')
+            return `tenant:${request.tenantId || 'none'}`;
         if (config.key === 'global')
             return 'global';
         return `user:${request.userId || 'anonymous'}`;
     }
 }
 exports.RateLimiter = RateLimiter;
+function emissionOf(config) {
+    return config.windowMs / Math.max(1, config.maxRequests);
+}
+function burstOf(config) {
+    return Math.max(1, config.burst ?? config.maxRequests);
+}
+function gcraDecide(tat, now, emissionMs, burst) {
+    const next = Math.max(tat ?? now, now) + emissionMs;
+    const allowAt = next - burst * emissionMs;
+    if (allowAt > now)
+        return { allowed: false, retryAt: allowAt, tat: tat ?? now };
+    return { allowed: true, retryAt: now, tat: next };
+}

package/dist-cjs/postgres/circuits.d.ts

@@ -1,5 +1,7 @@
-import type { CircuitStateStore, SharedCircuitState } from '../ops/circuit-breaker.js';
+import type { CircuitObservation, CircuitStateStore, CircuitWindow, SharedCircuitState } from '../ops/circuit-breaker.js';
+import type { MigrationResult, SchemaMigration } from '../utils/schema-migrations.js';
 import { type PostgresLikeClient } from './client.js';
+import type { PostgresMigrateOptions } from './migrations.js';
 /** Options for the Postgres circuit store. */
 export interface PostgresCircuitStateStoreOptions {
     /** Table name, optionally schema-qualified. Defaults to `nexus_circuits`. */
@@ -7,8 +9,13 @@ export interface PostgresCircuitStateStoreOptions {
     /** Clock for probe leases. Defaults to `Date.now`, the same clock the breaker uses. */
     now?: () => number;
 }
-/** The schema, as statements. */
+/** The schema, as statements: every migration's, in order. */
 export declare function circuitStoreMigration(options?: Pick<PostgresCircuitStateStoreOptions, 'table'>): string[];
+/**
+ * The versioned schema, which `migrate()` and `nexus db migrate` apply. Version 1 is the 2.0 table;
+ * version 2 adds the shared failure window, so a breaker counts every worker's calls.
+ */
+export declare function circuitStoreMigrations(options?: Pick<PostgresCircuitStateStoreOptions, 'table'>): SchemaMigration[];
 /**
  * Shared circuit state in Postgres.
  *
@@ -20,10 +27,14 @@ export declare class PostgresCircuitStateStore implements CircuitStateStore {
     private readonly client;
     private readonly options;
     private readonly table;
+    private readonly windowTable;
     private readonly now;
     constructor(client: PostgresLikeClient, options?: PostgresCircuitStateStoreOptions);
-    /** Creates the table if it does not exist. Never runs implicitly. */
-    migrate(): Promise<void>;
+    /**
+     * Applies this store's pending migrations, recorded in `nexus_schema_migrations`, under a lock.
+     * Never runs implicitly. Safe on a database an older release created: what exists is kept.
+     */
+    migrate(options?: PostgresMigrateOptions): Promise<MigrationResult>;
     /** Every provider's shared circuit state. */
     read(): Promise<SharedCircuitState[]>;
     /**
@@ -35,4 +46,10 @@ export declare class PostgresCircuitStateStore implements CircuitStateStore {
      * claimant, including when it already holds the claim.
      */
     claimProbe(providerName: string, owner: string, ttlMs: number): Promise<boolean>;
+    /**
+     * Adds one worker's calls to a provider's shared window, then sums it. The add, the trim of buckets
+     * that rolled out, and the streak update are one statement, so two workers reporting at once both
+     * count. Needs version 2 of the schema.
+     */
+    observe(providerName: string, observation: CircuitObservation): Promise<CircuitWindow>;
 }