@zackbart/connecta 0.16.1 → 0.18.0

package/documentation/code-mode.md

@@ -53,8 +53,8 @@ createConnecta({
 });
 ```
 
-Dynamic Workers require the Workers Paid plan. The complete required binding and
-package setup is in the [Worker example](../examples/worker/README.md#code-mode).
+Dynamic Workers require the Workers Paid plan. 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) carries the full setup.
 
 ## What an executor must implement
 
@@ -104,8 +104,8 @@ Connecta passes exactly one provider, named `connecta`. An executor must:
    uncaught tool failure keeps its type (`E1`).
 6. **Capture `console.log`, `console.warn`, and `console.error`** into `logs` in
    call order (`R5`), bounding what it retains.
-7. **Bound the guest**: wall clock, memory, stack, and CPU (`L3`, `L5`), with no
-   network, filesystem, environment, or import capability (`P2`).
+7. **Bound the guest**: wall clock, memory, stack, and CPU (`L3`, `L5`). Keep
+   ambient capabilities within the documented and tested `P2`/`X5` boundary.
 8. **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`.
@@ -138,10 +138,10 @@ reinterpreted, so do not rely on it.
 It is host plumbing, callable but not contract: it takes a connector id and an
 unsanitized-or-sanitized tool name and can change shape without notice.
 
-Anything else a runtime happens to expose is outside the contract and must not
-be used, even where it exists. Neither executor grants network egress,
-filesystem access, credentials, or deployment configuration; what they leave
-lying around otherwise differs (`X5`).
+Anything else a runtime happens to expose 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 access and keeps its environment maps empty, but
+it exposes the globals and runtime builtins described in `X5`.
 
 **P3.** Values cross the host bridge as JSON. Arguments must be
 JSON-serializable and results arrive as plain JSON values. A value outside JSON —
@@ -154,8 +154,9 @@ scratch storage carried to the next program, and no request-bound object outlive
 the request that created it. Within one execution, host calls share one
 downstream request scope.
 
-**P5.** Plain JavaScript only. TypeScript syntax is a syntax error, and there is
-no `import` or `require` to reach for.
+**P5.** Plain JavaScript only. TypeScript syntax is a syntax error. Portable code
+does not import: QuickJS blocks imports, while Dynamic Workers expose the `X5`
+runtime modules. Neither executor exposes `require`.
 
 ## Addressing
 
@@ -172,7 +173,10 @@ global whose properties are its tools, so `<connectorId>.<toolName>(args)` works
 with both parts sanitized into JavaScript identifiers — characters outside
 `[A-Za-z0-9_$]` become `_`, a leading digit gets `_` prefixed, and a reserved
 word gets `_` appended (`my-service.get.thing` → `my_service.get_thing`). The
-globals are lazy: no catalog is fetched until a program touches one.
+globals are lazy: no catalog is fetched until a program touches one. The
+bounded deployment inventory in the `execute_code` description shows each
+canonical connector id and labels the shortcut only when it differs; the
+[discovery guide](./meta-tools.md#discovery-context) defines that bound.
 
 **A3.** A shortcut that resolves to more than one tool fails closed with
 `ambiguous_tool_alias`, naming the colliding tool names and pointing at
@@ -240,8 +244,8 @@ can set `includeSchemaKeys: false` to buy the bytes back.
 **S3.** Discovery is bounded and the bounds throw rather than silently shrink: a
 `limit` outside 1–100 is `invalid_args`, and a page whose serialized form
 exceeds 256,000 bytes is `result_too_large`, each with a hint naming the ways to
-ask for less. As with every failure, the *thrown* error carries only the message
-(`E1`); the code appears when the failure escapes the program uncaught.
+ask for less. The thrown error carries the stable `code`, `retryable`, and
+`details` fields (`E1`).
 
 ### connecta.describe
 
@@ -255,10 +259,13 @@ const { tools } = await connecta.describe({
 });
 ```
 
-**S4.** Returns `{ tools }` in the order asked, one entry per address. An
-address that is unknown, or whose connector's catalog could not be loaded,
-returns an entry carrying `error` — one bad address never fails the whole call.
-More than 100 addresses is `invalid_args`; the same 256,000-byte ceiling applies.
+**S4.** Returns `{ tools }` in order, one entry per address. An unknown address
+or failed catalog returns `error` plus typed `errorDetails`: `code`, `message`, and `retryable`. Misses
+carry a route-aware `nextAction`; a close miss may add three canonical `suggestions`.
+Catalog failures add only `retryAfterMs` when known. One bad address never fails the whole call. Each failed entry clamps its
+caller-authored `address` to 512 UTF-8 bytes with an `…` marker. Entry order
+correlates a clipped address with its request; successes keep canonical addresses. More than 100
+addresses is `invalid_args`; the same 256,000-byte ceiling applies.
 
 ### connecta.call
 
@@ -295,9 +302,7 @@ order. A success is `{ address, ok: true, data }`. A failure is
 field names the host's internal batch path uses. One failing call never rejects
 the batch, and more than ten calls throws.
 
-**S8.** `connecta.batch` is the classification channel: because a thrown host
-error crosses the bridge as a bare message (`E1`), a batch of one is the supported
-way for a program to *decide* something about a failure rather than report it.
+**S8.** Batch and thrown failures share one vocabulary (`E1`): an entry's `errorDetails.code` and `retryable` equal the fields on the error the same call would throw. Use batch for independent concurrency, not to recover lost type.
 
 ### connecta.emit
 
@@ -310,24 +315,18 @@ clauses are [Emitted output](#emitted-output) (`M1`–`M10`).
 
 ## Errors
 
-**E1.** There are four error channels, and only two of them are typed.
+**E1.** There are four error channels. Connecta failures are typed whether caught or uncaught.
 
 | Channel | Shape | Typed? |
 | --- | --- | --- |
-| A throw inside the program | `Error` with `message` only | no |
+| A caught Connecta host failure | `Error` with `message`, `code`, `retryable`, and `details` | yes |
 | `connecta.batch` outcome | `{ ok: false, error, errorDetails }` | yes |
 | An uncaught **tool or discovery** failure, as the model sees it | `{ error: { code, message, retryable, … } }` with `isError` | yes |
-| Anything else that ends the run (`E5`, `E6`, a bridge bound in `L6`) | error text | no |
-
-The message-only throw is a hard limit of the guest bridge: both executors reduce a rejected
-host call to `new Error(message)`, dropping every own property. A program must
-therefore never branch on an error's fields and never parse its message. To
-classify, use `errorDetails`; to hand a failure to the model with its type
-intact, let it escape uncaught — connecta re-attaches the typed details on the
-way out. The model-facing version of this lives in `execute_code`'s description,
-not in the always-loaded usage skill, which `test/meta-tools.test.ts` caps at
-2,500 bytes — a budget the guide already spends nearly all of, so new text there
-displaces old rather than adding to what every request pays for.
+| Program or execution failure (`E5`, `E6`, a bridge bound in `L6`) | error text | no |
+
+Both executor bridges reduce a rejected host call to `new Error(message)`. Connecta restores the typed failure in a trusted prelude with a per-execution authenticated frame (`X11`), without turning the rejection into a returned value.
+`message` remains the human text. `code` and `retryable` are the stable branch fields; `details` is the complete host classification. This covers `call`, connector shortcuts, `search`, `describe`, `emit`, `ui`, rejected batch input, and the host-call budget.
+Program-authored errors stay untyped, and code must never parse error prose.
 
 **E2.** The taxonomy: `retryable` is what connecta reports, `Y3` what a program may do.
 
@@ -339,16 +338,18 @@ displaces old rather than adding to what every request pays for.
 | `destructive_tool_requires_approval` | the tool is not explicitly read-only | 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, classified off `errorDetails` per `E1` and never off a caught error, raised only where the provider tells absence from a permission gap ([H11](./provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next)) | false |
+| `not_found` | the downstream answered and the resource is not there — the one code that says skip this id rather than stop, raised only where the provider tells absence from a permission gap ([H11](./provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next)) | false |
 | `input_required_unsupported` | a downstream asked for mid-call input | false |
 | `rate_limited` | the downstream reported a rate limit | true |
 | `unavailable` | the downstream is down or unreachable | true |
 | `timeout` | the per-call 15-second deadline expired | true |
 | `cancelled` | the run ended while this call was in flight (`E5`) | false |
-| `connector_call_failed` | anything else the connector threw, and the host-call budget (`L4`) | per message |
+| `connector_call_failed` | anything else the connector threw | per message |
 | `batch_call_failed` | a `connecta.batch` entry connecta could not even attempt | 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 or emitted-output budget | false |
 
 **E3.** `auth_required` carries the same recovery envelope as `call_tool`:
 `connector`, `operation`, `recovery` (`oauth`, `operator_config`, or
@@ -382,7 +383,7 @@ exactly first, by containment second — so a program that *wraps* a failure's
 message in its own text still reports the underlying typed failure. Keeping the
 type beats keeping the prose.
 
-**E7.** `retryable` for `unknown_address`, `unknown_tool`, `ambiguous_tool_alias`, and `destructive_tool_requires_approval` is pinned false, never inferred from an address containing `503`, `429`, or `temporar`. The first two carry `nextAction: { function: "connecta.search", arguments: { query, connector?, includeSchemas: "compact" } }` — the same scoped discovery the top-level record names, keyed to the surface the caller actually has. A program cannot call `search_tools`, so it is never told to. Both the message and the derived `query` clamp the address to 512 UTF-8 bytes with a `…` marker: the address is caller-authored and lands in the message, the query, the text content, and `structuredContent`, so an invented 50 KB one would otherwise produce a refusal orders of magnitude past the deployment's result cap. A clipped address still identifies the mistake; a short one — the common case — is exact and untagged.
+**E7.** `retryable` for `unknown_address`, `unknown_tool`, `ambiguous_tool_alias`, and `destructive_tool_requires_approval` is pinned false, never inferred from an address containing `503`, `429`, or `temporar`. The first two carry `nextAction: { function: "connecta.search", arguments: { query, connector?, includeSchemas: "compact" } }` — the same scoped discovery the top-level record names, keyed to the surface the caller actually has. A program cannot call `search_tools`, so it is never told to. The message, the derived `query`, and a failed describe entry's `address` clamp caller-authored text to 512 UTF-8 bytes with an `…` marker. Those values land in the text content and `structuredContent`, so an invented 50 KB address would otherwise produce a refusal orders of magnitude past the deployment's result cap. A clipped address still identifies the mistake by its position; a short one — the common case — is exact and untagged.
 
 **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 scoped search recovery keyed `function: "connecta.search"` like every other in-program miss. 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`.
 
@@ -590,14 +591,14 @@ the same mistake as automatic host-side projection, refused in `ethos.md`
 ([#282](https://github.com/zackbart/connecta/issues/282)).
 
 **U13.** The always-loaded MCP instructions locate `connecta.ui(html)` before an
-agent chooses a route: it is a guest function inside `execute_code`, never a
-connector address or catalog result, takes one HTML string, and carries `U12`'s
-mirrored-return duty. The detailed tool description proved too late to stop cold
-agents from searching downstream catalogs for UI; the location distinction
-therefore rides `initialize`, under a 1,000-character ceiling for the complete
+agent chooses a route: it exists only inside `execute_code`, never in connector
+search, and carries `U12`'s mirrored-return duty. The detailed call, binding,
+budget, and repair rules live in the on-demand `usage` skill. The location
+distinction rides `initialize`, under a 1,000-character ceiling for the complete
 instructions string. This promotes existing contract, not capability: the
 seven-tool surface, guest API, catalog, Apps delivery, and runtime do not change
-([#286](https://github.com/zackbart/connecta/issues/286)).
+([#286](https://github.com/zackbart/connecta/issues/286),
+[#418](https://github.com/zackbart/connecta/issues/418)).
 
 Bounded view reads follow normative [`V1`–`V8`](./program-ui-read-calls.md) ([#287](https://github.com/zackbart/connecta/issues/287), [#289](https://github.com/zackbart/connecta/issues/289)).
 
@@ -608,25 +609,22 @@ annotation-gated `maxRetries`; code mode fixes it at zero, so one
 `connecta.call` is exactly one downstream attempt. The program is the retry
 loop, and its budget is visible to it (`L4`).
 
-**Y2.** A program may retry a failure whose `errorDetails.retryable` is true,
-learned through `connecta.batch` (`S8`). Every attempt spends host-call budget,
-so a retry loop that ignores the budget converts a transient failure into a
-budget failure.
+**Y2.** A program may retry a caught failure whose `retryable` is true, or a batch failure whose `errorDetails.retryable` is true (`S8`). Every attempt spends host-call budget, so an unchecked loop converts a transient failure into `budget_exceeded`.
 
 **Y3.** What must never be retried automatically:
 
 - anything with `retryable: false` — a policy refusal, a missing credential, a
   bad address, or malformed arguments will fail identically forever;
-- `rate_limited`, immediately. The sandbox has no timers, so a program cannot
-  wait out a window; retrying inside it is the harm the signal exists to
-  prevent. Return the failure and let the model, which can wait, re-issue with
-  `retryAfterMs` in hand.
+- `rate_limited`, immediately. A portable program has no timer, and a
+  Dynamic-Worker-only wait would spend the run's wall-clock budget 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`).
 
 **Y4.** Connecta's own retry machinery beneath the meta-tools honours a
 connector-reported `Retry-After` exactly or not at all, and declines windows
 longer than 10 seconds rather than shortening them. A program sees the window
-verbatim as `errorDetails.retryAfterMs`.
+verbatim as `err.details.retryAfterMs` or `errorDetails.retryAfterMs`.
 
 ## Cancellation and limits
 
@@ -653,13 +651,12 @@ because connecta enforces them above the sandbox:
 | Deadline per host call | 15 s |
 | 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 |
 
-Exhausting the host-call budget fails that call like any other, with code
-`connector_call_failed` (`E2`) and a message naming the budget — no connector was
-reached, so nothing more specific is true. Retrying it is pointless: the budget
-does not refill inside one execution.
+Exhausting the host-call budget fails that call with non-retryable `budget_exceeded` (`E2`) and a message naming the budget. No connector is reached, and the budget does not refill inside one execution.
 
 **L5.** The guest is memory-, stack-, and CPU-bounded, and a program that
 exhausts a bound ends the run with an error instead of degrading the host. The
@@ -672,7 +669,7 @@ 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 untyped text (`E1`). An over-bound *result* names the address the program
+is executor-owned untyped text, not a Connecta host failure (`E1`). An over-bound *result* names the address the program
 called, not the internal dispatcher behind the shortcut namespaces; an over-bound
 *argument* payload is refused before it is parsed, so it names no address at
 all — parsing it to write a better message would spend exactly the work the bound
@@ -750,11 +747,9 @@ Worker renders arguments with `String()` (so an object logs as
 latter two. Only the three captured everywhere are contract (`R5`); rendering is
 not.
 
-**X5. Leftover globals.** The QuickJS guest has no `fetch`, `process`, timers,
-`crypto`, or `WebSocket` at all. The Dynamic Worker guest has all of them:
-`fetch` exists but throws on use because outbound access is disabled,
-`process.env` is empty, and timers work. `P2` is the contract — a program that
-uses `setTimeout` is writing Workers-only code, and it will fail on Node.
+**X5. Leftover authority.** QuickJS blocks imports and has no `fetch`, `process`, timers, `crypto`, or `WebSocket`. A Dynamic Worker has those globals plus a non-contract set of runtime builtins through `import()` and `process.getBuiltinModule()`, including `node:path`, `node:crypto`, `node:net`, `node:tls`, `node:dns`, `node:module`, and `cloudflare:workers`. The upstream set can drift; this list is not an allowlist.
+The supported Worker construction is exactly `new DynamicWorkerExecutor({ loader })`. Do not pass `bindings`, `modules`, or `globalOutbound`: each can grant ambient configuration, code, or egress. Under it, `process.env`, lexical `this.env`, and `cloudflare:workers.env` are empty; `node:fs`, `node:http`, and `node:https` are unavailable through either access route; external `fetch`, `WebSocket`, `node:net`, and `node:tls` fail with workerd's outbound-denial error; DNS lookup ends unresolved; and `fetch("data:...")` resolves locally.
+`P2` is the portable contract. Programs use none of this runtime-only authority, including timers and `crypto`, because the same code fails on QuickJS. The `execute_code` description and served `usage` skill say so before an agent writes code.
 
 **X6. Stall detection.** QuickJS notices a program awaiting something that can
 never settle and fails fast; the Dynamic Worker waits for its deadline. The fast
@@ -786,11 +781,16 @@ a `process.send` with a hard ceiling. A program that returns a quarter-megabyte
 from one tool call therefore fails on Node and may succeed on Workers — reduce
 inside the program either way (`R1`).
 
+**X11. Typed host rejection.** Both executors rebuild Connecta's authenticated host-failure frame as a thrown guest `Error` (`E1`). The per-run secret stays in the trusted prelude closure, and the prelude locks `globalThis.Error`, so guest code and connector prose cannot forge the host transport frame.
+The human message is unchanged; a mismatched frame is ordinary untyped prose.
+
 ## Changes from earlier code mode
 
-Five behaviors changed with this contract, matching the changelog's Unreleased
+Six behaviors changed with this contract, matching the changelog's Unreleased
 entry. Programs that ran before still run.
 
+- **Caught Connecta failures expose their classification** (`E1`, `X11`). Their human message and thrown semantics stay unchanged; `code`, `retryable`, and `details` are additive.
+
 - **`connecta.batch` failures gained `errorDetails`** (`S7`). They carried only a
   message, which left a program unable to tell a policy refusal from a transient
   failure. Additive, and it reuses the host's internal batch field names, so a
@@ -833,21 +833,21 @@ the upstream `Executor` shape assignable.
 | Clauses | Test |
 | --- | --- |
 | `P1`, `P5` | `test/guest-api-contract.test.ts` (TypeScript syntax), `test/quickjs-executor.test.ts` (`normalizeCode`) |
-| `P2`, `X5` | `test/guest-api-contract.test.ts` (no usable network, no config) |
+| `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/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` (sanitizing) |
+| `A1`, `A2` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (sanitizing), `test/server.test.ts` (bounded live connector inventory) |
 | `A3` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (colliding alias) |
 | `A4` | `test/execute.test.ts` (namespace collisions, reserved namespace) |
 | `A5` | verdict; `A1`–`A3` are its enforcement |
 | `S1`, `S2` | `test/guest-api-contract.test.ts` (flat page, connector guides, schema keys, and the unfiltered browse that replaces `list_connectors`), `test/execute.test.ts` (guide pagination/partial/no-match behavior and `$ref`/`allOf`), `test/meta-tools.test.ts` (mixed complete/partial ranking and stable pagination) |
 | `S3` | `test/guest-api-contract.test.ts` (typed uncaught bound), `test/execute.test.ts` (count limits, fan-out bound) |
-| `S4` | `test/guest-api-contract.test.ts` (unknown address in `describe`) |
+| `S4` | both guest-contract executors (ordered mixed describe results with unknown-address, unknown-tool suggestion, and catalog-failure details), `test/meta-tools.test.ts` (top-level routing, no-suggestion, catalog-failure, and hostile-input bounds) |
 | `S5` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`) |
 | `S6` | `test/execute.test.ts` (fail-closed annotations, activity parity) |
 | `S7` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (batch cap) |
-| `S8`, `E1` | `test/guest-api-contract.test.ts` (typed batch outcomes) |
-| `E2`, `E8` | `test/guest-api-contract.test.ts` (code → `retryable`, batch and uncaught validation recovery), `test/meta-tools.test.ts` (direct, destructive, batch, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts` |
+| `S8`, `E1`, `X11` | both guest-contract executors (caught call, namespace, discovery, utility, batch-validation, budget, and forgery cases; typed batch equivalence) |
+| `E2`, `E8` | `test/guest-api-contract.test.ts` (code → `retryable`, caught, batch, and uncaught validation recovery), `test/meta-tools.test.ts` (direct, destructive, batch, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts` |
 | `E3` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`) |
 | `E4` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (destructive) |
 | `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) |
@@ -883,7 +883,7 @@ the upstream `Executor` shape assignable.
 | `U7`, `U8` | two arms passing one case table, `test/codemode-compat.test.ts` |
 | `U9` | `test/execute-ui.test.ts` (a `ui` byte aggregate distinct from `emitted`, absent when nothing was accepted) |
 | `U12` | `test/server.test.ts` (the `connecta.ui` bullet carries the return-value clause); a duty on program authors, so the description is the only place it can be enforced |
-| `U13` | `test/code-first-surface.test.ts`, `test/server.test.ts` (served `initialize.instructions` locate UI inside `execute_code`, exclude it from catalog search, state the one-string call and mirrored return, and stay within the complete 1,000-character budget) |
+| `U13` | `test/code-first-surface.test.ts`, `test/server.test.ts` (served `initialize.instructions` locate UI inside `execute_code`, exclude it from connector search, state the mirrored-return duty, and stay within the complete 1,000-character budget; the usage skill carries detailed call rules) |
 | `X3` | `test/quickjs-executor.test.ts` (cancels a running child) |
 | `X4` | `test/guest-api-contract.test.ts` (string logs only) |
 | `X6` | `test/quickjs-executor.test.ts` (never-settling await) |

package/documentation/connector-guides.md

@@ -40,13 +40,17 @@ hand-written connector. It is deployment-owned configuration like everything
 else here: an edit and a redeploy, never a runtime registration.
 
 `content` is returned byte for byte by `skills({ name: "connector:<id>" })`.
-`summary` is normalized and capped at 120 characters for discovery. Omit it and
-connecta derives the same bounded line the skills listing uses: the first
-meaningful body line, with frontmatter, fences, rules, comments, and table rows
-skipped, a heading used only when the guide has no body, and the connector's
-description as the last resort. A derived summary is usually worse than a
-written one — it was written to open a document, not to answer "is this guide
-relevant to what I am about to do".
+`summary` is normalized and must fit 120 characters. A longer configured value
+refuses construction instead of silently changing the operator's words. Omit
+it and connecta derives the same bounded summary the skills listing uses: the
+first meaningful body paragraph, joined across Markdown's physical line wraps,
+with frontmatter, fences, rules, comments, and tables skipped. When the
+paragraph does not fit, connecta keeps a useful complete sentence when one
+fits, then prefers a clause or word boundary before adding an ellipsis. A heading is used
+only when the guide has no body, and the connector's description is the last
+resort. A derived summary is usually worse than a written one — it was written
+to open a document, not to answer "is this guide relevant to what I am about
+to do".
 
 `connector:<id>` is the only address for a guide, and built-in skill names are
 bare identifiers, so a guide can never shadow or be shadowed by `usage`: a
@@ -56,15 +60,12 @@ unknown name, unknown connector, connector with no guide — is an explicit
 error. Nothing silently falls back to the generic guide, because a generic
 answer to a specific question is worse than no answer.
 
-Discovery text is conditional on the deployment actually having a guide. The
-guide sentences in the `skills`, `search_tools`, `call_destructive_tool`, and
+Discovery text is conditional on the deployment actually having a guide. Short
+pointers in the `skills`, `search_tools`, `call_destructive_tool`, and
 `execute_code` descriptions appear only when at least one visible connector
-declares one — the connector set is fixed at construction, so this is stable
-per deployment, and a deployment with no guides pays no always-loaded context
-for a feature it does not use. The built-in `usage` skill is the deliberate
-exception: it stays byte-identical across every deployment, including its
-per-connector-guides section, so an agent that has read it once in a task never
-needs a deployment-local copy of it.
+declares one. The detailed selection rules live only in the built-in `usage`
+skill. That skill stays byte-identical across deployments, including its
+per-connector-guides section, so an agent reads it at most once per task.
 
 ## What belongs in a guide
 
@@ -160,15 +161,16 @@ schemas will never carry, because it cannot change them
 ## Tests that enforce this
 
 `test/meta-tools.test.ts` owns the guide behavior end to end: the skills
-listing carrying one entry per guided connector, summaries derived from the
-first meaningful line and falling back to the connector description when the
-guide is all markup, whitespace-only guides treated as no guide, content
-returned verbatim including surrounding padding, identical content in two
-deployments staying isolated, every miss erroring rather than falling back to
-the generic guide with an identically labelled skills list on each branch, the
-`guide` pointer in search output, and `guideRequired` appearing for
-connector-required conventions, approval-bound tools, and truncated schemas —
-and being absent from a search that asked for no schemas. `test/server.test.ts`
-owns the conditional half: it compares a guide-free deployment's four tool
-descriptions against a guided one's, and asserts the `usage` skill is
-byte-identical between them.
+listing carrying one entry per guided connector, summaries joining a
+hard-wrapped opening paragraph and shortening at readable boundaries,
+configured summaries refusing construction past the bound, heading and
+description fallbacks, markup skipping, whitespace-only guides treated as no
+guide, content returned verbatim including surrounding padding, identical
+content in two deployments staying isolated, every miss erroring rather than
+falling back to the generic guide with an identically labelled skills list on
+each branch, the `guide` pointer in search output, and `guideRequired`
+appearing for connector-required conventions, approval-bound tools, and
+truncated schemas — and being absent from a search that asked for no schemas.
+`test/server.test.ts` owns the conditional half: it compares a guide-free
+deployment's four short pointers against a guided one's, and asserts the
+complete `usage` skill is byte-identical between them.

package/documentation/connectors.md

@@ -252,6 +252,17 @@ the cursor ends, preserve schemas and annotations, and never cache or serve a
 partial walk. The fixed TTL is paired with a schema fingerprint so a changed
 catalog invalidates persisted results even within the time window.
 
+Agent reads use a complete entry inside `staleCatalogSeconds` immediately and
+defer the refresh that read already demanded. Every live refresh is
+single-flight per connector in one runtime. A blocking operator or direct read
+joins an agent-owned refresh and awaits it; an agent stale read joins an
+operator-owned refresh without awaiting it. The first refresh owns the context
+and deadline. A deferred first refresh owns a fresh scope and signal, then
+closes that scope. Operator status and direct registry reads still await
+freshness. The operator page reports whether the last agent read in this runtime
+was fresh or stale; this payload-free timestamp is not persisted. No timer or
+idle warmup originates downstream traffic.
+
 Tool calls must use the shared invocation path. That keeps direct calls, batch
 children, and code-mode host calls aligned on safety, retries, admission,
 timeouts, validation, result guards, and typed failures.
@@ -259,7 +270,8 @@ timeouts, validation, result guards, and typed failures.
 Connector usage guides are configuration too. `usageGuide` accepts the
 historical markdown string or `{ content, summary?, required? }`; the latter
 lets discovery explain what the guide covers without loading it. The summary
-is only a bounded routing hint. Mark a guide `required` only when no complete
+is a 120-character routing hint; a longer configured value refuses construction
+instead of being silently shortened. Mark a guide `required` only when no complete
 tool schema can describe correct use, such as a generic operation wrapper or a
 mandatory cross-tool sequence. Mutations and truncated compact schemas already
 produce automatic review requirements. Two deployments may reuse the same

package/documentation/meta-tools.md

@@ -60,6 +60,14 @@ their smallest successful one-tool shapes:
 
 ## Discovery context
 
+The deployment-derived `execute_code` description includes a live connector
+inventory before any catalog search. It preserves registry order and uses each
+canonical id, adding `shortcut <name>` only when the program namespace differs.
+The complete inventory line is capped at 256 UTF-8 bytes. Entries stay whole,
+and a truncated line ends with the exact `+N more` count. This reads only the
+configured registry: it loads no catalog, probes no credential, grants no
+capability, and does not replace canonical discovery or addressing.
+
 Start an unknown-address lookup with two to four distinctive action/object
 terms, not the full request, and omit `limit` so the default eight-result page
 stays small. When the integration is obvious, set `connector` to its id: a
@@ -89,14 +97,16 @@ Compact search is deliberately a routing view, not a second copy of connector
 documentation. Tool purposes are capped at 160 characters, connector
 descriptions and property prose are omitted, required input fields render
 before optional ones, and each input or output shape is capped at 1,024 UTF-8
-bytes. Within that unchanged total, each enum node may spend at most 256 UTF-8
-bytes. This lets about three near-cap enum nodes coexist while reserving the
-remaining quarter for surrounding syntax; the global fallback still applies
-when the complete shape exceeds 1,024 bytes. A large enum keeps the longest
-whole-value prefix that fits, then adds `unknown` and a comment with the exact
-omitted-value count. An empty enum renders as the valid `never` type. A capped
-object becomes a valid required-first shape with `unknown` types; other shapes
-become `unknown /* truncated */`. Either cap marks the match with
+bytes. Within that unchanged total, each enum node and each constraint
+annotation may spend at most 256 UTF-8 bytes. Numeric bounds, string length
+bounds, patterns, and formats render beside their type. A constraint that does
+not fit is dropped whole. If constraints push the full shape over 1,024 bytes,
+search retries the shape without them. Compact describe keeps all declared
+constraints. A large enum keeps the longest whole-value prefix that fits, then
+adds `unknown` and a comment with the exact omitted-value count. An empty enum
+renders as the valid `never` type. A capped object becomes a valid
+required-first shape with `unknown` types; other shapes become
+`unknown /* truncated */`. Any cap marks the match with
 `inputSchemaTruncated` or `outputSchemaTruncated`; repeat the search with
 `includeSchemas: "json"` or use the existing describe path when exact
 constraints matter. Small enums and both exact paths remain complete.
@@ -107,12 +117,13 @@ A connector may attach a deployment-owned guide as markdown, preserving the
 original `usageGuide: string` configuration, or as
 `{ content, summary?, required? }`. The structured form does not register a
 connector or create a shared runtime template. `content` remains the markdown
-returned verbatim by `skills`; `summary` is normalized and capped at 120
-characters for discovery. When it is absent, Connecta derives the same bounded
-fallback used by the skills listing: the first meaningful body line, with a
-heading used only when the guide has no body. `required: true` is reserved for generic
-API wrappers and cross-operation conventions a complete downstream schema
-cannot express.
+returned verbatim by `skills`; `summary` is normalized and refuses construction
+when it exceeds 120 characters. When it is absent, Connecta derives the same
+bounded fallback used by the skills listing: the first meaningful body
+paragraph, joined across physical Markdown line wraps and shortened at a
+sentence, clause, or word boundary, with a heading used only when the guide has
+no body. `required: true` is reserved for generic API wrappers and
+cross-operation conventions a complete downstream schema cannot express.
 
 Search and describe results keep the existing `guide: "connector:<id>"`
 pointer and add `guideSummary`. A matching tool also carries
@@ -143,8 +154,12 @@ the zero-tool page.
 The built-in `usage` skill is byte-identical across deployments and says to
 read it at most once per task. Connector guides remain scoped to the deployment
 that listed them, even when two deployments happen to use identical content.
-Deployments without connector guides receive none of the conditional guide
-sentences in their always-loaded tool descriptions.
+The always-loaded instructions and seven tool definitions own route selection,
+the fail-closed boundary, and the minimum guest syntax. The usage skill owns
+program selection detail, examples, runtime differences, and repair guidance.
+This split avoids two normative copies while preserving a valid first program
+for clients that never fetch the skill. Deployments without connector guides
+receive none of the short conditional guide pointers in their definitions.
 
 ## Result representation
 
@@ -170,12 +185,18 @@ can shrink anything before it returns.
 
 `fields` keeps its historical flat `{ "<path>": value }` result when every
 requested dot-path resolves. Dot notation traverses objects; append `[]` to an
-array field before continuing, as in `results[].id`. An exact downstream
+array field before continuing, as in `results[].id`. Empty arrays resolve to
+empty arrays. An exact downstream
 `$connecta` field is always escaped under `data`. If any path misses—or that
 reserved name is selected—the result carries matches under `data` and reserves `$connecta` for a
 `type: "field_projection"` recovery record naming each `unmatchedFields`
-entry. When a miss matches a declared array path except for `[]`, the record
-also carries the traversal hint. The discriminator means downstream fields
+entry. A path that resolves for only some array elements stays in `data` and
+appears in `partialFields`; its unresolved positions serialize as `null`, while
+the recovery record distinguishes them from genuine downstream nulls. A path
+that misses every element appears in `unmatchedFields` and is omitted from
+`data`. Both lists scale with requested paths, never with array length. When a
+miss matches a declared array path except for `[]`, the record also carries the
+traversal hint. The discriminator means downstream fields
 named `data`, `projection`,
 or `$connecta` remain ordinary values nested under `data`, never apparent
 metadata. A declared output schema contributes a bounded `availableFields`
@@ -307,6 +328,16 @@ a tool. A read path that reaches an unannotated, write-capable, or destructive
 tool returns `nextAction` for `call_destructive_tool` with the canonical
 address. Nothing is executed by these records.
 
+`connecta.describe` keeps failures inline so one miss cannot discard the other
+schemas. Each failed entry keeps its human `error` and adds `errorDetails` with
+the equivalent invocation `code` and `retryable`. Address and tool misses use
+the same route-aware discovery action above. A close tool-name miss on a known
+connector may also carry `suggestions`: at most three deterministically ranked
+canonical addresses, with no scores or descriptions. An unknown connector
+stays unscoped and has no suggestions. A catalog-load failure carries only
+`code`, bounded `message`, `retryable`, and any `retryAfterMs`; discovery does
+not inherit later additions to the call-failure envelope.
+
 That route echoes the caller's own arguments back only while they fit a
 512-byte budget, and then whole — never clipped. An error envelope is not
 size-guarded the way a result is, so an unbounded echo would let a large
@@ -384,3 +415,6 @@ duplicate `additionalProperties` branches never reach the caller. A schema the l
 validator cannot evaluate passes through to the provider. Provider error prose
 is not parsed or guessed, so an unknown format remains
 `connector_call_failed`.
+
+Describe's nearby-address list uses the same three-item recovery bound. It
+contains addresses only; it never serializes ranking scores or result prose.

package/documentation/mixpanel.md

@@ -50,6 +50,26 @@ password, not ordinary configuration. Mixpanel currently labels service-account
 MCP authentication beta. Prefer OAuth unless the deployment is intentionally
 headless.
 
+## Conditional input contracts
+
+Mixpanel's hosted descriptions enforce three cross-field conditions that its
+input schemas do not encode. Connecta preserves those schemas unchanged under
+[P1](./provider-conventions.md#p1--normalize-by-adding-never-by-rewriting), so
+the maintained guide carries the missing call guidance:
+
+- `Get-Business-Context` requires `project_id` or `organization_id`.
+- `Get-Property-Values` requires `properties` or the deprecated `property`
+  alias. Event property values also require `event`.
+- `List-Properties` accepts `names` or `query`, never both.
+
+A read-only live audit on 2026-08-13 confirmed all three refusals against the
+US hosted endpoint. They are reported upstream as
+[`mixpanel/mixpanel-headless#202`](https://github.com/mixpanel/mixpanel-headless/issues/202).
+The vetted catalog records the same audit's schema digests for all 63 tools,
+so a later schema correction or regression appears by tool name in the
+maintainer drift check. The guide can then shrink when the downstream schema
+becomes complete; Connecta does not absorb the defect permanently.
+
 The wrapper classifies the documented observational tools as reads and the
 documented create, update, edit, merge, dismiss, duplicate, and delete tools as
 writes. An unfamiliar tool the downstream leaves unannotated fails closed onto

package/documentation/notion.md

@@ -237,6 +237,23 @@ and all deliberately absent: this is a deliberate tool surface, not a mirror of
 the API. Anything missing is reachable through a custom `api()` connector
 beside this one, which remains a first-class path.
 
+The 2026-03-11 contract also offers more fields on create and update. They were
+reviewed after the 0.17.0 drift check and remain deliberately absent:
+
+- `create_page` does not create workspace-private pages, apply templates,
+  choose page placement, or accept expanded icon and cover forms. Those change
+  ownership, start asynchronous content work, control ordering, or depend on
+  file surfaces. They are not extensions of the maintained page/row authoring
+  contract (#408).
+- `update_page_properties` does not lock pages, apply templates, or erase page
+  content. Locking is coordination state, templates finish asynchronously, and
+  `erase_content` permanently deletes every child block through the API. None
+  belongs under an approval named for property replacement (#409).
+
+`trash_page` stays separate and reversible. The current `create_page`,
+`update_page_properties`, and `trash_page` request subsets remain valid against
+the expanded published contract.
+
 There is also **no guarded raw-REST escape hatch** — no `notion_api_get`, no
 `notion_api_mutate`. The convention that permits one
 ([H14](./provider-conventions.md#h14--a-named-tool-must-beat-the-escape-hatch-and-the-escape-hatch-splits-by-safety))