nexus-ai-pro 2.20.2 → 2.21.0

package/API_STABILITY.md

@@ -67,6 +67,36 @@ graduation:
 | Upgrade | A migration test from the previous minor |
 | Soak | A long-running test with flat memory and no leaked handles |
 
+## 2.21 stage (2.21.0)
+
+Everything 2.21 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable, in `nexus-ai-pro/decisions`: `BoxQuestion`, `BoxAnswer`, `DecisionBox`, `boxOverlap()`,
+`statePictures()`, `readPicture()`, `DecisionPicture`, `ReadDecisionPicture`, the question type `box`
+and its `DecisionDistribution`, `DecisionProviderCapabilities.images`, `answeredRight()`'s box and
+`overlap`, `DecisionEvaluatorOptions.where` and `overlap`, `DecisionConformanceOptions.picture`,
+`DecisionConformanceReport.skipped`, and `CompletionDecisionsOptions.images`; in
+`nexus-ai-pro/decisions/typesafe`, `TypeSafeDecisionProviderOptions.media`; in `nexus-ai-pro/adapter-kit`,
+`gatherRecords()`, `GatherRecordsOptions`, `GatherReport`, `GatheredSource`, `GatherOutcome`,
+`RecordSource`, and `ADAPTER_KEYWORD`; the command `nexus adapters gather`; a package's
+`nexus.compatibility` field, the URL of its record; in `nexus-ai-pro/config`, `useDefaults()`,
+`nexusDefaults()`, `NexusDefaults`, `DEFAULT_CHANGES`, and `DefaultChange`, and the `NEXUS_DEFAULTS`
+variable; `DoctorOptions.upgrade` and `nexus doctor --upgrade`; and `TraceStore.durable`. The
+preview turns on exactly what 3.0 will; should 3.0 change its defaults again before it ships, the
+preview follows, and `DEFAULT_CHANGES` says so. A box from TypeSafe AI rests
+on what it marks as experimental, its pictures and boxes, whose request format may change between its
+releases.
+
+Changed on purpose: TypeSafe AI's 400 and 413 are `DECISION_INVALID`, not `DECISION_FAILED`; neither
+was retried before or is now. A provider of your own that reads pictures declares `images: true`;
+without it, a decision about a picture is not sent to it. A union over `DecisionQuestionType` or
+`DecisionAnswer` that handled three kinds now meets a fourth, `box`. `compatibilityPage()` writes a
+repository that is not an `http` or `https` address as text, not a link, and escapes a record's
+Markdown. A doctor report has one more check, `upgrade`, skipped unless asked for. With `tenants`, an
+A2A handler answers `/{tenant}/.well-known/agent-card.json` with that tenant's card, where it answered
+the card itself; without `tenants`, nothing changes. A model on OpenAI's Responses API is sent
+`include` and `top_logprobs` when a request asks for log probabilities, which it was not before.
+
 ## 2.20 stage (2.20.0)
 
 Everything 2.20 adds is stable from the start and additive, unless this section says otherwise.

package/CHANGELOG.md

@@ -4,6 +4,80 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.21.0] - 2026-10-26
+
+Typed decisions about pictures, compatibility records gathered from community adapters' own CI, and
+3.0's defaults behind one switch today; with log probabilities from OpenAI's Responses API, and a card
+of its own for each tenant of an A2A agent.
+
+### Added
+
+- **Decisions about pictures.** A decision's state may hold pictures, as image parts or image assets
+  anywhere in it, and a question names each by its path in backticks, such as `photo` or
+  `frames[2].frame`. Every question type may ask about one, and a new `box` question, `BoxQuestion`,
+  asks where something is: its `BoxAnswer` is a `DecisionBox` of four edges, each a fraction of the
+  picture's height or width, with a confidence. `boxOverlap()` measures how far two boxes overlap,
+  `answeredRight()` counts a box right at half or more, `calibrate()` chooses a box's threshold as any
+  answer's, and `decisionEvaluator()` scores a box against `where` the thing is. `statePictures()`
+  lists a state's pictures and `readPicture()` reads one with the media family's readers.
+- TypeSafe AI's Jev is sent a state's pictures as the API's assets, each under a new reference, with
+  the `TypeSafe-Danger-Zone-Images` header that pictures and boxes require, and answers boxes on Jev 1.14
+  and later. A picture it would refuse, outside PNG or JPEG, animated, over 16 MiB, or outside 280 to
+  1,568 pixels a side, or a request over 32 MiB, is refused first, naming the picture's path.
+  `TypeSafeDecisionProviderOptions.media` reads pictures held by file, URL, or stored asset.
+- `completionDecisions()` shows a vision model the pictures a state holds, each labelled by its path,
+  and reads a box as the median of several samples, its confidence how far they agree; `images: false`
+  marks a text-only model.
+- `DecisionProviderCapabilities.images`: a provider that does not read pictures is refused a decision
+  about one, and passed over as a fallback. The mock reads pictures and answers boxes.
+- `DecisionConformanceOptions.picture` runs the conformance checks of pictures and boxes, and
+  `DecisionConformanceReport.skipped` lists the checks that could not run, rather than passing them.
+- **Compatibility records from community CI.** An adapter's own CI publishes its sealed record at the
+  URL its package names as `nexus.compatibility`, beside the keyword `nexus-ai-pro-adapter`.
+  `nexus adapters gather`, and `gatherRecords()` in `nexus-ai-pro/adapter-kit`, find those packages on
+  npm, fetch each record, and keep only those whose digest matches and that name their own package,
+  from HTTPS; a source that is down keeps its last record, and a package that no longer names one
+  leaves the page. Nothing an adapter publishes is run. A daily `Community compatibility` workflow
+  writes the page, with the adapters this repository ships, to the `compatibility` branch, where a
+  record that says its adapter fails turns it red. `compatibility/sources.json` lists adapters not
+  on npm.
+
+- **A preview of 3.0's defaults.** `useDefaults('3.0')`, from `nexus-ai-pro/config`, or
+  `NEXUS_DEFAULTS=3.0`, turns on the three settings 2.x keeps opt-in, as 3.0 will: incremental tracing on
+  a durable trace store, the Redis operation store's dispatch index where the client can keep it, and
+  `hash-v2` for a deployment first recorded. An option set explicitly wins, and without the switch
+  nothing changes. `DEFAULT_CHANGES` lists each, with what to do first; `nexusDefaults()` says which
+  defaults are in effect; and `nexus doctor --upgrade 3.0`, `DoctorOptions.upgrade`, says what 3.0
+  would change for a deployment. `TraceStore.durable` marks a store whose runs live only in the
+  process, as `MemoryTraceStore`'s.
+
+- OpenAI's models on the Responses API, such as `gpt-5.5-pro`, report token log probabilities when a
+  request asks for them, as its chat models do: the request includes `message.output_text.logprobs`
+  with up to 20 alternatives a token, and each text part's are read back. A typed decision asked of
+  one is read from them in one call, rather than sampled; a model that refuses them is still sampled.
+
+- With `tenants`, an A2A handler serves each tenant a card of its own at
+  `/{tenant}/.well-known/agent-card.json`, every interface naming the tenant, so a client that reads it,
+  such as the A2A project's reference client, calls as that tenant over each binding. The nightly
+  interoperability run drives a tenant through `@a2a-js/sdk` over JSON-RPC, HTTP+JSON, and gRPC, and
+  checks that a tenant it may not act for, and a call naming none, are refused.
+
+### Fixed
+
+- The compatibility page writes a record as text: an adapter links to its repository only at an
+  `http` or `https` address, so a record naming `javascript:` makes no link on the HTML page; a
+  record's line breaks, pipes, brackets, and stars no longer break or add to the Markdown; and the
+  HTML page colours each row by its state.
+
+### Changed
+
+- TypeSafe AI's 400 and 413 refuse a decision as `DECISION_INVALID`, as a 422 does, rather than
+  failing it as `DECISION_FAILED`: the request, such as a picture, is what was refused. Neither is
+  retried.
+- A decision's trace and cache key hold a digest of each picture in its place, never its bytes, and the
+  budget holds a picture at 1,600 tokens rather than reading its base64 as text.
+- A doctor report has one more check, `upgrade`, skipped unless `upgrade` asks about a release.
+
 ## [2.20.2] - 2026-10-24
 
 The first published release of 2.20. The package is 2.20.0's: the publishes of 2.20.0 and 2.20.1
@@ -3287,7 +3361,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.20.2...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.21.0...HEAD
+[2.21.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.20.2...v2.21.0
 [2.20.2]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.20.1...v2.20.2
 [2.20.1]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.20.0...v2.20.1
 [2.20.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.19.0...v2.20.0

package/README.md

@@ -338,15 +338,16 @@ Shipped so far:
   a person when it is not;
 - 2.20 tools read from a service's own OpenAPI document, which an agent calls or an emulator plays,
   an emulator that holds what a whole evaluation did so examples that build on each other are
-  evaluated with nothing sent, and one A2A handler serving many tenants, each seeing only its own.
+  evaluated with nothing sent, and one A2A handler serving many tenants, each seeing only its own;
+- 2.21 typed decisions about pictures, a yes or no, a choice, a score, or a box around something in
+  one, from TypeSafe AI's Jev or any vision model; community adapters' compatibility records gathered
+  from their own CI, a failing one turning red; and 3.0's defaults behind one switch today.
 
 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.21 asks typed decisions about pictures, and gathers community adapters' compatibility
-records from their own CI.
-Pinecone, images, the Gemini
-embedding batch tier, media understanding, video, Gemini Live, SIP, and both phone providers
-graduate once the live workflow passes against each. The
+Next, in 2.22, Pinecone, images, the Gemini embedding batch tier, media understanding, video, typed
+decisions, Gemini Live, SIP, and both phone providers graduate once the live workflow passes against
+each. The
 [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists what comes after, in the order
 applications ask for it.
 

package/dist/adapter-kit/gather.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Compatibility records gathered from where adapters' own CI publishes them: packages found on npm by
+ * a keyword, each naming its record's URL in its `package.json`, and sources listed by hand. Each
+ * record is read as `nexus adapters verify` sealed it, and must name the package that points to it.
+ * Nothing an adapter publishes is run: a gathered record is listed as its CI recorded it.
+ */
+import { type CompatibilityRecord } from './record.js';
+/** The npm keyword an adapter package carries to be found: `nexus-ai-pro-adapter`. */
+export declare const ADAPTER_KEYWORD = "nexus-ai-pro-adapter";
+/** Where one adapter's CI publishes its record. */
+export interface RecordSource {
+    /** The adapter's package name, which its record must name. */
+    package: string;
+    /** The record's URL: HTTPS, or HTTP to this machine. */
+    url: string;
+}
+/** Options for `gatherRecords()`. */
+export interface GatherRecordsOptions {
+    /**
+     * The keyword adapter packages are found by on npm, each naming its record's URL as
+     * `nexus.compatibility` in its `package.json`. Defaults to `ADAPTER_KEYWORD`; `false` finds none.
+     */
+    keyword?: string | false;
+    /** Sources listed by hand, beside those found; a listed package's URL is used over its own. */
+    sources?: readonly RecordSource[];
+    /** The npm registry. Defaults to `https://registry.npmjs.org`. */
+    registry?: string;
+    /**
+     * The records gathered last time: a package whose record cannot be read now, because its source is
+     * down or what it serves is refused, keeps its last one, and says why.
+     */
+    previous?: readonly CompatibilityRecord[];
+    /** The most bytes a record may have. Defaults to 1 MiB. */
+    maxBytes?: number;
+    /** How long each request may take, in milliseconds. Defaults to 15 seconds. */
+    timeoutMs?: number;
+    /** The most packages found by keyword. Defaults to 1,000. */
+    maxPackages?: number;
+    /** Replaces the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/**
+ * What became of one package's record: `gathered` now; `kept` from last time, as now it could not be;
+ * `refused` or `unreachable` with nothing to keep; or `undeclared`, a package that names no record.
+ */
+export type GatherOutcome = 'gathered' | 'kept' | 'refused' | 'unreachable' | 'undeclared';
+/** One package's source, and what became of its record. */
+export interface GatheredSource {
+    /** The package's name. */
+    package: string;
+    /** Where its record is published, when it says. */
+    url?: string;
+    /** What became of it. */
+    outcome: GatherOutcome;
+    /** Why, for every outcome but `gathered`. */
+    detail?: string;
+    /** The record listed for it: gathered now, or kept. */
+    record?: CompatibilityRecord;
+}
+/** What `gatherRecords()` found. */
+export interface GatherReport {
+    /** Every record to list, gathered now or kept, by package name. */
+    records: CompatibilityRecord[];
+    /** Every package, by name, and what became of its record. */
+    sources: GatheredSource[];
+}
+/**
+ * Gathers the compatibility records adapters' own CI publishes: finds adapter packages on npm by
+ * `keyword`, reads where each publishes its record, and fetches each, with `sources` listed by hand.
+ * A record is gathered only when it reads as sealed, with a digest that matches it, and names the
+ * package that points to it; a package whose record cannot be read now keeps its `previous` one.
+ * Throws when npm cannot be searched, rather than reporting every adapter gone.
+ */
+export declare function gatherRecords(options?: GatherRecordsOptions): Promise<GatherReport>;
+/** The name of a package from how a record names it, such as `@acme/nexus-milvus` from `@acme/nexus-milvus@0.3.0`. */
+export declare function packageName(specifier: string): string;

package/dist/adapter-kit/gather.js

@@ -0,0 +1,147 @@
+import { readCompatibilityRecord } from './record.js';
+export const ADAPTER_KEYWORD = 'nexus-ai-pro-adapter';
+export async function gatherRecords(options = {}) {
+    const request = options.fetch ?? fetch;
+    const registry = (options.registry ?? 'https://registry.npmjs.org').replace(/\/+$/, '');
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const maxBytes = options.maxBytes ?? 1024 * 1024;
+    const get = (url) => request(url, { signal: AbortSignal.timeout(timeoutMs), redirect: 'follow' });
+    const found = new Map();
+    const keyword = options.keyword === undefined ? ADAPTER_KEYWORD : options.keyword;
+    if (keyword) {
+        for (const name of await search(get, registry, keyword, options.maxPackages ?? 1_000))
+            found.set(name, undefined);
+    }
+    for (const source of options.sources ?? [])
+        found.set(source.package, source.url);
+    const previous = new Map();
+    for (const record of options.previous ?? []) {
+        const name = record.adapter.package ? packageName(record.adapter.package) : undefined;
+        if (name)
+            previous.set(name, record);
+    }
+    const sources = [];
+    for (const name of [...found.keys()].sort()) {
+        const listed = found.get(name);
+        const result = await gatherOne(name, listed, { get, registry, maxBytes });
+        const last = previous.get(name);
+        if ((result.outcome === 'refused' || result.outcome === 'unreachable') && last) {
+            sources.push({ ...result, outcome: 'kept', record: last, detail: `${result.outcome}: ${result.detail}` });
+        }
+        else
+            sources.push(result);
+    }
+    return {
+        records: sources.flatMap((source) => (source.record ? [source.record] : [])),
+        sources,
+    };
+}
+export function packageName(specifier) {
+    const at = specifier.lastIndexOf('@');
+    return at > 0 ? specifier.slice(0, at) : specifier;
+}
+async function search(get, registry, keyword, limit) {
+    const names = [];
+    for (let from = 0; names.length < limit;) {
+        const url = `${registry}/-/v1/search?text=keywords:${encodeURIComponent(keyword)}&size=250&from=${from}`;
+        let page;
+        try {
+            const response = await get(url);
+            if (!response.ok)
+                throw new Error(`it answered ${response.status}`);
+            page = (await response.json());
+        }
+        catch (error) {
+            throw new Error(`npm could not be searched for "${keyword}": ${message(error)}`);
+        }
+        const objects = page.objects ?? [];
+        for (const item of objects)
+            if (typeof item.package?.name === 'string')
+                names.push(item.package.name);
+        from += objects.length;
+        if (objects.length === 0 || from >= (page.total ?? 0))
+            break;
+    }
+    return [...new Set(names)].slice(0, limit);
+}
+async function gatherOne(name, listed, context) {
+    let url = listed;
+    if (url === undefined) {
+        try {
+            const response = await context.get(`${context.registry}/${name.replace('/', '%2f')}/latest`);
+            if (!response.ok)
+                return { package: name, outcome: 'unreachable', detail: `npm answered ${response.status}` };
+            const manifest = (await response.json());
+            const declared = manifest.nexus?.compatibility;
+            if (typeof declared !== 'string' || !declared.trim()) {
+                return { package: name, outcome: 'undeclared', detail: 'its package.json names no nexus.compatibility record' };
+            }
+            url = declared.trim();
+        }
+        catch (error) {
+            return { package: name, outcome: 'unreachable', detail: `npm could not be read: ${message(error)}` };
+        }
+    }
+    if (!allowed(url))
+        return { package: name, url, outcome: 'refused', detail: `${url} is not HTTPS` };
+    let text;
+    try {
+        const response = await context.get(url);
+        if (response.url && !allowed(response.url)) {
+            return {
+                package: name,
+                url,
+                outcome: 'refused',
+                detail: `${url} redirects to ${response.url}, which is not HTTPS`,
+            };
+        }
+        if (!response.ok)
+            return { package: name, url, outcome: 'unreachable', detail: `${url} answered ${response.status}` };
+        const declared = Number(response.headers.get('content-length') ?? 0);
+        if (declared > context.maxBytes)
+            return tooLarge(name, url, declared, context.maxBytes);
+        text = await response.text();
+    }
+    catch (error) {
+        return { package: name, url, outcome: 'unreachable', detail: `${url} could not be read: ${message(error)}` };
+    }
+    const size = new TextEncoder().encode(text).length;
+    if (size > context.maxBytes)
+        return tooLarge(name, url, size, context.maxBytes);
+    let record;
+    try {
+        record = readCompatibilityRecord(text);
+    }
+    catch (error) {
+        return { package: name, url, outcome: 'refused', detail: message(error) };
+    }
+    const named = record.adapter.package;
+    if (!named)
+        return { package: name, url, outcome: 'refused', detail: 'the record names no package' };
+    if (packageName(named) !== name) {
+        return { package: name, url, outcome: 'refused', detail: `the record names ${named}, not ${name}` };
+    }
+    return { package: name, url, outcome: 'gathered', record };
+}
+function allowed(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol === 'https:')
+            return true;
+        return parsed.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(parsed.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function tooLarge(name, url, size, limit) {
+    return {
+        package: name,
+        url,
+        outcome: 'refused',
+        detail: `the record is ${size} bytes, over the ${limit}-byte limit`,
+    };
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/adapter-kit/index.d.ts

@@ -20,6 +20,7 @@ import { type AdapterErrorClass } from './errors.js';
 import { type CompatibilityRecord, type CompatibilityRecordOptions } from './record.js';
 export { ADAPTER_CONTRACTS, ADAPTER_FIXTURE_PASSAGES, type AdapterCheck, type AdapterContract, type AdapterContractVersion, type RetrieverCapabilities, type RetrieverContractOptions, runRetrieverContract, runStoreContract, runVectorStoreContract, type StoreCapabilities, type VectorStoreCapabilities, type VectorStoreContractOptions, } from './contracts.js';
 export { AdapterError, type AdapterErrorClass, type AdapterErrorCode, classifyAdapterError } from './errors.js';
+export { ADAPTER_KEYWORD, type GatheredSource, type GatherOutcome, type GatherRecordsOptions, type GatherReport, gatherRecords, type RecordSource, } from './gather.js';
 export { type CheckChange, COMPATIBILITY_RECORD_FORMAT, type CompatibilityComparison, type CompatibilityPageOptions, type CompatibilityRecord, type CompatibilityRecordAdapter, CompatibilityRecordError, type CompatibilityRecordOptions, type CompatibilityState, type CompatibilityStatus, compareRecords, compatibilityPage, compatibilityRecord, readCompatibilityRecord, recordDigest, recordStatus, } from './record.js';
 export { parseVersion, satisfiesRange } from './semver.js';
 /** The kinds of adapter the kit builds. */

package/dist/adapter-kit/index.js

@@ -7,6 +7,7 @@ import { compatibilityRecord } from './record.js';
 import { satisfiesRange } from './semver.js';
 export { ADAPTER_CONTRACTS, ADAPTER_FIXTURE_PASSAGES, runRetrieverContract, runStoreContract, runVectorStoreContract, } from './contracts.js';
 export { AdapterError, classifyAdapterError } from './errors.js';
+export { ADAPTER_KEYWORD, gatherRecords, } from './gather.js';
 export { COMPATIBILITY_RECORD_FORMAT, CompatibilityRecordError, compareRecords, compatibilityPage, compatibilityRecord, readCompatibilityRecord, recordDigest, recordStatus, } from './record.js';
 export { parseVersion, satisfiesRange } from './semver.js';
 const OPERATIONS = {

package/dist/adapter-kit/record.d.ts

@@ -145,6 +145,8 @@ export interface CompatibilityPageOptions {
 /**
  * One page listing every record: each adapter, its kind and version, the release and contract it was
  * verified against, its state there, its checks, and its p95 per operation, by kind and name. The
- * same records make the same page, so it can be checked for drift.
+ * same records make the same page, so it can be checked for drift. A record is written as text, never
+ * as markup: an adapter links to its repository only at an `http` or `https` address, and the HTML
+ * page colours each row by its state, a failing one red.
  */
 export declare function compatibilityPage(records: readonly CompatibilityRecord[], options?: CompatibilityPageOptions): string;

package/dist/adapter-kit/record.js

@@ -161,7 +161,7 @@ export function compatibilityPage(records, options = {}) {
             record,
             status,
             cells: [
-                record.adapter.repository
+                record.adapter.repository && /^https?:\/\//i.test(record.adapter.repository)
                     ? { text: record.adapter.name, href: record.adapter.repository }
                     : { text: record.adapter.name },
                 { text: record.adapter.kind },
@@ -187,7 +187,8 @@ export function compatibilityPage(records, options = {}) {
         const cell = (item) => item.href ? `<a href="${escapeHtml(item.href)}">${escapeHtml(item.text)}</a>` : escapeHtml(item.text);
         return [
             '<!doctype html>',
-            `<html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(title)}</title></head><body>`,
+            `<html lang="en"><head><meta charset="utf-8"><title>${escapeHtml(title)}</title>`,
+            `<style>${STATE_STYLE}</style></head><body>`,
             `<h1>${escapeHtml(title)}</h1>`,
             ...(options.intro ? [`<p>${escapeHtml(options.intro)}</p>`] : []),
             `<p>States are judged against nexus-ai-pro ${escapeHtml(nexusVersion)}.</p>`,
@@ -207,9 +208,11 @@ export function compatibilityPage(records, options = {}) {
             '',
         ].join('\n');
     }
+    const literal = (text) => oneLine(text).replace(/[|[\]*_`\\]/g, (char) => `\\${char}`);
     const cell = (item) => {
-        const text = item.text.replace(/\|/g, '\\|');
-        return item.href ? `[${text}](${item.href.replace(/\|/g, '%7C')})` : text;
+        const text = literal(item.text);
+        const href = item.href?.replace(/[|\s()]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`);
+        return href ? `[${text}](${href})` : text;
     };
     return [
         `# ${title}`,
@@ -221,7 +224,10 @@ export function compatibilityPage(records, options = {}) {
         `| ${headers.map(() => '---').join(' | ')} |`,
         ...rows.map((row) => `| ${row.cells.map(cell).join(' | ')} |`),
         ...(notes.length > 0
-            ? ['', ...notes.map((row) => `- **${row.record.adapter.name}**: ${row.status.reasons.join('; ')}`)]
+            ? [
+                '',
+                ...notes.map((row) => `- **${literal(row.record.adapter.name)}**: ${row.status.reasons.map(literal).join('; ')}`),
+            ]
             : []),
         '',
     ].join('\n');
@@ -240,6 +246,15 @@ function runtimeName() {
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+const STATE_STYLE = [
+    'tr[data-state="passing"] td{color:#1a7f37}',
+    'tr[data-state="failing"] td{color:#cf222e;font-weight:600}',
+    'tr[data-state="incompatible"] td{color:#9a6700}',
+    'tr[data-state="stale"] td{color:#57606a}',
+].join('');
+function oneLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
 function escapeHtml(text) {
     return text.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
 }

package/dist/cli/adapters.d.ts

@@ -1,10 +1,11 @@
 import { type ParsedArgs } from './args.js';
 /**
- * `nexus adapters verify <module>[#export]`, `nexus adapters page <records...>`, and
- * `nexus adapters recheck <records...>`.
+ * `nexus adapters verify <module>[#export]`, `nexus adapters page <records...>`,
+ * `nexus adapters recheck <records...>`, and `nexus adapters gather --out <dir>`.
  *
  * `verify` runs an adapter's contract suite and benchmark from its own repository and writes its
  * compatibility record; `page` lists records on one page; `recheck` verifies each listed adapter again
- * against the installed release and fails when one that passed no longer does.
+ * against the installed release and fails when one that passed no longer does; `gather` fetches the
+ * records adapters' own CI publishes, checked and never run, into a directory a page lists.
  */
 export declare function runAdaptersCommand(subcommand: string | undefined, args: ParsedArgs): Promise<void>;

package/dist/cli/adapters.js

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs';
-import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { ADAPTER_KEYWORD, gatherRecords } from '../adapter-kit/gather.js';
 import { compareRecords, compatibilityPage, readCompatibilityRecord, recordStatus, } from '../adapter-kit/record.js';
 import { CliUsageError, flagBool, isRecord, printTable, stringFlag, writeJson } from './args.js';
 export async function runAdaptersCommand(subcommand, args) {
@@ -12,7 +13,75 @@ export async function runAdaptersCommand(subcommand, args) {
         return page(args);
     if (subcommand === 'recheck')
         return recheck(args);
-    throw new CliUsageError(`Unknown adapters command "${subcommand ?? ''}". Use verify, page, or recheck.`);
+    if (subcommand === 'gather')
+        return gather(args);
+    throw new CliUsageError(`Unknown adapters command "${subcommand ?? ''}". Use verify, page, recheck, or gather.`);
+}
+async function gather(args) {
+    const out = stringFlag(args.flags, 'out');
+    if (!out)
+        throw new CliUsageError('nexus adapters gather needs --out <dir>: where the gathered records are kept.');
+    const sourcesFile = stringFlag(args.flags, 'sources');
+    const sources = sourcesFile ? sourcesFrom(await readFile(sourcesFile, 'utf8'), sourcesFile) : [];
+    const previous = [];
+    for (const name of existsSync(out) ? (await readdir(out)).sort() : []) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            previous.push({ file: name, record: readCompatibilityRecord(await readFile(path.join(out, name), 'utf8')) });
+        }
+        catch {
+        }
+    }
+    const registry = stringFlag(args.flags, 'registry');
+    const report = await gatherRecords({
+        keyword: args.flags.keyword === false ? false : (stringFlag(args.flags, 'keyword') ?? ADAPTER_KEYWORD),
+        sources,
+        previous: previous.map((entry) => entry.record),
+        ...(registry ? { registry } : {}),
+    });
+    await mkdir(out, { recursive: true });
+    const written = new Set();
+    for (const source of report.sources) {
+        if (!source.record)
+            continue;
+        const file = `${slug(source.package)}.json`;
+        written.add(file);
+        await writeFile(path.join(out, file), `${JSON.stringify(source.record, null, 2)}
+`);
+    }
+    for (const { file } of previous)
+        if (!written.has(file))
+            await rm(path.join(out, file));
+    if (flagBool(args.flags, 'json')) {
+        writeJson(report);
+        return;
+    }
+    printTable(report.sources.map((source) => ({
+        package: source.package,
+        outcome: source.outcome,
+        state: source.record ? recordStatus(source.record).state : '',
+        detail: source.detail ?? '',
+    })), ['package', 'outcome', 'state', 'detail']);
+    console.log('');
+    console.log(`${report.records.length} records listed in ${out}, of ${report.sources.length} packages.`);
+}
+function sourcesFrom(text, file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new CliUsageError(`${file} is not JSON: ${error.message}`);
+    }
+    if (!Array.isArray(parsed))
+        throw new CliUsageError(`${file} must list sources: [{ "package": ..., "url": ... }]`);
+    return parsed.map((item, index) => {
+        if (!isRecord(item) || typeof item.package !== 'string' || typeof item.url !== 'string') {
+            throw new CliUsageError(`${file}, source ${index + 1}: each source names its "package" and its record's "url"`);
+        }
+        return { package: item.package, url: item.url };
+    });
 }
 async function verify(args) {
     const [target] = args.positionals;

package/dist/cli/doctor.js

@@ -28,6 +28,9 @@ export async function runDoctorCommand({ flags }) {
     const maxQueueAgeMs = numberFlag(flags, 'max-queue-age-ms');
     if (maxQueueAgeMs !== undefined)
         options.maxQueueAgeMs = maxQueueAgeMs;
+    const upgrade = stringFlag(flags, 'upgrade');
+    if (upgrade !== undefined)
+        options.upgrade = upgrade;
     let report;
     try {
         report = await diagnose(options);

package/dist/cli.js

@@ -437,7 +437,7 @@ Usage:
   nexus db status --client <db.mjs> [--adapters ...] [--dialect postgres|sqlite] [--table t] [--check] [--json]
   nexus db migrate --client <db.mjs> [--dry-run] [--adapters ...] [--dialect postgres|sqlite] [--table t] [--json]
   nexus migrate [paths...] [--write] [--check] [--json]
-  nexus doctor [--module doctor.mjs] [--replicas n] [--max-queue-age-ms n] [--strict] [--json]
+  nexus doctor [--module doctor.mjs] [--replicas n] [--max-queue-age-ms n] [--upgrade 3.0] [--strict] [--json]
   nexus graph lint <module>[#export] [--deployed] [--strict] [--ignore CODE,CODE] [--json]
   nexus deploy status [assistant] --url <server> [--token t] [--json]
   nexus deploy canary <assistant> <revision> <percent> --url <server> [--reason r] [--version n]
@@ -446,6 +446,7 @@ Usage:
   nexus adapters verify <module>[#export] [--out record.json] [--package name@version] [--repository url] [--verify spec] [--json]
   nexus adapters page <records|dir...> [--out page.md] [--html] [--title t] [--intro text] [--expect page.md] [--check] [--strict]
   nexus adapters recheck <records|dir...> [--out dir] [--update] [--json]
+  nexus adapters gather --out <dir> [--keyword nexus-ai-pro-adapter | --no-keyword] [--sources sources.json] [--registry url] [--json]
   nexus policy check <policy.json> [--base <policy.json>|git:<ref>] [--accept path,path] [--json]
   nexus optimize [request.json|prompt.txt] [--model gpt-5-mini] [--max-input-tokens 4000] [--densify] [--json]
 
@@ -461,6 +462,7 @@ Database modules for "db status" and "db migrate" export { client }, and optiona
 "graph lint" reads a compiled graph's shape and exits 1 on an error finding, or on a warning with --strict.
 "adapters verify" exits 1 when the adapter does not pass; its module exports { adapter, config, options, record, close }.
 "adapters recheck" verifies each listed adapter again and exits 1 when one that passed no longer does; "adapters page --check" exits 1 on a failing or incompatible record, --strict on a stale one too.
+"adapters gather" fetches the records adapters' own CI publishes, found on npm by keyword or listed in --sources, keeps only those sealed and naming their package, and never runs them.
 "policy check" exits 1 when the policy is not valid, or, against --base, when a change that widens what a tenant may reach is not acknowledged.`);
 }
 main().catch((error) => {

package/dist/core/config-builder.d.ts

@@ -95,3 +95,4 @@ export declare function createNexusConfig(seed?: Partial<NexusAIConfig>): NexusC
  * Identity helper for users who prefer object literals but want type inference and validation in editors.
  */
 export declare function defineNexusConfig(config: NexusAIConfig): NexusAIConfig;
+export { DEFAULT_CHANGES, type DefaultChange, type NexusDefaults, nexusDefaults, useDefaults } from './defaults.js';

package/dist/core/config-builder.js

@@ -148,3 +148,4 @@ export function createNexusConfig(seed = {}) {
 export function defineNexusConfig(config) {
     return config;
 }
+export { DEFAULT_CHANGES, nexusDefaults, useDefaults } from './defaults.js';