nexus-ai-pro 2.0.0 → 2.2.0

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

@@ -1,6 +1,6 @@
 export { AuditLogger } from './audit-logger.js';
 export { FamilyTelemetry } from './family-telemetry.js';
-export { ProviderHealthMonitor } from './health.js';
+export { ProviderHealthMonitor, } from './health.js';
 export { InMemoryMetrics, MetricsCollector, OpenTelemetryMetricsSink, } from './metrics.js';
 export { OpenTelemetryTraceExporter, } from './otel-tracing.js';
 export { NexusRateLimitError, RateLimiter } from './rate-limiter.js';

package/dist/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/ops/rate-limit-adapters.js

@@ -1,6 +1,9 @@
+import { gcraDecide } from './rate-limiter.js';
+export { gcraDecide };
 export class MemoryRateLimitStore {
     now;
     buckets = new Map();
+    arrivals = new Map();
     constructor(now = () => Date.now()) {
         this.now = now;
     }
@@ -15,11 +18,19 @@ export class MemoryRateLimitStore {
         bucket.count += 1;
         return bucket;
     }
+    gcra(key, emissionMs, burst) {
+        const decided = 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();
     }
 }
 const HIT_SCRIPT = `
@@ -35,12 +46,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}
+`;
 export 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';
     }
@@ -64,6 +90,14 @@ export 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/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/ops/rate-limiter.js

@@ -15,6 +15,7 @@ export class NexusRateLimitError extends Error {
 }
 export class RateLimiter {
     buckets = new Map();
+    arrivals = new Map();
     async checkAsync(request, config) {
         if (!config?.enabled)
             return;
@@ -24,6 +25,14 @@ export 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);
@@ -34,6 +43,13 @@ export 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 });
@@ -47,8 +63,23 @@ 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'}`;
     }
 }
+function emissionOf(config) {
+    return config.windowMs / Math.max(1, config.maxRequests);
+}
+function burstOf(config) {
+    return Math.max(1, config.burst ?? config.maxRequests);
+}
+export 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/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;