@zackbart/connecta 0.28.1 → 0.30.0

package/documentation/code-mode.md

@@ -1,23 +1,41 @@
 # Code mode — the guest API contract
 
-The normative description of what a program written for `execute_code` is
-promised: what it can reach, what it gets back, how failures look, what it may
-retry, what bounds it runs under, and what it leaves behind in activity. It is
-specified in prose first and implemented second.
-
-Two executors implement it: QuickJS in a child process on Node, and
-`DynamicWorkerExecutor` from `@cloudflare/codemode` on Workers. Divergence is a
-bug unless it appears in [Executor exceptions](#executor-exceptions), which
-names the reason; a third executor is implementable from this document alone.
-[`ethos.md`](../ethos.md) carries the verdicts behind the shape,
+The `execute_code` contract: capabilities, results, failures, retries, limits,
+and activity. Specified in prose first, implemented second.
+
+Two executors implement it: QuickJS in a Node child process and `workerExecutor()`
+from `@zackbart/connecta/worker` around upstream `DynamicWorkerExecutor` on Workers.
+Divergence is a bug unless explained in [Executor exceptions](#executor-exceptions);
+a third executor is implementable from this document alone.
+[`PRINCIPLES.md`](https://github.com/zackbart/connecta/blob/main/PRINCIPLES.md) states the invariants,
 [`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
-seven — `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`,
-`authorize_connector`, `get_result`, and `skills`. Construction fails when the
+six — `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`,
+`authorize_connector` and `skills`. Construction fails when the
 executor is missing, and the removed `surface` option is rejected rather than
 ignored ([#273](https://github.com/zackbart/connecta/issues/273)), as are the
 pause-only `execute.resumableWrites` and `execute.pausedRunTtlSeconds`
@@ -33,26 +51,37 @@ import { quickJsExecutor } from "@zackbart/connecta/quickjs";
 createConnecta({ executor: quickJsExecutor() /* connectors, auth, storage… */ });
 ```
 
-`quickJsExecutor()` runs each program in a disposable child-process sandbox; its
-CPU, wall-time, memory, stack, queue, result, log, and IPC bounds are configured
-on the executor. Server bundlers must keep the `@zackbart/connecta/quickjs`
-package files external so the child entry stays on disk. The
-[Node template](../templates/node/README.md) carries the complete setup.
+`quickJsExecutor()` runs each program in a disposable child process, with CPU,
+wall-time, memory, stack, queue, result, log, and IPC bounds on the executor.
+Keep `@zackbart/connecta/quickjs` external in server bundles so the child entry
+stays on disk. The [Node template](../templates/node/README.md) has the full setup.
 
-On Cloudflare Workers the Worker Loader binding is the sandbox, and Dynamic
-Workers require the Workers Paid plan:
+On Workers the Worker Loader is the sandbox; Dynamic Workers require the Paid plan:
 
 ```ts
-createConnecta({ executor: new DynamicWorkerExecutor({ loader: env.LOADER }) });
+import { workerExecutor } from "@zackbart/connecta/worker";
+
+createConnecta({ executor: workerExecutor({ loader: env.LOADER }) });
 ```
 
-The supported constructor passes only `loader`; `bindings`, `modules`, or
-`globalOutbound` grant ambient guest authority and violate `P2`. The
-[Worker example](../examples/worker/README.md#code-mode) has the full setup.
+The adapter uses only `loader` and an optional `timeout`. Its admission defaults
+are two active runs, eight queued runs, and a five-second queue deadline, settable
+through `admission`. Lease release disposes RPC and loader handles independently
+of guest settlement. `bindings`, `modules`, or `globalOutbound` violate `P2`.
+The [Worker example](../examples/worker/README.md#code-mode) has the full setup.
+
+Replace `import { DynamicWorkerExecutor } from "@cloudflare/codemode";` with
+`import { workerExecutor } from "@zackbart/connecta/worker";` and use the wiring above.
+Keep the peer. Unbranded executors throw, including bundled upstream copies.
+Shipped executors carry a non-enumerable `Symbol.for("connecta.executor")` version/lifecycle brand.
+Custom sandboxes import `customExecutor` from `@zackbart/connecta`, then configure
+`executor: customExecutor(myExecutor, { lifecycle: "self-managed" })`. They own guest termination
+and cleanup at budget exhaustion, cancellation, and deadlines; the wrapper only delegates methods.
 
 ## What an executor must implement
 
-The host side of the seam is two types in `src/types.ts` and nothing else.
+The Promise provider/result seam lives in `src/types.ts`. Custom implementations
+also need the lifecycle wrapper above; structural compatibility alone is insufficient.
 
 ```ts
 interface Executor {
@@ -70,6 +99,8 @@ interface ExecutorProvider {
 interface ExecuteResult {
   result: unknown;      // the program's resolved value
   error?: string;       // set instead of result when the run failed
+  failure?: { name: string; line?: number; call?: CallErrorDetails;
+    timeout?: { elapsedMs: number; deadlineMs: number } };
   logs?: string[];      // captured console output, in call order
 }
 ```
@@ -78,34 +109,38 @@ Connecta passes exactly one provider, named `connecta`. An executor must:
 
 1. **Expose each provider as a guest global** whose properties are its `fns`,
    called with the program's arguments and awaited. Connecta supplies `search`,
-   `describe`, `call`, and `emit`.
+   `describe`, `call`, `read`, `result`, `skill`, and `emit`.
 2. **Evaluate `prelude` after the provider globals exist and before the
-   program.** It is trusted host code; connecta uses it to restore typed host
-   errors without exposing the private error frame.
+   program.** It is trusted host code that installs the immutable namespace
+   and waits for emission acknowledgements. Capture runner intrinsics first;
+   privileged initialization must be single-use.
 3. **Marshal values as JSON** both directions (`P3`), and reject a host call
    whose function is not an own property of `fns` — the guest can ask for
    inherited members too.
-4. **Return, never throw, for a failed program**: set `error` to the guest's
-   message, leave `result` undefined. `createExecuteTool` reads `error` first and
-   matches it back to the failures recorded during the run, which is how an
-   uncaught tool failure keeps its type (`E1`).
+4. **Return, never throw, for a failed program.** Set `error` and leave
+   `result` undefined. Rebuild a rejected host `InvocationFailure` as a guest
+   Error with `code`, `retryable`, and `details`, and retain its identity in
+   executor-owned state. If that same Error escapes the program, return its
+   typed details in `failure.call`. A wrapped or copied Error is `program_error`.
+   Construct outcomes through the host-owned RPC return or QuickJS host bridge,
+   never by parsing guest stdout, prints, returned values, or thrown look-alikes.
+   No secret held in the guest realm authenticates anything. Guest module
+   specifiers must not resolve runner internals, including dynamic imports.
+   For compilation failures, return `failure: { name, line? }`. For a sandbox
+   timeout, add `failure.timeout: { elapsedMs, deadlineMs }`.
 5. **Capture `console.log`, `console.warn`, and `console.error`** into `logs` in
    call order (`R5`), bounding what it retains.
-6. **Bound the guest**: wall clock, memory, stack, and CPU (`L3`, `L5`), staying
-   inside the tested `P2`/`X5` boundary. Settle `execute()` on your own
-   deadline: connecta stops waiting at `execute.watchdogMs` and reports the
-   sandbox unresponsive (`L3`).
-7. **Grant no ambient authority of its own.** Never back this with `eval` or
-   `node:vm`: the sandbox is a containment layer on top of connecta's boundary,
-   not a replacement for it, and every capability arrives through `fns`.
-
-Optionally implement `AdmittingExecutor` (`acquire()` returning a lease whose
-`execute` runs once) for bounded admission (`L7`) and `close()` for shutdown;
-connecta wraps a plain `Executor` with `withExecutorAdmission` otherwise. The
-optional `name` — else a class's constructor name, which a minifier may rewrite
-— is the executor name `/health` and `connecta doctor` report.
-[Emitted output](#emitted-output) asks nothing of an executor: `connecta.emit`
-is just another provider function (`M8`).
+6. **Bound the guest**: wall clock, memory, stack, and CPU (`L3`, `L5`), within
+   `P2`/`X5`. Settle `execute()` on your own deadline; connecta stops waiting
+   at `execute.watchdogMs` and reports the sandbox unresponsive (`L3`).
+7. **Grant no ambient authority.** Never use `eval` or `node:vm`: sandboxing
+   supplements connecta's boundary; every capability arrives through `fns`.
+
+Optional `AdmittingExecutor.acquire()` returns a once-executed lease for bounded
+admission (`L7`); otherwise connecta uses `withExecutorAdmission`. `close()` handles
+shutdown. `/health` and `connecta doctor` report `name`, falling back to the
+constructor name, which minifiers may rewrite. [Emission](#emitted-output) is
+another provider function (`M8`).
 
 ## The program
 
@@ -120,7 +155,7 @@ statements, and bare statement bodies are outside host recovery. QuickJS may
 wrap a bare body when driven directly; that is outside the portable contract.
 
 **P2.** The only capabilities in the contract are `connecta.search`,
-`connecta.describe`, `connecta.call`, `connecta.emit`, and `console.log` /
+`connecta.describe`, `connecta.call`, `connecta.read`, `connecta.result`, `connecta.skill`, `connecta.emit`, and `console.log` /
 `console.warn` / `console.error`, captured and returned. Anything else a runtime
 exposes is outside the portable contract and must not be used. QuickJS grants
 none of it. A loader-only Dynamic Worker denies external egress and filesystem
@@ -163,10 +198,10 @@ belonged to shortcut dispatch and stay retired; nothing reuses those ids.
 
 ## The surface
 
-Four functions, all `async`: `search`, `describe`, `call`, and `emit`. Nothing
-else works. Reading any other property yields a function — the guest namespace
-is a Proxy, so `typeof connecta.toString` is `"function"` — but *calling* it
-fails, because the host resolves only own members of the provider's `fns`.
+Seven functions: `search`, `describe`, `call`, `read`, `result`, `skill`, and `emit`.
+All return awaitable values; emission also works without `await`. The namespace
+has no inherited members. Unknown properties are undefined, and calling them
+fails as a guest `TypeError`. The host also dispatches only own members of `fns`.
 
 ### connecta.search
 
@@ -178,15 +213,17 @@ const page = await connecta.search({
   limit: 8,                         // 1–100, default 8
   offset: 0,
   fullDescriptions: false,
-  includeSchemas: "compact",        // or "json" / "typescript"
+  includeSchemas: "json",           // default; or "compact" / "typescript"
   includeSchemaKeys: true,          // default true in code mode
 });
 ```
 
-**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 }`. Ranking is
+**S1.** Returns the same flat page as top-level `search_tools`:
+`{ catalogErrors, tools, total, offset, limit, hasMore }`, plus `nextOffset`
+when more remains and `matchMode: "partial"` when no tool matched every term.
+Read `catalogErrors` and any `absence` before selecting a tool. Catalog failures
+carry recovery actions at the top of the page; an absent service returns no
+lookalikes. Both paths use only the caller's endpoint/pool and grants. Ranking is
 [lexical discovery](./meta-tools.md#lexical-discovery)'s, and 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 plus
@@ -201,16 +238,20 @@ bounded `guideSummary`, requested or not. An output shape learned under `S9`
 also carries `outputSchemaSource: "observed"`; provider declarations carry no
 source marker.
 
+Programs default to `includeSchemas: "json"`: `inputSchema` and available
+`outputSchema` are JSON Schema values, labeled `schemaFormat: "json"`.
+Explicit `includeSchemas: "compact"` returns strings labeled
+`schemaFormat: "text"`; TypeScript signatures carry the same text label.
 Compact shapes omit property prose and put required fields first, under these
 bounds:
 
-| Bound | Value |
-| --- | --- |
-| `execute_code` source | ≤ 65,536 UTF-8 bytes, checked before executor admission; over-limit source returns `invalid_args` |
-| Rendered shape | 1,024 UTF-8 bytes each |
-| Work per shape | 2,000 visits across schema nodes, property and required names, literal values, any constraint-free retry, and its key-only fallback |
-| Each enum node | 256 of those bytes |
-| Resolved `$ref` text | reused within one walk |
+| Bound                 | Value                                                                                                                               |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `execute_code` source | ≤ 65,536 UTF-8 bytes, checked before executor admission; over-limit source returns `invalid_args`                                   |
+| Rendered shape        | 1,024 UTF-8 bytes each                                                                                                              |
+| Work per shape        | 2,000 visits across schema nodes, property and required names, literal values, any constraint-free retry, and its key-only fallback |
+| Each enum node        | 256 of those bytes                                                                                                                  |
+| Resolved `$ref` text  | reused within one walk                                                                                                              |
 
 About three near-cap enum nodes therefore coexist while the final quarter stays
 for surrounding syntax, and above 1,024 bytes the global fallback applies.
@@ -229,7 +270,7 @@ use `format: "json"` or JSON search.
 `includeSchemas: "typescript"` spends those same bounds on a different
 rendering: one `signature` string in place of `inputSchema` and
 `outputSchema`, reading `(args: { runId: number }) => Promise<Run>` for the
-value `connecta.call` returns. It is documentation for the program's author —
+`data` value `connecta.call` returns. It is documentation for the program's author —
 the program itself is still JavaScript, and a type annotation copied into it
 is a syntax error (`P5`). Truncation keeps compact's flags and
 turns what compact would print as a name or raw JSON into a marked `unknown`;
@@ -239,14 +280,10 @@ its degradation rules are specified once, under
 signature is byte-identical to the one `search_tools` returns.
 
 **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
-`connecta.call` runs unasked; `"approvalRequired"` returns the complementary
-fail-closed class, false, missing, and contradictory annotations included,
-whose calls a program has refused (`E4`) unless config exempts them (`W12`),
-which a row marks with `approval: "exempt"` without moving it out of that
-class; omitted or `"all"` preserves the complete catalog. These filters grant
-no authority and change no admission decision.
+integration is ambiguous. `safety: "readOnly"` selects stored read verdicts;
+`"approvalRequired"` selects stored write verdicts; omitted or `"all"` selects
+both. Search and describe rows carry `classification`. These filters grant no
+authority and change no pool trust or call admission decision.
 
 **S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`
 (declared properties only), and `outputKeys`: the names the rendered schema
@@ -278,12 +315,14 @@ hint and the stable `code`, `retryable`, and `details` fields (`E1`).
 const one = await connecta.describe({ address: "ci.get_run" });
 const many = await connecta.describe({
   addresses: ["ci.get_run", "ci.get_job_logs"],  // ≤ 100
-  format: "compact",                             // or "json" / "typescript"
+  format: "json",                                // default; or "compact" / "typescript"
   fullDescriptions: false,
 });
 ```
 
-**S4.** Returns `{ tools }` in order, one entry per address; one bad address
+**S4.** Defaults to JSON Schema values with `schemaFormat: "json"`.
+Explicit compact schemas and TypeScript signatures have `schemaFormat: "text"`.
+Returns `{ tools }` in order, one entry per address; one bad address
 never fails the whole call. An unknown address or failed catalog returns `error`
 plus typed `errorDetails` (`code`, `message`, `retryable`). Misses carry a
 route-aware `nextAction`, a close miss may add three canonical `suggestions`,
@@ -302,15 +341,38 @@ says so inside its `Promise<…>`.
 
 ### connecta.call
 
+The published `GuestApi` type describes the supplied global for editors.
+The executable usage guide checks its API notation against those declarations;
+programs still use plain JavaScript.
+
 ```js
-const run = await connecta.call("ci.get_run", { runId: 42 });
+const { data: run, format } = await connecta.call("ci.get_run", { runId: 42 });
+// Equivalent: connecta.call({ address: "ci.get_run", args: { runId: 42 }, timeoutMs: 30_000 })
 ```
 
-**S5.** Takes a canonical address and one arguments object; returns the tool's
-value already unwrapped. For an MCP connector that means `structuredContent`
-when present, otherwise text content JSON-parsed when it parses and the raw text
-when it does not; a downstream result flagged `isError` throws. Omitted `args`
-is treated as `{}`.
+**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.
+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
@@ -320,6 +382,32 @@ program does decides it. The sandbox is an additional containment layer, not a
 second implementation of the boundary, and nothing a program does widens what
 it can reach.
 
+### connecta.result and connecta.skill
+
+`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. 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
+tool classification. A read-only endpoint cannot page a write result, so a
+direct write there returns an inline truncation notice without stashing the
+result or advertising a paging action. Binding
+mismatches, revoked access, and old entries without bindings are `not_found`, as
+are unknown or expired ids; a storage failure is `unavailable`. IDs are random UUIDs.
+The `get_result` meta-tool is removed.
+
+`await connecta.skill(name)` resolves the same URI or compatibility name as
+top-level `skills`, within the admitted connector view. It reads the registry
+behind native `skills/get` and `resources/read`, including opted-in downstream
+skills. It returns
+`{ name, format: "text", text }`; an unknown name is `not_found`.
+
 ### Parallel calls
 
 **S7.** Use `Promise.all` for independent calls when any failure should fail the
@@ -331,7 +419,7 @@ as sequential calls. There is no separate batch size or result contract.
 `details`. Project those fields before returning — an `Error` object is not a
 JSON result contract.
 
-**S9.** A successful explicitly read-only call whose provider declared no
+**S9.** A successful call classified as a read whose provider declared no
 `outputSchema` passively learns one from the unwrapped result. The observation
 keeps field names and broad JSON types only — no arguments, scalar values, raw
 results, code, credentials, or errors — and property names may be user-authored.
@@ -350,10 +438,75 @@ successful call. No discovery read, timer, refresh, background job, or storage
 adapter executes or persists work for this cache: the result-sampling refusal in
 [#282](https://github.com/zackbart/connecta/issues/282) stands.
 
+### connecta.read
+
+```js
+const resource = await connecta.read(
+  "resource://docs/" + encodeURIComponent("docs://manual/start"),
+);
+return resource.contents.map(content => content.text);
+```
+
+**S10.** Reads a downstream resource through a configured connector that
+implements `readResource`. The routing URI is exactly
+`resource://<connectorId>/<encodeURIComponent(downstreamUri)>`, at most 8,192
+UTF-8 bytes. The downstream URI must have a scheme and no control characters.
+Encode it once, including any path, query and fragment. Bare URLs, malformed
+encoding, routing userinfo, ports and extra routing query or fragment fields
+fail with `invalid_args`. Remote MCP connectors first load the complete,
+paginated resources and URI-template inventories through the same host-auth
+partitioned catalog cache. The decoded URI must exactly match an advertised
+resource or match an advertised URI template. An unmatched URI fails with a
+fixed `not_found` message before any downstream read. Template matching keeps
+the scheme and authority fixed and supports bounded RFC 6570 scalar and list
+expansions, including prefix modifiers and safe multi-segment `{+path}` and
+`{/p*}` paths. Variables cannot supply authority, backslashes, dot segments,
+a scheme change, query delimiters, controls or Unicode format characters,
+including through repeated percent encoding. Initial percent encoding and
+UTF-8 decoding stay strict. Later decoding layers preserve literal percent
+signs produced by `%25` while checking every remaining `%HH` escape. The
+matcher scans forward to the
+leftmost following literal without backtracking. Adjacent expressions and
+literals that the preceding expression can contain are refused with
+`resource_template_ambiguous`. Matching all templates is capped at 262144
+combined template and URI characters per read, with
+`resource_match_budget_exceeded` beyond that bound. Operator status retains
+each typed refusal once, without URI or template text. Mixed exploded
+composites remain unsupported.
+Connecta passes an admitted decoded URI as an opaque MCP `resources/read`
+argument to the configured endpoint. It never fetches that
+URI or creates a connector from it.
+
+Resources are protocol reads in both `read-only` and `trusted` pools. A read
+requires a grant to the whole connector through the endpoint/pool and identity
+intersection. Exact-tool grants, including guarded grants, authorize no
+resources. An absent, hidden, tool-restricted or resource-incapable connector
+fails with `unknown_address`. The URI and extra arguments cannot select a
+different credential owner or downstream subject. Personal credentials come
+from the admitted principal, just as they do for tool calls.
+
+The return is the downstream JSON `{ contents }` result, with text or base64
+blob entries and available metadata. It is not unwrapped or JSON-parsed.
+Every read spends one shared host call and uses the connector's call admission
+with `toolName: "resources/read"` and `args: { uri: downstreamUri }`. One deadline
+covers admission and dispatch; cancellation ends the wait and releases its
+permit. Reads share the execution's downstream request scope. They make one
+attempt, bypass response caching, and never start authorization. A downstream
+resource miss is `not_found`; a mid-call input request is
+`input_required_unsupported`. Other failures use the existing typed error
+contract, including credential recovery. Values and failures cross the same
+credential redaction boundary as `call`. Diagnostics use the fixed operation
+name `read`; resource URIs and bodies enter no activity or diagnostic record.
+This function exposes no resource listing, template discovery, subscriptions
+or upward proxy to programs. Native upward skill resources are separate
+[Phase 3](https://github.com/zackbart/connecta/issues/707) work.
+
 ### 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
@@ -362,53 +515,65 @@ clauses are [Emitted output](#emitted-output) (`M1`–`M10`).
 ## Errors
 
 **E1.** There are three error channels. Connecta failures are typed whether
-caught or uncaught.
+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 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 text | no |
+| 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 reduce a rejected host call to `new Error(message)`, and
-connecta restores the typed failure in a trusted prelude with a per-execution
-authenticated frame (`X11`). `message` stays human text, capped at 2,000
+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`, `search`, `describe`, `emit`, and
-the host-call budget. Program-authored errors stay untyped, and code must never
+describes a different call. This covers `call`, `read`, `search`, `describe`, `result`, `skill`, `emit`, and
+write and emitted-output budgets. Program-authored errors use `program_error`; code must never
 parse error prose. An `unavailable` classification may add `details.host`, an
 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.
 
-| Code | Raised when | `retryable` |
-| --- | --- | --- |
-| `unknown_address` | no connector owns the address | false |
-| `unknown_tool` | the connector has no such tool | false |
-| `destructive_tool_requires_approval` | the tool is neither explicitly read-only nor config-exempt (`E4`) | false |
-| `auth_required` | the credential is missing, expired, or rejected | false |
-| `invalid_args` | arguments or discovery bounds were rejected | false |
-| `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 | false |
-| `conflict` | the write named a base version someone else already moved past; nothing changed. `details.current` says where things stand (at most 20 whole-number entries) — re-read, reapply, retry with that base | 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; 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 |
-| `catalog_lookup_failed` | the connector's catalog could not be loaded | per cause |
-| `result_processing_failed` | the result could not be prepared | per message |
-| `result_too_large` | a discovery response exceeded its byte bound | false |
-| `budget_exceeded` | the run exhausted a host-call, write, or emitted-output budget | false |
-| `write_outcome_unknown` | an exempt write was sent and no answer came back; it is never sent again (`W9`) | false |
+| Code                                 | Raised when                                                                                                                                                                                           | `retryable`   |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `unknown_address`                    | no visible connector owns the tool address or grants the resource reader                                                                                                                              | false         |
+| `unknown_tool`                       | the connector has no such tool                                                                                                                                                                        | false         |
+| `destructive_tool_requires_approval` | a program in a read-only pool attempted a write (`E4`)                                                                                                                                                | false         |
+| `auth_required`                      | the credential is missing, expired, or rejected                                                                                                                                                       | false         |
+| `invalid_args`                       | arguments or discovery bounds were rejected                                                                                                                                                           | false         |
+| `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                      | false         |
+| `conflict`                           | the write named a base version someone else already moved past; nothing changed. `details.current` says where things stand (at most 20 whole-number entries) — re-read, reapply, retry with that base | false         |
+| `input_required_unsupported`         | a downstream asked for input; use `nextAction` for the equivalent direct call                                                                                                                         | false         |
+| `rate_limited`                       | the downstream reported a rate limit                                                                                                                                                                  | 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`                            | a call or sandbox deadline expired; details name operation, stage, elapsedMs, and deadlineMs                                                                                                          | per operation |
+| `program_error`                      | guest JavaScript failed; `details.name`, `line`, and a fixed repair hint describe it                                                                                                                  | false         |
+| `cancelled`                          | the run ended while this call was in flight (`E5`)                                                                                                                                                    | false         |
+| `connector_call_failed`              | anything else the connector threw                                                                                                                                                                     | per message   |
+| `catalog_lookup_failed`              | the connector's catalog could not be loaded                                                                                                                                                           | per cause     |
+| `result_processing_failed`           | the result could not be prepared                                                                                                                                                                      | per message   |
+| `result_too_large`                   | a discovery response exceeded its byte bound                                                                                                                                                          | false         |
+| `budget_exceeded`                    | the run exhausted a host-call, write, or emitted-output budget                                                                                                                                        | false         |
+| `write_outcome_unknown`              | a trusted-pool write was sent and no answer came back; it is never sent again (`W9`)                                                                                                                  | false         |
 
 **E3.** `auth_required` carries the same recovery envelope as `call_tool`:
 `connector`, `operation`, `recovery` (`oauth`, `operator_config`, or
@@ -416,17 +581,18 @@ caller what to do next, and never invents a cause it was not told.
 sentence. A program cannot recover credentials — only an operator can — so stop
 and let the failure reach the model.
 
-**E4.** An unannotated, write-capable, or destructive tool never runs in a
-program unless config exempts it (`W12`). It is refused with
+**E4.** A tool classified as a write never runs in a
+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.
 
-**E5.** Failures of the *execution*, not of a call, never appear inside the
+**E5.** Failures of the _execution_, not of a call, never appear inside the
 guest: admission rejection (`executor_overloaded`, retryable, with
 `retryAfterMs`), cancellation (`executor_cancelled`), shutdown
 (`executor_closed`), deadline expiry, an executor that never settles (`L3`),
@@ -436,19 +602,33 @@ 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. 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 (an inherited one like
-`toString` included), a `throw` of its own — ends the run with an untyped error
-result carrying that message. One precedence rule: connecta recognizes an
-escaped tool failure by its message, exactly first and by containment second for
-messages of at least eight characters, so a program that *wraps* a failure's
-message still reports the underlying typed failure — keeping the type beats
-keeping the prose. Matching retains only the most recent 64 failures per
-execution, caught refusals included; an older escaped message stays an untyped
-execution failure. An empty terminal error uses the fixed message in `E5`.
+when empty. An empty string reports `program_error` with
+`Program Error: Execution failed without an error message.`
+
+**E6.** A guest `TypeError`, `ReferenceError`, syntax error, invented API, or
+program-authored throw is `program_error`. `details.name` is a bounded engine
+error name; `details.line` is the source line when the runtime supplies one,
+otherwise null. Fixed hints repair imports/require/filesystem access, shadowed
+`connecta`, and invented globals such as `callTool` and `mixpanel`.
+
+An unchanged uncaught host error retains its classification through Error
+identity. A new error containing its message is a new program error. Copied
+public `code`/`details`, printed text, and returned outcome-shaped objects carry
+no authority. Host-call counts stay in host state. The guest JSON codec, Object
+prototype, and Promise prototype are immutable. Promise race and species are
+protected too. Host completion uses captured intrinsics so guest edits cannot
+change bridge decoding or async return adoption. Worker guest modules contain
+only the user callback and an import helper limited to runtime builtins.
+Relative and other guest module imports cannot reach runner code. Trusted
+wrappers and preludes remain outside the guest's lexical scope, and privileged
+initialization is single-use. A separate private runner module captures and
+freezes its references before the guest module evaluates, including the guest
+namespace initializer. The entrypoint imports that runner before its guest
+dependency. Before loading, the adapter parses the assembled guest export and
+requires exactly one expression with no additional statements. Normalized
+multi-statement bodies remain one async arrow expression.
+Program diagnostic fields are bounded before transport, including escaped text;
+a large custom error name cannot turn a failure into a truncated success.
 
 **E7.** `retryable` for `unknown_address`, `unknown_tool`, and
 `destructive_tool_requires_approval` is pinned false, never inferred from an
@@ -479,32 +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
-`get_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 with `get_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
@@ -512,18 +705,22 @@ 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. `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
-([#247](https://github.com/zackbart/connecta/issues/247)).
+non-string argument renders is not contract (`X4`). At terminal host-call
+budget exhaustion, QuickJS returns its streamed prefix; a Dynamic Worker
+has no host log stream and cannot supply logs from its suspended guest (`L4`).
+
+**R6.** Every run returns `hostCalls: { attempted, admitted, succeeded, failed }`,
+including admission failure, cancellation, budget refusal, and code-size refusal.
+Calls include search, describe, call, result, and skill. `emit` has separate budgets.
+An abandoned host call counts as failed when the run ends; guest catches do not
+change the counts. These numbers are outside the program's returned `result`.
+`diagnostics: true` adds the existing payload-free timing block. Emitting adds
+`emitted: N` and its content blocks.
 
 **R7.** Diagnostic timing separates admission, provider setup, total executor
 wall time, catalog work, and connector work. Catalog and connector values are
 cumulative, so parallel work can exceed executor wall time. Each used operation
-kind (`search`, `describe`, `call`) gets one aggregate with count, failures,
+kind (`search`, `describe`, `call`, `read`) gets one aggregate with count, failures,
 duration, returned serialized bytes, and catalog/connector time.
 
 **R8.** Diagnostics contain measurements and fixed operation names only: no
@@ -533,13 +730,37 @@ request; it is not activity, a session, or a stream.
 
 ## Emitted output
 
+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.
-The refused alternatives are in `ethos.md`
+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
@@ -552,34 +773,44 @@ a successful result, appended to `content` after the JSON envelope, which gains
 response (`R6`). `structuredContent` stays the envelope alone — emission is
 presentation, not a second data channel.
 
-**M3.** Return value and emission are independent: `R2` never measures emitted
-bytes, a truncated return does not suppress delivered blocks, and blocks do not
-shrink the return budget.
+**M3.** Text emission shares `R2`'s 24,000 serialized-character cap. Its
+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
+chain. A separate unhandled branch still fails the run.
 
 **M4.** A failed program delivers no blocks. The error result reports
-`emittedDiscarded: N` when N > 0 — a field on the structured envelope, a
-trailing line on the plain-text paths — never silently.
+`emittedDiscarded: N` when N > 0 as a field on the structured envelope.
 
 **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. No `get_result` stash: the program
+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
 learns while it can still choose differently. The byte default is a transport
 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`,
-and `call` share it. `M5`'s bounds are emission's only bounds.
+`call`, `read`, `result`, and `skill` share it. Text also observes `R2`.
 
-**M8.** Emission asks nothing of an executor: `emit` is a provider function,
-blocks cross the guest boundary once as an argument, and `ExecuteResult` is
-unchanged — `Executor` stays assignable from `@cloudflare/codemode`'s
-`DynamicWorkerExecutor`, so any executor that bridges provider calls gets
-emission for free.
+**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.
 
 **M9.** Request-local and unstreamed: blocks exist only in the finished
 response, and `emit` resolving means "accepted," never "delivered."
@@ -607,7 +838,7 @@ host-call budget, so an unchecked loop converts a transient failure into
   Dynamic-Worker-only wait would spend the run's wall clock on code that fails
   on QuickJS. Return the failure and let the model, which can wait, re-issue
   with `retryAfterMs` in hand.
-- a cancelled or timed-out *execution*: it is already over (`L1`).
+- a cancelled or timed-out _execution_: it is already over (`L1`).
 
 **Y4.** A provider's `retryAfterMs` is returned unchanged; the caller decides
 whether and when to reissue, and a later call gets its own deadline and
@@ -620,14 +851,21 @@ poll, no cancellation exception to catch, and no guarantee that a `finally`
 block runs — a cancelled QuickJS child is terminated outright. Write programs
 that need no cleanup.
 
-**L2.** What cancellation guarantees: in-flight host calls abort, no further
-host call is admitted — `search` and `describe` included, which fail
-`cancelled` rather than go on loading catalogs — the response returns
-`executor_cancelled` without waiting for the executor to settle, or for an
-`acquire()` that ignores the signal to grant, the admission lease is released
-(a lease granted after the run gave up is released on arrival), and nothing
-request-bound survives the request. Whether the program itself stops is the
-executor's (`X3`).
+**L2.** Cancellation aborts in-flight host calls and admits no further calls,
+including discovery. The response returns `executor_cancelled` without awaiting
+a wedged executor or `acquire()` that ignores its signal. It releases the lease;
+a late-granted lease releases on arrival. Nothing request-bound survives the
+request. Whether guest computation stops is the executor's (`X3`).
+
+Programs and direct calls use the same invocation deadline and stages. A call's
+`timeoutMs` wins, then `calls.defaultTimeoutMs`, then `execute.hostCallTimeoutMs`
+(default 15,000). A guest may request a longer individual call, but the sandbox
+and request ceilings still bound the whole run. Timeout details are agent-facing;
+INV-6 operator records retain only checked classifications and numeric facts.
+A dispatched write timeout becomes `write_outcome_unknown` and retains its
+deadline details even when the program catches the failure. The final program
+error includes the first timeout in `details`; multiple write timeouts also
+appear in `timeouts`, bounded to ten entries.
 
 **L3.** Every execution runs under a wall-clock deadline that includes time
 spent waiting on host calls. Expiry ends the run with an execution error and no
@@ -636,7 +874,7 @@ it sits a ceiling connecta enforces outside the sandbox, `execute.watchdogMs`
 (120 s by default, above both executors' own deadlines), because an executor's
 deadline may live inside the sandbox it is meant to stop: a wedged Dynamic
 Worker never fires its in-isolate timer. A run whose executor has not settled
-by the ceiling ends as a non-retryable `executor_failed` whose message calls
+by the ceiling ends as a non-retryable `timeout` whose message calls
 the sandbox unresponsive, with no partial result, and its admission lease is
 released, so wedged runs cannot fill the code pool. Raising an executor's
 deadline past the ceiling means raising the ceiling too.
@@ -644,25 +882,38 @@ deadline past the ceiling means raising the ceiling too.
 **L4.** Per-execution bounds that are contract, identical in both executors
 because connecta enforces them above the sandbox:
 
-| Bound | Value |
-| --- | --- |
-| Host calls per execution, shared by `search`, `describe`, and `call` | 20 by default, `execute.maxHostCalls` |
-| Exempt writes per run, on top of the host calls they also spend (`W10`) | 10 by default, `execute.maxWrites` |
-| Deadline per host call | 15 s, `execute.hostCallTimeoutMs`; one deadline covers catalog resolution, admission, and the connector call |
-| Discovery page | ≤ 100 tools, ≤ 256,000 serialized bytes |
-| `describe` addresses | ≤ 100 |
-| `describe` nearby suggestions | ≤ 3 canonical addresses per failed entry |
-| Caller text echoed by `describe` recovery | ≤ 512 UTF-8 bytes per field, plus `…` |
-| Result | 24,000 serialized characters |
-| Logs presented to the model | 4,000 characters |
-
-Every `call` attempt spends one host call on entry, before address resolution,
-catalog lookup, safety checks, validation, or dispatch, so unknown addresses,
-unknown tools, catalog failures, and other pre-dispatch refusals cost what a
-successful call costs; catching a refusal does not refund it. `search` and
-`describe` likewise spend on entry. Exhausting the 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.
+| Bound                                                                         | Value                                                                                                        |
+| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Host calls per execution, shared by `search`, `describe`, `call`, and `read`  | 20 by default, `execute.maxHostCalls`                                                                        |
+| Trusted-pool writes per run, on top of the host calls they also spend (`W10`) | 10 by default, `execute.maxWrites`                                                                           |
+| Deadline per host call                                                        | 15 s, `execute.hostCallTimeoutMs`; one deadline covers catalog resolution, admission, and the connector call |
+| Discovery page                                                                | ≤ 100 tools, ≤ 256,000 serialized bytes                                                                      |
+| `describe` addresses                                                          | ≤ 100                                                                                                        |
+| `describe` nearby suggestions                                                 | ≤ 3 canonical addresses per failed entry                                                                     |
+| Caller text echoed by `describe` recovery                                     | ≤ 512 UTF-8 bytes per field, plus `…`                                                                        |
+| Result                                                                        | 24,000 serialized characters                                                                                 |
+| Logs presented to the model                                                   | 4,000 characters                                                                                             |
+
+Every `call`, `read`, `search`, and `describe` spends one host call on entry, before
+resolution, validation, or dispatch. Catching a local refusal refunds nothing.
+The first call beyond the budget ends the host run with one non-retryable
+`budget_exceeded` (`E2`). Its bridge stays pending until lease disposal so guest
+`try/catch` cannot swallow it. Later host access, including `emit`, stops; pending
+replies are withheld. The refusal reaches no connector, returns no partial result,
+and discards accepted emits (`M4`). Calls still resolving or awaiting admission
+are cancelled, including trusted-pool writes past their gate. Dispatched trusted-pool writes
+drain under `W9`; unknown outcomes retain precedence. The lease then releases:
+QuickJS terminates its child, and the Worker adapter disposes RPC and loader
+handles independently of the guest deadline. Workers guest computation may
+continue briefly, including a timer escaping the bridge (`X3`), with no host
+access. The Promise executor contract carries typed failures separately from guest values.
+
+The failure adds payload-free `hostCalls: { attempted, admitted, succeeded, failed }`
+without diagnostics. `attempted` includes the first refusal, normally 21; `admitted`
+counts the 20 calls past the gate, local refusals included. `succeeded` and `failed`
+count outcomes at response time, the budget refusal and abandoned pending calls
+as failed, so `succeeded + failed === attempted`. `emit` and later attempts are
+excluded; no budget refills.
 
 **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
@@ -672,22 +923,44 @@ 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
 `executor_overloaded` carrying `retryAfterMs`; cancellation and shutdown are
-terminal. Admission happens *before* any catalog or provider is built, so a
+terminal. Admission happens _before_ any catalog or provider is built, so a
 queued request holds no state.
 
-**L8.** Bounds are deployment configuration, not program inputs: a program
-cannot raise one by asking. `execute_code`'s description states the host-call
+**L8.** Result, log, host-call, and emission budgets are deployment configuration.
+A call may request `timeoutMs` just as a direct call does; the guest deadline is
+capped by the time remaining before the program watchdog. `execute_code`'s description states the host-call
 budget and the per-call deadline — the ones a program must plan around before it
 runs. The result and log caps live here and in the truncation notice itself
 (`R2`, `R5`).
@@ -705,7 +978,7 @@ event.
 
 **V2.** Each event carries `connectorId`, `toolName`, `address`, `source`,
 `outcome` (`success`, `error`, `timeout`, `cancelled`), `durationMs`,
-`attempts`, and `errorCode` when the call *failed* — plus request, actor, and
+`attempts`, and `errorCode` when the call _failed_ — plus request, actor, and
 server identity. Rows written before
 [#672](https://github.com/zackbart/connecta/issues/672) may also carry the
 `paused` and `approved` outcomes, `source: "resume_execution"`, and an
@@ -719,65 +992,89 @@ is still recorded. `address` is canonical (`A1`) where a tool resolved,
 otherwise the name the program used — the honest record of what was attempted.
 
 **V3.** A call whose connector does not exist is recorded at the address as
-written, *provided* it split into the two fields activity keeps — one with no
+written, _provided_ it split into the two fields activity keeps — one with no
 interior dot records nothing. An invented id is the address mistake an operator
 most needs to see, but recording it as written puts caller-authored text in
 fields that are otherwise operator- and connector-authored, so `connectorId`
 and `toolName` clamp at 128 UTF-8 bytes (`address` at 257) with a `…` marker:
-payload-free *by construction* means the event has nowhere to put a payload.
+payload-free _by construction_ means the event has nowhere to put a payload.
 
 **V4.** The execution itself emits no event. It has no address, and its one
-distinctive artifact is the program source — exactly what a payload-free history
+distinctive output is the program source — exactly what a payload-free history
 must never keep.
 
-**V5.** An exempt write a program issues after it has already returned is not
+**V5.** A trusted-pool write a program issues after it has already returned is not
 sent and records nothing: it was never an attempt (`W9`).
 
 ## Writes
 
-A program does not ask anyone anything. It runs explicitly read-only tools and
-the writes config exempts from asking, and refuses every other write (`E4`), so
-each consequential call is its own `call_destructive_tool` and the host's
-permission prompt is the one approval there is. Programs once paused at a write
-and resumed by replay
-([#565](https://github.com/zackbart/connecta/issues/565)); hosts approve one
-call at a time, so under always-allow that prompt approved nothing and cost a
-round trip and a replay, and it went
-([#672](https://github.com/zackbart/connecta/issues/672)). `W1`–`W8` and `W11`
-belonged to pausing and stay retired; nothing reuses those ids.
-
-**W9.** An exempt write the program does not await outlives it: the play stops
-gating once the program settles — a write that reaches the gate after is not
-sent (`V5`) — and waits for writes already dispatched, each within its host-call
-deadline, before the run's scope aborts them. A write sent and never answered
-makes the result `write_outcome_unknown` with
-`writes: { succeeded, failed, unknown }`, whatever the program returned, and it
-is never sent again. Only a refusal (`auth_required`, `invalid_args`,
-`not_found`, `rate_limited`, `conflict`, `input_required_unsupported`) or the
-tool's own `isError` answers; an `isError` reading as a timeout does not, and
-`connector_call_failed` — an oversized body, a refused redirect — may come after
-the write landed. A program that fails after writing carries the same `writes`
-on its error, because it is not a program that is safe to run again.
-
-**W10.** `execute.maxWrites` (default 10) bounds a run's exempt writes beyond
-the host calls they spend, checked at the gate after validation and before
-admission, so an over-budget write fails `budget_exceeded` without a permit.
-The host-call budget bounds fan-out; this one bounds how much a program may
-change unasked, which is a different question even for writes a deployment
-called cheap.
-
-**W12.** Config may exempt a write from asking, and nothing else may
-([#566](https://github.com/zackbart/connecta/issues/566)). `execute.approval`
-maps connector ids and `connector.tool` addresses to `"never"` or `"ask"`; the
-address wins over the connector entry, which wins over a connector's own
-built-in default (reserved for connectors connecta ships, such as artifacts),
-which wins over `"ask"`. An exempt call is decided at the write gate, after
-validation and before admission, and dispatches with the write budget (`W10`),
-`W9`'s tracking, and a `V1` event. Exempt is never read-only: no read-only tool
-is reported exempt, discovery keeps an exempt tool approval-required,
-`call_tool` refuses it, and no annotation grants it, or a downstream could
-exempt itself. Unknown connectors and `api()` addresses its tools lack refuse
-to construct; an unserved remote address never matches.
+Pool trust belongs to deployment code. The default `/mcp` endpoint uses
+`trust: "read-only"`; each named pool has its own `trust`, also defaulting to
+`"read-only"`. A trusted default endpoint does not make named pools trusted.
+The default preserves refusal of ordinary program writes. A deployment must opt into program writes explicitly.
+
+```ts
+createConnecta({
+  connectors, executor,
+  trust: "read-only",
+  pools: {
+    automation: { tools: ["posthog"], trust: "trusted", grant },
+  },
+  classification: {
+    posthog: { exec: "read" }, // only for a deployment with a read-only exec contract
+    vendor: { mislabeled_update: "write" },
+  },
+});
+```
+
+The registry computes one `classifyTool` verdict on each request-scoped
+published catalog entry. It caches and persists only raw downstream facts.
+Every caller consumes that stored verdict. Config cannot classify an individual
+invocation's arguments: marking a mixed entry point read is an assertion about
+all calls this deployment can make through it.
+
+| Precedence | Evidence                                                 | Result                                                                                                                                           |
+| ---------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 1          | Exact deployment `classification[connectorId][toolName]` | `read` or `write`, even over a stale provider review                                                                                             |
+| 2          | `Connector.classification` provider review               | Reviewed writes remain writes; a stale schema digest makes a read a write; an explicit downstream contradiction also invalidates a reviewed read |
+| 3          | Downstream annotations                                   | Read only when `readOnlyHint === true && destructiveHint !== true`; otherwise write                                                              |
+
+Unknown connector override keys fail construction. Unknown static tool keys
+fail construction; unknown remote tool keys fail publication of the whole
+catalog. Overrides are exact tool names, including names containing dots.
+They are never inferred from descriptions or arguments.
+
+**W9.** Programs in trusted pools may write. A dispatched write is awaited even
+if the program does not await it, bounded by its host-call deadline. A write
+that reaches accounting after the program settles is not sent. An unanswered
+write makes the run fail `write_outcome_unknown` with
+`writes: { succeeded, failed, unknown }`, regardless of its return value.
+A failed program that already wrote carries those counts on its error. No
+write is automatically retried, including an ambiguous timeout. A downstream
+refusal or a tool's `isError` can establish failure; a timeout or an unanswered
+transport failure leaves the outcome unknown.
+
+**W10.** `execute.maxWrites`, default 10, bounds writes in trusted programs in
+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.
+`call_tool` accepts only reads in either tier; `call_destructive_tool` may send
+writes in either tier. Approval belongs to the host. Trust grants no tool or
+connector access and cannot be set by guest code, request arguments, or a
+downstream catalog. `execute.approval`, `Connector.approval`, and per-tool
+approval exemptions are removed. `W1`–`W8` and `W11` remain retired.
 
 ## Executor exceptions
 
@@ -796,12 +1093,13 @@ isolate limits apply untuned. A specific heap ceiling is a Node-only option.
 `AbortSignal` and kills the child — SIGTERM, then SIGKILL if it has not exited
 within a second — and releasing a lease whose child is still running recycles
 that child, so a run the watchdog abandons (`L3`) ends too.
-The Dynamic Worker executor's `execute()` takes no signal, so a cancelled or
-abandoned program runs on in its isolate until its host calls fail or its own
-deadline expires. `L2` and `L3` hold either way — the calls abort, connecta
-stops awaiting the executor and frees the admission slot — but "the run ends"
-is best-effort on Workers, and for that tail the code pool bounds what
-connecta is waiting on, not what the platform is still running.
+Upstream `execute()` takes no signal; its guest timeout may never settle after
+the parent response ends. `workerExecutor()` owns each lease's RPC and loader
+handles: release disposes them, detaches host functions, and settles the adapter's
+promise independently of upstream evaluation. Guest computation may continue
+briefly until platform teardown, but no late return, callback, `finally`, call,
+or emit changes the finished host result. Disposal releases request resources;
+it does not guarantee a synchronous guest-CPU kill.
 
 **X4. Log rendering and capture.** QuickJS JSON-stringifies non-string arguments
 and captures `log`, `info`, `warn`, `error`, and `debug`; the Dynamic Worker
@@ -820,14 +1118,16 @@ starts has no guest logs to recover.
 `process`, timers, `crypto`, or `WebSocket`, and its Node child starts with an
 explicit environment holding only `TZ=UTC`, so local time matches a Dynamic
 Worker's, 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 drifts, so that is not an allowlist.
-The supported construction is exactly `new DynamicWorkerExecutor({ loader })` —
+deployment variables or `NODE_OPTIONS`. A Dynamic Worker exposes runtime-only
+builtins through `import()` and `process.getBuiltinModule()`, including `node:path`,
+`node:crypto`, `node:net`, `node:tls`, `node:dns`, and
+`cloudflare:workers`; the upstream set drifts, so that is not an allowlist.
+The adapter refuses `node:module` and `node:process` imports and removes their
+builtin lookup routes, so `createRequire` cannot resolve runner modules.
+The supported adapter uses `new DynamicWorkerExecutor({ loader, timeout })`.
 `bindings`, `modules`, and `globalOutbound` each 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
+code, or egress. Under it, `process.env` and `cloudflare:workers.env` are empty,
+and lexical `this.env` is undefined; `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. `P2` is the portable
@@ -844,9 +1144,9 @@ 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-property message.** An unknown `connecta` property throws
-`Unknown function connecta.x` on QuickJS and `Tool "x" not found` on the Dynamic
-Worker. Both satisfy `E6`; the text is not contract.
+**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.
 
 **X9. Refusing a value outside JSON.** The Dynamic Worker ends the run with an
 error when a program returns something its codec cannot carry. QuickJS converts
@@ -856,81 +1156,87 @@ 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.
 
-**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 frame. The host bounds details before
-framing (`E1`), JSON escapes included; QuickJS refuses an oversized frame whole
-rather than slicing through its JSON, hides one whose JSON is malformed, and
-keeps the raw bridge and its JSON decoder in a private closure so guest code
-cannot intercept a frame first. A mismatched frame is ordinary untyped prose.
+**X11. Typed host rejection.** QuickJS creates and retains guest Error handles
+in its host bridge and compares handles when the program rejects. The Worker
+adapter stores each typed failure in a per-run host map under a random UUID.
+Its private entrypoint associates that ID with the guest Error and returns only
+the ID through Worker Loader RPC. The host resolves it to its own record before
+upstream result shaping; unknown or forged IDs attach no typed details, and IDs
+from previous runs cannot resolve. Rethrowing an earlier call's Error retains
+that call's record. The guest receives a separate copy for catching errors.
+Both construct `failure.call` from host-retained values, never from a guest
+result, parsed guest-realm object, or printed text. The Worker codec checks own
+binary-envelope properties, and completion uses captured array iteration even
+when the executor runs without the Connecta guest prelude. Host failure details are
+bounded before bridging (`E1`), including JSON escapes. No frame parser or
+prose matching participates in classification. The guest cannot import runner
+modules or repeat privileged initialization. QuickJS checks host interrupt and
+deadline facts before describing a rejection. It retains a private native Error
+brand check and reads only own string data descriptors for diagnostics; guest
+accessors, serialization hooks, and Proxy traps do not run. Other thrown objects
+receive a fixed description.
 
 ## Verification
 
-Every clause has a test. `test/guest-contract-cases.ts` holds the case table,
-written once and run twice: `test/guest-api-contract-quickjs.test.ts` runs it on
-the Node QuickJS executor, and `test/guest-api-contract.test.ts` runs it on a
-real `DynamicWorkerExecutor` in workerd — a Miniflare Worker Loader binding
-makes that arm real rather than simulated — alongside the clauses connecta
-enforces above any executor. Rows naming `test/guest-api-contract.test.ts` are
-covered by both arms, and each case's title carries its clauses. Two arms
-passing one table is also the check on the executor duties above, with
-`test/codemode-compat.test.ts` holding the upstream `Executor` shape assignable.
-
-| 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.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.test.ts` (exact absent globals and blocked imports), `test/quickjs-child-stderr.test.ts` (a child-process environment holding only `TZ=UTC`), `test/deployment-shapes.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.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, budget, removed-function, and forgery cases; typed promise rejections), `test/quickjs-executor.test.ts` (oversized messages, private transport, 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, failure isolation) |
-| `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.test.ts` (mid-run shutdown) |
-| `E6`, `X8` | `test/guest-api-contract.test.ts` (unknown and inherited members, wrapped-message precedence), `test/quickjs-executor.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.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) |
-| `L5`, `L7`, `X2` | `test/quickjs-executor.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue) |
-| `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) |
-| `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/d1-activity-example.test.ts` (historical pause and approval rows still render and round-trip) |
-| `V5`, `W9` | `test/program-writes.test.ts` (an unawaited exempt 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` (an exempt write runs and every other write keeps `E4`, the write budget, precedence and a connector default switched off, `call_tool` still refusing, search and describe markers, construction refusals), `test/artifacts-connector.test.ts` (the shipped default and switching it off), `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.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.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) |
-| `X3`, `X6` | `test/quickjs-executor.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 seven-tool list),
+`test/guest-contract-cases.ts` runs on QuickJS in `test/guest-api-contract-quickjs.node.test.ts`
+and on the Worker adapter with a real Miniflare Loader in `test/guest-api-contract.test.ts`.
+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`, `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),
 and `test/program-writes.test.ts` (the retired pause options refused at construction).