nexus-ai-pro 2.0.0 → 2.2.0

package/dist/server/assistant.d.ts

@@ -1,3 +1,4 @@
+import type { GraphStreamProjection } from '../types/graph.js';
 import type { AssistantRunContext, ServerAssistant } from '../types/server.js';
 /**
  * The part of a compiled graph the adapter uses.
@@ -11,11 +12,15 @@ 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. */
     state(threadId: string, step?: number): Promise<{
@@ -28,18 +33,56 @@ 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. */
     updateState?(threadId: string, values: Record<string, unknown>, options?: {
         asNode?: string;
     }): Promise<unknown>;
+    /** Runs an input as a stream of typed events. Used when the assistant serves `events`. */
+    events?(input: unknown, options: GraphEventOptionsLike): GraphEventsLike;
+    /** Like `events()`, answering an interrupt. */
+    resumeEvents?(threadId: string, value: unknown, options: GraphEventOptionsLike): GraphEventsLike;
+    /** Like `events()`, continuing a thread from its latest checkpoint. */
+    continueEvents?(threadId: string, options: GraphEventOptionsLike): GraphEventsLike;
 }
+/** The options of a graph's `events()` the adapter passes. */
+type GraphEventOptionsLike = {
+    threadId?: string;
+    tenantId?: string;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+    control?: DrainSwitch;
+    include?: GraphStreamProjection[];
+};
+/** A graph's event stream, as the adapter reads it: the events, then the run's result. */
+type GraphEventsLike = AsyncIterable<unknown> & {
+    result: Promise<{
+        status: string;
+        state: unknown;
+        interrupt?: unknown;
+        interrupts?: unknown[];
+    }>;
+};
+/** Asks a graph to stop after its current superstep. A graph's `RunControl` has this shape. */
+type DrainSwitch = {
+    readonly draining: boolean;
+    readonly reason?: string;
+};
 /** Options for `graphAssistant()`. */
 export interface GraphAssistantOptions {
     /** What the assistant is, reported by the assistants endpoint. */
     description?: string;
     /** Metadata recorded on every checkpoint the server's runs create. */
     metadata?: Record<string, unknown>;
+    /**
+     * Records these projections of the graph's event stream on each run, such as `messages` and
+     * `tools`, so a client following the run sees model output and tool calls as they happen. The
+     * run's last event still carries its state and any question, as without it. Defaults to none: one
+     * event per superstep.
+     */
+    events?: GraphStreamProjection[];
 }
 /**
  * Serves a compiled graph as an assistant.
@@ -61,3 +104,4 @@ export declare function graphAssistant(graph: GraphLike, options?: GraphAssistan
 export declare function functionAssistant(run: (input: unknown, context: AssistantRunContext) => AsyncIterable<unknown> | Promise<unknown> | unknown, options?: {
     description?: string;
 }): ServerAssistant;
+export {};

package/dist/server/assistant.js

@@ -1,17 +1,36 @@
 export function graphAssistant(graph, options = {}) {
+    const projections = options.events?.length ? options.events : undefined;
+    const eventOptions = (context, threadId) => ({
+        ...(threadId ? { threadId } : {}),
+        signal: context.signal,
+        metadata: { ...options.metadata, runId: context.runId },
+        ...tenantOf(context),
+        ...(context.control ? { control: context.control } : {}),
+        include: [...(projections ?? []), 'values'],
+    });
     return {
         description: options.description,
         stream(input, context) {
+            if (projections && graph.events) {
+                return withResult(graph.events(input ?? {}, eventOptions(context, context.threadId)));
+            }
             return graph.stream(input ?? {}, {
                 threadId: context.threadId,
                 signal: context.signal,
                 metadata: { ...options.metadata, runId: context.runId },
+                ...tenantOf(context),
+                ...(context.control ? { control: context.control } : {}),
             });
         },
         resume(threadId, value, context) {
+            if (projections && graph.resumeEvents) {
+                return withResult(graph.resumeEvents(threadId, value, eventOptions(context)));
+            }
             return graph.resume(threadId, value, {
                 signal: context.signal,
                 metadata: { ...options.metadata, runId: context.runId },
+                ...tenantOf(context),
+                ...(context.control ? { control: context.control } : {}),
             });
         },
         async state(threadId) {
@@ -29,9 +48,13 @@ export function graphAssistant(graph, options = {}) {
             if (checkpoint.status !== 'running' && checkpoint.status !== 'failed' && checkpoint.status !== 'interrupted') {
                 return undefined;
             }
+            if (projections && graph.continueEvents)
+                return withResult(graph.continueEvents(threadId, eventOptions(context)));
             return graph.continue(threadId, {
                 signal: context.signal,
                 metadata: { ...options.metadata, runId: context.runId },
+                ...tenantOf(context),
+                ...(context.control ? { control: context.control } : {}),
             });
         },
         async restore(threadId, step) {
@@ -57,3 +80,19 @@ 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;
+    const result = await events.result;
+    yield {
+        type: result.status === 'awaiting_input' ? 'interrupt' : 'done',
+        status: result.status,
+        state: result.state,
+        ...(result.interrupt === undefined ? {} : { interrupt: result.interrupt }),
+        ...(result.interrupts === undefined ? {} : { interrupts: result.interrupts }),
+    };
+}

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

@@ -97,6 +97,10 @@ export declare class RunManager {
     private readonly local;
     /** Runs holding one of this replica's execution slots. */
     private readonly slots;
+    /** The drain switch of each run this replica is executing, so `drain()` can reach graph runs. */
+    private readonly controls;
+    /** Runs handed back to the queue during a drain, as each graph run stopped at a boundary. */
+    private readonly drainedRuns;
     private readonly state;
     private readonly events;
     private readonly now;
@@ -155,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>;
     /**
@@ -206,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;
@@ -26,6 +28,8 @@ export class RunManager {
     store;
     local = new Map();
     slots = new Set();
+    controls = new Map();
+    drainedRuns = new Set();
     state;
     events;
     now;
@@ -118,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) {
@@ -217,11 +231,18 @@ export class RunManager {
     async drain(options = {}) {
         this.draining = true;
         this.stopWorking();
+        if (this.options.queue) {
+            for (const control of this.controls.values()) {
+                control.draining = true;
+                control.reason = 'replica draining';
+            }
+        }
         const running = [...this.slots];
         const deadline = Date.now() + (options.timeoutMs ?? 25_000);
         while (this.slots.size > 0 && Date.now() < deadline)
             await pause(Math.min(50, deadline - Date.now()));
-        const released = [];
+        const released = [...this.drainedRuns];
+        this.drainedRuns.clear();
         if (this.options.queue) {
             for (const id of [...this.slots]) {
                 if (this.runner.release(id))
@@ -341,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;
@@ -374,14 +397,18 @@ export class RunManager {
     async execute(plan, context) {
         const runId = context.operationId;
         let cost = 0;
+        const control = { draining: false };
         const runContext = {
             runId,
             threadId: plan.threadId,
             signal: context.signal,
+            control,
             principal: plan.principal,
             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;
@@ -411,6 +438,7 @@ export class RunManager {
                 ? plan.assistant.resume(plan.threadId, plan.resume, runContext)
                 : plan.assistant.stream(plan.input, runContext));
         let last;
+        this.controls.set(runId, control);
         try {
             for await (const event of stream) {
                 last = event;
@@ -419,6 +447,8 @@ export class RunManager {
             }
         }
         catch (error) {
+            if (control.draining && isDrained(error) && this.runner.release(runId))
+                this.drainedRuns.add(runId);
             if (context.signal.aborted && context.signal.reason instanceof OperationReleasedError) {
                 await this.record(runId, 'status', { status: 'queued', reason: 'handed to another worker' });
                 await this.settle(runId, 'queued', { addCost: cost });
@@ -439,6 +469,9 @@ export class RunManager {
             await this.releaseTenant(runId, plan.principal?.tenantId);
             throw error;
         }
+        finally {
+            this.controls.delete(runId);
+        }
         const interrupt = interruptOf(last);
         const status = interrupt ? 'awaiting_input' : 'succeeded';
         const output = outputOf(last);
@@ -517,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);
@@ -548,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);
@@ -567,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;
@@ -660,3 +752,7 @@ function delay(ms) {
             timer.unref?.();
     });
 }
+function isDrained(error) {
+    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),
+    }));
+}