nexus-ai-pro 2.4.0 → 2.5.0

package/API_STABILITY.md

@@ -41,6 +41,91 @@ 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.5 stage (2.5.0)
+
+Everything 2.5 adds is stable from the start and additive.
+
+New and stable:
+- `putIfVersion()`, optional on `Store` and `ServerStateStore`, and its implementations;
+  `Deployments.atomicChanges`; `ScalingSnapshot.atomicChanges`;
+- `nexus-ai-pro/postgres/tenancy`: `PostgresTenantUsage`, `PostgresTenantUsageOptions`,
+  `tenantUsageMigration()`, and `tenantUsageMigrations()`; the `tenancy` member of
+  `PostgresAdapter`;
+- `OperationStoreFilter.kinds`, `OperationStoreStats.queuedByKind`, `RevisionRequest.queued`,
+  `RevisionChoice.local`, `ScalingSnapshot.queuedByRevision`, and the
+  `nexus_server_runs_queued_by_revision` metric.
+
+- signing on `nexus-ai-pro/context-hub`: `ContextHubOptions.signer`, `keyring`, and `requireSignature`;
+  `ContextHub.verify()` and `ContextVerification`; `ContextBundle.signatures`; `ContextSignatureError`;
+  `generateContextKey()`, `ed25519Signer()`, `ed25519Keyring()`, `contextDigest()`, and the signing
+  types. The signed digest's format is `nexus-context-signature`, format version 1, and a later release
+  verifies it;
+- `metadata.context` on a traced model call;
+- on `nexus-ai-pro/server/deployments`, experimental with the rest of it: `BucketStrategy`,
+  `DeploymentRecord.bucketStrategy`, `RevisionedAssistantOptions.bucketStrategy`, the `bucketing`
+  change and `Deployments.bucketing()`, the strategy argument of `bucket()`; `recordRun()`,
+  `rollups()`, `flushRollups()`, `stats({ deployment })`, `DeploymentRollup`, `RevisionRollup`, and
+  `DeploymentsOptions.rollupMs`; `CanaryGuardOptions.from`. `ServerDeployments` gains an optional
+  `recordRun()`, and `RunManagerOptions.deployments`. The positions `fnv1a-v1` and `hash-v2` give a key
+  never change;
+- the doctor's `settings` check; `RedisOperationStore.indexed`; `Tracer.store` and
+  `Tracer.incremental`;
+- `nexus-ai-pro/evaluate/threads`, experimental: `simulatedUser()`, `scriptedUser()`,
+  `conversationTarget()`, `graphThreadAgent()`, `formatThread()`, `goalReached()`,
+  `goalCompletion()`, `turnCount()`, `turnScores()`, and their types. The score keys `goal_reached`,
+  `goal_completion`, `turns`, and `turn_score` are stable once the entry point graduates.
+
+The studio now refuses, as the compatibility rules allow for security: a change whose body is not
+`application/json`, with `415`; a body that is not a JSON object, with `400`; a body past
+`maxBodyBytes`, with `413`; and a list `limit`, `hours`, or `days` past its ceiling, with `400`. With
+accounts, only a bearer `Authorization` header stands in for the page token. The agent server refuses
+an assistant or revision named after a built-in property, such as `constructor`. Also stable from
+2.5: `StudioOptions.maxBodyBytes`, `Studio.routes` and `StudioRoute`, and
+`MemoryStudioJournalOptions.maxComments`.
+
+### Graduation
+
+Two more surfaces leave experimental status in 2.5, by the same checklist as in 2.4. Every test named
+here runs in CI.
+
+**Deployments** (`nexus-ai-pro/server/deployments`):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | Atomic changes on the memory server store and the memory, Redis, Postgres, and SQLite stores: `tests/atomic-deployments.test.ts`; routing, canaries, and guards: `tests/deployments.test.ts`, `tests/fair-canaries.test.ts`; revision pools: `tests/revision-pools.test.ts` |
+| Crash recovery | A change is one compare-and-set write, so a crash leaves the old record or the new one; a drained replica hands its runs to another: `tests/deployments.test.ts`. A replica that dies loses at most its last `rollupMs` of counts, which the guide states |
+| Concurrency | Ten replicas making mixed changes at once land in one linear history on every store: `tests/atomic-deployments.test.ts` |
+| Load | `deployments.route-canary` and `deployments.bucket` in `surface-budget.json` |
+| Tenant isolation | n/a: a deployment is an assistant's configuration, not a tenant's data. The runs it routes are operations, which are isolated: `tests/tenant-isolation.test.ts` |
+| Security | [Review](./SECURITY.md#deployments): four findings fixed, two documented limitations |
+| Upgrade | A 2.3 replica's deployment routes the same here, and every thread keeps its bucket: `tests/upgrade-previous-minor.test.ts` |
+| Soak | 50,000 route, admit, and release cycles, 500 replica lifecycles, and 20,000 runs counted and judged from rollups, with no timer left running |
+
+**The studio and its accounts** (`nexus-ai-pro-studio`):
+
+| Requirement | Evidence |
+| --- | --- |
+| Conformance | Every view over its sources, with and without accounts: `studio/test/studio.test.ts`, `studio/test/team.test.ts`, `studio/test/deployments.test.ts` |
+| Crash recovery | n/a: the studio keeps no state but its journal, which appends one line per entry and skips a line a crash cut short: `studio/test/security.test.ts` |
+| Concurrency | n/a: every change goes through its source's own API, where races are settled: prompt and bundle labels by compare-and-set, deployments by `putIfVersion()` |
+| Load | 500 signed-in reads within a budget relative to the machine: `studio/test/security.test.ts` |
+| Tenant isolation | A studio over `tenantScope()` views lists one tenant's runs, and another tenant's trace is not found: `studio/test/security.test.ts` |
+| Security | [Review](./SECURITY.md#the-studio-and-its-accounts): ten findings, all fixed; every route fuzzed by every role and with hostile input: `studio/test/security.test.ts` |
+| Upgrade | The journal reads what 2.4 wrote, and accounts and configuration load unchanged: `studio/test/security.test.ts`, `studio/test/team.test.ts` |
+| Soak | 2,000 sign-in, read, and change cycles with flat memory, and 200 servers started and closed with no handle left open: `studio/test/security.test.ts` |
+
+**Still experimental**, each with what remains:
+- **Images.** Recorded live conformance must pass on all three backends. The scheduled live workflow
+  records it wherever a backend's credential is set, and none has run with all three yet.
+- **The Qdrant, Redis, Pinecone, Weaviate, and Chroma vector stores.** The contract must pass against
+  the real servers. The scheduled live workflow runs it against each one, Pinecone when its secret is
+  set, and its evidence is published when it has passed against all five.
+
+A queued run's kind now names its revision, as `assistant:<id>@<revision>`. Code that reads the
+server's runs by the `assistant:` prefix, as the server itself does, is unaffected.
+
+A state store without `putIfVersion()` keeps its earlier behavior.
+
 ## 2.4 stage (2.4.0)
 
 Everything 2.4 adds is stable from the start and additive. These security fixes tighten behavior,

package/CHANGELOG.md

@@ -4,6 +4,151 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-10-09
+
+Graduation finished, and conversations evaluated.
+
+### Added
+
+- **Deployment changes that are atomic across replicas.**
+  - The long-term `Store` contract and the server's `ServerStateStore` gain an optional
+    `putIfVersion()`. It writes a record only when the stored one's `version` is still the version
+    the change was decided on, in one atomic step. The memory, Postgres, and SQLite stores, the server's
+    memory store, and the Redis store (when its client has `eval`) have it, and `fromStore()` passes
+    it on.
+  - A deployment change uses it. A replica that loses the race decides again on the winner's record,
+    so two changes made at once both land, in order. A change made on an `expectedVersion` is
+    refused with `DEPLOYMENT_CONFLICT` instead. Two replicas starting at once seed one record.
+  - `Deployments.atomicChanges` and `/scaling`'s `atomicChanges` say whether the state store
+    offers this.
+- **Tenant usage in Postgres**, on the new `nexus-ai-pro/postgres/tenancy`: `PostgresTenantUsage`, so
+  every replica enforces one tenant limit without Redis. The `tenancy` adapter joins
+  `postgresMigrations()` and `nexus db migrate`.
+- **Revision worker pools.** A worker image carries some revisions of an assistant, and claims only
+  the runs routed to them, so a new revision ships in a new image beside the old one.
+  - A queued run's kind names its revision, as `assistant:<id>@<revision>`, and a worker claims with
+    the kinds of the revisions it registered.
+  - A run that will wait in the queue is routed over the revisions any fresh worker reports
+    (`RevisionRequest.queued`), so the API replicas send traffic to a revision only a new image
+    carries. `RevisionChoice.local` says whether the answering replica has it.
+  - `/scaling` reports `queuedByRevision`, and `/metrics` `nexus_server_runs_queued_by_revision`, so an
+    autoscaler starts the pool a waiting revision needs.
+  - `OperationStoreFilter.kinds` filters by exact kinds on every operation store, and
+    `OperationStoreStats.queuedByKind` counts queued records per kind. `claimQueued()` checks each
+    candidate against the filter itself, for a store that ignores one.
+- **Signed context bundles.**
+  - A hub with a `signer` signs every new version with Ed25519, through Web Crypto, so on any
+    runtime. The signature covers the bundle's content and its pinned prompts' content, under the
+    full SHA-256 that `contextDigest()` computes, not the 12-digit version.
+  - A hub with a `keyring` checks signatures with `verify()`. With `requireSignature`, it refuses a
+    bundle without a trusted signature, with a `ContextSignatureError`, on `import()` and whenever
+    `resolve()` or `renderPrompt()` serves one.
+  - An import keeps the signatures that claim its content, and adds the importing hub's. That is how
+    keys rotate.
+  - `generateContextKey()`, `ed25519Signer()`, and `ed25519Keyring()` make and load keys, as JSON Web
+    Keys or Web Crypto keys.
+- **Canaries that stay fair.**
+  - A deployment records a `bucketStrategy`. `hash-v2` mixes the thread id's hash with
+    MurmurHash3's finalizer, so sequential ids such as `user-1` to `user-500` split as evenly as random
+    ones. `fnv1a-v1` stays the default, and every deployment recorded before keeps it, so no thread
+    moves through an upgrade. `Deployments.assistant()` takes `bucketStrategy`; `bucketing()` and a
+    `bucketing` change switch a recorded deployment. `bucket()` takes the strategy.
+  - Every replica counts the runs it finishes, per revision, in a rollup under the deployment version
+    they were routed with: counts, latency in buckets 5% apart, and cost. `stats()` with `deployment`
+    and `rollups()` sum them in one read, and `GET /deployments/:assistant` reports them.
+  - `watchCanaries({ from: 'rollups' })` judges a canary on every run since the split last changed,
+    instead of the latest 2,000 run records.
+- **A doctor that knows the opt-in settings.** `nexus doctor` and `diagnose()` warn, in a new
+  `settings` check, when a `RedisOperationStore` runs without `index: true`, and when a `Tracer`
+  writes to a persistent store without `incremental`. Each warning names the setting that fixes it.
+  Both stay opt-in through 2.x. `RedisOperationStore.indexed`, `Tracer.store`, and
+  `Tracer.incremental` report the settings.
+- **Graduation.** Deployments and the studio leave experimental status, each with its checklist and
+  evidence in `API_STABILITY.md` and a threat review in `SECURITY.md`.
+- **The studio's routes, listed.** `Studio.routes` gives every route's method, path, role, and audit
+  action. `StudioOptions.maxBodyBytes` bounds a request body, and
+  `MemoryStudioJournalOptions.maxComments` bounds the comments kept in memory.
+- **Whole conversations, evaluated** (`nexus-ai-pro/evaluate/threads`).
+  - `simulatedUser()` plays a user with a goal and a persona, driven by a model, and says when the goal
+    was met or when it gives up. `scriptedUser()` follows a script, for deterministic tests.
+  - `conversationTarget()` is an `evaluate()` target that holds a conversation per example and returns
+    the `Thread`: every turn, how long each answer took, the messages the agent added, and how it
+    ended. `graphThreadAgent()` drives an agent from `createAgent()`, which keeps its own tool calls
+    from turn to turn.
+  - Thread evaluators: `goalReached()`, `goalCompletion()` with a judge, `turnCount()`, and
+    `turnScores()`, which scores every turn with an evaluator of single answers and names the turn
+    where the conversation went wrong.
+- **Context on every trace.** A traced model call records `metadata.context` beside
+  `metadata.prompt`, so a trace query or an insight narrows by bundle version.
+
+### Security
+
+- **The studio**, from its threat review:
+  - A request body is refused with `413` past `maxBodyBytes`, 1 MiB by default, as it arrives and
+    before anyone is signed in. Before, a body was read whole into memory first.
+  - With accounts, only a bearer `Authorization` header stands in for the page token. Before, any
+    `Authorization` header did, and a browser adds Basic credentials to another site's request by
+    itself, so a sign-in proxy that uses Basic authentication let another site make changes.
+  - A change's body must be `application/json` (`415` otherwise) and a JSON object (`400`
+    otherwise).
+  - A change refused for want of the page token is recorded in the audit log.
+  - Graphs and review queues are looked up among the application's own entries, so a name such as
+    `constructor` no longer reaches the prototype.
+  - Malformed percent-encoding in a path is a `400`, not a server error.
+  - `limit`, `hours`, and `days` have ceilings: 1,000 items, 10,000 audit entries, 90 days of
+    issues, and 366 days of costs.
+  - The memory journal keeps at most 10,000 comments.
+  - The server no longer sends an internal error's message, and logs it instead.
+  - Only `http` and `https` pull-request links are rendered.
+- **The agent server** refuses an assistant or revision named after a built-in property, such as
+  `constructor`, with `400`. Before, such a run was accepted and failed when it ran.
+
+### Fixed
+
+- A worker that lacked the revision a run was routed to ran the assistant's live revision instead,
+  and the run still recorded the revision it was routed to. A worker now claims only runs of revisions
+  it carries.
+
+### Proof
+
+- The studio's threat review is a test: every route is called by every role and refuses the roles
+  below its own, recording each refusal; over 2,000 requests with hostile paths, queries, and bodies
+  all answer below `500`, and no prototype is polluted. 2,000 sign-in, read, and change cycles leave
+  the heap flat, and 200 servers start and close with no handle left open.
+- The doctor's seeded deployment warns about a Redis operation store without its index and a tracer
+  writing to a persistent store at the end of each trace, and the same deployment with both settings
+  turned on passes.
+- Ten replicas make mixed changes to one deployment at once (canaries, splits, promotions,
+  rollbacks, and a bucketing change), held until all ten arrive, on the memory server store and the
+  memory, Redis, Postgres, and SQLite stores. Every change lands, each with a version of its own, and
+  the history is one linear sequence.
+- Over 48 sets of 500 sequential thread ids, `hash-v2` places a canary's share within 2.3 standard
+  deviations of its weight, as random placement does; `fnv1a-v1` strays by up to 9.9. Over 10,000
+  sequential ids, `hash-v2` is within half a point at every weight.
+- A canary that fails 0.8% of the time against 0.5% is held by a guard over the latest 2,000 run
+  records, and rolled back by a guard over rollups, which counts all 100,000 runs from three replicas
+  in one read.
+- A simulated user holds 50 conversations with each of two versions of a support agent built with
+  `createAgent()`. The thread evaluators score every conversation, and `compareExperiments()` finds
+  the second version better on goals met, the judge's verdict, turns taken, and per-turn scores, with
+  no regression; the reverse comparison regresses. A conversation that failed names the turn where it
+  went wrong.
+- A signed bundle imports into a hub that requires signatures. It is refused there when it is unsigned,
+  or edited after export even with its version recomputed. One edited where it is stored is refused
+  when it is served. A re-import through a hub with a new key keeps both signatures, so the bundle
+  stays trusted once the old key is retired. Every traced model call rendered from it names its
+  context and prompt versions.
+- Two worker images drain one queue, one carrying v1 and the other v1 and v2, with an API replica
+  that carries only v1. Under a 50% canary, every run executes on the revision it was routed to, and
+  only the image with v2 runs v2. A run for a pool scaled to zero waits, is counted per revision on
+  `/scaling` and `/metrics`, and runs when that pool returns.
+- Two replicas changing one deployment in the same instant both land, on the memory, Redis,
+  Postgres, and SQLite stores. The race test holds both writers until both arrive, and the same race
+  on a store without `putIfVersion()` loses a change. Of two changes made on one expected version,
+  exactly one is refused.
+- Ten workers spending one tenant budget lose nothing, and never over-grant a slot, on Postgres as
+  on memory and Redis.
+
 ## [2.4.0] - 2026-10-08
 
 Graduation and interoperability.
@@ -1959,7 +2104,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.4.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.5.0...HEAD
+[2.5.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.4.0...v2.5.0
 [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

package/README.md

@@ -266,12 +266,17 @@ Shipped so far:
 - 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.
+  client, providers, graphs, and agents running on Deno, Bun, edge runtimes, and browsers;
+- 2.5 graduation finished, and conversations evaluated: deployments that change atomically across
+  replicas, revision worker pools, fair canaries judged on every run, and the studio out of
+  experimental after a threat review; Postgres tenant usage; signed context named on every trace;
+  simulated users and thread evaluators; and a doctor that knows the opt-in settings.
 
 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.
-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.
+Next, 2.6 completes the agent protocols: tool progress on every stream, AG-UI deltas and frontend
+tools, A2A tasks and ACP sessions that survive a restart, and a browser in CI. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
+releases after it.
 
 ## Before Production
 

package/SECURITY.md

@@ -52,7 +52,7 @@ what it could do with that input. Each review is published here with its finding
 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.
+These reviews were done for 2.4, and for 2.5 where a review says so.
 
 ### SQLite adapters
 
@@ -168,7 +168,18 @@ server trusts by itself.
 
 Findings: none.
 
-### Deployments (reviewed; still experimental)
+### Deployments
+
+Reviewed for 2.4, and again for 2.5, when it graduated.
+
+Trust boundary: a deployment is changed by an admin, a canary guard, or the studio's admins; a run
+names its assistant, and optionally a revision, in a request from any caller with the write scope.
+Replicas, guards, and the studio share the server's state store, which they trust.
+- Every change is decided on the version it read and written by compare-and-set, on every included
+  state store, so a stale change never overwrites a newer one.
+- A guard acts on the version it judged, so guards on every replica never undo each other.
+- A replica writes rollups only to its own record. Counts are as trustworthy as the state store, as
+  run records already are.
 
 Findings:
 - **Fixed in 2.4: one caller's ratings could decide a canary.** A canary was judged on feedback
@@ -177,10 +188,68 @@ Findings:
   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.
+- **Fixed in 2.5: two replicas changing one deployment in the same instant could lose one change.**
+  The state store gained `putIfVersion()`, and a replica that loses the race decides again on the
+  winner's record. Proof: ten replicas held until all arrive make mixed changes on every store, and
+  every change lands in one linear history.
+- **Fixed in 2.5: a name from a request could reach an object's prototype.** A run for the assistant
+  `constructor`, or naming the revision `constructor`, was accepted and failed when it ran. Only an
+  application's own assistants and revisions are looked up now, and both are refused with `400`.
+- **Documented limitation: `fnv1a-v1` spreads sequential ids unevenly.** It stays the default, since
+  its positions are part of the stability promise. `hash-v2` spreads them evenly, opt-in per
+  deployment.
+- **Documented limitation: a replica that dies loses the runs it counted in its last `rollupMs`.**
+  Rollups are statistics; the run records stay whole.
+
+### The studio and its accounts
+
+Reviewed for 2.5, when it graduated.
+
+Trust boundary: anyone who can reach the port, before signing in; a signed-in person, limited by
+their role; a page on another site acting through a signed-in person's browser; and the data the
+studio shows, which traces, models, and people wrote.
+- The `Host` header must be a loopback name or one in `allowedHosts`, which closes DNS rebinding.
+- Tokens are compared in constant time. A token in the URL is moved into an HTTP-only, `SameSite=Strict`
+  cookie, `Secure` over HTTPS, and taken out of the address bar. `headerAuth()` trusts identity
+  headers only with the proxy's secret or from its addresses.
+- Every change needs a page token in a header, an HMAC of the user and their role under the server's
+  secret, which another site can neither read nor send. Every refusal is audited.
+- Every response carries a content security policy without inline script, `nosniff`, `no-store`,
+  and no referrer. The page inserts every value as text.
+
+Findings, each fixed in 2.5 with a test in `studio/test/security.test.ts`:
+- **A request body was read whole before anyone signed in.** Anyone who could reach the port could
+  fill the server's memory. A body past `maxBodyBytes`, 1 MiB by default, is now refused with `413`
+  as it arrives.
+- **Behind a sign-in proxy that uses Basic authentication, another site could make a change.** Any
+  `Authorization` header counted as proof that a script, not a browser, sent the change. But a
+  browser attaches Basic credentials to another site's request by itself. Only a bearer token counts
+  now, and a change's body must be `application/json`, which a form on another site cannot send.
+- **A change refused for want of the page token was not audited.** It is now, under the person whose
+  browser sent it, so a forged change leaves a trace.
+- **A name from the URL could reach an object's prototype.** A graph or review queue named
+  `constructor` failed with a server error. Only an application's own entries are looked up.
+- **A body that was not a JSON object reached handlers that read its fields.** `null`, an array, or a
+  number failed with a server error. Such a body is now refused with `400`.
+- **A path with malformed percent-encoding failed with a server error.** It is now a `400`.
+- **A viewer could ask a store for everything it holds.** `limit`, `hours`, and `days` had no
+  ceiling. A list now returns at most 1,000 items, the audit log 10,000 entries, the issues view 90
+  days, and the costs view 366 days; past that, the request is refused with `400`.
+- **The memory journal kept every comment.** It now keeps the latest 10,000, as it keeps audit entries.
+- **The server answered an internal error with its message.** That reply could reach anyone who can
+  reach the port. It now says only that the request failed, and logs the error on the server.
+- **A proposal's pull-request link was rendered as stored.** The content security policy already
+  blocked a `javascript:` address. Only `http` and `https` links are rendered now.
+
+Documented limitations, which the studio guide states:
+- The studio has no tenants of its own. Every account sees every source the studio is given, so a
+  tenant's people get a studio over that tenant's `tenantScope()` views.
+- A page token stays valid while the secret, the user, and their role do. Rotate `secret` to revoke
+  every page at once.
+- Someone without a session who opens another person's personal link is signed in as that person.
+  The page shows who is signed in.
+- `FileStudioJournal` reads its whole file for each listing, so rotate a long-lived one.
+- The playground spends model budget, which is why it needs the editor role.
+
+The fuzzing behind these: every route called by every role, and over 2,000 requests with hostile
+paths, queries, and bodies. Each must answer below `500`, and no prototype may be polluted.

package/dist/context-hub/hub.d.ts

@@ -2,6 +2,7 @@ import type { GateResult } from '../prompts/errors.js';
 import type { PromptRegistry } from '../prompts/registry.js';
 import type { PromptHistoryEntry, PromptLabel, PromptStore, PromptVersion, RenderedPrompt, RenderOptions } from '../types/prompts.js';
 import { type ContextDiff } from './diff.js';
+import { type ContextKeyring, type ContextSignature, type ContextSigner } from './signing.js';
 /** A prompt a bundle uses, pinned to one content version of the prompt registry. */
 export interface ContextPromptPin {
     /** The prompt's name in the registry. */
@@ -61,6 +62,8 @@ export interface ContextBundle extends ContextBundleDefinition {
     author?: string;
     /** The version that was newest before it. */
     parent?: string;
+    /** Signatures over its content and its pinned prompts' content. Not part of the version. */
+    signatures?: ContextSignature[];
 }
 /** Which bundle version is being used, as experiments and traces record it. */
 export interface ContextReference {
@@ -125,9 +128,33 @@ export interface ContextHubOptions {
     gates?: Record<string, readonly ContextPromotionGate[]>;
     /** Called after every recorded change. */
     onChange?: (entry: ContextHistoryEntry) => void | Promise<void>;
+    /**
+     * Signs every new version, over its content and its pinned prompts' content, so another hub can
+     * check where it came from. Signing a bundle that pins prompts needs `prompts`.
+     */
+    signer?: ContextSigner;
+    /**
+     * The keys whose signatures this hub trusts, for `verify()`, and for `requireSignature`. A signature
+     * by a key the keyring does not hold is kept, but never trusted.
+     */
+    keyring?: ContextKeyring;
+    /**
+     * Refuses any bundle without a valid signature by a key in `keyring`: on import, and whenever a
+     * version is served through `resolve()` or `renderPrompt()`.
+     */
+    requireSignature?: boolean;
     /** Replaces the system clock, for tests. */
     now?: () => Date;
 }
+/** What `ContextHub.verify()` found. */
+export interface ContextVerification {
+    /** Whether a key in the keyring signed exactly this content. */
+    trusted: boolean;
+    /** The digest the content has now. */
+    digest: string;
+    /** The signature that verified, when one did. */
+    signature?: ContextSignature;
+}
 /** Base class for context hub errors, each with a stable `code`. */
 export declare class ContextHubError extends Error {
     /** Stable code, such as `CONTEXT_NOT_FOUND`. */
@@ -160,6 +187,18 @@ export declare class ContextPromotionError extends ContextHubError {
     /** Every gate's verdict. */
     results: GateResult[]);
 }
+/** Raised when a bundle has no signature the hub trusts, or its signatures do not match its content. */
+export declare class ContextSignatureError extends ContextHubError {
+    /** The bundle. */
+    readonly bundle: string;
+    /** The version. */
+    readonly version: string;
+    constructor(
+    /** The bundle. */
+    bundle: string, 
+    /** The version. */
+    version: string, reason: string);
+}
 /** Raised when a bundle definition, a pin, or an import is invalid. */
 export declare class ContextDefinitionError extends ContextHubError {
     constructor(message: string);
@@ -182,6 +221,8 @@ export declare class ContextHub {
     /** Where versions, labels, and history live. */
     readonly store: PromptStore;
     private readonly now;
+    /** Versions already verified as trusted, which never change. */
+    private readonly trusted;
     constructor(options?: ContextHubOptions);
     /**
      * Commits a bundle and returns its version. Unchanged content returns the existing version and
@@ -193,8 +234,15 @@ export declare class ContextHub {
         author?: string;
         label?: string | readonly string[];
     }): Promise<ContextBundle>;
+    private commitSigned;
     /** A version by content version, label, or `latest`, the default. Throws `ContextNotFoundError` when there is none. */
     get(name: string, ref?: string): Promise<ContextBundle>;
+    /**
+     * Whether a key in the hub's keyring signed exactly this bundle's content, and its pinned prompts'
+     * content as the prompt registry holds them. A version's answer never changes, so it is checked
+     * once.
+     */
+    verify(bundle: ContextBundle): Promise<ContextVerification>;
     /** A version with the reference experiments and traces record for it. */
     resolve(name: string, ref?: string): Promise<{
         bundle: ContextBundle;
@@ -262,6 +310,11 @@ export declare class ContextHub {
         label?: string | readonly string[];
         by?: string;
     }): Promise<ContextBundle>;
+    /** Refuses a bundle without a trusted signature, when the hub requires one. */
+    private assertTrusted;
+    private check;
+    /** What a signature over this bundle covers, with its pinned prompts read from the registry. */
+    private signedContent;
     private read;
     private pointer;
     private record;