@zackbart/connecta 0.29.0 → 0.31.0

package/documentation/code-mode.md

@@ -11,6 +11,26 @@ a third executor is implementable from this document alone.
 [`meta-tools.md`](./meta-tools.md) owns the top-level tool contract, and clause
 identifiers (`A1`, `E3`, …) are stable and cited by [Verification](#verification).
 
+## Task routes
+
+For normal endpoint work, start with [Operating an endpoint](./operating.md).
+Use this reference for exact guest behavior or executor implementation.
+[Agent index](./README.md) routes other work.
+
+| Task                                         | Sections                                                                                                                                         |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Wire a shipped or custom executor            | [Deploy-time capability](#deploy-time-capability), [executor requirements](#what-an-executor-must-implement), [exceptions](#executor-exceptions) |
+| Write a portable program                     | [Program form](#the-program), [addresses](#addressing), [guest functions](#the-surface)                                                          |
+| Discover and call tools                      | [Search](#connectasearch), [describe](#connectadescribe), [call](#connectacall), [parallel calls](#parallel-calls)                               |
+| Page results, load skills or read resources  | [Result and skill](#connectaresult-and-connectaskill), [read](#connectaread), [projection](#results-and-projection)                              |
+| Emit incremental output                      | [emit](#connectaemit), [emitted output](#emitted-output)                                                                                         |
+| Handle errors, writes, or cancellation       | [Errors](#errors), [retries](#retry-semantics), [limits](#cancellation-and-limits), [writes](#writes), [activity](#activity)                     |
+| Change the contract or check executor parity | [Verification](#verification), then the tests indexed by clause                                                                                  |
+
+Clause IDs remain stable, including retired IDs. Check current behavior against
+source and the verification table; do not reuse a retired clause to introduce
+new behavior.
+
 ## Deploy-time capability
 
 The `executor` passed to `createConnecta()` is required. `tools/list` is exactly
@@ -333,11 +353,27 @@ const { data: run, format } = await connecta.call("ci.get_run", { runId: 42 });
 **S5.** Takes a canonical address, optional arguments, and optional
 `{ timeoutMs }`; the object form is `{ address, args?, timeoutMs? }`. A malformed
 signature fails with `invalid_args` and both exact signatures, before discovery.
-Returns `{ data, format: "json" | "text" }`. MCP `toolResult` or
+Normally returns `{ data, format: "json" | "text" }`. Oversized values may return
+a `format: "paged"` handle for `connecta.result`, as described in `L6` below.
+MCP `toolResult` or
 `structuredContent` is JSON; all-text content is JSON when it parses, otherwise
 text. API string values are text, other API values are JSON. Check `format`
 before treating `data` as an object. A downstream `isError` throws.
 
+An inline MCP result containing image, audio, resource, or resource_link blocks
+also exposes `content?: GuestNativeBlock[]`, even when `data` comes from
+`structuredContent` or `toolResult`. `data` keeps its existing shape.
+`connecta.emit(result)` forwards all native blocks; iterating `result.content`
+and calling `connecta.emit(block)` forwards selected blocks. Both forward the
+host-retained originals, so guest edits do not change native output. Results
+over the 1 MiB inline cap return paging handles without native content; page
+and reduce them as described in `L6`. If only the native presentation is too
+large or its transfer fails, `data` stays intact and `contentResult` carries
+its paging handle or an unavailable-paging notice for presentation that exceeds
+bounded traversal limits or is cyclic. When a result ID exists,
+`connecta.result(result.contentResult)` pages the original MCP envelope;
+`emit(result)` refuses with `result_too_large`.
+
 **S6.** Every call goes through the same catalog, fail-closed read-only
 predicate, admission, credential containment, timeout classification, health
 accounting, and activity recording as an ordinary meta-tool call. The predicate
@@ -348,11 +384,14 @@ it can reach.
 
 ### connecta.result and connecta.skill
 
-`await connecta.result(id, { offset?, maxBytes? })` reads a stashed direct-call
-result bound to the admitted subject, principal, endpoint/pool, request origin,
+`await connecta.result(handleOrId, { page?, offset?, maxBytes? })` reads a stashed direct-call
+or program-call result bound to the admitted subject, principal, endpoint/pool, request origin,
 connector, and tool. It returns
 `{ resultId, offset, bytes, totalBytes, hasMore, nextOffset?, format: "text", text }`.
-Offsets and sizes are UTF-8 bytes; the page cap is the original call's inline cap.
+Offsets and sizes are UTF-8 bytes. Pages obey the original call's inline cap
+and a 32 KiB bridge ceiling. `page` is zero-based and mutually exclusive with
+`offset`; keep `maxBytes` fixed while incrementing pages. Nominal page windows
+are at least four bytes wide and align both edges to UTF-8 boundaries.
 Follow `nextOffset`, reassemble inside the program, and return a reduced value.
 Before returning a page, the host rechecks current authentication, connector/tool
 grants, pool membership, and endpoint trust against both the original and current
@@ -465,7 +504,9 @@ or upward proxy to programs. Native upward skill resources are separate
 ### connecta.emit
 
 ```js
-await connecta.emit({ type: "image", data: shot.data, mimeType: "image/png" });
+const badge = await connecta.call("assets.get_badge_image", {});
+connecta.emit(badge);
+// Or: for (const block of badge.content ?? []) connecta.emit(block);
 ```
 
 The rich-output channel, delivered after the JSON envelope on success. Its
@@ -477,17 +518,17 @@ clauses are [Emitted output](#emitted-output) (`M1`–`M10`).
 caught or uncaught. Host-call budget exhaustion ends the host run and blocks host
 access (`L4`); Workers guest computation may continue briefly until teardown (`X3`).
 
-| Channel                                                                   | Shape                                                       | Typed? |
-| ------------------------------------------------------------------------- | ----------------------------------------------------------- | ------ |
-| A caught Connecta host failure                                            | `Error` with `message`, `code`, `retryable`, and `details`  | yes    |
-| An uncaught **tool, resource or discovery** failure, as the model sees it | `{ error: { code, message, retryable, … } }` with `isError` | yes    |
-| Program or execution failure (`E5`, `E6`, a bridge bound in `L6`)         | `{ error: { code, message, retryable, details? } }`         | yes    |
+| Channel                                                                   | Shape                                                              | Typed? |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------ |
+| A caught Connecta host failure                                            | `Error` with `message`, `code`, `retryable`, `data`, and `details` | yes    |
+| An uncaught **tool, resource or discovery** failure, as the model sees it | `{ error: { code, message, retryable, … } }` with `isError`        | yes    |
+| Program or execution failure (`E5`, `E6`, a bridge bound in `L6`)         | `{ error: { code, message, retryable, details? } }`                | yes    |
 
 Both executor bridges rebuild typed host rejections as guest Errors and retain
 their identity in executor-owned state (`X11`). `message` stays 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 and fits 3,700 serialized characters. Optional recovery metadata
+`code` and `retryable` are the stable branch fields; `data` and `details` carry the same host
+classification, which fits 3,700 serialized characters. Optional recovery metadata
 that would exceed that bound is omitted whole, preserving `code`, `message`,
 `retryable`, and `retryAfterMs`, because a clipped recovery address or argument
 describes a different call. This covers `call`, `read`, `search`, `describe`, `result`, `skill`, `emit`, and
@@ -497,6 +538,17 @@ HTTP(S) origin of at most 253 UTF-8 bytes, and `details.code`, a validated
 network errno, undici transport code, or `timeout` of at most 32 bytes; neither
 enters activity.
 
+On hosts without URL elicitation, `connecta.call` auth failures carry `recovery`,
+`nextAction`, and the handoff in `error.data`, also exposed as `error.details`.
+An OAuth handoff includes `authorizationUrl` and `instructions`; operator
+credential recovery includes `operatorUrl`, declared credential fields, and
+instructions. `connecta.search` catalog errors and `connecta.describe`
+`errorDetails` carry the same fields. When an auth error includes a handoff, give
+it to the user or operator. One program run reuses one handoff per connector,
+including concurrent call and catalog errors. Errors never request a forced
+restart. Use `authorize_connector` for an explicit connection or a fresh link.
+URL-elicitation hosts retain their existing flow.
+
 **E2.** The taxonomy: `retryable` is what connecta reports, `Y3` what a program
 may do. A provider maps each downstream failure to the code that tells the
 caller what to do next, and never invents a cause it was not told.
@@ -533,8 +585,9 @@ and let the failure reach the model.
 program unless the pool is trusted (`W12`). It is refused with
 `destructive_tool_requires_approval` before validation and before anything is
 sent, `nextAction` carrying its canonical address to `call_destructive_tool`
-plus the original arguments when they fit the 512-byte echo budget — whole or
-not at all, since a clipped copy is a different call. The host's prompt on that
+and a schema-filtered snapshot within the 512-byte echo budget. `argsRedacted`
+marks partial or withheld arguments; use the original arguments if this flag is
+set or `args` is absent. Snapshots are never clipped. The host's prompt on that
 call is the approval, and the only one: generated code can neither mint the
 capability nor approve its own write, and the model's short `reason` grants no
 authority and never goes downstream.
@@ -606,33 +659,45 @@ fields. Program-authored projection saved bytes; host heuristics could drop
 deliberately returned fields. Helpers need [#222](https://github.com/zackbart/connecta/issues/222)
 evidence that programs fail to project.
 
-**R2.** The boundary is 24,000 serialized characters (~6k tokens). A value over
-it is replaced by exactly one envelope:
-
-```json
-{
-  "truncated": true,
-  "preview": "…",
-  "totalChars": 5242880,
-  "hint": "filter/map/slice data inside execute_code and return only what you need"
-}
-```
-
-The envelope is itself bounded as serialized, so `totalChars` is always the true
-size of what the program returned and truncation happens exactly once no matter
-how many hops the value takes.
-
-**R3.** Truncation is a _successful_ result: the program ran but returned too
-much. Run a program that returns less; that is why the envelope says so.
-
-**R4 (verdict: no result paging for programs).** Program results have no
-`connecta.result` handle. A program can shrink its return; paging would reward
-unprojected data.
-
-For non-repeatable writes, inspect and reduce the full result before return,
-or page a direct `call_destructive_tool` result on a trusted endpoint with
-`connecta.result`. Sampling a
-program result may discard the only copy.
+**R2.** The boundary is 24,000 serialized characters (~6k tokens), shared with
+emitted text. An oversized return is stashed as compact JSON through the same
+result store as direct calls. The returned notice carries `truncated`, `resultId`,
+`totalBytes`, `hint`, `nextOffset: 0`, and an executable `nextAction` that pages
+with `connecta.result`. It also retains `totalChars` and a bounded `preview`.
+The recovery action and hint precede the preview, so clients that spill results
+after the first 2,000 characters retain the handle and the instruction.
+Small returns pass through unchanged; Connecta does not select fields.
+
+**R3.** Truncation is a _successful_ result. The program completed and its full
+return can be read without running it again. Prefer filtering or reducing reads
+before returning them. If the run completed a write, the notice opens with
+"This write already ran: do not call it again to see its result."
+This warning uses host accounting for writes completed in this run. Paging an
+earlier write result does not count as a new write.
+
+**R4.** Program returns share direct-call stash envelopes, 15-minute expiry,
+aggregate capacity charges, and credential redaction before persistence.
+Their pages bind the admitted subject, principal, endpoint/pool, origin, and
+all contributing tool calls, resource and skill reads, and catalog metadata.
+Downstream skill and resource dependencies require a whole-connector grant.
+Local guides and catalog dependencies require visibility of the contributing connector or tool, even
+when the metadata describes a write on a read-only endpoint.
+Caught call failures retain that connector visibility when catalog loading or
+tool resolution fails. Recovery messages listing configured connectors or
+local guides retain visibility of those contributors too.
+Each page rechecks current auth,
+grants, pool membership, and trust. Reading a stash inside a program carries
+its dependencies forward to any new return stash. The page cap is the smallest
+of the deployment cap and contributing connectors' effective `maxResultBytes`.
+Read-only endpoints cannot page write results. A UUID is a handle, never a grant.
+
+If paging is unavailable because the stash is full, storage fails, or text
+cannot round-trip as UTF-8, the successful return keeps the existing bounded
+`{ truncated, preview, totalChars, hint }` fallback. Its hint explains that
+paging is unavailable and retains the instruction to filter/map/slice. A write's
+hint still says it already ran. Never rerun a write to recover its output.
+JSON serialization preserves lone surrogates as escapes, so ordinary
+JSON-returning programs can page them losslessly.
 
 **R5.** `console.log`, `console.warn`, and `console.error` are captured in call
 order and returned as one `logs` string, capped at 4,000 characters with a
@@ -665,17 +730,37 @@ request; it is not activity, a session, or a stream.
 
 ## Emitted output
 
-Images accept only `image/png`, `image/jpeg`, `image/gif`, or `image/webp`
+Guest-authored images accept only `image/png`, `image/jpeg`, `image/gif`, or `image/webp`
 and nonempty canonical base64. Whitespace, URL-safe alphabets, bad padding,
 and nonzero pad bits are rejected before collection. Size budgets still apply.
 
 MCP-native output a return value cannot carry: base64 is not projectable, so a
-block that survives intake uncapped (`S5`) must not die at the `R2` exit guard.
+block that fits the inline call limit (`S5`, `L6`) can use the separate
+emission transport budget instead of the `R2` return guard.
 The earlier alternatives are in [decision history](https://github.com/zackbart/connecta/blob/main/decisions/0001-ethos-verdict-table.md)
 ([#267](https://github.com/zackbart/connecta/issues/267),
 [#270](https://github.com/zackbart/connecta/issues/270)).
 
-**M1.** `connecta.emit(block)` accepts exactly one block: `{ type: "text",
+**M1.** `connecta.emit(result)` accepts a rich result from this program's
+`connecta.call` and forwards its original native content blocks, including
+resources, resource links, annotations and `_meta`. `connecta.emit(block)` also
+accepts individual entries of that result's `content`. The trusted guest
+prelude maps these objects to opaque request-local references; the host checks
+those references and emits owned deep snapshots of retained native blocks taken
+before result paging can yield. Oversized structured data returns its paging
+handle before native presentation is inspected. Presentation traversal stops at
+64 levels, 32,768 values, or the larger of the default and configured emission
+byte budgets. Only envelopes within the 1 MiB inline cap retain block snapshots.
+Cycles, non-JSON values, and traversal limits refuse presentation with an
+unavailable-paging notice; structured data remains usable. That notice has no
+result ID and reports `totalBytes: 0` because traversal could not measure a
+complete JSON value.
+Connector mutations after retention cannot change guest output, accepted blocks,
+or their byte and text charges, including nested resource fields and metadata.
+Copies and guest-authored blocks keep the strict validation below. No program
+can mint a native URI.
+
+Guest-authored `connecta.emit(block)` accepts exactly one block: `{ type: "text",
 text }` or `{ type: "image" | "audio", data /* base64 */, mimeType }`, every
 field a string, no extra fields, no `annotations`, no `_meta`, no sugar forms.
 An invalid block throws catchably and nothing is accepted — rejected, not
@@ -692,6 +777,8 @@ presentation, not a second data channel.
 serialized block size reduces the return budget, and oversized text fails with
 `result_too_large`. Image/audio blocks use the separate transport budget and
 reach the model as real MCP media content, including when `emit` is not awaited.
+Native embedded resource text also shares the result cap; resource blobs count
+against the serialized-byte emission budget.
 The trusted runner waits for emission acknowledgments before returning success.
 An unobserved emission failure fails the run; an awaited failure remains catchable.
 Rejections propagated through `then` or `finally` can be caught later in that
@@ -703,7 +790,8 @@ chain. A separate unhandled branch still fails the run.
 **M5.** Two budgets (`ConnectaConfig.execute.maxEmittedBytes` /
 `.maxEmittedBlocks`, defaults 4,000,000 serialized bytes and 32 blocks) fail
 loudly at the `emit` call, naming the budget and the room remaining; nothing is
-partially accepted and prior blocks stand. Accepted and rejected emission attempts
+partially accepted and prior blocks stand. Forwarding a whole native result
+checks every block before accepting any of them. Accepted and rejected emission attempts
 also have a terminal limit of four times the configured block cap (at least 128),
 which bounds retained host failures and guest acknowledgement state without
 discarding an older error identity. No result stash for emitted blocks: the program
@@ -712,14 +800,15 @@ bound, not a context bound — emitted media reaches the model as media, not
 base64 text.
 
 **M6.** No provenance is claimed: every emitted block is program output, trusted
-exactly as much as the return value. Preservation is re-emission of the raw
-downstream block, so `S5`'s uncapped fallthrough is contract.
+exactly as much as the return value. Native forwarding preserves the raw
+downstream block through a host-issued reference, within `S5`, `L6` and `M5`.
 
 **M7.** `emit` alone spends no host-call budget (`L4`); `search`, `describe`,
 `call`, `read`, `result`, and `skill` share it. Text also observes `R2`.
 
-**M8.** `emit` is a provider function; blocks cross the guest boundary once as
-an argument. `ExecuteResult` remains compatible with upstream codemode's types;
+**M8.** `emit` is a provider function. Guest-authored blocks cross as arguments;
+native blocks cross once as call output and emissions send only their references.
+Native call output uses the same bounded stash transfers as `L6`. `ExecuteResult` remains compatible with upstream codemode's types;
 construction requires the Worker adapter or explicit custom opt-in. Any executor
 that bridges provider calls gets emission for free.
 
@@ -834,13 +923,34 @@ the Dynamic Worker inherits the platform isolate's limits (`X2`). A third
 executor must bound all three somehow — this is the clause that makes untrusted
 code safe to run at all.
 
-**L6.** A host call's serialized arguments and its serialized result are each
-bounded — QuickJS caps both at 256 KiB (`X10`) — and exceeding either fails that
-call, not the execution, so a program can catch it and ask for less. The failure
-is executor-owned untyped text, not a Connecta host failure (`E1`). An
-over-bound _result_ names the address the program called rather than only the
-generic bridge function; an over-bound _argument_ payload is refused before it
-is parsed, so it names no address at all.
+**L6.** QuickJS bounds each serialized host-call message at 256 KiB. Full guest
+returns cross bounded 65,536-character IPC chunks, with a 64 MiB aggregate
+transport ceiling. The parent retains the completed value until it can apply
+the result stash policy; the 1 MiB per-message IPC ceiling stays in force. Oversized
+`connecta.call` results use the existing direct-call stash before crossing that
+bridge. The trusted guest initializer reconstructs values up to 1 MiB from
+bounded pages, retaining JSON versus text format and every payload code point,
+including U+FEFF at page starts. Larger values return a
+`{ format: "paged", valueFormat, resultId, totalBytes, truncated: true, hint }`
+handle. Pass the handle or its `resultId` to `connecta.result` and reduce the
+pages before returning them. Automatic transfers spend no additional host-call
+budget; explicit paging does. This policy is shared by QuickJS, Worker and custom
+executors that run provider preludes.
+Oversized raw text containing unpaired UTF-16 surrogates returns a handle without
+`resultId`, with a notice that it cannot be paged as text. This preserves the
+UTF-8 byte-offset contract without silently replacing code units. The completed
+call stays successful, including write accounting; JSON-wrapped strings still
+round-trip losslessly.
+
+Stashes retain their existing bindings, 15-minute expiry, per-connector page
+caps and aggregate capacity charges on memory, SQLite and D1. Capacity exhaustion
+or a storage failure returns a successful notice without a `resultId`. A failed
+automatic reconstruction retains the handle. Neither result path reissues the
+call or changes a completed write into a failed or unknown write. Guest returns use the same store when they exceed the presentation cap (`R2`–`R4`).
+
+Over-bound arguments and other unpaged bridge results still fail catchably with
+executor-owned text. An over-bound result names the called address; an argument
+payload is refused before parsing and names no address.
 
 **L7.** Executions are admitted, not queued indefinitely: bounded concurrency
 plus a bounded queue with a wait timeout. Overload is a retryable
@@ -948,6 +1058,15 @@ transport failure leaves the outcome unknown.
 addition to the host-call budget. It is checked after argument validation and
 before admission, so an over-budget write spends no permit.
 
+Program `uncertainCall` and `uncertainCalls` use the same schema-filtered argument
+snapshots as direct calls, even when guest code catches the failure. `argsRedacted: true`
+means sensitive fields were omitted or the entire echo was withheld because
+sensitivity could not be resolved. `argsOmitted: true` means no `args` is present,
+including echoes above the byte budget. These fields identify targets for
+reconciliation. Any new call must use the original arguments when its echo is
+partial or absent. A returned `writes` count cannot make a run safe to repeat.
+See [argument echo rules](./meta-tools.md#echo-budgets) for supported schema shapes.
+
 **W12.** `trusted` endpoints annotate `execute_code` as a write and permit
 program writes. `read-only` endpoints annotate it as read-only and refuse
 program writes before validation, with `call_destructive_tool` as the recovery.
@@ -1025,7 +1144,7 @@ reasonable demand on a platform sandbox.
 values through a tagged envelope, so a `Uint8Array` may survive there. `P3` is
 the contract: JSON-serializable values, or the program is Workers-only.
 
-**X8. Unknown properties.** The guest namespace exposes only the six documented
+**X8. Unknown properties.** The guest namespace exposes only the seven documented
 functions. Unknown and inherited members are absent on both executors; calling
 one is a guest `TypeError` under `E6`. Engine message text is not contract.
 
@@ -1037,13 +1156,11 @@ Normalizing that would spend real CPU on every program to improve the error
 message of a program that is already wrong. `P3` is the contract: neither
 behavior returns the value.
 
-**X10. Per-host-call payload bound.** `L6`'s 256 KiB ceiling on a host call's
-arguments and result is QuickJS's, enforced at its IPC boundary. The Dynamic
-Worker has no documented equivalent; Workers RPC limits apply and connecta adds
-none, because that boundary is an isolate-to-isolate call rather than a
-`process.send` with a hard ceiling. A program returning a quarter-megabyte from
-one tool call therefore fails on Node and may succeed on Workers — reduce inside
-the program either way (`R1`).
+**X10. Per-host-call payload bound.** QuickJS enforces `L6`'s 256 KiB message
+ceiling at its IPC boundary. The Dynamic Worker uses Workers RPC limits.
+Connecta's shared program result policy keeps call results and result pages
+within the QuickJS message ceiling on every executor. It does not raise the
+argument limit or the guest's heap, CPU, execution, or returned-result limits.
 
 **X12** described a paused sandbox and left with pausing
 ([#672](https://github.com/zackbart/connecta/issues/672)); the id stays retired.
@@ -1076,49 +1193,49 @@ Titles name clauses; executor-independent clauses run in both arms.
 `test/codemode-compat.test.ts` pins upstream shape compatibility, minified upstream
 rejection, and branded adapter acceptance across module copies.
 
-| Clauses           | Test                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `P1`, `P5`        | both guest-contract executors (TypeScript syntax, trailing terminators, wrapper recovery), `test/program-source.test.ts` (which semicolons and wrappers are recovered), `test/quickjs-executor.node.test.ts` (`normalizeCode`)                                                                                                                                                                                                                                                                                                  |
-| `P2`, `X5`        | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.node.test.ts` (exact absent globals and blocked imports), `test/quickjs-child-stderr.node.test.ts` (a child-process environment holding only `TZ=UTC`), `test/deployment-shapes.node.test.ts` (loader-only Worker construction)                                                                                                                 |
-| `P3`, `X9`        | `test/guest-api-contract.test.ts`, `test/execute.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `P4`              | `test/guest-api-contract.test.ts` (no cross-run leakage), `test/execute.test.ts` (one catalog load per connector per execution)                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `A1`, `A2`        | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (canonical addressing), `test/server.test.ts` (bounded live connector inventory)                                                                                                                                                                                                                                                                                                                                                                                      |
-| `S1`, `S1a`, `S2` | `test/guest-api-contract.test.ts` (flat page, connector guides, schema keys, unfiltered browse), `test/execute.test.ts` (guide pagination/partial/no-match behavior and `$ref`/`allOf`), `test/meta-tools-search.test.ts` (mixed complete/partial ranking, stable pagination, the two safety classes), `test/typescript-signatures.test.ts` (the TypeScript format over provider and pathological schemas, search/describe parity, observed labeling), `test/typescript-signatures-parse.node.test.ts` (every rendering parses) |
-| `S3`              | `test/guest-api-contract.test.ts` (typed uncaught bound), `test/execute.test.ts` (count limits, fan-out bound)                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `S4`              | both guest-contract executors (ordered mixed describe results with unknown-address, unknown-tool suggestion, and catalog-failure details), `test/meta-tools-search.test.ts` (top-level routing, no-suggestion, catalog-failure, and hostile-input bounds)                                                                                                                                                                                                                                                                       |
-| `S5`, `S6`        | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`, 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, removed-function, and forgery cases; typed promise rejections), `test/quickjs-executor.node.test.ts` (oversized messages, private transport, forged outcomes)                                                                                                                                                                                                                                                                                                   |
-| `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, failure isolation)                                                                                                                                                                                                                                                                      |
-| `S10`             | `test/resource-read.test.ts` (qualified routing, whole-connector grants, personal credentials, redaction, admission, timeout, cancellation and downstream MCP reads), both guest-contract executors (successful resource reads and caught/uncaught typed failures)                                                                                                                                                                                                                                                              |
-| `E2`, `E8`        | `test/guest-api-contract.test.ts` (code → `retryable`, caught, parallel, and uncaught validation recovery, a conflict's bounded `current`), `test/meta-tools-call.test.ts` (direct, destructive, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts`                                                                                                                                                                                                                             |
-| `E3`, `E4`        | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`, destructive reroute), `test/program-writes.test.ts` (the refusal's `nextAction`, nothing sent, a caught refusal)                                                                                                                                                                                                                                                                                                                                    |
-| `E5`              | `test/guest-api-contract.test.ts` (execution-failure channel, in-flight `cancelled`), `test/execute.test.ts` (admission), `test/executor-admission.test.ts`, `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                            |
-| `E6`, `X8`        | `test/guest-api-contract.test.ts` (unknown and inherited members, retained error identities), `test/quickjs-executor.node.test.ts`                                                                                                                                                                                                                                                                                                                                                                                              |
-| `E7`              | `test/guest-api-contract.test.ts` (refusals about a `503`-named connector), `test/errors.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `R1`, `R2`, `R3`  | `test/guest-api-contract.test.ts` (pass-through, truncation is success, envelope fits the cap and is idempotent)                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `R4`, `M6`, `M9`  | verdicts; `R2`'s guard, `M1`'s strict typing, and `M2`'s collect-then-deliver are their enforcement                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `R5`              | `test/guest-api-contract.test.ts`, `test/quickjs-log-limits.node.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `R6`–`R8`         | `test/guest-api-contract.test.ts` (normal result keys), `test/execute.test.ts` (opt-in operation aggregates, failure paths, payload exclusion)                                                                                                                                                                                                                                                                                                                                                                                  |
-| `Y1`, `Y2`, `Y3`  | `test/guest-api-contract.test.ts` (one attempt per call, retryable flags by code)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `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, discovery included, and refuses discovery after the run; a cancelled wedged executor, or one whose `acquire()` ignores the signal, returns promptly and releases its lease)                                                                                                                                                                                                                       |
-| `L3`, `X1`        | `test/guest-api-contract.test.ts` (short-deadline executors), `test/execute.test.ts` (the watchdog ends a never-settling executor, frees the default pool, spares a slow run, and falls back from an unusable value)                                                                                                                                                                                                                                                                                                            |
-| `L4`, `L8`        | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (shared discovery/call budgets and terminal catch-and-continue loops and queued-write cancellation on both executors), `test/worker-budget-response.node.test.ts` (native handle disposal and admission recovery across completed HTTP responses)                                                                                                                                                                                                                     |
-| `L5`, `L7`, `X2`  | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue)                                                                                                                                                                                                                                                                                                                                                                                    |
-| `L6`, `X10`       | `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.node.test.ts` (outer reply serialization failure settles the call)                                                                                                                                                                                                                                                                                                     |
-| `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, the identity clamp, the one-attempt floor), `test/operator-view.test.ts`, `test/sql-storage-contract.ts`, run by `test/d1-storage.node.test.ts` and `test/sqlite-storage.node.test.ts` (historical pause and approval rows still render and round-trip)                              |
-| `V5`, `W9`        | `test/program-writes.test.ts` (an unawaited trusted-pool write finished and recorded, its unknown outcome reported, counts on a failed program, the classification table), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                                |
-| `W10`, `W12`      | `test/program-writes.test.ts` (a trusted-pool write runs and every other write keeps `E4`, the write budget, pool trust and override precedence, `call_tool` still refusing, search and describe verdicts, construction refusals), `test/operator-ui-model.test.ts`, `test/browser/operator-ui.spec.ts` (the badge)                                                                                                                                                                                                             |
-| `M1`              | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (every rejected shape)                                                                                                                                                                                                                                                                                                                                                                                           |
-| `M2`, `M3`        | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path)                                                                                                                                                                                                                                                                                                                                             |
-| `M4`              | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths), `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                                                                       |
-| `M5`, `M7`        | `test/execute-emit.test.ts` (both budgets fail the crossing block; host-call budget untouched)                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `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)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `X4`              | `test/guest-api-contract.test.ts` (string logs only), `test/quickjs-executor.node.test.ts` (logs before cancellation), `test/quickjs-child-stderr.node.test.ts` (crash, shutdown, deadline, IPC failure, bounded parent retention), `test/quickjs-log-limits.node.test.ts` (unchanged successful logs)                                                                                                                                                                                                                          |
-| `X3`, `X6`        | `test/quickjs-executor.node.test.ts` (cancels a running child, never-settling await), `test/execute.test.ts` (a wedged executor stops being awaited)                                                                                                                                                                                                                                                                                                                                                                            |
-| `X7`              | `P3`'s tests; the Workers superset is deliberately unused                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| Clauses                | Test                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `P1`, `P5`             | both guest-contract executors (TypeScript syntax, trailing terminators, wrapper recovery), `test/program-source.test.ts` (which semicolons and wrappers are recovered), `test/quickjs-executor.node.test.ts` (`normalizeCode`)                                                                                                                                                                                                                                                                                                  |
+| `P2`, `X5`             | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.node.test.ts` (exact absent globals and blocked imports), `test/quickjs-child-stderr.node.test.ts` (a child-process environment holding only `TZ=UTC`), `test/deployment-shapes.node.test.ts` (loader-only Worker construction)                                                                                                                 |
+| `P3`, `X9`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `P4`                   | `test/guest-api-contract.test.ts` (no cross-run leakage), `test/execute.test.ts` (one catalog load per connector per execution)                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `A1`, `A2`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (canonical addressing), `test/server.test.ts` (bounded live connector inventory)                                                                                                                                                                                                                                                                                                                                                                                      |
+| `S1`, `S1a`, `S2`      | `test/guest-api-contract.test.ts` (flat page, connector guides, schema keys, unfiltered browse), `test/execute.test.ts` (guide pagination/partial/no-match behavior and `$ref`/`allOf`), `test/meta-tools-search.test.ts` (mixed complete/partial ranking, stable pagination, the two safety classes), `test/typescript-signatures.test.ts` (the TypeScript format over provider and pathological schemas, search/describe parity, observed labeling), `test/typescript-signatures-parse.node.test.ts` (every rendering parses) |
+| `S3`                   | `test/guest-api-contract.test.ts` (typed uncaught bound), `test/execute.test.ts` (count limits, fan-out bound)                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `S4`                   | both guest-contract executors (ordered mixed describe results with unknown-address, unknown-tool suggestion, and catalog-failure details), `test/meta-tools-search.test.ts` (top-level routing, no-suggestion, catalog-failure, and hostile-input bounds)                                                                                                                                                                                                                                                                       |
+| `S5`, `S6`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`, 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, removed-function, and forgery cases; typed promise rejections), `test/quickjs-executor.node.test.ts` (oversized messages, private transport, forged outcomes)                                                                                                                                                                                                                                                                                                   |
+| `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, failure isolation)                                                                                                                                                                                                                                                                      |
+| `S10`                  | `test/resource-read.test.ts` (qualified routing, whole-connector grants, personal credentials, redaction, admission, timeout, cancellation and downstream MCP reads), both guest-contract executors (successful resource reads and caught/uncaught typed failures)                                                                                                                                                                                                                                                              |
+| `E2`, `E8`             | `test/guest-api-contract.test.ts` (code → `retryable`, caught, parallel, and uncaught validation recovery, a conflict's bounded `current`), `test/meta-tools-call.test.ts` (direct, destructive, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts`                                                                                                                                                                                                                             |
+| `E3`, `E4`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`, destructive reroute), `test/program-writes.test.ts` (the refusal's `nextAction`, nothing sent, a caught refusal)                                                                                                                                                                                                                                                                                                                                    |
+| `E5`                   | `test/guest-api-contract.test.ts` (execution-failure channel, in-flight `cancelled`), `test/execute.test.ts` (admission), `test/executor-admission.test.ts`, `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                            |
+| `E6`, `X8`             | `test/guest-api-contract.test.ts` (unknown and inherited members, retained error identities), `test/quickjs-executor.node.test.ts`                                                                                                                                                                                                                                                                                                                                                                                              |
+| `E7`                   | `test/guest-api-contract.test.ts` (refusals about a `503`-named connector), `test/errors.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `R1`, `R2`, `R3`, `R4` | `test/guest-api-contract.test.ts` and `test/guest-api-contract-quickjs.node.test.ts` (small pass-through, shared return paging and unavailable fallback, no repeated writes, live authority), `test/program-result-cases.ts` (reconstruction, redaction, notice survives a 2,000-character spill)                                                                                                                                                                                                                               |
+| `M6`, `M9`             | verdicts; `R2`'s guard, `M1`'s strict typing, and `M2`'s collect-then-deliver are their enforcement                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `R5`                   | `test/guest-api-contract.test.ts`, `test/quickjs-log-limits.node.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `R6`–`R8`              | `test/guest-api-contract.test.ts` (normal result keys), `test/execute.test.ts` (opt-in operation aggregates, failure paths, payload exclusion)                                                                                                                                                                                                                                                                                                                                                                                  |
+| `Y1`, `Y2`, `Y3`       | `test/guest-api-contract.test.ts` (one attempt per call, retryable flags by code)                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `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, discovery included, and refuses discovery after the run; a cancelled wedged executor, or one whose `acquire()` ignores the signal, returns promptly and releases its lease)                                                                                                                                                                                                                       |
+| `L3`, `X1`             | `test/guest-api-contract.test.ts` (short-deadline executors), `test/execute.test.ts` (the watchdog ends a never-settling executor, frees the default pool, spares a slow run, and falls back from an unusable value)                                                                                                                                                                                                                                                                                                            |
+| `L4`, `L8`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (shared discovery/call budgets and terminal catch-and-continue loops and queued-write cancellation on both executors), `test/worker-budget-response.node.test.ts` (native handle disposal and admission recovery across completed HTTP responses)                                                                                                                                                                                                                     |
+| `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue)                                                                                                                                                                                                                                                                                                                                                                                    |
+| `L6`, `X10`            | `test/guest-api-contract-quickjs.node.test.ts` and `test/guest-api-contract.test.ts` (whole oversized reads and one-write pageable handles), `test/sqlite-storage.node.test.ts` and `test/d1-storage.node.test.ts` (shared stash transfers), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.node.test.ts` (outer reply serialization failure settles the call)                                                        |
+| `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, the identity clamp, the one-attempt floor), `test/operator-view.test.ts`, `test/sql-storage-contract.ts`, run by `test/d1-storage.node.test.ts` and `test/sqlite-storage.node.test.ts` (historical pause and approval rows still render and round-trip)                              |
+| `V5`, `W9`             | `test/program-writes.test.ts` (an unawaited trusted-pool write finished and recorded, its unknown outcome reported, counts on a failed program, the classification table), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                                |
+| `W10`, `W12`           | `test/program-writes.test.ts` (a trusted-pool write runs and every other write keeps `E4`, the write budget, pool trust and override precedence, `call_tool` still refusing, search and describe verdicts, construction refusals), `test/operator-ui-model.test.ts`, `test/browser/operator-ui.spec.ts` (the badge)                                                                                                                                                                                                             |
+| `M1`                   | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (rejected shapes, bounded native snapshots, paging before metadata traversal, and cyclic presentation refusal)                                                                                                                                                                                                                                                                                                   |
+| `M2`, `M3`             | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path)                                                                                                                                                                                                                                                                                                                                             |
+| `M4`                   | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths), `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                                                                       |
+| `M5`, `M7`             | `test/execute-emit.test.ts` (both budgets fail the crossing block; host-call budget untouched)                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `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)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `X4`                   | `test/guest-api-contract.test.ts` (string logs only), `test/quickjs-executor.node.test.ts` (logs before cancellation), `test/quickjs-child-stderr.node.test.ts` (crash, shutdown, deadline, IPC failure, bounded parent retention), `test/quickjs-log-limits.node.test.ts` (unchanged successful logs)                                                                                                                                                                                                                          |
+| `X3`, `X6`             | `test/quickjs-executor.node.test.ts` (cancels a running child, never-settling await), `test/execute.test.ts` (a wedged executor stops being awaited)                                                                                                                                                                                                                                                                                                                                                                            |
+| `X7`                   | `P3`'s tests; the Workers superset is deliberately unused                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 
 The surface itself is checked by `test/server.test.ts` (the exact six-tool list),
 `test/code-first-surface.test.ts` (construction, executor, removed tools, copy, and size),