nexus-ai-pro 2.1.0 → 2.2.0

package/dist/postgres/index.js

@@ -1,35 +1,69 @@
-import { circuitStoreMigration } from './circuits.js';
-import { evaluationStoreMigration } from './evaluate.js';
-import { operationStoreMigration } from './operations.js';
-import { promptStoreMigration } from './prompts.js';
-import { storeMigration } from './store.js';
-import { traceStoreMigration } from './traces.js';
-import { vectorStoreMigration } from './vectors.js';
-export { circuitStoreMigration, PostgresCircuitStateStore, } from './circuits.js';
+import { MIGRATIONS_TABLE, migrationChecksum, sqlLiteral } from '../utils/schema-migrations.js';
+import { circuitStoreMigrations } from './circuits.js';
+import { quoteTable } from './client.js';
+import { evaluationStoreMigrations } from './evaluate.js';
+import { migrationsTableStatements } from './migrations.js';
+import { operationStoreMigrations } from './operations.js';
+import { promptStoreMigrations } from './prompts.js';
+import { rollupStoreMigrations } from './rollups.js';
+import { storeMigrations } from './store.js';
+import { traceStoreMigrations } from './traces.js';
+import { vectorStoreMigrations } from './vectors.js';
+export { migrationChecksum, SchemaMigrationError, } from '../utils/schema-migrations.js';
+export { circuitStoreMigration, circuitStoreMigrations, PostgresCircuitStateStore, } from './circuits.js';
 export { fromPostgresJs } from './client.js';
-export { evaluationStoreMigration, PostgresDatasetStore, PostgresExperimentStore, } from './evaluate.js';
-export { operationStoreMigration, PostgresOperationStore } from './operations.js';
-export { PostgresPromptStore, promptStoreMigration } from './prompts.js';
-export { PostgresStore, storeMigration } from './store.js';
-export { PostgresTraceStore, traceStoreMigration } from './traces.js';
-export { PostgresVectorStore, vectorStoreMigration } from './vectors.js';
+export { evaluationStoreMigration, evaluationStoreMigrations, PostgresDatasetStore, PostgresExperimentStore, } from './evaluate.js';
+export { applyPostgresMigrations, postgresMigrationStatus, } from './migrations.js';
+export { operationStoreMigration, operationStoreMigrations, PostgresOperationStore, } from './operations.js';
+export { PostgresPromptStore, promptStoreMigration, promptStoreMigrations, } from './prompts.js';
+export { PostgresRollupStore, rollupStoreMigration, rollupStoreMigrations, } from './rollups.js';
+export { PostgresStore, storeMigration, storeMigrations } from './store.js';
+export { PostgresTraceStore, traceStoreMigration, traceStoreMigrations, } from './traces.js';
+export { PostgresVectorStore, vectorStoreMigration, vectorStoreMigrations, } from './vectors.js';
+export const POSTGRES_ADAPTERS = [
+    'operations',
+    'store',
+    'traces',
+    'evaluation',
+    'circuits',
+    'prompts',
+    'rollups',
+    'vectors',
+];
+export function postgresMigrations(options = {}) {
+    const adapters = new Set(options.adapters ?? POSTGRES_ADAPTERS.filter((adapter) => adapter !== 'vectors'));
+    const vectorDimensions = options.vectorDimensions;
+    const migrationsOf = {
+        operations: () => operationStoreMigrations(),
+        store: () => storeMigrations(vectorDimensions ? { vectorDimensions } : {}),
+        traces: () => traceStoreMigrations(),
+        evaluation: () => evaluationStoreMigrations(),
+        circuits: () => circuitStoreMigrations(),
+        prompts: () => promptStoreMigrations(),
+        rollups: () => rollupStoreMigrations(),
+        vectors: () => {
+            if (vectorDimensions === undefined)
+                throw new RangeError('The vectors adapter needs vectorDimensions');
+            return vectorStoreMigrations({ dimensions: vectorDimensions });
+        },
+    };
+    return POSTGRES_ADAPTERS.filter((adapter) => adapters.has(adapter)).flatMap((adapter) => migrationsOf[adapter]());
+}
 export function postgresMigration(options = {}) {
-    const adapters = new Set(options.adapters ?? ['operations', 'store', 'traces', 'evaluation', 'circuits', 'prompts']);
-    const statements = [
-        ...(adapters.has('operations') ? operationStoreMigration() : []),
-        ...(adapters.has('store')
-            ? storeMigration(options.vectorDimensions ? { vectorDimensions: options.vectorDimensions } : {})
-            : []),
-        ...(adapters.has('traces') ? traceStoreMigration() : []),
-        ...(adapters.has('evaluation') ? evaluationStoreMigration() : []),
-        ...(adapters.has('circuits') ? circuitStoreMigration() : []),
-        ...(adapters.has('prompts') ? promptStoreMigration() : []),
-        ...(adapters.has('vectors') ? vectorMigrationFor(options.vectorDimensions) : []),
-    ];
+    const migrations = postgresMigrations(options);
+    const statements = migrations.flatMap((migration) => [...migration.statements]);
+    if (options.record) {
+        statements.push(...migrationsTableStatements());
+        for (const migration of migrations) {
+            statements.push(`INSERT INTO ${quoteTable(MIGRATIONS_TABLE)} (component, version, name, checksum, applied_at) VALUES (${[
+                migration.component,
+                String(migration.version),
+                migration.name,
+                migrationChecksum(migration),
+            ]
+                .map((value, index) => (index === 1 ? value : sqlLiteral(value)))
+                .join(', ')}, to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')) ON CONFLICT (component, version) DO NOTHING`);
+        }
+    }
     return `${statements.join(';\n\n')};\n`;
 }
-function vectorMigrationFor(dimensions) {
-    if (dimensions === undefined)
-        throw new RangeError('The vectors adapter needs vectorDimensions');
-    return vectorStoreMigration({ dimensions });
-}

package/dist/postgres/migrations.d.ts

@@ -0,0 +1,60 @@
+import { type MigrationResult, type MigrationStatus, type SchemaMigration } from '../utils/schema-migrations.js';
+import { type PostgresLikeClient } from './client.js';
+export { type AppliedMigration, type MigrationResult, type MigrationStatus, migrationChecksum, type SchemaMigration, SchemaMigrationError, } from '../utils/schema-migrations.js';
+/** Options for applying or inspecting Postgres migrations. */
+export interface PostgresMigrateOptions {
+    /** Plans without writing anything, not even the table that records migrations. */
+    dryRun?: boolean;
+    /** The table that records applied migrations, optionally schema-qualified. Defaults to `nexus_schema_migrations`. */
+    table?: string;
+    /**
+     * Runs one migration's statements, and the row recording it, in one transaction on one connection.
+     * Without it, statements run one at a time and the record is written last: every bundled statement
+     * is idempotent, so an interrupted migration runs again on the next call. Pass it for a pool, where
+     * `BEGIN` and `COMMIT` would otherwise reach different connections:
+     *
+     * ```ts
+     * transaction: async (run) => {
+     *   const connection = await pool.connect();
+     *   try {
+     *     await connection.query('BEGIN');
+     *     const result = await run(connection);
+     *     await connection.query('COMMIT');
+     *     return result;
+     *   } catch (error) {
+     *     await connection.query('ROLLBACK');
+     *     throw error;
+     *   } finally {
+     *     connection.release();
+     *   }
+     * }
+     * ```
+     *
+     * PGlite needs only `transaction: (run) => db.transaction(run)`.
+     */
+    transaction?: <T>(run: (client: PostgresLikeClient) => Promise<T>) => Promise<T>;
+    /**
+     * How long one migrator holds the lock before another may take it over, renewed before each
+     * migration. Defaults to 10 minutes, longer than any bundled migration takes.
+     */
+    lockTtlMs?: number;
+    /** How long to wait for another migrator to finish before giving up. Defaults to 2 minutes. */
+    lockTimeoutMs?: number;
+}
+/**
+ * Where a Postgres database stands against a list of migrations. Reads only: on a database that has
+ * never been migrated, everything is pending.
+ */
+export declare function postgresMigrationStatus(client: PostgresLikeClient, migrations: readonly SchemaMigration[], options?: Pick<PostgresMigrateOptions, 'table'>): Promise<MigrationStatus>;
+/**
+ * Applies the pending migrations in order, under a lock, recording each with a checksum.
+ *
+ * The lock is a row with a lease rather than a session advisory lock, so it holds through a
+ * connection pool and serverless drivers alike: a second migrator waits, and one that died is taken
+ * over once its lease lapses. A migration whose statements changed after it ran is refused before
+ * anything is written. Migrations a newer release recorded are left alone, so an older worker
+ * starting mid-rollout does nothing.
+ */
+export declare function applyPostgresMigrations(client: PostgresLikeClient, migrations: readonly SchemaMigration[], options?: PostgresMigrateOptions): Promise<MigrationResult>;
+/** The statements that create the migrations table and its lock, which `migrate()` runs first. */
+export declare function migrationsTableStatements(table?: string): string[];

package/dist/postgres/migrations.js

@@ -0,0 +1,121 @@
+import { assertUnchanged, delay, label, MIGRATIONS_TABLE, migrationChecksum, planMigrations, SchemaMigrationError, } from '../utils/schema-migrations.js';
+import { quoteTable } from './client.js';
+export { migrationChecksum, SchemaMigrationError, } from '../utils/schema-migrations.js';
+const LOCK_NAME = 'migrate';
+const DB_NOW = '(extract(epoch from clock_timestamp()) * 1000)';
+export async function postgresMigrationStatus(client, migrations, options = {}) {
+    return planMigrations(migrations, await readApplied(client, options.table ?? MIGRATIONS_TABLE));
+}
+export async function applyPostgresMigrations(client, migrations, options = {}) {
+    const tableName = options.table ?? MIGRATIONS_TABLE;
+    if (options.dryRun) {
+        const status = await postgresMigrationStatus(client, migrations, options);
+        assertUnchanged(status);
+        return { applied: status.pending, statements: status.pending.flatMap((m) => [...m.statements]), dryRun: true };
+    }
+    planMigrations(migrations, []);
+    await bootstrap(client, tableName);
+    const owner = `migrator-${globalThis.crypto.randomUUID()}`;
+    const lockTtlMs = options.lockTtlMs ?? 600_000;
+    await acquire(client, tableName, owner, lockTtlMs, options.lockTimeoutMs ?? 120_000);
+    try {
+        const status = planMigrations(migrations, await readApplied(client, tableName));
+        assertUnchanged(status);
+        const statements = [];
+        for (const migration of status.pending) {
+            if (!(await claim(client, tableName, owner, lockTtlMs))) {
+                throw new SchemaMigrationError('MIGRATION_LOCKED', `The migration lock lapsed before ${label(migration)}`);
+            }
+            const apply = async (connection) => {
+                for (const statement of migration.statements)
+                    await connection.query(statement);
+                await connection.query(`INSERT INTO ${quoteTable(tableName)} (component, version, name, checksum, applied_at)
+           VALUES ($1, $2, $3, $4, $5) ON CONFLICT (component, version) DO NOTHING`, [
+                    migration.component,
+                    migration.version,
+                    migration.name,
+                    migrationChecksum(migration),
+                    new Date().toISOString(),
+                ]);
+            };
+            if (options.transaction)
+                await options.transaction(apply);
+            else
+                await apply(client);
+            statements.push(...migration.statements);
+        }
+        return { applied: status.pending, statements, dryRun: false };
+    }
+    finally {
+        await client
+            .query(`DELETE FROM ${lockTable(tableName)} WHERE name = $1 AND owner = $2`, [LOCK_NAME, owner])
+            .catch(() => undefined);
+    }
+}
+export function migrationsTableStatements(table = MIGRATIONS_TABLE) {
+    return [
+        `CREATE TABLE IF NOT EXISTS ${quoteTable(table)} (
+  component text NOT NULL,
+  version integer NOT NULL,
+  name text NOT NULL,
+  checksum text NOT NULL,
+  applied_at text COLLATE "C" NOT NULL,
+  PRIMARY KEY (component, version)
+)`,
+        `CREATE TABLE IF NOT EXISTS ${lockTable(table)} (
+  name text PRIMARY KEY,
+  owner text NOT NULL,
+  expires_at double precision NOT NULL
+)`,
+    ];
+}
+async function bootstrap(client, table) {
+    for (const statement of migrationsTableStatements(table)) {
+        try {
+            await client.query(statement);
+        }
+        catch (error) {
+            const code = error?.code;
+            if (code !== '23505' && code !== '42P07')
+                throw error;
+        }
+    }
+}
+async function readApplied(client, table) {
+    const { rows: exists } = await client.query('SELECT to_regclass($1) IS NOT NULL AS present', [quoteTable(table)]);
+    if (!exists[0]?.present)
+        return [];
+    const { rows } = await client.query(`SELECT component, version, name, checksum, applied_at FROM ${quoteTable(table)} ORDER BY applied_at, component, version`);
+    return rows.map((row) => {
+        const value = row;
+        return {
+            component: String(value.component),
+            version: Number(value.version),
+            name: String(value.name),
+            checksum: String(value.checksum),
+            appliedAt: String(value.applied_at),
+        };
+    });
+}
+async function acquire(client, table, owner, ttlMs, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let wait = 50;
+    while (!(await claim(client, table, owner, ttlMs))) {
+        if (Date.now() >= deadline) {
+            throw new SchemaMigrationError('MIGRATION_LOCKED', `Another migrator held the lock for ${timeoutMs} ms. It is released when that migrator finishes, or when its lease lapses.`);
+        }
+        await delay(wait);
+        wait = Math.min(wait * 2, 1_000);
+    }
+}
+async function claim(client, table, owner, ttlMs) {
+    const lock = lockTable(table);
+    const { rows } = await client.query(`INSERT INTO ${lock} (name, owner, expires_at) VALUES ($1, $2, ${DB_NOW} + $3::double precision)
+     ON CONFLICT (name) DO UPDATE SET owner = EXCLUDED.owner, expires_at = EXCLUDED.expires_at
+     WHERE ${lock}.owner = EXCLUDED.owner OR ${lock}.expires_at < ${DB_NOW}
+     RETURNING owner`, [LOCK_NAME, owner, ttlMs]);
+    return rows.length > 0;
+}
+function lockTable(table) {
+    return quoteTable(`${table}_lock`);
+}

package/dist/postgres/operations.d.ts

@@ -1,12 +1,20 @@
 import type { OperationRecord, OperationStore, OperationStoreFilter, OperationStoreStats } from '../types/operations.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 operation store. */
 export interface PostgresOperationStoreOptions {
     /** Table name, optionally schema-qualified. Defaults to `nexus_operations`. */
     table?: string;
 }
-/** The schema, as statements. Applied by `migrate()`, `nexus db sql`, or the application's own tooling. */
+/** The schema, as statements: every migration's, in order. For `nexus db sql` or the application's own tooling. */
 export declare function operationStoreMigration(options?: PostgresOperationStoreOptions): string[];
+/**
+ * The versioned schema, which `migrate()` and `nexus db migrate` apply. Version 1 is the 2.0 table;
+ * version 2 indexes queued work by age, so a claim reads the oldest few rows instead of sorting the
+ * queue; version 3 indexes queued work by tenant.
+ */
+export declare function operationStoreMigrations(options?: PostgresOperationStoreOptions): SchemaMigration[];
 /**
  * Operation records in Postgres.
  *
@@ -25,8 +33,11 @@ export declare class PostgresOperationStore<TResult = unknown> implements Operat
     private readonly options;
     private readonly table;
     constructor(client: PostgresLikeClient, options?: PostgresOperationStoreOptions);
-    /** Creates the table and indexes 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>;
     /**
      * Inserts a new record. Throws `OperationDuplicateError` when its idempotency key is already
      * claimed. Refuses records carrying raw bytes.

package/dist/postgres/operations.js

@@ -1,12 +1,37 @@
 import { OperationDuplicateError } from '../operations/errors.js';
 import { assertSerializableRecord } from '../operations/serialization.js';
 import { TERMINAL_OPERATION_STATUSES } from '../types/operations.js';
-import { fromJson, isUniqueViolation, quoteDerived, quoteTable, runStatements, } from './client.js';
+import { fromJson, isUniqueViolation, quoteDerived, quoteTable } from './client.js';
 const DEFAULT_TABLE = 'nexus_operations';
 const TERMINAL = TERMINAL_OPERATION_STATUSES.map((status) => `'${status}'`).join(', ');
 export function operationStoreMigration(options = {}) {
+    return operationStoreMigrations(options).flatMap((migration) => [...migration.statements]);
+}
+export function operationStoreMigrations(options = {}) {
     const name = options.table ?? DEFAULT_TABLE;
     const table = quoteTable(name);
+    const component = `operations:${name}`;
+    return [
+        { component, version: 1, name: 'create the operations table', statements: createStatements(name, table) },
+        {
+            component,
+            version: 2,
+            name: 'index queued work by age',
+            statements: [
+                `CREATE INDEX IF NOT EXISTS ${quoteDerived(name, 'queued')} ON ${table} (created_at, id) WHERE status = 'queued'`,
+            ],
+        },
+        {
+            component,
+            version: 3,
+            name: 'index queued work by tenant',
+            statements: [
+                `CREATE INDEX IF NOT EXISTS ${quoteDerived(name, 'tenant_queued')} ON ${table} ((doc ->> 'tenantId'), created_at, id) WHERE status = 'queued'`,
+            ],
+        },
+    ];
+}
+function createStatements(name, table) {
     return [
         `CREATE TABLE IF NOT EXISTS ${table} (
   id text PRIMARY KEY,
@@ -32,8 +57,9 @@ export class PostgresOperationStore {
         this.options = options;
         this.table = quoteTable(options.table ?? DEFAULT_TABLE);
     }
-    async migrate() {
-        await runStatements(this.client, operationStoreMigration(this.options));
+    async migrate(options = {}) {
+        const { applyPostgresMigrations } = await import('./migrations.js');
+        return applyPostgresMigrations(this.client, operationStoreMigrations(this.options), options);
     }
     async create(record) {
         assertSerializableRecord(record);
@@ -95,29 +121,21 @@ export class PostgresOperationStore {
     }
     async listQueued(limit, filter) {
         const params = [new Date().toISOString(), limit];
-        let kind = '';
-        if (filter?.kindPrefix) {
-            params.push(filter.kindPrefix);
-            kind = ' AND substr(kind, 1, char_length($3)) = $3';
-        }
+        const narrowed = filterSql(filter, params);
         const { rows } = await this.client.query(`SELECT doc::text AS doc FROM ${this.table}
-       WHERE status = 'queued' AND (lease_expires_at IS NULL OR lease_expires_at <= $1)${kind}
+       WHERE status = 'queued' AND (lease_expires_at IS NULL OR lease_expires_at <= $1)${narrowed}
        ORDER BY created_at, id
        LIMIT $2`, params);
         return rows.map((row) => fromJson(row.doc));
     }
     async stats(now, filter) {
         const params = [now];
-        let kind = '';
-        if (filter?.kindPrefix) {
-            params.push(filter.kindPrefix);
-            kind = ' AND substr(kind, 1, char_length($2)) = $2';
-        }
+        const narrowed = filterSql(filter, params);
         const { rows } = await this.client.query(`SELECT status, count(*)::int AS count,
          min(created_at) FILTER (WHERE status = 'queued') AS oldest,
          count(*) FILTER (WHERE status = 'running' AND (lease_expires_at IS NULL OR lease_expires_at <= $1))::int AS lapsed
        FROM ${this.table}
-       WHERE status NOT IN (${TERMINAL})${kind}
+       WHERE status NOT IN (${TERMINAL})${narrowed}
        GROUP BY status`, params);
         return statsFromRows(rows);
     }
@@ -139,6 +157,18 @@ export class PostgresOperationStore {
         ];
     }
 }
+function filterSql(filter, params) {
+    let sql = '';
+    if (filter?.kindPrefix) {
+        params.push(filter.kindPrefix);
+        sql += ` AND substr(kind, 1, char_length($${params.length})) = $${params.length}`;
+    }
+    if (filter?.tenantId !== undefined) {
+        params.push(filter.tenantId);
+        sql += ` AND doc ->> 'tenantId' = $${params.length}`;
+    }
+    return sql;
+}
 function statsFromRows(rows) {
     const byStatus = {};
     let oldestQueuedAt;

package/dist/postgres/prompts.d.ts

@@ -1,10 +1,16 @@
 import type { PromptHistoryEntry, PromptLabel, PromptStore, PromptVersion } from '../types/prompts.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 prompt store. */
 export interface PostgresPromptStoreOptions {
     /** Table name prefix, optionally schema-qualified. Defaults to `nexus_prompt`, for `nexus_prompt_versions` and so on. */
     table?: string;
 }
+/**
+ * The versioned schema, which `migrate()` and `nexus db migrate` apply. Version 1 is the 2.0 schema.
+ */
+export declare function promptStoreMigrations(options?: PostgresPromptStoreOptions): SchemaMigration[];
 /** The schema for the prompt store, as statements. */
 export declare function promptStoreMigration(options?: PostgresPromptStoreOptions): string[];
 /**
@@ -20,8 +26,11 @@ export declare class PostgresPromptStore implements PromptStore {
     private readonly labels;
     private readonly history;
     constructor(client: PostgresLikeClient, options?: PostgresPromptStoreOptions);
-    /** Creates the prompt 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 version, unless one with the same content version exists. */
     saveVersion(version: PromptVersion): Promise<void>;
     /** Reads a version. */

package/dist/postgres/prompts.js

@@ -1,8 +1,18 @@
-import { fromJson, quoteDerived, quoteTable, runStatements } from './client.js';
+import { fromJson, quoteDerived, quoteTable } from './client.js';
 function tables(options) {
     const base = options.table ?? 'nexus_prompt';
     return { base, versions: `${base}_versions`, labels: `${base}_labels`, history: `${base}_history` };
 }
+export function promptStoreMigrations(options = {}) {
+    return [
+        {
+            component: `prompts:${tables(options).versions}`,
+            version: 1,
+            name: 'create the prompt tables',
+            statements: promptStoreMigration(options),
+        },
+    ];
+}
 export function promptStoreMigration(options = {}) {
     const names = tables(options);
     return [
@@ -44,8 +54,9 @@ export class PostgresPromptStore {
         this.labels = quoteTable(names.labels);
         this.history = quoteTable(names.history);
     }
-    async migrate() {
-        await runStatements(this.client, promptStoreMigration(this.options));
+    async migrate(options = {}) {
+        const { applyPostgresMigrations } = await import('./migrations.js');
+        return applyPostgresMigrations(this.client, promptStoreMigrations(this.options), options);
     }
     async saveVersion(version) {
         await this.client.query(`INSERT INTO ${this.versions} (name, version, created_at, doc) VALUES ($1, $2, $3, $4::jsonb) ON CONFLICT DO NOTHING`, [version.name, version.version, version.createdAt, JSON.stringify(version)]);

package/dist/postgres/rollups.d.ts

@@ -0,0 +1,35 @@
+import { type RollupKey, type RollupQuery, type RollupRow, type RollupStore, type RollupTotals } from '../tracing/rollups.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 rollup store. */
+export interface PostgresRollupStoreOptions {
+    /** Table name, optionally schema-qualified. Defaults to `nexus_rollups`. */
+    table?: string;
+}
+/** The schema, as statements: every migration's, in order. */
+export declare function rollupStoreMigration(options?: PostgresRollupStoreOptions): string[];
+/** The versioned schema, which `migrate()` and `nexus db migrate` apply. */
+export declare function rollupStoreMigrations(options?: PostgresRollupStoreOptions): SchemaMigration[];
+/**
+ * Rollup rows in Postgres, so a dashboard's totals live beside its traces and survive a restart.
+ *
+ * Adding to a row is one `INSERT … ON CONFLICT DO UPDATE` that sums every total, latency buckets
+ * included, so two workers finishing runs in the same hour both count. A query reads only the rows
+ * of its range: a month of one tenant is a few hundred rows, however many runs it held.
+ */
+export declare class PostgresRollupStore implements RollupStore {
+    private readonly client;
+    private readonly options;
+    private readonly table;
+    constructor(client: PostgresLikeClient, options?: PostgresRollupStoreOptions);
+    /**
+     * Applies this store's pending migrations, recorded in `nexus_schema_migrations`, under a lock.
+     * Never runs implicitly.
+     */
+    migrate(options?: PostgresMigrateOptions): Promise<MigrationResult>;
+    /** Adds totals to the row for `key`, creating it, in one statement. */
+    add(key: RollupKey, totals: RollupTotals): Promise<void>;
+    /** Rows matching a query, oldest hour first, filtered as the in-memory store filters them. */
+    query(query?: RollupQuery): Promise<RollupRow[]>;
+}

package/dist/postgres/rollups.js

@@ -0,0 +1,129 @@
+import { ROLLUP_LATENCY_BOUNDS_MS, } from '../tracing/rollups.js';
+import { quoteDerived, quoteTable } from './client.js';
+import { SqlParams } from './sql.js';
+const DEFAULT_TABLE = 'nexus_rollups';
+export function rollupStoreMigration(options = {}) {
+    return rollupStoreMigrations(options).flatMap((migration) => [...migration.statements]);
+}
+export function rollupStoreMigrations(options = {}) {
+    const name = options.table ?? DEFAULT_TABLE;
+    const table = quoteTable(name);
+    return [
+        {
+            component: `rollups:${name}`,
+            version: 1,
+            name: 'create the rollups table',
+            statements: [
+                `CREATE TABLE IF NOT EXISTS ${table} (
+  hour text COLLATE "C" NOT NULL,
+  kind text NOT NULL,
+  name text NOT NULL,
+  model text NOT NULL,
+  provider text NOT NULL,
+  tenant text NOT NULL,
+  runs bigint NOT NULL,
+  errors bigint NOT NULL,
+  cost double precision NOT NULL,
+  input_tokens bigint NOT NULL,
+  output_tokens bigint NOT NULL,
+  latency bigint[] NOT NULL,
+  PRIMARY KEY (hour, kind, name, model, provider, tenant)
+)`,
+                `CREATE INDEX IF NOT EXISTS ${quoteDerived(name, 'tenant_hour')} ON ${table} (tenant, hour)`,
+            ],
+        },
+    ];
+}
+export class PostgresRollupStore {
+    client;
+    options;
+    table;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.options = options;
+        this.table = quoteTable(options.table ?? DEFAULT_TABLE);
+    }
+    async migrate(options = {}) {
+        const { applyPostgresMigrations } = await import('./migrations.js');
+        return applyPostgresMigrations(this.client, rollupStoreMigrations(this.options), options);
+    }
+    async add(key, totals) {
+        const t = this.table;
+        await this.client.query(`INSERT INTO ${t} (hour, kind, name, model, provider, tenant, runs, errors, cost, input_tokens, output_tokens, latency)
+       VALUES ($1, $2, $3, $4, $5, $6, $7::bigint, $8::bigint, $9::double precision, $10::bigint, $11::bigint, $12::bigint[])
+       ON CONFLICT (hour, kind, name, model, provider, tenant) DO UPDATE SET
+         runs = ${t}.runs + EXCLUDED.runs,
+         errors = ${t}.errors + EXCLUDED.errors,
+         cost = ${t}.cost + EXCLUDED.cost,
+         input_tokens = ${t}.input_tokens + EXCLUDED.input_tokens,
+         output_tokens = ${t}.output_tokens + EXCLUDED.output_tokens,
+         latency = ARRAY(
+           SELECT coalesce(stored, 0) + coalesce(added, 0)
+           FROM unnest(${t}.latency, EXCLUDED.latency) WITH ORDINALITY AS bucket(stored, added, position)
+           ORDER BY position
+         )`, [
+            key.hour,
+            key.kind,
+            key.name,
+            key.model,
+            key.provider,
+            key.tenant,
+            totals.runs,
+            totals.errors,
+            totals.cost,
+            totals.inputTokens,
+            totals.outputTokens,
+            `{${bucketsOf(totals.latency).join(',')}}`,
+        ]);
+    }
+    async query(query = {}) {
+        const params = new SqlParams();
+        const where = [];
+        if (query.since)
+            where.push(`hour >= ${params.add(hourOf(query.since))}`);
+        if (query.until)
+            where.push(`hour <= ${params.add(query.until)}`);
+        if (query.kind !== undefined) {
+            const kinds = Array.isArray(query.kind) ? query.kind : [query.kind];
+            where.push(kinds.length ? `kind IN (${kinds.map((kind) => params.add(kind)).join(', ')})` : 'FALSE');
+        }
+        if (query.model !== undefined)
+            where.push(`model = ${params.add(query.model)}`);
+        if (query.provider !== undefined)
+            where.push(`provider = ${params.add(query.provider)}`);
+        if (query.tenant !== undefined)
+            where.push(`tenant = ${params.add(query.tenant)}`);
+        if (query.name !== undefined)
+            where.push(`name = ${params.add(query.name)}`);
+        const { rows } = await this.client.query(`SELECT hour, kind, name, model, provider, tenant, runs::text AS runs, errors::text AS errors, cost,
+         input_tokens::text AS input_tokens, output_tokens::text AS output_tokens, latency::text AS latency
+       FROM ${this.table}
+       ${where.length ? `WHERE ${where.join(' AND ')}` : ''}
+       ORDER BY hour, kind, name, model, provider, tenant`, params.values);
+        return rows.map((raw) => {
+            const row = raw;
+            return {
+                hour: String(row.hour),
+                kind: row.kind,
+                name: String(row.name),
+                model: String(row.model),
+                provider: String(row.provider),
+                tenant: String(row.tenant),
+                runs: Number(row.runs),
+                errors: Number(row.errors),
+                cost: Number(row.cost),
+                inputTokens: Number(row.input_tokens),
+                outputTokens: Number(row.output_tokens),
+                latency: String(row.latency).replace(/[{}]/g, '').split(',').filter(Boolean).map(Number),
+            };
+        });
+    }
+}
+function bucketsOf(latency) {
+    return Array.from({ length: ROLLUP_LATENCY_BOUNDS_MS.length + 1 }, (_, index) => Math.round(latency[index] ?? 0));
+}
+function hourOf(iso) {
+    const date = new Date(iso);
+    date.setUTCMinutes(0, 0, 0);
+    return date.toISOString();
+}