@zackbart/connecta 0.10.5 → 0.11.0

package/documentation/code-first-exploration.md

@@ -38,7 +38,8 @@ The recommendation is to evolve Connecta toward:
   and result retrieval;
 - policy, credentials, egress, and auditing enforced below generated code; and
 - the current tool surface retained as a compatibility path and evaluation
-  control while the new path matures.
+  control while the new path matures — a retention that ended with #273, which
+  made the executor mandatory and deleted the classic surface outright.
 
 This was an exploratory spike, not a production implementation. The next agent
 should use these findings as a design brief rather than porting the prototype
@@ -195,7 +196,10 @@ It did not establish:
   complexity.
 
 The existing surface should therefore remain available during the transition
-as a compatibility mode, rollback path, and experimental control.
+as a compatibility mode, rollback path, and experimental control. It was, and
+then it was not: #224 made code-first the default and #273 removed the second
+shape entirely. The open questions above outlived the control arm rather than
+being settled by it.
 
 ## Recommended product shape
 
@@ -222,11 +226,10 @@ Turn the exploratory scenarios into a repeatable evaluation suite before
 changing the default surface. Run at least 20 independent samples per task and
 model, with prompt variation.
 
-That suite now exists as
-[`eval/code-first-gate`](../eval/code-first-gate/README.md): these ten scenarios
-as versioned tasks with three phrasings each, the classic nine-tool surface as
-the control arm, and a per-model report that ends in a flip/hold verdict without
-flipping anything.
+That suite was built under
+[`eval/code-first-gate`](../eval/code-first-gate/README.md). Its recorded results
+remain as measurement history; the runnable comparison was retired when #273
+removed the alternate deployment shapes.
 
 Capture:
 
@@ -254,16 +257,13 @@ catalogs, centralized invocation, admission control, and lazy connector
 capabilities. Build the new surface on those rather than recreating parallel
 logic in the executor.
 
-### Phase 3: ship behind an explicit surface choice
+### Phase 3: consolidate the surface
 
-Offer code-first and classic modes initially. Executor-backed deployments can
-opt into code-first while deployments without a safe executor remain classic.
-Keep consequential writes outside the sandbox in both modes.
-
-Once the repeated model eval and production telemetry are healthy, make
-code-first the executor-backed default. Avoid adding new top-level read tools
-unless a measured case cannot be expressed safely or clearly through the
-programmable surface.
+This phase is complete: code-first became the default in #224, then #273 made
+the executor mandatory and removed the deployment choice. Consequential writes
+remain outside the sandbox. New top-level read tools still require a measured
+case that cannot be expressed safely or clearly through the programmable
+surface.
 
 ### Phase 4: stabilize successful workflows
 

package/documentation/code-mode.md

@@ -20,19 +20,11 @@ are stable and cited by the tests in [Verification](#verification).
 
 ## Deploy-time capability
 
-The `executor` passed to `createConnecta()` is the complete switch, and it selects
-the whole surface rather than one tool
-([#224](https://github.com/zackbart/connecta/issues/224)): with a live `Executor`,
-`tools/list` is exactly seven — `execute_code`, `search_tools`, `call_tool`,
-`call_destructive_tool`, `authorize_connector`, `get_result`, `skills`; without one
-it is the nine base meta-tools, whose `list_connectors`, `describe_tools`, and
-`batch_call` are what seven folds into `connecta.search`, `connecta.describe`, and
-`connecta.batch`.
-
-No feature flag, and no code tool advertised before it can be honored.
-`surface: "classic"` beside an executor is the one override (ten tools, the eval
-gate's incremental arm); `surface: "code-first"` without one throws at
-construction rather than advertise an absent program surface.
+The `executor` passed to `createConnecta()` is required. `tools/list` is exactly
+seven — `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`,
+`authorize_connector`, `get_result`, and `skills`. Construction fails when the
+executor is missing, and the removed `surface` option is rejected rather than
+ignored ([#273](https://github.com/zackbart/connecta/issues/273)).
 
 On Node, install the optional `quickjs-emscripten` peer and use the package's
 QuickJS subpath:
@@ -51,25 +43,20 @@ const connecta = createConnecta({
 CPU, wall-time, memory, stack, queue, result, log, and IPC bounds are configured
 on the executor. Server bundlers must keep the `@zackbart/connecta/quickjs`
 package files external so the child entry stays on disk. The
-[Node example](../examples/node/README.md) is enabled; remove its `executor` field
-for the nine-tool compatibility deployment.
+[Node example](../examples/node/README.md) carries the complete setup.
 
-On Cloudflare Workers, the Worker Loader binding is both the paid capability and
-the configuration switch:
+On Cloudflare Workers, the Worker Loader binding provides the required sandbox:
 
 ```ts
 createConnecta({
-  ...(env.LOADER
-    ? { executor: new DynamicWorkerExecutor({ loader: env.LOADER }) }
-    : {}),
+  executor: new DynamicWorkerExecutor({ loader: env.LOADER }),
   // connectors, auth, storage…
 });
 ```
 
-Leave the binding absent on the Workers Free plan. Its absence must also be
-represented as optional in the deployment's `Env` type. The
+Dynamic Workers require the Workers Paid plan. The
 [Worker example](../examples/worker/README.md#code-mode) carries the complete
-binding and package setup.
+required binding and package setup.
 
 ## What an executor must implement
 
@@ -98,7 +85,8 @@ 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's provider carries
-   `search`, `describe`, `call`, `batch`, and `__callNamespace` — see point 3.
+   `search`, `describe`, `call`, `batch`, `emit`, and `__callNamespace` — see
+   point 3.
 2. **Evaluate `prelude` after the provider globals exist and before the
    program**, in a scope where those globals are reachable. It is host-authored
    trusted code, never model input, and skipping it is not an option: connecta's
@@ -127,6 +115,10 @@ Optionally implement `AdmittingExecutor` (`acquire()` returning a lease whose
 `execute` runs once) for bounded admission (`L7`) and `close()` for shutdown;
 connecta wraps a plain `Executor` with `withExecutorAdmission` otherwise.
 
+Note what is *not* on this list: [emitted output](#emitted-output) asks
+nothing of an executor — `connecta.emit` is just another provider function
+(`M8`).
+
 ## The program
 
 **P1.** A program is one JavaScript `async` arrow-function expression. It is
@@ -300,13 +292,22 @@ const outcomes = await connecta.batch([
 order. A success is `{ address, ok: true, data }`. A failure is
 `{ address, ok: false, error, errorDetails }`, where `error` is the message and
 `errorDetails` is the typed object described in [Errors](#errors) — the same two
-field names `batch_call` uses. One failing call never rejects the batch, and more
-than ten calls throws.
+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.
 
+### connecta.emit
+
+```js
+await connecta.emit({ type: "image", data: shot.data, mimeType: "image/png" });
+```
+
+The rich-output channel, delivered after the JSON envelope on success. Its
+clauses are [Emitted output](#emitted-output) (`M1`–`M10`).
+
 ## Errors
 
 **E1.** There are four error channels, and only two of them are typed.
@@ -354,11 +355,12 @@ program may do about it.
 sentence. A program cannot recover credentials — only an operator can — so the
 right move is to stop and let the failure reach the model.
 
-**E4.** A read-only refusal is not a downstream failure. An unannotated,
-write-capable, or destructive tool is refused in the sandbox with
-`destructive_tool_requires_approval` and stays refused; the program returns and
-the model crosses `call_destructive_tool`, where the host can ask a human.
-Generated code cannot mint that capability.
+**E4.** An unannotated, write-capable, or destructive tool stays refused with
+`destructive_tool_requires_approval`; `nextAction` carries its canonical address
+to `call_destructive_tool`, plus the original arguments when they fit the
+512-byte echo budget — whole or not at all, since a clipped copy is a different
+call. The model's short `reason` for the human reviewer grants no authority,
+never goes downstream, and generated code cannot mint the capability.
 
 **E5.** Failures of the *execution*, not of a call, never appear inside the
 guest: admission rejection (`executor_overloaded`, retryable, with
@@ -377,11 +379,9 @@ 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`.
+**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.
 
-**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. Unsupported schemas pass through; unrecognized provider prose remains `connector_call_failed`.
+**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. Unsupported schemas pass through; unrecognized provider prose remains `connector_call_failed`.
 
 ## Results and projection
 
@@ -423,12 +423,70 @@ on data nobody asked for.
 
 **R5.** `console.log`, `console.warn`, and `console.error` are captured in call order and returned as a single `logs` string, capped at 4,000 characters with a truncation marker. Logs survive failure — they ride along with the error result, which is what makes them worth writing. How a non-string argument renders is not contract (`X4`).
 
-**R6.** Nothing else is added to a normal program result. Passing `diagnostics: true` adds one request-local, payload-free `diagnostics` block; omitted and `false` are byte-for-byte the ordinary response path.
+**R6.** Nothing else is added to a normal program result. Passing `diagnostics: true` adds one request-local, payload-free `diagnostics` block; a program that emitted adds `emitted: N` and its blocks (`M2`). Omitted, `false`, and emit-free are byte-for-byte the ordinary response path.
 
 **R7.** Timing separates admission, provider setup, total executor wall time, catalog work, and connector work. Catalog and connector values are cumulative, so parallel work can exceed executor wall time. Each used operation kind (`search`, `describe`, `call`, `batch`) gets one aggregate with count, failures, duration, returned serialized bytes, and catalog/connector time; batch adds only its total child count.
 
 **R8.** Diagnostics contain measurements and fixed operation names only: no addresses, arguments, results, code, credentials, logs, or raw errors. Result sizes are numbers, never previews. The collector exists only for the opted-in request; it is not activity, a session, or a stream.
 
+## Emitted output
+
+MCP-native output a return value cannot carry: base64 is not projectable, so a
+block that survives intake uncapped (`S5`) must not die at the `R2` exit
+guard. The argument and the refused alternatives live in the
+[design record](./rich-output-design.md) and `ethos.md`
+([#267](https://github.com/zackbart/connecta/issues/267),
+[#270](https://github.com/zackbart/connecta/issues/270)).
+
+**M1.** `connecta.emit(block)` accepts exactly one block: `{ type: "text",
+text }` or `{ type: "image" | "audio", data /* base64 */, mimeType }`, every
+field a string, no extra fields, no `annotations`, no `_meta`, no sugar forms.
+An invalid block throws catchably and nothing is accepted — rejected, not
+stripped. The refused types are pointers: a guest-minted `resource_link` URI
+is a lure a client may dereference.
+
+**M2.** Blocks collect on the host in emission order and are delivered only
+with a successful result, appended to `content` after the JSON envelope, which
+gains `emitted: N`. A program that never emits produces the byte-for-byte
+ordinary response (`R6`). `structuredContent` stays the envelope alone —
+emission is presentation, not a second data channel.
+
+**M3.** Return value and emission are independent: `R2` never measures emitted
+bytes, a truncated return does not suppress delivered blocks, and blocks do
+not shrink the return budget.
+
+**M4.** A failed program delivers no blocks. The error result reports
+`emittedDiscarded: N` when N > 0 — a field on the structured envelope, a
+trailing line on the plain-text paths — never silently.
+
+**M5.** Two budgets (`ConnectaConfig.execute.maxEmittedBytes` /
+`.maxEmittedBlocks`, defaults 4,000,000 serialized bytes and 32 blocks) fail
+loudly at the `emit` call, naming the budget and the room remaining; nothing
+is partially accepted and prior blocks stand. No `get_result` stash: the
+program learns while it can still choose differently. The byte default is a
+transport bound, not a context bound — emitted media reaches the model as
+media, not base64 text.
+
+**M6.** No provenance is claimed: every emitted block is program output,
+trusted exactly as much as the return value. Preservation is re-emission of
+the raw downstream block, so `S5`'s uncapped fallthrough is contract.
+
+**M7.** `emit` spends no host-call budget (`L4`); `M5`'s bounds are its only
+bounds.
+
+**M8.** Emission asks nothing of an executor: `emit` is a provider function,
+blocks cross the guest boundary once as an argument, and `ExecuteResult` is
+unchanged — `Executor` stays assignable from `@cloudflare/codemode`'s
+`DynamicWorkerExecutor`, and any executor that bridges provider calls gets
+emission for free.
+
+**M9.** Request-local and unstreamed: blocks exist only in the finished
+response, and `emit` resolving means "accepted," never "delivered."
+
+**M10.** Activity stays payload-free. `diagnostics: true` adds one `emitted`
+aggregate — count and serialized bytes, numbers only (`R8`), present only
+when something was emitted.
+
 ## Retry semantics
 
 **Y1.** Connecta retries nothing beneath a program. `call_tool` accepts an
@@ -519,27 +577,34 @@ itself (`R2`, `R5`).
 
 ## Activity
 
-**V1.** One payload-free activity event per call that named a real connector,
-with `source: "execute_code"` — every dispatched call, plus every refusal
-connecta could attribute to a connector: a read-only refusal, an unknown tool on
-a known connector, an ambiguous shortcut, a connector whose catalog could not be
-loaded, a credential connecta could not supply, an exhausted host-call budget. A
-program that calls ten tools is ten events — as legible as ten `call_tool` calls,
-which is what makes moving work into the sandbox an optimization, not a
-blindfold.
+**V1.** One payload-free activity event per attempted call, with
+`source: "execute_code"` — every dispatched call plus every local refusal: a
+read-only refusal, an unknown tool, an ambiguous shortcut, an unloadable
+catalog, a missing credential, an exhausted host-call budget, an address no
+connector owns. Ten tools called is ten events, as legible as ten `call_tool`
+calls — which makes moving work into the sandbox an optimization, not a blindfold.
 
 **V2.** Each event carries `connectorId`, `toolName`, `address`, `source`,
 `outcome` (`success`, `error`, `timeout`, `cancelled`), `durationMs`,
-`attempts`, and `errorCode` when there was one — plus the request's id, actor,
-and server identity. It has nowhere to put arguments, results, program source,
-or raw error text, by construction. A failure the program *caught* is still
-recorded: the call happened. `address` is canonical (`A1`) for every call that
-resolved to a tool; for the refusals that never resolved to one it is the name the
-program used, which for a shortcut is the sanitized alias — the honest record of
-what was attempted.
-
-**V3.** A call whose connector does not exist — an unknown address — emits
-nothing. There is no connector to attribute it to.
+`attempts`, and `errorCode` when the call *failed* — plus request, actor, and
+server identity. Typed codes derive an optional `friction`: `tool_not_found`,
+`schema_retry`, `destructive_reroute`, or `auth_required`. The fifth class,
+`result_too_large`, cannot reach an `execute_code` event: it belongs to a
+`call_tool` result too large to return inline, and a program's own
+return is refused paging by design rather than truncated into friction. There is
+nowhere to put arguments, results, program source, or
+raw error text; a caught failure is still recorded. `address` is
+canonical (`A1`) where a tool resolved, otherwise the name the program used —
+for a shortcut its sanitized alias, the honest record of what was attempted.
+
+**V3.** A call whose connector does not exist is recorded at the address as
+written, *provided* it split into the two fields activity keeps — one with no
+interior dot records nothing. An invented id is the address mistake an operator
+most needs to see. But recording it as written puts caller-authored text in
+fields that are otherwise operator- and connector-authored, so `connectorId`
+and `toolName` clamp at 128 UTF-8 bytes (`address` at 257) with a `…` marker:
+payload-free *by construction* means the event has nowhere to put a payload,
+not merely that connecta declines to.
 
 **V4.** The execution itself emits no event. It has no address, and its one
 distinctive artifact is the program source, which is exactly what a payload-free
@@ -614,8 +679,8 @@ entry. Programs that ran before still run.
 
 - **`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 `batch_call`'s field names so one shape covers
-  both surfaces.
+  failure. Additive, and it reuses the host's internal batch field names, so a
+  program and the host describe a failed call the same way.
 - **A policy refusal can no longer look retryable** (`E7`). Pinned in code rather
   than read out of message text, so a connector named `svc-503` stops flipping a
   permanent refusal to `retryable: true`. This reaches the call tools too.
@@ -632,6 +697,10 @@ The middle three were places where the contract described behavior the code did
 not quite have. The code moved, because the described behavior is the one worth
 having.
 
+One surface was added since: [emitted output](#emitted-output) (`M1`–`M10`,
+[#270](https://github.com/zackbart/connecta/issues/270)) — additive by
+construction, with the byte-for-byte no-emit promise pinned by test.
+
 ## Verification
 
 Every clause has a test. `test/guest-contract-cases.ts` holds the case table,
@@ -681,19 +750,24 @@ the upstream `Executor` shape assignable.
 | `L5`, `X2` | `test/quickjs-executor.test.ts` (CPU, heap) |
 | `L6`, `X10` | `test/quickjs-executor.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message) |
 | `L7` | `test/execute.test.ts`, `test/executor-admission.test.ts` |
-| `V1`, `V2` | `test/guest-api-contract.test.ts` (dispatched calls, and the four refusal classes that name a connector), `test/activity.test.ts` |
-| `V3`, `V4` | `test/guest-api-contract.test.ts` (no event without a connector) |
+| `V1`–`V4` | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, and the identity clamp) |
+| `M1` | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (every rejected shape) |
+| `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) |
+| `M5`, `M7` | `test/execute-emit.test.ts` (both budgets fail the crossing block; host-call budget untouched) |
+| `M6`, `M9` | verdicts; `M1`'s strict typing and `M2`'s collect-then-deliver are their enforcement |
+| `M8` | two arms passing one case table, `test/codemode-compat.test.ts` |
+| `M10` | `test/execute-emit.test.ts` (aggregate present, numbers only, absent when nothing emitted) |
 | `X3` | `test/quickjs-executor.test.ts` (cancels a running child) |
 | `X4` | `test/guest-api-contract.test.ts` (string logs only) |
 | `X6` | `test/quickjs-executor.test.ts` (never-settling await) |
 | `X7` | `P3`'s tests; the Workers superset is deliberately unused |
 
-The surface itself is checked by `test/server.test.ts` (the exact seven, nine, and
-ten tool lists) and `test/code-first-surface.test.ts` (the fold's construction
-rules, refusals, copy, and measured size). The release audit compares the same
-two shapes:
+The surface itself is checked by `test/server.test.ts` (the exact seven-tool
+list) and `test/code-first-surface.test.ts` (the fold's construction rules, the
+required executor, the refusals a removed top-level tool now gets, copy, and
+measured size). There is one shape left to audit, so there is one audit:
 
 ```sh
 npm --prefix eval/current-version run audit
-npm --prefix eval/current-version run audit -- --executor disabled
 ```

package/documentation/connectors.md

@@ -33,7 +33,7 @@ Connecta deliberately sits between protocol generations
   [#206](https://github.com/zackbart/connecta/issues/206).
 - **Multi-round-trip results:** a downstream `input_required` result becomes a
   non-retryable `input_required_unsupported` failure. `call_tool`, the
-  `execute_code` host bridge, and classic's `batch_call` all preserve the
+  `execute_code` host bridge and internal batch path both preserve the
   structured code. Relaying the
   opaque `requestState` is architecturally possible but gated until real hosts
   and downstreams adopt it.

package/documentation/meta-tools.md

@@ -4,26 +4,20 @@ Connecta keeps one small tool surface in model context and resolves downstream
 tools behind it. `search_tools` finds addresses, the call tools enforce safety
 annotations, and `get_result` pages bounded results.
 
-## Which surface a deployment serves
+## The deployment surface
 
-The `executor` decides it, and there is nothing else to configure
-([#224](https://github.com/zackbart/connecta/issues/224)):
-
-| | `tools/list` | Discovery breadth and batching |
-| --- | --- | --- |
-| **executor configured** | seven: `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`, `authorize_connector`, `get_result`, `skills` | `connecta.search`, `connecta.describe`, `connecta.batch` inside a program |
-| **no executor** | nine: the above minus `execute_code`, plus `list_connectors`, `describe_tools`, `batch_call` | those three top-level tools |
+Every deployment requires an executor and `tools/list` is exactly seven:
+`execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`,
+`authorize_connector`, `get_result`, and `skills`. Discovery breadth and
+batching live in `connecta.search`, `connecta.describe`, and `connecta.batch`
+inside a program ([#273](https://github.com/zackbart/connecta/issues/273)).
 
 Code-first is what a model sees. Four overlapping ways to reach one connector
 became two: `search_tools` then `call_tool` for a single cold read — measurably
 cheaper direct than through a program — and `execute_code` for everything wider.
-The fold is worth 19.6% of the serialized tool definitions measured against the
-ten-tool shape an executor-backed deployment used to serve — 10,675B to 8,587B —
-and, more durably, one fewer routing decision a model makes before doing any
-work. Note which baseline that is: the executor-free nine serialize to 7,207B,
-so the seven-tool surface is *larger* than the row below it in that table. It
-buys the program with those bytes. The [guest API contract](./code-mode.md) is
-what a program is promised.
+The consolidation removed overlapping routing choices while preserving the
+cheaper direct path for one cold call. The [guest API contract](./code-mode.md)
+is what a program is promised.
 
 `execute_code` accepts optional `diagnostics: true` when a caller is measuring
 a workflow. It adds only compact request-local timing and serialized-size
@@ -31,20 +25,11 @@ aggregates; normal calls carry no diagnostics block or response-context cost.
 The measurements never contain program source, arguments, values, addresses,
 credentials, logs, or raw error text.
 
-Classic is the compatibility surface: what an executor-free deployment
-necessarily serves, since the program surface the fold depends on is not there.
-It is supported and tested, not an equal citizen in the docs. `surface:
-"classic"` beside an executor is the only override; it produces the ten-tool
-shape the [eval gate](../eval/code-first-gate/README.md)'s *incremental* arm
-measures. That gate's control arm is executor-free classic and needs no
-override.
-
 Nothing became unreachable. `connecta.describe` takes the same addresses and
-formats as `describe_tools`, `connecta.batch` runs the same 1–10 parallel
-read-only calls as `batch_call` and returns the same typed outcomes, and an
-unfiltered `connecta.search({})` browses every catalog a program can reach —
-the part of `list_connectors` a model used. Live connector probing was the rest
-of it, and that is an operator concern: the operator pages and `/health` own it.
+formats as the internal catalog service, `connecta.batch` runs 1–10 parallel
+read-only calls and returns typed outcomes, and an unfiltered
+`connecta.search({})` browses every catalog a program can reach. Live connector
+probing is an operator concern: the operator pages and `/health` own it.
 
 ## Discovery context
 
@@ -61,8 +46,8 @@ shape. Bounded plain-object schemas also expose `inputKeys`,
 list rather than repeating a large partial inventory. Matches carry declared
 behavior annotations. When
 that shape is sufficient, call the returned address directly. Reserve schema
-expansion — `connecta.describe` in a program, `describe_tools` on the classic
-surface — for a search without schemas, an ambiguous compact shape, or exact
+expansion through `connecta.describe` for a search without schemas, an
+ambiguous compact shape, or exact
 constraints that require `format: "json"`.
 
 Compact search is deliberately a routing view, not a second copy of connector
@@ -89,6 +74,14 @@ mode; they are not a duplicated Connecta object result. Newly stashed JSON and
 downstream content envelopes use compact serialization, so `get_result` byte
 offsets and totals refer to that exact compact text.
 
+A `call_tool` truncation notice carries both the historical `resultId` and an
+exact `nextAction: { tool: "get_result", arguments: { id, offset: 0 } }`. The
+handle is therefore
+directly actionable without copying an identifier out of prose; re-calling with
+`fields` remains the smaller alternative when projection is possible. Program results and oversized discovery responses carry no such
+route — paging a program's return value is a refused shape, because a program
+can shrink anything before it returns.
+
 `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
@@ -172,6 +165,74 @@ only through the same-origin, Clerk-operator credential route. After OAuth
 consent or an operator update, retry the original operation; a static update is
 read from the vault on the next call and needs no redeploy.
 
+## Routing recovery
+
+Predictable local refusals carry structured recovery on both result modes.
+An unknown connector suggests an unscoped discovery query derived from the
+attempted tool name; an unknown tool scopes the same query to the connector that
+answered. The suggested route follows the route the caller took: `tool:
+"search_tools"` for a top-level call, `function: "connecta.search"` with the same
+arguments when the miss happened inside `execute_code`, which has no way to call
+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.
+
+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
+argument object produce a refusal many times the deployment's result cap, on
+both `call_tool` and calls a program routes through `connecta.call` or
+`connecta.batch`. Over budget, `args` is absent and the `purpose` says to
+re-send what was just sent: the agent already holds its own arguments, and half
+of them would describe a call nobody made.
+
+The address gets the same budget and the opposite rule: 512 bytes, clamped
+with a trailing `…` rather than dropped. It is caller-authored too — an
+invented one can be any length — and it reaches the error message *and* the
+recovery query, each of which lands in both the text content and
+`structuredContent`; unbounded, a 50 KB typo produced a 200 KB refusal under a
+1 KB result cap. Dropping it is not an option the way dropping arguments is:
+the address is the thing being corrected, a clipped one still identifies the
+mistake, and a short one — every real one — comes back exact and untagged.
+
+Shortcut ambiguity inside `execute_code` returns every colliding canonical
+address and points at `connecta.call`; the program or model must still choose
+which one matches the user's intent. `call_destructive_tool` accepts an optional
+`reason` of at most 500 characters for the host's human approval view. It is
+outer-call context only: Connecta neither treats it as authority nor passes it
+to the downstream connector, and an empty or whitespace-only one is read as no
+reason rather than as a reason to refuse the call.
+
+Activity carries an optional coarse `friction` class: `tool_not_found`,
+`schema_retry`, `destructive_reroute`, `auth_required`, or `result_too_large`.
+It is derived from the typed error code, except on the one call that has no
+error code to derive from: a result too large to return inline is friction for
+the agent while remaining `outcome: "success"`. That applies to a `call_tool`
+result, the only source of `result_too_large` friction. (Activity stored by
+older releases may still carry the retired `batch_call` source; nothing writes
+it today.)
+An oversized *discovery* response and an oversized program return are shaped
+differently and produce none, and an `errorCode` is written only when the call
+actually failed. The category adds no arguments, results, search text,
+generated code, credentials, or raw errors.
+
+An address whose connector does not exist is recorded too, as written, provided
+it has the `<connectorId>.<toolName>` shape at all — a string that never split
+into the two fields activity keeps still records nothing. A hallucinated
+connector id is the most common address mistake, and an operator reading
+activity should see it; addresses are already a first-class activity field, so
+nothing new is retained.
+
+What *is* new is that those fields now hold caller-authored text, so the
+recording seam clamps them: `connectorId` and `toolName` at 128 UTF-8 bytes
+each, `address` at 257, with a `…` marker. Far past any real id or tool name,
+and far short of a 40 KB invented one. The clamp is structural rather than a
+policy the writer applies, because "payload-free by construction" has to mean
+the event type has nowhere to put a payload — a 40 KB connector id is a payload
+wearing an id's clothing. Clamped rather than skipped: the invented id is
+exactly what an operator needs to see, and its first 128 bytes say as much
+about the mistake as all 40,000 would.
+
 ## Argument recovery
 
 A remote MCP tool's advertised `inputSchema` is checked in the shared
@@ -183,9 +244,11 @@ JSON Pointer `path`, schema-keyword `code`, and expected shape. Submitted
 values are never copied into those findings.
 
 At most three findings are returned; `validation.truncated` says when more
-exist. `nextAction` points to `search_tools` scoped to the same connector and
-tool name when the compact schema is needed, while `retry` says to correct the
-listed arguments and reissue the original operation. A schema the local
+exist. `nextAction` points to discovery scoped to the same connector and tool
+name when the compact schema is needed — routed like any other miss, so a
+program is sent to `connecta.search` and a top-level call to `search_tools` —
+while `retry` says to correct the listed arguments and reissue the original
+operation. A schema the local
 validator cannot evaluate passes through to the provider. Provider error prose
 is not parsed or guessed, so an unknown format remains
 `connector_call_failed`.