@zackbart/connecta 0.38.0 → 0.40.0

package/documentation/architecture.md

@@ -47,7 +47,8 @@ as the isolate — on Workers a lazy module-scope singleton, which is why both
 deployment shapes construct it outside the request handler.
 
 An OAuth connector, `remoteMcp()` or `api()` with a static grant, owns a
-runtime-local refresh completion gate in `src/auth/downstream-oauth.ts`.
+runtime-local refresh completion gate in
+`src/auth/downstream-oauth/refresh-coordinator.ts`.
 Joined scopes share the outcome while keeping their own request I/O and
 cancellation. Grant use and the caller's wait belong to the call. Renewal
 preparation is call-owned only until the first durable coordinator write
@@ -99,6 +100,18 @@ never retried and requires re-consent. Valid rotations retry their grant commit
 up to 32 times without another HTTP request; exhausted commits and all dispatched
 provider failures require re-consent. [Auth](./auth.md#refresh-failures) describes the lease and failure
 contracts.
+The grant body stores `expiresAt` beside the tokens it describes; reads never
+add it (INV-10). A call renews a token within `OAUTH_REFRESH_SKEW_MS` (60 s)
+of it before sending: the invocation's authorization check (`registerInvocationAuth`
+in `src/connectors/remote-mcp.ts` and `src/connectors/api-connector.ts`) runs
+the 401 flow before entering the connector, so a failed renewal is a
+pre-dispatch authorization failure, never an unknown write (INV-9).
+`KvOAuthProvider.renewalDue` decides from the grant read that check already
+made, in memory. The token request carries the access token it replaces
+(`earlyRenewalFetch`), and the coordinator adopts any stored token that differs
+instead of redeeming again. Status, listing, discovery and the connectionless
+catalog read never renew. [Auth](./auth.md#refreshing-before-expiry) has the
+operator contract.
 
 **Per request, and no longer.** The MCP server, its transport, downstream MCP
 clients, abort signals, and the connector scope a probe opens all belong to the
@@ -107,7 +120,10 @@ across requests on Workers is a cross-request capability leak, and a promise awa
 work the runtime may already have torn down. Deferred work has one sanctioned
 channel, `ctx.waitUntil`, threaded through `fetch(request, env, ctx)` — activity
 writes and OAuth renewals from claim submission use it. Catalog listing and SQL cache
-publication finish in the requesting scope. A fresh
+publication finish in the requesting scope. The operator surface's Promise
+edge (`ui.handle`) owns the request's signal and is awaited to its end even
+when the caller leaves, so a storage write it has started, such as a stored
+status observation, settles before the request does. A fresh
 `McpServer` per request is what makes the deployment stateless: no sessions, no
 server push, no stream resumability, scope resolved rather than remembered.
 
@@ -324,7 +340,7 @@ without storage reads, decryption or hashing. Catalog invalidation (including
 operator refresh and OAuth connect/disconnect/restart) advances a counter for the
 registry's cache store; built-in vault set/clear advances a counter for that vault.
 These weakly held counters contain no catalogs, credentials or caller identity;
-catalogs and derived views remain request-local. A moved fence replaces the
+registry catalogs and derived views remain request-local. A moved fence replaces the
 retained read and its search views, and prevents joining an older registry flight.
 Changes made through another process/isolate or directly in storage need not be
 observed mid-request; the next request uses the durable generation and auth checks.
@@ -603,6 +619,176 @@ Only complete, intake-redacted tools/list, resources/list and
 resources/templates/list successes are stored. Resource payloads are not cached. SDK default
 in-memory caching is replaced, so raw catalogs never enter it.
 
+A warm isolate retains at most four validated stored JSON catalogs, with a
+combined accounting budget of 8 MiB (twice serialized input bytes, key bytes and
+64 bytes per object property/array slot; larger entries bypass reuse).
+These deeply frozen facts contain no request context, transport, signal,
+callback or promise, and require neither weak references nor cleanup timers.
+Reuse follows the same manifest TTL checks, complete chunk reads, recomputed
+SHA-256 fingerprint and fresh generation/credential acceptance fence as a cold
+read. Its key binds the stored entry, current private owner/deployment partition
+(even for public entries), and chunk fingerprint. Request-specific credential
+redaction and TTL intake still run every time. Eviction affects performance
+only; SQL remains authoritative.
+
+Stored catalog and negotiation keys use deployment-keyed partitions. A remote
+connector's whole cache configuration and negotiation input enter a stored key
+only through HMAC-SHA-256 (`src/storage-digest.ts`) under a key that never
+enters storage: every configured URL in full (the endpoint, a client metadata
+document, a static client's issuer and the redirect URI), static auth header
+values, resource headers, and a static OAuth client's secret. The
+operator-managed or request-resolved credential (joined with the forwarded
+principal), a custom connector's credential values, and the OAuth token
+response that fences a listing are keyed the same way. The key is the vault's
+`storageDigestKey()`, which `encryptedCredentialVault()` derives with HKDF from
+its credential key. Without a vault, or with a custom vault that lacks the
+method, a random key held only in the process is used: the partitions stay
+exact, but another process or isolate addresses different entries and fills
+its own cache, so cross-isolate reuse of remote catalogs, verdicts and health
+records needs a vault. A different URL, header, credential, token response or
+epoch addresses a different entry at once, including a value changed by
+redeploy, and an earlier entry is never served under the new value; rotating
+back to an earlier value within its TTL finds its entries again. A new
+deployment key addresses new entries. Entries written by earlier releases are
+not read and expire on their own TTLs (catalogs within `catalogMaxTtlSeconds`,
+refresh baselines within 48 hours, verdicts within six hours), so each remote
+connector's partitions refill once after the upgrade with one handshake and
+listing.
+
+Warm remote resolution batches the negotiation verdict and locating generation
+when their physical keys share an observed SQL store. Private and public
+manifest probes share a `getMany` statement; their normal precedence and public
+scope check still apply. These batches contain only reads. Catalog addresses
+use the listing's pinned OAuth identity and locating generation; they authorize
+nothing. After chunk verification, acceptance re-reads the OAuth identity and
+generation separately and refuses a changed epoch or token digest. The invocation
+gate checks disconnect first, then reads tokens separately to refuse absent
+credentials and observe current expiry and the invalidation fingerprint. Token
+removal, expiry, scope and replacement can change without advancing the epoch;
+epoch fences alone cannot protect these values. The SDK's later token read may
+return no tokens and omit Authorization, so it does not replace invocation's
+token-presence refusal. The transport also refuses tokenless MCP requests on
+passive OAuth paths, regardless of provider history; an explicit authorization
+start may probe for the SDK's challenge. A refused tool send binds its private
+failure provenance to the undispatched physical request. Invocation accepts it
+only for the owning boundary and whole logical call; error fields, copied
+connectors, and refusals after a send cannot supply that proof.
+Connection reuse and SDK dispatch retain their fresh
+epoch or token reads; no credential read is prefetched.
+Stores with replaced methods or separate backing stores retain individual reads.
+
+A remote connector's `listTools` without a live connection in its request
+reads this cache before connecting. It derives the same partition a connect
+binds (the admitted principal, the caller's credential digest, or the owner's
+OAuth epoch and token digest) from storage reads only, then makes the SDK's
+two-probe read with the pre-connect empty server identity: the private slot,
+then a shared connector's public slot, served only when written public. OAuth
+grants are read by a non-mutating snapshot: no plaintext grant is sealed in
+place, no epoch is bound, nothing is refreshed. Every identity check during
+cache acceptance reads the grant again and refuses the entry unless the epoch
+its partition was derived from and the token digest both still hold. A missing
+or expired generation is a miss at every check and is never claimed or
+recreated. An unexpired complete entry is returned with no transport,
+handshake, session cleanup or storage write. A miss, an expired entry, an
+explicit `ttlMs: 0`, an invalidated generation, a credential, token or epoch
+change, an operator-disconnected or token-less grant, a cache read failure,
+and a downstream whose stored negotiation verdict is modern all connect as
+before. Modern downstreams connect without a handshake and read the cache
+through the SDK. The connect reuses the credential and negotiation verdict that
+read resolved. `list_changed` arrives only over a live connection, so an
+unconnected catalog changes at its TTL or on invalidation.
+
+A catalog served from this cache, before or after connecting, does not
+validate downstream credential health. An expired or vendor-revoked credential
+can still expose cached tools, and discovery reports no auth-related
+`catalogErrors` entry for it until the cache misses. Tool calls and resource
+reads reach the downstream and report auth failures with their handoffs. A
+status probe connects: a legacy downstream answers a handshake, while a modern
+downstream with a stored verdict connects without a request. A credential test
+always sends a live `tools/list` that bypasses the cache in both directions.
+
+In `"auto"` mode a remote connector stores its negotiation verdict, data only,
+in the `negotiation` key family, partitioned by connector configuration,
+credential and OAuth epoch, with secret-bearing inputs keyed as above. A later connect reuses it instead of probing with
+`server/discover`. A modern verdict lasts five minutes. A legacy verdict lasts
+six hours, because a server that adds the modern era still answers the legacy
+handshake. Two signals end a verdict early:
+
+- A legacy-verdict handshake refused with a 4xx other than 401, 403 or 429 (a
+  modern-only server answers 400 with its supported versions) is negotiated
+  again at once in the same connect. The new verdict replaces the old.
+- On a modern connection (adopted from the verdict or just negotiated), an
+  HTTP 400 is read through a bounded clone of its body, as the transport's
+  backward-compatibility rule requires. A modern server also answers 400 with
+  `HeaderMismatch` (-32020) and `MissingRequiredClientCapability` (-32021),
+  which concern the request alone and keep the verdict and the connection.
+  `UnsupportedProtocolVersion` (-32022) keeps them only while its
+  `data.supported` list (at most 64 strings) still names the request's
+  `MCP-Protocol-Version`; a missing, malformed or other list makes the verdict
+  unusable. Any other body, empty or not a recognized modern error (a legacy
+  server's sessionless refusal, a gateway's page), is a legacy refusal. Either
+  way the verdict is deleted and that client retired. The refused request
+  fails and is never repeated. The next connect, in the same request or a
+  later one, probes again. The clone read ends with the call, the request or
+  the connection scope: an abort cancels it, cancels the unread original and
+  takes no evidence (INV-7).
+
+An upgrade to a server that still answers the legacy handshake is therefore
+adopted within six hours. Losing the legacy handshake costs one refused
+request, and a downgrade costs the one request that met the refusal.
+
+**Discovery health.** An unscoped search (`search_tools` or `connecta.search`
+without `connector`) probes each connector for at most 5,000 ms, or
+`discovery.probeTimeoutMs` when that is shorter, and its probes end within a
+9,000 ms discovery budget. A tenth of the budget, at most 500 ms, is kept for
+recording outcomes: a probe that starts late gets only what remains before
+that slice, and one that cannot start reports `timeout`. Health reads, claims
+and writes start only while budget remains and the caller is still waiting;
+health is otherwise unknown. Once started, each is awaited to its end before
+the search returns, never raced or detached, since a storage write cannot be
+withdrawn once sent. The budget bounds when health work starts, not when it
+finishes, so slow storage can carry a search past it by one operation's
+latency. A scoped search,
+`connecta.describe`, native `tools/list` and tool calls keep the full
+`discovery.probeTimeoutMs`. A probe that times out on its own deadline, or a
+retryable failure that itself took at least one second or named its own wait,
+writes a record in the `connector-health:v1:` family: the connecta
+classification code, observation time, retry time (60 seconds later, or the
+downstream's shorter named wait, at least one second), and the connector's
+catalog invalidation generation. Each probe's time is its own, measured as it
+settles. Records hold no downstream text, tools, arguments or credentials.
+Each is keyed by connector id and the deployment-keyed digest (as for the
+catalog cache above) of the catalog owner partition (principal, subject,
+caller identity and pool, origin and public URL), the admitted endpoint (plain
+`/mcp`, `/mcp/<pool>` or `/agent/<pool>`), the connector's described
+configuration, whose endpoint keeps its path, and the package version. One owner's
+or endpoint's record never skips another's search. A change `describe()`
+cannot see, such as a static header rotated in deployment code, takes effect
+on redeploy; a record written before it keeps skipping for at most its retry
+time, about 60 seconds. Until its retry time an unscoped search skips that connector
+and reports it in `catalogErrors` with the recorded code, `retryable: true`,
+`retryAfterMs`, and a fixed message that names the scoped search to try it
+now; no tools from the failed walk are ever served. A scoped search still
+probes and settles the record. A record whose generation no longer matches
+lapses, so a vault credential change, OAuth connect or disconnect, or operator
+invalidation clears every partition at once. A success, or an auth or
+permission failure that shows the connector answers, clears the record this
+request saw. Caller cancellation, a probe the budget cut short, a fast
+failure, and a non-retryable failure record nothing. After its retry time a
+record lingers for 60 seconds: the request that dispatches the next probe
+claims it by compare-and-set, with a lease to an absolute time, the end of
+that request's discovery budget plus two seconds, so a slow claim write cannot
+shorten it; the others keep skipping until it settles or the lease lapses. Health reads are one `getMany` per unscoped search, made
+once per request; a health storage failure is logged and never fails
+discovery.
+
+A healthy connector whose complete catalog always takes longer than 5 seconds
+to list can therefore stay out of unscoped discovery: each unscoped probe
+times out and records it. A scoped search, or any operation with the longer
+`discovery.probeTimeoutMs` deadline that completes the listing (describe, a
+tool call), warms a reusable complete catalog that later unscoped searches
+read without the slow listing, and a success clears the record.
+
 `discovery.catalogTtlSeconds` (300 by default) is the fallback for legacy
 listings without `ttlMs`. Positive hints are bounded by
 `catalogMinTtlSeconds` (0) and `catalogMaxTtlSeconds` (86400, also the SDK
@@ -653,7 +839,15 @@ activity write. The first complete catalog is a baseline.
 Hash-only baselines publish bounded chunks before a manifest. They store the
 catalog digest and hashes of each tool name and fact, so added, removed and changed counts require no persisted tool names or
 schemas. They use the exact host auth/config cache partition, survive catalog
-expiry and invalidation, and expire after 48 hours. There is no connection-wide
+expiry and invalidation, and expire 48 hours after they are written. A refresh
+reads the manifest first. When its digest matches a baseline written within the
+last hour, the refresh writes nothing; an older matching baseline is rewritten
+with fresh chunks, so every refresh leaves a baseline for at least 47 hours.
+A manifest's lifetime is never extended without new chunks, so its chunks
+always outlive it. A changed digest writes the new baseline and reports drift
+against the previous one. An unchanged zero-TTL listing therefore writes no
+baseline; it still lists live every time and deletes its cache slots, since a
+concurrent request may have published an older reusable catalog there. There is no connection-wide
 fallback baseline across partitions. Private catalog events use the admitted
 principal actor basis even for shared-auth connectors; activity disclosure
 requires that same owner and the recorded pool's grants. Ownerless private
@@ -1128,7 +1322,11 @@ switched by the environment, and keep their entries under 30 lines.
 A maintained provider is one `defineProvider()` call (`src/provider.ts`): a
 name, title, `kind: "api"`, maintained skill, closed `options` shape and a
 synchronous `create`. Common values are checked before construction and the
-factory stamps its provider name onto `describe().source.provider`. API
+factory stamps its provider name onto `describe().source.provider`. The kit's
+`defineApiProvider` also takes optional `searchSynonyms` groups (single
+lowercase words, at most 32 groups of 2–8), checks them at definition and
+attaches them to each connector for
+[lexical discovery](./meta-tools.md#lexical-discovery). API
 implementations and their contract evidence remain vendored. Hosted MCP servers
 use generic `remoteMcp()` entries; provider reviews and hosted defaults are
 removed. Legacy hosted selectors fail at construction with the generic migration
@@ -1543,7 +1741,10 @@ Use the existing stateful fixture vendors and published-edge deployment adapters
   Node/SQLite/QuickJS and native Workers/D1. It covers transcript-too-large
   recovery, empty intermediate pages, selected fields, withheld photo/credential
   values and shared-vault reuse after application reconstruction. No-op,
-  fabricated-read and erased-delivery controls must fail.
+  fabricated-read and erased-delivery controls must fail. Its fake, tasks and
+  deployment wiring live in `src/providers/granola/eval/`, unshipped;
+  `providers:generate` registers a provider's `eval/` wiring with the harness
+  (`eval/README.md`, provider-local eval wiring).
 - `test/identity-write-journey.node.test.ts` uses the existing Node deployment
   adapter, stateful MCP fake, SQLite vault and QuickJS to grade admitted human
   and machine identities, pool isolation, fail-closed discovery, endpoint and
@@ -1810,10 +2011,10 @@ storage is the root's namespaced to its principal.
 | Admission (`executor-admission.ts`, `call-admission.ts`)               | Queued waiters are Deferreds settled by whoever removes them from the queue; a wait is one flat race of grant, Clock timeout, and signal. The uncontended path stays synchronous. Two controllers, as [#453](https://github.com/zackbart/connecta/issues/453) requires.                                                                                                                                                                                                                                                                                                                                    |
 | One tool call (`invocation.ts`)                                        | One fiber: resolution, the read-only and schema refusals, admission, and the downstream attempt sit under a single `withDeadlineEffect`, whose expiry interrupts the call wherever it is. The permit is an `acquireRelease`; the connector call is `Effect.tryPromise` over the unchanged `Connector`.                                                                                                                                                                                                                                                                                                     |
 | `execute_code` (`execute.ts`)                                          | One fiber whose Scope owns the run's signal and executor lease, so a result, a throw, the watchdog, and cancellation all release the lease and abort the signal the same way. Public executor methods stay Promise-shaped; registered built-in execution composes directly as an Effect under the signal and `execute.watchdogMs`. Queued acquisition retains its Promise request handoff. Each guest host call is a fiber of its own.                                                                                                                                                                     |
-| Discovery (`catalog-service.ts`)                                       | A request-scoped cache: one shared read per connector (`runtime/shared-read.ts`), settled by the read itself and carrying its own signal and the probe timeout whichever asker starts it. Each asker waits under its own deadline and signal, so one that times out or is cancelled fails alone, and the read is cancelled only once every asker has gone. Fan-out is `Effect.forEach` under the discovery concurrency.                                                                                                                                                                                    |
+| Discovery (`catalog-service.ts`)                                       | A request-scoped cache: one shared read per connector (`runtime/shared-read.ts`), settled by the read itself and carrying its own signal and the probe timeout whichever asker starts it. Each asker waits under its own deadline and signal, so one that times out or is cancelled fails alone, and the read is cancelled only once every asker has gone. Fan-out is `Effect.forEach` under the discovery concurrency; unscoped search adds the discovery budget and health record (`discovery-health.ts`).                                                                                               |
 | Registry (`registry.ts`)                                               | The result stash is a program over `Storage`. Same-request catalog loads share one read the way discovery's do. Remote MCP caching uses the SDK ResponseCacheStore adapter over SQL-backed KV, with no cross-request catalog flight.                                                                                                                                                                                                                                                                                                                                                                       |
-| Remote MCP (`connectors/remote-mcp.ts`)                                | Each request scope's state holds a Scope, each connection is a lease forked from it, and a connect in flight is a Deferred carrying the client it connected. Closing a session and the transport are each bounded to a second.                                                                                                                                                                                                                                                                                                                                                                             |
-| Downstream OAuth (`auth/downstream-oauth.ts`, `auth/static-oauth.ts`)  | A refresh flight is a Deferred. Before the first durable coordinator write (claim CAS) is submitted, call/request closure stops preparation without a CAS, token request or state change. Submission transfers renewal to the storage coordinator under its own 35-second preparation deadline and 20-second token-request/body deadline, followed by the fenced rotation commit through the runtime deferred-work hook. A closed caller promptly fails without consuming the result, marking its ledger renewed or sending/resending a resource request.                                                  |
+| Remote MCP (`connectors/remote-mcp.ts`, `connectors/remote-mcp/`)      | Each request scope's state holds a Scope, each connection is a lease forked from it, and a connect in flight is a Deferred carrying the client it connected. Closing a session and the transport are each bounded to a second.                                                                                                                                                                                                                                                                                                                                                                             |
+| Downstream OAuth (`auth/downstream-oauth*`, `auth/static-oauth.ts`)    | A refresh flight is a Deferred. Before the first durable coordinator write (claim CAS) is submitted, call/request closure stops preparation without a CAS, token request or state change. Submission transfers renewal to the storage coordinator under its own 35-second preparation deadline and 20-second token-request/body deadline, followed by the fenced rotation commit through the runtime deferred-work hook. A closed caller promptly fails without consuming the result, marking its ledger renewed or sending/resending a resource request.                                                  |
 | Operator and activity data (`routes/operator.ts`)                      | Each JSON route is one program run by `serveOperator` behind the Promise `handle()`. Reads run under the request's signal; writes do not, so a vault write or OAuth disconnect that started reaches its cache invalidation.                                                                                                                                                                                                                                                                                                                                                                                |
 | QuickJS pool (`executors/quickjs.ts`, Node only)                       | Each child is a scoped resource whose release sends SIGTERM, then SIGKILL after a second; crash respawn backoff is a `Schedule`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
@@ -1974,6 +2175,11 @@ value, matching that fallback. Interruption remains interruption. The lookup
 module imports no SQL or platform implementation and does not change the
 published storage interfaces.
 
+`NativeStorage.getMany` reads several keys in one statement, answering by
+position exactly as one `get` per key would; the SQL drivers share it, a
+replaced `get` answers each key itself, and other stores fall back to one `get`
+at a time. Catalog reads fetch up to eight chunks per round trip with it.
+
 `openSqlite` retains file modes, WAL, busy timeout,
 and database ownership. `test/sql-effect-contract.ts` retains affected-row,
 50-claim, typed-failure, cancellation, and tracing probes on SQLite and native
@@ -2133,6 +2339,93 @@ within five minutes of expiry in the same auth partition. Partial walks and
 auth or permission failures refuse fallback; resources require unexpired
 inventories, and stale fallback cannot authorize post-entry auth recovery.
 
+**Repeated reads share one request's memo.** `src/runtime/request-reads.ts`
+gives each request owner a memo of storage reads, emptied when the request
+closes (INV-7). It holds plain strings keyed by the physical key in the
+underlying store, so namespaced views of one partition share an entry and two
+principals' partitions never do. A read consults it only where the call site
+opts in and states why staleness within one request is safe; every other read
+goes to storage.
+
+- Every write through the SQL drivers, `memoryStorage()` or a namespaced view
+  over them drops that key from every open memo in the same isolate, before
+  submission and again on settlement. A read that such a write overlapped is
+  not recorded.
+- Only the latest read of a key that the request started records. An earlier
+  read that settles later never replaces a newer fresh observation.
+- A fresh read records what it saw, so a memoized reader is never older than
+  its request's latest fresh read of the key.
+- A custom store, or a built-in one with a replaced method, is never memoized.
+- A runtime without `WeakRef` and `FinalizationRegistry` memoizes nothing:
+  workerd before compatibility date 2025-05-05 without `enable_weak_ref` reads
+  storage every time.
+
+The memo cannot see another isolate, another process sharing the database, or
+an entry expiring. After the first read, a memoized key can lag such a change
+for the rest of the request. So nothing that gates authority, sends a
+credential, or decides a write is memoized.
+
+Memoized:
+
+- the negotiation verdict, which only orders handshake versions;
+- catalog generation reads that only locate an entry, accepted or refused by a
+  fresh fence;
+- the credential reads behind connector status, drift and the operator UI card,
+  which only label a view. Only the built-in vault with its original `getAll`
+  and `metadata` shares a read; a custom vault, a subclass, or an instance
+  that overrides either method is called itself for every read, dispatch
+  included.
+
+Always fresh:
+
+- every OAuth grant read, including the token and epoch check behind each SDK
+  message (a disconnect need not revoke the vendor token), `peekGrant` and
+  every cache-acceptance identity check, compare-and-set loops, refresh claims
+  and leases, resets and disconnects;
+- the catalog generation fence before a cached entry is served or published;
+- the credential a call sends.
+
+`test/request-reads.node.test.ts` holds the memo's contract, including a
+disconnect written by another isolate between paginated `tools/list` pages.
+
+### Request budgets (contributor)
+
+`test/request-reads.node.test.ts` also guards the common request shapes the way
+bundle caps guard size. Each case counts downstream HTTP requests, D1 round
+trips (`all`, `run` or `batch`) and SQL statements separately, since a batch is
+one round trip but several statements. The fixture is production-shaped: D1
+over `node:sqlite`, a sealed vault holding the API credential and the OAuth
+grant, Cloudflare Access with `accessTokens()`, a D1 activity sink settled
+through `waitUntil`, the operator UI and QuickJS standing in for Dynamic Worker
+startup. "Cold isolate" is a new deployment instance over the populated
+database. The ceilings, measured value plus about 10% D1 headroom and exact
+downstream counts, live in its `BUDGETS` table. Measured on main in October 2026:
+
+| Request                                  | Downstream | D1 round trips | SQL statements |
+| ---------------------------------------- | ---------: | -------------: | -------------: |
+| Legacy remote MCP call, warm             |          5 |              6 |              7 |
+| Legacy remote MCP call, cold isolate     |          5 |              9 |             12 |
+| Modern remote MCP call, warm             |          1 |              7 |              8 |
+| Modern remote MCP call, cold isolate     |          1 |             10 |             13 |
+| OAuth remote MCP call, warm              |          5 |             19 |             20 |
+| OAuth remote MCP call, cold isolate      |          5 |             22 |             25 |
+| OAuth call after a 401, with refresh     |          9 |             39 |             48 |
+| OAuth call with proactive refresh        |          6 |             35 |             43 |
+| `api()` credential call, warm            |          1 |              3 |              4 |
+| `api()` credential call, cold isolate    |          1 |              6 |              9 |
+| Unscoped search, warm (3 remote, 1 api)  |          0 |             20 |             20 |
+| `execute_code`, 5 calls to one connector |          9 |             10 |             15 |
+| UI connector detail, `api()` credential  |          0 |              2 |              2 |
+| UI connector detail, credential remote   |          4 |              9 |              9 |
+| UI connector detail, OAuth remote        |          4 |             18 |             18 |
+
+Header-auth calls to the legacy (session) server handshake per request:
+`initialize`, `notifications/initialized`, the SSE `GET`, the call and the
+session `DELETE`. The modern server advertises a catalog TTL, so a warm call is
+the call alone. OAuth calls read the grant fresh before every SDK message.
+Run with `D1_BUDGET_REPORT=1` to print each measurement; a failing case prints
+its request and statement log.
+
 ### Contributor provider kit
 
 Provider declarations use `src/http/vendor.ts` for HttpApi operations and
@@ -2151,17 +2444,29 @@ exact vendor count as `page.total` from its page callback. The kit validates a
 nonnegative safe integer and includes it on continuing and terminal pages;
 without a vendor count the property is absent. Lists without the opt-in keep
 their existing schema and result bytes. Never derive an exact total from a
-partial page or an estimate. `src/http/fields.ts` refuses an unknown first
-segment before dispatch; a selected
-result renders against a sparse output schema. `src/http/hatch.ts` is the
+partial page or an estimate. `src/http/fields.ts` derives each `fields`
+description's anchor and example from the contract that validates it. It
+refuses before dispatch a path whose first segment is not a declared property,
+and a deeper segment only inside an object the schema closes with
+`additionalProperties: false`; a selected result renders against a sparse
+output schema. `src/http/hatch.ts` is the
 standard hatch (`_api_search`, `_api_details`, `_api_read`, `_api_write`) over
 an `OperationIndex` with explicit verdicts. It keeps the REST family's
 argument and envelope names and validates `fields` against the operation's
-declared response roots before dispatch. Search answers stay within 16 KiB
+declared response roots before dispatch. A deeper miss is reported in
+bounded `warnings` naming declared properties only, never refused, because the
+pinned index declares paths only to a bounded depth. Search answers stay within 16 KiB
 (at most eight compact entries, long labels cut and marked, continuation by
 cursor); details stay within 32 KiB, paging whole parameters and body
 properties, and chunking any piece larger than one answer, behind a bound
-cursor. Standard hatch search removes conversational framing; framing-only
+cursor. `src/http/hatch-response.ts` builds details' capped `response` section
+from the index's declared response paths in `fields` coordinates. It lists
+selectable paths and promises no readability. Its `withheld` hint comes from
+`ResultSafety.withholds`: `ValueSafety.withholds` reads the rules `redact`
+applies that change every non-null value they reach, matched with list
+markers. Custom redactions may declare their own hint. Rules that can pass a
+value through (`url:`, `origin:`, `[?…]`, `@keys`, string-only scrubbing) are
+never hints. Standard hatch search removes conversational framing; framing-only
 queries return no matches. It admits partial lexical matches alongside full
 matches. Action/read queries require all content nouns in the operation text,
 or any noun in the path/id with at least half the nouns in the text. Their
@@ -2308,9 +2613,10 @@ A binding may opt into `truncated: true` to supply reviewed size-cut paths
 (such as `data.content`) in its answer. The hatch then declares and propagates
 an optional top-level `truncated: string[]` on reads and writes. Without the
 opt-in, the schemas and results are unchanged; size-cut metadata is not inferred
-from vendor booleans or added to other providers. A separate `warnings: true`
-opt-in declares and preserves reviewed `warnings: string[]` beside `data`, even
-when `fields` narrows the vendor body.
+from vendor booleans or added to other providers. Every hatch read and write
+declares an optional `warnings: string[]` for `fields` entries that matched
+nothing in a nonempty body. A separate `warnings: true` opt-in also preserves
+reviewed vendor warnings there, even when `fields` narrows the vendor body.
 
 A binding may expand deployment-owned path defaults (Cloudflare) or canonicalize
 repository contents paths (GitHub) before indexed resolution, and may prepare a
@@ -2839,6 +3145,51 @@ Effect is pinned exactly; deployments using Effect must resolve the same version
 Per-provider bundles are reported, not capped, because their standalone graphs
 include the shared core again. Deployed non-provider shapes are capped by
 `scripts/bundle-budget.json`.
+The always-loaded agent surface has fixed-cost caps of the same kind: the
+`always-loaded agent surface budgets` cases in
+`test/meta-tool-schemas.test.ts` cap the instructions plus `tools/list` total,
+each tool description and output schema, the `usage` skill, and one default
+and one compact search row, measured on a pinned four-connector fixture.
+
+### Route names
+
+Connecta-authored agent text names a route in the wording of the surface that
+serves it, resolved when the text is built (`src/agent-routes.ts`). Nothing
+renders afterwards: no code scans or rewrites replies, program values,
+downstream results, resources, guides or caller data, so paging, previews,
+totals and offsets measure the final text.
+
+Two tables per surface. `AgentRouteNames` names the tools (`call_tool`,
+`call_destructive_tool`, `search_tools`, `execute_code`, `authorize_connector`,
+`skills` on the meta surface); a sentence uses a name only when written for a
+surface that lists that tool. `RoutePhrases` holds complete phrases for
+sentences every surface shares, such as "for a direct call_tool only" against
+"when calling this tool directly", "call directly (call_tool, connecta.result
+to page)" against "call this tool directly and page with read_result", and the
+authorization sentences, which on native pools tell the agent to give the
+error's nextAction to the user or operator. `program` is undefined on a native
+pool without `execute_code`, so text about program capacity branches on it.
+The eval code arm's phrases keep the text its comparator protocol recorded.
+
+Where each text gets its wording:
+
+| Text                                                            | Wording                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Invocation refusals, authorization handoffs, paging notices     | The request's names, from the MCP route through meta-tools, programs and native pools                                                                                                                                                                                                                                                                          |
+| Connector and provider call text                                | `routePhrases(ctx)`; inside a call's Effect, the `Routes` reference; vendor tables' `words(detail, routes)`; an `api()` connection's write-401 refusal, configured at construction, receives the call's `Routes`                                                                                                                                               |
+| Contexts the registry builds                                    | The deployment's names (meta, or the eval code arm's); a call carries its request's names                                                                                                                                                                                                                                                                      |
+| Static provider schema descriptions                             | `routeDescription(build)`: the declared meta text; each request's catalog sets them on its own copy of each `api()` tool, which keeps the tool's source classification, built for its serving surface. Description paths are cached per connector and tool name, and rendered text per declared description and surface. Downstream catalogs are never touched |
+| Meta instructions, meta-only tool descriptions, built-in guides | Meta names, built once; built-in guides keep one digest across deployments                                                                                                                                                                                                                                                                                     |
+| Native instructions, the `execute_code` description             | Built per surface                                                                                                                                                                                                                                                                                                                                              |
+| Program-return and program-call paging notes                    | Meta names; they name only `execute_code`, which every surface running programs lists                                                                                                                                                                                                                                                                          |
+| The OAuth adapter's `UnauthorizedError`                         | Meta names; only its class reaches callers, which word their own error from the call                                                                                                                                                                                                                                                                           |
+
+The provider standard's S7 check refuses a spelled-out meta-tool name in
+provider code. Remaining literals are not agent route text: `execute_code`'s own
+budget and timeout errors, operator log lines, construction errors, the
+configuration reference, the OAuth callback page and operator fix prompts. The
+eval code arm marks its configuration with `renderRoutesAsPrograms`, an internal
+hook no package entry exports; no configuration key selects it.
 
 [Decision 0019](https://github.com/zackbart/connecta/blob/main/decisions/0019-core-validation-http-boundaries.md) records the rejected Schema/HttpApi measurements.
 
@@ -2973,7 +3324,10 @@ compiling and configuring the real thing.
   is a known failure only on refusal provenance recorded where the evidence is
   observed, never inferred from an error code: (a) the ledger proves it never
   left, or (b) the downstream served an HTTP refusal, a 4xx other than 408
-  (`refusedStatus` and `vendorRefusal` in `src/provider-call.ts`), under the
+  (`refusedStatus` and `vendorRefusal` in `src/provider-call.ts`); for
+  `remoteMcp()` only when that 4xx carries a JSON-RPC error body, since a bare
+  one may be a gateway's answer after the server acted (`ambiguous` on the
+  call's dispatch in `src/connectors/remote-mcp/transport.ts`), under the
   provider's existing served classification (a write's HTTP 409 is a `conflict`). One helper, `servedRefusal` in `src/write-outcome.ts`, decides
   (b) for the ledger and for a transport outside one: a refusing status the
   provider reads as `unavailable` or a timeout (Stripe's 424) is not proof, so
@@ -3419,8 +3773,19 @@ change. All 88 declarations still exclude Effect and have complete references.
 ### Native remote MCP programs (contributor)
 
 Remote MCP connection joins, credential and epoch checks, catalog intake,
-negotiation, calls, resources, Skills, auth and status compose native programs in
-`connectors/remote-mcp.ts`. `catalog-cache.ts` owns native SDK cache reads,
+negotiation, calls, resources, Skills, auth and status compose native programs.
+`connectors/remote-mcp.ts` keeps the published options, the redirect guard and
+`remoteMcp()`, which builds one runtime from per-seam factories in
+`connectors/remote-mcp/`: `config.ts` (options and validation), `errors.ts`
+(boundary error mapping), `transport.ts` (transport and write-once dispatch),
+`connection.ts` (the per-scope connection state machine), `catalog.ts`
+(catalog intake), `resources.ts` (Skills and resource reads), `oauth.ts` (the
+OAuth surface) and `call.ts` (`callTool`); `runtime.ts` types what they share.
+`auth/downstream-oauth.ts` keeps `KvOAuthProvider`'s state and declared
+methods; `auth/downstream-oauth/` holds the refresh coordinator and, by seam,
+the provider's native method bodies (grant and epoch store, consent records,
+refresh lease and spent records, SDK hooks), installed once each by
+`authMethods`. `catalog-cache.ts` owns native SDK cache reads,
 chunked publication, generation fencing, complete refresh acceptance and listing
 serialization; `connectors/negotiation-cache.ts` owns native negotiation storage.
 The published connector, cache and SDK callback methods remain Promise shells.