@zackbart/connecta 0.24.1 → 0.24.3

package/documentation/auth.md

@@ -6,6 +6,16 @@ Cloudflare Access from `/auth/cloudflare-access`. Providers may be combined;
 static bearers are checked first, then other providers in configuration order.
 Connecta no longer issues `cta_` tokens or serves token-management routes.
 
+The bearer adapter challenges with `WWW-Authenticate: Bearer` and deliberately
+omits `resource_metadata`. Its credential is configured out of band; it has no
+OAuth authorization server or registration endpoint to advertise. Interactive
+adapters or the edge own OAuth discovery. Every open deployment with at least
+one connector warns at construction, including API connectors with static auth
+headers. Credential and OAuth connectors add explicit wording about those grants.
+
+MCP browser origins pass the [Origin check](./request-admission.md#origin-before-admission)
+before admission or auth. This is independent of an identity's tool grants.
+
 ## Principals, visibility, and operators
 
 The actor identifies the caller in activity. The subject owns transient results
@@ -13,10 +23,95 @@ such as `get_result` pages. The principal is the human owner of personal
 connector auth. An interactive Clerk or Access user supplies all three. A
 Cloudflare service identity has an actor and subject but no principal.
 
-`identity.connectorAccess` returns `"all"` or declared connector ids. It governs
-discovery and use, and defaults to all connectors. Visibility alone grants no
-authentication-management permission. Two independent resolvers return
-`"all"`, `"none"`, or declared connector ids:
+A subject or user id always selects a result-stash partition, even when the
+provider omits `activityActorNamespace`. An explicit namespace remains the
+partition namespace; without one, Connecta uses `connecta:auth:<provider kind>`.
+Subject ids must be distinct within that namespace. This fallback grants no
+personal-auth ownership and changes no activity attribution. Open deployments
+and providers that return no identity share one result partition. A provider
+that supplies only an explicit principal uses that principal as its subject.
+
+`identity.connectorAccess` returns `"all"` or a list of grants. A grant is a
+declared connector id, which opens every tool on it, or a `connector.tool`
+address, which opens that tool alone. Grants are additive, so a bare id beside
+addresses for the same connector means the whole connector. It governs
+discovery and use, and defaults to all connectors.
+
+Tool grants are enforced in the scoped registry view, below the catalog
+service. Since 0.24.2, `search_tools`, `describe_tools`, both call tools, a
+program's `connecta.search`, `connecta.describe`, and `connecta.call`, and the
+connection UI read that filtered tool list. Connector-level discovery, guides,
+and `authorize_connector` retain a connector when any tool on it is granted.
+In particular, a `docs.read` grant permits the `docs` authorization handoff,
+subject to the separate auth-management permissions below. Without any grant
+on `docs`, `authorize_connector` returns the same "Unknown connector" refusal
+as an absent connector. An ungranted tool fails exactly like one the connector
+never had: `unknown_tool`, with no hint that it exists. That is the whole security
+claim, and it lives in one place on purpose. There is no separate endpoint per
+tool set; an identity that should see a narrower slice is a branch in this
+resolver, and a bot that needs its own slice is its own bearer subject.
+
+## Pools
+
+A pool is a named slice of the deployment served at its own endpoint,
+`/mcp/<pool>`, for the case where one identity needs different capability
+sets on different clients: a support agent that sees three Notion tools and
+Linear, a calendar bot that sees one tool, both over the same credentials and
+catalog cache.
+
+```ts
+createConnecta({
+  pools: {
+    support: {
+      tools: ["linear", "notion.search_pages", "notion.fetch_page"],
+      grant: ({ principal }) => supportTeam.has(principal?.id ?? ""),
+    },
+    calendar_bot: {
+      tools: ["calendar.create_event"],
+      grant: ({ actor }) => actor.id === "calendar-bot",
+    },
+  },
+  identity: { connectorAccess },
+  connectors,
+  executor,
+});
+```
+
+The rules, each of which is a test:
+
+- **A pool narrows; it never widens.** The view on `/mcp/<pool>` is the pool
+  intersected with the identity's own `connectorAccess`. Plain `/mcp` is
+  unchanged. The security boundary is still the resolver; the pool decides
+  which part of it a given client sees.
+- **Grant defaults to deny.** A pool with no `grant` serves nobody. Only a
+  literal `true` admits; any other return, a throw, and an undeclared pool
+  name produce one 404 identical in status, body, and headers, so a
+  credential does not enumerate the other pools by response content. Timing
+  is explicitly not hidden: a declared name awaits its grant, while an
+  undeclared name returns without that lookup. We accept this pool-name
+  oracle because names grant no access, a fixed delay cannot hide unbounded
+  grant I/O, and invoking grants for unknown names would add avoidable work
+  while holding an admission permit. Keep grants pure and fast; do not treat
+  pool names as secrets. The operator log carries the refusal reason.
+- **Structural mistakes throw at construction.** A malformed name, an
+  unknown connector, an empty pool, and a `connector.tool` address an
+  `api()` connector's static catalog lacks all refuse to boot. Remote
+  catalogs load lazily, so their addresses are checked at load and stay
+  unreachable until they match.
+- **OAuth discovery follows the path.** On Clerk, the 401 challenge for
+  `/mcp/<pool>` names `/.well-known/oauth-protected-resource/mcp/<pool>`,
+  whose `resource` is the pool URL, so RFC 9728 clients see a match.
+  Cloudflare Managed OAuth is application-level and needs nothing.
+
+A `connector.tool` address the live catalog does not contain is unreachable
+and warned once while its address remains in a 1,024-entry FIFO. An evicted
+address may warn again; caller-derived grant text cannot grow retained warning
+state without bound. Remote catalogs load lazily, so construction
+cannot check it, and a catalog that drifts later can never widen a grant
+because there is no wildcard: every tool grant is an exact name.
+
+Visibility alone grants no authentication-management permission. Two
+independent resolvers return `"all"`, `"none"`, or declared connector ids:
 
 - `credentialAdministration` allows an interactive human to manage shared
   credentials and shared OAuth grants.
@@ -39,8 +134,12 @@ administrator role or token-management authority.
 createConnecta({
   auth: cloudflareAccessAuth(),
   identity: {
-    connectorAccess: ({ principal }) =>
-      principal?.id === "owner-id" ? "all" : ["shared_docs", "personal_linear"],
+    connectorAccess: ({ principal, actor }) =>
+      principal?.id === "owner-id"
+        ? "all"
+        : actor.id === "calendar-bot"
+          ? ["calendar.create_event"]
+          : ["shared_docs", "personal_linear", "notion.search_pages"],
     credentialAdministration: ({ principal }) =>
       principal?.id === "owner-id" ? "all" : "none",
     personalConnection: () => ["personal_linear"],
@@ -160,6 +259,11 @@ secret-free handoff to the connection UI. Without the UI, that recovery is
 interactive MCP caller can still start downstream OAuth through
 `authorize_connector` without the UI. Core owns the callback and verifies state
 and principal ownership independently of the optional browser application.
+A browser returning from downstream consent normally carries no MCP
+Authorization header, so an interactive bearer provider's 401 does not reject
+the callback. The verified state and its saved principal handoff select the
+owner; a browser identity, when present, must match that owner and may manage
+the connector. An interactive provider's explicit 403 still refuses the flow.
 
 See [meta-tools](./meta-tools.md#authorization-recovery) and
 [storage and credentials](./storage-and-credentials.md). The

package/documentation/call-admission.md

@@ -103,15 +103,28 @@ checks, and authorization operations stay outside the budget: they are not the
 calls a provider is rate-limiting, and charging discovery for them would make
 a program's first search cost it capacity to act.
 
-Queue admission and connector execution have separate clocks. `queueTimeoutMs`
-bounds only the wait for a permit; a per-attempt `timeoutMs` starts after
-admission. A saturated call can therefore take up to their sum. With
+`queueTimeoutMs` bounds only the wait for a permit. The per-call `timeoutMs`
+is one deadline over catalog resolution, the permit wait, and the connector
+call together, so a saturated call can never take longer than `timeoutMs`;
+the queue timeout may only end it sooner. With
 `diagnostics: true`, `admissionMs` reports the permit wait and `connectorMs`
 the admitted attempt — which is the only way to tell "the provider is slow"
 from "we are throttling ourselves".
 
 ## Enforcement scope
 
+Shared connectors use the root registry's controller. Personal connectors use
+the owning principal's registry, so two accounts each receive their own budget;
+all requests and call paths for one principal still share it. `close()` rejects
+queued and future admissions on both kinds of controller, including a personal
+registry constructed after shutdown.
+
+The principal cache is bounded at 1,024 registries. Eviction closes an idle
+registry so an older request view cannot use an orphaned controller. A registry
+with active calls, queued calls, or unexpired rolling entries is never evicted.
+If all 1,024 are occupied, a new principal view fails closed with HTTP 403 until
+one drains. Cache churn cannot reset a live account's quota.
+
 This is deliberately **per-runtime**. It completely contains fan-out inside one
 request, including parallel `connecta.call` calls in one Worker isolate. A rolling
 budget is exact inside one Node process or Worker isolate, and best-effort
@@ -124,13 +137,16 @@ the bound actually is rather than implying a global one.
 
 ## Observations
 
-`/health` exposes payload-free aggregates at
-`admission.downstreamCalls.connectors.<id>`: retained partition count, current
+`/health` exposes one payload-free aggregate at
+`admission.downstreamCalls.aggregate`, summed across root and retained personal
+controllers: rule and retained partition counts, current
 active and queued gauges, cumulative admitted/queued/rejected/rate-limited/
 cancelled counts, and queue-wait count, total, and maximum. The open endpoint
-never exposes partition keys, tool arguments, or results — a partition key can
+never exposes connector ids, principal ids, partition keys, tool arguments, or results — a partition key can
 be a customer identifier, which is precisely why it stays out of an unauthenticated
-payload. Ordinary payload-free activity records the final call outcome and its
+payload. Queue-wait maxima take the maximum, other counters sum, and `closed`
+means every included controller is closed. Evicted idle controllers no longer
+contribute to these runtime snapshots. Ordinary payload-free activity records the final call outcome and its
 typed error code.
 
 ## Tests that enforce this
@@ -138,5 +154,5 @@ typed error code.
 | Invariant | Suite |
 | --- | --- |
 | Independent partitions, exact rolling-window reset and retry, queued cancellation charging no budget, synchronous cancel during partition derivation, validated values snapshotted rather than read from mutable config, bounded partition state and contained `partitionKey` failures, empty and multi-rule policies refused | `test/call-admission.test.ts` (controller) |
-| One base-registry limiter shared by direct and program calls, promise concurrency with input order preserved, cancellation threading, no dispatch or retry or health poisoning after cancellation, retry hints returned without waiting or poisoning health, payload-free `/health` aggregates | `test/call-admission.test.ts` (integration, Node + Workers) |
+| Shared and personal limiters shared by direct and program calls, independent principal budgets, shutdown covering both, eviction preserving live budgets, promise concurrency with input order preserved, cancellation threading, no dispatch or retry or health poisoning after cancellation, retry hints returned without waiting or poisoning health, payload-free `/health` aggregates | `test/call-admission.test.ts` (integration, Node + Workers) |
 | Where provider budgets are allowed to come from at all | [provider conventions P12](./provider-conventions.md#p12--declare-an-admission-budget-only-when-the-provider-documents-a-number), [provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md) |

package/documentation/code-mode.md

@@ -180,11 +180,11 @@ const page = await connecta.search({
 });
 ```
 
-**S1.** Returns one flat page: `{ tools, total, offset, limit, hasMore }`, plus `nextOffset` when more remains and `matchMode: "partial"` when no tool matched every term. Top-level `search_tools` is different: it returns `{ connectors: [{ id, tools }], total, offset, limit, hasMore }`. Complete matches normally precede partial matches, but a partial candidate whose complete normalized tool name occurs in the normalized raw query competes by score; conversational cleanup applies only to scoring terms. Other candidates covering at least two terms fill the page after every complete match; when no complete match exists, the existing any-term fallback remains. Each entry in `tools` carries `address`, `name`, the configured `connectorTitle` when present (normalized whitespace, at most 120 UTF-8 bytes), and — when requested — `description`, `inputSchema`, `outputSchema`, `annotations`, and the connector's `guide`. An output shape learned under `S9` also carries `outputSchemaSource: "observed"`; provider declarations carry no source marker. Tool rows expose neither lexical scores nor per-result coverage. An empty or whitespace-only query browses. Non-empty input with no ASCII lexical terms returns no tools and bounded no-match analysis; mixed input searches with its ASCII terms. Compact shapes omit property prose, put required fields first, and cap each shape at 1,024 UTF-8 bytes. Each enum node gets 256 of those bytes. About three near-cap enum nodes can therefore coexist while leaving the final quarter for surrounding syntax; the unchanged global fallback still applies above 1,024 bytes. A capped enum preserves whole values before `unknown` and an exact omitted-value count, while an empty enum renders as `never`. Either cap carries `inputSchemaTruncated` or `outputSchemaTruncated`; a shape-wide cap remains structurally valid with `unknown` types plus `/* truncated */`. Small enums remain complete. Use `connecta.describe` (or JSON search) for omitted exact constraints.
+**S1.** Returns one flat page: `{ tools, total, offset, limit, hasMore }`, plus `nextOffset` when more remains and `matchMode: "partial"` when no tool matched every term. Top-level `search_tools` is different: it returns `{ connectors: [{ id, tools }], total, offset, limit, hasMore }`. Complete matches normally precede partial matches, but a partial candidate whose complete normalized tool name occurs in the normalized raw query competes by score; conversational cleanup applies only to scoring terms. Other candidates covering at least two terms fill the page after every complete match; when no complete match exists, the existing any-term fallback remains. Each entry in `tools` carries `address`, `name`, the configured `connectorTitle` when present (normalized whitespace, at most 120 UTF-8 bytes), and — when requested — `description`, `inputSchema`, `outputSchema`, `annotations`, and the connector's `guide`. An output shape learned under `S9` also carries `outputSchemaSource: "observed"`; provider declarations carry no source marker. Tool rows expose neither lexical scores nor per-result coverage. An empty or whitespace-only query browses. Non-empty input with no ASCII lexical terms returns no tools and bounded no-match analysis; mixed input searches with its ASCII terms. Compact shapes omit property prose, put required fields first, and cap each shape at 1,024 UTF-8 bytes. Each render spends at most 2,000 visits across schema nodes, property and required names, literal values, any constraint-free retry, and its key-only fallback. Resolved `$ref` text is reused within that walk; exhausted work yields `unknown /* truncated */` and the corresponding truncation flag. Each enum node gets 256 of those bytes. About three near-cap enum nodes can therefore coexist while leaving the final quarter for surrounding syntax; the unchanged global fallback still applies above 1,024 bytes. A capped enum preserves whole values before `unknown` and an exact omitted-value count, while an empty enum renders as `never`. Either cap carries `inputSchemaTruncated` or `outputSchemaTruncated`; a shape-wide cap remains structurally valid with `unknown` types plus `/* truncated */`. Small enums remain complete. `prefixItems` renders as a tuple with the declared `items` rest, an `unknown[]` rest when open, or no rest when `items` is false. `dependentSchemas` and `if`/`then`/`else` keep the base shape plus `/* conditional */` and set the truncation flag. `$dynamicRef` resolves a same-named definition like `$ref`; unresolved dynamic references become `unknown` with the truncation flag. These forms share the byte and work bounds above. Use `connecta.describe({ address, format: "json" })` or JSON search for omitted exact constraints.
 
 **S1a.** `connector` loads only the named catalog; omit it only when the integration is ambiguous, because an unscoped search fans out across every configured connector. `safety: "readOnly"` returns exactly the tools available through `connecta.call`; `"approvalRequired"` returns the complementary fail-closed class, including false, missing, and contradictory annotations. Omitted or `"all"` preserves the complete catalog. These filters grant no authority and change no admission decision.
 
-**S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`, and `outputKeys`: the same names the rendered schema shows, ready to check before building arguments. Match inputs, truncation, safety, and outputs, not lexical
+**S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`, and `outputKeys`: the same names the rendered schema shows, ready to check before building arguments. `requiredInputKeys` includes only declared properties. Match inputs, truncation, safety, and outputs, not lexical
 rank; search distinct operations separately and use `outputKeys`, not guessed roots. A non-object schema — a union, an array, an
 unresolvable `$ref` — carries no lists rather than empty ones, because absent
 means "read the schema" where `[]` would claim the tool takes no fields. The
@@ -199,9 +199,8 @@ carries the same metadata whenever schemas are requested. Code-mode callers
 can set `includeSchemaKeys: false` to buy the bytes back.
 
 **S3.** Discovery is bounded and the bounds throw rather than silently shrink: a
-`limit` outside 1–100 is `invalid_args`, and a page whose serialized form
-exceeds 256,000 bytes is `result_too_large`, each with a hint naming the ways to
-ask for less. The thrown error carries the stable `code`, `retryable`, and
+`limit` outside 1–100, an `offset` that is not a non-negative integer, or a supplied `query` that is not a string is `invalid_args`. Omitted `offset` starts at 0; omitted `query` browses. A page whose serialized form
+exceeds 256,000 bytes is `result_too_large`; a program's page is measured as its serialized value, while top-level `search_tools` measures the complete tool result including both copies and JSON escaping. Each error carries a hint for correcting the request. The thrown error carries the stable `code`, `retryable`, and
 `details` fields (`E1`).
 
 ### connecta.describe
@@ -222,7 +221,7 @@ carry a route-aware `nextAction`; a close miss may add three canonical `suggesti
 Catalog failures add only `retryAfterMs` when known. One bad address never fails the whole call. Each failed entry clamps its
 caller-authored `address` to 512 UTF-8 bytes with an `…` marker. Entry order
 correlates a clipped address with its request; successes keep canonical addresses. More than 100
-addresses is `invalid_args`; the same 256,000-byte ceiling applies. A success whose output shape came from `S9` carries `outputSchemaSource: "observed"` beside the rendered schema.
+addresses is `invalid_args`; the same 256,000-byte ceiling applies. Compact describe keeps property prose within a separate 8,192-byte UTF-8 shape cap and shares search's 2,000-visit work budget. A capped shape sets `inputSchemaTruncated` or `outputSchemaTruncated`; use `format: "json"` for the exact schema. A success whose output shape came from `S9` carries `outputSchemaSource: "observed"` beside the rendered schema.
 
 ### connecta.call
 
@@ -286,8 +285,9 @@ clauses are [Emitted output](#emitted-output) (`M1`–`M10`).
 | Program or execution failure (`E5`, `E6`, a bridge bound in `L6`) | error text | no |
 
 Both executor bridges reduce a rejected host call to `new Error(message)`. Connecta restores the typed failure in a trusted prelude with a per-execution authenticated frame (`X11`), without turning the rejection into a returned value.
-`message` remains the human text. `code` and `retryable` are the stable branch fields; `details` is the complete host classification. This covers `call`, `search`, `describe`, `emit`, and the host-call budget.
+`message` remains human text, capped at 2,000 JSON-serialized characters including quotes and an `…` marker when clipped. `code` and `retryable` are the stable branch fields; `details` carries the host classification. The complete details object fits 3,700 serialized characters. If optional recovery metadata would exceed that bound, it is omitted whole, preserving `code`, `message`, `retryable`, and `retryAfterMs`; a clipped recovery address or argument would describe a different call. This covers `call`, `search`, `describe`, `emit`, and the host-call budget.
 Program-authored errors stay untyped, and code must never parse error prose.
+An `unavailable` classification may include optional `details.host` as an HTTP(S) origin of at most 253 UTF-8 bytes and `details.code` as a validated network errno, undici transport code, or `timeout` of at most 32 bytes; these diagnostics never enter activity records.
 
 **E2.** The taxonomy: `retryable` is what connecta reports, `Y3` what a program may do.
 
@@ -301,7 +301,7 @@ Program-authored errors stay untyped, and code must never parse error prose.
 | `not_found` | the downstream answered and the resource is not there — the one code that says skip this id rather than stop, raised only where the provider tells absence from a permission gap ([H11](./provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next)) | false |
 | `input_required_unsupported` | a downstream asked for mid-call input | false |
 | `rate_limited` | the downstream reported a rate limit | true |
-| `unavailable` | the downstream is down or unreachable | true |
+| `unavailable` | the downstream is down or unreachable; optional sanitized `details.host` and `details.code` describe the transport failure without paths, queries, credentials, or provider prose | true |
 | `timeout` | the per-call deadline (`execute.hostCallTimeoutMs`, default 15 s) expired | true |
 | `cancelled` | the run ended while this call was in flight (`E5`) | false |
 | `connector_call_failed` | anything else the connector threw | per message |
@@ -330,16 +330,16 @@ guest: admission rejection (`executor_overloaded`, retryable, with
 reported to the model as an error result. One seam: a host call still in flight
 when the run is cancelled fails with `cancelled`, catchable on the way out but
 never worth acting on (`Y3`). When shutdown tears down a program that had
-already started, accepted blocks are reported as discarded under `M4`; a failure before execution started carries no discard fields.
+already started, accepted blocks are reported as discarded under `M4`; a failure before execution started carries no discard fields. A returned `error` field is a failure even when empty; an empty string reports `executor_failed` with `Error: Execution failed without an error message.`
 
 **E6.** An error the program raises itself — a `TypeError`, a call to a
 `connecta` member that is not a provider function (including an inherited one
 like `toString`), a `throw` of its own — ends the run with an error result
 carrying that message. It is not typed, because it is not a connector failure.
 One precedence rule: connecta recognizes an escaped tool failure by its message —
-exactly first, by containment second — so a program that *wraps* a failure's
+exactly first, by containment second for messages of at least eight characters — so a program that *wraps* a failure's
 message in its own text still reports the underlying typed failure. Keeping the
-type beats keeping the prose.
+type beats keeping the prose. Matching retains only the most recent 64 failures per execution, including caught refusals; an older escaped message remains an untyped execution failure. An empty terminal error uses the fixed message in `E5`.
 
 **E7.** `retryable` for `unknown_address`, `unknown_tool`, and `destructive_tool_requires_approval` is pinned false, never inferred from an address containing `503`, `429`, or `temporar`. The first two carry `nextAction: { function: "connecta.search", arguments: { query, connector?, includeSchemas: "compact" } }` — the same scoped discovery the top-level record names, keyed to the surface the caller actually has. A program cannot call `search_tools`, so it is never told to. The message, the derived `query`, and a failed describe entry's `address` clamp caller-authored text to 512 UTF-8 bytes with an `…` marker. Those values land in the text content and `structuredContent`, so an invented 50 KB address would otherwise produce a refusal orders of magnitude past the deployment's result cap. A clipped address still identifies the mistake by its position; a short one — the common case — is exact and untagged.
 
@@ -383,7 +383,7 @@ anything, so paging its result would reward the one behavior code mode exists to
 remove — and stashing every unprojected return value would spend the result store
 on data nobody asked for.
 
-**R5.** `console.log`, `console.warn`, and `console.error` are captured in call order and returned as a single `logs` string, capped at 4,000 characters with a truncation marker. Logs survive failure — they ride along with the error result, which is what makes them worth writing. How a non-string argument renders is not contract (`X4`).
+**R5.** `console.log`, `console.warn`, and `console.error` are captured in call order and returned as a single `logs` string, capped at 4,000 characters with a truncation marker. Logs survive program failure through either a returned error result or a thrown error carrying `logs: string[]`. QuickJS streams captured entries to its parent and preserves the received prefix on cancellation, shutdown, deadline termination, child crashes, and IPC failures (`X4`). How a non-string argument renders is not contract (`X4`).
 
 **R6.** Nothing else is added to a normal program result. Passing `diagnostics: true` adds one request-local, payload-free `diagnostics` block; a program that emitted adds `emitted: N` and its blocks (`M2`). Omitted, `false`, and emit-free are byte-for-byte the ordinary response path. Diagnostics exist so catalog, connector, and executor costs are distinguishable without persisting payloads or charging normal responses ([#247](https://github.com/zackbart/connecta/issues/247)).
 
@@ -433,8 +433,8 @@ media, not base64 text.
 trusted exactly as much as the return value. Preservation is re-emission of
 the raw downstream block, so `S5`'s uncapped fallthrough is contract.
 
-**M7.** `emit` spends no host-call budget (`L4`); `M5`'s bounds are its only
-bounds.
+**M7.** `emit` alone spends no host-call budget (`L4`); `search`, `describe`,
+and `call` share it. `M5`'s bounds are emission's only bounds.
 
 **M8.** Emission asks nothing of an executor: `emit` is a provider function,
 blocks cross the guest boundary once as an argument, and `ExecuteResult` is
@@ -491,7 +491,7 @@ because connecta enforces them above the sandbox:
 
 | Bound | Value |
 | --- | --- |
-| Host calls per execution | 20 |
+| Host calls per execution, shared by `search`, `describe`, and `call` | 20 by default, `execute.maxHostCalls` |
 | Deadline per host call | 15 s, `execute.hostCallTimeoutMs` |
 | Discovery page | ≤ 100 tools, ≤ 256,000 serialized bytes |
 | `describe` addresses | ≤ 100 |
@@ -500,7 +500,7 @@ because connecta enforces them above the sandbox:
 | Result | 24,000 serialized characters |
 | Logs presented to the model | 4,000 characters |
 
-Exhausting the host-call budget fails that call with non-retryable `budget_exceeded` (`E2`) and a message naming the budget. No connector is reached, and the budget does not refill inside one execution.
+Every `call` attempt spends one host call on entry, before address resolution, catalog lookup, safety checks, validation, or dispatch. Unknown addresses, unknown tools, catalog failures, and other pre-dispatch refusals spend the same budget as successful calls; catching a refusal does not refund it. `search` and `describe` likewise spend on entry. Exhausting the host-call budget fails that call with non-retryable `budget_exceeded` (`E2`) and a message naming the budget. No connector is reached, and the budget does not refill inside one execution.
 
 **L5.** The guest is memory-, stack-, and CPU-bounded, and a program that
 exhausts a bound ends the run with an error instead of degrading the host. The
@@ -588,7 +588,14 @@ arguments and captures `log`, `info`, `warn`, `error`, and `debug`; the Dynamic
 Worker renders arguments with `String()` (so an object logs as
 `[object Object]`) and captures only `log`, `warn`, and `error`, prefixing the
 latter two. Only the three captured everywhere are contract (`R5`); rendering is
-not.
+not. QuickJS streams each accepted entry within the existing IPC envelope
+bound while retaining its per-entry and cumulative child caps. The parent
+keeps at most 4,001 joined characters for failure recovery, one beyond the
+presentation cap so truncation stays visible. On a normal reply, its complete
+log array takes precedence over that prefix; the two copies are never joined.
+On termination or IPC failure, the parent attaches its retained prefix to the
+thrown error. Admission rejection before the program starts has no guest logs
+to recover.
 
 **X5. Leftover authority.** QuickJS blocks imports and has no `fetch`, `process`, timers, `crypto`, or `WebSocket`. Its Node child starts with an explicitly empty process environment rather than inheriting deployment variables or `NODE_OPTIONS`. A Dynamic Worker has those globals plus a non-contract set of runtime builtins through `import()` and `process.getBuiltinModule()`, including `node:path`, `node:crypto`, `node:net`, `node:tls`, `node:dns`, `node:module`, and `cloudflare:workers`. The upstream set can drift; this list is not an allowlist.
 The supported Worker construction is exactly `new DynamicWorkerExecutor({ loader })`. Do not pass `bindings`, `modules`, or `globalOutbound`: each can grant ambient configuration, code, or egress. Under it, `process.env`, lexical `this.env`, and `cloudflare:workers.env` are empty; `node:fs`, `node:http`, and `node:https` are unavailable through either access route; external `fetch`, `WebSocket`, `node:net`, and `node:tls` fail with workerd's outbound-denial error; DNS lookup ends unresolved; and `fetch("data:...")` resolves locally.
@@ -625,7 +632,12 @@ from one tool call therefore fails on Node and may succeed on Workers — reduce
 inside the program either way (`R1`).
 
 **X11. Typed host rejection.** Both executors rebuild Connecta's authenticated host-failure frame as a thrown guest `Error` (`E1`). The per-run secret stays in the trusted prelude closure, and the prelude locks `globalThis.Error`, so guest code and connector prose cannot forge the host transport frame.
-The human message is unchanged; a mismatched frame is ordinary untyped prose.
+The host bounds details before framing (`E1`), including JSON escapes. QuickJS
+refuses an oversized authenticated frame whole rather than slicing through its
+JSON, and the prelude hides an authenticated frame whose JSON is malformed.
+QuickJS keeps the raw bridge and its JSON decoder in a private closure so guest
+code cannot intercept the frame before the prelude handles it. A mismatched
+frame is ordinary untyped prose.
 
 ## Changes from earlier code mode
 
@@ -659,7 +671,7 @@ the upstream `Executor` shape assignable.
 | `S5` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`) |
 | `S6` | `test/execute.test.ts` (fail-closed annotations, activity parity) |
 | `S7` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (parallel calls and shared admission) |
-| `S8`, `E1`, `X11` | both guest-contract executors (caught call, discovery, utility, budget, removed-function, and forgery cases; typed promise rejections) |
+| `S8`, `E1`, `X11` | both guest-contract executors (caught call, discovery, utility, budget, removed-function, and forgery cases; typed promise rejections), `test/quickjs-executor.test.ts` (oversized messages, private transport, and forged frames) |
 | `S9` | `test/result-shapes.test.ts` (value exclusion, bounds, merging, LRU and time expiry, runtime isolation, read-only admission, declared precedence, definition invalidation, unwrapped MCP results, discovery provenance, copy isolation, and failure isolation) |
 | `E2`, `E8` | `test/guest-api-contract.test.ts` (code → `retryable`, caught, parallel, and uncaught validation recovery), `test/meta-tools.test.ts` (direct, destructive, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts` |
 | `E3` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`) |
@@ -677,9 +689,9 @@ the upstream `Executor` shape assignable.
 | `Y4` | `test/meta-tools-call.test.ts`, `test/call-admission.test.ts` (one attempt, retry hints, caller reissue) |
 | `L1`, `L2` | `test/guest-api-contract.test.ts` (in-flight call fails `cancelled`), `test/execute.test.ts` (cancels outstanding host calls) |
 | `L3`, `X1` | `test/guest-api-contract.test.ts` (short-deadline executors) |
-| `L4`, `L8` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (budgets) |
+| `L4`, `L8` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (shared discovery/call budgets) |
 | `L5`, `X2` | `test/quickjs-executor.test.ts` (CPU, heap) |
-| `L6`, `X10` | `test/quickjs-executor.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message) |
+| `L6`, `X10` | `test/quickjs-executor.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.test.ts` (outer reply serialization failure settles the call) |
 | `L7` | `test/execute.test.ts`, `test/executor-admission.test.ts` |
 | `V1`–`V4` | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, and the identity clamp) |
 | `M1` | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (every rejected shape) |
@@ -690,7 +702,7 @@ the upstream `Executor` shape assignable.
 | `M8` | two arms passing one case table, `test/codemode-compat.test.ts` |
 | `M10` | `test/execute-emit.test.ts` (aggregate present, numbers only, absent when nothing emitted) |
 | `X3` | `test/quickjs-executor.test.ts` (cancels a running child) |
-| `X4` | `test/guest-api-contract.test.ts` (string logs only) |
+| `X4` | `test/guest-api-contract.test.ts` (string logs only), `test/quickjs-executor.test.ts` (logs before cancellation), `test/quickjs-child-stderr.test.ts` (crash, shutdown, deadline, IPC failure, bounded parent retention), `test/quickjs-log-limits.test.ts` (unchanged successful logs) |
 | `X6` | `test/quickjs-executor.test.ts` (never-settling await) |
 | `X7` | `P3`'s tests; the Workers superset is deliberately unused |
 

package/documentation/connectors.md

@@ -188,6 +188,21 @@ downstream wrote them, and an unannotated or contradictory one stays
 fail-closed onto `call_destructive_tool`. The contract binds the surfaces we
 write, not the catalogs we relay.
 
+An `unavailable` failure can carry `details.host` and `details.code` in its
+classified error. `host` is an HTTP(S) origin, including a non-default port,
+with no userinfo, path, query, or fragment and at most 253 UTF-8 bytes. `code`
+is an allowlisted network errno, an undici transport code, or `timeout`, at
+most 32 bytes. Invalid or oversized fields are omitted, never clipped.
+`remoteMcp()` and the guarded transport know the failed fetch destination;
+`api()` can classify a handler's structured runtime code but cannot recover
+its destination from `ctx.baseUrl`, which names Connecta itself. A handler can
+supply a known URL in a typed `ConnectorCallError` and the constructor reduces
+it to an origin. AbortError and TimeoutError become diagnostic `timeout`;
+workerd outbound denial supplies no errno, so a fetch boundary reports the
+known origin alone. No provider prose supplies a code or retryability.
+These diagnostics belong in tool failures and the bounded warning log, never
+in payload-free activity records.
+
 ## The guarded fetch transport
 
 Every hand-written HTTP surface re-derives the same safety machinery, and two
@@ -237,9 +252,13 @@ What it owns is mechanical and provider-independent:
   as an absurd response is a fact about the API, not about HTTP. A declared
   `Content-Length` past the ceiling fails before a byte is read, and a
   streaming body is abandoned at the ceiling rather than buffered past it.
+  Without a body stream, text is measured in UTF-8 bytes before it is accepted;
+  JSON is parsed from that same bounded text. Such runtimes still buffer their
+  read internally, but cannot return an oversized body as a successful result.
 - **Normalization.** An unreachable provider becomes a retryable `unavailable`
   instead of whatever `TypeError` the runtime threw, and `ctx.signal` rides
-  every request.
+  every request. `Retry-After` hints accept delta-seconds and HTTP dates;
+  a date in the past means no further wait.
 
 What it deliberately does not own is meaning. It never reads a status code and
 never invents an authentication scheme: the provider's `authenticate` callback
@@ -288,9 +307,13 @@ Connecta deliberately sits between protocol generations
   compatibility concession, so modern protocol support is still discovered.
 - **Legacy sessions:** Connecta's own endpoint creates no protocol session, but
   a stateful legacy downstream can still issue `Mcp-Session-Id`. Closing a
-  request scope explicitly sends the legacy DELETE before closing its transport.
-  SDK v2 `Client.close()` does not do that on Connecta's behalf, so
-  `terminateSession` remains required and tested.
+  request scope, rotating credentials, retiring an OAuth generation, and
+  abandoning a connect all send the legacy DELETE before closing the transport.
+  The DELETE gets at most one second and failures are logged. Rotation and
+  abandoned connects start cleanup without waiting; the connector context has
+  no deferred-work hook. Scope teardown gives its bounded tail back to core,
+  which can attach the runtime's deferred channel. SDK v2 `Client.close()` does
+  not send DELETE on Connecta's behalf.
 - **Modern cache hints:** `tools/list` is deployment-fixed and returns a
   one-hour private cache hint. Downstream hints do not alter Connecta's existing
   five-minute fingerprinted catalog cache; that remains gated in
@@ -352,7 +375,11 @@ For remote MCP tools, that path checks the catalog's advertised `inputSchema`
 before provider dispatch. Supported mismatches become bounded, payload-free
 `invalid_args` findings; a schema the local validator cannot evaluate passes
 through unchanged. Connecta does not parse provider error prose to invent a
-validation classification.
+validation classification. A downstream JSON-RPC `-32602` is an explicit
+`invalid_args` refusal, with a bounded server message and no retry. HTTP 4xx
+refusals preserve a bounded JSON `message`, including `error.message`, and are
+non-retryable; 429 becomes `rate_limited` and 408 becomes `timeout`. The SDK
+still owns OAuth challenges and step-up authorization.
 
 ## Authentication
 
@@ -363,6 +390,21 @@ server issuer discovered and validated by the SDK; see
 The callback route validates `state` before passing the complete callback query
 to the SDK so RFC 9207 `iss` validation is not lost.
 
+Within one runtime, overlapping refreshes share one completion gate per
+credential partition and generation. A valid token response is a consumed
+refresh token, so the coordinator keeps that response's tokens on the flight.
+If the owner then fails before the SDK saves them — cancelled, redirected to
+authorization, or invalidated — the host persists the rotation itself, holds
+contenders behind the mutation marker until that write lands, and hands them
+the saved rotation; a retired token is never redeemed twice. A write already
+running in `saveTokens` clears the marker on its own success or failure, and a
+late duplicate save from a detached owner is harmless. Nothing can leave a
+permanent 503 gate ([#526](https://github.com/zackbart/connecta/issues/526)).
+Refresh token response validation
+reads at most 65,536 bytes, and credential reads stop after 64 revision races
+with `temporarily_unavailable` so churn cannot spin indefinitely. Request
+cancellation is checked before each attempt.
+
 A remote MCP connector that authenticates with a static key has two ways to
 receive one. `{ type: "headers", headers }` bakes the literal value into the
 deployment file, which suits a secret the runtime already holds.

package/documentation/meta-tools.md

@@ -121,15 +121,25 @@ bytes. Within that unchanged total, each enum node and each constraint
 annotation may spend at most 256 UTF-8 bytes. Numeric bounds, string length
 bounds, patterns, and formats render beside their type. A constraint that does
 not fit is dropped whole. If constraints push the full shape over 1,024 bytes,
-search retries the shape without them. Compact describe keeps all declared
-constraints. A large enum keeps the longest whole-value prefix that fits, then
+search retries the shape without them. Compact describe keeps declared
+constraints and property prose within its own 8,192-byte shape cap, sharing
+search's 2,000-visit rendering budget; a capped shape sets
+`inputSchemaTruncated` or `outputSchemaTruncated`, and `format: "json"` or
+JSON search returns the exact schema. A large enum keeps the longest whole-value prefix that fits, then
 adds `unknown` and a comment with the exact omitted-value count. An empty enum
 renders as the valid `never` type. A capped object becomes a valid
 required-first shape with `unknown` types; other shapes become
 `unknown /* truncated */`. Any cap marks the match with
 `inputSchemaTruncated` or `outputSchemaTruncated`; repeat the search with
 `includeSchemas: "json"` or use the existing describe path when exact
-constraints matter. Small enums and both exact paths remain complete.
+constraints matter. `prefixItems` renders as a tuple, with the `items` type
+as its rest, an `unknown[]` rest when open, and no rest for `items: false`.
+`dependentSchemas` and `if`/`then`/`else` preserve the base shape and append
+`/* conditional */`, setting the truncation flag so the caller reads the exact
+JSON schema. `$dynamicRef` resolves a same-named definition like `$ref`; an
+unresolved dynamic reference renders as `unknown` with the truncation flag.
+These shapes share the same byte and work budgets. Small enums and both exact
+paths remain complete.
 
 ## Connector guide selection
 
@@ -206,12 +216,42 @@ removing or summarizing the text copy is deferred until host-forwarding
 measurements demonstrate that supported clients do not need it.
 
 Plain-text guidance and errors remain text-only. A downstream MCP tool's native
-content blocks also pass through unchanged when `call_tool` uses MCP result
-mode; they are not a duplicated Connecta object result. Newly stashed JSON and
+content blocks pass through when `call_tool` uses MCP result mode. When no
+text block exists and `structuredContent` is present, Connecta appends a text
+block containing its compact JSON, then applies the same content size guard.
+This preserves structured-only results, including `null`, arrays, and scalars.
+An existing text mirror stays unchanged; Connecta does not add another copy. Newly stashed JSON and
 downstream content envelopes use compact serialization, so `get_result` byte
 offsets and totals refer to that exact compact text.
 
-A `call_tool` truncation notice carries both the historical `resultId` and an
+The direct-call stash keeps results for 15 minutes. `results.maxStashBytes`
+defaults to 8 MiB and `results.maxStashEntries` to 64 per `createConnecta`
+runtime, shared across all subjects and pools. Both accept non-negative safe
+integers; zero disables stashing. The byte budget counts the stored ASCII
+paging envelope, including base64 overhead, rather than only the result text.
+Capacity is reserved before each storage write, so concurrent requests cannot
+oversubscribe it. A full stash refuses new entries. A later stash attempt
+deletes expired entries before reusing their capacity; a failed deletion keeps
+the charge. These bounds cover writes by this runtime, not other processes,
+Worker isolates, or entries left by a previous runtime.
+
+Results belong to the authenticated subject whenever auth supplies a subject
+or user id, independently of activity configuration. The provider's namespace
+is used when present; otherwise the namespace is `connecta:auth:<provider kind>`.
+Keep subject ids distinct within that namespace. An explicit principal is the
+fallback subject when neither id is supplied. Open deployments and auth
+providers that supply no identity share one partition.
+
+New entries store UTF-8 bytes in a base64 envelope. After the KV read,
+`get_result` decodes only the requested byte range and a few boundary bytes;
+it does not encode the full text on every page. Storage still reads one full
+value. Pre-upgrade raw-text entries remain readable during their TTL using
+one full encoding per page. Offsets and `totalBytes` always describe the
+original UTF-8 text, not the envelope. A supplied offset inside a character
+moves back to its start; page ends also align to character boundaries, and a
+page smaller than one character widens just enough to make progress.
+
+A successfully stashed `call_tool` truncation notice carries both the historical `resultId` and an
 exact `nextAction: { tool: "get_result", arguments: { id, offset: 0 } }`. The
 handle is therefore
 directly actionable without copying an identifier out of prose. Program results
@@ -219,6 +259,28 @@ and oversized discovery responses carry no such route — paging a program's
 return value is a refused shape, because a program can shrink anything before
 it returns.
 
+A refused stash or failed stash write cannot undo a downstream success. Both direct call tools
+return a truncated preview where usable, with a paging-unavailable notice and
+no `resultId` or paging action. Activity records success; the operator logger
+receives a fixed warning with the connector and tool, without storage error
+prose. For read-only work, reduce the result inside `execute_code`; repeating
+an approved write is not a way to recover its output. Other result-processing
+failures use a fixed `result_processing_failed` message and are never retryable.
+
+Downstream MCP `isError` text is bounded at its source to 512 UTF-8 bytes plus
+an `…` marker. Error framing may shorten it further to fit the call's result
+cap, counting JSON escaping and both copies in value mode.
+
+The top-level discovery ceiling is 256,000 UTF-8 bytes for the serialized tool
+result, including text, `structuredContent`, and JSON escaping. Measuring only
+one copy would advertise half the bytes the adapter actually returns.
+
+A per-call `timeoutMs` covers catalog resolution, admission, and connector
+execution with one deadline. The admission queue's own timeout may expire
+sooner, but it cannot extend the call deadline. Result processing happens after
+that deadline ends, because a completed downstream call must not turn into a
+retryable timeout while Connecta prepares its response.
+
 ## Lexical discovery
 
 `search_tools` tokenizes tool names and descriptions at punctuation and
@@ -373,6 +435,12 @@ recovery query, each of which lands in both the text content and
 the address is the thing being corrected, a clipped one still identifies the
 mistake, and a short one — every real one — comes back exact and untagged.
 
+Unknown `get_result.id`, `authorize_connector.connector`, and `skills.name`
+echoes use the same 512-byte clamp. `search_tools.connector` instead rejects
+values over 512 UTF-8 bytes with `invalid_args` before catalog lookup, so a
+clipped scope can never select a different connector. A failed result-storage
+read returns typed `unavailable` without exposing backend error text.
+
 `call_destructive_tool` accepts an optional
 `reason` of at most 500 characters for the host's human approval view. It is
 outer-call context only: Connecta neither treats it as authority nor passes it