nexus-ai-pro 2.13.0 → 2.15.0

package/API_STABILITY.md

@@ -41,6 +41,57 @@ 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.15 stage (2.15.0)
+
+Everything 2.15 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- in `nexus-ai-pro/adapter-kit`: `Adapter.record()`, `compatibilityRecord()`, `readCompatibilityRecord()`,
+  `recordDigest()`, `recordStatus()`, `compareRecords()`, `compatibilityPage()`,
+  `CompatibilityRecordError`, `COMPATIBILITY_RECORD_FORMAT`, `CompatibilityRecord`,
+  `CompatibilityRecordAdapter`, `CompatibilityRecordOptions`, `CompatibilityStatus`,
+  `CompatibilityState`, `CompatibilityComparison`, `CheckChange`, `CompatibilityPageOptions`,
+  `ADAPTER_CONTRACTS`, `AdapterContract`, and `AdapterContractVersion`; `AdapterReport.contractVersion`,
+  `nexusRange`, `capabilities`, and `budgets`;
+- the `nexus-compatibility/1` record format: a reader of one format version reads every record of it;
+  a new field may be added, and a record that needs it declares a new format;
+- the `nexus adapters verify`, `page`, and `recheck` commands, their flags, and their exit codes;
+- `OpenAIRealtimeServerOptions.credentials`, `tenantId`, and `provider`, the optional `apiKey`, and the
+  tenant the session endpoint takes per call.
+
+A contract's version rises when a minor release adds a check, by the rule above; its history keeps
+every version.
+
+## 2.14 stage (2.14.0)
+
+Everything 2.14 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable:
+- `nexus-ai-pro/policy`: `parsePolicy()`, `applyPolicy()`, `comparePolicies()`, `checkPolicyChange()`,
+  `providerGate()`, `policyHash()`, `PolicyError`, `Policy`, `PolicyDocument`, `PolicyAccess`,
+  `PolicyRouting`, `PolicyBudgets`, `PolicyResidency`, `PolicyCredentials`, `PolicyIssue`,
+  `ApplyPolicyOptions`, `PolicyChange`, `PolicyChangeKind`, and `PolicyCheck`;
+- `LifecycleConfig.providers` and `policy`, `ProviderGate`, `PolicyReference`,
+  `OperationDescriptor.policy`, `AuditLogEvent.policy`, and `OperationLifecycle.access()`;
+- the `nexus policy check` command, its flags, its exit codes, and its `--json` output;
+- `nexus-ai-pro/evaluate/emulate`: `emulatedTools()`, `EmulatedToolsOptions`, `EmulatorClient`,
+  `EmulatedToolCall`, `EmulatedResult`, `EmulationStore`, `MemoryEmulationStore`, `EmulationError`, and
+  `emulationKey()`. What the emulator is told may be reworded in a minor release; a store's keys never
+  change within a major;
+- `CallResidency.refusal()`, optional, and the optional `model` its `allows()`, `place()`, and
+  `check()` take;
+- `OperationLifecycle.callContext()`, the optional `OperationLifecycleLike.callContext`, and
+  `ContinuedCallContext`;
+- `tenantId` on `BatchSubmitRequest`, `EmbeddingBatchSubmitRequest`, `MediaReadRequest`,
+  `MediaDescribeRequest`, `MediaAnswerRequest`, `TranscriptionRequest`, `SpeechRequest`, and every
+  telephony request that takes a `signal`; `MediaCallContext.tenantId` and `credential`;
+  `RealtimeSessionConfig.credential`; the optional context the OpenAI voice adapter and the Twilio and
+  Telnyx adapters take on each method that calls their API.
+
+The kinds `comparePolicies()` gives a change may be refined in a minor release: a change found to widen
+what a tenant may reach is reported as `widened` from then on, so a check may start to ask for an
+acknowledgment it did not ask for before. A check never stops asking for one it asked for.
+
 ## 2.13 stage (2.13.0)
 
 Everything 2.13 adds is stable from the start and additive, unless this section says otherwise.

package/CHANGELOG.md

@@ -4,6 +4,72 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.15.0] - 2026-10-19
+
+A compatibility record for community adapters, and realtime sessions minted with the tenant's key.
+
+### Added
+
+- **A compatibility record for community adapters.** `adapter.record()` and `compatibilityRecord()`
+  seal what an adapter kit adapter's `verify()` proved: the contract version it passed, against which
+  release, its benchmark, its runtime, and a digest. `nexus adapters verify` makes one from the
+  adapter's own repository, `nexus adapters page` lists records on one page, and
+  `nexus adapters recheck` verifies each listed adapter again against the installed release and exits
+  1 when one that passed no longer does, naming the check. `recordStatus()` tells a passing record
+  from a failing, incompatible, or stale one, and `compareRecords()` what broke between two.
+  [COMPATIBILITY.md](./COMPATIBILITY.md) lists the adapters this repository ships, verified again by
+  every build.
+- **Contracts, versioned.** `ADAPTER_CONTRACTS` gives each kind's contract version and what each
+  version added. The vector-store contract is at version 2: “adds a passage again under an id it
+  deleted”. An `AdapterReport` carries its `contractVersion`, `nexusRange`, `capabilities`, and
+  `budgets`.
+- **Realtime sessions minted with the tenant's key.** The OpenAI realtime server helpers take the
+  client's `credentials` resolver and a `tenantId`: the session an SDP exchange makes and the client
+  secret a browser connects with use the tenant's key, a tenant without one is refused before anything
+  is sent, and the key is cleaned from every error. The session endpoint takes the tenant per call.
+
+## [2.14.0] - 2026-10-19
+
+Policy you can review, evaluation without side effects, and credentials per tenant in every family.
+
+### Added
+
+- **Policy you can review.** `nexus-ai-pro/policy` reads guardrails, routing, budgets, residency, and
+  credentials from one versioned file. `parsePolicy()` validates it as the client starts, naming every
+  issue; `applyPolicy()` turns it into the client's configuration; and every operation and audit event
+  records the policy's name, version, and content hash. `nexus policy check` compares a version with
+  the one before it, a file or `git:<ref>`, and fails the build on a change that widens what a tenant
+  may reach (a region, a provider, a model, a budget, lowered guardrails, a shared key) until it is
+  acknowledged in the file or with `--accept`, and on content changed without a new version.
+- **Per-tenant routing rules.** `LifecycleConfig.providers` takes a `ProviderGate` that admits or
+  refuses each provider and model an operation would reach, checked wherever residency is: a refused
+  provider is refused with an `OperationDeniedError` naming the rule before anything is sent, a
+  completion's refused attempt is dropped from its route, and an embedding never falls back to a
+  refused model. `providerGate()` builds one from a policy's routing rules, with `*` wildcards.
+- **Evaluation without side effects.** `emulatedTools()`, on the new `nexus-ai-pro/evaluate/emulate`,
+  returns an agent's tools answered by a model playing each one, told the tool, its result schema, a
+  scenario, real calls, and the run's earlier calls, and never run, so an evaluation of an agent that
+  charges cards or writes to a database sends nothing. Answers are kept by tool, arguments, scenario,
+  and call, and replayed, so a suite runs the same answers in CI without a model; tools that change
+  nothing can run for real.
+- **Credentials per tenant in every family.** Video, media understanding, completion and embedding
+  batches, voice, telephony, and realtime sessions send the tenant's key, resolved by
+  `LifecycleConfig.credentials`, in place of the configured one, as completions, embeddings, and images
+  have since 2.13. Each takes `tenantId` on its requests. A video job's or a batch's ref records its
+  tenant, so `status()`, `resume()`, `cancel()`, and `download()` use the tenant's key and regions from
+  any process, through the new `OperationLifecycle.callContext()`. A Twilio tenant's calls go out on its
+  subaccount; an OpenAI SIP call keeps its project's key.
+- `ai.lifecycle.access()` returns the `CallResidency` an operation would get, and
+  `CallResidency.refusal()` says why a provider would be refused once placed on its twin; `allows()`,
+  `place()`, and `check()` take the model as well.
+
+### Fixed
+
+- `VideoManager.start()` and the calls on a video ref, and `EmbeddingBatchManager.start()` and the
+  calls on its refs, ran outside the client's residency policy; they are held to the tenant's regions
+  now. A durable video generation ran its operation without its tenant, so a tenant's budget and rate
+  limit did not apply to it.
+
 ## [2.13.0] - 2026-10-19
 
 Regions and residency, and credentials per tenant.
@@ -2946,7 +3012,9 @@ 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.13.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.15.0...HEAD
+[2.15.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.14.0...v2.15.0
+[2.14.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.13.0...v2.14.0
 [2.13.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.12.0...v2.13.0
 [2.12.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.11.0...v2.12.0
 [2.11.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.10.0...v2.11.0

package/README.md

@@ -141,7 +141,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [MCP](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/mcp.md) | Borrowing tools from MCP servers, a registry of many, and serving your own |
 | [Agent protocols](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/protocols.md) | Serving an agent to user interfaces over AG-UI, to other agents over A2A, and to code editors over ACP, and calling remote agents as tools |
 | [Traces](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/tracing.md) | Run trees, queries, feedback, comparison, and alerts |
-| [Evaluation](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/evaluation.md) | Datasets, evaluators, experiments, comparisons with a verdict, review queues, LLM judges |
+| [Evaluation](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/evaluation.md) | Datasets, evaluators, experiments, comparisons with a verdict, review queues, LLM judges, and tools emulated by a model so an evaluation sends nothing |
 | [Context hub](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/context-hub.md) | Prompts, instructions, tools, and skills versioned together, promoted through gates, and moved between projects |
 | [Insights](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/insights.md) | Failing and slow runs clustered, regressions between time windows, and evaluated fix proposals |
 | [Prompts](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/prompts.md) | Typed templates, content versions, gated promotion, rollback, A/B splits, serving through outages |
@@ -162,11 +162,12 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Realtime voice](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/realtime.md) | Browser and server realtime sessions with barge-in, tools, and exports |
 | [Telephony](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/telephony.md) | Calls, webhooks, phone numbers, and phone agents on realtime sessions |
 | [Testing](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/testing.md) | Recording and replaying provider traffic, and conformance suites |
-| [Adapter kit](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/adapter-kit.md) | Building a provider, store, or retriever outside this repository, and verifying it against the same contracts |
+| [Adapter kit](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/adapter-kit.md) | Building a provider, store, or retriever outside this repository, verifying it against the same contracts, and its compatibility record on the [compatibility page](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/COMPATIBILITY.md) |
 | [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 |
+| [Policy](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/policy.md) | Guardrails, routing, budgets, residency, and credentials as one versioned file, validated as the client starts, checked by `nexus policy check` in CI, and recorded on every operation |
 | [Regions and credentials](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/regions.md) | Agent servers across regions behind a gateway, residency rules that keep each tenant's requests, traces, and assets in its regions, and each tenant's provider keys from a secret manager |
 | [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 |
@@ -312,14 +313,22 @@ Shipped so far:
 - 2.13 regions and residency, and credentials per tenant: agent servers across regions behind a
   gateway that fails over only within a tenant's regions, residency rules that keep each tenant's
   provider calls, traces, and assets in its regions, and each tenant's provider keys from a secret
-  manager, rotated without a restart and kept out of every error.
+  manager, rotated without a restart and kept out of every error;
+- 2.14 policy you can review, and evaluation without side effects: guardrails, routing, budgets,
+  residency, and credentials as one versioned file that `nexus policy check` compares with the version
+  before it in CI and every operation records, tools emulated by a model so an evaluation sends
+  nothing, and each tenant's key in every family;
+- 2.15 a compatibility record for community adapters: `nexus adapters verify` seals the contract an
+  adapter passed, against which release, with its benchmark; `nexus adapters recheck` turns a listed
+  adapter red before a release that would break it; and one
+  [page](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/COMPATIBILITY.md) lists them.
 
 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.14 makes policy a reviewed file, checked by the command line before it ships, brings
-per-tenant keys to every family, and lets an evaluation run an agent over emulated tools with nothing
-sent. 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, 2.16 serves A2A over its HTTP+JSON and gRPC bindings beside JSON-RPC, one task store behind
+all three, and lets a push webhook receive each piece of streamed text. 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
 [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/contracts.d.ts

@@ -7,6 +7,7 @@ import type { RagChunk } from '../hallucination/rag.js';
 import type { EmbeddingProvider, VectorStore } from '../hallucination/retrieval.js';
 import type { Retriever } from '../rag/retrievers.js';
 import type { Store } from '../types/store.js';
+import type { AdapterKind } from './index.js';
 /** One check of a contract suite. */
 export interface AdapterCheck {
     /** What was checked, as a sentence. */
@@ -18,6 +19,30 @@ export interface AdapterCheck {
     /** True when the adapter does not declare the capability the check needs. */
     skipped?: boolean;
 }
+/** One version of a kind's contract: the release it arrived in, and the checks it added. */
+export interface AdapterContractVersion {
+    /** The contract's version, counted from 1. */
+    version: number;
+    /** The release of `nexus-ai-pro` it arrived in. */
+    nexus: string;
+    /** The checks it added, by name. */
+    added: readonly string[];
+}
+/** A kind's contract: its current version, and what each version added. */
+export interface AdapterContract {
+    /** The adapter kind it is for. */
+    kind: AdapterKind;
+    /** Its current version, which every record names. */
+    version: number;
+    /** Each version, oldest first, so a record verified against an older one says what it was not checked for. */
+    history: readonly AdapterContractVersion[];
+}
+/**
+ * Every kind's contract, versioned: a version is added when a release adds a check, so a record of
+ * an adapter verified against an older version is known to be stale, and the checks it has not run are
+ * named.
+ */
+export declare const ADAPTER_CONTRACTS: Readonly<Record<AdapterKind, AdapterContract>>;
 /** The passages every retrieval contract runs on, and that benchmarks reuse. */
 export declare const ADAPTER_FIXTURE_PASSAGES: readonly RagChunk[];
 /** What a vector store declares it supports, for its contract. */
@@ -40,7 +65,8 @@ export interface VectorStoreContractOptions {
 }
 /**
  * The `VectorStore` contract: ranking, `topK`, sources and metadata round-tripped, filters,
- * `minScore`, vector search, replacement by id, deletes, and empty writes. The store should be empty
+ * `minScore`, vector search, replacement by id, deletes, an id added again after its delete, and
+ * empty writes. The store should be empty
  * when it starts.
  */
 export declare function runVectorStoreContract(store: VectorStore, options: VectorStoreContractOptions): Promise<AdapterCheck[]>;

package/dist/adapter-kit/contracts.js

@@ -1,3 +1,17 @@
+export const ADAPTER_CONTRACTS = {
+    provider: { kind: 'provider', version: 1, history: [{ version: 1, nexus: '2.4.0', added: [] }] },
+    embeddings: { kind: 'embeddings', version: 1, history: [{ version: 1, nexus: '2.4.0', added: [] }] },
+    'vector-store': {
+        kind: 'vector-store',
+        version: 2,
+        history: [
+            { version: 1, nexus: '2.4.0', added: [] },
+            { version: 2, nexus: '2.15.0', added: ['adds a passage again under an id it deleted'] },
+        ],
+    },
+    retriever: { kind: 'retriever', version: 1, history: [{ version: 1, nexus: '2.4.0', added: [] }] },
+    store: { kind: 'store', version: 1, history: [{ version: 1, nexus: '2.4.0', added: [] }] },
+};
 export const ADAPTER_FIXTURE_PASSAGES = [
     {
         id: 'refunds#0',
@@ -112,6 +126,13 @@ export async function runVectorStoreContract(store, options) {
         const results = await store.search('how long do refunds take', { topK: 10 });
         return !results.some((result) => result.id === 'refunds#0') || 'the deleted passage is still found';
     });
+    await suite.check('adds a passage again under an id it deleted', async () => {
+        await store.add([fixturePassages()[0]]);
+        await settle();
+        const results = await store.search('how long do refunds take', { topK: 10 });
+        const copies = results.filter((result) => result.id === 'refunds#0').length;
+        return copies === 1 || (copies === 0 ? 'the passage stays deleted' : `found ${copies} copies`);
+    });
     await suite.check('accepts empty writes', async () => {
         await store.add([]);
         await store.delete([]);

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

@@ -17,8 +17,10 @@ import type { EmbeddingsProvider } from '../types/embeddings.js';
 import type { Store } from '../types/store.js';
 import { type AdapterCheck, type RetrieverCapabilities, type RetrieverContractOptions, type StoreCapabilities, type VectorStoreCapabilities } from './contracts.js';
 import { type AdapterErrorClass } from './errors.js';
-export { ADAPTER_FIXTURE_PASSAGES, type AdapterCheck, type RetrieverCapabilities, type RetrieverContractOptions, runRetrieverContract, runStoreContract, runVectorStoreContract, type StoreCapabilities, type VectorStoreCapabilities, type VectorStoreContractOptions, } from './contracts.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 { 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. */
 export type AdapterKind = 'provider' | 'embeddings' | 'vector-store' | 'retriever' | 'store';
@@ -89,6 +91,14 @@ export interface AdapterReport {
     checks: AdapterCheck[];
     /** Latency per operation over the contract's calls. */
     benchmark: Record<string, AdapterBenchmarkEntry>;
+    /** The releases the adapter declares support for. */
+    nexusRange: string;
+    /** What it declares it can do. */
+    capabilities: unknown;
+    /** The p95 budgets it declares. */
+    budgets?: Readonly<Record<string, number>>;
+    /** The version of its kind's contract it was verified against, from `ADAPTER_CONTRACTS`. */
+    contractVersion: number;
 }
 /** An adapter built with the kit. */
 export interface Adapter<Config, Instance, Capabilities, VerifyOptions> extends Readonly<Omit<AdapterDefinition<Config, Instance, Capabilities>, 'create'>> {
@@ -100,6 +110,11 @@ export interface Adapter<Config, Instance, Capabilities, VerifyOptions> extends
     compatible(nexusVersion?: string): boolean;
     /** Runs the contract suite for its kind against a fresh instance, with a benchmark. */
     verify(config: Config, options: VerifyOptions): Promise<AdapterReport>;
+    /**
+     * Verifies it and seals the report as a `CompatibilityRecord`: what a page lists, and what a release
+     * is checked against.
+     */
+    record(config: Config, options: VerifyOptions, record?: CompatibilityRecordOptions): Promise<CompatibilityRecord>;
 }
 /** What a chat provider supports, which decides the conformance cases it runs. */
 export interface ProviderAdapterCapabilities {

package/dist/adapter-kit/index.js

@@ -1,11 +1,13 @@
 import { runEmbeddingProviderConformance, } from '../testing/embedding-provider-conformance.js';
 import { runProviderConformance } from '../testing/provider-conformance.js';
 import { NEXUS_VERSION } from '../version.js';
-import { runRetrieverContract, runStoreContract, runVectorStoreContract, } from './contracts.js';
+import { ADAPTER_CONTRACTS, runRetrieverContract, runStoreContract, runVectorStoreContract, } from './contracts.js';
 import { AdapterError, classifyAdapterError } from './errors.js';
+import { compatibilityRecord } from './record.js';
 import { satisfiesRange } from './semver.js';
-export { ADAPTER_FIXTURE_PASSAGES, runRetrieverContract, runStoreContract, runVectorStoreContract, } from './contracts.js';
+export { ADAPTER_CONTRACTS, ADAPTER_FIXTURE_PASSAGES, runRetrieverContract, runStoreContract, runVectorStoreContract, } from './contracts.js';
 export { AdapterError, classifyAdapterError } from './errors.js';
+export { COMPATIBILITY_RECORD_FORMAT, CompatibilityRecordError, compareRecords, compatibilityPage, compatibilityRecord, readCompatibilityRecord, recordDigest, recordStatus, } from './record.js';
 export { parseVersion, satisfiesRange } from './semver.js';
 const OPERATIONS = {
     provider: ['complete', 'healthCheck'],
@@ -21,7 +23,7 @@ function build(kind, definition, contract) {
     }
     satisfiesRange(NEXUS_VERSION, definition.nexus);
     const create = async (config, options = {}) => instrument(kind, definition, await definition.create(config), options);
-    return {
+    const adapter = {
         kind,
         name: definition.name,
         version: definition.version,
@@ -31,6 +33,9 @@ function build(kind, definition, contract) {
         ...(definition.budgets ? { budgets: definition.budgets } : {}),
         create,
         compatible: (nexusVersion = NEXUS_VERSION) => satisfiesRange(nexusVersion, definition.nexus),
+        async record(config, options, record) {
+            return compatibilityRecord(await adapter.verify(config, options), record);
+        },
         async verify(config, options) {
             const durations = new Map();
             const instance = await create(config, {
@@ -78,9 +83,14 @@ function build(kind, definition, contract) {
                 passed: checks.every((check) => check.ok),
                 checks,
                 benchmark,
+                nexusRange: definition.nexus,
+                capabilities: definition.capabilities,
+                ...(definition.budgets ? { budgets: definition.budgets } : {}),
+                contractVersion: ADAPTER_CONTRACTS[kind].version,
             };
         },
     };
+    return adapter;
 }
 function instrument(kind, definition, instance, options) {
     const operations = new Set(OPERATIONS[kind]);

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

@@ -0,0 +1,150 @@
+import { type AdapterCheck } from './contracts.js';
+import type { AdapterBenchmarkEntry, AdapterKind, AdapterReport } from './index.js';
+/** The format every record declares, so a reader knows what it holds. */
+export declare const COMPATIBILITY_RECORD_FORMAT = "nexus-compatibility/1";
+/** The adapter a record is of, as its definition declares it. */
+export interface CompatibilityRecordAdapter {
+    /** Its name, usually its package name. */
+    name: string;
+    /** Its version. */
+    version: string;
+    /** Its kind. */
+    kind: AdapterKind;
+    /** The releases of `nexus-ai-pro` it declares support for, as a range. */
+    nexus: string;
+    /** What it declares it can do. */
+    capabilities: unknown;
+    /** The p95 budgets it declares, in milliseconds. */
+    budgets?: Readonly<Record<string, number>>;
+    /** Where it is published, such as `@acme/nexus-milvus@0.3.0`. */
+    package?: string;
+    /** Its source repository. */
+    repository?: string;
+    /**
+     * The module that verifies it, as `nexus adapters verify` loads one, so `nexus adapters recheck` can
+     * verify it again: a path, or a package specifier such as `@acme/nexus-milvus/verify`.
+     */
+    verify?: string;
+}
+/** What an adapter's `verify()` proved, sealed. */
+export interface CompatibilityRecord {
+    /** `nexus-compatibility/1`. */
+    format: typeof COMPATIBILITY_RECORD_FORMAT;
+    /** The adapter. */
+    adapter: CompatibilityRecordAdapter;
+    /** The contract it was verified against: its kind and version. */
+    contract: {
+        kind: AdapterKind;
+        version: number;
+    };
+    /** The release of `nexus-ai-pro` it was verified against. */
+    nexusVersion: string;
+    /** ISO-8601 time it was verified. */
+    verifiedAt: string;
+    /** The runtime it was verified on, such as `node 24.21.0 linux x64`. */
+    runtime: string;
+    /** Whether that release is inside the adapter's declared range. */
+    compatible: boolean;
+    /** Whether it is compatible and every check that ran held. */
+    passed: boolean;
+    /** Every check, in order, skipped ones marked. */
+    checks: AdapterCheck[];
+    /** Latency per operation over the contract's calls. */
+    benchmark: Record<string, AdapterBenchmarkEntry>;
+    /** The SHA-256 of everything above, so an edited record is known for one. */
+    digest: string;
+}
+/** What `compatibilityRecord()` adds to a report. */
+export interface CompatibilityRecordOptions {
+    /** Where the adapter is published. */
+    package?: string;
+    /** Its source repository. */
+    repository?: string;
+    /** The module that verifies it, for `nexus adapters recheck`. */
+    verify?: string;
+    /** The runtime, when not the one this runs on. */
+    runtime?: string;
+    /** Replaces the clock, for tests. */
+    now?: () => Date;
+}
+/** Raised when a record cannot be read: not a record, of an unknown format, or edited after it was sealed. */
+export declare class CompatibilityRecordError extends Error {
+    /** Every problem found. */
+    readonly issues: readonly string[];
+    constructor(message: string, 
+    /** Every problem found. */
+    issues?: readonly string[]);
+}
+/** A record of what `verify()` reported, sealed with its digest. */
+export declare function compatibilityRecord(report: AdapterReport, options?: CompatibilityRecordOptions): CompatibilityRecord;
+/** The digest a record is sealed with: the SHA-256 of its content, its keys in order, without the digest. */
+export declare function recordDigest(record: Omit<CompatibilityRecord, 'digest'> | CompatibilityRecord): string;
+/**
+ * Reads a record, as JSON text or as an object, and checks it: its format, the fields every record
+ * has, and its digest. Throws a `CompatibilityRecordError` listing every problem.
+ */
+export declare function readCompatibilityRecord(input: string | unknown): CompatibilityRecord;
+/** Where a record stands against a release: what a page shows, and what a check gates on. */
+export type CompatibilityState = 'passing' | 'failing' | 'incompatible' | 'stale';
+/** A record's state against a release, and why. */
+export interface CompatibilityStatus {
+    /**
+     * `failing` when a check did not hold; `incompatible` when the release is outside the adapter's
+     * declared range; `stale` when it was verified against an older version of its contract;
+     * `passing` otherwise.
+     */
+    state: CompatibilityState;
+    /** Why, a sentence each. */
+    reasons: string[];
+    /** The checks its contract added since the version it was verified against. */
+    unverified: string[];
+}
+/** Where a record stands against a release, the installed one by default. */
+export declare function recordStatus(record: CompatibilityRecord, options?: {
+    nexusVersion?: string;
+}): CompatibilityStatus;
+/** One check whose outcome moved between two records of an adapter. */
+export interface CheckChange {
+    /** The check. */
+    name: string;
+    /** Why it fails now, when it does. */
+    detail?: string;
+}
+/** What changed between an adapter's listed record and a record of it verified again. */
+export interface CompatibilityComparison {
+    /** The adapter. */
+    adapter: string;
+    /** Checks that held before and fail now. */
+    broken: CheckChange[];
+    /** Checks the listed record did not have, with whether each holds. */
+    added: AdapterCheck[];
+    /** Checks that failed before and hold now. */
+    fixed: string[];
+    /** Operations whose p95 more than doubled, with both. */
+    slower: Array<{
+        operation: string;
+        beforeMs: number;
+        afterMs: number;
+    }>;
+    /** True when the listed record passed and the new one does not: this release turns it red. */
+    regressed: boolean;
+}
+/** Compares an adapter's listed record with one verified again, such as against a release candidate. */
+export declare function compareRecords(listed: CompatibilityRecord, current: CompatibilityRecord): CompatibilityComparison;
+/** Options for `compatibilityPage()`. */
+export interface CompatibilityPageOptions {
+    /** The page's title. Defaults to `Adapter compatibility`. */
+    title?: string;
+    /** A paragraph under the title. */
+    intro?: string;
+    /** The release each record's state is judged against. Defaults to the installed one. */
+    nexusVersion?: string;
+    /** `markdown`, the default, or `html`. */
+    format?: 'markdown' | 'html';
+}
+/**
+ * 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.
+ */
+export declare function compatibilityPage(records: readonly CompatibilityRecord[], options?: CompatibilityPageOptions): string;