@zackbart/connecta 0.24.4 → 0.26.0

package/documentation/architecture.md

@@ -43,7 +43,7 @@ channel, `ctx.waitUntil`, threaded through `fetch(request, env, ctx)` — activi
 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 resumability, scope resolved rather than remembered.
+server push, no stream resumability, scope resolved rather than remembered.
 
 ## Request lifecycle
 
@@ -61,7 +61,7 @@ top to bottom.
 | 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. |
+| 4 | `/health` | Open and payload-free: health, executor, whether resumable writes are on, 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. |
@@ -77,7 +77,8 @@ An admitted non-preflight `/mcp` request then takes five steps in
 
 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, not until the handler returns.
+   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
@@ -93,21 +94,22 @@ An admitted non-preflight `/mcp` request then takes five steps in
 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 eight 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 five modules the registry owns
+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. 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/resumable.ts`, `src/run-journal.ts` | Resumable writes: a program's host-call numbering, the write gate that pauses it, the journal a paused run becomes, the replay `resume_execution` plays from it, and the claim and write-ahead marks that keep an approved write to at most one send. |
 
 `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
@@ -128,6 +130,18 @@ 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.
+`admission.requests.maxDurationMs` defaults to 300,000 ms and may be set to a
+positive whole number up to 2,147,483,647 ms. Its clock starts when admission
+grants a permit and covers authorization, tool execution, and response delivery.
+The owning request aborts its derived signal at that deadline, including signals
+passed to connector calls, and closes a live response. If workerd ends the
+request without running that timer or cancellation, the controller reclaims
+only the expired permit's scalar record on the next request (or a queued
+request's own timer). It never reads the old request's signal or touches its
+stream. Expired queued waiters are pruned before any handoff; every handed-off
+permit has its own deadline even if the recipient never resumes. Lease identities
+make an old late release harmless to a newer permit. Set the bound above the
+longest admitted request the deployment expects to serve.
 
 Call admission (`src/call-admission.ts`) answers what the envelope cannot see —
 a connector's optional policy over its own `Connector.callTool` attempts,
@@ -138,15 +152,91 @@ 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`.
 
+### Production Worker disconnects
+
+The original production probe for [#573](https://github.com/zackbart/connecta/issues/573)
+ran on 2026-09-25 with compatibility date `2025-01-01`, first with no flags and
+then with `enable_request_signal`. It used Wrangler 4.114.0 and a Node 26.9.0
+client. A raw Worker stream established the runtime behavior; a custom auth
+provider returning a synthetic streaming 401 exercised Connecta's real admission
+wrapper. Each case had its own Connecta instance with one request permit and no
+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 |
+
+The last row is a different failure. The client observed the response end
+*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
+an actual MCP request; this measures retained capacity, not an infinite leak.
+
+Enable `enable_request_signal` when deploying on Workers: it let Connecta's
+abort listener cancel the source and release admission for live responses in
+this experiment. It does not solve runtime-ended streams. The admitted-request
+bound above recovers capacity on the first later request at or after its
+deadline, even if the old request's timer never ran. This is capacity recovery,
+not proof that workerd cancelled an old stream. A still-live request reaches
+the same hard deadline and is aborted in its own context.
+Cloudflare documents the flag in its
+[Request API](https://developers.cloudflare.com/workers/runtime-apis/request/).
+
+A second production run on the same date tested the request bound at 2,000 ms.
+All twelve raw-stream and MCP cases passed with both flag configurations. Live
+MCP requests still rejected a competing request with 503 before the deadline;
+the first MCP request after the deadline returned all eight tools with 200 in
+the original isolate. Admission then reported zero active requests. Without the
+flag, the source still recorded no abort or cancellation, so recovery did not
+rely on runtime cleanup. The [recovery observations](https://github.com/zackbart/connecta/blob/32d8e94/scripts/probes/worker-disconnect-recovered-2026-09-25.json)
+also retain two inconclusive queue-handoff cases: concurrent client connections
+reached different isolates and could not establish an abandoned queued waiter.
+A [second trial using HTTP/2](https://github.com/zackbart/connecta/blob/b174812/scripts/probes/worker-disconnect-h2-2026-09-25.json)
+repeated the twelve passing core cases and verified queued cancellation with
+request signals enabled. Even on one HTTP/2 connection, the no-signal queue case
+crossed isolates and remained inconclusive. The Node and workerd regression
+suites cover expired waiters, orphaned handoffs, and identity-safe late release
+deterministically.
+
+To repeat from a repository checkout, run
+`node scripts/probes/worker-disconnect.mjs` with an authenticated Wrangler.
+The script is not in the npm package. It deploys a disposable Worker containing
+only synthetic data, verifies the served configuration, saves observations under `eval/results/`,
+and deletes the Worker in `finally`. It uses no `waitUntil`, which would change
+the lifetime being measured. The production runtime build number was not
+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.
-Adapters: `src/storage/memory.ts`, `src/storage/file.ts` (Node), and the
-Cloudflare KV/D1 pair in `examples/worker/`, copyable reference source and
-deliberately not an importable subpath.
+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`. Resumable writes require it: of two `resume_execution` calls racing
+for one paused run exactly one may win, and every write that run sends is
+marked on its header first, so a read and a write standing in for the claim
+could send an approved write twice. Omitted, `execute.resumableWrites` is on
+exactly when the store has it, and asking for it over a store without it
+refuses to construct. 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`.
 
 `src/credentials.ts` is the AES-GCM vault behind the root-exported
 `CredentialVault` contract, selected through the `vault` slot. It binds connector
@@ -173,9 +263,9 @@ change who owns its auth.
 
 ## Optional deployment modules
 
-`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
+`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
 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.
@@ -187,8 +277,15 @@ 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. Credential handoff URLs exist only
-while the UI is mounted; OAuth callbacks never need it.
+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
+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
@@ -199,6 +296,86 @@ 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.
 
+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.
+Resumable writes and approval exemptions are off. 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`).
+
 ## Import-graph purity
 
 Nothing reachable from `src/index.ts` may import a `node:` builtin, so the same
@@ -218,6 +395,180 @@ 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, 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. |
+| Resumable writes (`resumable.ts`) | A play's stop is a Deferred its write gate completes, raced against the executor like the watchdog; the gate for call n awaits the decision Deferreds of every lower-numbered call; header writes are one compare-and-set at a time on a per-play turn. A paused run holds nothing request-bound — its journal is data, and the next play is a new request's. |
+| 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`. |
+
+### 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.
+
+**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.
+
+### 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:
@@ -250,7 +601,7 @@ compiling and configuring the real thing.
   `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; Node's `listen()` calls it on
+  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, the removed `accessTokens` option, a missing executor: