nexus-ai-pro 2.2.0 → 2.4.0

package/API_STABILITY.md

@@ -41,6 +41,217 @@ 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.
+
+- `ToolDefinition.capabilities` and the capability grammar; `permissionPolicy()`, `PermissionPolicy`,
+  `PermissionRules`, `PermissionRequest`, `PermissionVerdict`, `PermissionDecision`,
+  `PermissionPolicyLike`, `parseCapability()`, `capabilitiesOf()`, `isSensitiveCapability()`, and
+  `normalizePath()` (`nexus-ai-pro/agent/permissions`); `CreateAgentOptions.permissions`;
+- the sandbox contract: `Sandbox`, its option, result, and isolation types, `sandboxTools()`,
+  `runSandboxConformance()` and its report types, `SandboxPathError` (`nexus-ai-pro/agent/sandbox`).
+  `processSandbox()` is a development reference and may change; conformance checks may be added;
+- `NodeOptions.effects` and `interrupts`, `CompileOptions.tools`, `GraphToolDescription`, and the lint
+  codes `SENSITIVE_TOOL_WITHOUT_APPROVAL`, `UNDECLARED_TOOL_CAPABILITIES`, and
+  `SIDE_EFFECT_BEFORE_INTERRUPT`;
+- `nexus-ai-pro/agent/middleware` and every middleware and option type on it;
+  `AgentMiddleware.wrapModelCall`, `AgentMiddlewareContext`, `AgentModelCallContext`, the third
+  argument of `wrapToolCall`, `next(call)`, and `AgentStopReason` `'stopped'`. The PII patterns
+  may be tightened in a minor release to cut false positives, and new `PiiKind` members may be
+  added;
+- `nexus-ai-pro/server/auth`: `jwtAuth()`, `apiKeyAuth()`, `trustedProxyAuth()`, `anyAuth()`,
+  `createJwtVerifier()`, `hashApiKey()`, `JwtError` and its codes, and every option type. New
+  `JwtAlgorithm` and `JwtErrorCode` members may be added;
+- `Principal.roles`, `method`, and `claims`; `GraphRunOptions.principal`, `NodeContext.principal`,
+  `WorkflowRunOptions.principal`, and `WorkflowContext.principal`; `ToolContext` and the second
+  argument of `ToolDefinition.execute`; `AgentMiddlewareContext.principal` and
+  `PermissionRequest.principal`. A checkpoint's `metadata.userId` is recorded when a run has a
+  principal with a subject;
+- `SparseRetriever`; `PostgresKeywordIndex` and `keywordIndexMigrations()`
+  (`nexus-ai-pro/postgres/fulltext`); `ElasticsearchKeywordIndex` and `ElasticsearchError`
+  (`nexus-ai-pro/rag/elasticsearch`); and every reranker and option type on
+  `nexus-ai-pro/rag/rerankers`. The default endpoints of hosted rerankers follow their providers'
+  current API versions;
+- `nexus-ai-pro/rag/pipeline`: `createIngestionPipeline()`, `ingestionExecutor()`, and their types.
+  The manifest's layout under `['nexus', 'ingestion', <name>]` is stable: a later release reads a
+  manifest an earlier one wrote;
+- `nexus-ai-pro/deep-agent`: `createDeepAgent()`, `DeepAgentOptions`, `DeepSubagent`, and
+  `DeepSkill`, and the names and arguments of the tools it gives the model (`write_todos`,
+  `delegate`, `load_skill`, `edit_file`). The wording of its system prompt may change in any release.
+
 ## 2.2 stage (2.2.0)
 
 Everything 2.2 adds is stable from the start and additive: no default changes meaning.
@@ -579,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.
 
@@ -593,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.
 
@@ -605,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
@@ -621,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.
 
@@ -633,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,328 @@ 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.
+
+### Added
+
+- **Capabilities and permission policies.** A tool declares what each call does —
+  `filesystem:write:<path>`, `network:<host>`, `shell:<command>`, `code`, or an effect of the
+  application's own — as a list or a function of its arguments. `permissionPolicy()`, on the new
+  `nexus-ai-pro/agent/permissions`, grants filesystem globs, network hosts, and shell command
+  prefixes, and decides each call: allow, deny, or ask. Paths are normalized before any grant sees
+  them, and a command that chains, pipes, or substitutes is never granted by a prefix.
+  `createAgent({ permissions })` enforces it before a tool runs: a denied call never runs, an `ask`
+  interrupts as `interruptOn` does, and arguments an approver edits are decided again.
+- **A sandbox contract**, on the new `nexus-ai-pro/agent/sandbox`: the `Sandbox` interface a
+  container, VM, or hosted interpreter fills; `sandboxTools()`, whose calls declare exactly the
+  command or path they use; `runSandboxConformance()`, which proves any sandbox against the
+  contract; and `processSandbox()`, a reference for development that is never a security boundary
+  and says so.
+- **The linter reads capabilities.** `SENSITIVE_TOOL_WITHOUT_APPROVAL` reports a tool that writes, runs
+  commands or code, or reaches the network with neither approval nor a policy;
+  `UNDECLARED_TOOL_CAPABILITIES` a tool whose effects cannot be judged; and
+  `SIDE_EFFECT_BEFORE_INTERRUPT` a node that declares `effects` and `interrupts`. An agent's graph
+  describes its tools for it.
+- **A middleware catalog**, on the new `nexus-ai-pro/agent/middleware`, each a separate import:
+  `modelRetry()`, `modelFallback()` (to another model or another client), `dynamicModel()`,
+  `toolRetry()` (which by default repeats only a call that cannot have changed anything),
+  `toolSelector()` (by rule, embedding similarity, or both), `contextEditor()` (clears old tool
+  results in batches, so a prompt cache keeps working), `piiMiddleware()` (validated card numbers
+  and IBANs; redact, mask, hash, or block), `humanApproval()` (per call, in band or out of band),
+  `modelCallLimit()` (per run and per thread, the thread count shared through the store), and
+  `filesystemContext()` (instruction files in, large results out to a file). The three existing
+  middleware are there too.
+- **A wider middleware seam.** `wrapModelCall` wraps the model call itself, and may call `next()`
+  again to retry or fall back. Every hook receives an `AgentMiddlewareContext`: the state, the
+  store, the thread and tenant, the run's signal, and `interrupt()`. `context.stop()` ends a run
+  with an answer and the new `stopReason: 'stopped'`. A `wrapToolCall` can pass `next()` changed
+  arguments, which the permission policy decides again.
+- **Server authentication**, on the new `nexus-ai-pro/server/auth`. It is built on Web Crypto, with no
+  dependency:
+  - `jwtAuth()` takes an identity provider's key set (cached, and refetched when a token names a new
+    key), a public key, or a shared secret, and checks issuer, audience, expiry, and age. It refuses
+    `alg: none` and key confusion, and requires an audience with a key set.
+  - `apiKeyAuth()` compares keys by their SHA-256 hash, from `hashApiKey()`.
+  - `trustedProxyAuth()` refuses to exist without proof that the proxy sent the request.
+  - `anyAuth()` combines hooks.
+  - `createJwtVerifier()` verifies tokens outside the server.
+- **One Principal, everywhere a run goes.** It gains `roles`, `method`, and `claims`.
+  - Graph and workflow runs take a `principal`, which nodes read as `context.principal`. Its tenant
+    becomes the run's, and its subject is recorded on every checkpoint and in the run's trace.
+  - `graphAssistant()` passes the authenticated caller on.
+  - Tools receive a `ToolContext` as the second argument of `execute`: the principal, the thread
+    and tenant, the run's signal, and the tenant's store.
+  - Middleware and permission policies see the principal too.
+- **Sparse retrieval as a contract.** A `SparseRetriever` is keyword search that takes writes, so it
+  fuses with vector search and stays in step with a vector store. `KeywordIndex` is one. Two more
+  ship:
+  - `PostgresKeywordIndex` (`nexus-ai-pro/postgres/fulltext`) uses Postgres full-text search, with a
+    GIN index and ranking in the database. With `shared`, it searches a pgvector table through a
+    generated column, so hybrid search keeps one copy of the data.
+  - `ElasticsearchKeywordIndex` (`nexus-ai-pro/rag/elasticsearch`) works with Elasticsearch or
+    OpenSearch over the REST API, with no client library.
+- **Rerankers**, on the new `nexus-ai-pro/rag/rerankers`, with no SDK:
+  - `cohereReranker()`, `voyageReranker()`, and `jinaReranker()` for hosted APIs;
+  - `teiReranker()` for a self-hosted cross-encoder;
+  - `httpReranker()` for any other API;
+  - `crossEncoderReranker()` for a model run in process.
+- **Durable ingestion**, on the new `nexus-ai-pro/rag/pipeline`. `createIngestionPipeline()` keeps a
+  manifest in any `Store`: each document's content version, its chunking, the embedding model, and
+  each chunk's version. A run:
+  - embeds only new and changed chunks; chunks are named by their text, so one that only moved keeps
+    its embedding;
+  - deletes the chunks and documents that are gone;
+  - keeps keyword indexes in step;
+  - writes to the stores before the manifest.
+
+  `ingestionExecutor()` runs it as a durable operation, and a retry starts at the document the
+  failed attempt stopped on.
+- **A deep-agent preset**, on the new `nexus-ai-pro/deep-agent`. `createDeepAgent()` is
+  `createAgent()` composed with:
+  - a plan, kept in the transcript;
+  - a sandboxed workspace, with `edit_file` for precise changes and commands granted by name;
+  - helpers behind one `delegate` tool, which never get a tool that needs approval;
+  - skills loaded on demand;
+  - instruction files and context offloading;
+  - context editing, optional tool selection, and a default permission policy.
+
+  It returns the same compiled graph as any agent; it is not a new engine.
+- `processSandbox()` loads Node's modules when first used, so `nexus-ai-pro/agent/sandbox`, and a
+  deep agent over a container sandbox, import on any runtime.
+
+### Fixed
+
+- `MemoryStore` swept every item for expiry on every write, so writing n items took time
+  proportional to n². It now sweeps only once an item has a time to live, and at most once a second.
+  Expired items were already hidden from reads.
+
+- `limitToolCalls()` counted calls in memory shared by every run of an agent, so one thread's calls
+  used up another's limit, and the count never reset. It now counts per run from the transcript.
+- A subgraph run through `asNode()` now runs for its parent's tenant, so its store is the tenant's
+  view, as the parent's is.
+- `sandboxTools()` file tools accept a path that names the mount, such as `/workspace/notes.txt`,
+  as well as one relative to it, and say in their descriptions which to use.
+
+### Proof
+
+- In a real agent tool loop, a write outside the workspace and a request to an unlisted host are
+  refused before their tools run, and a granted command that needs approval waits for a person.
+- The process sandbox passes the conformance suite, and a sandbox that leaks the host's environment
+  and writes outside its root fails exactly those two checks.
+- An agent over 150 tools completes 40 tasks, a third of them needing two tools, with
+  `toolSelector()` at equal quality: every task succeeds either way. Input tokens per task fall from
+  about 64,000 to about 5,200, and latency by about 70%: the model's time computed from
+  each request's size, plus the agent's own measured time. Two experiments, reported by
+  `compareExperiments()`, show it.
+- Each middleware is proved in a real agent loop. For example:
+  - a charge that timed out is never retried;
+  - an approver who raises a refund past what the policy allows has the edit refused;
+  - two agents sharing a store share one thread budget;
+  - a 45,000-character tool result reaches the transcript as a preview and a file.
+- A JWT from a test identity provider is verified against its key set and reaches an agent's tool
+  call as a `Principal` with its subject, tenant, roles, and scopes.
+  - The tool's writes land in that tenant's view of the store.
+  - The checkpoint records who ran the step.
+  - Another tenant's token gets 404 for the thread.
+  - Expired, wrong-audience, wrong-issuer, unsigned, and forged tokens are refused.
+  - The provider rotates its key with one refetch.
+- On the stored support dataset, on real Postgres with full-text search and pgvector, hybrid retrieval
+  beats vector-only: recall@5 0.71 → 0.97 and mean reciprocal rank 0.51 → 0.71, both with a 95%
+  interval above zero. A hosted reranker and a local cross-encoder, compared in the same experiment,
+  each lift mean reciprocal rank to 0.97. One contract test runs against all four keyword indexes.
+- An ingestion of 100,000 documents dies halfway inside a durable operation. Its retry starts at the
+  document the first attempt stopped on, and embeds no chunk that had finished. A second run after
+  ten documents are edited embeds exactly ten chunks and deletes their old versions.
+- A deep agent completes a multi-step task on a fixture repository inside the reference sandbox. It
+  plans, runs the failing test, reads and edits the bug, verifies the fix, has a helper review it,
+  loads a skill, and records the change; the test then passes outside the agent. Along the way, a
+  30,000-character log is offloaded to a file. The default policy refuses an unlisted command, a
+  chained command, a write outside the workspace, and an ungranted tool.
+
 ## [2.2.0] - 2026-10-05
 
 Production scale and safe upgrades. Every database schema is versioned, so an upgrade applies only
@@ -1637,7 +1959,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.2.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
 [2.0.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.25.0...v2.0.0