nexus-ai-pro 2.1.0 → 2.2.0

package/API_STABILITY.md

@@ -41,6 +41,44 @@ Both are covered by this policy:
 Deep imports into `dist`, `dist-cjs`, or `src` are not supported. Import only from `nexus-ai-pro` or
 one of its explicit subpaths.
 
+## 2.2 stage (2.2.0)
+
+Everything 2.2 adds is stable from the start and additive: no default changes meaning.
+
+- versioned migrations: `SchemaMigration`, `AppliedMigration`, `MigrationStatus`, `MigrationResult`,
+  `SchemaMigrationError`, `migrationChecksum()`, `applyPostgresMigrations()`,
+  `postgresMigrationStatus()`, `postgresMigrations()`, `PostgresMigrateOptions`, every adapter's
+  `…Migrations()`, and the SQLite twins (`nexus-ai-pro/postgres`, `nexus-ai-pro/postgres/migrations`,
+  `nexus-ai-pro/sqlite`, `nexus-ai-pro/sqlite/migrations`). A migration, once released, never
+  changes; later releases add versions. `migrate()` now resolves to a `MigrationResult` instead of
+  nothing;
+- `nexus db status` and `nexus db migrate`, and `nexus db sql --record`;
+- `RedisOperationStoreOptions.index` and `reindex()`;
+- `CircuitBreakerConfig.shareObservations`, `CircuitStateStore.observe()`, `CircuitObservation`,
+  `CircuitWindow`, and `CircuitSnapshot.shared`;
+- `PostgresRollupStore` (`nexus-ai-pro/postgres/rollups`);
+- the tenant model (`nexus-ai-pro/tenancy`): every `tenant…()` view, `tenantScope()`,
+  `TenantAssetStore`, `TenantStores`, `assertTenantId()`, `TenantIdError`, and `TENANT_NAMESPACE`.
+  The prefix a view stores names under (`tenant/<id>/`) is part of the contract and does not change
+  within 2.x; `GraphRunOptions.tenantId`, `NodeContext.tenantId`, the `tenantId` options of `state()`,
+  `history()`, `fork()`, and `updateState()`, `OperationRecord.tenantId`,
+  `OperationSubmitOptions.tenantId`, `OperationStoreFilter.tenantId`, `RateLimitedRequest.tenantId`,
+  and `rateLimit.key: 'tenantId'`;
+- `CacheConfig.namespace`, `CacheNamespace`, `CacheOutcome` and `ResponseMeta.cache`,
+  `CompletionRequest.responseCache`, `MemoryCache.lookup()`, and the `scope` of `SemanticCache`'s
+  `get()` and `set()`;
+- `diagnose()` and its types (`nexus-ai-pro/doctor`), and `nexus doctor`. Checks may be added in a
+  minor release; a check's id and what makes it fail do not change within 2.x;
+- workflow steps' `timeout`, `onError`, `StepTimeout`, `StepFailure`, `StepRecovery`,
+  `StepContext.heartbeat()`, `WorkflowOptions.stepDefaults`, `WorkflowRunOptions.control` and
+  `tenantId`, `WorkflowContext.tenantId`, and `WorkflowStepTimeoutError.kind`;
+- `RunHandOffError`, `AssistantRunContext.saveProgress()` and `progress`.
+
+Three races are closed rather than added: a busy thread is claimed atomically, and the in-memory and
+Redis operation stores refuse a second record under a held idempotency key, as the SQL stores
+already did. The semantic cache no longer matches across tenants, and a failing response cache no
+longer fails a request.
+
 ## 2.1 stage (2.1.0)
 
 Everything 2.1 adds is stable from the start and additive: no default changes meaning.

package/CHANGELOG.md

@@ -4,6 +4,149 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-10-05
+
+Production scale and safe upgrades. Every database schema is versioned, so an upgrade applies only
+what changed, and a worker of the previous release keeps running beside the new one. A claim costs
+the same however long the queue is, routing costs the same however many models are configured, a
+circuit breaker counts every worker's failures, and work that several replicas race for is taken by
+exactly one. One tenant model reaches every store, and a deployment can check itself. Nothing
+changes until it is opted into, except races and leaks that are now closed.
+
+### Added
+
+- **Versioned migrations.** Every Postgres and SQLite adapter's schema is a list of numbered
+  `SchemaMigration`s, recorded in `nexus_schema_migrations` with a checksum. `migrate()` applies what
+  is pending, under a lock that holds through a connection pool, and refuses a migration whose
+  statements changed after it ran (`SchemaMigrationError`). Version 1 is the schema 2.0 created, so an
+  existing database is recognized as it is. `applyPostgresMigrations()`, `postgresMigrationStatus()`,
+  `postgresMigrations()`, and their SQLite twins work on any list, from `nexus-ai-pro/postgres`,
+  `nexus-ai-pro/sqlite`, and the new `nexus-ai-pro/postgres/migrations` and
+  `nexus-ai-pro/sqlite/migrations`. `PostgresMigrateOptions.transaction` runs each migration in one
+  transaction on one connection, and `postgresMigration({ record: true })` records what the script
+  creates.
+- **`nexus db status` and `nexus db migrate`**, through a module that exports your own client:
+  applied, pending, changed, and newer migrations, `--check` for a deploy step, and `--dry-run`.
+- **Indexed dispatch.** Version 2 of the Postgres and SQLite operation schemas indexes queued work by
+  age, so a claim reads the oldest few rows instead of sorting the queue, and version 3 by tenant.
+  `RedisOperationStore` takes `index: true`: queued work in a sorted set by age and leased work in one
+  by lease expiry, kept in the same Lua call as the record, with `reindex()` to index what is already
+  stored. A claim reads the same handful of records with 100,000 operations queued as with 1,000.
+- **A circuit breaker that counts across workers.** `shareObservations: true` adds each worker's
+  calls to a rolling window in the shared store, so nine failures over three workers count as nine
+  and the circuit opens on all of them. Checks stay synchronous; a worker learns the shared count on
+  its next sync. `CircuitStateStore.observe()` is implemented by the memory, Redis, and Postgres
+  stores, and `CircuitSnapshot.shared` reports the window.
+- **`PostgresRollupStore`**, on the new `nexus-ai-pro/postgres/rollups`: hourly rollups beside the
+  traces, summed in one statement so two workers adding to one hour both count.
+- **A routing index.** The auto-router plans once per configuration — candidates, allow and deny
+  lists, capability requirements as bitmasks, and strategy scores — and a request pays only for open
+  circuits and health. Over 1,000 models a warm route takes about 15 µs at p50 and 23 µs at p99.
+- **One tenant model**, on the new `nexus-ai-pro/tenancy`: a tenant's view of every store —
+  `tenantStore()`, `tenantTraceStore()`, `tenantOperationStore()`, `tenantPromptStore()` (and with it
+  the context hub), `tenantDatasetStore()`, `tenantExperimentStore()`, `tenantVectorStore()`,
+  `tenantCache()`, `tenantAssetStore()`, `tenantRollupStore()` — each implementing the store's own
+  contract over any backend, and `tenantScope()` for all of them at once. Graph runs take a
+  `tenantId`: recorded on every checkpoint, read as `context.tenantId`, scoping `context.store`, and
+  refusing another tenant's resume, continue, fork, or edit. `graphAssistant()` passes the
+  principal's tenant. Operations carry `tenantId`, and `OperationStoreFilter.tenantId` narrows queue
+  reads. Model calls are traced with their `tenantId`, so rollups count model spend per tenant, and
+  `rateLimit.key: 'tenantId'` gives each tenant its own share of a client's rate limit.
+- **Cache namespaces and outcomes.** `cache.namespace` keeps responses apart by tenant, environment,
+  model revision, and context version. Every response reports `meta.cache` — `hit`, `miss`, `stale`,
+  `bypass`, or `error`, with its layer and reason — and the request's trace records it.
+  `CompletionRequest.responseCache` skips the cache (`bypass`) or refreshes it (`refresh`).
+- **`nexus doctor`**, and `diagnose()` on the new `nexus-ai-pro/doctor`: the Node.js version,
+  optional packages, provider credentials (by name only), database connectivity and pending or
+  changed migrations, Redis, lapsed leases and a stalled queue, the registry's age, stale provider
+  health, and process-local stores behind several replicas. It exits 1 on a failure, or with
+  `--strict` on a warning.
+- **Runtime budgets.** `npm run bench:runtime`, part of the release gate, times fourteen paths — graph
+  creation, a 1,000-node compile, `Send`, checkpoints, routing at three registry sizes, a
+  20-middleware agent, traces, the event stream, server event fan-out, claims, and cache lookups —
+  as ratios to a calibration loop, so a budget holds across machines, and checks that 100,000
+  checkpoints and 10,000 runs leave the heap where it was.
+- **Workflow steps have what graph nodes have.** `timeout: { runMs, idleMs }` with
+  `context.heartbeat()`, an `onError` that decides once retries run out — recorded as `recovered`,
+  so a resume repeats neither the step nor its recovery — `stepDefaults`, a `control` that drains
+  between steps and ends in `GraphDrainedError`, and `tenantId`. A workflow the agent server serves
+  is handed off on a drain like a graph.
+- **A function assistant hands its run off on a drain**: it checks `context.control?.draining`,
+  saves how far it got with `context.saveProgress()`, and throws `RunHandOffError`; the next worker
+  reads `context.progress` and carries on.
+
+### Changed
+
+- `migrate()` on every Postgres and SQLite adapter resolves to a `MigrationResult` instead of
+  nothing, records what it applied, and loads the migration runner only when called.
+- `nexus db sql` and `postgresMigration()` include the rollups table and the new indexes by
+  default; every statement stays idempotent.
+- The root import grew by 11 KB, to 336 KB, with the routing plan, cache outcomes, and linked
+  signals; `nexus-ai-pro/graph` by 5 KB, to 78 KB, with tenant runs; and
+  `nexus-ai-pro/graph/functional` by 6 KB, to 32 KB, with step timeouts, recovery, drain, and
+  tenants.
+
+### Fixed
+
+- **Two replicas could both start a run on one busy thread.** The busy check read and wrote
+  separately. A thread is now claimed through the operation store under a unique key with
+  compare-and-set, so exactly one run proceeds and the rest meet the busy policy. An `enqueue` start
+  still busy when `queueTimeoutMs` runs out is refused instead of running beside the other.
+- **Two submissions under one idempotency key could both run** on the in-memory and Redis operation
+  stores, which overwrote the key's owner. Both now refuse a second record under a key another record
+  holds, as Postgres and SQLite do, and Redis checks and writes in one Lua call.
+- A circuit breaker's calls recorded before its shared-state module finished loading were not
+  shared.
+- **Security: the semantic response cache answered one tenant with another's response** when their
+  questions were alike, because it compared every entry regardless of tenant. A semantic match is
+  now kept to the request's tenant and cache namespace.
+- A response cache that threw failed the request, and one that failed to store an answer failed it
+  after the provider had answered. Both are now reported in `meta.cache`, and the request goes on.
+- The auto-router rebuilt the model registry for every candidate on every request: over 1,000 models
+  a request took most of a second.
+- **Memory grew with every run that shared a signal.** `AbortSignal.any()`, which composed each task
+  attempt's signal, keeps a reference per call for as long as any source lives in Node 22, so a
+  server's or a worker's long-lived signal held about 5 KB per graph run, and every client operation
+  with a deadline held one too. Signals are now linked and released when their work ends; 10,000
+  runs leave the heap within 0.3 MB of where it started, down from 52 MB.
+
+### Proof
+
+- A database created by the published 2.0.0 package upgrades with 2.2's migrations, on Postgres and
+  SQLite, and a published 2.1.0 worker and a 2.2 worker drain one queue together, nothing run twice.
+- Ten workers race one thread, one idempotency key, one queue, one tenant's slots and budget, and one
+  circuit, on every shared store, and every invariant holds.
+- A Redis claim reads the same number of records at 1,000 and 100,000 queued; Postgres and SQLite
+  plan a claim through the age index with no sort.
+- The Redis stores' Lua runs for real in the tests, in a Lua VM over an in-memory Redis.
+- The routing index decides exactly as the published 2.1.0 router on 300 random configurations, and
+  a warm route over 1,000 models stays under 100 µs at p50 and 1 ms at p99.
+- A tenant-isolation suite runs against every storage adapter — memory, Redis, Postgres, SQLite, and
+  files — and fails on any cross-tenant get, list, search, delete, fork, resume, trace query, vector
+  search, or cache hit.
+- `nexus doctor` reports each misconfiguration a fixture deployment is seeded with — an old Node.js,
+  no credentials, an old registry, pending migrations, an unreachable Redis, a lapsed lease and a
+  stalled queue, stale health, and memory stores behind three replicas — and passes it once fixed.
+- A workflow and a function assistant are each drained on one worker and finished on the next, with
+  every step and every item run exactly once.
+
+### Not in this release, and why
+
+- **The migration lock is a row with a lease, not a session advisory lock.** A session lock does not
+  hold through a connection pool or a serverless driver, where each statement may reach another
+  connection; a lease row does, everywhere. Without a `transaction` function, statements run one at a
+  time, which is safe because every bundled statement is idempotent.
+- **The Redis dispatch index is opt-in**, since a 2.1 worker writes records without index entries;
+  `stats()` on Redis still reads every record.
+- **Consecutive failures across workers are counted as failures since any worker's last success.**
+  Calls are reported in batches, so two workers' failures and successes in the same second may be
+  ordered differently than they happened.
+- **Tenant views scope by prefix and stamp, not by a column**, so they work over every backend
+  unchanged; data written before a view was used is not the tenant's until it is copied under its
+  prefix.
+- **Runtime budgets compare ratios to a calibration loop**, which catches a cliff, not a 10% drift;
+  the tolerance is three times the recorded ratio.
+
 ## [2.1.0] - 2026-10-04
 
 Fault-tolerant graphs and crash-safe observability. A graph now chooses when its checkpoints are
@@ -1494,7 +1637,8 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.1.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.2.0...HEAD
+[2.2.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.25.0...v2.0.0
 [1.25.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.24.0...v1.25.0

package/README.md

@@ -8,12 +8,12 @@ team can share.
 Import only what you use. The root import is the client and nothing else, and every other capability
 has its own entry point with a size budget CI enforces; [the packaging guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/packaging.md)
 publishes what each one costs. The package has no required dependencies: a graph-only application
-loads 73 KB, and installs nothing but this package.
+loads 78 KB, and installs nothing but this package.
 
 - NPM: https://www.npmjs.com/package/nexus-ai-pro
 - GitHub: https://github.com/mkhitar-abrahamyan/nexus-ai
 - Contributing, testing, and release procedure: [CONTRIBUTING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/CONTRIBUTING.md)
-- Delivered work and what is planned next: [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md)
+- What is planned next: [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md)
 - For AI assistants: [llms.txt](https://raw.githubusercontent.com/mkhitar-abrahamyan/nexus-ai/main/llms.txt) indexes every guide, and [llms-full.txt](https://raw.githubusercontent.com/mkhitar-abrahamyan/nexus-ai/main/llms-full.txt) holds them all in one file
 
 ## Install
@@ -158,6 +158,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Studio](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/studio.md) | A shared UI for traces, threads, approvals, experiments, prompts, deployments, costs, and health, as a separate package |
 | [Agent server](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/server.md) | Self-hosted HTTP server for assistants: threads, durable runs, resumable streams, cron, a worker queue, and metrics |
 | [Deployments](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/deployments.md) | Revisions and canaries with automatic rollback, autoscaling on Kubernetes and Helm, and per-tenant limits |
+| [Tenancy](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/tenancy.md) | One tenant model: a tenant's view of every store, tenant graph runs, and the isolation suite |
 | [Workflows](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/workflows.md) | Ready-made chains and domain workflows |
 | [Command line](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/cli.md) | The `nexus` command |
 | [Packaging and install weight](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/packaging.md) | Every entry point and what it costs |
@@ -200,7 +201,8 @@ npm run check:release
 
 `check` runs formatting and lint gates, source/test/example type checks, the build, unit and mock
 conformance tests, coverage thresholds, package import checks, and an external type-consumer test.
-`check:release` additionally verifies the dry-run tarball and a clean packed-package install.
+`check:release` additionally holds the scheduling and runtime budgets — speed against a calibration
+loop, and memory by retention — and verifies the dry-run tarball and a clean packed-package install.
 
 `npm run docs:check` fails when any public export, or any public member of an exported class,
 interface, or enum, has no doc comment, and `npm run docs:guides` fails when a guide does not name
@@ -216,8 +218,8 @@ npm run test:vectors:live
 
 ## Roadmap
 
-See [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) for what has
-shipped and what is planned. It is a design proposal, not a compatibility promise; the guarantees
+See [ROADMAP.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) for what is
+planned, and [CHANGELOG.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/CHANGELOG.md) for what has shipped. It is a design proposal, not a compatibility promise; the guarantees
 live in [API_STABILITY.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/API_STABILITY.md).
 
 Shipped so far:
@@ -246,12 +248,15 @@ Shipped so far:
   every provider;
 - 2.1 fault tolerance and crash-safe observability: checkpoints written on your terms, recovery after
   retries, idle timeouts and a clean drain, traces that survive a crash and reach any OpenTelemetry
-  backend, one event stream, and dashboard rollups.
+  backend, one event stream, and dashboard rollups;
+- 2.2 production scale and safe upgrades: versioned database migrations, queue claims and routing
+  that cost the same at any size, a circuit breaker that counts across workers, one tenant model
+  across every store, and `nexus doctor` to check a deployment before it serves traffic.
 
 Upgrading from 1.x: `npx nexus migrate src --write` moves your imports, and
 [MIGRATING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/MIGRATING.md) covers the rest.
-Next, 2.2 removes the scaling cliffs the guides document: versioned database migrations, indexed
-queue dispatch, a circuit breaker that counts across workers, a routing index, and one tenant model. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
+Next, 2.3 gives agents a real security boundary — capabilities, permissions, and a sandbox contract —
+with a complete middleware catalog, and retrieval that works at production scale. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
 releases after it.
 
 ## Before Production

package/dist/cache/memory-cache.d.ts

@@ -15,6 +15,14 @@ export declare class MemoryCache<T> {
     constructor(maxEntries?: number);
     /** Returns a value, or `undefined` for a miss or an expired entry. A hit counts as recent use. */
     get(key: string): T | undefined;
+    /**
+     * Like `get()`, also saying whether an entry was there but had expired, which a caller can report
+     * as stale rather than missing. The expired entry is removed either way.
+     */
+    lookup(key: string): {
+        value?: T;
+        stale: boolean;
+    };
     /** Stores a value. Defaults to 5 minutes. */
     set(key: string, value: T, ttlSeconds?: number): void;
     /** Removes every entry. */

package/dist/cache/memory-cache.js

@@ -16,6 +16,15 @@ export class MemoryCache {
         this.entries.set(key, entry);
         return entry.value;
     }
+    lookup(key) {
+        const entry = this.entries.get(key);
+        if (entry && entry.expiresAt < Date.now()) {
+            this.entries.delete(key);
+            return { stale: true };
+        }
+        const value = this.get(key);
+        return value === undefined ? { stale: false } : { value, stale: false };
+    }
     set(key, value, ttlSeconds = 300) {
         if (this.entries.size >= this.maxEntries) {
             const oldest = this.entries.keys().next().value;

package/dist/cache/semantic-cache.d.ts

@@ -25,10 +25,13 @@ export declare class SemanticCache {
     constructor(options?: SemanticCacheOptions);
     /**
      * The cached response for the most similar earlier request above the threshold, or `undefined`.
+     * Only entries stored under the same `scope` are compared: the client passes the request's tenant
+     * and cache namespace, so one tenant is never answered from another's entry however alike the
+     * questions are.
      */
-    get(request: CompletionRequest): Promise<NexusResponse | undefined>;
-    /** Caches a response under its request's embedding. */
-    set(key: string, request: CompletionRequest, response: NexusResponse): Promise<void>;
+    get(request: CompletionRequest, scope?: string): Promise<NexusResponse | undefined>;
+    /** Caches a response under its request's embedding, in a `scope` lookups must match. */
+    set(key: string, request: CompletionRequest, response: NexusResponse, scope?: string): Promise<void>;
     /** Removes every entry. */
     clear(): void;
 }

package/dist/cache/semantic-cache.js

@@ -7,7 +7,7 @@ export class SemanticCache {
         this.options = options;
         this.embed = options.embed || createHashEmbeddings;
     }
-    async get(request) {
+    async get(request, scope = '') {
         if (!this.options.enabled)
             return undefined;
         const text = requestToSearchText(request);
@@ -17,6 +17,8 @@ export class SemanticCache {
         let best;
         this.entries = this.entries.filter((entry) => entry.expiresAt > now);
         for (const entry of this.entries) {
+            if (entry.scope !== scope)
+                continue;
             const score = cosineSimilarity(embedding, entry.embedding);
             if (score >= threshold && (!best || score > best.score)) {
                 best = { entry, score };
@@ -37,7 +39,7 @@ export class SemanticCache {
             },
         };
     }
-    async set(key, request, response) {
+    async set(key, request, response, scope = '') {
         if (!this.options.enabled)
             return;
         const text = requestToSearchText(request);
@@ -47,6 +49,7 @@ export class SemanticCache {
             this.entries.shift();
         this.entries.push({
             key,
+            scope,
             text,
             embedding,
             response,

package/dist/cli/args.js

@@ -5,12 +5,15 @@ export const BOOLEAN_FLAGS = new Set([
     'allow-dataset-mismatch',
     'check',
     'densify',
+    'dry-run',
     'fail',
     'fail-on-regression',
     'help',
     'json',
     'print',
+    'record',
     'reveal-values',
+    'strict',
     'write',
 ]);
 export function parseArgs(args) {

package/dist/cli/db.d.ts

@@ -1,8 +1,20 @@
 import { type ParsedArgs } from './args.js';
 /**
- * `nexus db sql` prints the Postgres schema for the chosen adapters.
+ * `nexus db sql | status | migrate`.
  *
- * Printed rather than applied, so the CLI needs no database driver and the schema goes through
- * whatever review and migration tooling the application already has: `nexus db sql | psql "$URL"`.
+ * `sql` prints the Postgres schema, so the CLI needs no driver and the schema can go through the
+ * application's own review and tooling: `nexus db sql | psql "$URL"`. `status` and `migrate` reach
+ * the database through a module the application writes, which exports its own client:
+ *
+ * ```js
+ * // db.mjs
+ * import pg from 'pg';
+ * export const client = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+ * export const close = () => client.end();
+ * ```
+ *
+ * The module may also export `dialect` (`postgres` or `sqlite`), a `transaction` function (see
+ * `PostgresMigrateOptions`), and `migrations`, a list replacing the bundled ones, for stores on
+ * custom tables.
  */
-export declare function runDbCommand(subcommand: string | undefined, { flags }: ParsedArgs): Promise<void>;
+export declare function runDbCommand(subcommand: string | undefined, args: ParsedArgs): Promise<void>;

package/dist/cli/db.js

@@ -1,28 +1,175 @@
-import { postgresMigration } from '../postgres/index.js';
-import { CliUsageError, listFlag, numberFlag } from './args.js';
-const ADAPTERS = [
-    'operations',
-    'store',
-    'traces',
-    'evaluation',
-    'circuits',
-    'prompts',
-    'vectors',
-];
-export async function runDbCommand(subcommand, { flags }) {
-    if (subcommand !== 'sql')
-        throw new CliUsageError(`Unknown db command "${subcommand ?? ''}". Use sql.`);
-    const adapters = listFlag(flags, 'adapters');
-    const unknown = adapters?.filter((adapter) => !ADAPTERS.includes(adapter));
-    if (unknown?.length) {
-        throw new CliUsageError(`Unknown adapter ${unknown.join(', ')}. Choose from ${ADAPTERS.join(', ')}.`);
-    }
+import { POSTGRES_ADAPTERS, postgresMigration, postgresMigrations } from '../postgres/index.js';
+import { CliUsageError, flagBool, listFlag, loadModule, numberFlag, printTable, stringFlag, writeJson, } from './args.js';
+const SQLITE_ADAPTERS = ['operations', 'store', 'vectors'];
+export async function runDbCommand(subcommand, args) {
+    if (subcommand === 'sql')
+        return printSql(args);
+    if (subcommand === 'status' || subcommand === 'migrate')
+        return withDatabase(subcommand, args);
+    throw new CliUsageError(`Unknown db command "${subcommand ?? ''}". Use sql, status, or migrate.`);
+}
+function printSql({ flags }) {
+    const adapters = postgresAdapters(flags);
     const vectorDimensions = numberFlag(flags, 'vector-dimensions');
-    if (adapters?.includes('vectors') && vectorDimensions === undefined) {
-        throw new CliUsageError('The vectors adapter needs --vector-dimensions.');
-    }
     process.stdout.write(postgresMigration({
         ...(adapters ? { adapters } : {}),
         ...(vectorDimensions === undefined ? {} : { vectorDimensions }),
+        ...(flagBool(flags, 'record') ? { record: true } : {}),
     }));
 }
+function postgresAdapters(flags) {
+    const adapters = listFlag(flags, 'adapters');
+    const unknown = adapters?.filter((adapter) => !POSTGRES_ADAPTERS.includes(adapter));
+    if (unknown?.length) {
+        throw new CliUsageError(`Unknown adapter ${unknown.join(', ')}. Choose from ${POSTGRES_ADAPTERS.join(', ')}.`);
+    }
+    if (adapters?.includes('vectors') && numberFlag(flags, 'vector-dimensions') === undefined) {
+        throw new CliUsageError('The vectors adapter needs --vector-dimensions.');
+    }
+    return adapters;
+}
+async function withDatabase(command, { flags }) {
+    const location = stringFlag(flags, 'client');
+    if (!location)
+        throw new CliUsageError(`nexus db ${command} needs --client <db.mjs>, a module exporting \`client\`.`);
+    const database = await openDatabase(location, stringFlag(flags, 'dialect'));
+    try {
+        const migrations = database.migrations ?? (await bundledMigrations(database.dialect, flags));
+        const table = stringFlag(flags, 'table');
+        if (command === 'status') {
+            const status = await statusOf(database, migrations, table);
+            if (flagBool(flags, 'json'))
+                writeJson(status);
+            else
+                printStatus(status);
+            if (flagBool(flags, 'check') && !status.current)
+                process.exitCode = 1;
+            return;
+        }
+        const result = await migrate(database, migrations, { dryRun: flagBool(flags, 'dry-run'), table });
+        if (flagBool(flags, 'json'))
+            writeJson(result);
+        else
+            printResult(result);
+    }
+    finally {
+        await database.close?.();
+    }
+}
+async function openDatabase(location, dialectFlag) {
+    const loaded = await loadModule(location);
+    const client = loaded.client ?? loaded.default;
+    if (!client || typeof client !== 'object') {
+        throw new CliUsageError(`${location} must export a database client as \`client\`.`);
+    }
+    const candidate = client;
+    const dialect = (dialectFlag ?? loaded.dialect);
+    const detected = dialect ??
+        (typeof candidate.query === 'function'
+            ? 'postgres'
+            : typeof candidate.prepare === 'function' || typeof candidate.exec === 'function'
+                ? 'sqlite'
+                : undefined);
+    if (detected !== 'postgres' && detected !== 'sqlite') {
+        throw new CliUsageError(`${location} exports a client this CLI cannot recognize. Export \`dialect\` as "postgres" or "sqlite".`);
+    }
+    return {
+        dialect: detected,
+        client,
+        ...(typeof loaded.transaction === 'function'
+            ? { transaction: loaded.transaction }
+            : {}),
+        ...(Array.isArray(loaded.migrations) ? { migrations: loaded.migrations } : {}),
+        ...(typeof loaded.close === 'function' ? { close: loaded.close } : {}),
+    };
+}
+async function bundledMigrations(dialect, flags) {
+    if (dialect === 'postgres') {
+        const adapters = postgresAdapters(flags);
+        const vectorDimensions = numberFlag(flags, 'vector-dimensions');
+        return postgresMigrations({
+            ...(adapters ? { adapters } : {}),
+            ...(vectorDimensions === undefined ? {} : { vectorDimensions }),
+        });
+    }
+    const adapters = listFlag(flags, 'adapters');
+    const unknown = adapters?.filter((adapter) => !SQLITE_ADAPTERS.includes(adapter));
+    if (unknown?.length) {
+        throw new CliUsageError(`Unknown SQLite adapter ${unknown.join(', ')}. Choose from ${SQLITE_ADAPTERS.join(', ')}.`);
+    }
+    const { sqliteMigrations } = await import('../sqlite/index.js');
+    return sqliteMigrations(adapters ? { adapters } : {});
+}
+async function statusOf(database, migrations, table) {
+    const options = table ? { table } : {};
+    if (database.dialect === 'postgres') {
+        const { postgresMigrationStatus } = await import('../postgres/migrations.js');
+        return postgresMigrationStatus(database.client, migrations, options);
+    }
+    const { sqliteMigrationStatus } = await import('../sqlite/migrations.js');
+    return sqliteMigrationStatus(database.client, migrations, options);
+}
+async function migrate(database, migrations, options) {
+    const common = { dryRun: options.dryRun, ...(options.table ? { table: options.table } : {}) };
+    if (database.dialect === 'postgres') {
+        const { applyPostgresMigrations } = await import('../postgres/migrations.js');
+        return applyPostgresMigrations(database.client, migrations, {
+            ...common,
+            ...(database.transaction ? { transaction: database.transaction } : {}),
+        });
+    }
+    const { applySqliteMigrations } = await import('../sqlite/migrations.js');
+    return applySqliteMigrations(database.client, migrations, common);
+}
+function printStatus(status) {
+    const changed = new Set(status.changed.map(({ migration }) => `${migration.component}@${migration.version}`));
+    const rows = [
+        ...status.applied
+            .filter((row) => !status.unknown.includes(row))
+            .map((row) => {
+            const key = `${row.component}@${row.version}`;
+            return {
+                component: row.component,
+                version: String(row.version),
+                name: row.name,
+                state: changed.has(key) ? 'changed' : 'applied',
+                applied: row.appliedAt,
+            };
+        }),
+        ...status.unknown.map((row) => ({
+            component: row.component,
+            version: String(row.version),
+            name: row.name,
+            state: 'newer release',
+            applied: row.appliedAt,
+        })),
+        ...status.pending.map((migration) => ({
+            component: migration.component,
+            version: String(migration.version),
+            name: migration.name,
+            state: 'pending',
+            applied: '',
+        })),
+    ];
+    if (rows.length === 0) {
+        console.log('No migrations known or recorded.');
+        return;
+    }
+    printTable(rows, ['component', 'version', 'name', 'state', 'applied']);
+    console.log(status.current
+        ? '\nUp to date.'
+        : `\n${status.pending.length} pending${status.changed.length ? `, ${status.changed.length} changed after they ran` : ''}. Run: nexus db migrate`);
+}
+function printResult(result) {
+    if (result.applied.length === 0) {
+        console.log('Nothing to apply: the database is up to date.');
+        return;
+    }
+    const verb = result.dryRun ? 'Would apply' : 'Applied';
+    for (const migration of result.applied)
+        console.log(`${verb} ${migration.component} v${migration.version}: ${migration.name}`);
+    if (result.dryRun) {
+        console.log('\n-- The statements, in order:\n');
+        console.log(`${result.statements.join(';\n\n')};`);
+    }
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,17 @@
+import { type ParsedArgs } from './args.js';
+/**
+ * `nexus doctor` checks a deployment and exits 1 when a check fails, or with `--strict` when one
+ * warns. Without `--module` it checks what it can see from the shell: Node.js, packages, credentials,
+ * and the model registry. A module reaches the rest, exporting any of:
+ *
+ * ```js
+ * // doctor.mjs
+ * export const database = { client: pool };       // or `client` alone, as for nexus db
+ * export const redis = new Redis(process.env.REDIS_URL);
+ * export const operations = new PostgresOperationStore(pool);
+ * export const ai = client;
+ * export const deployment = { replicas: 3, stores: { checkpointer, state, tenantUsage } };
+ * export const close = async () => { await pool.end(); redis.disconnect(); };
+ * ```
+ */
+export declare function runDoctorCommand({ flags }: ParsedArgs): Promise<void>;