@zackbart/connecta 0.24.2 → 0.24.4

package/documentation/request-admission.md

@@ -1,170 +0,0 @@
-# Request admission
-
-Connecta bounds work at the Web-standard request boundary — before inbound
-auth, before the MCP server exists, before any catalog is touched. A burst
-therefore meets an explicit active count and an explicit queue instead of
-asking traffic shape and the runtime allocator to pick the process high-water
-mark.
-
-There are two pools here and a third elsewhere. This guide covers the first
-two: the deployment-wide `/mcp` pool and the fallback code pool. Per-connector
-downstream bounds are [call admission](./call-admission.md), which is a
-different question — request admission bounds the whole MCP envelope, call
-admission bounds the individual `Connector.callTool` attempts fanned out inside
-it.
-
-## The pools
-
-Every non-preflight `/mcp` request takes one permit from a deployment-wide FIFO
-pool. Initialization, discovery, ordinary calls, and `execute_code` all pay it.
-A program then takes a *second* permit from the deliberately smaller code pool,
-so one request cannot trade ordinary capacity for an unbounded number of
-sandboxes.
-
-```ts
-const connecta = createConnecta({
-  admission: {
-    requests: { concurrency: 16, maxQueueSize: 32, queueTimeoutMs: 5_000, retryAfterMs: 1_000 },
-    code:     { concurrency: 2,  maxQueueSize: 8,  queueTimeoutMs: 5_000, retryAfterMs: 1_000 },
-  },
-  // …
-});
-```
-
-Those values are the defaults, and both pools are the same
-`AdmissionController` (`src/executor-admission.ts`) with different numbers.
-`maxQueueSize: 0` is the fail-fast shape. Every value is a finite whole number;
-concurrency and the queue timeout must be positive, while queue size and the
-retry hint may be zero. Invalid bounds throw at construction rather than
-silently removing the deployment's memory boundary — a pool that quietly became
-unbounded is worse than a deployment that refuses to boot.
-
-`admission.code` is a *fallback*. An executor that implements `acquire()` is an
-`AdmittingExecutor` and already owns a bounded pool, so its own settings win and
-connecta warns that `admission.code` was ignored. `quickJsExecutor()` is one of
-those: it defaults to one active execution and 32 queued callers, configured on
-the executor rather than here. Cloudflare's `DynamicWorkerExecutor` is not, so
-a Worker deployment gets the fallback pool wrapped around it at construction —
-which is also why `/health` always has a code-admission shape to report.
-
-The request pool is global FIFO across identities. It is a capacity boundary,
-not tenant fairness: one busy caller can occupy it. Per-tenant fairness needs a
-policy above connecta, and one deployment still serves one tenant even when
-identity rules give its principals different connector views
-([`ethos.md`](../ethos.md)), so a global queue is not pretending to supply
-something it does not.
-
-## Admission before auth
-
-`/mcp` acquires its permit *before* running the auth gate. This looks backwards
-until you price it: authenticating first means an unauthenticated flood buys a
-Clerk network lookup per request, so the cheapest possible attack becomes the
-most expensive request the server can serve. Admitting first means it buys a
-queue slot and a 503.
-
-The permit is released with the response *body*, not when the handler returns.
-A slow client draining a large result still counts as active work, because its
-bytes and its socket still exist. `releaseAdmissionWithResponse` re-wraps the
-response stream to do this, absorbs a rejecting `cancel()` rather than leaking
-an unhandled rejection, and releases exactly once — release is idempotent, and
-`test/request-admission.test.ts` pins both the stream-cancel path and the
-double-release case.
-
-Every other route bypasses the pool entirely. `/health` and the operator
-surface stay responsive while MCP is saturated, which is the whole point: an
-operator diagnosing an overload must not have to queue behind it. `/health`
-names the exempt routes in `admission.reservedRoutes` so the claim is checkable
-from outside.
-
-## Overload, cancellation, shutdown
-
-A full queue or an expired queue deadline answers HTTP 503 with `Retry-After`,
-CORS headers, and a stable JSON-RPC error:
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": null,
-  "error": {
-    "code": -32001,
-    "message": "Server capacity is exhausted. Retry later.",
-    "data": { "code": "server_overloaded", "retryable": true, "retryAfterMs": 1000 }
-  }
-}
-```
-
-`Retry-After` is that hint rounded up to at least one whole second. It is
-advice, not a reservation. Shutdown uses `-32002` / `server_shutting_down` and
-is not retryable. Code-pool overload never reaches this layer: it surfaces as
-an ordinary MCP tool error with `executor_overloaded`, `retryable: true`, and
-the executor's own `retryAfterMs`.
-
-A cancelled queued request is removed immediately and never receives a later
-permit — cancelling and then being admitted would hold capacity for a caller
-that is gone. An admitted request keeps its permit until its body completes,
-errors, or is cancelled.
-
-`connecta.close()` closes both queues before releasing executor resources:
-queued and future MCP work is rejected with `server_shutting_down` while
-admitted work drains. Node's `listen()` calls it on SIGTERM or SIGINT, stops
-accepting connections, drains, and enforces `shutdownTimeoutMs` (10 s default)
-— SIGTERM arrives on every `docker compose up` recreate, and Node's default
-response to it is to die mid-request.
-
-## What admission is not
-
-The Node adapter's `maxBodyBytes` (10 MiB default) is a separate ingress guard.
-It caps the HTTP body while constructing the Web `Request`, which happens
-*before* the portable `/mcp` boundary can run. Admission bounds MCP, auth,
-catalog, and response work; it is not a byte budget for many simultaneous slow
-or near-limit uploads. Hostile public traffic wants an ingress proxy with a
-body-rate limit in front, and `maxBodyBytes` set to the smallest value the
-deployment actually needs.
-
-The rejection warning is rate-limited to one per second, and each line reports
-how many were suppressed since the last one. The `/health` totals count every
-rejection, so the log is a sample and the counters are the record. Queue waits
-log at debug level. Nothing on this path records or exposes request bodies,
-tool arguments, identities, or results.
-
-## Observations
-
-`/health` exposes payload-free snapshots under `admission.requests`,
-`admission.code`, and `admission.downstreamCalls`. The first two carry
-configured bounds, current active and queued counts, cumulative
-admitted/queued/rejected/cancelled/closed totals, and queue-wait count, total,
-and maximum. The request policy is labelled `global-fifo`; downstream policy is
-labelled `connector-partitioned-per-runtime`. An executor that owns its own
-pool and exposes no snapshot reports `{ managedByExecutor: true }`.
-
-With `execute_code({ diagnostics: true })`, a caller sees the same split from
-the inside: `admissionMs` is time spent waiting for a permit and `connectorMs`
-is the admitted attempt.
-
-## Measuring capacity
-
-`npm run load:admission` builds the package, then starts server and generator
-in separate processes over real loopback TCP, warms a 10,000-tool catalog,
-verifies every returned value, and records throughput, p50/p95/p99, server-only
-peak RSS, RSS after forced GC, and live heap after GC. Each matrix cell gets a
-fresh server so an earlier allocator high-water mark cannot contaminate the
-next baseline; the three-round soak deliberately reuses one, because allocator
-high-water retention and a live-object climb look identical in a single run and
-different across three.
-
-`CONNECTA_LOAD_CATALOG_SIZE`, `CONNECTA_LOAD_CONCURRENCY`, and
-`CONNECTA_LOAD_MAX_QUEUE_SIZE` change catalog size, server concurrency, and
-queue depth. The script prints its own numbers; no baseline is checked in,
-deliberately. A laptop matrix is an example capacity profile, not a portable
-SLO, and downstream payload size moves it more than any setting here does — pin
-a runner before enforcing a regression ratio, and measure the connector mix the
-deployment actually runs.
-
-## Tests that enforce this
-
-| Invariant | Suite |
-| --- | --- |
-| FIFO bounds, active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown | `test/executor-admission.test.ts` (Node + Workers) |
-| `/mcp` bounded before auth, stable 503 and `Retry-After`, health and operator responsiveness under saturation, payload-free counters, queued cancellation, shutdown rejection while active work drains, the separate fallback code pool | `test/request-admission.test.ts` |
-| A client disconnect propagating through the Web `Request` into a program's connector call, releasing both permits | `test/node.test.ts` |
-| The `/health` admission payload alongside the drift counts | `test/catalog-drift.test.ts`, `test/server.test.ts` |

package/documentation/revenuecat.md

@@ -1,305 +0,0 @@
-# RevenueCat prebuilt connection
-
-Import `revenuecat()` independently from
-`@zackbart/connecta/providers/revenuecat`. It wraps
-[RevenueCat's hosted MCP server](https://www.revenuecat.com/docs/tools/mcp/setup)
-with OAuth by default, project-scoping guidance that differs by credential
-shape, a task-oriented usage guide, and a vetted safety classification. It adds
-no provider dependency and is not reachable from Connecta's root entry.
-
-```ts
-import { revenuecat } from "@zackbart/connecta/providers/revenuecat";
-
-const subscriptions = revenuecat("revenuecat", {
-  purpose: "Subscription state, entitlements, and revenue across our projects",
-  instructions: "Never grant a promotional entitlement without a support ticket.",
-});
-```
-
-The endpoint is `https://mcp.revenuecat.ai/mcp` over streamable HTTP.
-
-`purpose` is required, and it does more work here than in any other maintained
-connection. RevenueCat's own tools do not report which project a static key
-reaches until you call one, and Connecta runs no credential test at construction
-(P10), so `purpose` is the only place the deployment's intent is written down.
-It opens the guide and it *is* the guide summary, which is the field search
-returns. Project `instructions` are appended to the maintained guide and cannot
-change the connector's safety classification.
-
-## The scoping fact this connection exists to get right
-
-RevenueCat has two credential shapes with two different scopes, and the guide
-you get depends on which one you configured.
-
-**A secret API key is project-wide.** RevenueCat's own words:
-"Secret API keys are project-wide and can be created and revoked by project
-Admins" ([authentication](https://www.revenuecat.com/docs/projects/authentication)).
-`list-projects` "lists all RevenueCat projects accessible with the provided API
-key" — with an `sk_` key that is exactly one project. So a `headers`-auth
-connector reaches one project and nothing outside it. Its title is
-`RevenueCat (single project)` and its guide opens by naming the project the
-operator said the key is for.
-
-**OAuth is account-scoped.** One session reaches every project the account can
-see, and each project-scoped tool takes a `project_id`. Its title is
-`RevenueCat` and its guide opens with the resolution discipline: call
-`list-projects` first, carry the exact `project_id` it returned into every
-project-scoped call, and stop and ask when more than one project fits.
-Connecta does not pick a project, and the connector id, title, and purpose are
-routing hints rather than proof of where a call will land.
-
-The constructor deliberately has no `project` option. Declaring a project that
-Connecta then checked against `list-projects` at construction would be a
-credential test, which P10 forbids — a proxy makes no unasked-for downstream
-call. The operator's stated purpose carries the claim; the agent confirms it
-with `list-projects` on first use.
-
-## Several projects
-
-One key, one project, one connector. A deployment that needs two projects
-declares two connectors, each with its own key and its own id:
-
-```ts
-import { revenuecat } from "@zackbart/connecta/providers/revenuecat";
-
-connectors: [
-  revenuecat("bepresent_ios", {
-    purpose: "Subscription state for the BePresent iOS project",
-    auth: {
-      type: "headers",
-      headers: { Authorization: `Bearer ${env.REVENUECAT_BEPRESENT_KEY}` },
-    },
-  }),
-  revenuecat("biblescroll", {
-    purpose: "Subscription state for the BibleScroll project",
-    auth: {
-      type: "headers",
-      headers: { Authorization: `Bearer ${env.REVENUECAT_BIBLESCROLL_KEY}` },
-    },
-  }),
-]
-```
-
-Neither key has to be a runtime secret. Declare the slot instead and each
-connector's key is pasted, tested, and rotated on the connection UI at `/`:
-
-```ts
-connectors: [
-  revenuecat("bepresent_ios", {
-    purpose: "Subscription state for the BePresent iOS project",
-    auth: { type: "credential", credential: { label: "API v2 secret key" } },
-  }),
-  revenuecat("biblescroll", {
-    purpose: "Subscription state for the BibleScroll project",
-    auth: { type: "credential", credential: { label: "API v2 secret key" } },
-  }),
-]
-```
-
-Two ids, two slots, two single-project catalogs — the `credential` option is
-optional, and omitting it gives the same "API v2 secret key" label. See
-[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
-
-That is config-as-code doing what an account model would otherwise do: one
-credential per connector, each with its own catalog, storage namespace, health,
-and admission counters. The two share a title, because Connecta cannot know
-which project a key opens — so the guide summary is what tells them apart, and
-it is built from `purpose`. Write a purpose that names the project, not one
-that names RevenueCat.
-
-If the deployment genuinely needs to move between projects in one session, use
-OAuth instead and let the agent resolve `project_id`. Do not point a
-project-scoped key's `project_id` argument at a project it cannot reach; the
-call fails at RevenueCat, which is the correct outcome but a wasted round trip.
-
-## Authentication
-
-OAuth is the default and the option RevenueCat recommends: "OAuth provides a
-seamless authentication experience: log in to your RevenueCat account and grant
-access to the MCP server, with no API keys to manage." Each connector instance
-keeps its own flow and tokens in connector-scoped storage.
-
-RevenueCat also accepts an API v2 secret key as a bearer token for headless
-agents:
-
-```ts
-revenuecat("bepresent_ios", {
-  purpose: "Subscription state for the BePresent iOS project",
-  auth: {
-    type: "headers",
-    headers: { Authorization: `Bearer ${env.REVENUECAT_KEY}` },
-  },
-});
-```
-
-Keys are prefixed `sk_`, are issued read-only or write-enabled, and can be
-revoked at any time by a project Admin. RevenueCat's setup guidance is to "use
-a write-enabled key if you plan to create/modify resources"; "a read-only key
-works if you only need to view data". Keep the key in the runtime's secret
-store, never in the deployment file — or declare
-`auth: { type: "credential" }` and let the operator hold it in the vault
-instead, which is the shape the two-project example above uses.
-
-**Connecta does not filter writes for a read-only key.** It has no way to tell
-which kind a key is without spending a call, so every write in the catalog is
-offered, reaches RevenueCat, and fails there in RevenueCat's own words. The
-guide says so, so an agent reads that refusal as "this key cannot write" rather
-than as a bad argument and repairs it by routing to a write-enabled connector
-instead of retrying.
-
-An expired or revoked credential surfaces as `auth_required`, and the guide
-names the `authorize_connector` recovery. A permission gap, a plan restriction,
-or a rejected argument arrives as RevenueCat wrote it and is not an
-authorization problem.
-
-## The ninety-six tools, and what they are classified as
-
-RevenueCat's
-[tool reference](https://www.revenuecat.com/docs/tools/mcp/tools-reference),
-read on **2026-08-30**, documents ninety-six tools. Ninety-five carry an access
-column and are classified here: **51 read-only, 15 additive writes, 29
-destructive writes.**
-
-Reads are every `Read` row, verbatim — the nine project and app reads, the four
-product reads, the entitlement, offering, targeting, paywall, customer, virtual
-currency, chart, webhook, and SDK reads, `get-paywall-ai-task`, and
-`get-refund-request-preferences`.
-
-Writes follow the verb where the verb is honest: `archive-*` and `unarchive-*`
-flip an existing object's active state, `update-*`, `delete-*`, `publish-*`,
-`unpublish-*`, and `detach-*` change or remove something that already exists,
-and a plain `create-*` brings a new object into being beside the old ones.
-`set-product-store-state` is an upsert and `submit-products-to-store` sends
-products to Apple for review, so both are destructive.
-`assign-customer-offering` and `grant-customer-entitlement` change a real
-customer's access, so both are destructive too.
-
-Nine verdicts are not decided by the verb, and each is argued in the source
-beside the row:
-
-| Tool | Verdict | Why |
-| --- | --- | --- |
-| `create-product-prices` | destructive | named `create-`, described "Configure prices for a product". The price set already exists and configuring it replaces what is there. Money-facing and overwriting |
-| `equalize-subscription-prices` | additive | "Fills **missing** App Store subscription territory prices" — by RevenueCat's own word it writes only where nothing is set |
-| `validate-app-credentials` | additive | RevenueCat files it `Write`, so it does not reach the read path, but it leaves the saved credentials alone and only records the outcome of a check |
-| `upload-product-store-state-screenshot` | additive | "Reserves an App Store Connect review screenshot slot" — a new slot appears; nothing existing is replaced |
-| `attach-products-to-entitlement` | additive | attach adds membership and removes nothing; `detach-products-from-entitlement` is the destructive half. Filing both destructive would make the pair read identically in the approval copy a human sees |
-| `attach-products-to-package` | additive | the same argument one level down |
-| `duplicate-paywall` | additive | "Duplicates an existing paywall's current draft" — the original is untouched |
-| `create-paywall-ai` | additive | starts an async task that creates a paywall; every existing one is left alone |
-| `edit-paywall-ai` | destructive | starts an async task that rewrites a draft that already exists |
-
-`create-webhook-integration` deserves a sentence too. No existing integration
-changes, so the verb reads additive — but with filters omitted the new one
-"starts delivering" every customer event in the project to a URL the caller
-typed. Customer data leaving the account makes it destructive on consequence,
-so the approval copy says what is at stake.
-
-**`render-paywall-screenshot` is deliberately unclassified.** RevenueCat's
-reference gives it no access column. The current live server explicitly marks
-it read-only, so that catalog keeps it callable from `execute_code`; if a later
-catalog omits the annotation, it fails closed onto `call_destructive_tool`.
-Connecta preserves the provider's current annotation without inventing a
-release classification from the tool's harmless-sounding name (P5).
-
-That classification fills in downstream silence and otherwise preserves explicit
-annotations. A tool on the read allowlist arriving with `destructiveHint: true`
-or `readOnlyHint: false` keeps exactly what the downstream said and stays behind
-`call_destructive_tool`. A tool on neither maintained list arriving with
-`readOnlyHint: true` keeps that too. Both are the downstream telling you this
-release's allowlist is stale. The one fail-closed exception applies to a name
-this release reviewed and filed destructive: a `grant-customer-entitlement`
-claiming `readOnlyHint: true` is a downstream bug rather than news, and stays on
-the approval path.
-
-The tool list is not a fixed set, and the guide says so. RevenueCat gates parts
-of its catalog by plan, platform, and beta enrollment — paywall AI editing,
-benchmarks, experiments, virtual currencies, and the account-billing tools are
-the usual absentees — so search this connector for what it actually exposes
-rather than assuming a documented tool is here.
-
-**No schemas are vendored.** The manifest ships names and safety verdicts only.
-The live `tools/list` response remains the schema agents receive; Connecta does
-not replace it with a snapshot or require a maintainer credential to validate
-one.
-
-## Rate limits
-
-RevenueCat documents numbers, and this connection still declares no budget.
-
-API v2 meters per minute and **per domain**
-([rate limits](https://www.revenuecat.com/docs/api-v2#tag/Rate-Limit), read
-2026-08-18):
-
-| Domain | Requests per minute |
-| --- | --- |
-| Customer Information | 480 |
-| Virtual Currencies | 480 |
-| Subscription Transactions Refunds | 480 |
-| Audiences | 60 |
-| Project Configuration | 60 |
-| Charts & Metrics | 25 |
-
-A `ConnectorCallAdmissionPolicy` carries exactly one rule, so a connector-wide
-budget has to pick one of those six numbers for all ninety-six tools.
-Transcribing 25 would throttle a customer read loop to a nineteenth of its
-documented allowance; transcribing 480 would leave a chart sweep unprotected.
-Neither is the provider's limit, and both would look like RevenueCat being
-flaky. The metering scope says the same thing again: the limit applies per API
-key for app-level keys and **per developer** for developer-level keys, so an
-OAuth session shares one budget with everything else that developer does, which
-a per-runtime counter cannot approximate in either direction.
-
-So the number stays with the operator who knows the account (P12), and the
-guide states RevenueCat's own limits instead, along with the `429`,
-`Retry-After`, and `backoff_ms` signals to back off on. Supply one like this:
-
-```ts
-revenuecat("revenuecat", {
-  purpose: "Revenue charts and cohort reporting",
-  callAdmission: {
-    rules: [
-      {
-        maxConcurrency: 4,
-        queueTimeoutMs: 5_000,
-        retryAfterMs: 2_000,
-        // The Charts & Metrics ceiling, because this connector is used for
-        // charts. A customer-lookup connector would declare 480.
-        budget: { kind: "rolling-window", maxCalls: 25, windowMs: 60_000 },
-      },
-    ],
-  },
-});
-```
-
-As with every connector policy this is a **best-effort approximation** of the
-provider's limit, not an enforcement of it. Each runtime keeps its own counter,
-so N Worker isolates or Node processes serving one deployment can each admit up
-to the stated rate. Discovery traffic is outside connector call admission and
-still needs restrained use.
-
-## What is not verified
-
-- **The 2026-08-30 live review used a project-scoped catalog.** It proves the
-  additions that catalog serves, including `get-refund-request-preferences`,
-  but cannot prove a globally documented tool was removed. The manifest stays
-  a superset because plan, platform, and credential scope hide tools.
-- **No complete schema set is vendored.** The live review read the new schemas,
-  but its scoped catalog omitted many classified writes. Runtime schemas still
-  come from the server.
-- **Whether `render-paywall-screenshot` mutates anything.** It has no access
-  column, and guessing is exactly what P5 exists to prevent.
-
-`npm run drift:check -- --docs --provider revenuecat` checks the official setup
-page and its 105-row tool reference without a credential. It compares the
-documented names with the release-reviewed classifications. The screenshot
-tool's blank Access column is a manually reviewed exception: the checker
-reports it separately and Connecta keeps it fail-closed. The check reads names,
-not live schemas or machine-interpreted access verdicts.
-
-## Conventions
-
-This connection is audited against
-[the provider conventions](./provider-conventions.md). Its verdict per
-convention is the RevenueCat section of
-[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).

package/documentation/storage-and-credentials.md

@@ -1,201 +0,0 @@
-# Storage and credentials
-
-The core `KVStorage` contract supports `get`, `set`, and `delete`; adapters may
-also implement `list(prefix)`. Core uses storage for connector state, catalogs,
-and result paging. The vault is an explicit independent option:
-
-```ts
-import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
-
-createConnecta({
-  connectors,
-  executor,
-  storage,
-  vault: encryptedCredentialVault(storage, encryptionKey),
-});
-```
-
-`encryptionKey` is a base64 32-byte AES key. The factory implements the
-root-exported `CredentialVault` contract. Core depends on the contract without
-importing the encrypted implementation; deployments may supply their own.
-A replacement must isolate both connector id and optional owner, preserve
-metadata-only reads for the UI, and keep plaintext confined to host credential
-resolution. The built-in AES-GCM implementation binds connector and owner into
-authenticated encryption context. Sharing a backend is not permission to share
-a principal's credentials.
-
-Connectors declare a human-managed `credential` slot in code. The vault exposes
-read access only through that connector's `ctx.credential`. Values, masked
-values, call arguments, and raw errors never enter model recovery or activity.
-Omitting the vault leaves literal deployment-provided secrets and downstream
-OAuth available, but declared vault slots cannot be managed.
-
-Credentials fail at use. Proactive liveness probing remains removed by
-[the 0.9 decision](../ethos.md). Operator-triggered tests and local credential
-shape checks remain. `authorize_connector` returns a human credential handoff
-only when both a vault and the UI are configured. Without either, recovery is
-`unavailable` and explains the missing configuration.
-
-A static bearer may invoke a connector but never mutate its auth as a browser
-user. Interactive users need visibility plus `credentialAdministration` for
-shared auth or `personalConnection` for their own personal auth. Both management
-permissions default to none. Saving, testing, replacing, or removing a value
-never returns it. The vault is read for each call, so a saved replacement takes
-effect without restarting the deployment.
-
-## Storage continuity
-
-This module extraction changes no encrypted record keys, owner partitions, or
-OAuth storage format. Reuse the existing storage and encryption key when
-constructing `encryptedCredentialVault`. Keep connector ids, principal ids, and
-identity namespaces unchanged. Losing the encryption key makes old vault
-values unreadable; changing identity context selects another personal partition.
-
-Removed Connecta-issued token records remain inert in storage. This upgrade
-does not delete them, convert them to another credential, or migrate their
-clients automatically.
-
-## Shared and personal auth
-
-Connector auth defaults to `authScope: "shared"`. Its credential, OAuth state,
-tokens, catalog cache, and connector storage belong to the deployment. Set
-`authScope: "personal"` when every human principal needs a separate downstream
-account:
-
-```ts
-remoteMcp("linear", {
-  url: "https://mcp.linear.app/mcp",
-  authScope: "personal",
-  auth: { type: "oauth" },
-});
-```
-
-Personal connectors disappear from a request that has no stable human
-principal. For a principal that can see one, connecta partitions connector
-storage, encrypted vault records, catalog caches, OAuth generations, and
-observed result shapes under an opaque SHA-256 identity key. Results used by
-`get_result` are partitioned by the authenticated subject, so one authenticated subject cannot page another subject's call.
-
-Literal `auth: { type: "headers" }` cannot be personal because its secret lives
-in deployment code. `remoteMcp()` refuses that combination at construction.
-Use operator-managed credential auth or OAuth instead.
-
-## A remote MCP connector's static credential
-
-`remoteMcp()` accepts a third auth shape beside OAuth and literal headers:
-
-```ts
-remoteMcp("revenuecat_bepresent", {
-  url: "https://mcp.revenuecat.ai/mcp",
-  auth: { type: "credential", credential: { label: "API v2 secret key" } },
-});
-```
-
-The connector, its endpoint, and the credential *slot* stay declared in code;
-only the secret arrives through the connection UI at `/`. That is the same boundary
-`api()` has always had, and the reason a project-wide key no longer has to be a
-Worker secret or an environment variable
-([#439](https://github.com/zackbart/connecta/issues/439)).
-
-`header` defaults to `Authorization` and `scheme` to `Bearer`. `scheme: null`
-sends the stored value verbatim, which is what Linear's personal API keys
-expect. A scheme whose last token is `Basic` declares HTTP Basic credentials, so
-the stored `user:secret` is base64-encoded first — `"Basic"` produces
-`Basic <base64>`, and Mixpanel's documented `"Bearer Basic"` produces
-`Bearer Basic <base64>`. There is one reserved `value` field and no multi-field
-header composition: named `credential.fields` are refused at construction.
-
-A stored value is checked before anything frames it: a line break or other
-control character — what a key pasted across two lines leaves behind — is
-refused as `auth_required` with a message naming the problem and never the
-value. That check exists because the runtime that rejects such a header quotes
-the whole offending value back in its `TypeError`, and that message would
-otherwise reach the agent, the operator page, and the activity log. Behind it,
-any error whose message quotes the credential or the header it became is
-discarded whole and replaced; nothing is masked or truncated, because a
-redaction that keeps part of a secret is still a leak.
-
-An empty slot is not a boot failure and not a silently absent connector. The
-connector is present, its status reads `auth_required`, calls fail with the same
-typed error a missing OAuth grant produces, and `authorize_connector` returns
-a connection UI handoff at `/` when UI and vault are configured. Without either,
-it returns `unavailable` and explains what is missing.
-
-The vault is read before any cached downstream client is trusted, so a rotation
-lands on the next call rather than the next deploy. Connecta compares a SHA-256
-digest of the value the cached client connected with; a different digest closes
-that client and reconnects. The plaintext lives in the connect attempt's local
-scope, never on connector state, never in a log, and never in a status or error
-message. A cleartext `http://` destination warns at construction here exactly as
-it does for literal headers — who owns the secret changed, not what the wire
-carries.
-
-The connection UI Test action connects with the stored value and reports how many
-tools the downstream served. That is the whole honest check for a proxy: which
-account, project, or mode the key reaches is the provider's answer, not
-Connecta's.
-
-## Downstream OAuth
-
-`remoteMcp()` stores dynamic client registration, tokens, PKCE material, state,
-and the pending authorization URL in the connector's storage namespace.
-Registration and token envelopes are bound to the validated authorization
-server `issuer`. An unbound pre-0.9 envelope is upgraded in place on its first
-issuer-aware read, preserving the existing grant.
-
-For personal OAuth, the authorization handoff also stores a 15-minute mapping
-from a SHA-256 digest of `state` to the principal partition. The public callback
-uses that mapping before it verifies state or exchanges the code. Neither the
-browser nor a callback parameter can select a principal. The callback deletes
-the mapping before it exchanges the code, so a second callback cannot replay
-the principal handoff in strongly consistent storage. Cloudflare KV deletion
-is eventually consistent, so handoff consumption there is best-effort across
-PoPs; the downstream authorization code remains single-use. If the callback
-request also carries an interactive identity, Connecta refuses it when that
-principal did not start the flow.
-
-If later discovery resolves a different issuer, Connecta does not send the old
-client identifier or tokens to it. The provider publishes a new generation
-epoch, makes every older credential namespace unreadable, cleans up the retired
-values, and lets the SDK begin registration and authorization again. The same
-epoch fence prevents an older isolate or late token exchange from resurrecting
-the retired grant.
-
-The OAuth callback verifies the one-shot `state` first, then hands the complete
-query string—including RFC 9207 `iss`—to the SDK transport. One-shot state,
-verifier, and pending URL are cleared only after a successful exchange.
-
-Within one `remoteMcp()` runtime, one request scope owns refresh-token
-redemption for an OAuth generation. Concurrent scopes wait for the owner's
-token save or bounded failure, then either read storage again or receive that
-failure. A scope that had already read the retired refresh token reuses the
-newly stored rotating token locally instead of sending the retired value
-upstream. Force reauthorization retires the old generation's gate, and a
-failed flow releases ownership for a later attempt. The coordinator retains
-only a completion signal and one temporary owner-abort listener until that
-exact flight settles, never the token response or downstream transport. A
-follower may stop waiting when its own request is cancelled without cancelling
-the owner or poisoning the generation for later callers. If the owner's
-credential mutation fails, joined callers receive that same bounded failure
-instead of waking to redeem the unchanged token; a later independent call may
-retry. Non-success and malformed token responses settle current waiters at the
-fetch boundary, before any later authorization callback can itself fail.
-Cancelling the owner aborts its fetch and fails current joiners rather than
-promoting one: once a request reaches the authorization server, repeating its
-old refresh token is not known to be safe. If that cancellation lands while
-the valid response's credential write is already running, a same-generation
-attempt receives `temporarily_unavailable` until the exact write succeeds or
-fails. This mutation marker contains no retained promise; force
-reauthorization removes it when the old generation becomes unreadable.
-An additional opaque success identity lets a request recognize a refresh that
-completed after its issuer-aware token read even when the authorization server
-returned byte-identical credentials. The identity is generation-scoped and is
-discarded with the retired generation. Every authoritative storage-generation
-read also retires coordinator state from other epochs, so an externally
-advanced generation cannot be overwritten in runtime state by late old work.
-
-This guarantee is runtime-local. `KVStorage` has no atomic lock or
-compare-and-set operation, so separate processes or Worker isolates can still
-redeem the same refresh token concurrently. Generation envelopes continue to
-fence their writes, but Connecta does not claim cross-isolate exactly-once
-refresh.