nexus-ai-pro 2.2.0 → 2.4.0

package/README.md

@@ -8,7 +8,10 @@ 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 78 KB, and installs nothing but this package.
+loads 81 KB, and installs nothing but this package.
+The client, the provider adapters, graphs, agents, and the agent protocols run on Node.js, Deno,
+Bun, edge runtimes, and browsers; [the runtimes guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/runtimes.md)
+lists the entry points that need Node.js, and why.
 
 - NPM: https://www.npmjs.com/package/nexus-ai-pro
 - GitHub: https://github.com/mkhitar-abrahamyan/nexus-ai
@@ -132,9 +135,11 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Providers and routing](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/providers.md) | The twelve completion providers, routing and failover, the model registry |
 | [Guardrails](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/security.md) | Injection, PII, secrets, schema validation, output redaction |
 | [Graphs](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/graphs.md) | Parallel branches, interrupts, checkpoints, time travel, subgraphs, caching, diagrams |
-| [Agents and tools](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/agents.md) | Graph-based agents with approvals and middleware, and the simple tool loop |
+| [Agents and tools](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/agents.md) | Graph-based agents with approvals, capabilities and permission policies, a sandbox contract, the middleware catalog, and the simple tool loop |
+| [The deep-agent preset](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/deep-agents.md) | Long, multi-step agents: a plan, a sandboxed workspace, helpers, skills, and a context that stays small |
 | [Long-term memory](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/memory.md) | Namespaced memory with semantic search, in memory or Redis |
 | [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 |
 | [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 |
@@ -155,6 +160,7 @@ 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 |
 | [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 |
@@ -162,6 +168,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [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 |
+| [Runtimes](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/runtimes.md) | The portable kernel, and running the client, providers, graphs, and agents on Deno, Bun, edge runtimes, and browsers |
 
 ## Examples
 
@@ -251,13 +258,20 @@ Shipped so far:
   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.
+  across every store, and `nexus doctor` to check a deployment before it serves traffic;
+- 2.3 agents that act safely, on production retrieval: capabilities and permission policies, a
+  sandbox contract, a middleware catalog, server authentication with one principal on every run,
+  keyword search in Postgres and Elasticsearch with rerankers, durable ingestion, and a deep-agent
+  preset;
+- 2.4 graduation and interoperability: SQLite, loaders, retrievers, the MCP registry, the context
+  hub, insights, and tenant limits out of experimental with published evidence; canaries judged with
+  confidence and on quality; an adapter kit; AG-UI, A2A, and ACP; and a portable kernel, with the
+  client, providers, graphs, and agents running on Deno, Bun, edge runtimes, and browsers.
 
 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.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.
+What comes next is on the [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md):
+the gaps 2.4 left open, and the work applications ask for after them.
 
 ## Before Production
 

package/SECURITY.md

@@ -44,3 +44,143 @@ Nexus guardrails reduce common AI application risks, but they are not a complete
 - Browser WebRTC still requires a backend security boundary. A direct media path reduces latency; it
   does not remove the need for server-owned credentials, session policy, tool authorization, abuse
   monitoring, and provider-side safety controls.
+
+## Threat reviews
+
+Every surface that leaves experimental status is reviewed for how untrusted input reaches it and
+what it could do with that input. Each review is published here with its findings, which are closed
+before the surface graduates. A finding is closed in one of two ways: by a fix with a test that
+names the attack, or by a documented limitation that the surface's guide states.
+
+These reviews were done for 2.4.
+
+### SQLite adapters
+
+Trust boundary: an application's data, an operation's payload, and metadata filters that may come
+from a request.
+- Table names are checked against a strict pattern and quoted. Every value, including each metadata
+  filter key and its JSON path, is a bound parameter, so a filter cannot change a statement.
+- A migration records its checksum, and a changed migration is refused rather than reapplied.
+- Every change to an operation is one `UPDATE … WHERE sequence = expected`, so two workers sharing
+  a file never both claim it. The ten-worker race tests run on SQLite.
+- Tenant data is scoped by key prefix, and the isolation suite runs on every SQLite store.
+
+Findings: none.
+
+### The Postgres and SQLite vector stores
+
+Trust boundary: metadata filters, which applications often build from a request.
+- The pgvector store sends a filter as one bound `jsonb` containment parameter, and quotes its table
+  and index names.
+- The SQLite store binds each key's JSON path and value, and matches a value's JSON type as well as
+  its value, so `"1"` never matches `1`.
+
+Findings: none.
+
+### Loaders
+
+Trust boundary: everything a loader reads is untrusted. A repository, a website, a sitemap, or an
+uploaded file may be written by an attacker who wants it in a knowledge base, or who wants the
+loader to read something else.
+- Web pages and sitemaps go through the SSRF-safe fetch. Private, loopback, and cloud-metadata
+  addresses are refused, every redirect is checked again, and bodies are capped.
+- The Git loader runs `git` without a shell. It disables the `ext::` transport, puts `--` before
+  the repository, and refuses a repository that starts with `-`.
+- `loadDirectory()` does not follow symbolic links.
+
+Findings, both fixed in 2.4:
+- **The Git loader followed symbolic links.** A tracked link such as `notes.md` pointing to
+  `~/.ssh/id_rsa` was read and ingested, so a knowledge base could quote a file of the host. A
+  link is now never followed, nor a path that resolves outside the checkout. Proof: a repository
+  holding a tracked link to a file outside it loads without that file, cloned and in place. On
+  Linux, the test fails on the earlier loader.
+- **A gzipped sitemap could be a decompression bomb.** A few megabytes of gzip inflated without a
+  limit. Inflation now stops at 50 MB, the sitemap protocol's own maximum. Proof: 60 MB of gzip
+  that inflates past it is refused.
+
+### Retrievers
+
+Trust boundary: queries come from users, and documents may hold text written to steer a model.
+- Tokenizing is one linear regular expression, with no backtracking on hostile input.
+- Filters compare values; they never become code or a query language.
+- A model reranker or query-variant generator reads documents and queries as data in its prompt. Its
+  output is parsed as JSON and used only to order or widen a search, never to call a tool.
+
+Findings: none.
+
+### MCP registry
+
+Trust boundary: the configuration file is trusted, since it names programs to run. What a server
+says about itself is not: its tool names, its descriptions, and its results.
+- A server's tools are prefixed with its name by default, so one server cannot shadow another's
+  tool.
+- Allow and deny lists limit what agents see, and deny wins.
+- A tool from a server declares no capabilities. A permission policy denies such a tool unless its
+  `undeclared` rule says otherwise, and `humanApproval()` asks about it by default.
+- `${NAME}` placeholders keep credentials out of the file. A missing variable is named in the error,
+  never its value.
+
+Finding, fixed in 2.4: **a local server inherited this process's whole environment.** Any
+`npx`-started server, which is usually third-party code, saw every API key and database URL the
+application held. A server now starts with `env` and only what a process needs to run: the path,
+the home and temporary directories, the locale, proxies, and certificates. The new `inheritEnv`
+option widens this by name, or entirely. Proof: a real child process started by the transport sees
+the variables it was given, and not a secret set in the parent.
+
+### Context hub
+
+Trust boundary: an imported bundle may come from another team or another organization. Who may
+commit and promote is the application's access control, which the studio's roles enforce.
+- An import recomputes each bundle's and each prompt's content version, and refuses one whose content
+  changed after export.
+- A bundle names tools, but `bindTools()` binds only implementations the application supplies, so
+  a bundle cannot add code.
+- Promotion runs the label's gates, an experiment over the exact version among them.
+- Labels move by compare-and-set, so a promotion decided on a stale version is refused.
+
+Finding, fixed in 2.4: **the file store's compare-and-set could lose a move.** Two label moves at
+once in one process could both pass the check, and the later write erased the earlier one. Label
+writes to one file are now serialized across the process. Proof: two hubs whose writes are held
+until both arrive race for one label on every backend, and on the file store the earlier code
+loses a move every time. Several processes promoting the same label at once still need the Redis or
+Postgres store, as the prompts guide says.
+
+### Insights
+
+Trust boundary: runs and their errors carry user data, and a model proposes fixes.
+- An error signature replaces numbers, quoted values, URLs, ids, and long hexadecimal strings, so a
+  cluster's summary does not carry a customer's data.
+- A model's proposed fix is parsed as data, evaluated on a dataset, and never applied without a
+  person. A promotion still runs the label's gates.
+- A proposal id is checked against a strict pattern before it becomes a file name.
+
+Findings: none.
+
+### Tenant limits and the worker queue
+
+Trust boundary: a tenant is whoever the application's `authenticate()` says, never a header the
+server trusts by itself.
+- Concurrency, rate, and budget limits are kept in a shared store, so several replicas enforce one
+  limit. Admission and release are tested by ten racing workers.
+- A run is released exactly once, however it ends.
+- The queue claims an operation under a lease in one atomic step on every store. A lost lease
+  cancels the run's signal, and a crash at any durable boundary resumes to the same state.
+
+Findings: none.
+
+### Deployments (reviewed; still experimental)
+
+Findings:
+- **Fixed in 2.4: one caller's ratings could decide a canary.** A canary was judged on feedback
+  entries, not on runs. A hundred low ratings of one run met the minimum sample alone, and could
+  roll back a canary for everyone, or keep a bad one alive. Each run now counts once per feedback
+  key, as the mean of its ratings.
+- **Fixed in 2.4: two changes at once on one replica could lose one**, such as a guard's rollback
+  and an operator's promotion. Changes to one deployment now apply in order.
+- **Open: two replicas changing one deployment in the same instant can lose one change.** The
+  server's state store has no atomic compare-and-set. Until it does, deployments stay experimental.
+  The guide says to make changes from one place, or to pass `expectedVersion` and retry a conflict.
+- **Documented limitation: `bucket()` spreads sequential ids unevenly.** Ids that differ only in their
+  last characters spread unevenly over a few hundred threads. Random ids, which the server gives by
+  default, spread evenly. The function's output is part of the stability promise, so it is not
+  changed in 2.x.

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

@@ -0,0 +1,87 @@
+/**
+ * The contract suites the adapter kit ships: what every vector store, retriever, and long-term store
+ * must do, as checks that need no test framework. Each check is named for the behavior it proves,
+ * and a capability the adapter does not declare is reported as skipped, never as a failure.
+ */
+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';
+/** One check of a contract suite. */
+export interface AdapterCheck {
+    /** What was checked, as a sentence. */
+    name: string;
+    /** Whether it held. */
+    ok: boolean;
+    /** Why it did not hold, or why it was skipped. */
+    detail?: string;
+    /** True when the adapter does not declare the capability the check needs. */
+    skipped?: boolean;
+}
+/** 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. */
+export interface VectorStoreCapabilities {
+    /** `searchVector()` with a vector computed elsewhere. Defaults to true. */
+    searchVector?: boolean;
+    /** `minScore` drops weak matches. Defaults to true. */
+    minScore?: boolean;
+    /** Metadata filters: `exact` matches values, `typed` also tells `3` from `'3'`, `none` has no filters. Defaults to `exact`. */
+    filters?: 'none' | 'exact' | 'typed';
+}
+/** Options for `runVectorStoreContract()`. */
+export interface VectorStoreContractOptions {
+    /** The embedding function the store was given, to compute a query vector for `searchVector()`. */
+    embed: EmbeddingProvider;
+    /** What the store supports. */
+    capabilities?: VectorStoreCapabilities;
+    /** Waits for writes to become searchable, for a store whose index is eventually consistent. */
+    settle?: () => Promise<void>;
+}
+/**
+ * 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
+ * when it starts.
+ */
+export declare function runVectorStoreContract(store: VectorStore, options: VectorStoreContractOptions): Promise<AdapterCheck[]>;
+/** What a retriever declares it supports, for its contract. */
+export interface RetrieverCapabilities {
+    /** It holds its own passages, with `add()` and `delete()`: a `SparseRetriever`. Defaults to whether it has them. */
+    writes?: boolean;
+    /** Metadata filters. Defaults to true. */
+    filters?: boolean;
+}
+/** Options for `runRetrieverContract()`. */
+export interface RetrieverContractOptions {
+    /** What the retriever supports. */
+    capabilities?: RetrieverCapabilities;
+    /**
+     * Loads the fixture passages, for a retriever that does not hold its own: into the vector store
+     * behind it, say. A retriever with `add()` is loaded through that.
+     */
+    load?: (passages: RagChunk[]) => Promise<void>;
+    /** Waits for writes to become searchable. */
+    settle?: () => Promise<void>;
+}
+/**
+ * The `Retriever` contract, and the `SparseRetriever` contract when the retriever takes writes:
+ * an exact term found, ranking, `topK`, filters, replacement, deletes, and an empty query.
+ */
+export declare function runRetrieverContract(retriever: Retriever, options?: RetrieverContractOptions): Promise<AdapterCheck[]>;
+/** What a long-term store declares it supports, for its contract. */
+export interface StoreCapabilities {
+    /** `search()` lists a namespace prefix, newest first. Defaults to true. */
+    search?: boolean;
+    /** `search()` filters on value fields. Defaults to true. */
+    filters?: boolean;
+    /** `listNamespaces()`. Defaults to true. */
+    namespaces?: boolean;
+}
+/**
+ * The long-term `Store` contract: values round-trip, a replaced item keeps its creation time, a
+ * missing key reads as nothing, deletes, prefix search with filters and paging, and namespace
+ * listing. The store should be empty when it starts.
+ */
+export declare function runStoreContract(store: Store, options?: {
+    capabilities?: StoreCapabilities;
+}): Promise<AdapterCheck[]>;

package/dist/adapter-kit/contracts.js

@@ -0,0 +1,237 @@
+export const ADAPTER_FIXTURE_PASSAGES = [
+    {
+        id: 'refunds#0',
+        content: 'Refunds are issued within fourteen days of a return',
+        source: 'policy.md',
+        metadata: { tenant: 'acme', page: 3 },
+    },
+    {
+        id: 'shipping#0',
+        content: 'Orders ship from the warehouse within two business days',
+        source: 'policy.md',
+        metadata: { tenant: 'acme' },
+    },
+    { id: 'refunds#1', content: 'A refund goes back to the original payment method', metadata: { tenant: 'globex' } },
+    { id: 'careers#0', content: 'We are hiring engineers in three offices' },
+];
+function fixturePassages() {
+    return ADAPTER_FIXTURE_PASSAGES.map((passage) => ({
+        ...passage,
+        ...(passage.metadata ? { metadata: { ...passage.metadata } } : {}),
+    }));
+}
+class Suite {
+    checks = [];
+    async check(name, run) {
+        try {
+            const result = await run();
+            this.checks.push(result === true ? { name, ok: true } : { name, ok: false, detail: result === false ? 'did not hold' : result });
+        }
+        catch (error) {
+            this.checks.push({ name, ok: false, detail: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    skip(name, reason) {
+        this.checks.push({ name, ok: true, skipped: true, detail: reason });
+    }
+}
+export async function runVectorStoreContract(store, options) {
+    const suite = new Suite();
+    const settle = options.settle ?? (async () => undefined);
+    const capabilities = options.capabilities ?? {};
+    const filters = capabilities.filters ?? 'exact';
+    await suite.check('adds passages', async () => {
+        await store.add(fixturePassages());
+        await settle();
+        return true;
+    });
+    await suite.check('ranks the closest passage first, best first, within topK', async () => {
+        const results = await store.search('how long do refunds take', { topK: 2 });
+        if (results.length !== 2)
+            return `expected 2 results for topK 2, got ${results.length}`;
+        if (results[0]?.id !== 'refunds#0')
+            return `expected refunds#0 first, got ${results[0]?.id}`;
+        return (results[0]?.score ?? 0) > (results[1]?.score ?? 0) || 'results are not ordered by score';
+    });
+    await suite.check('returns a passage source and its metadata whole', async () => {
+        const [first] = await store.search('how long do refunds take', { topK: 1 });
+        if (first?.source !== 'policy.md')
+            return `expected source policy.md, got ${first?.source}`;
+        return (JSON.stringify(first?.metadata) === JSON.stringify({ tenant: 'acme', page: 3 }) ||
+            `metadata came back as ${JSON.stringify(first?.metadata)}`);
+    });
+    if (filters === 'none')
+        suite.skip('narrows a search by metadata', 'the store declares no filters');
+    else {
+        await suite.check('narrows a search by metadata', async () => {
+            const results = await store.search('refund', { filter: { tenant: 'globex' } });
+            return ((results.length === 1 && results[0]?.id === 'refunds#1') ||
+                `got ${results.map((result) => result.id).join(', ')}`);
+        });
+    }
+    if (filters === 'typed') {
+        await suite.check('tells a number from the same digits as text in a filter', async () => {
+            const numeric = await store.search('refunds', { filter: { page: 3 }, topK: 10 });
+            const text = await store.search('refunds', { filter: { page: '3' }, topK: 10 });
+            return ((numeric.length === 1 && text.length === 0) || `number matched ${numeric.length}, text matched ${text.length}`);
+        });
+    }
+    else
+        suite.skip('tells a number from the same digits as text in a filter', 'the store declares untyped filters');
+    if (capabilities.minScore === false)
+        suite.skip('drops matches under minScore', 'the store declares no minScore');
+    else {
+        await suite.check('drops matches under minScore', async () => {
+            const results = await store.search('how long do refunds take', { minScore: 0.99 });
+            return results.length === 0 || `${results.length} results above 0.99`;
+        });
+    }
+    if (capabilities.searchVector === false)
+        suite.skip('searches by a precomputed vector', 'the store declares no searchVector');
+    else {
+        await suite.check('searches by a precomputed vector', async () => {
+            const [vector] = await options.embed(['orders ship from the warehouse']);
+            const [first] = await store.searchVector(vector, { topK: 1 });
+            return first?.id === 'shipping#0' || `expected shipping#0, got ${first?.id}`;
+        });
+    }
+    await suite.check('replaces a passage added again under its id', async () => {
+        await store.add([
+            { id: 'careers#0', content: 'Refunds for event tickets are not available', metadata: { tenant: 'acme' } },
+        ]);
+        await settle();
+        const results = await store.search('event tickets refunds', { topK: 10 });
+        const copies = results.filter((result) => result.id === 'careers#0');
+        if (copies.length !== 1)
+            return `found ${copies.length} copies`;
+        return /event tickets/.test(copies[0]?.content ?? '') || 'the old content is still there';
+    });
+    await suite.check('deletes by id, ignoring ids it does not hold', async () => {
+        await store.delete(['refunds#0', 'not-stored']);
+        await settle();
+        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('accepts empty writes', async () => {
+        await store.add([]);
+        await store.delete([]);
+        return true;
+    });
+    return suite.checks;
+}
+export async function runRetrieverContract(retriever, options = {}) {
+    const suite = new Suite();
+    const settle = options.settle ?? (async () => undefined);
+    const sparse = retriever;
+    const writes = options.capabilities?.writes ?? (typeof sparse.add === 'function' && typeof sparse.delete === 'function');
+    const passages = fixturePassages();
+    await suite.check('loads the fixture passages', async () => {
+        if (writes)
+            await sparse.add?.(passages);
+        else if (options.load)
+            await options.load(passages);
+        else
+            return 'a retriever without add() needs a load() to fill what it reads from';
+        await settle();
+        return true;
+    });
+    await suite.check('finds the passage holding the query terms first', async () => {
+        const [first] = await retriever.retrieve('warehouse business days', { topK: 3 });
+        return first?.id === 'shipping#0' || `expected shipping#0, got ${first?.id}`;
+    });
+    await suite.check('returns at most topK results, best first', async () => {
+        const results = await retriever.retrieve('refund refunds return', { topK: 1 });
+        return results.length <= 1 || `${results.length} results for topK 1`;
+    });
+    if (options.capabilities?.filters === false)
+        suite.skip('narrows by metadata', 'the retriever declares no filters');
+    else {
+        await suite.check('narrows by metadata', async () => {
+            const results = await retriever.retrieve('refund', { filter: { tenant: 'globex' }, topK: 10 });
+            return ((results.every((result) => result.metadata?.tenant === 'globex') && results.length > 0) ||
+                `got ${results.map((result) => result.id).join(', ')}`);
+        });
+    }
+    if (!writes) {
+        suite.skip('replaces a passage added again under its id', 'the retriever does not take writes');
+        suite.skip('deletes by id, ignoring ids it does not hold', 'the retriever does not take writes');
+    }
+    else {
+        await suite.check('replaces a passage added again under its id', async () => {
+            await sparse.add?.([{ id: 'careers#0', content: 'Engineers relocate with a stipend' }]);
+            await settle();
+            const results = await retriever.retrieve('stipend relocate', { topK: 10 });
+            return (results.filter((result) => result.id === 'careers#0').length === 1 || 'the passage is missing or duplicated');
+        });
+        await suite.check('deletes by id, ignoring ids it does not hold', async () => {
+            await sparse.delete?.(['shipping#0', 'not-stored']);
+            await settle();
+            const results = await retriever.retrieve('warehouse business days', { topK: 10 });
+            return !results.some((result) => result.id === 'shipping#0') || 'the deleted passage is still found';
+        });
+    }
+    await suite.check('answers an empty query without failing', async () => {
+        await retriever.retrieve('', { topK: 3 });
+        return true;
+    });
+    return suite.checks;
+}
+export async function runStoreContract(store, options = {}) {
+    const suite = new Suite();
+    const capabilities = options.capabilities ?? {};
+    const namespace = ['contract', 'users'];
+    await suite.check('round-trips a value', async () => {
+        await store.put(namespace, 'ann', { name: 'Ann', plan: 'pro' });
+        const item = await store.get(namespace, 'ann');
+        return (item?.value.name === 'Ann' && item.key === 'ann') || `read ${JSON.stringify(item)}`;
+    });
+    await suite.check('keeps the creation time when an item is replaced', async () => {
+        const before = await store.get(namespace, 'ann');
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        await store.put(namespace, 'ann', { name: 'Ann', plan: 'team' });
+        const after = await store.get(namespace, 'ann');
+        if (after?.value.plan !== 'team')
+            return 'the replacement was not stored';
+        return after.createdAt === before?.createdAt || `createdAt moved from ${before?.createdAt} to ${after.createdAt}`;
+    });
+    await suite.check('reads a missing key as nothing', async () => (await store.get(namespace, 'nobody')) === undefined);
+    await suite.check('deletes an item', async () => {
+        await store.put(namespace, 'temp', { name: 'Temp' });
+        await store.delete(namespace, 'temp');
+        return (await store.get(namespace, 'temp')) === undefined;
+    });
+    if (capabilities.search === false)
+        suite.skip('lists a namespace prefix, with paging', 'the store declares no search');
+    else {
+        await suite.check('lists a namespace prefix, with paging', async () => {
+            await store.put([...namespace, 'archived'], 'bob', { name: 'Bob', plan: 'free' });
+            await store.put(namespace, 'cy', { name: 'Cy', plan: 'free' });
+            const all = await store.search(['contract'], { limit: 10 });
+            if (all.length !== 3)
+                return `expected 3 items under the prefix, got ${all.length}`;
+            const page = await store.search(['contract'], { limit: 2, offset: 2 });
+            return page.length === 1 || `expected 1 item on the second page, got ${page.length}`;
+        });
+    }
+    if (capabilities.search === false || capabilities.filters === false)
+        suite.skip('filters by a value field', 'the store declares no filters');
+    else {
+        await suite.check('filters by a value field', async () => {
+            const free = await store.search(['contract'], { filter: { plan: 'free' }, limit: 10 });
+            const names = free
+                .map((item) => item.value.name)
+                .sort()
+                .join(',');
+            return names === 'Bob,Cy' || `got ${names}`;
+        });
+    }
+    if (capabilities.namespaces === false)
+        suite.skip('lists namespaces under a prefix', 'the store declares no namespace listing');
+    else {
+        await suite.check('lists namespaces under a prefix', async () => {
+            const listed = (await store.listNamespaces({ prefix: ['contract'] })).map((parts) => parts.join('/')).sort();
+            return listed.join(',') === 'contract/users,contract/users/archived' || `got ${listed.join(', ')}`;
+        });
+    }
+    return suite.checks;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * One vocabulary for adapter failures, so code above an adapter retries, alerts, and reports the same
+ * way whichever database, provider, or service the adapter talks to.
+ */
+/** What kind of failure an adapter call met. */
+export type AdapterErrorCode = 'AUTH' | 'RATE_LIMIT' | 'NOT_FOUND' | 'INVALID' | 'CONFLICT' | 'TIMEOUT' | 'UNAVAILABLE' | 'CANCELLED' | 'UNKNOWN';
+/** A failure's code, and whether another attempt could succeed. */
+export interface AdapterErrorClass {
+    /** The kind of failure. */
+    code: AdapterErrorCode;
+    /** True for a failure a retry could get past: a rate limit, a timeout, an unavailable service. */
+    retryable: boolean;
+    /** The HTTP status, when the failure carried one. */
+    status?: number;
+}
+/** A failed adapter call, normalized. The original error is its `cause`. */
+export declare class AdapterError extends Error {
+    /** The adapter that failed. */
+    readonly adapter: string;
+    /** The method that failed, such as `search`. */
+    readonly operation: string;
+    /** The kind of failure. */
+    readonly code: AdapterErrorCode;
+    /** Whether another attempt could succeed. */
+    readonly retryable: boolean;
+    /** The HTTP status, when the failure carried one. */
+    readonly status?: number;
+    constructor(
+    /** The adapter that failed. */
+    adapter: string, 
+    /** The method that failed, such as `search`. */
+    operation: string, failure: AdapterErrorClass, cause: unknown);
+}
+/**
+ * Classifies any error by what it carries: an HTTP status (`status`, `statusCode`, or
+ * `response.status`), a Node network code such as `ECONNREFUSED`, or an `AbortError` or
+ * `TimeoutError` name. An adapter's own `normalizeError` runs first and may override it.
+ */
+export declare function classifyAdapterError(error: unknown): AdapterErrorClass;

package/dist/adapter-kit/errors.js

@@ -0,0 +1,52 @@
+export class AdapterError extends Error {
+    adapter;
+    operation;
+    code;
+    retryable;
+    status;
+    constructor(adapter, operation, failure, cause) {
+        super(`${adapter} ${operation} failed (${failure.code}): ${cause instanceof Error ? cause.message : String(cause)}`, {
+            cause,
+        });
+        this.adapter = adapter;
+        this.operation = operation;
+        this.name = 'AdapterError';
+        this.code = failure.code;
+        this.retryable = failure.retryable;
+        if (failure.status !== undefined)
+            this.status = failure.status;
+    }
+}
+const RETRYABLE = new Set(['RATE_LIMIT', 'TIMEOUT', 'UNAVAILABLE']);
+export function classifyAdapterError(error) {
+    const value = error;
+    const raw = value?.status ?? value?.statusCode ?? value?.response?.status;
+    const status = typeof raw === 'number' ? raw : undefined;
+    const code = (() => {
+        if (value?.name === 'AbortError')
+            return 'CANCELLED';
+        if (value?.name === 'TimeoutError' || value?.code === 'ETIMEDOUT')
+            return 'TIMEOUT';
+        if (status !== undefined) {
+            if (status === 401 || status === 403)
+                return 'AUTH';
+            if (status === 404)
+                return 'NOT_FOUND';
+            if (status === 408)
+                return 'TIMEOUT';
+            if (status === 409 || status === 412)
+                return 'CONFLICT';
+            if (status === 429)
+                return 'RATE_LIMIT';
+            if (status >= 500)
+                return 'UNAVAILABLE';
+            if (status >= 400)
+                return 'INVALID';
+        }
+        if (typeof value?.code === 'string' && /^(ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|EPIPE)$/.test(value.code)) {
+            return 'UNAVAILABLE';
+        }
+        return 'UNKNOWN';
+    })();
+    return { code, retryable: RETRYABLE.has(code), ...(status === undefined ? {} : { status }) };
+}