@zackbart/connecta 0.37.1 → 0.39.0

package/documentation/code-mode.md

@@ -113,7 +113,13 @@ 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`, `read`, `result`, `skill`, and `emit`.
+   `describe`, `call`, `read`, `result`, `skill`, and `emit`; the prelude also
+   binds the guest's `skills` alias to `skill`. Connecta also supplies
+   `unawaited`, which the built-in prelude calls at most once, after a failed
+   program read a result field off an unawaited call. It spends no host call;
+   the host admits one notice per run and ends the run with `budget_exceeded`
+   on any further call, so a bridge that exposes it directly gains no
+   uncounted round trips.
 2. **Evaluate `prelude` after the provider globals exist and before the
    program.** It is trusted host code that installs the immutable namespace
    and waits for emission acknowledgements. Capture runner intrinsics first;
@@ -196,13 +202,16 @@ is preserved; no JavaScript identifier conversion takes place.
 
 **A2.** Connectors create no guest globals, so an id resembling a JavaScript
 builtin, or one that would collide after sanitization, stays usable through its
-canonical address. The bounded connector inventory in the tool description shows
-canonical ids with bounded configured titles when present. Clauses A3–A5
+canonical address. The bounded connector inventory in the tool description names
+every connector by canonical id, adding a bounded configured title only when it
+says more than the id, and each guide's fetch call (see
+[meta-tools](./meta-tools.md#discovery-context)). Clauses A3–A5
 belonged to shortcut dispatch and stay retired; nothing reuses those ids.
 
 ## The surface
 
-Seven functions: `search`, `describe`, `call`, `read`, `result`, `skill`, and `emit`.
+Seven functions: `search`, `describe`, `call`, `read`, `result`, `skill`, and `emit`,
+plus `skills`, an undeclared alias bound to the same host function as `skill`.
 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`.
@@ -217,7 +226,7 @@ const page = await connecta.search({
   limit: 8,                         // 1–100, default 8
   offset: 0,
   fullDescriptions: false,
-  includeSchemas: "json",           // default; or "compact" / "typescript"
+  includeSchemas: "typescript",     // default; or "json" / "compact"
   includeSchemaKeys: true,          // default true in code mode
 });
 ```
@@ -234,18 +243,26 @@ query browses; non-empty input with no ASCII lexical terms returns no tools plus
 bounded no-match analysis in `queryAnalysis`; mixed input searches with its
 ASCII terms.
 
-Each entry carries `address`, `name`, the configured `connectorTitle` when
-present (normalized whitespace, at most 120 UTF-8 bytes), and — when requested —
-`description`, `inputSchema`, `outputSchema`, and `annotations`. An entry whose
-connector carries a usage guide also carries `guide` (the skill name) and a
-bounded `guideSummary`, requested or not. An output shape learned under `S9`
+The first page may also carry `readyCalls`: complete operation reads to pass
+unchanged as `connecta.call(entry.address, entry.args)`
+([fully determined operations](./meta-tools.md#discovery-context) only).
+
+Each entry carries `address`, `name`, and — when requested — `description`,
+the rendered schemas, and `annotations`. The page's `connectors` map holds each
+row's connector facts once, keyed by the id before the address's first dot: the
+configured `title` when present (normalized whitespace, at most 120 UTF-8
+bytes), and `guide` (the skill name) with a bounded `guideSummary` when the
+connector carries a usage guide, 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.
+Programs default to `includeSchemas: "typescript"`: each row carries one
+`signature` string for its input and available output, labeled
+`schemaFormat: "text"`, with `inputKeys`, `requiredInputKeys`, and `outputKeys`
+for code to check. A signature is about half the bytes of the JSON rows.
+Explicit `includeSchemas: "json"` returns `inputSchema` and available
+`outputSchema` as JSON Schema values, labeled `schemaFormat: "json"`, and
+`includeSchemas: "compact"` returns compact strings labeled `schemaFormat: "text"`.
 Compact shapes omit property prose and put required fields first, under these
 bounds:
 
@@ -349,8 +366,14 @@ 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.
+The `execute_code` description declares a compact subset of it inline: argument
+shapes that match what `GuestApi` accepts, result fields it returns, and no
+others. Authored emit blocks are the exact variants `M1` accepts;
+forwarded blocks are the native variants from `result.content`. It also
+states that search and describe return objects rather than arrays, that a call
+result over 1 MiB returns a paged handle, and that every function except `emit`
+spends a host call (`M7`). `GuestApi`'s `emit` takes no paged handle, which the
+host refuses. Programs still use plain JavaScript.
 
 ```js
 const { data: run, format } = await connecta.call("ci.get_run", { runId: 42 });
@@ -409,11 +432,17 @@ 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`.
+`await connecta.skill(name)` resolves the same URI, compatibility name, or bare
+connector id as top-level `skills`, within the admitted connector view; built-in
+names stay reserved (see
+[meta-tools](./meta-tools.md#connector-guides-and-skills)). 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`. It also
+accepts the top-level tool's `{ name }` object, and `connecta.skills` is an
+undeclared alias of `connecta.skill` with the same host-call accounting, because
+models copy the `skills` tool's shape into programs. Any other argument is
+`invalid_args`, with a message naming `connecta.skill("usage")`.
 
 ### Parallel calls
 
@@ -622,8 +651,20 @@ when empty. An empty string reports `program_error` with
 **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`.
+otherwise null. `message` is `Program <name>: <engine message>`, naming the
+error once even when an executor reports a prefixed message. Fixed hints repair
+imports/require/filesystem access, shadowed `connecta`, invented globals such
+as `callTool`, and a missing `await`. Detection is at runtime, never from
+source: the Promise each `connecta.*` call except `emit` returns has
+non-enumerable getters for result fields (`data`, `format`, `content`, `tools`,
+`catalogErrors`, `total`, `text`, `resultId`, `hasMore`, `nextOffset`). Reading
+one before `await`, as in `connecta.call(...).data` or
+`const { tools } = connecta.search(...)`, returns undefined as before and sets
+a per-run flag. When that program then fails, the prelude reports the flag
+through the uncounted `unawaited` host function before the failure crosses,
+and the hint is `connecta.* returns a Promise; await it`. Awaiting, `then`,
+`Promise.all`, and `Promise.allSettled` never read those fields. Hints are
+fixed text; no program source, field name, or value enters them.
 
 An unchanged uncaught host error retains its classification through Error
 identity. A new error containing its message is a new program error. Copied
@@ -657,13 +698,14 @@ past the deployment's result cap. A clipped address still identifies the mistake
 by its position; a short one is exact and untagged.
 
 **E8.** A remote MCP tool whose advertised schema rejects the call fails before
-provider dispatch with `invalid_args`, carrying bounded, value-free
-`{ path, code, expected }` findings and the same scoped
-`function: "connecta.search"` recovery every other in-program miss gets. A
-declared property reports the schema keyword that failed, never the validator's
-duplicate `additionalProperties` branch; a truly undeclared property still
-reports `additionalProperties`. Unsupported schemas pass through; unrecognized
-provider prose remains `connector_call_failed`.
+provider dispatch with `invalid_args`, carrying every bounded
+`{ path, expected, received? }` finding, one corrected `example` when it can be
+built, and the same scoped `function: "connecta.search"` recovery every other
+in-program miss gets ([argument recovery](./meta-tools.md#argument-recovery)).
+A declared property reports the constraint that failed, never the validator's
+duplicate `additionalProperties` branch; a truly undeclared property reports
+the accepted keys. Unsupported schemas pass through; unrecognized provider
+prose remains `connector_call_failed`.
 
 ## Results and projection
 
@@ -673,11 +715,26 @@ 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), shared with
-emitted text. An oversized return is stashed as compact JSON through the same
+**R2.** The boundary is `execute.maxResultChars` serialized characters, shared
+with emitted text: 24,000 (~6k tokens) by default, configurable from 4,000 to
+1,000,000. Raise it when agents need large results whole and the model's
+context can afford them, since every paging round trip costs a model step.
+The response carries a return twice (text content and `structuredContent`),
+and Connecta has no response-size limit of its own, so the client's limits
+apply; `admission.requests.maxBodyBytes` bounds request bodies only. Claude Code,
+for one, passes at most 50,000 characters of text and can reject a larger result
+with no content (see [truncated direct-call results](./meta-tools.md#truncated-direct-call-results)),
+so keep the cap below what every client of the deployment accepts. Redaction scans the whole envelope once, so its cost grows with the cap.
+The cap does not change stash paging: pages still obey the stashed call's
+`maxResultBytes` and the 32 KiB bridge ceiling.
+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`.
+with `connecta.result`. Its page size is `floor((maxResultChars - 1024) / 6)`
+bytes, so a page fits the next program's return even when every byte escapes to
+six characters (3,829 bytes by default), at most the stashed call's
+`maxResultBytes` and the 32 KiB bridge ceiling; direct-call notices use the same
+size. 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.
@@ -790,8 +847,8 @@ 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.** Text emission shares `R2`'s 24,000 serialized-character cap, less 512
-characters reserved for the envelope (23,488 for emitted text). Its
+**M3.** Text emission shares `R2`'s `execute.maxResultChars` cap, less 512
+characters reserved for the envelope (23,488 for emitted text by default). 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.
@@ -881,7 +938,11 @@ operations when a pending storage response arrives. An in-process caller receive
 
 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
+(default 15,000). `connecta.result`, `connecta.skill` and `connecta.read` always
+use `execute.hostCallTimeoutMs`. The `execute_code` description advertises the
+`connecta.call` default as `<n>s/host call`, or, when `calls.defaultTimeoutMs`
+differs, both deadlines, for example `25s/call (15s result/skill/read)`.
+A guest may request a longer individual call, but the sandbox
 and request ceilings still bound the whole run. Timeout details are agent-facing;
 operator records retain only checked classifications and numeric facts.
 Result processing, including stash reservation, uses the same remaining call
@@ -913,17 +974,17 @@ 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 every guest call except `emit`                      | 20 by default, `execute.maxHostCalls`                                                                                           |
-| Writes per run on a writable endpoint, 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, the connector call, and result processing |
-| 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                                                                                                                |
+| Bound                                                                                                | Value                                                                                                                                                                                                                                                             |
+| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Host calls per execution, shared by every guest call except `emit` and the single `unawaited` notice | 20 by default, `execute.maxHostCalls`                                                                                                                                                                                                                             |
+| Writes per run on a writable endpoint, on top of the host calls they also spend (`W10`)              | 10 by default, `execute.maxWrites`                                                                                                                                                                                                                                |
+| Deadline per host call                                                                               | `connecta.call`: its `timeoutMs`, else `calls.defaultTimeoutMs`, else `execute.hostCallTimeoutMs` (15 s); `result`, `skill` and `read`: `execute.hostCallTimeoutMs`. One deadline covers catalog resolution, admission, the connector call, and result processing |
+| 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 by default, `execute.maxResultChars` (4,000–1,000,000)                                                                                                                                                                               |
+| Logs presented to the model                                                                          | 4,000 characters                                                                                                                                                                                                                                                  |
 
 For any tool whose output declares `page`, continue while `page.hasMore` is true.
 When approaching the program's host-call limit, return `page.nextCursor` before
@@ -1285,51 +1346,97 @@ and on the Worker adapter with a real Miniflare Loader in `test/guest-api-contra
 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/identity-write-journey.node.test.ts` (read-only refusals before validation or dispatch, actual QuickJS)                                                                                                                                                                                                                                                                                                                 |
-| `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), `test/executor-requests.test.ts` (queued handoffs and refusal shape across separate workerd requests), `test/request-context.node.test.ts` (queued and QuickJS host-call request context)                                                                                                                                                                                         |
-| `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/kv-to-d1.test.ts` (SQL stash and native D1 fault probes), `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/browser/operator-ui.spec.ts` (identity changes), `test/sql-storage-contract.ts`, run by `test/sqlite-storage.node.test.ts` (historical activity rows still round-trip)                                                             |
-| `V5`, `W9`             | `test/program-writes.test.ts` (unawaited program drain, failed-program accounting), `test/identity-write-journey.node.test.ts` (committed ambiguity, reconciliation and physical writes), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                 |
-| `W10`, `W12`           | `test/identity-write-journey.node.test.ts` (real HTTP/MCP and QuickJS: write budget, read-only discovery and refusal, named guide, pool inheritance/reopening and connector policy), `test/program-writes.test.ts` (construction refusals and classification drift), `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),
+`test/package-surface.node.test.ts` compiles the description's compact guest
+declaration against `GuestApi`, checks arguments in both directions, and rejects
+invented, mistyped, and missing members and authored blocks the host refuses.
+
+| 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/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)               |
+| `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/identity-write-journey.node.test.ts` (read-only refusals before validation or dispatch, actual QuickJS)                                                                                                                                                                                                                                                     |
+| `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`                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `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)                                                                                                                                                                                                                                                                                     |
+| `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), `test/executor-requests.test.ts` (queued handoffs and refusal shape across separate workerd requests), `test/request-context.node.test.ts` (queued and QuickJS host-call request context)                                                                                                                             |
+| `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/storage-sql-d1.test.ts` (SQL stash and native D1 fault probes), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message)                                                                              |
+| `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/browser/operator-ui.spec.ts` (identity changes), `test/sql-storage-contract.ts`, run by `test/sqlite-storage.node.test.ts` (historical activity rows still round-trip) |
+| `V5`, `W9`             | `test/program-writes.test.ts` (unawaited program drain, failed-program accounting), `test/identity-write-journey.node.test.ts` (committed ambiguity, reconciliation and physical writes), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                     |
+| `W10`, `W12`           | `test/identity-write-journey.node.test.ts` (real HTTP/MCP and QuickJS: write budget, read-only discovery and refusal, named guide, pool inheritance/reopening and connector policy), `test/program-writes.test.ts` (construction refusals and classification drift), `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)                                                                                                                                                                                                                                                                                                                                               |
+| `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)
 and `test/program-writes.test.ts` (deployment policy and classification construction refusals).
+
+### Adding a guest function
+
+`src/guest-functions.ts` lists every `connecta.<name>` function once, as
+guest-safe data with no host code or imports. The guest runtime builds the
+frozen namespace from it, so the runtime source stays one self-contained string
+that QuickJS and the Worker executor evaluate unchanged. `execute.ts` admits
+each bridge call by the entry's budget class and binds it by name to a host
+implementation, and the `execute_code` description joins each entry's compact
+declaration and names the functions that spend no host call.
+
+| Function    | Budget     | Purpose                                                                    |
+| ----------- | ---------- | -------------------------------------------------------------------------- |
+| `search`    | `hostCall` | Searches the catalog and returns one flat page of `{ tools }`.             |
+| `describe`  | `hostCall` | Describes exact addresses, one entry per address in order.                 |
+| `call`      | `hostCall` | Calls one tool and inlines transfer pages and native content.              |
+| `read`      | `hostCall` | Reads one advertised resource URI.                                         |
+| `result`    | `hostCall` | Pages a retained result by page or UTF-8 byte offset.                      |
+| `skill`     | `hostCall` | Fetches a skill's text by exact name.                                      |
+| `emit`      | `emission` | Forwards a content block to the client; needs no await.                    |
+| `unawaited` | `once`     | Tells the host a failed program read a result field off an unawaited call. |
+
+A `hostCall` function spends one host call on entry (`L4`, `M7`) and returns a
+Promise whose result fields mark an unawaited read. The runtime wraps
+`provider.<name>`, or its own local of that name when the entry is `wrapped`,
+as `call` is. An `emission` function spends none, is bounded by the emission
+collector and an attempt cap, and returns a tracked thenable. A `once`
+function accepts one call per run, ends the run on a second, and is called only
+by the runtime, never from the namespace.
+
+To add a function:
+
+1. Add its entry to `GUEST_FUNCTIONS`: name, budget class, compact
+   declaration and a one-line JSDoc purpose. A `wrapped` function also needs a
+   guest-side local of the same name in `guestInitializer`.
+2. Add the member to `GuestApi` in `src/guest-types.ts`. The package-surface
+   declaration test fails until the compact declaration and `GuestApi` agree.
+3. Bind its host implementation in `sandboxProvider`'s `operations` in
+   `src/execute.ts`. Typecheck fails while a registry entry has no binding.
+4. Add behavior cases to `test/guest-contract-cases.ts`, which run on both
+   executors. The namespace-membership and missing-await cases cover the new
+   entry without edits.
+5. Document its clause in this guide and add its row to the table above; the
+   package-surface test compares the table with the registry.