@zackbart/connecta 0.25.0 → 0.26.1

package/documentation/architecture.md

@@ -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,8 +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 or the caller leaves, 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
@@ -94,12 +94,12 @@ 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 |
@@ -109,6 +109,7 @@ or hands out, and a change usually belongs in exactly one of them:
 | `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/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
@@ -129,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,
@@ -139,19 +152,85 @@ 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.
-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.
+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,
@@ -184,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.
@@ -202,17 +281,110 @@ 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
+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
-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.
+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`
+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
+page). The UI's `browser.css` imports both, and the build writes the same CSS,
+minified, into `src/page-styles.ts`, a module of two strings that core imports
+without the UI bundle, so an OAuth callback still renders with the UI omitted.
+`renderPage` in `src/branding.ts` is the one layout: head, favicon (the default
+is linked only when the UI serves it), `data-scheme`, the tokens with the theme
+after them, and the masthead. So `branding.theme` only has to append a `:root`
+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.
+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
 
@@ -306,12 +478,13 @@ would be another partition's.
 
 | 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. |
+| 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 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. |
+| 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. |
@@ -368,6 +541,20 @@ 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,

package/documentation/auth.md

@@ -51,8 +51,11 @@ deployments and providers that return no identity share one result partition.
 
 `identity.connectorAccess` returns `"all"` — the default — or a list of grants:
 a declared connector id opens every tool on it, a `connector.tool` address opens
-that tool alone, and grants are additive, so a bare id beside addresses for the
-same connector means the whole connector. It governs discovery and use alike.
+that tool alone, and `{ tool: "connector.tool", requireReadOnly: true }` opens
+that exact tool only while the loaded catalog says it is explicitly read-only.
+The guarded form accepts no connector-wide grant. Grants are additive, so a
+bare id or an unrestricted address beside a guarded address wins for that
+tool. It governs discovery and use alike.
 
 Tool grants are enforced in the scoped registry view, below the catalog service,
 so `search_tools`, both call tools, a program's `connecta.search`,
@@ -69,6 +72,84 @@ There is no *caller-selected* tool set. A narrower slice is a branch in this
 resolver or a config-declared pool; a bot that needs its own slice is its own
 bearer subject. What a request may never do is name its own scope.
 
+### Team read sets
+
+`connectorAccess` is the supported way to give Engineering and Marketing
+different views of one deployment. Keep membership in deployment code and
+review the exact tool addresses you intend to grant:
+
+```ts
+const engineering = new Set(["engineer-id"]);
+const marketing = new Set(["marketer-id"]);
+const engineeringGrants = ["issues", { tool: "campaigns.list", requireReadOnly: true }] as const;
+const marketingGrants = ["campaigns", { tool: "issues.search", requireReadOnly: true }] as const;
+
+createConnecta({
+  auth: cloudflareAccessAuth(),
+  identity: {
+    connectorAccess: ({ principal }) => {
+      const id = principal?.id;
+      if (!id) return [];
+      return [...new Set([
+        ...(engineering.has(id) ? engineeringGrants : []),
+        ...(marketing.has(id) ? marketingGrants : []),
+      ])];
+    },
+  },
+  connectors: [issues, campaigns, billing],
+  executor,
+});
+```
+
+Here Engineering sees every `issues` tool and only `campaigns.list`;
+Marketing sees every `campaigns` tool and only `issues.search`. Neither sees
+`billing`. Someone in both groups gets both connectors in full because grants
+are additive. An unknown or unprincipalled identity gets an empty view. The
+example assumes the two exact tools have been reviewed as read-only; the names
+themselves carry no safety meaning. The guarded grants also check the current
+loaded annotations before discovery or use. Use a stable authenticated
+principal or subject for membership, never a request header or tool argument. A pool can
+narrow any of these views on its endpoint, but cannot make plain `/mcp` narrower.
+
+New tool names are excluded until added to a reviewed list. A removed or
+renamed name is unreachable and warned when the scoped view reads its catalog.
+For a guarded grant, missing, false, or contradictory read-only annotations
+also remove that tool from discovery and every invocation path, including
+`call_destructive_tool` and approval-exempt programs. An unrestricted exact
+string grant has the earlier behavior: a tool that changes from read to write
+stays granted, though `call_tool` refuses it and the write paths take over.
+Changing schema alone does not revoke either kind of grant. Review schemas,
+annotations, and downstream behavior before changing lists or upgrading a
+maintained provider. An arbitrary remote MCP catalog can drift without a
+package upgrade; a valid stale cached catalog may keep its earlier
+classification until refresh. A downstream can also keep a read-only
+annotation while changing the behavior behind it. For `api()` tools, the
+deployment author owns both declaration and handler. Connecta enforces the
+loaded declaration, not the downstream's promise of no side effects. A
+restricted downstream credential adds protection where the provider offers
+one, but does not replace the per-identity grant.
+
+When the resolver returns `[]`, connector-level discovery and the connection
+UI have no connectors to show. An address-only grant can leave a connector
+visible while its named tool is absent; the tool stays unreachable. A failed
+remote catalog load is an error, not an empty successful catalog; a valid stale
+catalog may be served within its configured stale window. A guarded grant
+whose tool loses qualification can leave its connector visible with no tools.
+Personal OAuth ownership and credential-administration permissions remain separate from
+visibility. These are the checks for a team read set:
+
+| Boundary | Expected result for a reviewed address and an excluded write |
+| --- | --- |
+| `search_tools`, `describe_tools`, connector guides | Show the granted address; omit the write. |
+| `call_tool` | Invoke an explicitly read-only granted address; return `unknown_tool` for the write. |
+| `call_destructive_tool` | Return `unknown_tool` for the excluded write, without dispatch. |
+| `execute_code` search, describe, call | See granted tools only; refuse the excluded write. A granted write still follows the separate approval rules. |
+| Connection UI | List granted tools only; never turn visibility into credential administration. |
+| `/mcp/<pool>` | Intersect its grants with the identity view; plain `/mcp` keeps the identity view. |
+
+Integration tests in `test/identity-scope.test.ts` exercise these paths and
+the older unrestricted exact-grant behavior.
+
 ## Pools
 
 A pool is a named slice of the deployment served at its own endpoint,
@@ -169,6 +250,87 @@ means authorizing again. A vault without the optional `seal`/`open` members
 keeps these values plaintext and draws a startup warning. Without any vault,
 nothing changes: the state is plaintext, as it always was.
 
+## Starting, restarting, and retiring an OAuth epoch
+
+Every downstream OAuth value lives under an **epoch**, the value of
+`oauth:generation`. A restart or disconnect publishes a new one before it
+deletes anything, and a write from a flow that captured an older epoch lands
+in that epoch's own key namespace, where no reader looks. The fence is what
+keeps a retired grant out of use; deleting the old keys is hygiene on top.
+
+The operator's `POST /ui/oauth/<id>` takes a `mode` query parameter:
+
+| Request | What it does |
+| --- | --- |
+| `POST /ui/oauth/<id>` or `?mode=restart` | `startAuth(ctx, { force: true })`: a new epoch, with tokens, the registered client, discovery, and any pending flow wiped, so the next flow registers a client again. |
+| `?mode=continue` | `startAuth(ctx, { force: false })`: hand back the pending authorization URL if it was written in the last ten minutes; otherwise start a flow in the current epoch, reusing the stored client registration. A disconnected connector still gets its new epoch first. |
+| `DELETE /ui/oauth/<id>` | Disconnect: a disconnected epoch that passive reads never turn back into a consent flow. |
+
+Any other `mode`, or more than one, is a 400 before anything starts; the
+management permission, visibility, and principal checks are the same for
+both modes, and a personal connector continues only the caller's own flow.
+A 200 answers `{ state, authorizationUrl?, reused? }`, with `reused` present
+beside every URL: `true` when an earlier start's URL came back unchanged. A
+continue that reused a URL or found the connection healthy changed nothing,
+so it leaves the cached catalog alone; every other start invalidates it. The
+ten minutes are `PENDING_AUTHORIZATION_MAX_AGE_MS`. Connecta never expires
+its own half of a URL, but authorization servers expire theirs, and a fresh
+start that keeps the registration costs one authorization request. A URL
+stored without a write time — by an earlier release, or by a connector never
+reset since epochs arrived — is stale by definition. `authorize_connector`
+without `force` follows the same rule.
+
+Continue trusts the stored registration, which carries the `redirect_uris`
+it was registered with. After a `publicUrl` change the authorization server
+refuses that client's new callback at consent. Restart registers a client
+for the current URL and recovers.
+
+A restart cannot know which retired epochs a late write reached, so it
+publishes a **cleanup lineage** under the new epoch before activating it:
+the retired epochs, as the same plain list of names every release reads, and
+beside it a record of when each retired. A published lineage is never
+rewritten. A stale writer whose own cleanup fails appends to the live
+lineage, and a restart that rewrote the list it had read could drop that
+append. An epoch leaves the lineage only by being left out of its
+successor's.
+
+A restart does the same storage work however many came before it. After the
+fence it deletes the one epoch it retired: six values, then that epoch's own
+lineage records. An epoch's manifest outlives its values only when their
+deletion failed, so the restart also reads the manifests of the eight most
+recently retired epochs (`RETRY_PROBES`) and cleans up again any that still
+have one. A Disconnect or Restart that reported a failed cleanup therefore
+deletes the old grant when the operator retries it. Before publishing, it
+sweeps up to 16 epochs retired more than `CLEANUP_GRACE_MS` (24 hours) ago,
+oldest first, and leaves out only those whose values and records were all
+deleted. A failed sweep is carried and tried again later, and never fails
+the restart. Any other epoch inside its grace is not deleted again. A late write into it is unreadable behind the fence,
+and the late writer deletes it itself. If that delete fails, the writer
+records the epoch again as retired at that moment, appending it or, when it
+is already listed, moving only its time. A restart that swept it re-reads the
+lineage before publishing and keeps it. Whatever remains is swept once the
+grace has passed. Two such writers racing can lose one time update, which
+leaves the earlier time; a time missing altogether reads as retired at the
+moment of the restart that reads it, which only lengthens a grace.
+
+**The assumption:** no request holds a retired epoch for a day. The writers
+that can land late are OAuth flows, refreshes, and readers whose Workers KV
+replica still serves the old generation for a minute or more; none of them
+run that long. If it fails, only a writer that dies between its write and
+its own cleanup leaves residue no restart tracks, and that residue is never
+readable.
+
+The lineage holds at most 5,000 epochs, the ones retired within the last day
+plus any the sweep has not reached. A restart that would exceed that is
+refused before the fence moves, which takes more than 4,000 restarts of one
+connector in a day on top of the 1,000 an earlier release allowed. A
+connector that reached that release's 1,000 wall restarts again the day it
+upgrades, and its old entries drain 16 per restart a day later. An older
+release ignores the times, so a rollback still restarts unless a lineage has
+grown past its own 1,000 cap. Deletes run six at a time, the Workers limit
+on simultaneous connections, and catalog invalidation deletes its chunks
+concurrently under the registry's chunk I/O bound.
+
 ## Refresh failures
 
 A failed token refresh means one of two things, and connecta decides which
@@ -348,6 +510,28 @@ instead of a base64 stack on every route.
 
 ## Human authentication management
 
+An operator's OAuth Connect or Restart request gives the start and its handoff
+30 seconds. The request's abort signal and that deadline reach downstream OAuth
+fetches, including metadata discovery and dynamic registration. If the deadline
+expires, the route returns `504` with `OAuth authorization start timed out` after
+an already-started reset finishes. Storage has no cancellation contract: its
+generation write must drain before a response, or it could publish an old epoch
+over a newer flow. Catalog invalidation and connector scope close also finish
+outside the deadline. Those storage and cleanup waits can extend the click past
+30 seconds; the bound is on downstream work, where a hung authorization server
+was the failure. The OAuth provider checks its signal before writing and removes
+a cancelled value write that finishes late. An operator Disconnect keeps its
+existing commit-through behavior even if the browser leaves.
+
+Restart retains a dynamically registered client only when its stored issuer and
+the connector's URL, redirect URI, client metadata, auth scope, transport settings,
+and owner partition still match. It drops the grant and one-shot flow state,
+selects the authorization server again, and re-seals the retained client under
+the replacement epoch key. A different issuer registers a new client. Disconnect
+and issuer-mismatch recovery discard it. The SDK has no client-validation
+exchange while constructing a fresh consent URL; a provider that revokes a
+retained client may refuse it only at consent or callback, after this request.
+
 Credential and OAuth mutation require an admitted interactive human, connector
 visibility, the appropriate shared or personal permission, and an exact
 same-origin `Origin` for browser requests. A configured MCP bearer never becomes