nexus-ai-pro 2.1.0 → 2.2.0

package/dist/server/assistant.d.ts

@@ -12,12 +12,14 @@ export interface GraphLike {
         threadId?: string;
         signal?: AbortSignal;
         metadata?: Record<string, unknown>;
+        tenantId?: string;
         control?: DrainSwitch;
     }): AsyncIterable<unknown>;
     /** Answers an interrupt and continues the thread. */
     resume(threadId: string, value: unknown, options: {
         signal?: AbortSignal;
         metadata?: Record<string, unknown>;
+        tenantId?: string;
         control?: DrainSwitch;
     }): AsyncIterable<unknown>;
     /** The thread's checkpoint, at its latest step or at one given. */
@@ -31,6 +33,7 @@ export interface GraphLike {
     continue?(threadId: string, options: {
         signal?: AbortSignal;
         metadata?: Record<string, unknown>;
+        tenantId?: string;
         control?: DrainSwitch;
     }): AsyncIterable<unknown>;
     /** Writes values into a thread's state, which is how a rollback is applied. */
@@ -47,6 +50,7 @@ export interface GraphLike {
 /** The options of a graph's `events()` the adapter passes. */
 type GraphEventOptionsLike = {
     threadId?: string;
+    tenantId?: string;
     signal?: AbortSignal;
     metadata?: Record<string, unknown>;
     control?: DrainSwitch;

package/dist/server/assistant.js

@@ -4,6 +4,7 @@ export function graphAssistant(graph, options = {}) {
         ...(threadId ? { threadId } : {}),
         signal: context.signal,
         metadata: { ...options.metadata, runId: context.runId },
+        ...tenantOf(context),
         ...(context.control ? { control: context.control } : {}),
         include: [...(projections ?? []), 'values'],
     });
@@ -17,6 +18,7 @@ export function graphAssistant(graph, options = {}) {
                 threadId: context.threadId,
                 signal: context.signal,
                 metadata: { ...options.metadata, runId: context.runId },
+                ...tenantOf(context),
                 ...(context.control ? { control: context.control } : {}),
             });
         },
@@ -27,6 +29,7 @@ export function graphAssistant(graph, options = {}) {
             return graph.resume(threadId, value, {
                 signal: context.signal,
                 metadata: { ...options.metadata, runId: context.runId },
+                ...tenantOf(context),
                 ...(context.control ? { control: context.control } : {}),
             });
         },
@@ -50,6 +53,7 @@ export function graphAssistant(graph, options = {}) {
             return graph.continue(threadId, {
                 signal: context.signal,
                 metadata: { ...options.metadata, runId: context.runId },
+                ...tenantOf(context),
                 ...(context.control ? { control: context.control } : {}),
             });
         },
@@ -76,6 +80,10 @@ export function functionAssistant(run, options = {}) {
         },
     };
 }
+function tenantOf(context) {
+    const tenantId = context.principal?.tenantId;
+    return tenantId ? { tenantId } : {};
+}
 async function* withResult(events) {
     for await (const event of events)
         yield event;

package/dist/server/errors.d.ts

@@ -32,6 +32,18 @@ export declare class ForbiddenError extends ServerError {
     /** The scope the route required. */
     scope: string);
 }
+/**
+ * Thrown by an assistant to hand its run to another worker while this replica drains: the server puts
+ * the run back on the queue as its next attempt instead of failing it. A function assistant checks
+ * `context.control?.draining` between its own steps, saves where it got with `context.saveProgress()`,
+ * and throws this; the next worker reads `context.progress`. Thrown when the replica is not draining,
+ * it fails the run like any error.
+ */
+export declare class RunHandOffError extends Error {
+    /** Always `RUN_HANDED_OFF`. */
+    readonly code = "RUN_HANDED_OFF";
+    constructor(message?: string);
+}
 /** Raised when a thread is already running something and the busy policy is `reject`. */
 export declare class ThreadBusyError extends ServerError {
     /** The thread. */

package/dist/server/errors.js

@@ -35,6 +35,13 @@ export class ForbiddenError extends ServerError {
         this.name = 'ForbiddenError';
     }
 }
+export class RunHandOffError extends Error {
+    code = 'RUN_HANDED_OFF';
+    constructor(message = 'Handed to another worker while this one drains') {
+        super(message);
+        this.name = 'RunHandOffError';
+    }
+}
 export class ThreadBusyError extends ServerError {
     threadId;
     runId;

package/dist/server/index.d.ts

@@ -9,7 +9,7 @@
  */
 export { functionAssistant, type GraphAssistantOptions, graphAssistant, type GraphLike, } from './assistant.js';
 export { CronScheduler, type CronSchedulerOptions, type DueCronJob, parseCron } from './cron.js';
-export { AssistantCapabilityError, BadRequestError, ForbiddenError, NotFoundError, ServerError, type TenantLimit, TenantLimitError, ThreadBusyError, UnauthorizedError, } from './errors.js';
+export { AssistantCapabilityError, BadRequestError, ForbiddenError, NotFoundError, RunHandOffError, ServerError, type TenantLimit, TenantLimitError, ThreadBusyError, UnauthorizedError, } from './errors.js';
 export { MemoryRunEventLog, type MemoryRunEventLogOptions, type RedisEventLogLikeClient, RedisRunEventLog, type RedisRunEventLogOptions, } from './events.js';
 export { type NodeListenerOptions, type NodeRequestLike, type NodeResponseLike, toNodeListener, } from './node.js';
 export { type DrainResult, RunManager, type RunManagerOptions, type RunQueueOptions, type StartRunOptions, } from './runs.js';

package/dist/server/index.js

@@ -1,6 +1,6 @@
 export { functionAssistant, graphAssistant, } from './assistant.js';
 export { CronScheduler, parseCron } from './cron.js';
-export { AssistantCapabilityError, BadRequestError, ForbiddenError, NotFoundError, ServerError, TenantLimitError, ThreadBusyError, UnauthorizedError, } from './errors.js';
+export { AssistantCapabilityError, BadRequestError, ForbiddenError, NotFoundError, RunHandOffError, ServerError, TenantLimitError, ThreadBusyError, UnauthorizedError, } from './errors.js';
 export { MemoryRunEventLog, RedisRunEventLog, } from './events.js';
 export { toNodeListener, } from './node.js';
 export { RunManager, } from './runs.js';

package/dist/server/runs.d.ts

@@ -159,6 +159,8 @@ export declare class RunManager {
      * it with a `TenantLimitError`.
      */
     start(options: StartRunOptions): Promise<RunRecord>;
+    /** The rest of `start()`, once the thread, if any, is this run's. */
+    private startClaimed;
     /** Cancels a run, including one another replica is executing. */
     cancel(runId: string, principal?: Principal, reason?: string): Promise<RunRecord>;
     /**
@@ -210,8 +212,29 @@ export declare class RunManager {
     private freeSlot;
     private schedule;
     private tick;
-    /** Applies the busy policy, returning the thread once it is free to run something new. */
+    /**
+     * Applies the busy policy, returning the thread once this run holds it. The thread is claimed
+     * atomically, so of several replicas starting runs on one thread at once, exactly one proceeds and
+     * the rest meet the policy; a thread still busy after the policy has run its course is refused.
+     */
     private settleBusyThread;
+    /**
+     * Claims a thread for a run. The claim is a record in the operation store under a unique
+     * idempotency key, moved from run to run by compare-and-set, so two replicas cannot both take a free
+     * thread: creating it races on the key, and taking it over races on the sequence. Resolves
+     * undefined once this run holds the thread, or the id of the unfinished run that does.
+     *
+     * A store without `findByIdempotencyKey` falls back to the thread record's `activeRunId`, which is
+     * what every release before 2.2 used, and which two replicas racing can both see empty.
+     */
+    private claimThread;
+    /**
+     * Whether a thread's holder no longer needs it: its run finished, or it was never recorded and its
+     * claim is old enough that the replica starting it must have died.
+     */
+    private runIsFree;
+    /** Frees a thread this run holds. Losing the compare-and-set means another run took it over, which is fine. */
+    private releaseClaim;
     /** Waits for a run to finish, for the `enqueue` policy. */
     private waitForRun;
     private releaseThread;

package/dist/server/runs.js

@@ -1,4 +1,4 @@
-import { OperationReleasedError } from '../operations/errors.js';
+import { OperationDuplicateError, OperationReleasedError } from '../operations/errors.js';
 import { OperationRunner } from '../operations/runner.js';
 import { operationStats } from '../operations/stats.js';
 import { MemoryOperationStore } from '../operations/store.js';
@@ -9,6 +9,8 @@ import { MemoryServerStore, RUNS_NAMESPACE } from './state.js';
 const THREADS = ['nexus', 'server', 'threads'];
 const RUNS = RUNS_NAMESPACE;
 const KIND_PREFIX = 'assistant:';
+const THREAD_CLAIM = 'nexus-thread:';
+const UNRECORDED_CLAIM_MS = 60_000;
 const DEFAULT_CONCURRENCY = 10;
 const DEFAULT_POLL_MS = 1_000;
 const DEFAULT_RECOVER_MS = 30_000;
@@ -120,12 +122,22 @@ export class RunManager {
     }
     async start(options) {
         const base = this.assistant(options.assistant);
+        const runId = `run-${randomId()}`;
         let thread;
         if (options.threadId) {
             thread = await this.thread(options.threadId, options.principal);
-            thread = await this.settleBusyThread(thread, options);
+            thread = await this.settleBusyThread(thread, options, runId);
         }
-        const runId = `run-${randomId()}`;
+        try {
+            return await this.startClaimed(runId, base, thread, options);
+        }
+        catch (error) {
+            if (thread)
+                await this.releaseClaim(thread.id, runId).catch((cause) => this.report(cause, { runId }));
+            throw error;
+        }
+    }
+    async startClaimed(runId, base, thread, options) {
         let assistant = base;
         let revision;
         if (base.route) {
@@ -350,6 +362,8 @@ export class RunManager {
             acceptedId = (await this.runner.enqueue(submit)).id;
         }
         if (acceptedId !== runId) {
+            if (thread)
+                await this.releaseClaim(thread.id, runId);
             await this.state.delete(RUNS, runId);
             await this.releaseTenant(runId, options.principal?.tenantId);
             return (await this.state.get(RUNS, acceptedId)) ?? run;
@@ -393,6 +407,8 @@ export class RunManager {
             metadata: plan.metadata,
             attempt: context.attempt,
             ...(plan.revision ? { revision: plan.revision.id } : {}),
+            saveProgress: (details) => context.heartbeat(details),
+            ...(context.previousHeartbeat === undefined ? {} : { progress: context.previousHeartbeat }),
             recordCost: async (usd) => {
                 if (!Number.isFinite(usd) || usd <= 0)
                     return;
@@ -534,21 +550,21 @@ export class RunManager {
         const pollMs = this.options.queue?.pollMs ?? DEFAULT_POLL_MS;
         this.schedule(claimed > 0 && this.freeSlots() > 0 ? 0 : Math.min(pollMs, this.options.recoverEveryMs ?? pollMs));
     }
-    async settleBusyThread(thread, options) {
+    async settleBusyThread(thread, options, runId) {
         const policy = options.onBusy ?? this.options.onBusy ?? 'reject';
         let current = thread;
-        for (let attempt = 0; attempt < 2; attempt += 1) {
-            const activeId = current.activeRunId;
+        const deadline = this.now().getTime() + (this.options.queueTimeoutMs ?? 30_000);
+        for (let attempt = 0; attempt < 4 || (policy === 'enqueue' && this.now().getTime() < deadline); attempt += 1) {
+            const activeId = await this.claimThread(current, runId);
             if (!activeId)
                 return current;
             const active = await this.state.get(RUNS, activeId);
-            if (!active || isFinished(active.status)) {
-                current = { ...current, activeRunId: undefined };
-                await this.state.put(THREADS, current.id, current);
-                return current;
-            }
             if (policy === 'reject')
                 throw new ThreadBusyError(current.id, activeId);
+            if (!active) {
+                await delay(50);
+                continue;
+            }
             if (policy === 'enqueue') {
                 await this.waitForRun(activeId);
                 current = await this.thread(current.id, options.principal);
@@ -565,9 +581,67 @@ export class RunManager {
             }
             current = { ...current, activeRunId: undefined };
             await this.state.put(THREADS, current.id, current);
-            return current;
         }
-        return current;
+        throw new ThreadBusyError(current.id, current.activeRunId ?? 'another run');
+    }
+    async claimThread(thread, runId) {
+        if (!this.store.findByIdempotencyKey) {
+            const activeId = thread.activeRunId;
+            return activeId && !(await this.runIsFree(activeId, undefined)) ? activeId : undefined;
+        }
+        const key = `${THREAD_CLAIM}${thread.id}`;
+        for (let attempt = 0; attempt < 8; attempt += 1) {
+            const claim = await this.store.findByIdempotencyKey(key);
+            const at = this.now().toISOString();
+            if (!claim) {
+                try {
+                    await this.store.create({
+                        id: `${key}:${runId}`,
+                        status: 'succeeded',
+                        attempt: 1,
+                        maxAttempts: 1,
+                        sequence: 0,
+                        createdAt: at,
+                        updatedAt: at,
+                        kind: 'server.thread',
+                        idempotencyKey: key,
+                        result: { runId },
+                    });
+                    return undefined;
+                }
+                catch (error) {
+                    if (error instanceof OperationDuplicateError)
+                        continue;
+                    throw error;
+                }
+            }
+            const holder = claim.result?.runId;
+            if (holder === runId)
+                return undefined;
+            if (holder && !(await this.runIsFree(holder, claim.updatedAt)))
+                return holder;
+            const taken = await this.store.update({ ...claim, result: { runId }, sequence: claim.sequence + 1, updatedAt: at }, claim.sequence);
+            if (taken)
+                return undefined;
+        }
+        const holder = (await this.store.findByIdempotencyKey(key))?.result?.runId;
+        return holder ?? 'another run';
+    }
+    async runIsFree(runId, claimedAt) {
+        const run = await this.state.get(RUNS, runId);
+        if (run)
+            return isFinished(run.status);
+        if (claimedAt === undefined)
+            return true;
+        return this.now().getTime() - Date.parse(claimedAt) > UNRECORDED_CLAIM_MS;
+    }
+    async releaseClaim(threadId, runId) {
+        if (!this.store.findByIdempotencyKey)
+            return;
+        const claim = await this.store.findByIdempotencyKey(`${THREAD_CLAIM}${threadId}`);
+        if (!claim || claim.result?.runId !== runId)
+            return;
+        await this.store.update({ ...claim, result: {}, sequence: claim.sequence + 1, updatedAt: this.now().toISOString() }, claim.sequence);
     }
     async waitForRun(runId) {
         const deadline = this.now().getTime() + (this.options.queueTimeoutMs ?? 30_000);
@@ -584,6 +658,7 @@ export class RunManager {
     async releaseThread(threadId, runId) {
         if (!threadId)
             return;
+        await this.releaseClaim(threadId, runId).catch((error) => this.report(error, { runId }));
         const thread = await this.state.get(THREADS, threadId);
         if (!thread || thread.activeRunId !== runId)
             return;
@@ -678,5 +753,6 @@ function delay(ms) {
     });
 }
 function isDrained(error) {
-    return typeof error === 'object' && error !== null && error.code === 'GRAPH_DRAINED';
+    const code = typeof error === 'object' && error !== null ? error.code : undefined;
+    return code === 'GRAPH_DRAINED' || code === 'RUN_HANDED_OFF';
 }

package/dist/sqlite/index.d.ts

@@ -1,4 +1,17 @@
+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 { fromLibsql, fromSqliteDatabase, type LibsqlLikeClient, type SqliteDatabaseLike, type SqliteLikeClient, type SqliteValue, } from './client.js';
-export { SqliteOperationStore, type SqliteOperationStoreOptions, sqliteOperationStoreMigration } from './operations.js';
-export { SqliteStore, type SqliteStoreOptions, sqliteStoreMigration } from './store.js';
-export { SqliteVectorStore, type SqliteVectorStoreOptions, sqliteVectorStoreMigration } from './vectors.js';
+export { applySqliteMigrations, type SqliteMigrateOptions, sqliteMigrationStatus } from './migrations.js';
+export { SqliteOperationStore, type SqliteOperationStoreOptions, sqliteOperationStoreMigration, sqliteOperationStoreMigrations, } from './operations.js';
+export { SqliteStore, type SqliteStoreOptions, sqliteStoreMigration, sqliteStoreMigrations } from './store.js';
+export { SqliteVectorStore, type SqliteVectorStoreOptions, sqliteVectorStoreMigration, sqliteVectorStoreMigrations, } from './vectors.js';
+/** The SQLite adapters a migration can include. */
+export type SqliteAdapter = 'operations' | 'store' | 'vectors';
+/**
+ * The versioned migrations of the chosen adapters on their default tables, for
+ * `applySqliteMigrations()`, `sqliteMigrationStatus()`, and `nexus db migrate`. Defaults to every
+ * adapter. A store on a custom table migrates through its own `migrate()`.
+ */
+export declare function sqliteMigrations(options?: {
+    adapters?: readonly SqliteAdapter[];
+}): SchemaMigration[];

package/dist/sqlite/index.js

@@ -1,4 +1,17 @@
+import { sqliteOperationStoreMigrations } from './operations.js';
+import { sqliteStoreMigrations } from './store.js';
+import { sqliteVectorStoreMigrations } from './vectors.js';
+export { migrationChecksum, SchemaMigrationError, } from '../utils/schema-migrations.js';
 export { fromLibsql, fromSqliteDatabase, } from './client.js';
-export { SqliteOperationStore, sqliteOperationStoreMigration } from './operations.js';
-export { SqliteStore, sqliteStoreMigration } from './store.js';
-export { SqliteVectorStore, sqliteVectorStoreMigration } from './vectors.js';
+export { applySqliteMigrations, sqliteMigrationStatus } from './migrations.js';
+export { SqliteOperationStore, sqliteOperationStoreMigration, sqliteOperationStoreMigrations, } from './operations.js';
+export { SqliteStore, sqliteStoreMigration, sqliteStoreMigrations } from './store.js';
+export { SqliteVectorStore, sqliteVectorStoreMigration, sqliteVectorStoreMigrations, } from './vectors.js';
+export function sqliteMigrations(options = {}) {
+    const adapters = new Set(options.adapters ?? ['operations', 'store', 'vectors']);
+    return [
+        ...(adapters.has('operations') ? sqliteOperationStoreMigrations() : []),
+        ...(adapters.has('store') ? sqliteStoreMigrations() : []),
+        ...(adapters.has('vectors') ? sqliteVectorStoreMigrations() : []),
+    ];
+}

package/dist/sqlite/migrations.d.ts

@@ -0,0 +1,26 @@
+import { type MigrationResult, type MigrationStatus, type SchemaMigration } from '../utils/schema-migrations.js';
+import { type SqliteDatabaseLike, type SqliteLikeClient } from './client.js';
+export { type AppliedMigration, type MigrationResult, type MigrationStatus, migrationChecksum, type SchemaMigration, SchemaMigrationError, } from '../utils/schema-migrations.js';
+/** Options for applying or inspecting SQLite migrations. */
+export interface SqliteMigrateOptions {
+    /** Plans without writing anything, not even the table that records migrations. */
+    dryRun?: boolean;
+    /** The table that records applied migrations. Defaults to `nexus_schema_migrations`. */
+    table?: string;
+}
+/**
+ * Where a SQLite database stands against a list of migrations. Reads only: on a database that has
+ * never been migrated, everything is pending.
+ */
+export declare function sqliteMigrationStatus(database: SqliteLikeClient | SqliteDatabaseLike, migrations: readonly SchemaMigration[], options?: Pick<SqliteMigrateOptions, 'table'>): Promise<MigrationStatus>;
+/**
+ * Applies the pending migrations in order, recording each with a checksum.
+ *
+ * Each migration runs inside `BEGIN IMMEDIATE`, which takes SQLite's write lock: its statements and
+ * the row recording it land together or not at all, and a second process migrating the same file
+ * waits for the first instead of interleaving with it. A migration whose statements changed after it
+ * ran is refused before anything is written.
+ */
+export declare function applySqliteMigrations(database: SqliteLikeClient | SqliteDatabaseLike, migrations: readonly SchemaMigration[], options?: SqliteMigrateOptions): Promise<MigrationResult>;
+/** The statement that creates the migrations table, which `migrate()` runs first. */
+export declare function sqliteMigrationsTableStatement(table?: string): string;

package/dist/sqlite/migrations.js

@@ -0,0 +1,63 @@
+import { assertUnchanged, MIGRATIONS_TABLE, migrationChecksum, planMigrations, sqlLiteral, } from '../utils/schema-migrations.js';
+import { quoteSqliteTable, toSqliteClient } from './client.js';
+export { migrationChecksum, SchemaMigrationError, } from '../utils/schema-migrations.js';
+export async function sqliteMigrationStatus(database, migrations, options = {}) {
+    return planMigrations(migrations, await readApplied(toSqliteClient(database), options.table ?? MIGRATIONS_TABLE));
+}
+export async function applySqliteMigrations(database, migrations, options = {}) {
+    const client = toSqliteClient(database);
+    const tableName = options.table ?? MIGRATIONS_TABLE;
+    if (options.dryRun) {
+        const status = await sqliteMigrationStatus(client, migrations, options);
+        assertUnchanged(status);
+        return { applied: status.pending, statements: status.pending.flatMap((m) => [...m.statements]), dryRun: true };
+    }
+    planMigrations(migrations, []);
+    await client.exec(sqliteMigrationsTableStatement(tableName));
+    const status = planMigrations(migrations, await readApplied(client, tableName));
+    assertUnchanged(status);
+    const table = quoteSqliteTable(tableName);
+    const statements = [];
+    for (const migration of status.pending) {
+        const record = `INSERT OR IGNORE INTO ${table} (component, version, name, checksum, applied_at) VALUES (${sqlLiteral(migration.component)}, ${migration.version}, ${sqlLiteral(migration.name)}, ${sqlLiteral(migrationChecksum(migration))}, ${sqlLiteral(new Date().toISOString())})`;
+        const script = ['BEGIN IMMEDIATE', ...migration.statements, record, 'COMMIT'].join(';\n');
+        try {
+            await client.exec(`${script};`);
+        }
+        catch (error) {
+            try {
+                await client.exec('ROLLBACK');
+            }
+            catch {
+            }
+            throw error;
+        }
+        statements.push(...migration.statements);
+    }
+    return { applied: status.pending, statements, dryRun: false };
+}
+export function sqliteMigrationsTableStatement(table = MIGRATIONS_TABLE) {
+    return `CREATE TABLE IF NOT EXISTS ${quoteSqliteTable(table)} (
+  component TEXT NOT NULL,
+  version INTEGER NOT NULL,
+  name TEXT NOT NULL,
+  checksum TEXT NOT NULL,
+  applied_at TEXT NOT NULL,
+  PRIMARY KEY (component, version)
+)`;
+}
+async function readApplied(client, table) {
+    const exists = (await client.all(`SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?`, [
+        table,
+    ]));
+    if (exists.length === 0)
+        return [];
+    const rows = (await client.all(`SELECT component, version, name, checksum, applied_at FROM ${quoteSqliteTable(table)} ORDER BY applied_at, component, version`, []));
+    return rows.map((row) => ({
+        component: String(row.component),
+        version: Number(row.version),
+        name: String(row.name),
+        checksum: String(row.checksum),
+        appliedAt: String(row.applied_at),
+    }));
+}

package/dist/sqlite/operations.d.ts

@@ -1,12 +1,20 @@
 import { type OperationRecord, type OperationStore, type OperationStoreFilter, type OperationStoreStats } from '../types/operations.js';
+import type { MigrationResult, SchemaMigration } from '../utils/schema-migrations.js';
 import { type SqliteDatabaseLike, type SqliteLikeClient } from './client.js';
+import type { SqliteMigrateOptions } from './migrations.js';
 /** Options for the SQLite operation store. */
 export interface SqliteOperationStoreOptions {
     /** Table name. Defaults to `nexus_operations`. */
     table?: string;
 }
-/** The schema, as statements. Applied by `migrate()`, or by the application's own tooling. */
+/** The schema, as statements: every migration's, in order. For the application's own tooling. */
 export declare function sqliteOperationStoreMigration(options?: SqliteOperationStoreOptions): string[];
+/**
+ * The versioned schema, which `migrate()` applies. 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 sqliteOperationStoreMigrations(options?: SqliteOperationStoreOptions): SchemaMigration[];
 /**
  * Operation records in SQLite: durable operations, and — through `OperationStoreCheckpointer` — graph
  * and workflow checkpoints, on one machine with no server to run.
@@ -20,8 +28,11 @@ export declare class SqliteOperationStore<TResult = unknown> implements Operatio
     private readonly client;
     private readonly table;
     constructor(database: SqliteLikeClient | SqliteDatabaseLike, options?: SqliteOperationStoreOptions);
-    /** 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`, each inside
+     * `BEGIN IMMEDIATE`. Never runs implicitly. Safe on a file an older release created.
+     */
+    migrate(options?: SqliteMigrateOptions): Promise<MigrationResult>;
     /**
      * Inserts a new record. Throws `OperationDuplicateError` when its idempotency key is already
      * claimed. Refuses records carrying raw bytes.

package/dist/sqlite/operations.js

@@ -5,8 +5,31 @@ import { isSqliteUniqueViolation, quoteSqliteTable, toSqliteClient, } from './cl
 const DEFAULT_TABLE = 'nexus_operations';
 const TERMINAL = TERMINAL_OPERATION_STATUSES.map((status) => `'${status}'`).join(', ');
 export function sqliteOperationStoreMigration(options = {}) {
+    return sqliteOperationStoreMigrations(options).flatMap((migration) => [...migration.statements]);
+}
+export function sqliteOperationStoreMigrations(options = {}) {
     const name = options.table ?? DEFAULT_TABLE;
     const table = quoteSqliteTable(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 "${name}_queued" ON ${table} (status, created_at, id)`],
+        },
+        {
+            component,
+            version: 3,
+            name: 'index queued work by tenant',
+            statements: [
+                `CREATE INDEX IF NOT EXISTS "${name}_tenant_queued" ON ${table} (status, json_extract(doc, '$.tenantId'), created_at, id)`,
+            ],
+        },
+    ];
+}
+function createStatements(name, table) {
     return [
         `CREATE TABLE IF NOT EXISTS ${table} (
   id TEXT PRIMARY KEY,
@@ -32,9 +55,9 @@ export class SqliteOperationStore {
         this.client = toSqliteClient(database);
         this.table = quoteSqliteTable(options.table ?? DEFAULT_TABLE);
     }
-    async migrate() {
-        for (const statement of sqliteOperationStoreMigration(this.options))
-            await this.client.exec(statement);
+    async migrate(options = {}) {
+        const { applySqliteMigrations } = await import('./migrations.js');
+        return applySqliteMigrations(this.client, sqliteOperationStoreMigrations(this.options), options);
     }
     async create(record) {
         assertSerializableRecord(record);
@@ -99,29 +122,21 @@ export class SqliteOperationStore {
     }
     async listQueued(limit, filter) {
         const params = [new Date().toISOString()];
-        let kind = '';
-        if (filter?.kindPrefix) {
-            params.push(filter.kindPrefix, filter.kindPrefix);
-            kind = ' AND substr(kind, 1, length(?)) = ?';
-        }
+        const narrowed = filterSql(filter, params);
         params.push(limit);
         return this.many(`SELECT doc FROM ${this.table}
-       WHERE status = 'queued' AND (lease_expires_at IS NULL OR lease_expires_at <= ?)${kind}
+       WHERE status = 'queued' AND (lease_expires_at IS NULL OR lease_expires_at <= ?)${narrowed}
        ORDER BY created_at, id
        LIMIT ?`, params);
     }
     async stats(now, filter) {
         const params = [now];
-        let kind = '';
-        if (filter?.kindPrefix) {
-            params.push(filter.kindPrefix, filter.kindPrefix);
-            kind = ' AND substr(kind, 1, length(?)) = ?';
-        }
+        const narrowed = filterSql(filter, params);
         const rows = (await this.client.all(`SELECT status, count(*) AS count,
          min(CASE WHEN status = 'queued' THEN created_at END) AS oldest,
          sum(CASE WHEN status = 'running' AND (lease_expires_at IS NULL OR lease_expires_at <= ?) THEN 1 ELSE 0 END) AS lapsed
        FROM ${this.table}
-       WHERE status NOT IN (${TERMINAL})${kind}
+       WHERE status NOT IN (${TERMINAL})${narrowed}
        GROUP BY status`, params));
         const byStatus = {};
         let oldestQueuedAt;
@@ -146,3 +161,15 @@ export class SqliteOperationStore {
         return rows.map((row) => JSON.parse(row.doc));
     }
 }
+function filterSql(filter, params) {
+    let sql = '';
+    if (filter?.kindPrefix) {
+        params.push(filter.kindPrefix, filter.kindPrefix);
+        sql += ' AND substr(kind, 1, length(?)) = ?';
+    }
+    if (filter?.tenantId !== undefined) {
+        params.push(filter.tenantId);
+        sql += " AND json_extract(doc, '$.tenantId') = ?";
+    }
+    return sql;
+}

package/dist/sqlite/store.d.ts

@@ -1,5 +1,7 @@
 import type { Store, StoreIndexOptions, StoreItem, StoreNamespace, StorePutOptions, StoreSearchOptions } from '../types/store.js';
+import type { MigrationResult, SchemaMigration } from '../utils/schema-migrations.js';
 import { type SqliteDatabaseLike, type SqliteLikeClient } from './client.js';
+import type { SqliteMigrateOptions } from './migrations.js';
 /** Options for the SQLite store. */
 export interface SqliteStoreOptions {
     /** Table name. Defaults to `nexus_store`. */
@@ -11,6 +13,8 @@ export interface SqliteStoreOptions {
 }
 /** The schema, as statements. */
 export declare function sqliteStoreMigration(options?: Pick<SqliteStoreOptions, 'table'>): string[];
+/** The versioned schema, which `migrate()` applies. Version 1 is the 2.0 schema. */
+export declare function sqliteStoreMigrations(options?: Pick<SqliteStoreOptions, 'table'>): SchemaMigration[];
 /**
  * Long-term memory in SQLite, for one machine that needs memory to survive a restart.
  *
@@ -25,8 +29,11 @@ export declare class SqliteStore implements Store {
     private readonly table;
     private readonly now;
     constructor(database: SqliteLikeClient | SqliteDatabaseLike, options?: SqliteStoreOptions);
-    /** 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`, each inside
+     * `BEGIN IMMEDIATE`. Never runs implicitly. Safe on a file an older release created.
+     */
+    migrate(options?: SqliteMigrateOptions): Promise<MigrationResult>;
     /** Stores an item, keeping its original `createdAt` when it replaces one. */
     put<V>(namespace: StoreNamespace, key: string, value: V, options?: StorePutOptions): Promise<void>;
     /** Reads an item, or `undefined` when it does not exist or has expired. */