@zackbart/connecta 0.28.1 → 0.30.0

package/documentation/architecture.md

@@ -4,72 +4,107 @@ One Web-standard `fetch(request) => Promise<Response>` handler, a long-lived
 registry behind it, and a strict rule about what may be imported. Everything
 else in this repository is a detail of those three things.
 
-Read [`ethos.md`](../ethos.md) first; this guide says how the shape it describes
-is assembled and where each subsystem lives. The surface itself belongs to
+Read [PRINCIPLES.md](https://github.com/zackbart/connecta/blob/main/PRINCIPLES.md)
+first; this guide explains the shape and where each subsystem lives. The surface itself belongs to
 [meta-tools](./meta-tools.md), [code mode](./code-mode.md), and
 [inbound auth](./auth.md).
 
+## Task routes
+
+[Agent index](./README.md) routes endpoint use, deployment, integration, and
+repository maintenance. Read this guide when changing the core or checking an
+implementation boundary. Use these sections for the affected subsystem.
+
+| Change or question                      | Sections                                                                                                                                      |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Request handling, transport, cleanup    | [Two lifetimes](#the-two-lifetimes), [request lifecycle](#request-lifecycle), [admission](#admission-in-two-places)                           |
+| Discovery, invocation, classification   | [Layers below meta-tools](#layers-below-the-meta-tools), [providers and classification](#providers-and-reviewed-classification)               |
+| Storage, credentials, catalogs, paging  | [Storage and connectors](#storage-credentials-and-connectors), [errors and records](#errors-and-records)                                      |
+| Config validation and optional features | [Configuration](#configuration), [modules](#optional-deployment-modules), [operator contract](./operator-ui.md#operator-data-contract)        |
+| Imports, executors, or Effect           | [Purity](#import-graph-purity), [Effect](#effect-inside), [sharp edges](#sharp-edges)                                                         |
+| Find code and deployment evidence       | [Source map](#where-else-to-look), [sharp edges](#sharp-edges), [repository policy](https://github.com/zackbart/connecta/blob/main/AGENTS.md) |
+
+Source paths and test names in each section identify its implementation and
+regression evidence. Recorded production probes and bundle measurements are
+historical observations tied to their stated date or version, not current
+benchmarks or proof that planned replacements have shipped.
+
 ## The two lifetimes
 
 Almost every bug in this codebase is a lifetime mistake, so the split is worth
 stating before anything else.
 
 **Per isolate, built once.** `createConnecta(config)` returns
-`{ fetch, registry, close }` (`src/index.ts`). The `Registry` owns the connector
-set, address resolution, catalog caches, observed output schemas, connector
+`{ fetch, registry, describeConfig, close }` (`src/index.ts`). The `Registry` owns the connector
+set, address resolution, request-local catalog reads, observed output schemas, connector
 health, and the per-connector call limiters. It is built once and lives as long
 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
-(`src/auth/static-oauth.ts`, the same provider with its discovery and client
-answered from config) — also owns a runtime-local refresh completion gate
-(`src/auth/downstream-oauth.ts`). It coordinates credential mutation across
-concurrent request scopes while sharing no client, transport, or response, and
-never lets a follower cancel the owner. The subtle part is that a valid token
-response consumes the refresh token whether or not the owner survives to save it,
-so the accepted tokens live on the flight: cancelling the owner *before* a valid
-response fails the joiners, because promoting one could replay a token the
-authorization server already consumed, while cancelling it *after* one does not —
-the host persists the rotation on its own write, holds contenders behind a
-generation-keyed pending-mutation marker until that write lands, and hands them
-the saved rotation ([#526](https://github.com/zackbart/connecta/issues/526)).
+An OAuth connector, `remoteMcp()` or `api()` with a static grant, owns a
+runtime-local refresh completion gate in `src/auth/downstream-oauth.ts`.
+Joined scopes share the outcome while keeping their own request I/O and
+cancellation. A shared-storage CAS lease prevents independent isolates from
+redeeming the same refresh token concurrently. The holder commits an accepted
+rotation to the grant by CAS before releasing waiters, even when the owner
+cancels after dispatch. The HTTP exchange uses its own 20-second deadline,
+detached from caller cancellation, and the runtime passes its completion and
+commit to Workers `waitUntil`. Contenders read the committed tokens or typed
+verdict. An unsent claim can be taken over after expiry. Dispatch uses a lease CAS
+transition and a CAS of the token fingerprint into permanent spent storage
+before sending. Fingerprint records have no TTL and carry outstanding,
+ambiguous, or resolved state across Restart and Disconnect. Outstanding and
+ambiguous fingerprints block every epoch. A resolved fingerprint can be sent
+once in a later epoch only when its code exchange observed the resolved
+storage write before completing. Holder liveness survives reset until
+completion or expiry. Credential-bearing
+token requests use manual fetch and bypass resource redirect handling. Every
+3xx requires re-consent after a refresh and refuses a code exchange. The HTTP
+deadline is 20 seconds. A sent request
+whose 120-second storage-owned liveness record expired without a commit is
+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.
 
 **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
-request that created them. `Nothing request-bound survives a request` is an ethos
-invariant, not a style preference: a client retained across requests on Workers
-is a cross-request capability leak, and a promise awaited after the response is
+request that created them. INV-7 requires this lifetime: a client retained
+across requests on Workers is a cross-request capability leak, and a promise awaited after the response is
 work the runtime may already have torn down. Deferred work has one sanctioned
 channel, `ctx.waitUntil`, threaded through `fetch(request, env, ctx)` — activity
-writes use it, as does a stale-window catalog refresh, which owns a fresh scope
-and deadline rather than carrying the inbound one past the request. And a fresh
+writes and dispatched OAuth grant commits use it. Catalog listing and SQL cache
+publication finish in the requesting scope. A fresh
 `McpServer` per request is what makes the deployment stateless: no sessions, no
 server push, no stream resumability, scope resolved rather than remembered.
 
 ## Request lifecycle
 
 `src/server.ts` is the composition root: MCP origin check, scheme upgrade, route
-table, security headers. Route *order* is the contract — several routes would
+table, security headers. Route _order_ is the contract — several routes would
 behave differently if they were reachable in another order — so read the table
 top to bottom.
 
-| Order | Route | Notes |
-| --- | --- | --- |
-| 0 | MCP Origin check | A disallowed `Origin` on `/mcp*` is a fixed 403 before redirects, admission, auth, or preflight — costing no permit and no auth lookup. Originless requests are admitted. |
-| 0 | HTTPS upgrade | 308 to an HTTPS `publicUrl`, with path and query *assigned* onto it rather than resolved against it, so a `//host` pathname cannot replace the origin. `/health` is exempt: a loopback probe must not need public DNS. |
-| 0 | Cloudflare Access (Worker, when enabled) | Edge admission ahead of this table; an admitted invocation carries trusted identity in `ctx.access`. |
-| 1 | Mounted UI routes | Before wildcard OPTIONS, so mutation routes refuse preflight rather than inheriting MCP CORS. No UI module, no routes. |
-| 2 | MCP preflight | Allowed `OPTIONS` on `/mcp*`: 204 without admission or auth. |
-| 2 | Other `OPTIONS` | Auth metadata first, otherwise compatibility CORS preflight. |
-| 3 | `/.well-known/*` | Auth metadata, or 404. |
-| 4 | `/health` | Open and payload-free: health, executor, admission, and deployment metadata, with drift as stable short hashes. |
-| 5 | `/oauth/callback/<connectorId>` | Core downstream OAuth completion, state and personal-ownership checked, independent of the UI. |
-| 6 | `/mcp`, `/mcp/<pool>` | Admission, then auth, then a request-local MCP server. An undeclared pool, a refusing grant, and a throwing grant are one identical 404; see [pools](./auth.md#pools). |
-| 7 | Other paths | 404. Custom HTTP routes belong to the deployment. |
-
-Every response leaves through `withSecurityHeaders`, and the UI module adds a
-nonce-based script CSP and framing denial to its shells.
+| Order | Route                                                     | Notes                                                                                                                                                                                                                                                              |
+| ----- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 0     | MCP Origin check                                          | A disallowed `Origin` on `/mcp*` is a fixed 403 before redirects, admission, auth, or preflight — costing no permit and no auth lookup. Originless requests are admitted.                                                                                          |
+| 0     | HTTPS upgrade                                             | 308 to an HTTPS `publicUrl`, with path and query _assigned_ onto it rather than resolved against it, so a `//host` pathname cannot replace the origin. `/health` is exempt: a loopback probe must not need public DNS.                                             |
+| 0     | Cloudflare Access (Worker, when enabled)                  | Edge admission ahead of this table; an admitted invocation carries trusted identity in `ctx.access`.                                                                                                                                                               |
+| 1     | `/oauth/client-metadata/<connectorId>`                    | Public GET-only CIMD for configured self-hosted OAuth connectors; fixed `publicUrl`, no auth or storage.                                                                                                                                                           |
+| 1     | Mounted UI routes                                         | Before wildcard OPTIONS, so mutation routes refuse preflight rather than inheriting MCP CORS. No UI module, no routes.                                                                                                                                             |
+| 1     | `/connect/<connectorId>`, `/oauth/callback/<connectorId>` | GET-only browser OAuth routes, before wildcard OPTIONS. Both verify the initiating user and management permission, independent of the UI.                                                                                                                          |
+| 2     | MCP preflight                                             | Allowed `OPTIONS` on `/mcp*`: 204 without admission or auth.                                                                                                                                                                                                       |
+| 2     | Other `OPTIONS`                                           | Auth metadata first, otherwise compatibility CORS preflight.                                                                                                                                                                                                       |
+| 3     | `/.well-known/*`                                          | Auth metadata, or 404.                                                                                                                                                                                                                                             |
+| 4     | `/health`                                                 | Open and payload-free: health, executor, admission, and deployment metadata.                                                                                                                                                                                       |
+| 6     | `/mcp`, `/mcp/<pool>`                                     | Admission, then auth, then a request-local MCP server. Body-confirmed modern listens skip admission and are refused after auth and SDK validation. An undeclared pool, a refusing grant, and a throwing grant are one identical 404; see [pools](./auth.md#pools). |
+| 7     | Other paths                                               | 404. Custom HTTP routes belong to the deployment.                                                                                                                                                                                                                  |
+
+Every response leaves through `withSecurityHeaders`. HTML uses one common
+security-header helper, including status and error pages. Operator shells
+allow same-origin scripts and deny framing. Clerk pages also admit the validated
+loader origin, the exact Cloudflare CAPTCHA script and frame host, Clerk images,
+and first-party or blob workers. Local Clerk sign-in adds a nonce for its bootstrap.
 `test/server-route-contracts.test.ts` pins the ordering and the exact refusal
 bodies; it exists because the ordering is invisible in any one file and a
 reordering reads like a harmless refactor.
@@ -77,41 +112,112 @@ reordering reads like a harmless refactor.
 An admitted non-preflight `/mcp` request then takes five steps in
 `src/routes/mcp.ts`:
 
-1. **Admit.** One permit from the deployment-wide pool, taken before auth so an
+1. **Admit.** Modern `subscriptions/listen` requests take no permit: their
+   mirrored method and parsed body must both name the unsupported method.
+   They still pass auth, pool grants, and SDK validation, then receive HTTP
+   404 with JSON-RPC `-32601`. Their body classification and auth share the
+   configured request lifetime, starting before classification. Other requests
+   take one permit from the deployment-wide pool, taken before auth so an
    unauthenticated flood costs a permit rather than a Clerk lookup, and held
-   until the response *body* completes, the caller leaves, or its configured
+   until the response _body_ completes, the caller leaves, or its configured
    lifetime ends, not until the handler returns.
-2. **Authorize.** Each `InboundAuth` provider's `authorize` in order, bearer
-   before interactive. First `ok` admits; if all fail, the last provider's
-   challenge is returned. No providers means open — development only, and it
-   warns at construction.
+2. **Authorize.** Machine tokens precede interactive providers. A provider's
+   synchronous credential recognition selects the sole verifier for an explicit
+   credential; a refusal never falls back to another identity. Human routes
+   reject machine credentials without verification. With no recognized
+   credential, configured providers are tried in order. A 401 takes its
+   challenge from the actual protected-resource metadata owner. No providers
+   means open development and warns at construction.
 3. **Narrow to the pool.** On `/mcp/<pool>`, look the name up, run its grant
    against the identity, then `intersectAccess` the pool with the identity's own
    access. A pool can never widen a view; anything else is a 404 naming no pool.
 4. **Derive the registry view.** One `registry.scoped(...)` call with those
    connector ids, exact `connector.tool` addresses when the identity declares a
    narrower slice, and the subject and principal keys. Personal connectors use
-   the principal partition, result paging the subject partition, and no caller
-   parameter selects either (`test/identity-scope.test.ts`).
+   the principal partition and result paging the subject partition with principal,
+   endpoint/pool, origin, connector, and tool bindings. Paging rechecks current
+   grants, pool membership, and trust; no caller parameter selects a partition (`test/identity-scope.test.ts`).
 5. **Serve.** Refuse `?toolkit=` with a 404 — the toolkits are gone
    ([#178](https://github.com/zackbart/connecta/issues/178)) but their URLs were
    handed out, and retiring a scoping boundary into fail-open is worse than any
-   404 — then register the seven meta-tools on a fresh `McpServer`
+   404 — then register the six meta-tools on a fresh `McpServer`
    (`test/server.test.ts`, `test/code-first-surface.test.ts`).
 
+### Modern request metadata and transport refusals
+
+The SDK lifts each modern request's client declarations from `_meta` into
+`ctx.mcpReq.envelope`. Meta-tool handlers bind `clientCapabilities` and
+`clientInfo` to their request-local context before dispatch. These declarations
+never select an identity, grant, connector view, or pool. Direct and program
+activity records retain only the self-declared `clientName` and `clientVersion`,
+validated by one ASCII grammar at the record builder, SQL write/read boundaries,
+and authenticated activity read route. Names match
+`[A-Za-z0-9][A-Za-z0-9 ._@/+-]{0,63}`; versions match
+`[A-Za-z0-9][A-Za-z0-9._+-]{0,31}`, each as a whole string. Names allow up to
+64 characters, versions up to 32. `__proto__`, `constructor`, and `prototype`
+are reserved. Invalid values are absent, never truncated or escaped. Capabilities and other client metadata never enter activity.
+Legacy requests without an envelope leave client facts absent.
+Every emitted activity event also carries `packageVersion`, generated from
+`package.json` before build and independent of the display-only `serverInfo`.
+Doctor uses and reports that same generated version. SQL stores validate
+package versions against a bounded release-version grammar on write and read;
+the nullable `package_version` migration leaves old rows unknown rather than
+assigning today's version to history. `/ui/api/activity` serves these facts
+read-only with the same authorization and validation as `/ui/activity`.
+Catalog changes emit discrete, payload-free activity events after accepted
+refreshes. Reviewed drift observations remain in authenticated connector status
+and the maintainer-run provider check; public health counts are removed.
+
+`server/discover` advertises `io.modelcontextprotocol/skills` and `resources: {}`
+with private one-hour discovery cache hints. It includes the configured identity, icons, title,
+and website in `io.modelcontextprotocol/serverInfo` result metadata. The Skills
+extension and its skill-only resources share `src/skills.ts` with the meta-tool
+and guest API. Both direct
+call tools declare `address` as `x-mcp-header: "Address"`, which the SDK mirrors
+and validates as `Mcp-Param-Address` on modern requests.
+
+Connecta's own admission, deadline, pool, and access refusals use JSON-RPC error
+bodies with `Cache-Control: no-store` and the HTTP statuses below. They omit the
+unknown RPC id because the route refuses before decoding the RPC body. An aborted
+request releases its resources without cancelling a newly created deadline
+error body. Auth adapters continue to own their challenges and refusal bodies.
+Admission and Connecta-owned refusal bodies share the MCP exchange's
+request-scoped sent-credential set and pass through `redactAgentOutput` before
+serialization. The SDK's `server/discover` response and registered meta-tool
+results use that same set; connector contexts retain only an opaque scope.
+
+| Refusal                             | HTTP status | Application code | Previous code |
+| ----------------------------------- | ----------- | ---------------- | ------------- |
+| Request capacity exhausted          | 503         | `-33001`         | `-31001`      |
+| Server shutting down                | 503         | `-33002`         | `-31002`      |
+| Request lifetime exceeded           | 504         | `-33003`         | none          |
+| Pool missing or refused             | 404         | `-33004`         | none          |
+| Origin or admitted access forbidden | 403         | `-33005`         | none          |
+
+These allocations are outside JSON-RPC's reserved `-32768..-32000` range and
+MCP's `-32020..-32099` range. The prior admission codes were also outside those
+ranges; the migration changes the application allocation, not a reserved-code
+violation. See the [2026-07-28 error-code policy](https://modelcontextprotocol.io/specification/2026-07-28/basic#error-codes).
+
+`connecta doctor` uses SDK auto negotiation, checks the exported
+`META_TOOL_NAMES` set, and reports the negotiated revision. It closes its client
+on success or failure and refuses credential-bearing redirects during discovery,
+legacy initialization, and tool calls.
+
 ## Layers below the meta-tools
 
 The meta-tool handlers are thin. The work sits in six modules the registry owns
 or hands out, and a change usually belongs in exactly one of them:
 
-| Module | Owns |
-| --- | --- |
-| `src/registry.ts` | The connector set, identity-scoped views, personal storage partitions, address resolution, catalog TTL/persistence/completeness, refresh single-flight, connector health, per-connector call limiters, and drift. Construction-time refusals live here. |
-| `src/catalog-service.ts` | Request-local listing, search, and describe. Caches catalogs inside one request, fans discovery probes out under deadlines, and opts agent reads into the runtime's deferred catalog channel when one exists. |
-| `src/invocation.ts` | One tool call: argument validation, call admission, one-attempt timeout, provider retry hints, result unwrapping, size capping, and the activity record. |
-| `src/catalog.ts` | Ranking, description summarizing, and the compact and TypeScript schema renderers discovery shows. |
-| `src/result-shapes.ts` | Bounded runtime-only inference and merging for output shapes learned from successful read-only calls whose providers declared none. |
-| `src/exempt-writes.ts` | The writes a program may send, which config exempted from asking: the write budget's default, what a dispatched write's outcome says about whether it landed, and the tracking that lets one outlive the program without hiding an unknown outcome. Every other program write is refused before it reaches this. |
+| Module                   | Owns                                                                                                                                                                                                                             |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/registry.ts`        | The connector set, identity-scoped views, personal storage partitions, address resolution, request-local complete-catalog reads, connector health, per-connector call limiters, and drift. Construction-time refusals live here. |
+| `src/catalog-cache.ts`   | SQL-backed SDK tools/resource/template listing cache, intake redaction, TTL bounds, host auth partitions, invalidation generations, and completed-refresh observations.                                                          |
+| `src/catalog-service.ts` | Request-local listing, search, and describe. Caches catalogs inside one request and fans discovery probes out under deadlines.                                                                                                   |
+| `src/invocation.ts`      | One tool call: argument validation, call admission, one-attempt timeout, provider retry hints, result unwrapping, size capping, and the activity record.                                                                         |
+| `src/catalog.ts`         | Ranking, description summarizing, and the compact and TypeScript schema renderers discovery shows.                                                                                                                               |
+| `src/result-shapes.ts`   | Bounded runtime-only inference and merging for output shapes learned from successful read-only calls whose providers declared none.                                                                                              |
+| `src/program-writes.ts`  | Trusted-pool write accounting: write budgets, dispatch draining, and known or unknown outcomes.                                                                                                                                  |
 
 `src/meta-tools.ts` and `src/execute.ts` are two front doors onto the same two
 services, `CatalogService` and `InvocationService`. That is the point: a
@@ -121,11 +227,18 @@ same credential resolution, and the same fail-closed read-only check.
 `test/execute.test.ts` asserts the parity directly, because a sandbox path that
 quietly diverges is how generated code would mint a capability.
 
+Program result paging shares `meta-tools.ts`'s direct-call stash envelope and
+reader. `program-result.ts` owns executor-independent byte limits;
+`execute.ts` issues bounded transfer cursors, and `guest-runtime.ts` reconstructs
+values through provider preludes. Cursors hold only an ID and offset for the
+current run. Result bytes, expiry, authority and capacity charges stay in the
+existing storage and ledger; no executor-specific store or storage key is added.
+
 ## Admission, in two places
 
 Request admission (`src/executor-admission.ts`, applied in `src/routes/mcp.ts`)
 bounds the MCP envelope: one deployment-wide FIFO pool, plus a deliberately
-smaller code pool a program takes a *second* permit from, so one request cannot
+smaller code pool a program takes a _second_ permit from, so one request cannot
 trade ordinary capacity for unbounded sandboxes. `admission.code` is only a
 fallback — an executor implementing `acquire()` owns a bounded pool already, its
 settings win, and connecta warns the fallback was ignored. Invalid bounds throw
@@ -166,16 +279,16 @@ queue. Health checks and subsequent MCP requests confirmed the same isolate ID.
 The [recorded observations](https://github.com/zackbart/connecta/blob/a0ac904513fac735582b4bc9c817a48300134328/scripts/probes/worker-disconnect-2026-09-25.json)
 contain all twelve cases, including served flags and client-end timing.
 
-| Response and flag | Raw stream abort / cancel | Connecta source abort / cancel | Admission after response; next request |
-| --- | --- | --- | --- |
-| Heartbeats, no flag | neither | neither | active 1; 503 |
-| Idle with a pending timer, no flag | neither | neither | active 1; 503 |
-| Heartbeats, request signal enabled | abort only | both | active 0; 200 |
-| Idle with a pending timer, request signal enabled | abort only | both | active 0; 200 |
-| One chunk, then no timer or I/O, either configuration | neither | neither | active 1; 503 |
+| Response and flag                                     | Raw stream abort / cancel | Connecta source abort / cancel | Admission after response; next request |
+| ----------------------------------------------------- | ------------------------- | ------------------------------ | -------------------------------------- |
+| Heartbeats, no flag                                   | neither                   | neither                        | active 1; 503                          |
+| Idle with a pending timer, no flag                    | neither                   | neither                        | active 1; 503                          |
+| Heartbeats, request signal enabled                    | abort only                | both                           | active 0; 200                          |
+| Idle with a pending timer, request signal enabled     | abort only                | both                           | active 0; 200                          |
+| One chunk, then no timer or I/O, either configuration | neither                   | neither                        | active 1; 503                          |
 
 The last row is a different failure. The client observed the response end
-*before* its planned disconnect, although the source never closed itself.
+_before_ its planned disconnect, although the source never closed itself.
 The runtime ended the response without running JavaScript cleanup. This does
 not show a missing abort on a still-live request. The other cases remained open
 until the client aborted. Admission was sampled 1.5 seconds later, followed by
@@ -217,26 +330,193 @@ exposed by the deployment; these findings are tied to the date and flags above.
 
 ## Storage, credentials, and connectors
 
-`KVStorage` is `get`/`set`/`delete` with optional `list(prefix)`; core uses it for
-connector state, catalogs, and result paging — a 15-minute TTL with one
-runtime-wide accounting of stash bytes and entries, where a full stash returns the
-successful call's preview and a paging-unavailable notice rather than a result id.
-A second optional method, `compareAndSet(key, expected, next, options?)`, is an
-atomic claim: `null` means absent (expired counts) on the way in and delete on
-the way out. A successful write accepts the same optional `ttlSeconds` as
-`set`. Artifacts require it, because every write commits by swapping a head,
-and so does issuing access tokens; a read and a write standing in for the
-claim would let two writers both win. Downstream OAuth uses it where the store
-has it, so
-resealing legacy plaintext and discarding a refused grant cannot overwrite a
-consent that landed in between, and falls back to a read and a write where it
-does not.
-Adapters: `src/storage/memory.ts` and `src/storage/file.ts` (Node) both provide
-it, and the namespaced views core hands connectors forward it only when the
-underlying store has it. `examples/worker/` carries two more: Cloudflare KV,
-eventually consistent and so declaring none, and a D1 store that provides it —
-copyable reference source beside the D1 activity store, deliberately not an
-importable subpath. The shared cases live in `test/storage-contract.ts`.
+A deployment has one store. On Workers it is one D1 database
+(`d1Storage(env.CONNECTA_DB)` from `@zackbart/connecta/d1`); on Node it is one
+SQLite file (`sqliteStorage(path)` from `@zackbart/connecta/sqlite`, over the
+built-in `node:sqlite`). Both are the same SQL key-value store
+(`src/storage/sql.ts`) over a three-method driver, so every statement runs
+unchanged on each, and the same module carries the activity table beside it.
+Each store creates its tables on first use. `memoryStorage()` is the default
+and the test double. Workers KV and the 0.28 JSON file store are gone: KV is
+eventually consistent and cannot compare-and-set, and the file store rewrote
+its whole file on every write. Each has a one-shot copy into its replacement,
+`copyKvToD1` on `/d1` and `connecta migrate-state` on Node. Both copy live
+entries verbatim, because physical keys did not change, and both keep any key
+the target already holds. `copyKvToD1` reports counts per key family
+(`familyOfKey` in `src/storage/keys.ts`), never a key. It resumes through a
+source-bound, atomically claimed token, because Workers KV's own list cursor
+can spell a key. Copy under maintenance after KV stabilizes, verify hashes
+and expiries, and mark cutover before reopening traffic; the permanent D1
+marker refuses stale copies afterward.
+
+`KVStorage` is `get`/`set`/`delete`/`list(prefix)`/`compareAndSet`, all
+required, and `createConnecta` refuses storage missing one (INV-11).
+Adapters must also declare `capabilities: { absoluteExpiry: true }`.
+Construction rejects missing or false capability declarations with an error
+naming `capabilities.absoluteExpiry`. The memory, SQLite, and D1 adapters carry
+this marker. Custom adapters may declare it only after implementing absolute
+expiry on both writes; a legacy `ttlSeconds`-only adapter is rejected by the
+published types and at runtime.
+`compareAndSet(key, expected, next, options?)` is an atomic claim: `null` means
+absent (expired counts) on the way in and delete on the way out, and a
+successful write takes the same expiry options as `set`. Relative `ttlSeconds`
+is created and checked by the database clock inside each statement, so isolate
+clock skew cannot expire a live holder's record. Absolute `expiresAtMs` is a
+safe-integer epoch-millisecond deadline stored verbatim and checked against the
+storage clock. Supply at most one option. Custom adapters must implement both;
+a delayed absolute-expiry write must not restart a relative TTL at commit time. Each SQL claim
+is one statement, which SQLite executes atomically and D1 serializes on its
+primary. Everything that must claim a key exactly once relies on it with no
+read-then-write fallback: access-token issuance and
+capacity, OAuth handoff ownership, single-use connect links, every downstream
+OAuth grant write and consent claim, and the result stash.
+
+Every key is built in `src/storage/keys.ts`, which lists each family with its
+scope, version, codec, and TTL policy; `test/storage-keys.node.test.ts` fails when
+two families overlap, another source file spells a prefix (constant concatenation
+folded), or a storage call passes a key holding literal text. Core hands
+subsystems namespaced views: `conn:<id>:` per connector, `principal:<key>:` per
+personal registry, `results:` and `subject:<key>:` for result paging.
+
+Keys and list prefixes must not contain U+0000 (NUL). D1, SQLite, and memory
+storage reject them with `TypeError` before accessing storage: Node 22's
+`node:sqlite` truncates TEXT results at NUL. Builders reject NUL in unencoded
+components.
+State-file import validates all keys before writing. The `connecta_kv` table
+keeps its existing TEXT keys, including compatibility with the 0.28 schema.
+Storage writes no log lines. A refused import names the file and an entry's
+position, never a key, a value, or the JSON parser's account, which quotes
+the file (INV-6). Database failures report only a fixed import step and an
+entry's position, including errors raised by target-database triggers.
+
+Remote MCP catalogs use the SDK `ResponseCacheStore` over this same SQL KV.
+The `response-cache:v1:` family binds connector id, a hash of its configured
+endpoint/auth/protocol settings and TTL policy, an invalidation generation,
+and a hash of the listing method and host-computed auth partition. Later pages
+can only narrow the aggregate TTL and sharing within that partition. Request
+tokens and personal OAuth or credential auth always use private entries,
+including when the downstream declares `public`. Private partitions bind the
+admitted principal, subject, identity, pool, endpoint, credential digest, and
+OAuth epoch. Operator-shared credentials and unauthenticated connectors may
+share public-hinted listings across principals within the same admitted pool
+and endpoint. Private hints retain principal isolation even with shared auth.
+The adapter refuses the SDK's empty shared slot for private auth modes. OAuth
+listings resolve the current credential digest even within one epoch; a
+credential change during a walk prevents publication under the old digest.
+Each remote connector instance owns its request's cache lifetime separately,
+so closing a temporary client does not end another instance with the same id.
+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.
+
+`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
+ceiling); an explicit zero is never reused. Both bounds are nonnegative finite
+seconds (fractions round down to milliseconds), with min <= max <= 86400. `persistCatalog` and `staleCatalogSeconds`
+have been removed. SQL storage is always used for remote catalogs; dynamic
+custom connectors are listed anew in each request; authenticated callers may
+retain a complete private fallback, and static catalogs remain
+in configuration. After a transient first-page tool listing failure, ordinary calls
+may use a complete catalog for up to five minutes after its expiry in the same
+auth partition. Partial walks, permission and auth failures do not use this
+fallback. Resources require unexpired inventories. There is no deferred refresh.
+Host-only provenance carries each catalog's original fetch time, TTL and expiry,
+and whether it was a fallback, through classification and request-local copies.
+Zero TTL and stale fallbacks cannot authorize post-entry auth recovery.
+
+A manifest is published by CAS only after every UTF-8 chunk is written. It
+records the original fetch time, absolute expiry, revision, fingerprint, and
+monotonic stamp. Readers verify all chunks and fingerprint before accepting it.
+Freshness expires at the bounded TTL; tool facts remain for the five-minute
+fallback window, and generations expire after 48 hours; invalidation
+rotates the generation, and old chunks expire without becoming reachable
+again. Remote clients pin that generation before listing, including SDK cache
+refreshes. Each new listing pins the current generation, so a live client can
+publish a new catalog after invalidation without letting an older listing
+adopt its generation. A public transport observer starts a generation rotation
+before the SDK processes tool or resource list-changed notifications; its lifetime is
+the connection's, including after a successful resource read or listing ends.
+Opposite-scope cleanup only deletes its entry. SDK listings serialize per client
+because the cache store has no per-call options. Their operation binding lasts
+through the SDK's cleanup, and each cache method captures that binding before
+awaiting. Cache I/O checks cancellation and scope teardown at every await
+boundary. Cancelled storage waits release the listing without starting more
+I/O when an already-dispatched storage operation settles. Teardown waits a
+bounded time for generation rotations already started. Catalog age remains the
+original fetch age across process restarts and cache hits.
+`test/catalog-cache.test.ts` runs against real SQLite and D1.
+
+`observeCompletedCatalogRefresh` in `src/catalog-cache.ts` is the accepted
+refresh publication hook. The SDK tools/list wrapper calls it once after a
+complete, unfenced wire refresh, including zero-TTL results. Custom dynamic
+connectors publish their complete intake through the same hook. Cache hits,
+rejected or abandoned walks, and identical catalogs emit no change event.
+`Registry.recordCatalogDrift` compares the previous and next tool fingerprints
+from this hook, preserving the requesting actor, request id, pool and deferred
+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
+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
+observations cannot be disclosed. Public-hinted shared-auth catalogs retain
+shared history within their admitted pool and endpoint.
+
+Result paging stores each oversized result for 15 minutes, chunked so a page
+reads only what it covers. Its bounds (`results.maxStashBytes`,
+`results.maxStashEntries`) are the deployment's, not an isolate's: every charge
+is a row in one ledger record, booked by compare-and-set before any chunk is
+written, so isolates and processes sharing the store see one count. Every
+reservation starts with a finite deadline of booking time plus the 30-second
+write budget plus the chunk TTL, normally 15 minutes. Pending writes retain
+that charge until its deadline. Booking retries recognize their own reservation
+ID and reuse its stored deadline, including a final read after an ambiguous
+last CAS. A lost swap or transient storage error backs off and re-reads, up to
+32 attempts. A full ledger or unconfirmed exhausted booking returns no result id.
+
+Caller time only nominates charges for pruning. Before discarding one, the
+ledger writes a probe with that charge's absolute deadline and reads it back.
+Only an absent probe proves storage has passed the deadline; a live probe keeps
+the charge, and a storage error cannot free capacity. Each deadline has its own
+key in `stashExpiryKeys`, so concurrent probes cannot overwrite a different
+deadline's proof. Probes expire at the deadline they check and need no cleanup.
+This uses the same absolute-expiry contract on memory, SQLite and D1 without a
+storage API or schema change. An ahead caller clock cannot admit a second stash
+while the first remains readable.
+
+The whole chunk-write phase has a 30-second timeout measured from booking, with
+a clock check before and after each write. Trailing chunks precede the header;
+failure or timeout returns no result id and stops the write loop. Chunks use an
+absolute expiry at booking time plus their TTL, so slow writes shorten the
+remaining paging window. Storage promises cannot guarantee cancellation of an
+already-dispatched database operation, and a rejected client response does not
+prove that operation cannot commit later. Even a commit after timeout or process
+interruption keeps that absolute expiry, rather than starting another TTL.
+
+Settlement and release only shorten or remove a reservation. Successful writes
+attempt to shorten the charge to the fixed chunk expiry. Cleanup releases it
+only after all deletions succeed and every dispatched write returned confirmed
+success. Failed cleanup or exhausted release attempts finite settlement when
+no write is unconfirmed. A rejected or timed-out write keeps its original
+reservation because it may still commit after deletion. Each completion path
+has one 15-second budget covering deletion, release, fallback settlement, and
+their storage waits and retries. Successful-write settlement has the same
+15-second budget. A stalled operation stops being awaited when the budget
+expires; its late response starts no further I/O, and no background cleanup
+fiber is started. The caller returns its write outcome even if these
+optimizations cannot finish. Ledger updates retry within the same 32-attempt
+budget. If they fail, time out, crash, or exhaust,
+capacity may be over-held until the booked deadline, at most 15 minutes and
+30 seconds for the normal TTL. The ledger row itself has an absolute expiry at
+its latest live reservation deadline. There are no completion receipts or
+separate recovery rows; expiry probes carry no completion state. Expired data reads as absent and normal storage sweeps
+reclaim the physical rows. A full stash returns the successful call's preview
+and a paging-unavailable notice rather than a result id. Shared failure cases
+live in `test/stash-charge-contract.ts`, exercised by the memory and SQL suites.
 
 `src/credentials.ts` is the AES-GCM vault behind the root-exported
 `CredentialVault` contract, selected through the `vault` slot. It binds connector
@@ -255,23 +535,259 @@ produce instances that take the same catalog, read-only, credential, storage,
 invocation, result-size, and activity paths. Every one is deployment
 configuration, never runtime registration. `authScope: "shared" | "personal"`
 partitions connecta-owned context — state, credentials, OAuth, catalogs, observed
-shapes — by principal, and *only* connecta-owned context: a secret a custom
+shapes — by principal, and _only_ connecta-owned context: a secret a custom
 handler closes over is shared JavaScript state, and `remoteMcp()` refuses the
 literal-headers-plus-personal version of that mistake. Visibility
 (`identity.connectorAccess`) is a separate rule; hiding a connector does not
 change who owns its auth.
 
+### Errors and records
+
+A failure has two audiences with two rules. The agent that made a call may read
+the downstream's own answer to it: a JSON-RPC error message, an HTTP 4xx
+refusal, `isError` content, or the words a handler put in a
+`ConnectorCallError`. Each upstream request owns a memory-only sent-secrets
+set. Every connector context links its local set into that request, including
+listing, discovery, registry refresh, OAuth refresh, and provider handlers.
+Direct meta-tool invocations and program runs get fresh request identities;
+all operations within one HTTP request share its identity. Credential-slot reads, static
+auth headers, raw confidential OAuth client IDs and secrets, and outbound
+bearer tokens join the set, including tokens rotated during a call. Token and
+revocation requests register client credentials before dispatch, decoding OAuth
+Basic form components so a raw echo is covered too. Public client IDs remain
+visible. Before any diagnostic is truncated or returned, the
+agent boundary replaces these values and their auth prefixes, mixed JSON
+escapes, URL encodings, and base64/base64url forms with `[redacted]`. Final
+transports register sensitive headers and query values after assembling the
+request; custom API handlers use `ctx.fetch`. Values shorter than eight
+characters do not enter the matcher, including Basic usernames, passwords
+and explicitly secret fields such as `client_secret`. Configured short
+credentials produce one payload-free warning per connector; use secrets of
+at least eight characters. Encoded and JSON-escaped echoes of registered
+credentials follow the same redaction rules. Connecta's own messages
+never quote a credential.
+Core uncertainty and retry envelopes share one schema-filtered argument snapshot,
+captured before dispatch and byte budgeting. `writeOnly: true` omits values of
+every length, including nested properties, array items and prefixes, local
+`$ref`/`$defs`, and `allOf`. `oneOf`/`anyOf` must agree on sensitivity. Unresolved
+references, sensitive dynamic-property schemas or other unsupported applicators,
+and traversal limits withhold the entire echo. A private array element withholds
+its containing array to preserve indices. `argsRedacted: true` marks a partial
+or withheld echo as reconciliation context; retries require the original arguments.
+OAuth discovery and consent URLs are refused as a typed, non-retryable failure
+when they contain a known credential, before persistence or reuse. This guard
+checks the request's sent credentials and the current grant's credentials,
+including confidential client secrets. The consent URL's expected `client_id`
+parameter remains public, while echoes elsewhere are refused. URLs are never
+rewritten. OAuth failure
+origins are recorded only for the configured MCP or issuer origin, or the
+origin of discovery metadata whose issuer matches its authorization server.
+An origin matching a sent credential is omitted.
+The matcher is cached until its set changes; the empty set has a fast path.
+`redactAgentOutput` is the agent-facing choke point. Every meta-tool exit,
+including errors, and every host-to-guest value or rejection passes through
+it. Both MCP transports also pass their serialized response through it, covering
+JSON-RPC errors, HTTP diagnostics, structured content, and paging responses.
+Per-call redaction remains before diagnostic truncation, paging, and emits. Paging stores only request-redacted text before encoding
+chunks, so a later request needs no original credentials. Programs retain the
+request set only for the run so later outputs cannot reconstruct an echo.
+Discovery registers sent credentials under the same rules, including
+`server/discover`, legacy initialization, and every `tools/list` page on a
+reused transport. Remote MCP sanitizes every list page before SDK aggregation, automatic cache
+writes, derived indexes, or request-local definitions. Invalid `x-mcp-header`
+declarations refuse the entire listing before the SDK can log downstream names
+or silently exclude a tool. Registry intake also sanitizes custom, API and
+provider listings before observation or request-local storage. Failed listings
+are redacted in their own request and are never cached. Successful catalog caches and result
+stashes retain only intake-redacted values; there is no tool-response cache.
+Every nested string and object key passes through the redactor,
+including titles, descriptions, schemas and annotations. If a tool name would
+change, the complete catalog is refused. Rewriting a name changes dispatch;
+dropping only that tool would publish a partial catalog, against INV-8. Later
+cached reads need no credential set because the stored facts are already clean.
+Echoed sensitive header lines are also withheld. The set is never persisted
+or logged. Anything else (a transport, parser, stream, validator, or
+runtime error) reaches it in connecta's words: step, origin, HTTP status, and
+class, classified as the original would have been ([auth](./auth.md#what-a-servers-errors-may-say)).
+Operators read logs, status messages, and activity, and none of them carries
+any error's text, allowed or not (INV-6). `src/operator-record.ts` builds every
+failure record from an explicit list of fields, each checked against a constant
+table or grammar (connector, catalog-listed tool, step, origin, HTTP status,
+class, code, retryability, errno, counts), and `logFailure` writes a fixed
+`<rejected>` for a record it did not build, never throwing. Provenance is by
+identity, never by shape: an error's class is read from its prototype chain,
+never its `name`; a classification only from one connecta registered; a tool
+only from the catalog entry a call resolved to, and only if it fits MCP's
+tool-name grammar (else `<withheld>`, in activity rows too); and a status
+message only from the snapshot connecta took of a status it created, so a
+plugin `status()` or a decorator contributes its state alone. workerd quotes a
+body's Content-Type in its own output when a text read meets a type it does not
+parse as text, so connecta reads downstream bodies as bytes
+(`src/byte-read-response.ts`), `ctx.oauth.fetch()` answers included. The
+operator page may show catalog metadata the operator loaded (descriptions,
+schemas), but withholds a tool name outside the grammar as it does in records.
+`test/operator-record-sources.node.test.ts` is a secondary lint over every other
+log call in `src/`. Fix the sink, not the source: a filter at each source missed
+the next one.
+
+## Configuration
+
+`ConnectaConfig` is one schema (`src/config.ts`, combinators in
+`src/config-schema.ts`). The same value produces the TypeScript type a
+deployment writes, the unknown-key walk createConnecta runs before reading any
+value, every default (`src/config-defaults.ts`, which the enforcing modules
+read too), and one validation policy: a present value that is wrong throws
+with its path at construction (INV-11). Nothing warns and falls back. The walk
+reads property descriptors, never properties, and builds the plain copy that
+is resolved in place of the caller's object, so no getter or Proxy trap runs;
+an accessor on a config object or array is refused by path, as is an object
+that cannot be inspected. A closed object or record slot takes a plain object
+only: an array or a class instance there is refused by path, unread. String
+maps (static `headers`, `api()`'s `authorizationParams` and
+`tokenRequestHeaders`) are copied the same way and each value must be a
+string. A discriminated union (`remoteMcp()`'s `auth.type`,
+a provider's `surface`) with a missing or unrecognized discriminant throws
+with the valid values. Only plain data is copied. Connectors, modules,
+executors, storage, loggers, handlers, and schemas are opaque and never
+entered. An `api()` tool carries its handler, so it is checked in place (own
+keys declared, no accessor at a declared key, inherited ones included) and
+passed through as given: a class-instance tool keeps its prototype `handler()`
+and its private fields. Configuration is operator-authored and trusted, as in
+#698; the walk refuses mistakes by path and never echoes a value, and is not
+a sandbox for hostile objects. Records keyed by deployment
+names (pools, `classification`) have no prototype, so `__proto__` is a name.
+Built-in factories (`api()`, `remoteMcp()`, every provider, and each module
+factory) walk their own options the same way, against shapes the compiler
+checks against their option types (`optionsOf<T>()`). Provider definitions
+declare their closed `options` shape; `defineProvider()` validates it by the
+same descriptor walk before `create` reads a value and stamps the definition
+name onto `describe().source.provider`. `classify` is accepted by the remote
+shape and validated by the shared reviewed-classification validator. Custom
+connectors remain opaque, including their `classification` field, which the
+registry validates. Checks
+that need the connector set — pool members, exact classification overrides, a
+connector's own `maxResultBytes` — throw from `src/index.ts` and the registry
+under the same policy. `storage` stays opaque, but its check requires `list`
+and `compareAndSet` as well as `get`, `set`, and `delete`, so a leftover
+Workers KV adapter is refused at boot with the replacements named, not at the
+first OAuth callback.
+
+`resolveConfig` returns a frozen `ResolvedConfig`: defaults applied, auth
+ordered, `serverInfo` named and versioned.
+Routes and meta-tools read limits from it (`ServerOptions.config`) instead of
+from fields copied out one at a time. `Connecta.describeConfig()` is a
+secret-free snapshot of it, built once (`src/describe-config.ts`): an allowlist
+serializer that copies named fields and never spreads a config object, plus
+`Connector.describe()` on `remoteMcp()`, `api()`, and the providers. Header values, keys, client secrets, credentials, URL
+userinfo, queries, and fragments, and function bodies never appear; every URL
+a description emits, from `describeConfig()` or a direct `describe()`, passes
+through the sanitizers in `src/described.ts`, which keep http(s) URLs only
+(`blob:` wraps a URL with its userinfo in the path);
+`test/describe-config.test.ts` plants one in each position. Both deployment
+shapes write their configuration as `defineConfig((env) => …)` in
+`src/connecta.config.ts`, with optional modules as type-checked expressions
+switched by the environment, and keep their entries under 30 lines.
+
+### Providers and reviewed classification
+
+Infisical separates explicit value reads from identifier results. `get_secret`
+and `list_secrets` with `includeValues: true` return secret values and comments.
+All other results, including imported secrets and pending approvals, allow only
+checked IDs, keys, environment and tag slugs, paths, timestamps, positive versions
+and enum fields. They omit project slugs derived from free-text names, comments,
+descriptions, free-form names, reminder notes and arbitrary nested objects.
+`metadataOmitted: true` reports withheld or unavailable metadata.
+This assumes an honest server and protects against careless human entry in free
+text. A malicious server encoding values into valid identifiers is out of scope.
+Known, accepted residual risk: environment slugs are returned as required
+routing identifiers. Infisical's UI derives them from environment names by
+default, so secrets entered in those names can appear in returned slugs.
+Operators must not put secrets in environment names or slugs. Secrets placed in
+identifiers or key names are out of scope.
+Write input schemas mark secret values, secret comments and folder descriptions
+as `writeOnly`, so recovery argument echoes omit them without changing dispatch.
+Submitted values never join the request's sent-credential set, preserving later
+program arguments. Client credentials and tokens still join that set on every
+call. The [provider guide](https://github.com/zackbart/connecta/blob/main/src/providers/infisical/SKILL.md) owns routing and
+value-read conventions.
+
+A maintained provider is one `defineProvider()` call (`src/provider.ts`): a
+name, title, kind (`"mcp"`, `"api"`, or `"composed"`), a maintained skill, an
+optional reviewed classification, a closed `options` shape declared with
+`optionsOf<O>()`, and a synchronous `create`. The root exports the option-shape
+combinators and `PROVIDER_COMMON` so provider authors use the same validation
+path. The factory refuses undeclared keys and accessors before reading any
+option, copies plain data, preserves behaviour objects, then validates common
+values (purpose, title, instructions, `authScope`) before `create` runs, and renders the guide: heading, the
+connection context `create` supplies, the maintained text, then deployment
+instructions, which append and never replace. `src/provider.ts` imports neither
+transport, so an `api()` provider gains no MCP client or Effect graph from it
+(`test/purity.node.test.ts`). The factory carries its `definition`, which build and
+check tools read instead of keeping provider lists. All twenty providers
+live in their own folders. The eight hosted implementations, including the
+MCP branches of Notion, Vercel, and Cloudflare, use reviewed presets over
+`remoteMcp({ classify })`. The eleven API-only factories retain an internal
+adapter to the same definition and description-stamping path. GitHub composes hosted tools with a scope-enforced REST complement.
+Notion, Vercel and Cloudflare default to hosted MCP and select explicit REST
+complements with `surface: "api"`. Configure both under distinct connector ids
+with independent credentials when both are needed. Notion preserves its
+internal-integration identity under `integration_*` names; Vercel and Cloudflare
+retain documented REST gaps rather than duplicate hosted operations. See the
+[provider migration guide](./provider-migration-0.29.md).
+
+`remoteMcp({ classify })` is the public way to declare what a downstream's
+tools do: `{ tools: { name: "read" | "write" | "destructive" | { verdict,
+reason?, schemaDigest? } }, unlisted?: "hide" }`, validated at construction. It fails closed
+(INV-1): a reviewed read fills silence but yields to an explicit write
+annotation, a reviewed write stays a write whatever the downstream claims, an
+unlisted tool is a read only when it says so, and a reviewed tool whose
+`schemaDigest` no longer matches, or cannot be checked, is a write on discovery
+and every invocation path until a release reviews it again. A digest covers
+the whole schema; one too large to hash whole is unchecked. `unlisted: "hide"`
+removes every unreviewed name, even an explicitly annotated read, on every
+registry read, including persisted catalogs. `remoteMcp` also refuses direct
+calls to unlisted names before authentication. Tool classification does not
+authorize targets; providers such as GitHub check arguments and configured
+scopes separately before minting credentials.
+
+Connectors report facts; the registry is the only classifier. A reviewed
+connector carries its review as data, the deep-frozen
+`Connector.classification`, and its `listTools` returns the downstream's
+listing unclassified. The registry validates the field when it first reads a
+connector (INV-11) and classifies the intake-redacted facts on every read into
+fresh objects. Remote MCP caches the underlying SDK response before connector
+decorators; decorators run again on every read. Neither a cache layer nor a
+decorator holding a served or listed tool can carry a verdict. The request-scoped catalog also owns a deep copy
+and returns fresh copies to discovery and invocation. Each connector call
+receives a separate deep copy of its definition, so mutations cannot change
+classification, schemas, or write accounting later in the same program.
+A restart applies the current review to cached SDK facts. Retired registry
+manifest versions 2 and 3 are ignored and expire on their original TTL.
+During successful listings the registry counts drift against the same record, and `scripts/drift-check.mjs` compares
+its names with published inventories. The internal `withVettedCatalog()`
+helper has been removed. Public provider `*_VETTED_CATALOG` exports remain
+deprecated aliases derived from each definition
+(`test/classified-decorators.test.ts`, `test/hosted-presets.test.ts`).
+
+Wrappers must forward `classification` to keep the review. `{ ...connector }`,
+`Object.assign`, and `Object.create` keep it. A forwarding class that omits it
+serves an unreviewed connector: the downstream's annotations are its own
+claims and fail closed when absent, and nothing it persists carries safety.
+Phase 2's deployment-level classifier overrides, keyed by connector id and
+tool ([#706](https://github.com/zackbart/connecta/issues/706)), apply
+regardless of wrapping.
+
 ## Optional deployment modules
 
-`createConnecta` takes closed typed `ui`, `vault`, `activity`, and `artifacts`
-slots, with factories at `/ui`, `/credentials`, `/activity`, and `/artifacts`
-and bearer auth at `/auth/bearer`. Root exports the contracts, never the implementations, and there
+`createConnecta` takes closed typed `ui`, `vault`, and `activity`
+slots, with factories at `/ui`, `/credentials`, and `/activity`
+and machine tokens at `/auth/access-tokens`. Root exports the contracts, never the implementations, and there
 is no module array, runtime registration, or plugin lifecycle. Core keeps
 discovery, the executor contract, invocation, permissions, and OAuth callback
 verification; an omitted module contributes no runtime work at all.
 
 The operator UI — `src/ui.ts` (data-free shell and `/ui/data` payload),
-`src/routes/ui.ts`, `src/operator-ui/` (the Preact app and its pure rules) —
+`src/routes/ui.ts`, `src/operator-ui/` (the React app, owned Radix primitives and its pure rules) —
 shows a human what a deployment exposes and manages only the authentication
 material code explicitly permitted; it never edits the connector set, catalog,
 annotations, scopes, or permission rules. Two invariants shape it: a status read
@@ -280,16 +796,16 @@ and each lazy details request owns a bounded downstream scope, so one failing
 provider leaves the other connections usable. A connector's status message
 never reaches the page: it can quote a downstream error body, and that body can
 quote the secret it rejected, so the details payload carries only a classified
-`problem` — which picks fixed on-screen copy and a fixed fix prompt — and the raw
-text goes to the server log. The OAuth and credential Test notices keep the
-same rule: those routes answer a downstream's failure in fixed words (a Test
-answers only `{ ok }`), log its text, and the page picks a sentence by outcome
-without ever rendering what the server sent. Credential handoff URLs exist only while the UI is
+`problem`, which picks fixed on-screen copy and a fixed fix prompt. Server
+logs contain only checked failure records, with no raw text. OAuth and
+credential Test notices keep the same rule: those routes answer failures in
+fixed words (a Test answers only `{ ok }`), log checked facts, and let the page
+pick a sentence by outcome. Credential handoff URLs exist only while the UI is
 mounted; OAuth callbacks never need it.
 
 Its appearance is one token layer, and it is not the UI's alone: every page
 connecta shows a person — the operator shell, the OAuth callback, a browser's
-404, the artifact frame and Markdown pages — reads it. `src/operator-ui/tokens.css`
+404 — reads it. `src/operator-ui/tokens.css`
 resolves every color, radius, and font through a custom property and mixes the
 rest from those with `color-mix`; `page.css` holds the base typography and the
 primitives (shell, masthead, buttons, badges, messages, the one-message status
@@ -303,111 +819,49 @@ block after the stylesheet. The five tokens it accepts are gated in
 `src/branding.ts`, each by a narrow syntactic check: deployment config reaches a
 `<style>` element here, and an unvalidated value would be CSS injection. The
 dark palette is the same tokens under `prefers-color-scheme`; `colorScheme` pins
-one with a `data-scheme` attribute on the page, and the artifact viewer passes
-the same attribute into a Markdown page, never into authored HTML.
-
-The artifacts module — `artifacts()` from `/artifacts`, implemented in
-`src/artifacts/` — is the one module that contributes a connector. Core
-appends its prebuilt `artifacts` connector to the configured set, so its reads
-and writes take the same catalog, invocation, admission, and activity paths as
-any other connector; the slot binds its optional refresh runner once, after the
-registry and executor exist, and a deployment
-without it has no connector, no guide, and no artifact storage traffic. Its
-writes are not read-only anywhere — `call_tool` refuses them and discovery
-lists them approval-required — but they skip approval inside programs through
-the connector's own `approval: "never"`, which `execute.approval` switches off,
-because every write is a new immutable version anyone can roll back. The
-module needs `publicUrl`: the links it hands out are shared, so they must never
-come from a request's `Host`.
-
-An artifact can version an `execute_code` program and target data document with
-`set_refresh`, on a manual, daily, or weekly schedule. The deployment calls
-`artifacts.runDue()` from a Node timer or Worker `scheduled()` handler; core
-starts no background jobs. One tick scans at most 1,000 heads and starts at
-most 10 due runs. Every run uses the configured executor, host-call budget,
-and watchdog, with a registry view containing only shared connectors. The
-owner admitted to `set_refresh` is stored with the program. Every run rechecks
-that identity's current `connectorAccess` and pool grant, including continued
-access to `artifacts.set_refresh`, then intersects those grants with shared
-connectors. Revoking either grant stops later runs.
-Approval exemptions are off, so a refresh writes nothing. A refused call fails the
-entire refresh even if its program catches the error. The head CAS claims one
-run per artifact; the data commit checks the claim ID and program version in
-the same CAS. The claim deadline starts before executor admission and aborts
-a queued or active play when it expires. An expired old run cannot publish over
-a newer claim. Run history retains 50 records with bounded logs. A failure leaves the
-last good data intact and marks the artifact stale. Library and viewer show
-only outcome enums and times, never downstream messages or logs.
-
-With the operator UI mounted, `/artifacts` lists the team pages and
-`/artifacts/<id>` opens one. The shell contains no page data. It reads the
-artifact through an authenticated JSON route with the operator UI's inbound
-identity and connector visibility, then passes the document into a sandboxed
-frame. Snapshot links pin the view and document versions. The frame's response
-CSP gives scripts an opaque origin, refuses fetch, XHR, images and other
-unlisted requests. External script, style, and font origins default to none;
-a deployment opts in to each one it trusts with page data. The shell tightens
-its own `frame-src` to `'none'` after the fixed bootstrap loads and before it
-hands over the page,
-so a page script cannot navigate even its own frame to send data in a URL.
-This browser boundary is covered by Chromium tests, including a
-`document.open/write` rewrite.
-
-`artifactOrigin` optionally names a distinct HTTPS origin for these pages.
-The main host redirects every `/artifacts` path to it; the artifact host
-answers every other path, including `/mcp` and operator APIs, with 404. The
-artifact shell still uses the same inbound auth providers and checks the
-identity on each data read. The bare shell and fixed frame bootstrap carry no
-artifact data, so a visitor can reach sign-in before an authenticated read.
-Bearer tokens in browser localStorage belong to one origin: signing in on the
-main host does not sign in on the artifact host. A redirected visitor enters
-the token again there; the redirect carries no credential. Cookie or session
-auth likewise depends on the provider admitting that separate origin.
-
-Storage is an `ArtifactStore`, and `kvArtifactStore` is the reference: over any
-`KVStorage` with `compareAndSet` and `list`, one head record per artifact is
-the only key ever compared-and-set, earlier versions sit beside it immutable,
-and bodies are content-addressed — in the key-value store, or in R2 through the
-Worker example's `r2-artifact-blobs.ts`. Workers KV is refused at construction,
-because a write that cannot swap its head can lose a teammate's edit. Every
-rule lives once, in `src/artifacts/operations.ts`: a write checks its base
-against the one stream it touches, so of two writes from the same base exactly
-one wins and the other is a `conflict` carrying a bounded `current` map, while
-a head that moved for an unrelated reason is re-read and retried rather than
-reported. Patches match exactly once or change nothing, rollback is a new
-version reusing an old body, and the limits are checked on every write.
-Validation is a hand-written tokenizer and CommonMark subset rather than a
-dependency, because it is a lint: the page's CSP is the boundary.
-
-Who made a version is the one fact a built-in connector needs that
-`ConnectorContext` deliberately does not carry. `src/connector-caller.ts`
-attaches the admitted identity beside the context on the request's scoped
-view, the way the OAuth sealer rides beside it — readable only by in-repo
-code, set from the authorization and never from arguments
-(`test/identity-scope.test.ts`, `test/artifacts-connector.test.ts`).
+one with a `data-scheme` attribute on the page.
+
+Maintained providers act as the caller downstream. `src/connector-caller.ts`
+attaches the admitted identity beside the request-scoped context, readable only
+by in-repo code and set from authorization, never arguments. Google Workspace
+domain-wide delegation
+(`src/providers/google/`, first consumed by `./providers/gmail`) hands the
+admitted identity to a deployment-config `subject` function and mints a
+service-account token as whatever Workspace address it returns. The caller
+carries whether an inbound provider _authenticated_ it: an open deployment
+admits everyone as the anonymous actor, and the function is never asked about
+them. No caller, an unauthenticated one, or no address fails `auth_required`
+before any request leaves. The provider never chooses the account and a
+deployment's own connector still cannot read the caller (PRINCIPLES.md, INV-3; `test/google-workspace-delegation.test.ts`). Its tokens live in a
+bounded module-level map, in memory only, keyed by the key's own digest as well
+as the account, subject, and scopes. A mint in flight is shared across requests
+the way OAuth flights are: the owner settles a plain outcome
+inside its own request — a token, Google's refusal, or `abandoned` — and each
+follower waits on a promise of its own under its own signal and timer to the
+flight's deadline, never touching the owner's signal or response.
 
 ## Import-graph purity
 
 Nothing reachable from `src/index.ts` may import a `node:` builtin, so the same
 core runs unchanged in workerd and in Node. The Node-touching paths — `src/node.ts`
-(the `node:http` adapter), `src/storage/file.ts`, and the QuickJS process pool
+(the `node:http` adapter), `src/sqlite.ts` (`node:sqlite`), and the QuickJS process pool
 (`src/executors/quickjs.ts` plus its child) — each sit behind an explicit subpath
 and must stay unreachable from the root. `./auth/clerk` is separate because
 `@clerk/backend` is an optional peer rather than a dependency, and
 `./auth/cloudflare-access` for a third reason: it is Web-API-pure, but its trust
 contract is specific to a direct Worker invocation carrying `ctx.access`.
 
-`test/purity.test.ts` walks the relative-import graph and fails on any `node:`
+`test/purity.node.test.ts` walks the relative-import graph and fails on any `node:`
 specifier in a reachable file, or on any of those modules — plus the UI bundle,
 encrypted vault, and activity implementation — being reachable at all;
-`test/package-surface.test.ts` and `scripts/check-package.mjs` guard the same
+`test/package-surface.node.test.ts` and `scripts/check-package.mjs` guard the same
 boundary in the published tarball. The failure mode is not theoretical: one
 convenience import of `node:crypto` in a shared helper stops the whole Worker
 shape from building, in someone else's repository rather than this one.
 
 ## Effect inside
 
-The core runs on stable Effect v4, exact-pinned to `4.0.0`; no API a deployment
+The core runs on stable Effect v4 through a compatible `^4.0.0` range; no API a deployment
 touches does. `createConnecta`,
 `remoteMcp()`, `api()`, the `Connector` contract, and every shipped `.d.ts`
 are Promise-shaped and name no Effect type, so a connector author never meets a
@@ -441,7 +895,7 @@ and `npm run check:declarations` fails if what remains names an Effect type.
 ### One runner
 
 `src/runtime/run.ts` is the only place a fiber starts, and
-`test/purity.test.ts` fails if any other file calls `Effect.run*`, `runFork`,
+`test/purity.node.test.ts` fails if any other file calls `Effect.run*`, `runFork`,
 `forkDaemon`, or `ManagedRuntime.make`. It exports two ways out:
 
 - **`runEdge(effect, { signal, runtime? })`** runs an effect at a Promise
@@ -456,39 +910,35 @@ and `npm run check:declarations` fails if what remains names an Effect type.
   to `ctx.waitUntil` when there is one.
 
 Beside them sit `withDeadlineEffect`, which aborts the operation's own signal
-with the labelled timeout error *before* interrupting it, so work that honors
+with the labelled timeout error _before_ interrupting it, so work that honors
 the signal sees the same reason the caller does, and `fromSignal`, which turns
 an `AbortSignal` into a failure to race against. Nothing runs Effect at module
 scope, where a Worker may not start work, and nothing logs through
 `Effect.log`: logging goes through the configured `Logger`, which is what
 honors `logger: "silent"`.
 
-Each Connecta also gets a runtime of its own (`src/runtime/services.ts`):
-`Storage`, `Vault`, `ActivityRecorder` (one that records nothing when the module
-is omitted), `Logger`, and `ResolvedConfig`. Creating it builds nothing, since
-a Worker constructs its Connecta at global scope; the first run that needs the
-services builds them, and `close()` disposes the runtime last. Two things
-deliberately do not run on it. The request pipeline runs on no runtime, so
-`/health` and a closed deployment's 503 keep answering after `close()`. And a
-registry provides its own storage and logger to its programs
+There is no per-Connecta runtime. createConnecta resolves its configuration
+into plain values once (`src/config.ts`), and nothing needs a service context
+built from them. The request pipeline runs on no runtime, so `/health` and a
+closed deployment's 503 keep answering after `close()`. A registry provides its
+own `Storage` and `Logger` services (`src/runtime/services.ts`) to its programs
 (`runOnPartition` in `src/runtime/storage.ts`), because a personal registry's
-storage is the root's namespaced to its principal and the runtime's `Storage`
-would be another partition's.
+storage is the root's namespaced to its principal.
 
 ### What runs on Effect
 
-| Area | Shape |
-| --- | --- |
+| Area                                                                   | Shape                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Requests (`src/server.ts`, `src/routes/mcp.ts`, `src/routes/oauth.ts`) | One fiber per `fetch`, tied to `request.signal`. An `/mcp` request's admission permit and every `McpServer` it builds live in a Scope the response carries out, closed when the body ends, fails, or is cancelled, when the signal aborts, when its admitted-request lifetime ends in that request, or at once if the handler fails first. If workerd runs none of those callbacks, the next request reclaims only the expired admission record; it cannot close another request's Scope. The OAuth callback is uninterruptible: a single-use code's exchange and catalog invalidation are one commitment. |
-| 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. The executor's `acquire()` and `execute()` stay Promises raced against the signal and `execute.watchdogMs`. 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. |
-| Registry (`registry.ts`) | Catalog persistence and the result stash are programs over `Storage`. A refresh flight is a Deferred its publishing request completes, bounded by its owner's deadline (the default probe timeout when it has none); persisted-catalog writes take per-connector turns, each a Deferred its own request completes. Same-request loads share one read the way discovery's do. |
-| 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`) | A refresh flight is a Deferred; the owner's redemption is a fiber its abort interrupts, and committing an answer that already exists is uninterruptible. |
-| 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`. |
+| 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. The executor's `acquire()` and `execute()` stay Promises raced against the signal and `execute.watchdogMs`. 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.                                                                                                                                                                                    |
+| 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`)                          | A refresh flight is a Deferred. Preparation follows caller cancellation; after dispatch, the HTTP exchange owns a 20-second deadline and the grant commit continues through the runtime deferred-work hook.                                                                                                                                                                                                                                                                                                                                                                                                |
+| 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`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 
 ### What stays plain
 
@@ -505,7 +955,7 @@ would be another partition's.
   wrapping them would buy nothing and could starve a request.
 - **The MCP edges.** `@modelcontextprotocol/server` upward and the SDK client
   downstream; Effect's own `McpServer` is not used.
-- **The Node and browser leaves.** `node.ts`, `fileStorage`, the QuickJS
+- **The Node and browser leaves.** `node.ts`, `sqlite.ts`, the QuickJS
   child, runtime, and protocol, and the operator UI's browser app.
 
 ### Across requests
@@ -541,19 +991,16 @@ when its only pending work is waiting on another request and it has no timer or
 I/O of its own. Connecta's deadline timers are what keep a waiting request
 alive and bounded, so no wait may lose its timer.
 
-**A shared flight has a lifetime of its own.** A catalog refresh flight runs in
-its owner's request, under its owner's scope and signal, and lives only as long
-as its owner's deadline. Past that the owner may have answered and gone, taking
-its I/O with it on workerd, and a connector that ignores its abort signal would
-otherwise hold every later reader on a flight nothing will ever settle. So each
-joiner waits on its own timer, set to the flight's bound: when it fires, the
-joiner abandons the flight and makes a fresh attempt, and a reader that arrives
-after the bound starts one without joining. Joiners also leave when the owner
-fails for a reason that was only its own, such as its cancellation, rather than
-inheriting it. A flight's result enters the caches only while the flight is
-current, checked at the same points as the catalog generation, so a stuck
-listing that lands late is never cached or persisted and never overwrites the
-fresh attempt's.
+**Catalog I/O belongs to its request.** Listings share work only within one
+request and authorization partition. Independent requests may read the same
+complete SQL cache entry, but never await another request's listing, retain
+its client, or inherit its sent-secret set. A rotated cache generation makes
+late publication from an invalidated request unreachable. Missing chunks,
+expired entries, storage errors, or a failed page trigger a fresh complete
+listing. A transient first-page tool-listing failure may use a complete catalog
+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.
 
 ### Why not Schema or HttpApi
 
@@ -563,16 +1010,18 @@ of Worker cold start for it, and that cost was accepted over deep imports at
 every call site. The catch is that a module the barrel reaches is paid for in
 full, however little of it is used. Effect Schema for config validation and the
 meta-tool inputs came to about +62 KB gzip and +13 ms of cold start in the
-root, for a validator no clearer than the hand-written `CONFIG_SCHEMA`; the
+root, for a validator no clearer than the hand-written schema in `src/config.ts`; the
 meta-tool inputs stay zod, which the MCP SDK bundles regardless. `HttpApi` for
 the operator and activity routes cost about +100 KB gzip on `./ui` and +130 KB
 on `./activity`, and matching the wire format meant opting out of most of what
 it does: unowned paths fall through rather than 404, a wrong method is a JSON
 405, and the content-type and size checks run before a body is read. The root
-entry may import only `effect` itself (`test/purity.test.ts`). Effect v4's
+entry may import only `effect` itself (`test/purity.node.test.ts`). Effect v4's
 area imports, such as `effect/http-api` and `effect/ai`, would have to stay
 behind a subpath. APIs tagged `@stability unstable` can still change in minor
-releases, so stable v4 keeps the exact pin.
+releases, which is why the root may import only `effect` itself: that is what
+makes a caret range safe, and it lets a deployment that also uses Effect
+resolve a single copy. Adopting an unstable subpath is its own pull request.
 
 The stable `4.0.0` release was re-evaluated on 2026-10-01 with
 [`scripts/probes/effect-v4-evaluation.mjs`](https://github.com/zackbart/connecta/blob/main/scripts/probes/effect-v4-evaluation.mjs).
@@ -627,32 +1076,48 @@ src/
   server.ts           route ordering, HTTPS upgrade, security wrapper
   routes/             one file per surface; shared.ts holds the auth gate
   skills.ts           MCP instructions, the usage skill, connector guides
-  catalog-drift.ts    vetted manifests and the counts a refresh produces
+  catalog-drift.ts    reviewed classifications and the drift counts a refresh produces
+  provider.ts         defineProvider(): the one maintained-provider shape
   activity.ts         optional history factory and best-effort recorder
   auth/               bearer, Cloudflare Access, clerk (optional peer), downstream OAuth (remote and static)
   executors/          the QuickJS pool and child (Node only)
-  node.ts             listen() + fileStorage re-export (Node only)
+  node.ts             listen() (Node only)
+  d1.ts, sqlite.ts    the two storage drivers; storage/ holds the SQL core and key families
 ```
 
 There are exactly two deployment shapes — `templates/node/`, which
 `connecta init` copies with its container files, and `examples/worker/` — and
-`test/deployment-shapes.test.ts` with `npm run check:examples` keeps both
+`test/deployment-shapes.node.test.ts` with `npm run check:examples` keeps both
 compiling and configuring the real thing.
 
 ## Sharp edges
 
-- **The root registry is shared; identity views are partitioned.** Shared
-  connector caches are visible to later requests in the isolate; personal
-  connectors use a bounded principal registry and transient results the
-  authenticated subject. Putting a downstream client or credential on the wrong
+- **The root registry is shared; identity views are partitioned.** Public remote catalogs are shared only after intake redaction, keyed by the
+  connector configuration. Private entries include the admitted principal and
+  pool even for shared-auth connectors. Personal connectors use a bounded
+  principal registry and transient results the authenticated subject. Putting a downstream client or credential on the wrong
   side of those lines is the highest-severity mistake available here.
 - **Route order is behavior.** Moving a mutation route below the wildcard
   `OPTIONS` opts it into CORS preflight; reordering admission after auth makes
   the cheapest possible attack the most expensive request.
 - **`close()` is idempotent and ordered.** Both admission pools, then the
-  connector limiters, then the executor, then the Connecta's runtime; Node's `listen()` calls it on
+  connector limiters, then the executor; Node's `listen()` calls it on
   SIGTERM/SIGINT.
 - **Structural mistakes throw at construction.** A duplicate connector id, an
-  invalid admission rule, the old boolean `accessTokens` option, a missing executor:
+  invalid admission rule or limit, an unknown option at any depth, the old
+  boolean `accessTokens` option, a missing executor, or an executor without a
+  lifecycle brand:
   all refuse to boot (`test/config.test.ts`, `test/registry.test.ts`). Starting
   in the wrong shape is worse than not starting.
+  Shipped `/worker` and `/quickjs` executors carry a non-enumerable global-symbol
+  brand that survives package duplication and bundling. Custom sandboxes opt in
+  through `customExecutor(executor, { lifecycle: "self-managed" })` from the root
+  entry and own their termination and cleanup. Plain upstream executors need
+  the `/worker` adapter, regardless of constructor name.
+
+## Operator data contract
+
+The contract now lives in [Operator UI](./operator-ui.md#operator-data-contract),
+including configuration provenance, live facts, activity disclosure, doctor,
+and the browser implementation. [Optional deployment modules](#optional-deployment-modules)
+keeps the module composition and request-lifetime rules here.