nexus-ai-pro 2.3.0 → 2.4.0

package/API_STABILITY.md

@@ -41,6 +41,178 @@ 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.4 stage (2.4.0)
+
+Everything 2.4 adds is stable from the start and additive. These security fixes tighten behavior,
+as the compatibility rules allow:
+- the upload scanner checks the larger of the declared and actual sizes;
+- an allowlist refuses a file with no MIME type;
+- textual bytes are scanned;
+- secret findings carry a preview instead of the value;
+- card and phone matches must pass their checks.
+
+New and stable:
+- `confidence`, `minErrorRateIncrease`, `minFeedbackDrop`, and `resamples` on `watchCanaries()`;
+  the same options and `seed` on `compareRuns()`; `Regression.interval`;
+- `Deployments.evaluate()` with `RunEvaluationOptions` and `RunEvaluationReport`;
+- `RunRecord.feedback`, `RunManager.addFeedback()`, and `POST /runs/:id/feedback`;
+- `nexus-ai-pro/adapter-kit`: the `define*()` builders, `Adapter`, `AdapterDefinition`,
+  `AdapterReport`, `AdapterError` and its codes, the contract runners, and the capability types.
+  Contract checks may be added in a minor release when they test something the contract already
+  promised. A new check for a new promise arrives behind a capability an adapter must declare.
+- `nexus-ai-pro/protocols/ag-ui`, `nexus-ai-pro/protocols/a2a`, and `nexus-ai-pro/protocols/acp`:
+  the handlers, `a2aClient()`, `a2aTool()`, `serveAcp()`, and their types. Each speaks the
+  protocol version it names. A minor release may send an event or answer a method it did not
+  before, as a protocol adds them. An event or field already sent keeps its meaning. A new major
+  version of a protocol arrives beside the old one, not in its place.
+- `nexus-ai-pro/runtime`, `runtimeInfo()`, `RuntimeInfo`, and `RuntimeName`, which may gain
+  names in a minor release; the `fetch` option on the OpenAI, Anthropic, Google, and Cohere
+  provider configurations.
+- Portability, for the client, the kernel, the provider adapters, graphs, agents, and the agent
+  protocols: none of them starts needing Node.js in a minor release, and the build fails if one
+  does.
+
+Without `confidence`, a canary is judged as before.
+
+These security fixes tighten more behavior, each closing a finding of a graduation review in
+[SECURITY.md](./SECURITY.md#threat-reviews):
+- the Git loader never follows a symbolic link, nor a path that leaves the checkout;
+- a gzipped sitemap may inflate to 50 MB at most, the sitemap protocol's maximum;
+- a local MCP server inherits only what a process needs to run, not this process's environment.
+  `inheritEnv` restores the old behavior, by name or entirely;
+- a canary is judged on runs, so each run counts once per feedback key, as the mean of its scores;
+- the file prompt store's label compare-and-set holds within one process;
+- changes to one deployment through one `Deployments` object apply in order.
+
+### Graduation
+
+A surface left experimental status in 2.4 only when every requirement in
+[How an item graduates](./ROADMAP.md#how-an-item-graduates) had evidence. That evidence is below.
+"n/a" names a requirement that does not apply, and says why. Every test named here runs in CI.
+Load and soak budgets are checked by `npm run bench:surfaces` and `npm run bench:runtime`, which are
+part of `check:release`. Upgrade tests run against the published 2.3.0 package, installed as a
+development alias.
+
+Every graduated surface is covered by the 2.x compatibility rules, with no breaking change planned.
+That is the "API stability" requirement, met by all of them.
+
+**The SQLite adapters** (`nexus-ai-pro/sqlite` and its subpaths):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | The operation store, store, and vector store contracts: `tests/sqlite.test.ts`, `tests/vector-stores.test.ts` |
+| Crash recovery | A crash at every durable boundary resumes to the uninterrupted state: `tests/crash-injection.test.ts` |
+| Concurrency | Ten workers race one thread, one idempotency key, one queue, and one budget: `tests/ten-workers.test.ts` |
+| Load | `checkpoint.sqlite` and `operations.claim-10k-queued` in `runtime-budget.json`; `sqlite.vectors-query-2k` and `sqlite.store-put-get-search` in `surface-budget.json` |
+| Tenant isolation | Every SQLite store: `tests/tenant-isolation.test.ts` |
+| Security | [Review](./SECURITY.md#sqlite-adapters): no findings |
+| Upgrade | A 2.3 file upgrades in place, and a 2.3 worker shares its queue: `tests/upgrade-previous-minor.test.ts`; likewise from 2.0: `tests/upgrade.test.ts` |
+| Soak | 20,000 queue lifecycles and 2,000 open, migrate, and close cycles, with flat memory and no handle left open |
+
+**The Postgres and SQLite vector stores** (`PostgresVectorStore`, `SqliteVectorStore`):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | The vector store contract on pgvector and on SQLite: `tests/vector-stores.test.ts`. The retriever contract over each: `tests/graduation-conformance.test.ts` |
+| Crash recovery | n/a: a store keeps no run state, and a reload upserts the same ids |
+| Concurrency | Ten writers upserting the same ids at once leave one whole row per id: `tests/graduation-conformance.test.ts` |
+| Load | `sqlite.vectors-query-2k` and `postgres.vectors-query-1k` in `surface-budget.json` |
+| Tenant isolation | Both stores: `tests/tenant-isolation.test.ts` |
+| Security | [Review](./SECURITY.md#the-postgres-and-sqlite-vector-stores): no findings |
+| Upgrade | A table 2.3 wrote is searched and filtered here: `tests/upgrade-previous-minor.test.ts` |
+| Soak | 1,000 write, search, and delete cycles on pgvector |
+
+**The loaders** (`nexus-ai-pro/loaders/*`):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | Every format, the web loader through the SSRF-safe fetch, and Git cloned and in place: `tests/loaders.test.ts` |
+| Crash recovery | n/a: a loader keeps no state, and reloading replaces the same chunks |
+| Concurrency | n/a: a loader shares no records |
+| Load | `loaders.markdown-csv-html` in `surface-budget.json` |
+| Tenant isolation | n/a: a loader stores nothing; the store it loads into is isolated |
+| Security | [Review](./SECURITY.md#loaders): two findings, both fixed |
+| Upgrade | The same files give the same ids and text as in 2.3: `tests/upgrade-previous-minor.test.ts` |
+| Soak | 2,000 load cycles |
+
+**The retrievers** (`nexus-ai-pro/rag/retrievers`):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | The retriever contract on `KeywordIndex`, on a vector retriever over memory, SQLite, and pgvector, and on `hybridRetriever()`: `tests/graduation-conformance.test.ts` |
+| Crash recovery | n/a: an index is held in memory, and rebuilt by loading |
+| Concurrency | n/a: an index belongs to one process |
+| Load | `retrievers.keyword-query-5k` and `retrievers.hybrid-query` in `surface-budget.json` |
+| Tenant isolation | Filters narrow every retriever, by the contract; the stores behind them are isolated |
+| Security | [Review](./SECURITY.md#retrievers): no findings |
+| Upgrade | The same corpus ranks the same, score for score, as in 2.3: `tests/upgrade-previous-minor.test.ts` |
+| Soak | 50,000 add and delete cycles |
+
+**The MCP registry** (`nexus-ai-pro/mcp/registry`):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | Servers over the protocol in process and as a real child process: `tests/mcp-registry.test.ts` |
+| Crash recovery | A server that fails to start is reported, and the rest serve: `tests/mcp-registry.test.ts` |
+| Concurrency | n/a: a registry shares no records |
+| Load | `mcp.registry-tools-10-servers` in `surface-budget.json` |
+| Tenant isolation | n/a: a registry stores nothing |
+| Security | [Review](./SECURITY.md#mcp-registry): one finding, fixed |
+| Upgrade | A configuration reads the same as in 2.3: `tests/upgrade-previous-minor.test.ts` |
+| Soak | 1,000 connect, call, and close cycles, with no handle left open |
+
+**The context hub** (`nexus-ai-pro/context-hub`):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | The same behavior on memory, files, Redis, and Postgres: `tests/graduation-conformance.test.ts` |
+| Crash recovery | A commit is content-addressed, so repeating an interrupted one writes the same version: `tests/context-hub.test.ts` |
+| Concurrency | Two hubs racing for one label never both win, on every backend: `tests/graduation-conformance.test.ts` |
+| Load | `context-hub.commit-resolve` in `surface-budget.json` |
+| Tenant isolation | Context bundles: `tests/tenant-isolation.test.ts` |
+| Security | [Review](./SECURITY.md#context-hub): one finding, fixed |
+| Upgrade | A bundle has the same version as in 2.3, and a 2.3 export imports: `tests/upgrade-previous-minor.test.ts` |
+| Soak | 2,000 commit, resolve, and render cycles |
+
+**Insights** (`nexus-ai-pro/insights`):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | The same issues from runs in memory and in Postgres: `tests/graduation-conformance.test.ts`; proposals in memory and in files: `tests/insights.test.ts` |
+| Crash recovery | n/a: analysis is read-only, and a proposal is one write |
+| Concurrency | n/a: a proposal is decided once, by a person |
+| Load | `insights.find-issues-5k-runs` in `surface-budget.json` |
+| Tenant isolation | Insights read through the trace store, which is isolated: `tests/tenant-isolation.test.ts` |
+| Security | [Review](./SECURITY.md#insights): no findings |
+| Upgrade | A 2.3 proposal reads here, and errors group under the same signatures: `tests/upgrade-previous-minor.test.ts` |
+| Soak | 300 clustering cycles |
+
+**Tenant limits and the server's worker queue** (`nexus-ai-pro/server/tenancy`, and the queue
+`createAgentServer()` runs on its operation store):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | Tenant usage in memory and in Redis; the queue on every operation store: `tests/deployments.test.ts`, `tests/operations.test.ts` |
+| Crash recovery | A crash at every durable boundary resumes to the same state, and a draining worker hands a run to another: `tests/crash-injection.test.ts`, `tests/deployments.test.ts` |
+| Concurrency | Ten workers drain one queue, and spend one tenant budget without over-granting a slot: `tests/ten-workers.test.ts` |
+| Load | `tenancy.admit-release` in `surface-budget.json`; `operations.claim-10k-queued` and `server.sse-fanout` in `runtime-budget.json` |
+| Tenant isolation | Operations: `tests/tenant-isolation.test.ts` |
+| Security | [Review](./SECURITY.md#tenant-limits-and-the-worker-queue): no findings |
+| Upgrade | A 2.3 worker and a 2.4 worker drain one queue: `tests/upgrade-previous-minor.test.ts` |
+| Soak | 50,000 admit and release cycles, and 500 replica lifecycles with no timer left running |
+
+**Still experimental**, each with what remains:
+- **Deployments** (`nexus-ai-pro/server/deployments`). Two replicas changing one deployment in the
+  same instant can lose one change, because the state store has no atomic compare-and-set. Every
+  other requirement has evidence above or in its review.
+- **Images.** Recorded live conformance must pass on all three backends. The scheduled live workflow
+  now records it, wherever a backend's credential is set.
+- **The Qdrant, Redis, Pinecone, Weaviate, and Chroma vector stores.** The contract must pass against
+  the real servers, not only stubs. The scheduled live workflow now runs it against each one as a
+  service container, and Pinecone runs when its secret is set.
+- **The studio and its accounts.** A threat review of its sign-in, sessions, and roles, and a soak
+  of its server, are still to do.
+
 ## 2.3 stage (2.3.0)
 
 Everything 2.3 adds is stable from the start and additive: no default changes meaning.
@@ -618,6 +790,9 @@ of the 1.x line.
 
 ## Deployment stage (1.24.0)
 
+Tenant limits and the worker queue graduated in 2.4; see the 2.4 stage for their evidence.
+Deployments remain experimental.
+
 Deployments (`nexus-ai-pro/server/deployments`), tenant limits (`nexus-ai-pro/server/tenancy`), and the
 server's worker queue are experimental in production readiness. Their contracts follow the 1.x rules.
 
@@ -632,6 +807,9 @@ server's worker queue are experimental in production readiness. Their contracts
 
 ## Team platform stage (1.23.0)
 
+The context hub and insights graduated in 2.4; see the 2.4 stage for their evidence. The studio's
+accounts remain experimental.
+
 The context hub (`nexus-ai-pro/context-hub`), insights (`nexus-ai-pro/insights`), and the studio's
 accounts are experimental in production readiness. Their contracts follow the 1.x rules.
 
@@ -644,6 +822,9 @@ accounts are experimental in production readiness. Their contracts follow the 1.
 
 ## Retrieval breadth stage (1.22.0)
 
+The loaders, the SQLite vector store, the retrievers, and the MCP registry graduated in 2.4; see the
+2.4 stage for their evidence. The Redis, Pinecone, Weaviate, and Chroma stores remain experimental.
+
 The loaders (`nexus-ai-pro/loaders/*`), the Redis, Pinecone, Weaviate, Chroma, and SQLite vector
 stores, the retrievers (`nexus-ai-pro/rag/retrievers`), and the MCP registry
 (`nexus-ai-pro/mcp/registry`) are experimental in production readiness. Their contracts follow the
@@ -660,6 +841,8 @@ stores, the retrievers (`nexus-ai-pro/rag/retrievers`), and the MCP registry
 
 ## Durable execution stage (1.21.0)
 
+The SQLite adapters graduated in 2.4; see the 2.4 stage for their evidence.
+
 Functional workflows (`nexus-ai-pro/graph/functional`) and the SQLite adapters (`nexus-ai-pro/sqlite`)
 are experimental in production readiness. Their contracts follow the 1.x rules.
 
@@ -672,6 +855,9 @@ are experimental in production readiness. Their contracts follow the 1.x rules.
 
 ## Retrieval stores stage (1.20.0)
 
+`PostgresVectorStore` graduated in 2.4; see the 2.4 stage for its evidence. `QdrantVectorStore`
+remains experimental.
+
 `PostgresVectorStore` (`nexus-ai-pro/postgres/vectors`) and `QdrantVectorStore` (`nexus-ai-pro/rag/qdrant`)
 are experimental in production readiness. The `VectorStore` contract they share with
 `MemoryVectorStore` follows the 1.x rules: a minor release may add optional methods and options, not

package/CHANGELOG.md

@@ -4,6 +4,188 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-10-08
+
+Graduation and interoperability.
+
+### Added
+
+- **Canaries judged with confidence, and on quality.**
+  - `watchCanaries({ confidence })` judges each metric the way an evaluation comparison judges a
+    score: a seeded bootstrap interval that must not reach zero, and a minimum effect —
+    `minErrorRateIncrease`, the latency and cost margins, and `minFeedbackDrop`. A real regression
+    rolls back; noise and a trivially small change do not. `compareRuns()` takes the same options,
+    and each `Regression` carries its `interval`.
+  - `Deployments.evaluate()` scores an assistant's finished runs with evaluators from
+    `nexus-ai-pro/evaluate`, and records the scores as run feedback. A canary that answers worse is
+    then rolled back like one that fails more. Sampling is stable by run id, and a run is scored
+    once per source.
+  - Runs carry `feedback`. `POST /runs/:id/feedback` and `RunManager.addFeedback()` record a
+    person's rating as well.
+- **An adapter kit**, on the new `nexus-ai-pro/adapter-kit`, for building adapters outside this
+  repository:
+  - `defineProviderAdapter()`, `defineEmbeddingsAdapter()`, `defineVectorStoreAdapter()`,
+    `defineRetrieverAdapter()`, and `defineStoreAdapter()`. Each takes a capability declaration
+    and the range of releases the adapter supports, read as npm reads ranges.
+  - Every instance normalizes its failures into an `AdapterError` with a code and `retryable`, and
+    reports each call to an `onCall` telemetry hook.
+  - `verify()` runs the adapter's contract suite, skipping only what it declares it cannot do, with
+    a benchmark held to the p95 budgets it declares.
+  - The vector-store, retriever, and store contracts ship as `runVectorStoreContract()`,
+    `runRetrieverContract()`, and `runStoreContract()`, with no test framework needed.
+- **Agent protocols**, each on its own entry point and with no dependency:
+  - `nexus-ai-pro/protocols/ag-ui`: `agUiHandler()` serves a graph to any AG-UI frontend as
+    Server-Sent Events: each step, text as it streams, tool calls with their results, and the final
+    state. A run that needs approval finishes with an interrupt, and a resume entry on the same
+    thread continues it. `agUiEvents()` yields the same events for any other transport.
+  - `nexus-ai-pro/protocols/a2a`: `a2aHandler()` serves a graph as an A2A 1.0 agent: its card,
+    `SendMessage`, `SendStreamingMessage`, `GetTask`, and `CancelTask`. A context is a
+    conversation, and a task that needs approval asks for input and continues when a message answers
+    it. `a2aClient()` calls any A2A agent, and `a2aTool()` makes one a tool that declares the
+    host it reaches, so a permission policy decides it.
+  - `nexus-ai-pro/protocols/acp`: `serveAcp()` puts a graph in a code editor over the Agent
+    Client Protocol. The editor sees streamed text and thought, each tool call with its kind, file,
+    and diff, and the plan from `write_todos`. It asks the person to approve calls, and keeps an
+    always-allow or always-reject choice for the session.
+- **A portable kernel**, on the new `nexus-ai-pro/runtime`: messages, responses, the provider and
+  tool contracts, streaming, and capabilities, in one small import that reaches nothing Node-only.
+  `runtimeInfo()` names the runtime the code is on.
+- **The client, the provider adapters, graphs, agents, and the agent protocols run on Deno, Bun,
+  edge runtimes, and browsers.**
+  - Ids come from Web Crypto.
+  - SHA-256 for node-cache keys and dataset versions is computed in plain JavaScript where the
+    runtime has no synchronous native digest. The digests are identical, so existing cache keys
+    still match.
+  - Base64 and UTF-8 byte counts no longer need `Buffer`.
+  - 125 of 157 entry points now run anywhere. The new runtimes guide lists the rest, each with
+    exactly what it needs.
+- The OpenAI, Anthropic, Google, and Cohere providers take a `fetch` option: a platform's bound
+  fetch, a proxy, or a test stub.
+- **Measured graduation.** These surfaces leave experimental status, each with evidence for every
+  requirement of the graduation checklist, published in `API_STABILITY.md`:
+  - the SQLite adapters;
+  - the Postgres and SQLite vector stores;
+  - the loaders and the retrievers;
+  - the MCP registry;
+  - the context hub and insights;
+  - tenant limits and the server's worker queue.
+
+  Deployments, images, the Qdrant, Redis, Pinecone, Weaviate, and Chroma vector stores, and the
+  studio stay experimental, each with the requirement that remains named.
+- `inheritEnv` on a local MCP server, in `StdioClientOptions` and in the registry's server
+  configuration: which of this process's environment variables the server inherits.
+- Load and soak budgets for every graduated surface, held in CI by `npm run bench:surfaces`. A soak
+  fails on heap growth, on a handle left open, or on a timer never cleared, unref'd ones included.
+- The scheduled live workflow records image conformance on every backend with a credential, and
+  runs the vector store contract against real Qdrant, Chroma, Weaviate, and Redis servers.
+
+### Security
+
+Testing the security code to depth found these gaps, and each is closed:
+
+- **The upload scanner trusted the caller.**
+  - A declared `sizeBytes` could carry a larger file past `maxBytes`; the larger of the declared and
+    actual sizes is now checked.
+  - `run.exe.`, `run.exe ` (Windows drops the trailing dot or space), and a name with a control
+    character such as `run.exe\0.txt` passed the extension block; names are now read as the file
+    system reads them, and a control character is itself a critical finding.
+  - Content given as bytes, which is how upload middleware delivers it, was never scanned; textual
+    bytes are now decoded and scanned.
+  - A file with no MIME type passed an allowlist; an allowlist now fails closed. Types are compared
+    without parameters, so `text/plain; charset=utf-8` is `text/plain`.
+- **File ingestion read what it never scanned.** Text an extractor returns from a PDF or an image is
+  now scanned like a text file. A text file given as bytes is ingested rather than skipped.
+- **The input guard put secrets in its findings.** A finding now carries a short preview, such as
+  `ghp_… (40 characters)`, never the secret. The SSRF check also catches `[::1]`, all of
+  `127.0.0.0/8`, and the Google and Alibaba metadata hosts.
+- **Prompt hardening could be escaped.** User text holding the delimiter closed the block early; each
+  occurrence inside the text is now broken apart. The text parts of multi-part messages are wrapped
+  too.
+- **The injection detectors read text as typed, not as the model reads it.** Both now fold
+  full-width letters and drop zero-width characters first, so `ＩＧＮＯＲＥ previous instructions` and
+  `ig​nore previous instructions` are found. `neutralize()` leaves clean text exactly as it was.
+- **The PII detector and the output guard took any long number for a card or a phone.** A
+  millisecond timestamp or an order id was masked, and in the output guard a card's last digits
+  could survive because the phone pattern claimed the rest first. Card numbers must now pass Luhn,
+  and phone numbers need 10 to 15 digits with a separator or a leading `+`. Cards are claimed before
+  phones, and a span one kind has claimed is not reported again as another.
+- **Retrieved context reads as data.** `withRagContext()` now tells the model that the context is
+  data, not instructions.
+
+The graduation reviews, published in `SECURITY.md`, found these, and each is closed:
+
+- **The Git loader followed symbolic links.** A repository with a tracked link to a file of the host,
+  such as `~/.ssh/id_rsa`, had that file loaded into a knowledge base. A link is now never followed,
+  nor a path that leaves the checkout.
+- **A gzipped sitemap could be a decompression bomb.** Inflation now stops at 50 MB, the sitemap
+  protocol's maximum, and the loader reports the sitemap.
+- **A local MCP server inherited this process's whole environment**, every API key and database URL
+  included. It now starts with its `env` and only what a process needs to run: the path, the home
+  and temporary directories, the locale, the Windows system variables, proxies, and certificates.
+  Name what else a server needs in `env`, or set `inheritEnv`.
+- **One caller's ratings could decide a canary.** Feedback was counted per rating, so a hundred low
+  ratings of one run met the minimum sample alone, and could roll back a canary or keep a bad one
+  alive. Each run now counts once per feedback key, as the mean of its ratings.
+- **The file prompt store could lose a label move.** Its compare-and-set was a read and then a write,
+  so two moves at once in one process could both succeed, the later erasing the earlier. Label
+  writes to one file are now serialized across the process.
+- **Two changes at once to one deployment, on one replica, could lose one**, such as a guard's
+  rollback and an operator's promotion. They now apply in order. Changes from two replicas in the
+  same instant still can, which keeps deployments experimental.
+
+### Fixed
+
+- The agent server's guide called the server experimental, though it has been stable since 2.0.
+- Bundling the client for an edge runtime failed: it reached the file-based evaluation cache, which
+  loads `node:fs`. `FileEvaluationCache` now lives in a module of its own, still exported from
+  `nexus-ai-pro/evaluate`.
+- `extractCitations()` and `validateCitations()` read a Markdown link `[text](url)` as a citation,
+  and `[doc-1, doc-2]` as one id; links are ignored and lists are split.
+- The semantic injection classifier embeds a request in one call instead of one per message, and
+  `detectSync()` honours `enabled: false` as `detect()` did.
+
+### Proof
+
+- Grounding and verification, file ingestion, the upload scanner, the PII detector, and both
+  injection detectors are tested to the package's own coverage:
+  - grounding, the PII detector, prompt hardening, and the upload scanner at 100% of lines;
+  - file ingestion, which no test loaded before, at 97%.
+- Each security fix above is a test that names the attack it stops or the false positive it rules
+  out.
+- A canary seeded with a quality regression is rolled back. The proof runs on a real server: 300
+  runs, online evaluation recording the scores, and the guard reading them. A canary whose quality
+  differs only within the noise keeps its share. A difference that 20,000 runs make significant, but
+  that is under the minimum effect, is not a regression either.
+- A community-style adapter, built only from the kit, passes its contract suite. It is a vector store
+  in plain JavaScript inside the clean-install test's consumer project, importing nothing but
+  `nexus-ai-pro/adapter-kit` from the installed tarball. A deliberately broken store fails exactly the
+  checks it breaks.
+- A Nexus agent and a remote agent complete tasks over A2A in both directions:
+  - A client that writes raw JSON-RPC, as the specification describes it, drives the served agent
+    through a conversation, an approval, streaming, cancellation, and each error code.
+  - The client and tool complete tasks against a stub agent written from the specification alone.
+  - One Nexus agent calls another through the tool.
+- A frontend renders a run through AG-UI with a plain `fetch` and Server-Sent Events parser, and
+  no Nexus client code, approval and resume included.
+- An editor's end of an ACP connection approves an edit, and sees the plan, the diff, and the
+  answer.
+- The kernel's tests pass on Node.js, Deno, Bun, and Vercel's edge runtime, and CI runs all four.
+  The tests are written against web-standard APIs only, with no test framework and nothing of Node's,
+  and they cover a provider over `fetch`, the client, a cached graph, an agent, and A2A and AG-UI.
+  A check walks every entry point's imports, static and dynamic. It fails the build when the client,
+  the kernel, a provider adapter, graphs, agents, or a protocol reaches anything Node-only.
+- Every graduated surface passes its contract on every backend it supports. For the context hub,
+  that is memory, files, Redis, and Postgres, with two hubs racing for one label and never both
+  winning. For the retrievers, it is a vector retriever over memory, SQLite, and pgvector, besides
+  the keyword and hybrid retrievers.
+- What the published 2.3.0 package wrote, this release reads, and what it derived, this release
+  derives the same: a SQLite file shared by a 2.3 and a 2.4 worker, a pgvector table, loader ids,
+  retriever rankings, MCP configurations, context bundle versions and exports, insight proposals
+  and error signatures, and canary routing, thread by thread.
+- Each security fix has a test that names the attack, and fails on the code before it. The Git test
+  runs on Linux, where links are tracked as links, and the race test holds both writers until both
+  arrive, so it does not depend on timing.
+
 ## [2.3.0] - 2026-10-06
 
 Agents that act safely, on production retrieval.
@@ -1777,7 +1959,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.3.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.4.0...HEAD
+[2.4.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.3.0...v2.4.0
 [2.3.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.2.0...v2.3.0
 [2.2.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.0.0...v2.1.0

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 80 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
@@ -136,6 +139,7 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [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 |
@@ -156,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 |
@@ -163,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
 
@@ -256,13 +262,16 @@ Shipped so far:
 - 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.
+  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.4 takes the experimental surfaces out of experimental with evidence, adds an adapter kit, and
-speaks the agent protocols beyond MCP from a portable kernel. 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.