nexus-ai-pro 2.21.0 → 3.0.0

package/API_STABILITY.md

@@ -1,7 +1,7 @@
 # API Stability Policy
 
-This policy describes compatibility guarantees for `nexus-ai-pro`. The 2.x guarantees apply beginning
-with version 2.0.0, as the 1.x guarantees applied from 1.0.0. The sections for the 1.x stages below
+This policy describes compatibility guarantees for `nexus-ai-pro`. The 3.x guarantees apply beginning
+with version 3.0.0, as the 2.x guarantees applied from 2.0.0 and the 1.x guarantees from 1.0.0. The sections for the 1.x stages below
 still describe each surface; where they say "the 1.x rules", read the rules of the current major line.
 
 ## Release stages
@@ -67,6 +67,102 @@ graduation:
 | Upgrade | A migration test from the previous minor |
 | Soak | A long-running test with flat memory and no leaked handles |
 
+## 3.0 stage (3.0.0)
+
+3.0 is a major release. It turns on the three defaults 2.21 previewed — incremental tracing on a
+durable trace store, the Redis operation store's dispatch index, and `hash-v2` for a deployment first
+recorded — and removes `OpenApiTools.skipped` and `GraphCheckpointV2`, both deprecated in 2.x. Nothing
+stored changes: checkpoints of version 1 and 2, the state store's keys, operation records, and recorded
+deployments read as they did, and the state store's keys are read by every later 3.x.
+`useDefaults('2.x')` and `NEXUS_DEFAULTS=2.x` keep 2.x's three defaults through 3.x.
+[MIGRATING.md](./MIGRATING.md) covers each change. The rollout is proven against the published 2.21.0
+package, in `tests/upgrade-3.test.ts`: a 2.21 worker and a 3.0 worker share a Redis prefix, each
+claiming what it should and 3.0 finding the rest after one `reindex()`, and 2.21 and 3.0 replicas
+place every thread alike, whichever records a deployment first.
+
+Removed: `OpenApiTools.skipped`, always empty since 2.22, and `GraphCheckpointV2`, for `GraphCheckpoint`.
+Everything else 3.0 adds is stable from the start and additive, unless this section says otherwise.
+
+### Graduation
+
+The studio's sign-in leaves experimental status: `oidcSignIn()`, `OidcSignInOptions`,
+`SIGN_IN_COOKIE`, and the `/auth/login`, `/auth/callback`, and `/auth/logout` routes.
+
+| Requirement | Evidence |
+| --- | --- |
+| API stability | Covered by the compatibility rules, with no planned breaking change |
+| Conformance | Signs a person in through Dex v2.46.0, run in a container on every build, where a wrong password is kept and a reused code refused: `studio/test/signin-dex.test.ts`; every way a callback can be wrong, a token for another client among them, against a provider written from the specification: `studio/test/signin.test.ts` |
+| Crash recovery | n/a: it keeps nothing; a session is a signed cookie, and a sign-in in progress is one the person carries |
+| Concurrency | A sign-in begun on one replica finishes on another, and every replica sharing the secret reads the session: `studio/test/signin.test.ts` |
+| Load | 500 reads on a sign-in session cost at most twice the same reads on a personal token: `studio/test/signin.test.ts` |
+| Tenant isolation | A tenant from a claim reads only that tenant's sources, comments, and audit entries: `studio/test/signin.test.ts`, `studio/test/tenants.test.ts` |
+| Security | [Review](./SECURITY.md#the-studio-and-its-accounts), reviewed for 2.22, its findings closed |
+| Upgrade | A session sealed by 2.22.0 is read: `studio/test/signin.test.ts` |
+| Soak | 1,000 sign-ins and their reads with flat memory: `studio/test/signin.test.ts` |
+
+## 2.22 stage (2.22.0)
+
+Everything 2.22 adds is stable from the start and additive, unless this section says otherwise.
+
+New and stable: `StreamChunk.logprobs`; in `nexus-ai-pro/protocols/a2a`, `signA2aCard()`,
+`verifyA2aCard()`, `canonicalA2aCard()`, `A2aCardSignatureError`, `A2aCardSigner`, `A2aCardKeyResolver`,
+`A2aSignatureAlgorithm`, `A2aJsonWebKey`, `A2aCryptoKey`, `A2aServerOptions.sign`, and
+`A2aClientOptions.verifyCard`, which `A2aGrpcClientOptions` takes too; in `nexus-ai-pro/mcp`,
+`mcpHttpHandler()`, `McpHttpOptions`, `McpHttpHandler`, `samplingFrom()`, `McpSamplingOptions`,
+`McpSamplingClient`, `McpServerPrompt`, `McpPromptArgument`, `McpPromptMessage`, `McpServerResource`,
+the server's `registerPrompt()`, `registerResource()`, `resourceUpdated()`, `createMessage()`,
+`elicit()`, `listRoots()`, and `onRootsChanged()`, the client's `sampling`, `elicitation`, and `roots`
+options, `onPromptsChanged()`, `onResourcesChanged()`, `onResourceUpdated()`, `subscribeResource()`,
+`unsubscribeResource()`, and `rootsChanged()`, `HttpClientOptions.listen`, the protocol types
+`McpSamplingRequest`, `McpSamplingResult`, `McpSamplingMessage`, `McpSamplingContent`,
+`McpModelPreferences`, `McpElicitationRequest`, `McpElicitationResult`, `McpRoot`, and
+`McpCallerRequests`, and `ToolContext.mcp`; in `nexus-ai-pro/agent/openapi`, `swaggerToOpenApi()`,
+`bundleOpenApiDocument()`, `OpenApiBundleOptions`, `OpenApiCredential`, `OpenApiWebhook`,
+`OpenApiToolsOptions.credentials`, `OpenApiOperation.security`, `OpenApiTools.webhooks`, and
+`loadOpenApiTools()`'s `references`, `maxDocuments`, and `maxBytes`; in `nexus-ai-pro/server/auth`,
+`createJwtSigner()`, `JwtSigner`, `JwtSignerOptions`, `JwtSignOptions`, `generateJwtKey()`,
+`jwksHandler()`, `createApiKeyStore()`, `ApiKeyStore`, `ApiKeyStoreOptions`, `ApiKeyRecord`,
+`IssuedApiKey`, `ApiKeyIssueOptions`, `createSessions()`, `Sessions`, `SessionOptions`,
+`SessionCookieOptions`, `SessionRecord`, and `StartedSession`, and the principal method `session`; in
+`nexus-ai-pro/rag/pinecone`, `PineconeVectorStore.create()`, `ensurePineconeIndex()`,
+`PineconeIndexOptions`, `PineconeIndex`, and `PineconeCreateOptions`, experimental with the store;
+`TypeSafeDecisionProviderOptions.pictures`; and in `nexus-ai-pro/embeddings`, `EmbeddingVideoPart`, the
+modality `video`, `EmbeddingMeta.unpricedMedia`, and `EmbeddingModelCapabilities`'
+`costPerAudioSecond`, `costPerVideoFrame`, `videoFrames`, `maxAudioSeconds`, and `maxVideoSeconds`; in
+the loaders, `FileInput`'s stream form, `CsvRowParser`, `JsonLoaderOptions.recordsAt`,
+`WebLoaderOptions.render` and `renderBelow`, `browserRenderer()`, `WebPageRenderer`, `WebPageToRender`,
+`RenderingBrowser`, and `BrowserRendererOptions`; in the realtime family, `ImageItem`, the `message.image`
+event, and `RealtimeConversationOptions.recordImages`; in telephony, `TelephonyGatherResult`,
+`EndGatherRequest`, `parseGatherResult()` and `endGather()` on the manager and the providers, and
+`TelnyxTelephonyProviderConfig.transcriptionEngine`; in the studio, `StudioOptions.tenantSources`,
+`StudioUser.tenant`, `StudioAuditEntry.tenant`, `StudioComment.tenant`, `StudioAuditQuery`,
+`HeaderAuthOptions.tenant`, `BearerAuthOptions.tenant`, `StudioSignIn`, and `StudioOptions.signIn`.
+Experimental: in the studio, `oidcSignIn()`, `OidcSignInOptions`, `SIGN_IN_COOKIE`, and the
+`/auth/` routes, until a sign-in against a live provider is recorded; `nexus-ai-pro/voice/google`,
+`GoogleVoiceProvider` and `GoogleVoiceProviderConfig`, until a live run is recorded.
+The state store keys and sessions are kept in, under `nexus/server`, is read by every later 2.x.
+
+Changed on purpose: an answer the output guard changes or blocks keeps no `logprobs`, streamed or
+not; a typed decision of a model that reports the chosen token alone is sampled; an Ollama stream
+honours `stop`. An MCP server declares prompts and resource subscriptions at `initialize` whatever it
+was given, and serves every transport connected to it rather than the last; a tool it runs gets a
+`signal` and `mcp` in its context. The HTTP client transport returns from `send()` before a streamed
+answer ends, sends `mcp-protocol-version`, and sends a `DELETE` when closed with a session. OpenAPI
+tools are made of operations with any request body, where those with a body other than JSON or a form
+were skipped, and of Swagger 2.0 documents, which were refused; `loadOpenApiTools()` reads no more of
+a document than `maxBytes`. With `credentials` given, an operation whose security cannot be met fails
+before it is sent.
+
+A TypeSafe AI request with pictures is multipart unless `pictures: 'base64'`, and its size is counted
+in bytes. gemini-embedding-2's audio and video are priced, where they cost nothing before, and audio
+past 180 seconds or video past 120 is refused before the call. A Google embedding batch over 20 MB is
+sent as a file, where it was refused. Gemini Live acts on `updateSession()`, which it ignored. A
+realtime record holds the images sent, as `image` items, which a consumer that switches on every item
+type meets for the first time. A Telnyx gather for speech transcribes the caller, where it was
+refused.
+
+Deprecated: `OpenApiTools.skipped`, always empty, is removed in 3.0.
+
 ## 2.21 stage (2.21.0)
 
 Everything 2.21 adds is stable from the start and additive, unless this section says otherwise.

package/CHANGELOG.md

@@ -4,6 +4,168 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-10-30
+
+3.0, a major release. It turns on the three defaults 2.21 previewed, and removes the two names 2.x
+deprecated; nothing stored changes, and `useDefaults('2.x')` keeps 2.x's defaults for an application
+that upgrades first. [MIGRATING.md](./MIGRATING.md) covers each change, and `nexus migrate` finds what
+it touches.
+
+### Breaking
+
+- **A tracer on a durable store writes as it runs.** `TracerOptions.incremental` defaults to true on a
+  store whose `durable` is not `false`: each run is written as it starts and again as it ends, so a
+  run in a process that dies is not lost, at twice the writes. A store in memory still writes at the end.
+- **The Redis operation store keeps its dispatch index**, where the client has `zadd`, `zrem`, and
+  `zrangebyscore`, so a claim reads the same few records however long the queue. Work a worker
+  without the index queued is found once `reindex()` runs: call it once the last 2.x worker sharing the
+  prefix has stopped.
+- **A deployment first recorded on 3.0 places threads by `hash-v2`**, which spreads sequential ids
+  evenly. A deployment already recorded keeps its strategy, so no thread moves.
+- **`OpenApiTools.skipped` is removed.** It was always empty since every operation became a tool.
+- **`GraphCheckpointV2` is removed**, for `GraphCheckpoint`, which it named. `nexus migrate` renames it.
+
+### Changed
+
+- **The studio's sign-in is stable.** Every build signs a person in through Dex, an OpenID Connect
+  provider run in a container: its configuration read, the code exchanged with the client secret and
+  PKCE, its ID token verified against its keys, a wrong password kept at Dex, and a used code refused.
+  `oidcSignIn()`, `OidcSignInOptions`, `SIGN_IN_COOKIE`, and the `/auth/` routes leave experimental
+  status, with their evidence in API_STABILITY.md.
+- **Gemini's voice is in the live workflow.** It speaks a sentence in one of Gemini's voices and hears it
+  back; it graduates when that run passes.
+
+## [2.22.0] - 2026-10-29
+
+MCP over streamable HTTP both ways, OpenAPI tools that send each operation's credentials, tokens, keys,
+and sessions the server issues, and a studio that signs people in and serves many tenants; with signed
+A2A cards, embeddings of video, loaders that stream, Gemini's voice, and the kernel in Firefox and
+WebKit.
+
+### Added
+
+- **Log probabilities from a stream.** Each `text` chunk's `StreamChunk.logprobs` holds its tokens'
+  log probabilities, from OpenAI's Chat Completions and Responses API, Gemini, Ollama, and Cohere, so
+  the chunks' together are what `complete()` reports.
+- Cohere reports log probabilities, `complete()` and streamed: a piece of text at a time, each piece's
+  the sum of its tokens', with no alternatives.
+- **MCP both ways.** A server offers prompts (`McpServerPrompt`, `registerPrompt()`), resources a client
+  subscribes to (`resourceUpdated()`), and tells every client each list's changes; a tool it runs may ask
+  the client that called it for a completion from its model, an answer from its person, or its roots,
+  through `context.mcp`, and is stopped when the client cancels it. A client answers a server's
+  `sampling`, `elicitation`, and `roots` with handlers of its own, `samplingFrom()` answering with
+  the application's own model, and hears each list change and each resource it subscribed to.
+- **MCP over streamable HTTP, both ways.** `mcpHttpHandler()` serves an `McpServer` as a Web handler:
+  a session per client, a stream of events per request carrying the server's progress and questions
+  before its answer, a `GET` stream for what it sends of its own accord, `DELETE` to end a session, and
+  a request from another origin refused. The client's HTTP transport reads a stream as it comes, so a
+  question in the middle of a call arrives in time, listens on a `GET` stream with `listen`, sends the
+  protocol version, and ends its session on `close()`. The nightly interoperability run drives the
+  server with `@modelcontextprotocol/sdk`'s own client: its tools, a completion asked mid-call, its
+  progress, a prompt, and a subscribed resource's change.
+- **Signed A2A cards.** `signA2aCard()` and `verifyA2aCard()`, with `canonicalA2aCard()`, sign and check
+  a card as protocol 1.0 does, a flattened JWS over its canonical form, which is the A2A project's SDK's
+  form: a card either signs, the other verifies. A handler's `sign` signs every card it serves, each
+  tenant's and the extended card included, and a client's `verifyCard` makes no call until a signature
+  on the card holds. ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512, and Ed25519, by the
+  Web Crypto API alone. The nightly interoperability run checks both directions against `@a2a-js/sdk`.
+- **OpenAPI credentials.** Tools read from an OpenAPI document send the credentials each operation's
+  security asks for, from `credentials` given by scheme name, or chosen per call: an API key in a
+  header, query parameter, or cookie; HTTP Basic, bearer, or another HTTP scheme; and an OAuth 2.0 or
+  OpenID Connect token, held, or fetched by the client-credentials flow for the operation's scopes and
+  kept until a minute before it expires. An operation whose alternatives none can be met fails before
+  anything is sent, naming them. Each `OpenApiOperation` carries its `security`.
+- **Swagger 2.0, and references to other documents.** A Swagger 2.0 document is read as the OpenAPI 3.0
+  one it describes, which `swaggerToOpenApi()` returns. `bundleOpenApiDocument()` reads in the other
+  documents a document's references name, on its own origin by default, or as `references` allows,
+  within `maxDocuments` and `maxBytes`; `loadOpenApiTools()` does so itself.
+- OpenAPI tools send a multipart form, its file fields given as base64, a text or XML body, and a body
+  of bytes, such as an image, so every operation becomes a tool. `webhooks` lists what the API sends
+  the application, its webhooks and its operations' callbacks, each with its JSON body's schema.
+- **Tokens, keys, and sessions the server issues.** `createJwtSigner()` issues tokens with a secret, a
+  PEM or JWK private key, or a Web Crypto key pair, and `issue()` writes a principal under the claim
+  names `jwtAuth()` reads back; `generateJwtKey()` makes a key, and `jwksHandler()` publishes the
+  public halves, for a rotation that refuses no live token. `createApiKeyStore()` issues, rotates with
+  a grace period, and revokes API keys, kept as hashes in the server's state store with when each was
+  last used. `createSessions()` signs browsers in after a sign-in of the application's own: an
+  `HttpOnly`, `Secure`, `SameSite=Lax` cookie of a random secret whose hash alone is kept, an idle
+  and a total lifetime, sign-out here or everywhere, and a request from another site's page refused.
+- **A Pinecone store makes its own index.** `PineconeVectorStore.create()` creates a serverless index
+  with the cosine metric and the store's width, or uses one of that name that fits, waits until it is
+  ready, and returns a store over its host; `ensurePineconeIndex()` does the first part alone.
+- TypeSafe AI is sent a decision's pictures as parts of a multipart request, as bytes, so three
+  pictures of 10 MiB fit in the 32 MiB a request holds; `TypeSafeDecisionProviderOptions.pictures`
+  set to `base64` sends them within the JSON, as before.
+- **Embeddings of video, and audio and video priced by length.** An `EmbeddingVideoPart` holds a video
+  by its bytes, base64, or a URL, such as a Files API URI, and gemini-embedding-2 embeds it. Audio is
+  priced by the second and video by the frame the model takes, one a second and at most 32 on
+  gemini-embedding-2, at $0.00016 a second and $0.00079 a frame, each length read from the media's own
+  headers; a budget counts them before the call. Media longer than a model's `maxAudioSeconds` or
+  `maxVideoSeconds` is refused before it is sent, and media whose length cannot be read is counted in
+  `unpricedMedia`. A registry data file sets these prices and limits too, each checked when it loads.
+- A Google embedding batch over 20 MB, up to 2 GB, is uploaded as a JSONL file through the Files API, and
+  its results are read from the file the batch writes, matched to their inputs by key.
+- **CSV and JSON stream through.** `loadCsv()` and `loadJson()` read a file as it arrives and yield each
+  row or record as soon as it is read: a path in chunks, or a `FileInput` that is now also a stream,
+  such as a response's body. `CsvRowParser` parses CSV a piece at a time, and `recordsAt` names the
+  array of records inside a JSON document, such as `data.items`, read item by item. A file larger than
+  memory goes to the store a batch at a time.
+- **Pages built by script.** `loadWebPages()` takes a `render` of the application's own for a page
+  whose text a script builds, and `browserRenderer()` makes one from a Playwright or Puppeteer browser,
+  with no browser a dependency of the package.
+- **Gemini voice.** `GoogleVoiceProvider`, on `nexus-ai-pro/voice/google`, speaks in Gemini's voices, as
+  WAV or raw PCM, whichever its model answers with, directed by a system instruction that is never
+  spoken; and transcribes with a text model that hears the audio, inline or by a Files API URI, guided
+  by its language and the names it may hold. Experimental until a live run is recorded.
+- **Gemini Live changes its setup mid-call.** `updateSession()` on Gemini Live sets the session up again
+  between turns, on a new socket resumed from the latest handle: instructions, voice, language,
+  modalities, tools, turn detection, the model, and Gemini's own setup fields. What is sent meanwhile
+  waits, and the conversation carries on.
+- **Images in the realtime record.** An image sent in a realtime conversation is kept as an `ImageItem`,
+  with its digest and, unless `recordImages` is `digest`, the image, and a resumed session gives it
+  back to the model. Video frames are not kept.
+- **Telnyx gathers speech.** A gather that listens for speech on Telnyx transcribes the caller's side of
+  the call, with its prompts spoken and keys still taken, until `endGather()`. `parseGatherResult()`
+  reads what a gather collected on either provider, Twilio's `SpeechResult` and `Digits` or Telnyx's
+  `call.transcription` and `call.gather.ended`, as one `TelephonyGatherResult`.
+- **The studio signs people in, and serves many tenants.** `oidcSignIn()` signs people in with any
+  OpenID Connect provider, with no proxy in front: the code flow with PKCE, a state, and a nonce, the ID
+  token verified against the provider's keys, and a signed session cookie that replicas share, with
+  sign-out at the provider too. A person's `tenant`, from a claim, a header, or the users file, picks
+  the sources they read, from `tenantSources`; they see their tenant's comments and audit entries
+  alone, and their page token is bound to it.
+- **The kernel in Firefox and WebKit.** The portable kernel's own tests, the file Node.js, Deno, Bun,
+  and the edge runtime run, now run in a browser page too, in headless Chromium on every build and in
+  Firefox and WebKit, Safari's engine, in CI, with a graph, an agent with a streaming tool, and AG-UI.
+- **Cohere's Embed 5.** `embed-v5.0-pro` and `embed-v5.0-fast` are in the registry, with their
+  sizes from 256 to 2,048, 128,000 tokens, and images. Cohere publishes no per-token price for them,
+  so they are registered without one.
+
+### Changed
+
+- A TypeSafe AI request with pictures is multipart by default, and its 32 MiB is counted in bytes, not
+  characters, so a state of text outside ASCII is refused before it is sent rather than by the API.
+- `loadCsv()` and `loadJson()` yield their first document before the rest of the file is read; a JSON
+  file whose array of records is cut short is refused as such, after the records before the cut.
+- An OpenAPI operation with a multipart or other non-JSON body becomes a tool, where it was skipped; a
+  Swagger 2.0 document is read, where it was refused; and `loadOpenApiTools()` refuses a document over
+  `maxBytes`, 5 MB by default, reading no further.
+
+### Deprecated
+
+- `OpenApiTools.skipped`, always empty now that every operation becomes a tool. It is removed in 3.0.
+
+### Fixed
+
+- **An answer the output guard redacts keeps no log probabilities.** They name the tokens the model
+  wrote, so a redacted address or connection string was still spelled out in `response.logprobs`; now
+  they are dropped wherever the guard changes or blocks the text, streamed or not.
+- The Google embedding batch adapter reads inline results under the name Google's API reference gives
+  them, `inlinedResponses`, as well as its clients' name.
+- A typed decision asked of a model that reports only the chosen token's log probability, with no
+  alternatives, is sampled, where it was read as certain.
+- An Ollama stream stops at the request's `stop` sequences, as a call does.
+
 ## [2.21.0] - 2026-10-26
 
 Typed decisions about pictures, compatibility records gathered from community adapters' own CI, and
@@ -3361,7 +3523,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.21.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.22.0...v3.0.0
+[2.22.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.21.0...v2.22.0
 [2.21.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.20.2...v2.21.0
 [2.20.2]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.20.1...v2.20.2
 [2.20.1]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.20.0...v2.20.1

package/MIGRATING.md

@@ -1,4 +1,138 @@
-# Migrating to 2.0
+# Migrating
+
+- [To 3.0](#migrating-to-30), from 2.x
+- [To 2.0](#migrating-to-20), from 1.x
+
+## Migrating to 3.0
+
+3.0 turns on three defaults that 2.x kept opt-in, and removes two names 2.x deprecated. Nothing stored
+changes: checkpoints, operation records, the server's state, and recorded deployments read as 2.x
+wrote them. Most code compiles unchanged, but the three defaults change what a deployment does, so read
+each before the upgrade reaches production.
+
+To upgrade first and take the defaults later, keep 2.x's for now, on every replica:
+
+```ts
+import { useDefaults } from 'nexus-ai-pro/config';
+
+useDefaults('2.x'); // before creating a tracer, an operation store, or a deployment
+```
+
+or set `NEXUS_DEFAULTS=2.x` in the environment. Then `npx nexus doctor --upgrade 3.0` says what turning
+them on would change for your deployment, and `npx nexus migrate src` finds the removed names.
+
+| Change | The codemod | By hand |
+| --- | --- | --- |
+| [A tracer on a durable store writes as it runs](#a-tracer-on-a-durable-store-writes-as-it-runs) | — | Expect twice the trace writes; close abandoned runs |
+| [The Redis operation store keeps its index](#the-redis-operation-store-keeps-its-index) | — | Call `reindex()` once no worker without the index is left |
+| [A new deployment places threads by `hash-v2`](#a-new-deployment-places-threads-by-hash-v2) | — | Give `bucket()` the deployment's strategy |
+| [`OpenApiTools.skipped` is removed](#openapitoolsskipped-is-removed) | Lists each read | Delete it |
+| [`GraphCheckpointV2` is removed](#graphcheckpointv2-is-removed) | Renames it | — |
+| [`useDefaults('3.0')` changes nothing](#usedefaults30-changes-nothing) | Lists each call | Delete it |
+
+### A tracer on a durable store writes as it runs
+
+`TracerOptions.incremental` defaults to true on a store whose `durable` is not `false`. Each run is
+written when it starts and again when it ends, so a run in a process that dies stays in the store with
+every run beneath it that finished, and a run in progress can be watched. A store in memory, such as
+`MemoryTraceStore`, still writes each trace when its root finishes.
+
+- A store takes twice the writes, and a JSON Lines file twice the lines, the later one winning.
+- A run a dead process left stays `running` until `closeAbandonedRuns()` closes it. Call it when a
+  worker starts, or on a schedule.
+- Sampling is decided when the root starts. A trace not sampled is held in memory and written at the
+  end when tail sampling keeps it, so `keepErrors` still shows every failure.
+- A store of your own that keeps runs only in memory says `durable: false`, and is written at the end.
+
+```ts
+// Before: 2.x wrote each trace when its root finished
+const tracer = new Tracer({ store });
+
+// After, to keep that
+const tracer = new Tracer({ store, incremental: false });
+```
+
+### The Redis operation store keeps its index
+
+`RedisOperationStore` keeps queued work in a sorted set by age, and leased work in one by lease expiry,
+wherever its client has `zadd`, `zrem`, and `zrangebyscore`. A claim then reads the same few records
+with 100,000 operations queued as with 1,000. A client without those commands is not refused: the store
+reads every record, as 2.x did.
+
+A worker without the index, as every 2.x worker is unless asked, writes records without index
+entries, so work it queues is in the index only once `reindex()` adds it. Either way works:
+
+- **Roll 3.0 out, then reindex.** While 2.x workers run, they claim what they queued. Once the last of
+  them has stopped, call `reindex()` once, so the 3.0 workers find what was left. It is safe while
+  workers are busy.
+- **Turn the index on first, on 2.x.** On 2.2 or later, give every worker sharing the prefix
+  `index: true`, or on 2.21 `useDefaults('3.0')`, and call `reindex()` once; 3.0 then changes nothing.
+
+```ts
+const operations = new RedisOperationStore(redis);
+await operations.reindex(); // once no worker without the index shares the prefix
+```
+
+`index: false` keeps 2.x's behaviour.
+
+### A new deployment places threads by `hash-v2`
+
+A deployment first recorded on 3.0 places new threads and stateless runs by `hash-v2`, which spreads
+sequential ids, such as `user-1` to `user-500`, as evenly as random ones. A deployment already recorded
+keeps the strategy it records, `fnv1a-v1` before 3.0, so no thread moves through the upgrade;
+`Deployments.bucketing()` moves one when you choose to.
+
+`bucket()` still places a key by `fnv1a-v1` unless it is given a strategy, so code that predicts where a
+thread lands passes the deployment's:
+
+```ts
+// Before
+const onCanary = bucket(`support:${threadId}`) < 0.1;
+
+// After
+const deployment = await deployments.get('support');
+const onCanary = bucket(`support:${threadId}`, deployment?.bucketStrategy) < 0.1;
+```
+
+`bucketStrategy: 'fnv1a-v1'` on `Deployments.assistant()` keeps 2.x's strategy for a deployment not
+yet recorded. During a rolling upgrade, the replica that first records a deployment, by its first
+canary or split, decides its strategy, and every replica of 2.5 or later then reads it from the record;
+pass `bucketStrategy` to choose rather than leave it to the replica.
+
+### `OpenApiTools.skipped` is removed
+
+Every operation of an OpenAPI document becomes a tool since 2.22, its body sent whatever its type, so
+`skipped` was always empty. Delete each read. The codemod lists them, in files that use the OpenAPI
+tools.
+
+### `GraphCheckpointV2` is removed
+
+It was another name for `GraphCheckpoint`, kept since 1.25. The codemod renames it and keeps your local
+name:
+
+```ts
+// Before
+import type { GraphCheckpointV2 } from 'nexus-ai-pro/graph';
+
+// After
+import type { GraphCheckpoint as GraphCheckpointV2 } from 'nexus-ai-pro/graph';
+```
+
+### `useDefaults('3.0')` changes nothing
+
+An application that previewed 3.0 with `useDefaults('3.0')` or `NEXUS_DEFAULTS=3.0` already runs as 3.0
+does. The call and the variable change nothing now, and can go. `useDefaults('2.x')` and
+`NEXUS_DEFAULTS=2.x` keep 2.x's three defaults through 3.x.
+
+### What does not change
+
+- Checkpoints of version 1 and 2 are read by both checkpointers and by `migrateCheckpoint()`.
+- The server's state keys, sessions, API keys, operation records, and recorded deployments read as 2.x
+  wrote them.
+- Every other default, and every API this guide does not name.
+- Node.js 22 or later.
+
+## Migrating to 2.0
 
 2.0.0 removes what the 1.x line deprecated, and runs every call of every family through one
 lifecycle. Most applications change only their imports, and a codemod does that.
@@ -31,7 +165,7 @@ upgrade, and work through the table.
 | [Claude 4.6 onward think adaptively](#claude-46-onward-think-adaptively) | — | Nothing |
 | [Tool calls reach providers whole](#tool-calls-reach-providers-whole) | — | Nothing |
 
-## The root import keeps only the core
+### The root import keeps only the core
 
 In 2.0, `nexus-ai-pro` exports the core client and nothing else:
 
@@ -71,7 +205,7 @@ is in the [packaging guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/
 
 The root import now costs about 325 KB, down from 572 KB.
 
-## Validators and Node types are optional
+### Validators and Node types are optional
 
 `zod`, `ajv`, `ajv-formats`, and `@types/node` are optional peer dependencies. A production install
 is the package alone, about 5.3 MB instead of 12.3 MB.
@@ -88,7 +222,7 @@ install. A zod shape is checked through each field's own `safeParse`.
 The request check in the guardrails, `SchemaValidator`, no longer uses zod. It reports the same
 fields by the same paths; the wording of its findings changed.
 
-## A response's `estimatedCost` is removed
+### A response's `estimatedCost` is removed
 
 The formatted string on a response's metadata is gone. Read the numeric cost, and format it yourself:
 
@@ -104,7 +238,7 @@ if (cost) console.log(new Intl.NumberFormat('en-US', { style: 'currency', curren
 A plan's `estimatedCost`, from `ai.plan()`, is an object and stays. A custom provider that set the
 string should drop it; `buildMeta()` fills `usage` and `cost`.
 
-## Modalities say which way they flow
+### Modalities say which way they flow
 
 A model's `modalities` list mixed inputs and outputs: `vision` meant an image in, and `image` meant an
 image out. 2.0 removes it, and the `Modality` type with it. Every entry declares `inputModalities` and
@@ -128,7 +262,7 @@ models: { registry: { 'my-model': { inputModalities: ['text', 'image'], outputMo
 In routing requirements, replace `modalities` with `inputModalities` or `outputModalities`.
 `modalitiesOf()` still reads both lists, and now requires both.
 
-## Checkpoints are version 2
+### Checkpoints are version 2
 
 A checkpoint 2.x writes has a `version` of 2, an `id`, its `tasks` always spelled out, and every
 pending question in `interrupts`. The single `interrupt` field is gone.
@@ -152,7 +286,7 @@ so a thread left waiting resumes after the upgrade.
 | Build a checkpoint by hand | Use `toCheckpoint()`, which fills in the version, id, tasks, and questions |
 | Named `GraphCheckpointV2` | It still compiles; it is now another name for `GraphCheckpoint` |
 
-## Options that were never read are removed
+### Options that were never read are removed
 
 These were accepted and ignored, and warned once per process since they were deprecated. The codemod
 lists each one it finds.
@@ -170,11 +304,11 @@ lists each one it finds.
 Delete them. Nothing changes, because nothing read them. Approval before a tool runs is
 `interruptOn` on `createAgent()`.
 
-## `ImageManagerConfig` is removed
+### `ImageManagerConfig` is removed
 
 It was another name for `ImageConfig`. The codemod renames the import and keeps your local name.
 
-## Pipeline step names are a closed list
+### Pipeline step names are a closed list
 
 `PipelineStepName` lists the built-in stages only, so a `switch` over it can be exhaustive. A step you
 add with `use()` is recorded as `customStep`, with its own name in `custom`.
@@ -195,7 +329,7 @@ Metrics for a custom step keep its own name as their `step` label.
 `PipelineRunner` are generic over the request and the response. Both default to a completion's, so
 existing code compiles unchanged.
 
-## Streams open on their first read
+### Streams open on their first read
 
 `ai.stream()` returns at once. Authorization, the rate limit, guardrails, routing, and the budget run
 when the stream is first read, so their errors come out of the loop:
@@ -216,7 +350,7 @@ Streams now get what completions always had. They are audited and counted, the c
 circuit breaker apply, and the `done` chunk carries the request id and a cost priced on the routed
 model.
 
-## Every call runs through the lifecycle
+### Every call runs through the lifecycle
 
 Completions, streams, embeddings, voice, telephony, images, realtime sessions, graphs, agents, jobs,
 and batches share one [lifecycle](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/lifecycle.md).
@@ -244,7 +378,7 @@ To use the lifecycle, set `lifecycle` on the client: an `authorize` callback, a
 `hooks`. Pass `ai.lifecycle` to graphs, agents, workflows, realtime sessions, queues, and batches to
 make their runs operations of the client too.
 
-## Responses are priced on the routed model
+### Responses are priced on the routed model
 
 The client now prices each response on the model the request was routed to, as the registry names
 it. Providers often answer with a dated snapshot name the registry does not file. In 1.x, pricing on
@@ -252,7 +386,7 @@ that echo cost the call nothing, so OpenAI responses could show a cost of 0, and
 DeepSeek, and Cohere models filed under a prefix. Expect those costs to be priced in 2.0, and budgets
 to count them. A charge the provider reports, with `basis: 'reported'`, is kept as it is.
 
-## The model registry is current
+### The model registry is current
 
 The bundled registry was checked against each provider's documentation on 2026-10-02.
 
@@ -269,7 +403,7 @@ The bundled registry was checked against each provider's documentation on 2026-1
 
 `describeModel()` shows what a name resolves to and when its entry was verified.
 
-## Claude 4.6 onward think adaptively
+### Claude 4.6 onward think adaptively
 
 From the 4.6 generation on, Claude takes adaptive thinking and an effort level, not a thinking budget.
 After 4.6 a budget is rejected, so 1.x requests with `reasoning` failed on those models. 2.0 sends what
@@ -277,7 +411,7 @@ each model accepts, and the [core guide](docs/core.md#reasoning) has the details
 your code. From 4.7 on, Claude also rejects a non-default `temperature` or `topP`, so the client
 drops one and records a capability warning.
 
-## Tool calls reach providers whole
+### Tool calls reach providers whole
 
 In 1.x the OpenAI, Anthropic, and Google adapters dropped a conversation's tool calls and the ids that
 link results to them. A real tool loop could fail on its second turn. 2.0 sends both the way each API
@@ -287,7 +421,7 @@ Two things are new beside it. A tool can return `toolOutput()`, whose text, imag
 references go back as the tool message itself. And a model that produces images returns them on
 `response.assets`.
 
-## For provider authors
+### For provider authors
 
 The provider contracts only grew:
 
@@ -298,6 +432,6 @@ The provider contracts only grew:
 
 A provider written for 1.x compiles unchanged.
 
-## Runtime
+### Runtime
 
 2.0 runs on Node 22 and newer.

package/README.md

@@ -341,13 +341,21 @@ Shipped so far:
   evaluated with nothing sent, and one A2A handler serving many tenants, each seeing only its own;
 - 2.21 typed decisions about pictures, a yes or no, a choice, a score, or a box around something in
   one, from TypeSafe AI's Jev or any vision model; community adapters' compatibility records gathered
-  from their own CI, a failing one turning red; and 3.0's defaults behind one switch today.
-
-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, in 2.22, Pinecone, images, the Gemini embedding batch tier, media understanding, video, typed
-decisions, Gemini Live, SIP, and both phone providers graduate once the live workflow passes against
-each. The
+  from their own CI, a failing one turning red; and 3.0's defaults behind one switch today;
+- 2.22 MCP over streamable HTTP both ways, with prompts, resources, and a server's questions back to
+  the client; OpenAPI tools that send each operation's credentials; tokens, API keys, and sessions the
+  server issues; and a studio that signs people in with your identity provider and serves many
+  tenants, each seeing only its own;
+- 3.0 the three defaults 2.21 previewed, on: tracing written as it runs, the Redis dispatch index, and
+  `hash-v2` for a new deployment, with `useDefaults('2.x')` for an application that upgrades first;
+  and the studio's sign-in, stable, proven against a real OpenID Connect provider on every build.
+
+Upgrading from 2.x: 3.0 turns on three defaults 2.x kept opt-in, and `useDefaults('2.x')` keeps them
+off until you are ready; from 1.x, `npx nexus migrate src --write` moves your imports.
+[MIGRATING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/MIGRATING.md) covers both.
+Next, in 3.1, Pinecone, images, the Gemini embedding batch tier, media understanding, video, typed
+decisions, Gemini Live, SIP, both phone providers, and Gemini's voice graduate once the live workflow
+passes against each. The
 [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists what comes after, in the order
 applications ask for it.
 

package/SECURITY.md

@@ -281,9 +281,23 @@ Findings, each fixed in 2.5 with a test in `studio/test/security.test.ts`:
 - **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.
 
+Signing in and tenants, reviewed for 2.22, with tests in `studio/test/signin.test.ts`,
+`studio/test/tenants.test.ts`, and, against Dex, a real provider, `studio/test/signin-dex.test.ts`:
+- The provider's configuration must name the issuer the studio was given. An ID token must verify
+  against the provider's keys, name that issuer and the studio's client as its audience, and carry
+  the sign-in's nonce; a token for several clients must name the studio as `azp`.
+- The state, nonce, and PKCE verifier travel in a cookie signed for that purpose alone, for ten
+  minutes, so a callback from another browser, a late one, or a changed one is refused, and a sign-in
+  cookie is never taken as a session.
+- The page to come back to is always a path on the studio, never another site.
+- A tenant's people read only what `tenantSources` gives for their tenant. The studio itself keeps
+  comments and audit entries to their tenant, whatever the store does, and binds the page token to it.
+  `headerAuth()` with a tenant header refuses a request that lacks it.
+
 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.
+- Someone without a tenant reads the studio's own sources, the operators' view.
+- A session is a signed cookie, so one person's cannot be ended before it expires; rotating the
+  sign-in secret signs everyone out. Signing out is a plain link, which another site can follow.
 - 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.