nexus-ai-pro 2.1.0 → 2.2.0

package/dist/ops/circuit-store.js

@@ -2,9 +2,37 @@ export class MemoryCircuitStateStore {
     now;
     states = new Map();
     probes = new Map();
+    windows = new Map();
     constructor(now = () => Date.now()) {
         this.now = now;
     }
+    observe(providerName, observation) {
+        let window = this.windows.get(providerName);
+        if (!window) {
+            window = { buckets: new Map(), streak: 0 };
+            this.windows.set(providerName, window);
+        }
+        for (const bucket of observation.buckets) {
+            const stored = window.buckets.get(bucket.at) ?? { calls: 0, failures: 0 };
+            stored.calls += bucket.calls;
+            stored.failures += bucket.failures;
+            window.buckets.set(bucket.at, stored);
+        }
+        window.streak = observation.succeeded ? observation.trailingFailures : window.streak + observation.trailingFailures;
+        const keepAfter = observation.now - observation.windowMs - observation.bucketMs;
+        const since = observation.since ?? Number.NEGATIVE_INFINITY;
+        let calls = 0;
+        let failures = 0;
+        for (const [at, bucket] of window.buckets) {
+            if (at <= keepAfter)
+                window.buckets.delete(at);
+            else if (at >= since) {
+                calls += bucket.calls;
+                failures += bucket.failures;
+            }
+        }
+        return { calls, failures, consecutiveFailures: window.streak };
+    }
     read() {
         return [...this.states.values()].map((state) => ({ ...state }));
     }
@@ -34,14 +62,54 @@ redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
 redis.call('DEL', KEYS[2])
 return 1
 `;
+const OBSERVE_SCRIPT = `
+local key = KEYS[1]
+for i = 6, #ARGV, 3 do
+  redis.call('HINCRBY', key, 'c:' .. ARGV[i], ARGV[i + 1])
+  redis.call('HINCRBY', key, 'f:' .. ARGV[i], ARGV[i + 2])
+end
+local streak
+if ARGV[1] == '1' then
+  redis.call('HSET', key, 'streak', ARGV[2])
+  streak = tonumber(ARGV[2])
+else
+  streak = tonumber(redis.call('HINCRBY', key, 'streak', ARGV[2]))
+end
+local keepAfter = tonumber(ARGV[3])
+local since = tonumber(ARGV[4])
+local calls, failures = 0, 0
+local fields = redis.call('HGETALL', key)
+for i = 1, #fields, 2 do
+  local name = fields[i]
+  local kind = string.sub(name, 1, 2)
+  if kind == 'c:' or kind == 'f:' then
+    local at = tonumber(string.sub(name, 3))
+    if at <= keepAfter then
+      redis.call('HDEL', key, name)
+    elseif at >= since then
+      if kind == 'c:' then calls = calls + tonumber(fields[i + 1]) else failures = failures + tonumber(fields[i + 1]) end
+    end
+  end
+end
+redis.call('PEXPIRE', key, ARGV[5])
+return { calls, failures, streak }
+`;
 export class RedisCircuitStateStore {
     client;
     prefix;
     useEval;
+    observe;
     constructor(client, options = {}) {
         this.client = client;
         this.prefix = options.prefix ?? 'nexus-ai-pro:circuits:';
         this.useEval = options.useEval !== false && typeof client.eval === 'function';
+        if (this.useEval)
+            this.observe = (providerName, observation) => this.observeWithEval(providerName, observation);
+    }
+    async observeWithEval(providerName, observation) {
+        const reply = (await this.client.eval(OBSERVE_SCRIPT, 1, `${this.prefix}window:${providerName}`, observation.succeeded ? '1' : '0', String(observation.trailingFailures), String(observation.now - observation.windowMs - observation.bucketMs), String(observation.since ?? -1), String(observation.windowMs * 2 + observation.bucketMs), ...observation.buckets.flatMap((bucket) => [String(bucket.at), String(bucket.calls), String(bucket.failures)])));
+        const [calls, failures, streak] = (reply ?? []).map(Number);
+        return { calls: calls ?? 0, failures: failures ?? 0, consecutiveFailures: streak ?? 0 };
     }
     async read() {
         const all = (await this.client.hgetall(this.statesKey())) ?? {};

package/dist/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/ops/circuit-sync.js

@@ -4,6 +4,7 @@ export class CircuitCoordinator {
     syncing;
     lastSyncAt = Number.NEGATIVE_INFINITY;
     reachable = true;
+    unreported = new Map();
     constructor(host) {
         this.host = host;
     }
@@ -26,6 +27,8 @@ export 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;
@@ -51,6 +54,29 @@ export 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({
@@ -72,6 +98,23 @@ export 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');
             }
@@ -81,6 +124,46 @@ export 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)
@@ -120,3 +203,6 @@ export class CircuitCoordinator {
         }
     }
 }
+export function bucketWidth(windowMs) {
+    return Math.max(1, Math.floor(windowMs / 12));
+}

package/dist/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 {

package/dist/ops/rate-limiter.js

@@ -63,6 +63,8 @@ export 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'}`;

package/dist/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>;
 }

package/dist/postgres/circuits.js

@@ -1,28 +1,58 @@
-import { fromJson, quoteTable, runStatements } from './client.js';
+import { fromJson, quoteTable } from './client.js';
 export function circuitStoreMigration(options = {}) {
+    return circuitStoreMigrations(options).flatMap((migration) => [...migration.statements]);
+}
+export function circuitStoreMigrations(options = {}) {
+    const name = options.table ?? 'nexus_circuits';
+    const component = `circuits:${name}`;
     return [
-        `CREATE TABLE IF NOT EXISTS ${quoteTable(options.table ?? 'nexus_circuits')} (
+        {
+            component,
+            version: 1,
+            name: 'create the circuits table',
+            statements: [
+                `CREATE TABLE IF NOT EXISTS ${quoteTable(name)} (
   provider text PRIMARY KEY,
   updated_at double precision,
   doc jsonb,
   probe_owner text,
   probe_expires_at double precision
 )`,
+            ],
+        },
+        {
+            component,
+            version: 2,
+            name: 'add the shared failure window',
+            statements: [
+                `ALTER TABLE ${quoteTable(name)} ADD COLUMN IF NOT EXISTS failure_streak integer NOT NULL DEFAULT 0`,
+                `CREATE TABLE IF NOT EXISTS ${quoteTable(`${name}_window`)} (
+  provider text NOT NULL,
+  bucket double precision NOT NULL,
+  calls integer NOT NULL,
+  failures integer NOT NULL,
+  PRIMARY KEY (provider, bucket)
+)`,
+            ],
+        },
     ];
 }
 export class PostgresCircuitStateStore {
     client;
     options;
     table;
+    windowTable;
     now;
     constructor(client, options = {}) {
         this.client = client;
         this.options = options;
         this.table = quoteTable(options.table ?? 'nexus_circuits');
+        this.windowTable = quoteTable(`${options.table ?? 'nexus_circuits'}_window`);
         this.now = options.now ?? (() => Date.now());
     }
-    async migrate() {
-        await runStatements(this.client, circuitStoreMigration(this.options));
+    async migrate(options = {}) {
+        const { applyPostgresMigrations } = await import('./migrations.js');
+        return applyPostgresMigrations(this.client, circuitStoreMigrations(this.options), options);
     }
     async read() {
         const { rows } = await this.client.query(`SELECT doc::text AS doc FROM ${this.table} WHERE doc IS NOT NULL`);
@@ -43,4 +73,35 @@ export class PostgresCircuitStateStore {
        RETURNING provider`, [providerName, owner, now, now + ttlMs]);
         return rows.length > 0;
     }
+    async observe(providerName, observation) {
+        const keepAfter = observation.now - observation.windowMs - observation.bucketMs;
+        const { rows } = await this.client.query(`WITH added AS (
+         INSERT INTO ${this.windowTable} AS stored (provider, bucket, calls, failures)
+         SELECT $1, item.at, item.calls, item.failures
+         FROM jsonb_to_recordset($2::jsonb) AS item(at double precision, calls integer, failures integer)
+         ON CONFLICT (provider, bucket) DO UPDATE
+           SET calls = stored.calls + EXCLUDED.calls, failures = stored.failures + EXCLUDED.failures
+       ), trimmed AS (
+         DELETE FROM ${this.windowTable} WHERE provider = $1 AND bucket <= $5::double precision
+       )
+       INSERT INTO ${this.table} AS circuit (provider, failure_streak) VALUES ($1, $3::integer)
+       ON CONFLICT (provider) DO UPDATE SET failure_streak = CASE WHEN $4::integer = 1
+         THEN EXCLUDED.failure_streak ELSE circuit.failure_streak + EXCLUDED.failure_streak END
+       RETURNING failure_streak`, [
+            providerName,
+            JSON.stringify(observation.buckets),
+            observation.trailingFailures,
+            observation.succeeded ? 1 : 0,
+            keepAfter,
+        ]);
+        const totals = await this.client.query(`SELECT coalesce(sum(calls), 0)::int AS calls, coalesce(sum(failures), 0)::int AS failures
+       FROM ${this.windowTable}
+       WHERE provider = $1 AND bucket > $2::double precision AND bucket >= $3::double precision`, [providerName, keepAfter, observation.since ?? -1]);
+        const sums = totals.rows[0];
+        return {
+            calls: Number(sums?.calls ?? 0),
+            failures: Number(sums?.failures ?? 0),
+            consecutiveFailures: Number(rows[0]?.failure_streak ?? 0),
+        };
+    }
 }

package/dist/postgres/client.d.ts

@@ -37,7 +37,5 @@ export declare function quoteDerived(table: string, suffix: string): string;
  * reading text everywhere is the only way to get the same value from every driver.
  */
 export declare function fromJson<T>(value: unknown): T;
-/** Runs migration statements one at a time, which every driver accepts. */
-export declare function runStatements(client: PostgresLikeClient, statements: readonly string[]): Promise<void>;
 /** Whether an error is Postgres refusing a duplicate key. */
 export declare function isUniqueViolation(error: unknown): boolean;

package/dist/postgres/client.js

@@ -22,10 +22,6 @@ export function quoteDerived(table, suffix) {
 export function fromJson(value) {
     return (typeof value === 'string' ? JSON.parse(value) : value);
 }
-export async function runStatements(client, statements) {
-    for (const statement of statements)
-        await client.query(statement);
-}
 export function isUniqueViolation(error) {
     return error?.code === '23505';
 }

package/dist/postgres/evaluate.d.ts

@@ -1,5 +1,7 @@
 import type { Dataset, DatasetStore, Experiment, ExperimentStore } from '../types/evaluate.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 evaluation stores. */
 export interface PostgresEvaluationStoreOptions {
     /** Datasets table. Defaults to `nexus_datasets`. */
@@ -7,6 +9,10 @@ export interface PostgresEvaluationStoreOptions {
     /** Experiments table. Defaults to `nexus_experiments`. */
     experimentsTable?: string;
 }
+/**
+ * The versioned schema, which `migrate()` and `nexus db migrate` apply. Version 1 is the 2.0 schema.
+ */
+export declare function evaluationStoreMigrations(options?: PostgresEvaluationStoreOptions): SchemaMigration[];
 /** The schema for both tables, as statements. */
 export declare function evaluationStoreMigration(options?: PostgresEvaluationStoreOptions): string[];
 /**
@@ -20,8 +26,11 @@ export declare class PostgresDatasetStore implements DatasetStore {
     private readonly options;
     private readonly table;
     constructor(client: PostgresLikeClient, options?: PostgresEvaluationStoreOptions);
-    /** Creates both evaluation tables if they do 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>;
     /** Stores a dataset version, replacing one with the same name and version. */
     save(dataset: Dataset): Promise<void>;
     /** Returns a version, or the newest when none is given. */
@@ -38,8 +47,11 @@ export declare class PostgresExperimentStore implements ExperimentStore {
     private readonly options;
     private readonly table;
     constructor(client: PostgresLikeClient, options?: PostgresEvaluationStoreOptions);
-    /** Creates both evaluation tables if they do 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>;
     /** Stores an experiment, replacing one with the same id. */
     save(experiment: Experiment): Promise<void>;
     /** Reads an experiment by id. */

package/dist/postgres/evaluate.js

@@ -1,4 +1,14 @@
-import { fromJson, quoteDerived, quoteTable, runStatements } from './client.js';
+import { fromJson, quoteDerived, quoteTable } from './client.js';
+export function evaluationStoreMigrations(options = {}) {
+    return [
+        {
+            component: `evaluation:${options.datasetsTable ?? 'nexus_datasets'},${options.experimentsTable ?? 'nexus_experiments'}`,
+            version: 1,
+            name: 'create the dataset and experiment tables',
+            statements: evaluationStoreMigration(options),
+        },
+    ];
+}
 export function evaluationStoreMigration(options = {}) {
     const datasetsName = options.datasetsTable ?? 'nexus_datasets';
     const experimentsName = options.experimentsTable ?? 'nexus_experiments';
@@ -33,8 +43,9 @@ export class PostgresDatasetStore {
         this.options = options;
         this.table = quoteTable(options.datasetsTable ?? 'nexus_datasets');
     }
-    async migrate() {
-        await runStatements(this.client, evaluationStoreMigration(this.options));
+    async migrate(options = {}) {
+        const { applyPostgresMigrations } = await import('./migrations.js');
+        return applyPostgresMigrations(this.client, evaluationStoreMigrations(this.options), options);
     }
     async save(dataset) {
         await this.client.query(`INSERT INTO ${this.table} (name, version, created_at, doc) VALUES ($1, $2, $3, $4::jsonb)
@@ -67,8 +78,9 @@ export class PostgresExperimentStore {
         this.options = options;
         this.table = quoteTable(options.experimentsTable ?? 'nexus_experiments');
     }
-    async migrate() {
-        await runStatements(this.client, evaluationStoreMigration(this.options));
+    async migrate(options = {}) {
+        const { applyPostgresMigrations } = await import('./migrations.js');
+        return applyPostgresMigrations(this.client, evaluationStoreMigrations(this.options), options);
     }
     async save(experiment) {
         await this.client.query(`INSERT INTO ${this.table} (id, name, dataset_name, dataset_version, started_at, doc)

package/dist/postgres/index.d.ts

@@ -1,14 +1,18 @@
-export { circuitStoreMigration, PostgresCircuitStateStore, type PostgresCircuitStateStoreOptions, } from './circuits.js';
+import { type SchemaMigration } from '../utils/schema-migrations.js';
+export { type AppliedMigration, type MigrationResult, type MigrationStatus, migrationChecksum, type SchemaMigration, SchemaMigrationError, } from '../utils/schema-migrations.js';
+export { circuitStoreMigration, circuitStoreMigrations, PostgresCircuitStateStore, type PostgresCircuitStateStoreOptions, } from './circuits.js';
 export { fromPostgresJs, type PostgresJsLike, type PostgresLikeClient } from './client.js';
-export { evaluationStoreMigration, PostgresDatasetStore, type PostgresEvaluationStoreOptions, PostgresExperimentStore, } from './evaluate.js';
-export { operationStoreMigration, PostgresOperationStore, type PostgresOperationStoreOptions } from './operations.js';
-export { PostgresPromptStore, type PostgresPromptStoreOptions, promptStoreMigration } from './prompts.js';
-export { PostgresStore, type PostgresStoreOptions, storeMigration } from './store.js';
-export { PostgresTraceStore, type PostgresTraceStoreOptions, traceStoreMigration } from './traces.js';
-export { PostgresVectorStore, type PostgresVectorStoreOptions, vectorStoreMigration } from './vectors.js';
+export { evaluationStoreMigration, evaluationStoreMigrations, PostgresDatasetStore, type PostgresEvaluationStoreOptions, PostgresExperimentStore, } from './evaluate.js';
+export { applyPostgresMigrations, type PostgresMigrateOptions, postgresMigrationStatus, } from './migrations.js';
+export { operationStoreMigration, operationStoreMigrations, PostgresOperationStore, type PostgresOperationStoreOptions, } from './operations.js';
+export { PostgresPromptStore, type PostgresPromptStoreOptions, promptStoreMigration, promptStoreMigrations, } from './prompts.js';
+export { PostgresRollupStore, type PostgresRollupStoreOptions, rollupStoreMigration, rollupStoreMigrations, } from './rollups.js';
+export { PostgresStore, type PostgresStoreOptions, storeMigration, storeMigrations } from './store.js';
+export { PostgresTraceStore, type PostgresTraceStoreOptions, traceStoreMigration, traceStoreMigrations, } from './traces.js';
+export { PostgresVectorStore, type PostgresVectorStoreOptions, vectorStoreMigration, vectorStoreMigrations, } from './vectors.js';
 /** The Postgres adapters a migration can include. */
-export type PostgresAdapter = 'operations' | 'store' | 'traces' | 'evaluation' | 'circuits' | 'prompts' | 'vectors';
-/** Options for `postgresMigration()`. */
+export type PostgresAdapter = 'operations' | 'store' | 'traces' | 'evaluation' | 'circuits' | 'prompts' | 'rollups' | 'vectors';
+/** Options for `postgresMigrations()` and `postgresMigration()`. */
 export interface PostgresMigrationOptions {
     /**
      * Adapters to include. Defaults to every one but `vectors`, which needs pgvector and
@@ -18,10 +22,27 @@ export interface PostgresMigrationOptions {
     /** Enables pgvector for the long-term store, and sets the width of the `vectors` table. */
     vectorDimensions?: number;
 }
+/** Options for `postgresMigration()`. */
+export interface PostgresMigrationScriptOptions extends PostgresMigrationOptions {
+    /**
+     * Also creates `nexus_schema_migrations` and records every migration in the script as applied, so
+     * `nexus db status` agrees with a database built by the application's own tooling. Off by default.
+     */
+    record?: boolean;
+}
+/** Every adapter, in the order a migration applies them. */
+export declare const POSTGRES_ADAPTERS: readonly PostgresAdapter[];
+/**
+ * The versioned migrations of the chosen adapters on their default tables, for
+ * `applyPostgresMigrations()`, `postgresMigrationStatus()`, and `nexus db migrate`. A store on a
+ * custom table migrates through its own `migrate()`.
+ */
+export declare function postgresMigrations(options?: PostgresMigrationOptions): SchemaMigration[];
 /**
  * The schema for the chosen adapters, as one SQL script.
  *
  * For migration tooling the application already has — Flyway, Prisma, a plain `psql -f` — which is
- * usually where a schema change belongs. `nexus db sql` prints the same script.
+ * usually where a schema change belongs. Every statement is idempotent, so the script runs again
+ * safely after an upgrade. `nexus db sql` prints the same script.
  */
-export declare function postgresMigration(options?: PostgresMigrationOptions): string;
+export declare function postgresMigration(options?: PostgresMigrationScriptOptions): string;