@zackbart/connecta 0.24.3 → 0.25.0

package/documentation/architecture.md

@@ -4,8 +4,10 @@ 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 actually assembled, and where a change is likely to break it.
+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
+[meta-tools](./meta-tools.md), [code mode](./code-mode.md), and
+[inbound auth](./auth.md).
 
 ## The two lifetimes
 
@@ -13,234 +15,418 @@ 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 }`. The `Registry` owns the connector set, address
-resolution, catalog caches, observed output schemas, connector health, and the
-per-connector call limiters. It is constructed once and lives as long as the
-isolate or process —
-on Workers that means a lazy module-scope singleton, which is why both
-deployment shapes build it outside the request handler.
+`{ fetch, registry, close }` (`src/index.ts`). The `Registry` owns the connector
+set, address resolution, catalog caches, 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 `remoteMcp()` connector also owns a runtime-local refresh completion
-gate. It coordinates credential mutation across concurrent request scopes but
-never shares their clients, transports, or responses, and never lets a follower
-cancel the owner. Every participant still awaits the refresh inside its own
-request lifetime; a cancelled follower leaves the shared owner untouched and
-removes only its own wait. The owner's request signal belongs to its token
-fetch. Cancelling that owner fails current joiners too because promoting one
-could replay a refresh token the authorization server already consumed.
-
-A valid token response is a consumed refresh token whether or not the owner
-survives to save it. The coordinator therefore keeps the accepted tokens on the
-flight, and when the owner fails after that response — cancelled, redirected
-to authorization, or invalidated — it persists the rotation on the host's own
-write, holds contenders behind the pending-mutation marker until that write
-lands, and hands them the saved rotation. No contender ever redeems the retired
-token again, and the marker can no longer outlive the write that clears it
-([#526](https://github.com/zackbart/connecta/issues/526)).
-
-The coordinator retains the owner's abort signal only through one temporary
-listener on the exact active refresh. Save, failure, cancellation, or
-generation retirement removes it along with the map entry. It never retains a
-token response, client, or transport. If cancellation lands after a valid
-response while its credential write is still running, a generation-keyed
-identity marker rejects new owners until that exact write finishes. The marker
-contains no promise and generation retirement removes it.
+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)).
 
 **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 work the runtime may have already torn down. Deferred work has one
-sanctioned channel — `ctx.waitUntil`, threaded through `fetch(request, env,
-ctx)`. Best-effort activity writes use it. An agent read that already demanded
-an expired catalog refresh may also use it while serving a complete catalog
-inside its stale window. That refresh owns a new scope and deadline; it never
-carries the inbound scope or signal past the request.
-
-The registry is deliberately on the long side of that line and the MCP server
-deliberately on the short side. A fresh `McpServer` per request is what makes
-the deployment stateless: no sessions, no server push, no resumability, and
-scope resolved from the request rather than remembered.
+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
+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
+`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. It checks MCP origins, upgrades the
-scheme when it must, runs the route table, then wraps whatever came back in
-security headers. Route *order* is the contract — several routes would behave
-differently if they were reachable in another order — so the table below is
-read top to bottom.
+`src/server.ts` is the composition root: MCP origin check, scheme upgrade, route
+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 | `/mcp` and every `/mcp/` suffix reject a disallowed `Origin` with a fixed 403 before redirects, admission, auth, or preflight. `allowedOrigins` defaults to the configured public origin plus HTTP(S) loopback origins at any port. Requests without Origin are admitted. |
-| 0 | HTTPS upgrade | 308 to `publicUrl` when it is HTTPS and the request arrived over HTTP. Path and query are *assigned* onto the configured URL, never resolved against it, so a `//host` pathname cannot replace the deployment origin. `/health` is exempt: a loopback container probe must not depend on public DNS and TLS. `/ui` is canonicalized to `/` while upgrading. |
-| 0 | Cloudflare Access (Worker deployment, when enabled) | Edge admission before this route table. Managed OAuth owns its challenge and discovery metadata; an admitted direct invocation carries trusted identity in `ctx.access`. |
-| 1 | Mounted UI routes | The optional UI handles its shells, assets, data, details, and auth mutations before wildcard OPTIONS. Mutation routes refuse preflight rather than inheriting MCP CORS. No UI module means none of these routes. |
-| 2 | MCP preflight | Allowed `OPTIONS` on `/mcp` or any `/mcp/` suffix returns 204 without admission or auth. Reflect the allowed origin and requested valid `mcp-param-*` header names. |
-| 2 | Other `OPTIONS` | Auth metadata gets a chance, otherwise compatibility CORS preflight. |
+| 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 payload-free health, executor, admission, and deployment metadata; connector drift uses stable short hashes and downstream admission sums shared and personal controllers without ids. Reserved routes reflect installed modules. |
-| 5 | `/oauth/callback/<connectorId>` | Core downstream OAuth completion, state verification and personal ownership checks; independent of UI. |
-| 6 | `/mcp`, `/mcp/<pool>` | Origin check before admission, admission before auth, then a request-local MCP server. A pool path serves the declared pool intersected with the identity's own view; any undeclared suffix, including malformed names, a refusing grant, and a throwing grant return the same 404 status, body, and headers after auth. Grant lookup latency is not hidden; see [pools](./auth.md#pools). |
+| 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.
+`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.
 
-Every response leaves through `withSecurityHeaders`: `nosniff`, a no-referrer
-policy, HSTS on HTTPS, while the UI module adds a nonce-based script CSP and framing denial to its shells. `test/server-route-contracts.test.ts` pins this 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.
+An admitted non-preflight `/mcp` request then takes five steps in
+`src/routes/mcp.ts`:
 
-`/mcp` first checks Origin, including on preflight. A disallowed browser origin
-costs no permit and no auth lookup. The explicit `allowedOrigins: "*"` escape
-hatch preserves open CORS; a list reflects only admitted origins and varies
-responses by Origin. An originless client needs no CORS allow-origin header.
-
-An admitted non-preflight request then takes six steps:
-
-1. **Admit.** One permit from the deployment-wide FIFO pool, taken before auth
-   so an unauthenticated flood costs a permit rather than a Clerk lookup
-   ([request admission](./request-admission.md)). The permit is held until the
-   response *body* completes, not until the handler returns.
+1. **Admit.** 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 or the caller leaves, not until the
+   handler returns.
 2. **Authorize.** Each `InboundAuth` provider's `authorize` in order, bearer
-   before interactive providers. First `ok` admits; if all fail, the last provider's challenge
-   response is returned. No providers configured means open — development
-   only, and it warns at construction.
-3. **Derive the registry view.** Auth supplies a namespaced subject and, for a
-   human, a principal. `identity.connectorAccess` selects declared connector
-   ids and, for a narrower slice, exact `connector.tool` addresses; the
-   scoped view filters every catalog read through them. Personal connectors use the principal partition; result paging uses
-   the subject partition. No caller parameter selects either.
-4. **Narrow to the pool.** On `/mcp/<pool>`, look the name up in the
-   declared pools and run its grant against the authenticated identity. The
-   view becomes the pool intersected with the identity's `connectorAccess`;
-   a pool can never widen it. Anything else is a 404 that names no pool.
-5. **Refuse `?toolkit=`.** Caller-selected toolkits were removed ([#178](https://github.com/zackbart/connecta/issues/178))
-   but the URLs naming them were handed out, so the parameter is a 404 rather
-   than silently serving the full registry. Retiring a scoping boundary into
-   fail-open is the one outcome worse than the 404.
-6. **Serve.** A fresh `McpServer` per request, the seven meta-tools registered
-   against the registry and the response
-   handed back.
+   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.
+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`).
+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`
+   (`test/server.test.ts`, `test/code-first-surface.test.ts`).
 
 ## Layers below the meta-tools
 
-The meta-tool handlers are thin. The work sits in four services the registry
-owns or hands out, and a change usually belongs in exactly one of them:
+The meta-tool handlers are thin. The work sits in five 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 tool listing, search, and describe. It coalesces reads inside one request and opts agent reads into the runtime's deferred catalog channel when one exists. |
+| `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 schema renderer discovery shows. |
+| `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/meta-tools.ts` and `src/execute.ts` are two front doors onto the same
-three services. That is the point: a program's `connecta.call` and a top-level
-`call_tool` reach `InvocationService.invoke` by different routes and get the
-same admission, the same credential resolution, and the same fail-closed
-read-only check. `test/execute.test.ts` asserts that parity directly, because
-the alternative — a sandbox path that quietly diverges — is how generated code
-would mint a capability.
+`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
+program's `connecta.call` and a top-level `call_tool` reach
+`InvocationService.invoke` by different routes and get the same admission, the
+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.
+
+## 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
+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
+at construction, because a pool that quietly became unbounded is worse than a
+deployment that refuses to boot. The queue is global FIFO across identities: a
+capacity boundary, not tenant fairness, and one deployment serves one tenant.
+
+Call admission (`src/call-admission.ts`) answers what the envelope cannot see —
+a connector's optional policy over its own `Connector.callTool` attempts,
+partitioned by an optional `partitionKey` and bounded by concurrency, a
+rolling-window budget, or both. Exactly one rule is accepted, because several
+cannot be faked as sequential leases: consuming a rolling token before a later
+rule refuses would charge a call that never reached the provider, the exact
+accounting error a budget exists to prevent. Both layers are pinned by
+`test/request-admission.test.ts` and `test/call-admission.test.ts`.
+
+## 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)`, is an atomic
+claim: `null` means absent (expired counts) on the way in and delete on the way
+out. Nothing in core requires it yet. 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. A subsystem that needs an exactly-once claim will
+require it explicitly rather than emulate it that way.
+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`.
+
+`src/credentials.ts` is the AES-GCM vault behind the root-exported
+`CredentialVault` contract, selected through the `vault` slot. It binds connector
+id and owner into the authenticated encryption context, because sharing a backend
+is not permission to share a principal's credentials. Two rules carry the
+subsystem: credentials never leave the host — read only through the owning
+connector's `ctx.credential`, rendered by nothing, absent from activity and model
+recovery — and they fail at use, proactive liveness probing having been removed by
+decision. The vault is read per call, so a replacement needs no restart
+(`test/credentials.test.ts`).
+
+Connectors are the boundary between the fixed meta-tool surface and downstream
+capability, and `api()`, `remoteMcp()`, and a hand-written `Connector`
+(`src/connectors/`, plus the prebuilt connections under `src/providers/`) all
+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
+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.
 
 ## Optional deployment modules
 
-`createConnecta` takes closed typed `ui`, `vault`, and `activity` slots. Factories
-live at `/ui`, `/credentials`, and `/activity`; bearer auth lives at
-`/auth/bearer`. Root exports the contracts, never these implementations. There
-is no module array, runtime registration, or plugin lifecycle.
-
-Core keeps connector discovery, the executor contract, invocation, permissions,
-and OAuth callback verification together. Optional modules contribute no
-runtime work when omitted. The UI supplies credential handoff URLs only while
-mounted. Status reads never initiate OAuth, and each lazy details request owns
-its downstream scope. See [operator UI](./operator-ui.md).
+`createConnecta` takes closed typed `ui`, `vault`, and `activity` slots, with
+factories at `/ui`, `/credentials`, and `/activity` and bearer auth at
+`/auth/bearer`. 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) —
+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
+never starts authorization, since OAuth begins with an explicit authorized POST,
+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. Credential handoff URLs exist only while the UI is
+mounted; OAuth callbacks never need it.
+
+Its appearance is one token layer. `src/operator-ui/browser.css` resolves every
+color, radius, and font through a custom property and mixes the rest from those
+with `color-mix`, so `branding.theme` only has to append a `:root` block after
+that 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.
 
 ## Import-graph purity
 
-Nothing reachable from `src/index.ts` may import a `node:` builtin. The core is
-Web-API only so the same code runs unchanged in workerd and in Node.
-
-The Node-touching paths are `src/node.ts` (the `node:http` adapter),
-`src/storage/file.ts`, and the QuickJS process pool
-(`src/executors/quickjs.ts` and its child entry). Each lives behind an explicit
-subpath export — `@zackbart/connecta/node`, `@zackbart/connecta/quickjs` — and
-must stay unreachable from the root entry. The optional Clerk adapter is behind
-`./auth/clerk` for the adjacent reason: `@clerk/backend` is an optional peer,
-not a dependency. The zero-dependency Cloudflare Access adapter likewise stays
-behind `./auth/cloudflare-access`: 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 from `src/index.ts` and
-fails on (a) any `node:` specifier in a reachable file and (b) the Node
-adapter, file storage, QuickJS parent or child, auth adapters, UI bundle,
-encrypted vault implementation, or activity implementation being reachable at all. `test/package-surface.test.ts` and
-`scripts/check-package.mjs` guard the other half — that the published tarball
-matches the same boundary.
-
-The failure mode this prevents is not theoretical: a single convenience import
-of `node:crypto` in a shared helper makes the whole Worker deployment shape
-stop building, and it will do so in someone else's repository rather than
-this one.
-
-## Where things live
+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
+(`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:`
+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
+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 Effect v4; 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
+second async paradigm. The reason for the rewrite is the first section of this
+guide: the bugs here are lifetime bugs, and Effect makes a lifetime a value —
+a Scope that closes on every exit, an interrupt that reaches whatever a fiber
+is waiting on, a Deferred that one party completes and any number join. The
+conversion found and closed a dozen of them, each with a test that fails on the
+code before it: permits and leases held after their caller left, waits with no
+bound, and races between requests.
+
+### Shell and core
+
+Each converted module is a shell and a core. The shell keeps its exported class
+or function exactly — same members, same error classes, same `.d.ts`, private
+member names included, because TypeScript ships those too. The core is an
+Effect program behind it. In a published class it lives in a `static` block,
+the one place that can read private state without adding a member to the
+declarations; elsewhere it lives in an unexported function or in
+`src/runtime/`, which no `exports` target reaches. Errors keep their classes
+(`ConnectorCallError`, `ExecutorAdmissionError`, `CallAdmissionError`) because
+callers and tests check `instanceof`, `name`, and `message`.
+
+Effect callers skip the Promise and take the program: `admit` and
+`acquireScoped` for request admission (`src/runtime/admission.ts`), `admitCall`
+and `acquireCallScoped` for call admission, `closeScope` and `closeScopeOnExit`
+for a connector scope, `withDeadlineEffect` where Promise code has
+`withDeadline`. The build prunes every declaration no `exports` target reaches,
+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`,
+`forkDaemon`, or `ManagedRuntime.make`. It exports two ways out:
+
+- **`runEdge(effect, { signal, runtime? })`** runs an effect at a Promise
+  boundary. It rethrows the original failure or defect, never a wrapper. It
+  turns an interrupt into the caller's `signal.reason` rather than Effect's
+  "All fibers interrupted without error". And it runs every fiber on a
+  scheduler that yields through microtasks: Effect's default yields through
+  `setImmediate`, which vitest's fake timers freeze and Workers never had. The
+  price is that a fiber never yields to I/O, so CPU-heavy work stays out of
+  Effect loops.
+- **`detach(effect, ctx)`** is the only fire-and-forget, and it hands the work
+  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
+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
+(`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.
+
+### What runs on Effect
+
+| 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, or at once if the handler fails first. 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 Deferred per connector, completed by the first asker's read from that read's own settlement, so a probe deadline ends one asker's wait and never the read the others share. 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; persisted-catalog writes take per-connector turns, each a Deferred its own request completes. |
+| 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`. |
+
+### What stays plain
+
+- **Everything a deployment writes against.** The `Connector` contract,
+  `api()`, the providers, custom connectors, storage adapters, and the vault
+  are Promises. A connector is called with `Effect.tryPromise`, never asked to
+  return an Effect.
+- **Inbound authorization.** `authorize` in `src/routes/shared.ts` ships in
+  the declarations and in the `./activity` bundle; converting it cost 32 KB
+  gzip there for nothing a caller could see.
+- **Pure synchronous code.** Ranking, schema rendering, classification,
+  `validateToolInput`, the host-call budget, the emit collector, failure
+  framing, and result shaping. The microtask scheduler never yields to I/O, so
+  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
+  child, runtime, and protocol, and the operator UI's browser app.
+
+### Across requests
+
+Work shared across requests meets only through a Deferred that the owning
+request completes, never through a fiber that outlives its request. Two
+workerd rules follow, and both have bitten.
+
+**Waiting on a shared Deferred is its own edge.** Deferred resumes a waiting
+fiber synchronously, inside the call that completed it, which on Workers means
+inside the completing request's I/O context. A waiter that goes on to touch its
+own body, transport, or storage there fails with "Cannot perform I/O on behalf
+of a different request", or hangs until its deadline. So the wait runs through
+`runEdge`, and the waiter does its own I/O after awaiting that promise, which
+workerd resumes in the waiter's request as it does any promise resolved from
+another. The same holds one level out for every queue: a queued call, a queued
+`execute_code`, and a queued `/mcp` request are each handed their permit from
+inside the request that released one, so each awaits the controller's
+Promise-shaped `acquire` rather than yielding its Effect program, and does its
+own work only once that promise resolves. Effect's `Semaphore` is not used
+across requests for the same reason, and because a same-tick newcomer can take
+a released permit ahead of a waiter that queued earlier.
+
+**Never read another request's signal.** On workerd, reading `aborted` or
+`reason`, or calling `abort()`, on a signal that belongs to another request
+throws; adding and removing listeners does not. Code that runs from another
+request's completion — a queue handing out a permit, `close()` — must not look
+at a waiter's signal. A waiter whose signal aborts leaves the queue from its
+own listener, in its own request.
+
+One corollary is easy to break by tidying. Workerd cancels a request as hung
+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.
+
+### Why not Schema or HttpApi
+
+Both were measured and both lost. `effect` is imported through its barrel,
+which defeats tree-shaking: the first conversion step measured about +20 ms
+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
+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`); nothing in
+`src/` uses `effect/unstable/*`, which would have to stay behind a subpath.
+
+The core's cost is recorded rather than guessed. Against 0.24.4 the root entry
+grew from 235,346 to 279,526 bytes gzip, the Worker example from 263,949 to
+314,336, and each provider by about 36 KB, since each reaches Effect through
+`remoteMcp()`; `npm run check:bundle` caps every entry against
+`scripts/bundle-budget.json`. An install carries about 53 MB of `effect`, with
+no dependencies of its own.
+
+## Where else to look
+
+Beyond the modules already named:
 
 ```
 src/
-  index.ts            createConnecta + the public re-exports (Workers-clean)
   server.ts           route ordering, HTTPS upgrade, security wrapper
   routes/             one file per surface; shared.ts holds the auth gate
-  meta-tools.ts       the six non-execute meta-tools over the registry
-  execute.ts          execute_code, the sandbox host bridge, emitted media
   skills.ts           MCP instructions, the usage skill, connector guides
-  registry.ts         connector set, addresses, health, call limiters
-  catalog-service.ts  request-local catalog access, search, and describe
-  catalog.ts          ranking, summaries, compact schema rendering
-  result-shapes.ts    passive runtime-only observed output schemas
-  invocation.ts       one tool call, end to end
   catalog-drift.ts    vetted manifests and the counts a refresh produces
-  credentials.ts      the AES-GCM connector vault over KVStorage
   activity.ts         optional history factory and best-effort recorder
-  call-admission.ts   connector-partitioned downstream permits and budgets
-  executor-admission.ts  the portable bounded queue both pools use
-  ui.ts               the served operator shell and /ui/data payload
-  operator-ui/        the Preact app, its pure rules, and the built bundle
-  connectors/         remote-mcp.ts, api.ts, guarded-fetch.ts
-  providers/          the maintained prebuilt connections
   auth/               bearer, Cloudflare Access, clerk (optional peer), downstream OAuth
   executors/          the QuickJS pool and child (Node only)
-  storage/            memory.ts, file.ts (Node only)
   node.ts             listen() + fileStorage re-export (Node only)
 ```
 
+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
+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 use the
-  authenticated subject. Anything cached per request still dies with it.
-  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.
-- **Admission runs before auth, on purpose.** Reordering them to "authenticate
-  first" makes the cheapest possible attack the most expensive request.
-- **`close()` is idempotent and ordered.** It closes both admission pools and
-  the connector limiters, then the executor. Node's `listen()` calls it on
+  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
+  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
   SIGTERM/SIGINT.
 - **Structural mistakes throw at construction.** A duplicate connector id, an
-  invalid admission rule, removed `accessTokens` option, or missing executor: all refuse to boot. A deployment that starts in the wrong shape is
-  worse than one that does not start.
-
-## Tests that enforce this
-
-| Invariant | Suite |
-| --- | --- |
-| The core imports no `node:` builtin and reaches no Node-only module | `test/purity.test.ts` |
-| The published surface matches the same boundary | `test/package-surface.test.ts`, `scripts/check-package.mjs` |
-| Route order, per-route auth, and byte-exact refusals | `test/server-route-contracts.test.ts` |
-| `/mcp` end to end, the open routes, exactly seven tools, bounded connector orientation | `test/server.test.ts`, `test/code-first-surface.test.ts` |
-| Construction-time refusals and the grouped config boundary | `test/config.test.ts`, `test/registry.test.ts` |
-| Program and top-level calls take the same enforced path | `test/execute.test.ts` |
-| Both deployment shapes still compile and configure the real thing | `test/deployment-shapes.test.ts`, `npm run check:examples` |
+  invalid admission rule, the removed `accessTokens` option, a missing executor:
+  all refuse to boot (`test/config.test.ts`, `test/registry.test.ts`). Starting
+  in the wrong shape is worse than not starting.