@zackbart/connecta 0.39.0 → 0.41.0

package/documentation/auth.md

@@ -295,7 +295,7 @@ It has no queue and no configuration option. When full, a request receives HTTP
 `error: { code: "authentication_busy", message: "Authentication capacity reached.", retryable: true }`.
 The operator log records only the checked `authentication_busy` reason, never
 credentials or identity-provider diagnostics. Retry after the indicated delay;
-Connecta does not automatically retry the authentication.
+Connecta does not automatically retry authentication, except for one rejected Cloudflare Access identity lookup inside its existing deadline (see [Access on Workers](#cloudflare-access-on-workers)).
 
 Underlying work stays charged until it settles, including cancellation cleanup.
 A caller leaving alone never releases capacity. After an authorization's hard
@@ -399,7 +399,9 @@ This bound is independent of MCP request/program admission and downstream call
 limits. `Mcp-Method: subscriptions/listen` still defers its MCP request permit:
 after authentication and endpoint admission, a body-confirmed modern listen is
 refused promptly even when execution capacity is full. It always passes the
-authentication bound, and no request body is read before authentication.
+authentication bound, and the MCP route reads no request body before
+authentication. On Node, `listen()` has already buffered the body up to its own
+[pre-auth cap](./deploying.md#start-on-node) before core sees the request.
 
 Routes that do not invoke an inbound verifier consume no authentication slot:
 health, public OAuth discovery and client metadata, UI shells and static assets,
@@ -558,6 +560,7 @@ createConnecta({
   storage,
   agents: ["assistant", "ci"],
   accessTokens: accessTokens(storage),
+  publicUrl: "https://connecta.example.com",
   auth: clerkAuth({ publishableKey, secretKey }),
   ui: operatorUi(),
   maintainers: ["your-operator-id"],
@@ -651,6 +654,11 @@ agent's slot is `issued` naming exactly that record. Nothing else counts: a
 lookup or record the slot does not name is inert garbage. Every mutation
 commits by one `compareAndSet` on the slot and only moves forward; no security
 outcome depends on cleanup or on undoing a write.
+Admission reads this state afresh on every request; successful token verdicts
+are never cached. D1 and SQLite read the lookup, record, and slot in one
+statement, with the same validation and expiry checks. Custom storage adapters
+retain the sequential reads. Rotation and revocation therefore retain their
+next-request refusal bound.
 
 - **Rotate** writes the new record and its lookup (inert), checks the
   request's signal, then compare-and-sets the slot from what it read to
@@ -943,6 +951,7 @@ cache entries remain partitioned by the admitted pool.
 createConnecta({
   storage,
   accessTokens: accessTokens(storage),
+  publicUrl: "https://connecta.example.com",
   auth: clerkAuth({ publishableKey, secretKey }),
   readOnly: false, // required; pools without their own readOnly inherit it
   maintainers: ["user_owner"],
@@ -966,19 +975,19 @@ warning says, every pool path answers the 404 because nobody can be a member,
 and every agent endpoint answers the machine-only 401 because no agent can be
 admitted.
 
-| Rule         | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Scope        | `/mcp/<pool>` and `/agent/<pool>` serve exactly the pool's `tools` (connector ids or exact `connector.tool` addresses), with the pool's `readOnly`, to its member people and member agents respectively. Plain `/mcp` serves the whole catalog to maintainers and the unique member pool to other people. Neither intersects with or widens anything.                                                                                                                                         |
-| Refusal      | A person with zero or several memberships at `/mcp`, a non-member, and an undeclared pool get an identical 404 status, body, and headers, after auth. The operator log records `not_maintainer` (zero memberships), `ambiguous_pool` (several memberships), `not_pool_member`, or `pool_not_declared`. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content.                                                                                     |
-| Agents       | An agent member reaches its pools only at `/agent/<pool>`, with its `cta_` token. Human endpoints refuse `cta_`; see [agent endpoints](#agent-endpoints).                                                                                                                                                                                                                                                                                                                                     |
-| Surface      | From 0.35.0, optional `surface`: `"meta"` (default) serves the six meta-tools; `"native"` lists each of the pool's downstream tools directly, for clients with their own tool search, with optional `executeCode: false` to replace `execute_code` with `read_result` (invalid on meta pools). Calls take the same paths either way. See the [native tool surface](./meta-tools.md#native-tool-surface).                                                                                      |
-| Description  | Optional `description`: plain text telling the model what this endpoint is for. `/mcp/<pool>` and `/agent/<pool>` append it to the MCP `initialize` instructions after `This endpoint: `; a maintainer at plain `/mcp` and a pool without one serve the shared instructions unchanged. A routed person receives their pool description. It grants, hides, and refuses nothing, and changes no tool or tool description.                                                                       |
-| Construction | Malformed names, unknown options or connectors, empty pools, empty or missing `members`, mixed people and agent membership (a `ConfigError` naming the pool), unresolvable member references, a non-boolean `readOnly`, an `owner` that is not a Workspace email address, a `description` that is not 1 to 500 characters of one-line text after trimming, a retired `trust` or `grant`, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load. |
-| Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                                                                                                                                                                                                                                                          |
-| Drift        | No wildcards; pool tools are exact names. Missing live tools are unreachable and warned once while in a bounded 1,024-entry FIFO.                                                                                                                                                                                                                                                                                                                                                             |
+| Rule         | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Scope        | `/mcp/<pool>` and `/agent/<pool>` serve exactly the pool's `tools` (connector ids or exact `connector.tool` addresses), with the pool's `readOnly`, to its member people and member agents respectively. Plain `/mcp` serves the whole catalog to maintainers and the unique member pool to other people. Neither intersects with or widens anything.                                                                                                                                                |
+| Refusal      | A person with zero or several memberships at `/mcp`, a non-member, and an undeclared pool get an identical 404 status, body, and headers, after auth. The operator log records `not_maintainer` (zero memberships), `ambiguous_pool` (several memberships), `not_pool_member`, or `pool_not_declared`. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content.                                                                                            |
+| Agents       | An agent member reaches its pools only at `/agent/<pool>`, with its `cta_` token. Human endpoints refuse `cta_`; see [agent endpoints](#agent-endpoints).                                                                                                                                                                                                                                                                                                                                            |
+| Surface      | From 0.35.0, optional `surface`: `"meta"` (default) serves the six meta-tools; `"native"` lists each of the pool's downstream tools directly, for clients with their own tool search, with optional `executeCode: false` to replace `execute_code` with `read_result` (invalid on meta pools). Calls take the same paths either way. See the [native tool surface](./meta-tools.md#native-tool-surface).                                                                                             |
+| Description  | Optional `description`: plain text telling the model what this endpoint is for. `/mcp/<pool>` and `/agent/<pool>` prefix the MCP instructions with `Use skills. ` and the description before routing rules; a maintainer at plain `/mcp` and a pool without one serve the shared instructions unchanged. A routed person receives their pool description. It grants, hides, and refuses nothing, and changes no tool or tool description.                                                            |
+| Construction | Malformed names, unknown options or connectors, empty pools, empty or missing `members`, mixed people and agent membership (a `ConfigError` naming the pool), unresolvable member references, a non-boolean `readOnly`, an `owner` that is not a Workspace email address, a `description` that is not 1 to 500 UTF-16 code units of one-line text after trimming, a retired `trust` or `grant`, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load. |
+| Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                                                                                                                                                                                                                                                                 |
+| Drift        | No wildcards; pool tools are exact names. Missing live tools are unreachable and warned once while in a bounded 1,024-entry FIFO.                                                                                                                                                                                                                                                                                                                                                                    |
 
 Pool descriptions are trimmed before validation. The remaining text must be
-1 to 500 characters and contain no C0 or C1 control characters (including tabs,
+1 to 500 UTF-16 code units (non-BMP characters such as emoji count as two units) and contain no C0 or C1 control characters (including tabs,
 newlines, and NEL U+0085), LINE SEPARATOR (U+2028), or PARAGRAPH SEPARATOR
 (U+2029).
 
@@ -1097,6 +1106,7 @@ const team = [
   { handle: "bob", id: "user_bob", email: "bob@example.com" },
 ];
 createConnecta({
+  publicUrl: "https://connecta.example.com",
   auth: clerkAuth({ publishableKey, secretKey }),
   storage,
   accessTokens: accessTokens(storage),
@@ -1245,6 +1255,7 @@ const workspace: GoogleWorkspaceOptions = {
 };
 
 createConnecta({
+  publicUrl: "https://connecta.example.com",
   auth: clerkAuth({ publishableKey, secretKey }),
   storage,
   accessTokens: accessTokens(storage),
@@ -1345,25 +1356,48 @@ code, so `remoteMcp()` refuses it as personal at construction.
 
 ## Downstream OAuth state at rest
 
+An OAuth remote MCP connector requires an access token on passive MCP requests,
+including handshakes, catalog requests, and tool dispatches, even if the server
+accepts anonymous requests. This requirement survives provider replacement.
+If the SDK cannot obtain a token at send time, Connecta returns OAuth recovery
+before sending. A locally refused write counts as failed, without reconciliation;
+a write that may already have left remains unknown and is never replayed.
+Only an explicit authorization start may probe the MCP endpoint without a token
+for the SDK's challenge, never to call a tool. Authorization-server discovery,
+client registration, token exchange, and refresh retain their OAuth flows.
+
 Each owner of an OAuth connector (the deployment when shared, each principal
 when personal) has one **grant record**, `oauth:grant` in the connector's
 namespace: the live **epoch**, the latest consent's state digest, and one
 authorization server's client registration, tokens, and discovery. Each
-consent has a **flow record**, `oauth:flow:<sha256(state)>`, holding its
-epoch, consent URL, and PKCE verifier for fifteen minutes; the state itself is
-stored nowhere.
+consent has a **flow record**, `oauth:flow:<sha256(state)>`, holding its epoch
+and timestamp, its binding to the selected server and client, its consent URL,
+and its PKCE verifier for fifteen minutes; the state itself is stored nowhere
+outside that URL.
 
-With a vault, the grant's body and each verifier are sealed with its AES-GCM
-key, the additional authenticated data naming the connector, owner partition,
+With a vault, the grant's body and each flow record's binding, consent URL and
+verifier are sealed with its AES-GCM key, the additional authenticated data naming the connector, owner partition,
 record, and epoch, so ciphertext moved to another connector, principal,
 record, or epoch does not open. Anything that fails to open (tampered, or
 under a rotated key) reads as absent: `auth_required` and a logged warning.
-The epoch, consent URL, and state digest stay plaintext and authenticate
-nothing. A plaintext body written before the vault could seal is sealed where
+The epoch, timestamp, and state digest stay plaintext and authenticate nothing. A plaintext body written before the vault could seal is sealed where
 it lies on first read, by compare-and-set. An [`api()` OAuth
-connector](#downstream-oauth-on-api) stores no client. A vault without the
-optional `seal`/`open` members keeps the body plaintext with a startup
-warning; no vault, plaintext as always.
+connector](#downstream-oauth-on-api) stores no client.
+
+`createConnecta` throws when a configured vault lacks `seal` or `open` and any
+connector has `startAuth`. A vault without them still works for deployments with
+no OAuth connector. To migrate, use `encryptedCredentialVault(storage, key)` or
+add both methods; grants stored plaintext are then sealed on first read as above.
+
+**With no vault, the guarantee is narrower.** Nothing is encrypted at rest: the
+grant's body and the PKCE verifier are plaintext, and a configured URL's path can
+appear in them. The flow record is minimized instead. It stores no consent URL,
+and its binding keeps no URL userinfo, query or fragment, in plaintext or in its
+unkeyed discovery digest. Connect, callback and restart still work, and two things
+differ. A repeated non-forced start mints a fresh consent rather than handing the
+pending URL back; earlier links stay valid until their epoch ends. A change confined
+to a URL's query or fragment does not fence a pending consent.
+Use a vault wherever stored OAuth state must be protected.
 
 The body also holds `expiresAt`, the epoch milliseconds the stored access token
 expires: its `expires_in`, counted from just before the request that issued it
@@ -1432,7 +1466,7 @@ with the gate a call passes:
 | Stored grant        | Status                                                      | Start (Connect, Continue, Restart, `authorize_connector`)                                                                                                                                                                                                                          |
 | ------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Disconnected        | `auth_required`; the downstream is not asked                | Replaces the epoch, then proceeds as for no tokens                                                                                                                                                                                                                                 |
-| No tokens           | Connects; `auth_required` even when the downstream answers  | Connects first, so a 401's `resource_metadata` starts consent as before. A downstream that answers without credentials still gets consent, discovered from RFC 9728 metadata at the configured URL's well-known locations. The start answers `auth_required` with the consent URL. |
+| No tokens           | `auth_required`; tokenless MCP requests are refused locally | Connects first, so a 401's `resource_metadata` starts consent as before. A downstream that answers without credentials still gets consent, discovered from RFC 9728 metadata at the configured URL's well-known locations. The start answers `auth_required` with the consent URL. |
 | Tokens (any expiry) | Connects; `ok`, or `auth_required` when a 401 needs consent | Connects; `ok` without starting a flow when healthy                                                                                                                                                                                                                                |
 
 A start without a challenge runs the same SDK flow as a 401 without
@@ -2068,11 +2102,17 @@ targeting the host's private network:
 - A URL on the connector's configured origin is trusted; the operator wrote it.
 - Any other URL must be `https` and must not name a private host: `localhost`
   and `*.localhost`, `127/8`, `10/8`, `172.16/12`, `192.168/16`, `169.254/16`,
-  `100.64/10`, `0/8`, `::`, `::1`, `fc00::/7`, `fe80::/10`, or an IPv4-mapped
-  IPv6 form of any of those.
+  `100.64/10`, `0/8`, `192.0.0/24`, `192.0.2/24`, `192.88.99/24`, `198.18/15`,
+  `198.51.100/24`, `203.0.113/24`, `224/4`, `240/4`, `::`, `::1`, any IPv6
+  address outside global unicast `2000::/3` (which covers `fc00::/7`,
+  `fe80::/10`, `fec0::/10`, `ff00::/8` and `64:ff9b:1::/48`), `2001::/23`,
+  `2001:db8::/32`, or `3fff::/20`. An IPv6 address carrying an IPv4 address in
+  mapped, compatible, translated, NAT64 (`64:ff9b::/96`) or 6to4 (`2002::/16`)
+  form is judged by the address it carries.
 - A connector configured on a loopback host may also learn loopback URLs, over
   `http` too, so a local MCP server with a local authorization server keeps
-  working. LAN and link-local addresses stay refused.
+  working. Of the IPv4-carrying forms, only IPv4-mapped loopback counts as
+  loopback. LAN and link-local addresses stay refused.
 
 A refused URL is never requested. Discovery, registration, and code exchange
 fail with a non-retryable `connector_call_failed`. Resource-metadata origin
@@ -2083,10 +2123,22 @@ and the grant requires re-consent. Redirects cannot route around the
 rule; token requests never follow them, and resource redirects follow only
 same-origin hops.
 
-The check is syntactic: it reads the host after the WHATWG URL parser folds
-`2130706433` and `0x7f.1` into `127.0.0.1`, and never resolves a name — the
-Workers-safe core has no DNS. A public name resolving or rebinding to a private
-address is out of scope; a host that must stop that needs an egress policy.
+The shared check reads canonical URL syntax (including legacy IPv4 spellings).
+On Node, the owned transport also resolves learned hosts immediately before
+connecting, refuses the whole answer set if any IPv4 or IPv6 address violates
+the same rules, and pins the connection to a checked address. TLS SNI and
+certificate validation retain the original hostname, including through a proxy.
+Proxy TLS authenticates the proxy hostname separately from destination TLS.
+Resolution uses request-owned A/AAAA queries, cancelled when the request ends
+and bounded to ten seconds even without a caller deadline. Only absent address
+families may be omitted; resolver failures refuse the request. These DNS queries
+do not consult OS hosts-file aliases.
+Each redirect hop is checked. Configured origins remain exempt. Resolution
+refusals are typed, non-retryable, and send no destination request.
+
+Workers exposes no connection-time DNS hook and has no route to private networks;
+its behavior remains the shared syntactic check. The shared core never imports
+Node networking or the optional undici peer.
 
 Downstream advertisements choose consent destinations, never destinations for
 existing grants. Tokens and registered clients bind to their issuing server;
@@ -2213,7 +2265,9 @@ the first request on a fresh instance. It grants no identity and never falls
 back to another provider. Missing context without an assertion still returns 401. An unusable trusted AUD returns retryable 503 with
 `problem: "access_audience_invalid"`; it never proceeds to identity lookup.
 A rejected human identity, including a service identity or an unusable user
-id, returns 403. A thrown identity lookup or its five-second deadline returns retryable
+id, returns 403. A thrown identity lookup gets one retry after 100–250 ms of
+jitter, within the original five-second deadline. A hanging lookup is never
+retried concurrently. The second rejection or the deadline returns retryable
 503 with `problem: "identity_unavailable"` and `Retry-After: 1`. Every refusal
 carries `Cache-Control: no-store`; every unavailable-verification 503 carries
 `Retry-After: 1` and no `WWW-Authenticate` challenge. None of these failures admits an identity,
@@ -2231,9 +2285,24 @@ identifies the generic route fallthrough, `authorization_header_invalid` a
 malformed header, and `authentication_failed` an unclassified provider refusal.
 Access verification 503s emit `[connecta] Cloudflare Access verification unavailable`
 with the same facts and `access_context_unavailable`, `access_audience_invalid`,
-or `access_identity_unavailable`. These records contain no header values,
+or `access_identity_unavailable`. Identity lookup failures additionally carry
+checked `identityLookup` facts: `outcome` (`timeout` or `rejected`), `durationMs`,
+`cold` (whether this was the isolate's first identity lookup), and `inFlight`
+(the isolate's lookup attempts still pending when the failure was recorded; this
+request's own attempt counts only while it is pending, so a hung lookup counts
+itself, and a rejected lookup or a deadline during retry backoff does not).
+These records contain no header values,
 assertions, cookies, identities, URLs, response bodies, or exception text.
 
+Identity lookups stay request-owned: Connecta neither coalesces them across
+requests nor caches identity results. A caller-supplied assertion header is
+not an identity cache key. Failed identity lookups always refuse admission.
+
+After an authorized release, validate this mitigation with about 20 concurrent
+sessions. Count runs containing `identity_unavailable`, targeting fewer than
+1% of runs; distinguish `timeout` from `rejected` in the checked lookup facts.
+A passing local concurrency fixture does not establish production acceptance.
+
 Protect the Worker with a Worker-level Access application whose destination is
 `{ "type": "worker", "worker_id": "<the Worker script tag>" }`. A traditional
 hostname-level application blocks the URL but does not attach `ctx.access` to
@@ -2278,7 +2347,15 @@ tokens by default, both JWT and opaque. Verified `aud` or `resource` must
 contain the endpoint's exact canonical URL from protected-resource metadata.
 If both claims are present, both must match. Trailing slashes, case, queries,
 and fragments are not normalized. `/mcp` and `/mcp/support` are distinct
-resources. Set `publicUrl` behind an internal origin.
+resources.
+
+Clerk needs a fixed deployment URL. Set `ConnectaConfig.publicUrl`, or
+`clerkAuth({ publicUrl })` when only Clerk should use it; `createConnecta` throws
+when neither is set, on Node and on Workers. Both token `resource` checks and the
+session `azp` pin read this value, so a request's `Host` and `X-Forwarded-Proto`
+never decide them. There is no implicit loopback default: a local deployment names
+its origin, such as `http://localhost:8787`. The Node template does this when
+`PUBLIC_URL` is unset.
 
 ```ts
 clerkAuth({ publishableKey, secretKey,
@@ -2908,9 +2985,27 @@ grant with different consent settings.
 
 The grant record and consents, epoch fencing, vault sealing, shared/personal ownership,
 callback state/principal checks, `authorize_connector`, Connect, Restart, and
-Disconnect match `remoteMcp()`. Status calls report a stored grant for the
-configured token endpoint healthy without downstream probes and never start
-authorization. `oauth` and
+Disconnect match `remoteMcp()`. Status reads do not probe tokens, start OAuth,
+or write grant state. A grant for the configured token endpoint starts as `ok`;
+a real API 401 records `refused` and status becomes `auth_required`. A real API
+2xx records `accepted`. Other HTTP statuses do not establish an auth outcome.
+A persisted refusal does not block a later invocation: the API may have recovered,
+and an accepted response restores `ok`. Within the failing request, a second 401
+still latches authorization failure. Connect on a refused grant begins fresh consent
+rather than reporting existing tokens as healthy. Maintained OAuth providers record
+these same outcomes for initial and replayed requests. Repeated identical outcomes
+for the current revision do not rewrite the grant.
+Each consent and refresh advances a monotonic token revision within its grant
+epoch and clears the prior observation in the same compare-and-set write.
+Call observations carry the epoch and revision read with their token and are
+accepted only while both still match the live grant. No wall clock orders
+observations. Reconsent with an identical token still advances the revision.
+The observation stores only its revision and the `accepted`/`refused` enum;
+arguments, response bodies, code and error text are excluded. A declared oversized
+401 records refusal without reading its body, including on a replay. Normal Connect
+resets only while the refused epoch, revision and outcome it read still match;
+a concurrently recovered grant is preserved. An observation
+storage failure does not replace the already received API response. `oauth` and
 `credential` are exclusive per connector, giving `auth_required` one recovery.
 For providers offering both, deployment config chooses; handlers check `ctx.oauth`.
 

package/documentation/code-mode.md

@@ -1113,9 +1113,18 @@ fields that are otherwise operator- and connector-authored, so `connectorId`
 and `toolName` clamp at 128 UTF-8 bytes (`address` at 257) with a `…` marker:
 payload-free _by construction_ means the event has nowhere to put a payload.
 
-**V4.** The execution itself emits no event. It has no address, and its one
-distinctive output is the program source — exactly what a payload-free history
-must never keep.
+**V4.** By default the execution and its utility operations emit no events.
+With `activityHistory({ operations: true })`, each executed search, describe,
+result page and skill read adds a `kind: "operation"` row, and the whole program
+adds a `program` row with host-call counts. Utility attempts refused above the
+execution boundary remain represented by the program's host-call accounting.
+Rows use fixed operation names rather than argument-supplied addresses or IDs;
+they carry timings, typed outcomes/codes and serialized return byte counts,
+never program source or payloads. The existing detached sink handles storage,
+and these rows do not count as calls or friction. The
+[operation-history contract](./operator-ui.md#opt-in-to-operation-history)
+owns opt-in cost, scope and owner disclosure rules. Recording history changes
+no authorization or capability state.
 
 **V5.** A write a program issues after it has already returned is not
 sent and records nothing: it was never an attempt (`W9`).
@@ -1337,6 +1346,12 @@ receive a fixed description.
 
 ### Verification
 
+The QuickJS child imports only the guest runtime, IPC helpers and dependency-light
+error/route constants. `test/purity.node.test.ts` walks its emitted import graph
+to exclude server orchestration, Effect and the MCP SDK. The shared
+`InvocationFailure` constructor preserves host error identity across existing
+exports and typed IPC reconstruction.
+
 The earlier alternatives are in [decision history](https://github.com/zackbart/connecta/blob/main/decisions/0001-ethos-verdict-table.md)
 ([#267](https://github.com/zackbart/connecta/issues/267),
 [#270](https://github.com/zackbart/connecta/issues/270)).
@@ -1350,49 +1365,49 @@ rejection, and branded adapter acceptance across module copies.
 declaration against `GuestApi`, checks arguments in both directions, and rejects
 invented, mistyped, and missing members and authored blocks the host refuses.
 
-| Clauses                | Test                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `P1`, `P5`             | both guest-contract executors (TypeScript syntax, trailing terminators, wrapper recovery), `test/program-source.test.ts` (which semicolons and wrappers are recovered), `test/quickjs-executor.node.test.ts` (`normalizeCode`)                                                                                                                                                                                                                                      |
-| `P2`, `X5`             | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.node.test.ts` (exact absent globals and blocked imports), `test/deployment-shapes.node.test.ts` (loader-only Worker construction)                                                                                                                                                   |
-| `P3`, `X9`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `P4`                   | `test/guest-api-contract.test.ts` (no cross-run leakage), `test/execute.test.ts` (one catalog load per connector per execution)                                                                                                                                                                                                                                                                                                                                     |
-| `A1`, `A2`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (canonical addressing), `test/server.test.ts` (bounded live connector inventory)                                                                                                                                                                                                                                                                                                                          |
-| `S1`, `S1a`, `S2`      | `test/guest-api-contract.test.ts` (flat page, connector guides, schema keys, unfiltered browse), `test/execute.test.ts` (guide pagination/partial/no-match behavior and `$ref`/`allOf`), `test/meta-tools-search.test.ts` (mixed complete/partial ranking, stable pagination, the two safety classes), `test/typescript-signatures.test.ts` (the TypeScript format over provider and pathological schemas, search/describe parity, observed labeling)               |
-| `S3`                   | `test/guest-api-contract.test.ts` (typed uncaught bound), `test/execute.test.ts` (count limits, fan-out bound)                                                                                                                                                                                                                                                                                                                                                      |
-| `S4`                   | both guest-contract executors (ordered mixed describe results with unknown-address, unknown-tool suggestion, and catalog-failure details), `test/meta-tools-search.test.ts` (top-level routing, no-suggestion, catalog-failure, and hostile-input bounds)                                                                                                                                                                                                           |
-| `S5`, `S6`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`, fail-closed annotations, activity parity)                                                                                                                                                                                                                                                                                                                                             |
-| `S7`                   | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (parallel calls and shared admission)                                                                                                                                                                                                                                                                                                                                                                     |
-| `S8`, `E1`, `X11`      | both guest-contract executors (caught call, discovery, utility, removed-function, and forgery cases; typed promise rejections), `test/quickjs-executor.node.test.ts` (oversized messages, private transport, forged outcomes)                                                                                                                                                                                                                                       |
-| `S9`                   | `test/result-shapes.test.ts` (value exclusion, bounds, merging, LRU and time expiry, runtime isolation, read-only admission, declared precedence, definition invalidation, unwrapped MCP results, discovery provenance, copy isolation, failure isolation)                                                                                                                                                                                                          |
-| `S10`                  | `test/resource-read.test.ts` (qualified routing, whole-connector grants, personal credentials, redaction, admission, timeout, cancellation and downstream MCP reads), both guest-contract executors (successful resource reads and caught/uncaught typed failures)                                                                                                                                                                                                  |
-| `E2`, `E8`             | `test/guest-api-contract.test.ts` (code → `retryable`, caught, parallel, and uncaught validation recovery, a conflict's bounded `current`), `test/meta-tools-call.test.ts` (direct, destructive, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts`                                                                                                                                                                 |
-| `E3`, `E4`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`, destructive reroute), `test/identity-write-journey.node.test.ts` (read-only refusals before validation or dispatch, actual QuickJS)                                                                                                                                                                                                                                                     |
-| `E5`                   | `test/guest-api-contract.test.ts` (execution-failure channel, in-flight `cancelled`), `test/execute.test.ts` (admission), `test/executor-admission.test.ts`, `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                |
-| `E6`, `X8`             | `test/guest-api-contract.test.ts` (unknown and inherited members, retained error identities), `test/quickjs-executor.node.test.ts`                                                                                                                                                                                                                                                                                                                                  |
-| `E7`                   | `test/guest-api-contract.test.ts` (refusals about a `503`-named connector), `test/errors.test.ts`                                                                                                                                                                                                                                                                                                                                                                   |
-| `R1`, `R2`, `R3`, `R4` | `test/guest-api-contract.test.ts` and `test/guest-api-contract-quickjs.node.test.ts` (small pass-through, shared return paging and unavailable fallback, no repeated writes, live authority), `test/program-result-cases.ts` (reconstruction, redaction, notice survives a 2,000-character spill)                                                                                                                                                                   |
-| `M6`, `M9`             | verdicts; `R2`'s guard, `M1`'s strict typing, and `M2`'s collect-then-deliver are their enforcement                                                                                                                                                                                                                                                                                                                                                                 |
-| `R5`                   | `test/guest-api-contract.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `R6`–`R8`              | `test/guest-api-contract.test.ts` (normal result keys), `test/execute.test.ts` (opt-in operation aggregates, failure paths, payload exclusion)                                                                                                                                                                                                                                                                                                                      |
-| `Y1`, `Y2`, `Y3`       | `test/guest-api-contract.test.ts` (one attempt per call, retryable flags by code)                                                                                                                                                                                                                                                                                                                                                                                   |
-| `Y4`                   | `test/meta-tools-call.test.ts`, `test/call-admission.test.ts` (one attempt, retry hints, caller reissue)                                                                                                                                                                                                                                                                                                                                                            |
-| `L1`, `L2`             | `test/guest-api-contract.test.ts` (in-flight call fails `cancelled`), `test/execute.test.ts` (cancels outstanding host calls, discovery included, and refuses discovery after the run; a cancelled wedged executor, or one whose `acquire()` ignores the signal, returns promptly and releases its lease)                                                                                                                                                           |
-| `L3`, `X1`             | `test/guest-api-contract.test.ts` (short-deadline executors), `test/execute.test.ts` (the watchdog ends a never-settling executor, frees the default pool, spares a slow run, and falls back from an unusable value)                                                                                                                                                                                                                                                |
-| `L4`, `L8`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (shared discovery/call budgets and terminal catch-and-continue loops and queued-write cancellation on both executors)                                                                                                                                                                                                                                                                                     |
-| `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue), `test/executor-requests.test.ts` (queued handoffs and refusal shape across separate workerd requests), `test/request-context.node.test.ts` (queued and QuickJS host-call request context)                                                                                                                             |
-| `L6`, `X10`            | `test/guest-api-contract-quickjs.node.test.ts` and `test/guest-api-contract.test.ts` (whole oversized reads and one-write pageable handles), `test/sqlite-storage.node.test.ts` and `test/storage-sql-d1.test.ts` (SQL stash and native D1 fault probes), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message)                                                                              |
-| `V1`–`V4`              | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, the identity clamp, the one-attempt floor), `test/browser/operator-ui.spec.ts` (identity changes), `test/sql-storage-contract.ts`, run by `test/sqlite-storage.node.test.ts` (historical activity rows still round-trip) |
-| `V5`, `W9`             | `test/program-writes.test.ts` (unawaited program drain, failed-program accounting), `test/identity-write-journey.node.test.ts` (committed ambiguity, reconciliation and physical writes), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                     |
-| `W10`, `W12`           | `test/identity-write-journey.node.test.ts` (real HTTP/MCP and QuickJS: write budget, read-only discovery and refusal, named guide, pool inheritance/reopening and connector policy), `test/program-writes.test.ts` (construction refusals and classification drift), `test/browser/operator-ui.spec.ts` (the badge)                                                                                                                                                 |
-| `M1`                   | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (rejected shapes, bounded native snapshots, paging before metadata traversal, and cyclic presentation refusal)                                                                                                                                                                                                                                       |
-| `M2`, `M3`             | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path)                                                                                                                                                                                                                                                                                 |
-| `M4`                   | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths), `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                           |
-| `M5`, `M7`             | `test/execute-emit.test.ts` (both budgets fail the crossing block; host-call budget untouched)                                                                                                                                                                                                                                                                                                                                                                      |
-| `M8`                   | two arms passing one case table, `test/codemode-compat.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `M10`                  | `test/execute-emit.test.ts` (aggregate present, numbers only, absent when nothing emitted)                                                                                                                                                                                                                                                                                                                                                                          |
-| `X4`                   | `test/guest-api-contract.test.ts` (string logs only), `test/quickjs-executor.node.test.ts` (logs before cancellation)                                                                                                                                                                                                                                                                                                                                               |
-| `X3`, `X6`             | `test/quickjs-executor.node.test.ts` (cancels a running child, never-settling await), `test/execute.test.ts` (a wedged executor stops being awaited)                                                                                                                                                                                                                                                                                                                |
-| `X7`                   | `P3`'s tests; the Workers superset is deliberately unused                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Clauses                | Test                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `P1`, `P5`             | both guest-contract executors (TypeScript syntax, trailing terminators, wrapper recovery), `test/program-source.test.ts` (which semicolons and wrappers are recovered), `test/quickjs-executor.node.test.ts` (`normalizeCode`)                                                                                                                                                                                                                                                                                                                                                                |
+| `P2`, `X5`             | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.node.test.ts` (exact absent globals and blocked imports), `test/deployment-shapes.node.test.ts` (loader-only Worker construction)                                                                                                                                                                                                                                                                             |
+| `P3`, `X9`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `P4`                   | `test/guest-api-contract.test.ts` (no cross-run leakage), `test/execute.test.ts` (one catalog load per connector per execution)                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `A1`, `A2`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (canonical addressing), `test/server.test.ts` (bounded live connector inventory)                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `S1`, `S1a`, `S2`      | `test/guest-api-contract.test.ts` (flat page, connector guides, schema keys, unfiltered browse), `test/execute.test.ts` (guide pagination/partial/no-match behavior and `$ref`/`allOf`), `test/meta-tools-search.test.ts` (mixed complete/partial ranking, stable pagination, the two safety classes), `test/typescript-signatures.test.ts` (the TypeScript format over provider and pathological schemas, search/describe parity, observed labeling)                                                                                                                                         |
+| `S3`                   | `test/guest-api-contract.test.ts` (typed uncaught bound), `test/execute.test.ts` (count limits, fan-out bound)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `S4`                   | both guest-contract executors (ordered mixed describe results with unknown-address, unknown-tool suggestion, and catalog-failure details), `test/meta-tools-search.test.ts` (top-level routing, no-suggestion, catalog-failure, and hostile-input bounds)                                                                                                                                                                                                                                                                                                                                     |
+| `S5`, `S6`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`, fail-closed annotations, activity parity)                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `S7`                   | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (parallel calls and shared admission)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `S8`, `E1`, `X11`      | both guest-contract executors (caught call, discovery, utility, removed-function, and forgery cases; typed promise rejections), `test/quickjs-executor.node.test.ts` (oversized messages, private transport, forged outcomes)                                                                                                                                                                                                                                                                                                                                                                 |
+| `S9`                   | `test/result-shapes.test.ts` (value exclusion, bounds, merging, LRU and time expiry, runtime isolation, read-only admission, declared precedence, definition invalidation, unwrapped MCP results, discovery provenance, copy isolation, failure isolation)                                                                                                                                                                                                                                                                                                                                    |
+| `S10`                  | `test/resource-read.test.ts` (qualified routing, whole-connector grants, personal credentials, redaction, admission, timeout, cancellation and downstream MCP reads), both guest-contract executors (successful resource reads and caught/uncaught typed failures)                                                                                                                                                                                                                                                                                                                            |
+| `E2`, `E8`             | `test/guest-api-contract.test.ts` (code → `retryable`, caught, parallel, and uncaught validation recovery, a conflict's bounded `current`), `test/meta-tools-call.test.ts` (direct, destructive, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts`                                                                                                                                                                                                                                                                                           |
+| `E3`, `E4`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`, destructive reroute), `test/identity-write-journey.node.test.ts` (read-only refusals before validation or dispatch, actual QuickJS)                                                                                                                                                                                                                                                                                                                                                                               |
+| `E5`                   | `test/guest-api-contract.test.ts` (execution-failure channel, in-flight `cancelled`), `test/execute.test.ts` (admission), `test/executor-admission.test.ts`, `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                                                                                          |
+| `E6`, `X8`             | `test/guest-api-contract.test.ts` (unknown and inherited members, retained error identities), `test/quickjs-executor.node.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `E7`                   | `test/guest-api-contract.test.ts` (refusals about a `503`-named connector), `test/errors.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `R1`, `R2`, `R3`, `R4` | `test/guest-api-contract.test.ts` and `test/guest-api-contract-quickjs.node.test.ts` (small pass-through, shared return paging and unavailable fallback, no repeated writes, live authority), `test/program-result-cases.ts` (reconstruction, redaction, notice survives a 2,000-character spill)                                                                                                                                                                                                                                                                                             |
+| `M6`, `M9`             | verdicts; `R2`'s guard, `M1`'s strict typing, and `M2`'s collect-then-deliver are their enforcement                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `R5`                   | `test/guest-api-contract.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `R6`–`R8`              | `test/guest-api-contract.test.ts` (normal result keys), `test/execute.test.ts` (opt-in operation aggregates, failure paths, payload exclusion)                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `Y1`, `Y2`, `Y3`       | `test/guest-api-contract.test.ts` (one attempt per call, retryable flags by code)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `Y4`                   | `test/meta-tools-call.test.ts`, `test/call-admission.test.ts` (one attempt, retry hints, caller reissue)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `L1`, `L2`             | `test/guest-api-contract.test.ts` (in-flight call fails `cancelled`), `test/execute.test.ts` (cancels outstanding host calls, discovery included, and refuses discovery after the run; a cancelled wedged executor, or one whose `acquire()` ignores the signal, returns promptly and releases its lease)                                                                                                                                                                                                                                                                                     |
+| `L3`, `X1`             | `test/guest-api-contract.test.ts` (short-deadline executors), `test/execute.test.ts` (the watchdog ends a never-settling executor, frees the default pool, spares a slow run, and falls back from an unusable value)                                                                                                                                                                                                                                                                                                                                                                          |
+| `L4`, `L8`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (shared discovery/call budgets and terminal catch-and-continue loops and queued-write cancellation on both executors)                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue), `test/executor-requests.test.ts` (queued handoffs and refusal shape across separate workerd requests), `test/request-context.node.test.ts` (queued and QuickJS host-call request context)                                                                                                                                                                                                                                                       |
+| `L6`, `X10`            | `test/guest-api-contract-quickjs.node.test.ts` and `test/guest-api-contract.test.ts` (whole oversized reads and one-write pageable handles), `test/sqlite-storage.node.test.ts` and `test/storage-sql-d1.test.ts` (SQL stash and native D1 fault probes), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message)                                                                                                                                                                                                        |
+| `V1`–`V4`              | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no execution event by default), `test/identity-write-journey.node.test.ts` (opt-in real-program utility/program rows, payload exclusion and detached writes), `test/activity.test.ts` (the shared code → friction table, the identity clamp, the one-attempt floor), `test/browser/operator-ui.spec.ts` (identity changes), `test/sql-storage-contract.ts`, run by `test/sqlite-storage.node.test.ts` (historical activity rows still round-trip) |
+| `V5`, `W9`             | `test/program-writes.test.ts` (unawaited program drain, failed-program accounting), `test/identity-write-journey.node.test.ts` (committed ambiguity, reconciliation and physical writes), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                                                                               |
+| `W10`, `W12`           | `test/identity-write-journey.node.test.ts` (real HTTP/MCP and QuickJS: write budget, read-only discovery and refusal, named guide, pool inheritance/reopening and connector policy), `test/program-writes.test.ts` (construction refusals and classification drift), `test/browser/operator-ui.spec.ts` (the badge)                                                                                                                                                                                                                                                                           |
+| `M1`                   | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (rejected shapes, bounded native snapshots, paging before metadata traversal, and cyclic presentation refusal)                                                                                                                                                                                                                                                                                                                                                                 |
+| `M2`, `M3`             | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path)                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `M4`                   | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths), `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `M5`, `M7`             | `test/execute-emit.test.ts` (both budgets fail the crossing block; host-call budget untouched)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `M8`                   | two arms passing one case table, `test/codemode-compat.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `M10`                  | `test/execute-emit.test.ts` (aggregate present, numbers only, absent when nothing emitted)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `X4`                   | `test/guest-api-contract.test.ts` (string logs only), `test/quickjs-executor.node.test.ts` (logs before cancellation)                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `X3`, `X6`             | `test/quickjs-executor.node.test.ts` (cancels a running child, never-settling await), `test/execute.test.ts` (a wedged executor stops being awaited)                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `X7`                   | `P3`'s tests; the Workers superset is deliberately unused                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 
 The surface itself is checked by `test/server.test.ts` (the exact six-tool list)
 and `test/program-writes.test.ts` (deployment policy and classification construction refusals).

package/documentation/deploying.md

@@ -61,6 +61,17 @@ authenticated `admission.requests.maxBodyBytes` default. To accept larger MCP
 bodies, configure both core and `listen(..., { maxBodyBytes })`; a smaller
 platform, proxy or adapter cap still wins. See
 [request body limits](./architecture.md#admission-in-two-places).
+`listen(..., { maxInFlightBodyBytes })` caps the body bytes all in-flight
+requests hold together, counted from the first chunk until the response finishes
+or the client leaves. It defaults to 64 MiB, or `maxBodyBytes` when that is
+larger, and may not be set below `maxBodyBytes`. Past it a request gets `503` with
+`Retry-After: 1` and `Connection: close`. Raise it when legitimate concurrent
+large bodies are refused, keeping it within the process's memory budget.
+`listen()` answers `400` with `Connection: close`, before reading any body, when
+`Host` is anything but a host with an optional port, when `X-Forwarded-Proto` is
+anything but `http` or `https`, or when the request target does not start with
+`/`. A reverse proxy must overwrite `X-Forwarded-Proto` with one value; a
+comma-separated chain such as `https,http` is refused.
 A Node host serving `connecta.fetch` without `listen()` has no owned sender:
 every maintained-provider write, every reviewed POST read and every remote MCP
 write is refused before sending. Downstream OAuth credential POSTs also require
@@ -199,7 +210,9 @@ and `describeConfig()`, and [optional modules](./architecture.md#optional-deploy
 owns their composition contracts.
 
 Enable `encryptedCredentialVault(storage, key)` before persisting downstream
-OAuth credentials. Without a sealing vault, OAuth grants are stored as plaintext.
+OAuth credentials. With no vault, OAuth grants are stored as plaintext. A
+configured vault without `seal` and `open` refuses construction when any connector
+uses OAuth.
 The platform templates describe the base64 32-byte encryption key. Keep it
 outside the database and source control, and preserve it across upgrades.
 [OAuth state at rest](./auth.md#downstream-oauth-state-at-rest) owns sealing and
@@ -302,6 +315,17 @@ Bump the exact package pin, read the [changelog](../CHANGELOG.md) for every
 intervening release, and apply the relevant migration before startup. `init`
 does not merge changes into an existing deployment.
 
+A custom vault without `seal` and `open` now refuses construction when any
+connector has OAuth. Before upgrading, add both methods or switch to
+`encryptedCredentialVault(storage, key)`. Existing plaintext grants are sealed on
+first read; see [OAuth state at rest](./auth.md#downstream-oauth-state-at-rest).
+
+A deployment using `clerkAuth` must set a fixed URL before upgrading:
+`ConnectaConfig.publicUrl`, or `clerkAuth({ publicUrl })`. Startup otherwise fails
+with a configuration error. Use the origin clients reach, because tokens' `resource`
+must match it exactly; see
+[Clerk OAuth tokens](./auth.md#clerk-oauth-tokens-and-operator-sessions).
+
 Before upgrading past 0.37.1 with pre-0.29 state, follow
 [Retired layout migrations](./migration-retired-layouts.md). Version 0.37.1 is
 the last bridge for KV → D1, JSON → SQLite, and OAuth layout-2 conversions.

package/documentation/integrating.md

@@ -345,8 +345,8 @@ check shared behavior. Provider-specific tests remain beside each provider.
 
 Use [`@zackbart/connecta-eve`](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md)
 in the Eve app for an app-owned connection and endpoint instructions refreshed
-once per turn. It requires Node 24 and Eve 0.90.x, and installs separately from
-Connecta. Follow its README for the two agent files, token environment variables,
+once per turn. It installs separately from Connecta. Follow its README for the
+supported Node and Eve versions, the two agent files, token environment variables,
 optional write approval and Vercel OIDC token source. Configure the server's
 [agent and pool membership](./auth.md#issue-rotate-or-revoke-an-agent-token)
 before connecting.