@zackbart/connecta 0.24.2 → 0.24.3

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

package/documentation/operations.md

@@ -231,30 +231,30 @@ in.
 | Suite | Covers |
 | --- | --- |
 | `activity.test.ts` | payload-free delivery: a rejected async write attaches to `waitUntil` instead of throwing, approved destructive calls record under their real entry point, result-size friction records without retaining the result, and a hallucinated connector id or invented identity is clamped so the event still cannot carry a payload |
-| `api-connector.test.ts` | `api()` — kind, description, tool defs, dispatch, default args, unknown tools, handler throws, argument validation, and the construction contract |
+| `api-connector.test.ts` | `api()` — kind, description, tool defs, dispatch, default args, unknown tools, handler throws, argument validation, structured transport diagnostics, and the construction contract |
 | `bearer.test.ts` | constant-time bearer compare, case-insensitive scheme, 401 challenges, and the retired audience options refusing rather than silently unbinding |
 | `branding.test.ts` | branding fallbacks and overrides across the operator shells, OAuth result pages, `/favicon.*`, page titles, and escaping — branding is not an injection vector |
-| `call-admission.test.ts` | connector-scoped per-runtime downstream admission ([call admission](./call-admission.md)): independent partitions, exact rolling-window reset, cancellation that charges no budget, bounded partition state, local-refusal health isolation, one shared limiter across direct and program calls, and payload-free `/health` aggregates |
-| `catalog-drift.test.ts` | `vettedCatalog()`, `detectCatalogDrift()`, and `withVettedCatalog()`; drift on the registry surface and on `/health`; the connector seam projected rather than echoed; and the drift types being public |
-| `catalog.test.ts` | lexical ranking and the compact schema renderer — `const`, `allOf` beside siblings, `$ref`, the depth limit, per-schema caching, and 2020-12 keyword compatibility |
+| `call-admission.test.ts` | connector-scoped per-runtime downstream admission ([call admission](./call-admission.md)): independent partitions, exact rolling-window reset, cancellation that charges no budget, bounded partition state, local-refusal health isolation, direct and program calls sharing the appropriate controller, independent personal budgets, shared budgets, shutdown of both controller kinds, eviction preserving live budgets, and id-free `/health` aggregates |
+| `catalog-drift.test.ts` | `vettedCatalog()`, `detectCatalogDrift()`, and `withVettedCatalog()`; bounded schema-digest depth; drift on the registry surface and on `/health`; the connector seam projected rather than echoed; and the drift types being public |
+| `catalog.test.ts` | lexical ranking and the compact schema renderer: `const`, `allOf` beside siblings, memoized `$ref`, node/depth/byte bounds, truncation flags, declared required-key metadata, typed search argument validation, per-schema caching, and 2020-12 tuples, conditional markers, and dynamic references in search and describe |
 | `clerk.test.ts` | protected-resource metadata, the browser sign-in config, OAuth and session tokens, cached best-effort activity labels with their caps, the hand-applied `azp` rejection, and the `allowedDomains` allowlist including every lookalike that must not be repaired into a match |
 | `cloudflare-access-auth.test.ts` | trusted `ctx.access` human and service identities, absent/error fail-closed behavior, service-token MCP admission without operator mutation, human same-origin mutation, and the Clerk-to-ambient shell switch |
 | `cloudflare-provider.test.ts` | `cloudflare()` API and MCP construction, the code-mode safety manifest, API tool surface, current R2 and KV jurisdictions, useful output declarations, request building, projections including additive provider fields, typed failures, and credential test |
 | `code-first-surface.test.ts` | the seven-tool surface itself — an executor required, every removed option and top-level tool refused, compact always-loaded routing pinned below 1,000 characters, complete on-demand usage served, and no rendering instructions |
 | `codemode-compat.test.ts` | the `Executor` seam staying structurally compatible with `@cloudflare/codemode`'s `DynamicWorkerExecutor`, enforced by `tsc` |
-| `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds failing construction, and unknown own-properties rejected by their complete path before construction does work |
+| `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds, result stash limits, and origin lists failing construction, open-connector warnings including static API auth, and unknown own-properties rejected by their complete path before construction does work |
 | `credentials.test.ts` | the pure stored-shape classifier (containment, not equality) and the AES-GCM vault: round-trip, ciphertext bound to its connector id, named field sets, masked metadata, wrong-key rejection, deletion, coexistence with OAuth keys |
 | `d1-activity-example.test.ts` | the Worker example's deployment-owned D1 activity store: actor namespace round-trip, payload-free friction reconstructed from the persisted code, and agreement with the package's friction table |
-| `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and generation races, runtime-local rotating-token refresh coordination across request scopes, refresh failure/retry, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality, bounded diagnostics, and HTML escaping |
-| `errors.test.ts` | `ConnectorCallError` codes, retryable defaults and overrides, `retryAfterMs` round-trip, typed-over-heuristic classification, `AbortError` as a retryable timeout, and framing errors |
-| `execute.test.ts` | the code-mode host bridge: identifier sanitization, account titles in program discovery, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, fail-closed filtering of destructive and unannotated tools, MCP/code-mode invocation parity, and payload-free describe diagnostics |
+| `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and generation races, two eight-scope waves of runtime-local rotating-token refresh, recovery after abort/redirect/invalidation, bounded token reads and revision churn, refresh failure/retry, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality and identity-free 401 versus explicit 403, bounded diagnostics, and HTML escaping |
+| `errors.test.ts` | `ConnectorCallError` codes, retryable defaults and overrides, `retryAfterMs` round-trip, typed-over-heuristic classification, `AbortError` as a retryable timeout, sanitized bounded unavailable diagnostics, and framing errors |
+| `execute.test.ts` | the code-mode host bridge: identifier sanitization, account titles in program discovery, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, shared discovery/call budgets including pre-dispatch refusals, bounded recent-failure matching, empty terminal errors, logs on thrown executor failures, short-message failure matching, fail-closed filtering of destructive and unannotated tools, MCP/code-mode invocation parity, and payload-free describe diagnostics |
 | `execute-emit.test.ts` | `connecta.emit` (M1–M10) — block validation, budgets, the provider, delivery after the result envelope on success only, and the defaults |
 | `executor-admission.test.ts` | the portable bounded FIFO both pools use: active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown |
-| `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, and response handling |
+| `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, response handling, bounded no-stream text/JSON reads, sanitized transport diagnostics, and delta-seconds/HTTP-date Retry-After hints |
 | `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, typed inline describe recovery, discovery, utility, parallel-call, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
-| `identity-scope.test.ts` | identity-derived connector visibility, named pools at `/mcp/<pool>` (grant-gated, intersected with the identity ceiling, identical 404 for undeclared, refused, and throwing grants, construction-time refusals), exact `connector.tool` grants enforced identically across discovery, direct calls, the program host bridge, and the connection UI, fail-closed grant parsing, the once-per-isolate absent-grant warning, personal credential isolation, separate shared-auth and personal-auth management permissions, and personal OAuth callback ownership |
+| `identity-scope.test.ts` | identity-derived connector visibility, named pools at `/mcp/<pool>` (grant-gated, intersected with the identity ceiling, identical 404 for undeclared, refused, and throwing grants, construction-time refusals), exact `connector.tool` grants enforced identically across discovery, direct calls, the program host bridge, and the connection UI, fail-closed grant parsing, the once-per-isolate absent-grant warning, personal credential isolation, separate shared-auth and personal-auth management permissions, bearer-subject result isolation without activity namespaces, connector authorization visibility for tool grants, and personal OAuth callback ownership |
 | `linear-provider.test.ts` | the Linear proxy's construction, guide, plan-aware catalog superset, and current workspace, template, and issue-sharing classifications |
-| `meta-tools-call.test.ts` | registry-backed calls: structured errors, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, and offset alignment |
+| `meta-tools-call.test.ts` | registry-backed calls: structured errors, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, offset alignment, runtime-wide stash quotas including pending writes and expiry reclamation, and page-proportional decoding |
 | `meta-tools-search.test.ts` | registry-backed discovery: bounded search with page and address maxima, compact and JSON schemas with constraints, typed describe recovery and suggestions, and structured-result compatibility |
 | `meta-tools.test.ts` | the remaining registry-backed meta-tools: the complete on-demand usage skill, connector-guide selection and summary bounds, stored-credential drift, catalog health, authorization, probe timeouts, and unavailable or unknown browse recovery |
 | `mixpanel-provider.test.ts` | the Mixpanel proxy, its conditional-input guide, destructive metadata fill, and complete 64-tool schema-digest manifest |
@@ -264,21 +264,21 @@ in.
 | `optional-modules.test.ts` | absent modules, UI-free OAuth, fast lists and independent detail deadlines, explicit auth-management grants, invalid-resolver refusal, and passive OAuth consent-state protection |
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
 | `provider-registry.test.ts` | all seven maintained providers inside real deployments: boot, description, address, catalog, storage, credential, admission, and activity isolation; plus provider-specific discovery and guide contracts |
-| `registry.test.ts` | construction and id validation, startup warnings, address resolution, version 2 catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
-| `remote-mcp.test.ts` | `remoteMcp()` against an in-process server through the `_transportFactory` seam: passthrough, downstream `isError`, Workers-safe output-schema validation, request-scoped client reuse and at-most-once scope close; plus the real transport's manual redirect policy, destination guard, credential containment, and downstream session termination |
+| `registry.test.ts` | construction and id validation, startup warnings, bounded absent-grant warning state, address resolution, version 2 catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, broken-connector isolation, and bounded opportunistic memory-storage expiry |
+| `remote-mcp.test.ts` | `remoteMcp()` against an in-process server through the `_transportFactory` seam: passthrough, downstream `isError`, Workers-safe output-schema validation, request-scoped client reuse and at-most-once scope close; plus the real transport's manual redirect policy, destination guard, credential containment, session termination on scope close/rotation/abandonment, bounded JSON-RPC/HTTP error classification, and sanitized transport diagnostics |
 | `remote-mcp-credential.test.ts` | `remoteMcp()` drawing a static key from the connection UI: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, the payload-free activity event, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
 | `remote-mcp-pagination.test.ts` | the `tools/list` cursor chain in both directions — exact cursor handoff, first-wins dedup, a failed later page rejecting rather than returning its prefix, the runaway backstops, the tool-metadata re-prime across pages, and paginated catalogs reaching the discovery path |
 | `request-admission.test.ts` | `/mcp` bounded before auth, the stable 503 and `Retry-After`, health and operator responsiveness under saturation, payload-free counters, queued cancellation, shutdown rejection while active work drains, and the separate fallback code pool |
 | `result-shapes.test.ts` | passive output-shape learning: value-free bounded inference, merging, 256-entry LRU eviction, 24-hour expiry, runtime isolation, read-only admission, declared-schema precedence, definition-change invalidation, discovery provenance, and failure isolation |
 | `revenuecat-provider.test.ts` | the RevenueCat proxy's per-project key scoping and account-wide OAuth guides, its purpose-bearing summary, the refund-preference read and argued borderline verdicts in its digest-free manifest, and the deliberately unclassified `render-paywall-screenshot` |
-| `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory, account titles, on-demand investigation guidance, and no Apps metadata or resource capability → complete usage skill → `call_tool`), conditional guide pointers, open routes, Clerk `.well-known` metadata without network, code mode, removed connector HTTP hooks rejected at construction, and deferred catalog reads through both discovery surfaces |
-| `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: built-in routes and unknown-path 404s inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
+| `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory, account titles, on-demand investigation guidance, and no Apps metadata or resource capability → complete usage skill → `call_tool`), fixed seven-tool registration order across requests, conditional guide pointers, open routes, Clerk `.well-known` metadata without network, code mode, removed connector HTTP hooks rejected at construction, and deferred catalog reads through both discovery surfaces |
+| `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: Origin refusal before admission/auth/redirects, exact-origin and wildcard CORS, SEP-2243 preflight headers, all pool suffixes behind auth, application overload/shutdown codes, id-free health preserving doctor drift counts, built-in routes and unknown-path 404s inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
 | `startup-warnings.test.ts` | every construction-time `logger.warn` and, as importantly, the conditions that must *not* trigger one: open mode with a credential or OAuth connector, `publicUrl` unset beside OAuth, dropped branding and `uiAuth` URLs, a missing `verifyState`, a credential test-hook mismatch, and an unusable `calls.maxResultBytes` |
 | `stripe-provider.test.ts` | the Stripe proxy's mixed-mode OAuth and fixed-mode header contracts, current eleven-tool classifications, admission, exact account selectors, and no-guess rule |
 | `operator-view.test.ts` | the app's pure state rules from `view.ts`: filtering, page routing, capability states, activity summaries, drift display, and identity reset |
 | `ui-credentials.test.ts` | credential-management routes: save, test, delete, validation, authentication, same-origin checks, and multi-field credential shapes |
 | `ui.test.ts` | the server shell and remaining `/ui/*` routes: gated `/ui/data` with broken-connector isolation and registry-owned catalog-observation containment, plus the URL safety gates |
-| `validate.test.ts` | `validateToolInput()` — a returned (not thrown) `invalid_args` naming the path, `additionalProperties: false` enforcement, per-schema validator caching, and an unusable schema passed through with one warning |
+| `validate.test.ts` | `validateToolInput()` — a returned (not thrown) `invalid_args` naming the path, `additionalProperties: false` enforcement, bounded UTF-8 validation detail, per-schema validator caching, and an unusable schema passed through with one warning |
 | `vercel-provider.test.ts` | `vercel()` API and MCP construction, MCP inventory classification, team scoping, project and deployment projections, finite build and runtime logs, value-safe environment variables, domains, lifecycle writes, REST hatches, typed failures, and credential test |
 
 ### Node-bound (`NODE_ONLY_SUITES`)
@@ -292,15 +292,15 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | `doc-links.test.ts` | the documentation checker itself — local file and fragment resolution, repository URLs resolved back to the checkout, duplicate heading slugs, fenced-code exclusion, and useful failures | spawns the Node checker against filesystem fixtures |
 | `doctor-cli.test.ts` | `connecta doctor`'s executor line and credentials end to end — the sandbox the deployment reports is the one named, an unidentifiable executor gets an executor-neutral line, a hostile name is bounded, and a complete Cloudflare Access service-token pair is accepted while a partial pair is refused | spawns the CLI against a Node HTTP deployment over real sockets |
 | `drift-check.test.ts` | the credential-free maintainer drift checker: recorded touched endpoints, heading, table, and inline MCP inventories, setup-only providers, live-schema ownership, a quiet revision bump, clear failures for unavailable inputs, `$ref` traversal, and one well-formed row per endpoint | spawns the checker against filesystem fixtures |
-| `file-storage.test.ts` | `fileStorage()` across instances, logical TTL plus physical pruning without clobbering a newer value, and corrupt-file quarantine | exercises the Node filesystem storage adapter |
+| `file-storage.test.ts` | `fileStorage()` round trips, exclusive writer locks, namespace-aware heartbeat expiry and stale-guard recovery, close/exit cleanup, unique temp files, logical TTL plus physical pruning, and corrupt-file quarantine | exercises the Node filesystem storage adapter |
 | `guest-api-contract-quickjs.test.ts` | the shared guest-contract cases on the real QuickJS executor, including identical caught failure codes and inline describe recovery, its exact absent globals, and blocked runtime imports | runs the contract cases on the Node QuickJS executor |
 | `node.test.ts` | the `listen()` adapter propagating an HTTP client disconnect through the Web `Request` and the MCP handler into a program's connector call, releasing both admission permits | exercises the Node HTTP adapter over real TCP sockets |
 | `packed-links.test.ts` | the packed-link gate itself — shipped targets and repository URLs accepted, relative links into unshipped paths and directories rejected with the citation to write instead, reference definitions seen, fenced examples ignored, the changelog exempt | spawns the Node packed-link gate against filesystem fixtures |
 | `package-surface.test.ts` | the published boundary — built output shipped, the `exports` map carrying exactly the documented subpaths plus `./package.json`, only generic factories, platform storage kept in examples, Clerk and QuickJS behind optional subpaths, dependency-free Cloudflare Access behind its Worker subpath, every provider independently importable, and the Cloudflare API provider free of bare specifiers | walks the package tree with Node filesystem APIs |
 | `purity.test.ts` | the import-graph guardrail ([architecture](./architecture.md#import-graph-purity)) — the core stays Workers-clean | walks the source import graph with Node filesystem APIs |
 | `quickjs-child-entry.test.ts` | a missing QuickJS child entry failing before `fork()`, with the expected path and the bundler-externalization constraint | mocks Node child-process and filesystem APIs |
-| `quickjs-child-stderr.test.ts` | the QuickJS child-process boundary: an explicitly empty environment despite parent secrets and `NODE_OPTIONS`, plus abnormal exits retaining only an 8 KiB stderr tail in the parent-side diagnostic | mocks Node child-process streams |
-| `quickjs-executor.test.ts` | executable usage example with dependent, missing, and approval-required evidence; the child-process sandbox — code normalization, provider bridges and canonical connector calls, bounded IPC, separate guest-CPU and wall budgets, saturation, cancellation and shutdown, crash and OOM recovery, host-call hangs, stalled-promise detection | runs the Node QuickJS child-process executor |
+| `quickjs-child-stderr.test.ts` | the QuickJS child-process boundary: an explicitly empty environment despite parent secrets and `NODE_OPTIONS`, abnormal exits retaining only an 8 KiB stderr tail in the parent-side diagnostic, host-result serialization failure returning a bounded error reply, streamed logs on real child crashes, bounded parent retention, and log recovery on shutdown, deadline termination, and IPC failures | mocks Node child-process streams and runs the Node QuickJS child-process executor |
+| `quickjs-executor.test.ts` | executable usage example with dependent, missing, and approval-required evidence; the child-process sandbox — code normalization, provider bridges and canonical connector calls, private authenticated-failure transport and bounded error details, bounded IPC, separate guest-CPU and wall budgets, saturation, cancellation and shutdown, crash and OOM recovery, host-call hangs, stalled-promise detection, logs preserved on cancellation after a program starts | runs the Node QuickJS child-process executor |
 | `quickjs-log-limits.test.ts` | bounded `console.*` capture — per-entry cut, cumulative character and transport budgets, escape-heavy floods preserving the guest result | runs the Node QuickJS child-process executor |
 | `suite-partition.test.ts` | this partition, including itself: every `*.test.ts` in exactly one list, stale entries and empty reasons refused | walks the test directory to guard the partition |
 | `template-file-activity.test.ts` | the Node template's own activity store — persistence across restart, torn-line repair, newest-first paging, and compaction past the slack window | runs it against real files |

package/documentation/provider-conventions.md

@@ -231,6 +231,13 @@ convenient reading. A call that can only fail is refused locally as
 `invalid_args` before the round trip. Provider error prose is never parsed to
 invent a classification.
 
+An unreachable transport may report `unavailable` with optional sanitized
+`details.host` and `details.code`. The host is an HTTP(S) origin only, at most
+253 UTF-8 bytes; the code is an allowlisted runtime network code or `timeout`,
+at most 32 bytes. Omit what the runtime cannot establish. The typed error
+constructor strips URL credentials, paths, queries, and fragments, and drops
+invalid or oversized fields. Transport diagnostics never enter activity records.
+
 **A downstream 404 is `not_found` — when the provider means it.** The code
 exists because the next move is none of the others': you do not wait, you do
 not send the agent to `authorize_connector`, you do not repair the argument