@zackbart/connecta 0.29.0 → 0.31.0

package/documentation/architecture.md

@@ -9,6 +9,26 @@ first; this guide explains the shape and where each subsystem lives. The surface
 [meta-tools](./meta-tools.md), [code mode](./code-mode.md), and
 [inbound auth](./auth.md).
 
+## Task routes
+
+[Agent index](./README.md) routes endpoint use, deployment, integration, and
+repository maintenance. Read this guide when changing the core or checking an
+implementation boundary. Use these sections for the affected subsystem.
+
+| Change or question                      | Sections                                                                                                                                      |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Request handling, transport, cleanup    | [Two lifetimes](#the-two-lifetimes), [request lifecycle](#request-lifecycle), [admission](#admission-in-two-places)                           |
+| Discovery, invocation, classification   | [Layers below meta-tools](#layers-below-the-meta-tools), [providers and classification](#providers-and-reviewed-classification)               |
+| Storage, credentials, catalogs, paging  | [Storage and connectors](#storage-credentials-and-connectors), [errors and records](#errors-and-records)                                      |
+| Config validation and optional features | [Configuration](#configuration), [modules](#optional-deployment-modules), [operator contract](./operator-ui.md#operator-data-contract)        |
+| Imports, executors, or Effect           | [Purity](#import-graph-purity), [Effect](#effect-inside), [sharp edges](#sharp-edges)                                                         |
+| Find code and deployment evidence       | [Source map](#where-else-to-look), [sharp edges](#sharp-edges), [repository policy](https://github.com/zackbart/connecta/blob/main/AGENTS.md) |
+
+Source paths and test names in each section identify its implementation and
+regression evidence. Recorded production probes and bundle measurements are
+historical observations tied to their stated date or version, not current
+benchmarks or proof that planned replacements have shipped.
+
 ## The two lifetimes
 
 Almost every bug in this codebase is a lifetime mistake, so the split is worth
@@ -207,6 +227,13 @@ same credential resolution, and the same fail-closed read-only check.
 `test/execute.test.ts` asserts the parity directly, because a sandbox path that
 quietly diverges is how generated code would mint a capability.
 
+Program result paging shares `meta-tools.ts`'s direct-call stash envelope and
+reader. `program-result.ts` owns executor-independent byte limits;
+`execute.ts` issues bounded transfer cursors, and `guest-runtime.ts` reconstructs
+values through provider preludes. Cursors hold only an ID and offset for the
+current run. Result bytes, expiry, authority and capacity charges stay in the
+existing storage and ledger; no executor-specific store or storage key is added.
+
 ## Admission, in two places
 
 Request admission (`src/executor-admission.ts`, applied in `src/routes/mcp.ts`)
@@ -324,11 +351,20 @@ marker refuses stale copies afterward.
 
 `KVStorage` is `get`/`set`/`delete`/`list(prefix)`/`compareAndSet`, all
 required, and `createConnecta` refuses storage missing one (INV-11).
+Adapters must also declare `capabilities: { absoluteExpiry: true }`.
+Construction rejects missing or false capability declarations with an error
+naming `capabilities.absoluteExpiry`. The memory, SQLite, and D1 adapters carry
+this marker. Custom adapters may declare it only after implementing absolute
+expiry on both writes; a legacy `ttlSeconds`-only adapter is rejected by the
+published types and at runtime.
 `compareAndSet(key, expected, next, options?)` is an atomic claim: `null` means
 absent (expired counts) on the way in and delete on the way out, and a
-successful write takes the same optional `ttlSeconds` as `set`. SQL TTLs are
-created and checked by the database clock inside each statement, so isolate
-clock skew cannot expire a live holder's record. Each SQL claim
+successful write takes the same expiry options as `set`. Relative `ttlSeconds`
+is created and checked by the database clock inside each statement, so isolate
+clock skew cannot expire a live holder's record. Absolute `expiresAtMs` is a
+safe-integer epoch-millisecond deadline stored verbatim and checked against the
+storage clock. Supply at most one option. Custom adapters must implement both;
+a delayed absolute-expiry write must not restart a relative TTL at commit time. Each SQL claim
 is one statement, which SQLite executes atomically and D1 serializes on its
 primary. Everything that must claim a key exactly once relies on it with no
 read-then-write fallback: access-token issuance and
@@ -350,7 +386,8 @@ State-file import validates all keys before writing. The `connecta_kv` table
 keeps its existing TEXT keys, including compatibility with the 0.28 schema.
 Storage writes no log lines. A refused import names the file and an entry's
 position, never a key, a value, or the JSON parser's account, which quotes
-the file (INV-6).
+the file (INV-6). Database failures report only a fixed import step and an
+entry's position, including errors raised by target-database triggers.
 
 Remote MCP catalogs use the SDK `ResponseCacheStore` over this same SQL KV.
 The `response-cache:v1:` family binds connector id, a hash of its configured
@@ -433,12 +470,53 @@ Result paging stores each oversized result for 15 minutes, chunked so a page
 reads only what it covers. Its bounds (`results.maxStashBytes`,
 `results.maxStashEntries`) are the deployment's, not an isolate's: every charge
 is a row in one ledger record, booked by compare-and-set before any chunk is
-written, so isolates and processes sharing the store see one count. A lost swap
-backs off and re-reads; only a full ledger refuses. Each chunk's TTL is what
-remains of its charge's deadline, so no chunk outlives its charge. A full
-stash returns the successful call's preview and a paging-unavailable notice
-rather than a result id. The shared storage cases live in
-`test/storage-contract.ts` and `test/sql-storage-contract.ts`.
+written, so isolates and processes sharing the store see one count. Every
+reservation starts with a finite deadline of booking time plus the 30-second
+write budget plus the chunk TTL, normally 15 minutes. Pending writes retain
+that charge until its deadline. Booking retries recognize their own reservation
+ID and reuse its stored deadline, including a final read after an ambiguous
+last CAS. A lost swap or transient storage error backs off and re-reads, up to
+32 attempts. A full ledger or unconfirmed exhausted booking returns no result id.
+
+Caller time only nominates charges for pruning. Before discarding one, the
+ledger writes a probe with that charge's absolute deadline and reads it back.
+Only an absent probe proves storage has passed the deadline; a live probe keeps
+the charge, and a storage error cannot free capacity. Each deadline has its own
+key in `stashExpiryKeys`, so concurrent probes cannot overwrite a different
+deadline's proof. Probes expire at the deadline they check and need no cleanup.
+This uses the same absolute-expiry contract on memory, SQLite and D1 without a
+storage API or schema change. An ahead caller clock cannot admit a second stash
+while the first remains readable.
+
+The whole chunk-write phase has a 30-second timeout measured from booking, with
+a clock check before and after each write. Trailing chunks precede the header;
+failure or timeout returns no result id and stops the write loop. Chunks use an
+absolute expiry at booking time plus their TTL, so slow writes shorten the
+remaining paging window. Storage promises cannot guarantee cancellation of an
+already-dispatched database operation, and a rejected client response does not
+prove that operation cannot commit later. Even a commit after timeout or process
+interruption keeps that absolute expiry, rather than starting another TTL.
+
+Settlement and release only shorten or remove a reservation. Successful writes
+attempt to shorten the charge to the fixed chunk expiry. Cleanup releases it
+only after all deletions succeed and every dispatched write returned confirmed
+success. Failed cleanup or exhausted release attempts finite settlement when
+no write is unconfirmed. A rejected or timed-out write keeps its original
+reservation because it may still commit after deletion. Each completion path
+has one 15-second budget covering deletion, release, fallback settlement, and
+their storage waits and retries. Successful-write settlement has the same
+15-second budget. A stalled operation stops being awaited when the budget
+expires; its late response starts no further I/O, and no background cleanup
+fiber is started. The caller returns its write outcome even if these
+optimizations cannot finish. Ledger updates retry within the same 32-attempt
+budget. If they fail, time out, crash, or exhaust,
+capacity may be over-held until the booked deadline, at most 15 minutes and
+30 seconds for the normal TTL. The ledger row itself has an absolute expiry at
+its latest live reservation deadline. There are no completion receipts or
+separate recovery rows; expiry probes carry no completion state. Expired data reads as absent and normal storage sweeps
+reclaim the physical rows. A full stash returns the successful call's preview
+and a paging-unavailable notice rather than a result id. Shared failure cases
+live in `test/stash-charge-contract.ts`, exercised by the memory and SQL suites.
 
 `src/credentials.ts` is the AES-GCM vault behind the root-exported
 `CredentialVault` contract, selected through the `vault` slot. It binds connector
@@ -488,6 +566,14 @@ credentials produce one payload-free warning per connector; use secrets of
 at least eight characters. Encoded and JSON-escaped echoes of registered
 credentials follow the same redaction rules. Connecta's own messages
 never quote a credential.
+Core uncertainty and retry envelopes share one schema-filtered argument snapshot,
+captured before dispatch and byte budgeting. `writeOnly: true` omits values of
+every length, including nested properties, array items and prefixes, local
+`$ref`/`$defs`, and `allOf`. `oneOf`/`anyOf` must agree on sensitivity. Unresolved
+references, sensitive dynamic-property schemas or other unsupported applicators,
+and traversal limits withhold the entire echo. A private array element withholds
+its containing array to preserve indices. `argsRedacted: true` marks a partial
+or withheld echo as reconciliation context; retries require the original arguments.
 OAuth discovery and consent URLs are refused as a typed, non-retryable failure
 when they contain a known credential, before persistence or reuse. This guard
 checks the request's sent credentials and the current grant's credentials,
@@ -560,7 +646,7 @@ only: an array or a class instance there is refused by path, unread. String
 maps (static `headers`, `api()`'s `authorizationParams` and
 `tokenRequestHeaders`) are copied the same way and each value must be a
 string. A discriminated union (`remoteMcp()`'s `auth.type`,
-a provider's `surface`) with a missing or unrecognized discriminant throws
+a provider's `auth.type`) with a missing or unrecognized discriminant throws
 with the valid values. Only plain data is copied. Connectors, modules,
 executors, storage, loggers, handlers, and schemas are opaque and never
 entered. An `api()` tool carries its handler, so it is checked in place (own
@@ -604,8 +690,29 @@ switched by the environment, and keep their entries under 30 lines.
 
 ### Providers and reviewed classification
 
+Infisical separates explicit value reads from identifier results. `get_secret`
+and `list_secrets` with `includeValues: true` return secret values and comments.
+All other results, including imported secrets and pending approvals, allow only
+checked IDs, keys, environment and tag slugs, paths, timestamps, positive versions
+and enum fields. They omit project slugs derived from free-text names, comments,
+descriptions, free-form names, reminder notes and arbitrary nested objects.
+`metadataOmitted: true` reports withheld or unavailable metadata.
+This assumes an honest server and protects against careless human entry in free
+text. A malicious server encoding values into valid identifiers is out of scope.
+Known, accepted residual risk: environment slugs are returned as required
+routing identifiers. Infisical's UI derives them from environment names by
+default, so secrets entered in those names can appear in returned slugs.
+Operators must not put secrets in environment names or slugs. Secrets placed in
+identifiers or key names are out of scope.
+Write input schemas mark secret values, secret comments and folder descriptions
+as `writeOnly`, so recovery argument echoes omit them without changing dispatch.
+Submitted values never join the request's sent-credential set, preserving later
+program arguments. Client credentials and tokens still join that set on every
+call. The [provider guide](https://github.com/zackbart/connecta/blob/main/src/providers/infisical/SKILL.md) owns routing and
+value-read conventions.
+
 A maintained provider is one `defineProvider()` call (`src/provider.ts`): a
-name, title, kind (`"mcp"`, `"api"`, or `"composed"`), a maintained skill, an
+name, title, kind (`"mcp"`, `"api"`, `"composed"`, or `"dual"`), a maintained skill, an
 optional reviewed classification, a closed `options` shape declared with
 `optionsOf<O>()`, and a synchronous `create`. The root exports the option-shape
 combinators and `PROVIDER_COMMON` so provider authors use the same validation
@@ -621,12 +728,124 @@ live in their own folders. The eight hosted implementations, including the
 MCP branches of Notion, Vercel, and Cloudflare, use reviewed presets over
 `remoteMcp({ classify })`. The eleven API-only factories retain an internal
 adapter to the same definition and description-stamping path. GitHub composes hosted tools with a scope-enforced REST complement.
-Notion, Vercel and Cloudflare default to hosted MCP and select explicit REST
-complements with `surface: "api"`. Configure both under distinct connector ids
-with independent credentials when both are needed. Notion preserves its
-internal-integration identity under `integration_*` names; Vercel and Cloudflare
-retain documented REST gaps rather than duplicate hosted operations. See the
-[provider migration guide](./provider-migration-0.29.md).
+A `"dual"` provider lets `auth` select the implementation
+([decision 0005](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)):
+`variants(["auth", "type"], …)` closes each case's options, and
+`byAuth()` in `src/providers/_shared/rest/dispatch.ts` sends OAuth to
+`hostedOAuth()` (`remoteMcp()`, OAuth only, the reviewed classification) and a
+key to Connecta's REST connector. Stripe, Notion, Cloudflare, and Vercel are dual; `auth` is required.
+The REST connector (`src/providers/_shared/rest/`) serves
+`<vendor>_api_search`, `_api_details`, `_api_read`, and `_api_write` over an
+`OperationIndex` that `npm run providers:spec` compiles offline from the
+provider's pinned `openapi.source.json` into `openapi.generated.ts`.
+Each call is matched to an operation and checked against its parameters before
+transport; `_api_read` admits GET and the vendor's reviewed read-only POSTs in
+its handler, since classification is per tool name. Vendors configure only a
+transport, failure mapper, scope, framing, cursor extraction, a reviewed
+value-safety table (required; see below), argument-dependent refusals, and an
+idempotency header, plus optional hooks: `path` (fill default ids before
+matching), `admit` (an awaited check in `callRest` every tool passes, such as
+Cloudflare's account and zone pin), `result` (unwrap a vendor envelope;
+redaction runs after it and before cursors and `select`), a reviewed
+request-header allowlist, text bodies, and index `slashParams` that admit an
+encoded `/` in a final key segment (`test/rest-connector.test.ts`).
+Large documents opt into generator options that drop restated operation ids
+and plain path parameters and cap one operation's details (`opBudget`).
+`check:providers-generated` checks each index header against its source record
+offline; `providers:check` reports a pin that differs from the live document.
+No maintained provider selects an implementation with `surface` any more. See
+the
+[provider auth migration](./provider-auth-migration.md). Notion's token
+connector keeps its `integration_*` projections and authoring helpers beside
+the generic REST tools.
+
+#### Value safety for REST vendors
+
+The bar ([decision 0005](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)):
+no REST tool response, success or error, returns a credential that grants
+access to the vendor or a third party, or a stored secret value, unless a
+reviewed named tool exists to return it. The threat model is Infisical's
+above: an honest server, with secrets people type into free text out of
+scope. Field-by-field redaction over a whole vendor API does not converge, so
+every vendor ships one reviewed table through one mechanism
+(`src/providers/_shared/rest/value-safety.ts`):
+
+1. **Candidates from the pinned spec.** `scripts/value-safety.mjs` flags every
+   operation whose success response names or describes a credential, keyed
+   value, header, environment, or binding container, or whose path, id,
+   summary, or description names a secret family (tokens, secrets, keys,
+   signing, webhooks, drains, transfer, claim, and invite codes). It is the
+   union of the detectors Cloudflare and Vercel shipped first, and
+   deliberately over-inclusive. `providers:spec` writes
+   `value-safety.candidates.json` beside the index when the source record sets
+   `options.valueSafety` (vendor `operationWords`; Stripe's `expansions: false`
+   skips id-or-object expansions, which are their own operations' candidates),
+   stamped with the pinned digest, the detector format, and its options. The
+   file is test evidence and never ships.
+2. **One reviewed verdict per candidate**, in the vendor's `value-safety.ts`:
+   `refuse` (the generic tools refuse it before transport, naming the
+   operation and the reason), `redact` (reviewed field paths), or `safe`, each
+   with a reason. Paths are dot paths into the data a tool returns: a list on
+   the way is traversed, `[]` and `{}`/`*` address list items and map values,
+   `@keys` replaces secret map keys, `[?env]`, `[?credential]`, and
+   `[?header]` filter list items, `url:` sanitizes a URL, and `origin:` (or a
+   `#url` suffix) keeps only scheme and host. `keep` names reviewed metadata
+   the heuristic leaves (children are still checked). A vendor whose objects
+   repeat across operations (Stripe) reviews a field once in `fields`,
+   `redact` or `keep`, wherever it appears, and states `resources`: rules
+   keyed on the object's type discriminator (Stripe's `object`) that apply to
+   every such object wherever a response embeds it (an expansion, a list, an
+   event's `data.object` and its `previous_attributes`). A resource rule can
+   return a reviewed payer-facing URL verbatim only while a declarative guest
+   condition holds (deny by default: a Checkout page only when every field
+   that can bind the session to a Customer, an Account, or saved payment
+   methods is empty and the session only takes a payment) and withhold it
+   otherwise. `providers:spec` derives the binding fields from the pinned
+   schema, and the harness fails until the condition lists each one. Argument-dependent refusals (Stripe expansions,
+   Vercel `decrypt`) stay in the vendor's `refuse` hook.
+3. **Redaction on every success body**, in `callRest` after `result` and
+   before cursors and `select`, so named tools, HEAD data, and uploads pass
+   through it too: the operation's reviewed paths, then the key-name
+   heuristic as defense in depth. The heuristic is the union of the former
+   vendor engines: a credential word anywhere in a non-metadata name removes
+   the value whole, a credential suffix removes the strings below it,
+   labelled or typed secret records lose their value, environment containers
+   lose their values, header, cookie, and query rules lose theirs, external
+   destinations keep their origin, and every URL loses userinfo and
+   credential-named query parameters or fragments. Exemptions are never
+   shared; each vendor states its own.
+4. **Errors.** A reviewed operation, or an unreviewed one whose request
+   accepts a credential-named field, answers failures with the vendor's codes
+   and status but not its text, unless its verdict is wrapped in
+   `vendorErrors()` because a review found its errors cannot echo a stored
+   secret. Credentials Connecta sent are always removed by the sent-secrets
+   matcher.
+
+`providers:spec` (run under tsx) also checks the table against the pinned
+spec: every `redact` path and `keep` must name something the operation's
+response schema can return (through `options.valueSafety.dataRoot` for an
+envelope such as Cloudflare's `result`), and every resource rule path
+something the resource's schema can return. It stamps the paths that resolve
+into the candidates file and fails on the rest, unless
+`value-safety.absent.json` acknowledges them (shared verdicts applied to
+operations whose schema lacks a path, or fields a schema leaves undeclared;
+such paths still apply at runtime).
+
+`test/fixtures/value-safety.ts` is the shared harness each vendor's
+`value-safety.node.test.ts` runs; `reviewProblems` is pure, and
+`test/value-safety-harness.node.test.ts` proves wrong paths fail it. It fails
+on candidates from another pin, format, or option set; an unreviewed
+candidate; a verdict for an operation the index lacks; a table path the stamp
+lacks (unresolved, or edited since `providers:spec`); a flagged field no path,
+keep, field review, or scope map covers; a flagged field, built in the shape
+the pinned schema gives it, that survives redaction or that no redact path
+reaches; a keep that exempts anything below it or a vendor-wide keep of a
+credential name; a redact path or resource rule that leaves its value at the
+top level, in a list, an expansion, or an event; a refusal that reaches
+transport; a reviewed operation that echoes vendor error text; and a moved
+verdict count.
+`RestVendor.valueSafety` is required, so a new REST vendor cannot ship without
+a table.
 
 `remoteMcp({ classify })` is the public way to declare what a downstream's
 tools do: `{ tools: { name: "read" | "write" | "destructive" | { verdict,
@@ -1010,82 +1229,7 @@ compiling and configuring the real thing.
 
 ## Operator data contract
 
-`GET /ui/api/config`, owned by `operatorUi()`, returns `OperatorUiContract`
-from `connecta/ui`. `src/operator-ui/contract.ts` is also the browser's type
-source. The response has `schemaVersion: 1`, `config`, `configSources`, `live`, and `you`.
-`config` is the construction-time `describeConfig()` snapshot, filtered to
-visible connectors, granted tools, classification overrides, and admitted
-pools. Pool tools are the intersection with the caller's identity grants.
-`configSources` labels each serialized leaf as `default` or `config`, based on
-option presence rather than equality with the default. Factory descriptions carry
-relative `optionSources` paths so resolved module and transport defaults retain
-their provenance. The snapshot copies only resolved values; the UI consumes
-these presence facts separately. Its paths use connector
-ids and pool names and are filtered after disclosure; hidden values leave no
-provenance keys. It contains no source code or credential material.
-Every response is private, `no-store` JSON. Only GET is allowed, with the
-same auth gate and identity partition as `/ui/data` and `/ui/connectors/:id`.
-
-`live.connectors` carries status and problem codes, complete registry tools
-with their final read/write classification, catalog age in milliseconds, and
-last-call time/outcome. Catalog descriptions and schemas are allowed for an
-authenticated reader; grammar-failing names and addresses become `<withheld>`.
-`auth.registrationPath` reports the selected downstream OAuth client mechanism when known.
-Status prose, error text, credential values or suffixes, arguments, results,
-and code are excluded. Static and unobserved catalogs have a null age;
-persisted catalogs retain their original fetch time. Probes run with bounded
-concurrency and the configured probe deadline, and release their scopes.
-
-Last-call lookup requires the existing activity permission and read gate. It
-scans up to 1,000 recent rows, filters connector/tool grants, and restricts
-personal connectors to the caller's activity identity. Each retained fact
-copies a validated timestamp and outcome only. A null call means unknown or
-absent in that window, not proof of no calls. `live.activity` distinguishes
-available, unconfigured, forbidden, and unavailable history. `you` names no
-identity or auth material; it reports grants, root and admitted-pool trust,
-and effective activity, token, and per-connector auth permissions.
-
-`connecta doctor --config` fetches this authenticated contract and prints only
-`config` as indented JSON. It requires the UI module and the existing doctor
-authentication environment variables; it runs no diagnostic program, follows
-no redirects, and prints no raw HTTP failure body.
-
-The operator shell uses React, TanStack Router/Query/Table, Radix, cmdk and
-Tailwind v4. Inter, CSS, JavaScript and dependency notices are hashed assets
-under `/ui/assets/*`, served identically with immutable cache headers on Node
-and Workers. HTML contains only mount points and escaped inert configuration;
-it remains uncached. `generated.ts` is ignored and generated before build and
-test; `check:operator-ui` detects stale assets and shared page styles. The UI
-stays behind `./ui`, outside the root import graph. The identity-fenced store
-owns authenticated reads and existing mutations. Overview, Connectors, connector
-detail, Tools, Access and Config consume the typed contract. Activity retains
-its authenticated data routes. Connector detail tabs live
-in the URL hash; Activity filters live in the query string and apply to loaded
-history. Both `/ui/activity` and `/ui/api/activity` require Activity access and
-pass the optional activity `readGate`. Interactive operators and machine callers
-admitted by `identity.activityAccess` share the same history disclosure rules.
-Connector/tool grants and grants for the recorded pool filter each event. Shared
-connector history can include other principals' events, with recorded request
-IDs, validated client name/version and package version, and actor kind, ID and
-namespace. Interactive reads may also add directory actor labels; machine reads
-never add them. Personal connector history is owner-only: the event must have a
-checked `principal` actor basis and actor ID/namespace matching the reader's
-admitted principal. Rows without a provable personal owner are withheld. Activity
-carries no arguments, results, code or raw downstream errors. The last-call
-overlay uses the same event filter but returns only timestamp and outcome.
-Calls group only by recorded request ids, with missing ids shown as
-separate calls. Classification and result size are shown only when recorded. The verdict is
-captured after registry resolution, and result size counts UTF-8 bytes of the
-downstream value before paging or truncation. Nullable SQL columns preserve old
-rows. Catalog changes use the same paging envelope with `kind: "catalog_drift"`,
-`source: "catalog_refresh"` and a checked `catalog_changed` fact containing only
-added, removed and changed tool counts. The first complete catalog is a baseline;
-one refresh-publication hook emits each later change. It includes the request's
-id and typed actor when available, otherwise a fresh id and system actor. No
-names, descriptions or schemas enter the event. Private catalog changes require
-a matching principal owner even when the connector uses shared auth. Empty credential declarations
-report `credential_required` before running a connector status or catalog probe.
-The Access adapter reports inbound provider kinds, admitted pools, grants, trust
-and endpoint setup; token controls retain their existing permission gate.
-Configuration remains in deployment code. The UI mutates only credentials,
-OAuth connections and client tokens through the existing routes.
+The contract now lives in [Operator UI](./operator-ui.md#operator-data-contract),
+including configuration provenance, live facts, activity disclosure, doctor,
+and the browser implementation. [Optional deployment modules](#optional-deployment-modules)
+keeps the module composition and request-lifetime rules here.

package/documentation/auth.md

@@ -1,5 +1,28 @@
 # Inbound auth
 
+## Task routes
+
+[Agent index](./README.md) distinguishes endpoint operation from deployment
+and package maintenance. This guide owns identity, grants, and downstream
+credential contracts; use [deployment setup](./deploying.md) for runnable steps.
+
+| Task                                                  | Sections                                                                                                                                                                      |
+| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Connect a machine or migrate an old client            | [Managed tokens](#managed-client-tokens-and-upgrading-from-v023), [static bearer migration](#migrating-static-bearer-clients)                                                 |
+| Configure caller visibility, trust, or auth ownership | [Principals and operators](#principals-visibility-and-operators), [pools](#pools), [shared and personal auth](#shared-and-personal-auth)                                      |
+| Set up human sign-in                                  | [Access on Workers](#cloudflare-access-on-workers), [Clerk tokens and sessions](#clerk-oauth-tokens-and-operator-sessions), [management](#human-authentication-management)    |
+| Enable credential or connection controls              | [Management permissions](#management-permissions), [start/restart/disconnect](#starting-restarting-and-disconnecting)                                                         |
+| Diagnose consent or token refresh                     | [State at rest](#downstream-oauth-state-at-rest), [callbacks](#consents-and-callbacks), [refresh failures](#refresh-failures), [safe errors](#what-a-servers-errors-may-say)  |
+| Configure a downstream OAuth client or HTTP handler   | [Client registration](#downstream-oauth-client-registration), [api() OAuth](#downstream-oauth-on-api), [request-local bearer tokens](#request-local-downstream-bearer-tokens) |
+| Review browser or downstream URL boundaries           | [Origins](#origins), [advertised URLs](#urls-a-downstream-advertises), [one server per grant](#one-server-per-grant)                                                          |
+
+[Credential recognition and admission](#credential-recognition-and-admission)
+defines refusal precedence.
+[Source and tests](#source-and-tests) points to the implementation. Migration
+sections describe upgrade procedures, not additional auth modes to enable.
+
+## Credential recognition and admission
+
 Inbound auth decides who may reach the MCP endpoint. People use `clerkAuth`
 from `@zackbart/connecta/auth/clerk` or `cloudflareAccessAuth` from
 `/auth/cloudflare-access`. Machines use `accessTokens(storage)` from
@@ -369,7 +392,14 @@ longer live; one left behind cannot complete and expires with its link.
 | `DELETE /ui/oauth/<id>`                  | Disconnects and invalidates the cached catalog, even if the browser leaves.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
 `authorize_connector` issues the same browser link, with `force` carried in the
-signed handoff. Status reads never call `startAuth` and never expose the
+signed handoff. On hosts without URL elicitation, direct and program auth
+failures and search/describe catalog failures include the same authorization
+handoff. The admitted registry and management permission govern issuance.
+Each call or program run shares at most one handoff per connector; errors never
+request a forced restart. Signed links retain their fifteen-minute expiry,
+initiating-user and owner binding, origin check, and single-use browser nonce.
+Minting a link stores no nonce and starts no consent. When an auth error includes
+a handoff, give it to the user or operator. Status reads never call `startAuth` and never expose the
 provider's consent URL. A UI start answers `{ state: "auth_required",
 authorizationUrl }`, where the URL belongs to connecta. Continue hands back the
 latest consent only while it is unclaimed, in the live epoch, written within
@@ -574,7 +604,7 @@ withheld error keeps its original classification, and no connector error keeps
 a runtime, stream, or parser error as `cause`.
 
 The JSON-RPC and 4xx exception preserves diagnostics agents need to correct
-their arguments. Core redacts credentials used by that call before these
+their arguments. Core redacts credentials and submitted `writeOnly` argument values before these
 messages, nested causes/data, or tool results reach an agent or guest program.
 The memory-only set covers credential-slot values, static auth headers,
 outbound bearer tokens, and their JSON-escaped, URL-encoded, base64 and
@@ -586,6 +616,85 @@ maintained-provider transports track the final request too. Credential-slot
 reads cover values sent in headers, queries, or bodies. Echoed sensitive
 header lines are also withheld.
 
+Submitted values under JSON Schema `writeOnly: true` join this memory-only
+request set, including nested objects, arrays, and local references. Strings
+and numbers register with the same raw, URL, form, base64, and base64url forms
+as credentials; booleans and null carry no text. Property names inside a
+private object subtree are private values too; array indices are not. Output
+redaction protects the union of private fields across `oneOf`/`anyOf`
+alternatives. If a schema declares private fields but its sensitivity cannot
+be resolved, all submitted values are treated as private. Schemas without a
+`writeOnly` annotation skip this work. Private values never enter stored
+catalogs or operator records. The program's outgoing-argument filter and
+catalog caches use credentials alone, so later calls receive the original
+submitted data and cached catalogs never depend on one request's arguments.
+
+Payload rules apply where downstream or guest data enters: downstream results
+and errors, resource reads, connector usage guides and downstream skill files,
+program returns, logs, and emits, and relayed input prompts. JSON objects,
+arrays, and string literals are parsed and walked, whether they are wire text
+or a string inside a result, so nested JSON strings are decoded too. Every
+decoded string leaf and property name is scanned, and a number, boolean, or
+null whose canonical text matches becomes the string `[redacted]`, so the JSON
+stays valid. Text is reserialized
+only when something changed; otherwise its original bytes remain. The
+serialized bytes are then scanned raw, and a literal the walk cannot see, such
+as one spanning tokens, withholds the whole text. Other text is scanned raw and
+through one more layer of JSON string escapes at a time while the last layer
+could still hold an escape. A string is decoded through at most eight layers in
+total, counting the nested JSON strings it was parsed from; text that would
+need more is withheld. Every match is mapped back to the original text,
+overlapping and adjacent spans merge, and each merged span is replaced once, so
+one match can never split another. A span wholly inside an existing
+`[redacted]` placeholder is that placeholder; a private value that contains the
+placeholder text is still redacted. Connecta and MCP envelope field names, tag
+values such as a content `type` or result `format`, and typed facts such as
+`isError` and `retryable` are copied unchanged. The agent boundary around
+Connecta's own envelopes repeats credential and literal private-value
+replacement without the short-value rules, so envelope identifiers, counts, and
+JSON-RPC ids are never rewritten.
+
+Empty private strings are exempt because they contain nothing to leak. A
+non-empty private value shorter than eight characters redacts a structured
+string leaf, property name, or scalar only when it equals the value or a
+supported encoded form, including after JSON unescaping. A longer structured
+field that merely contains it, such as `prod-db` for `prod`, is kept: this
+documented tradeoff keeps identifiers and approval state usable. Prose that
+contains a short value or encoded form anywhere is withheld as `[redacted]`:
+plain-text results, `message`, `error`, `text`, `logs`, and `stack` strings,
+string program results, and relayed prompts. Typed error classification,
+retryability, retry delay, and write-outcome accounting remain. Private values
+of at least eight characters are replaced wherever they occur.
+
+Matching runs one Aho-Corasick automaton over every registered form, so each
+scanned code unit costs amortized constant work however many values are
+registered. The automaton indexes the first 256 code units of each form,
+credentials first, and at most 512 Ki indexed units for every registration
+together, so a long credential or private value costs no more automaton memory
+than its prefix. Where a longer form's prefix matches, the scanned view's
+rolling hash confirms the rest once its last unit arrives; equal text always
+confirms, so a hash collision could only redact more. Forms that share a prefix
+and a length share each confirmation, and overlapping prefix occurrences in
+self-similar text share one run of confirmations, so periodic text stays exact.
+Each confirmation is charged to the call's work budget before it is queued, and
+one scanned view holds at most 16 Ki runs; a view that needs more is withheld.
+Submitted values register at most 512 KiB of encoded forms and 4,096
+argument nodes. A form that does not fit either limit withholds every string
+at least as long as that form; an argument tree that cannot be walked withholds
+all downstream text.
+
+One redaction call has one work budget across parsing and every scanned view:
+64 Mi units with private values, and 1 Gi for credentials alone, which keeps
+multi-MiB document and skill-file reads. Work that does not fit the remaining
+budget withholds its field, so smaller identifiers can still be checked. The
+same call walks structured values iteratively, at most 512 containers deep and
+1 Mi entries in total, and copies only containers on a path that changed. A
+container's entries are counted before it is walked. One that does not fit the
+remaining entries is scanned as serialized text instead: kept unchanged when
+nothing registered appears, otherwise withheld. A cycle or a container past the
+depth limit is withheld. No limit throws or exposes a matcher diagnostic, and
+typed success outcomes remain.
+
 Only credentials of at least eight characters enter the redaction and structural
 matchers. Credentials shorter than 8 characters are not redacted from echoes;
 use longer secrets. Matching short secrets can corrupt JSON-RPC fields or refuse
@@ -594,7 +703,7 @@ this floor produces one operator warning per connector with the typed code
 `short_secret_not_redacted` and no credential value. Remote connectors warn at
 construction; static `api()` OAuth warns on its first provider operation.
 Connecta's own messages never quote credential values, regardless of length.
-One matcher is cached until the secret set changes, and an empty set skips matching. Redaction runs after
+One automaton is cached until the secret set changes, and an empty set skips matching. Redaction runs after
 JSON unwrapping or joining text blocks and on final serialized text and every
 structured string, before result paging, emits, and program outputs/errors/logs. See
 [the agent boundary](./architecture.md#errors-and-records).
@@ -962,8 +1071,14 @@ still serve configured credentials. Both routes accept only GET, otherwise retur
 `form_post` is unsupported. Clerk's session-only policy applies regardless of method.
 
 The fifteen-minute signed handoff carries connector ownership, initiating principal, deployment origin, nonce,
-and restart mode. Configure `vault: encryptedCredentialVault(storage, key)`, which derives its HMAC key with
-HKDF. Custom vaults need `signOAuthHandoff` and `verifyOAuthHandoff`; without a signing vault, links cannot be
+restart mode, and any predecessor link binding. New links use versioned, length-prefixed fields instead of
+JSON, with unpadded base64url payload and signature segments. Ordinary handoffs use an opaque wire encoding,
+not encryption; URL elicitation also seals those fields as described above. Copy the complete URL unchanged.
+The signature authenticates the exact version and payload text. Tampered or re-encoded links return
+`Invalid or expired connection link. Request a new link from connecta.` Pre-upgrade signed JSON and sealed
+v2 links still verify against their original text and expire after their original fifteen minutes.
+
+Configure `vault: encryptedCredentialVault(storage, key)`, which derives its HMAC key with HKDF. Custom vaults need `signOAuthHandoff` and `verifyOAuthHandoff`; without a signing vault, links cannot be
 issued or accepted. A link grants no identity. After identity and permissions pass, its nonce is consumed
 before OAuth starts, even while consent is pending. Failed starts need new links; nonce markers expire with
 their links.
@@ -1145,3 +1260,21 @@ is retained across requests, and rejected writes are never replayed. An omitted
 `app.privateKey` uses the encrypted connector vault's `privateKey` field;
 `describe()` includes neither the key nor the minted tokens. The maintained
 provider skill explains App permissions and installation prerequisites.
+
+## Source and tests
+
+Inbound adapters live in [src/auth](https://github.com/zackbart/connecta/tree/main/src/auth);
+[auth routes](https://github.com/zackbart/connecta/blob/main/src/routes/oauth.ts)
+own connection handoffs and callbacks. Check [inbound auth tests](https://github.com/zackbart/connecta/blob/main/test/inbound-auth.test.ts),
+[Access tests](https://github.com/zackbart/connecta/blob/main/test/cloudflare-access-auth.test.ts),
+and [identity-scope tests](https://github.com/zackbart/connecta/blob/main/test/identity-scope.test.ts)
+for credential precedence and disclosure boundaries.
+
+Downstream OAuth implementation and evidence are in
+[downstream-oauth.ts](https://github.com/zackbart/connecta/blob/main/src/auth/downstream-oauth.ts),
+[static-oauth.ts](https://github.com/zackbart/connecta/blob/main/src/auth/static-oauth.ts),
+[OAuth connect tests](https://github.com/zackbart/connecta/blob/main/test/oauth-connect.test.ts),
+[callback fencing](https://github.com/zackbart/connecta/blob/main/test/oauth-callback-fencing.test.ts),
+[refresh leases](https://github.com/zackbart/connecta/blob/main/test/oauth-refresh-lease.test.ts),
+and [API OAuth tests](https://github.com/zackbart/connecta/blob/main/test/api-oauth.test.ts).
+Use the test pointers within each section for narrower failure cases.