@zackbart/connecta 0.40.0 → 0.41.0

package/documentation/code-mode.md

@@ -1113,9 +1113,18 @@ 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.
 
-**V4.** The execution itself emits no event. It has no address, and its one
-distinctive output is the program source — exactly what a payload-free history
-must never keep.
+**V4.** By default the execution and its utility operations emit no events.
+With `activityHistory({ operations: true })`, each executed search, describe,
+result page and skill read adds a `kind: "operation"` row, and the whole program
+adds a `program` row with host-call counts. Utility attempts refused above the
+execution boundary remain represented by the program's host-call accounting.
+Rows use fixed operation names rather than argument-supplied addresses or IDs;
+they carry timings, typed outcomes/codes and serialized return byte counts,
+never program source or payloads. The existing detached sink handles storage,
+and these rows do not count as calls or friction. The
+[operation-history contract](./operator-ui.md#opt-in-to-operation-history)
+owns opt-in cost, scope and owner disclosure rules. Recording history changes
+no authorization or capability state.
 
 **V5.** A write a program issues after it has already returned is not
 sent and records nothing: it was never an attempt (`W9`).
@@ -1337,6 +1346,12 @@ receive a fixed description.
 
 ### Verification
 
+The QuickJS child imports only the guest runtime, IPC helpers and dependency-light
+error/route constants. `test/purity.node.test.ts` walks its emitted import graph
+to exclude server orchestration, Effect and the MCP SDK. The shared
+`InvocationFailure` constructor preserves host error identity across existing
+exports and typed IPC reconstruction.
+
 The earlier alternatives are in [decision history](https://github.com/zackbart/connecta/blob/main/decisions/0001-ethos-verdict-table.md)
 ([#267](https://github.com/zackbart/connecta/issues/267),
 [#270](https://github.com/zackbart/connecta/issues/270)).
@@ -1350,49 +1365,49 @@ rejection, and branded adapter acceptance across module copies.
 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                                                                                                                                                                                                                                                                                                                                                                                                           |
+| 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 execution event by default), `test/identity-write-journey.node.test.ts` (opt-in real-program utility/program rows, payload exclusion and detached writes), `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).

package/documentation/deploying.md

@@ -61,6 +61,17 @@ authenticated `admission.requests.maxBodyBytes` default. To accept larger MCP
 bodies, configure both core and `listen(..., { maxBodyBytes })`; a smaller
 platform, proxy or adapter cap still wins. See
 [request body limits](./architecture.md#admission-in-two-places).
+`listen(..., { maxInFlightBodyBytes })` caps the body bytes all in-flight
+requests hold together, counted from the first chunk until the response finishes
+or the client leaves. It defaults to 64 MiB, or `maxBodyBytes` when that is
+larger, and may not be set below `maxBodyBytes`. Past it a request gets `503` with
+`Retry-After: 1` and `Connection: close`. Raise it when legitimate concurrent
+large bodies are refused, keeping it within the process's memory budget.
+`listen()` answers `400` with `Connection: close`, before reading any body, when
+`Host` is anything but a host with an optional port, when `X-Forwarded-Proto` is
+anything but `http` or `https`, or when the request target does not start with
+`/`. A reverse proxy must overwrite `X-Forwarded-Proto` with one value; a
+comma-separated chain such as `https,http` is refused.
 A Node host serving `connecta.fetch` without `listen()` has no owned sender:
 every maintained-provider write, every reviewed POST read and every remote MCP
 write is refused before sending. Downstream OAuth credential POSTs also require
@@ -199,7 +210,9 @@ and `describeConfig()`, and [optional modules](./architecture.md#optional-deploy
 owns their composition contracts.
 
 Enable `encryptedCredentialVault(storage, key)` before persisting downstream
-OAuth credentials. Without a sealing vault, OAuth grants are stored as plaintext.
+OAuth credentials. With no vault, OAuth grants are stored as plaintext. A
+configured vault without `seal` and `open` refuses construction when any connector
+uses OAuth.
 The platform templates describe the base64 32-byte encryption key. Keep it
 outside the database and source control, and preserve it across upgrades.
 [OAuth state at rest](./auth.md#downstream-oauth-state-at-rest) owns sealing and
@@ -302,6 +315,17 @@ Bump the exact package pin, read the [changelog](../CHANGELOG.md) for every
 intervening release, and apply the relevant migration before startup. `init`
 does not merge changes into an existing deployment.
 
+A custom vault without `seal` and `open` now refuses construction when any
+connector has OAuth. Before upgrading, add both methods or switch to
+`encryptedCredentialVault(storage, key)`. Existing plaintext grants are sealed on
+first read; see [OAuth state at rest](./auth.md#downstream-oauth-state-at-rest).
+
+A deployment using `clerkAuth` must set a fixed URL before upgrading:
+`ConnectaConfig.publicUrl`, or `clerkAuth({ publicUrl })`. Startup otherwise fails
+with a configuration error. Use the origin clients reach, because tokens' `resource`
+must match it exactly; see
+[Clerk OAuth tokens](./auth.md#clerk-oauth-tokens-and-operator-sessions).
+
 Before upgrading past 0.37.1 with pre-0.29 state, follow
 [Retired layout migrations](./migration-retired-layouts.md). Version 0.37.1 is
 the last bridge for KV → D1, JSON → SQLite, and OAuth layout-2 conversions.

package/documentation/meta-tools.md

@@ -120,9 +120,11 @@ read-only endpoint nothing writes: `search_tools`, `connecta.search`, and
 `connecta.describe` omit write tools as if the connector lacked them, and
 every write call through `call_tool`, `call_destructive_tool`, or a program is
 refused before validation or dispatch with `read_only_endpoint`,
-`retryable: false`, and no `nextAction`. Connector guides are not filtered and
-may still name such a write. No route on that endpoint writes; the agent
-reports it. Connecta
+`retryable: false`, and an explicit statement that no write route exists here.
+Bootstrap instructions state the serving endpoint’s actual write policy. Connector
+guides preserve their authored Markdown and prepend the effective read-only
+endpoint or connection restriction: steps that change data will be refused.
+The agent reports the limitation and can ask the operator for a writable connection. Connecta
 never pauses, replays, or approves a program.
 
 Both search routes return the flat page specified under
@@ -373,7 +375,7 @@ even when a connector has that id, whose guide stays at `connector:usage` or
 `Connector "<id>" has no usage guide.`; any other unknown name fails as an
 unknown skill. Names containing `:`, including URIs, never fall back to a bare
 id. MCP `skills/get` resolves names the same way; `resources/read` accepts only
-document URIs.
+document URIs. Canonical names and document/root URIs take priority over compatibility aliases. An alias shared by multiple guides fails as ambiguous; use the canonical URI.
 
 A connector-scoped lexical miss keeps that connector's guide metadata under
 `queryAnalysis`. This matters for generic wrappers whose broad tool name
@@ -405,12 +407,16 @@ connector inventory, budgets, the endpoint's read-only setting, and whether any
 visible connector has a guide. No catalog outcome, call, authorization state,
 or other live status reaches `tools/list` or the instructions, so the
 always-loaded surface stays byte-stable for a client's prompt cache.
-The instructions are the same on every endpoint except one addition: at
+Instructions reflect the surface and endpoint write policy, subject to connector
+restrictions. When all admitted connectors are read-only, instructions state that
+writes are unavailable. They also include pool scope: at
 `/mcp/<pool>` and `/agent/<pool>`, a pool that sets a
-[`description`](./auth.md#pools) has it appended after `This endpoint: `, so
+[`description`](./auth.md#pools) has it placed first after `Use skills. `, so
 the model learns that endpoint's scope, for example
-`This endpoint: Team tier: shared tools only. For someone's own mail or files, ask them to message you one-on-one.`
-Plain `/mcp` never carries one. The description changes no tool or tool
+`Use skills. Team tier: shared tools only. For someone's own mail or files, ask them to message you one-on-one.`
+The guide pointer precedes the scope so both appear in the first 512 characters
+for a description of up to 500 characters. The routing rules follow. Meta instructions use compact equivalent routing rules
+when a scope is present. Plain `/mcp` never carries one. The description changes no tool or tool
 description, and `initialize` and `server/discover` stay `cacheScope: "private"`,
 so a client keeps what it learned per endpoint. Connector
 guides stay scoped to the deployment that listed them even when two deployments
@@ -419,17 +425,36 @@ the short conditional guide pointers in its tool definitions.
 
 ### Native Skills extension
 
+The [Skills extension](https://github.com/modelcontextprotocol/ext-skills) is Beta under
+[SEP-3392](https://modelcontextprotocol.io/seps/3392-extension-lifecycle): breaking
+revisions can reuse its ID. The released settings define no `revision`; Connecta
+refuses downstream declarations with an explicit revision rather than enabling
+unknown semantics. Upward handlers remain Connecta-owned to preserve caller views.
+
 Connecta declares `resources: {}` and `io.modelcontextprotocol/skills`, then
 serves `skills/list`, `skills/get`, `resources/list` and `resources/read` from
 the same registry as `skills` and `connecta.skill`. These methods return
-`resultType: "complete"`, `ttlMs: 0` and `cacheScope: "private"`. Listing pages
+`resultType: "complete"` and `cacheScope: "private"`. Local-only caller views
+advertise `ttlMs: 300000` (five minutes); any visible downstream skill source
+keeps `ttlMs: 0`, including reads of local guides on that view. Clients must key
+private caches by endpoint and authenticated caller. No request-bound catalog or
+digest promise is retained across requests. Listing pages
 contain at most five complete skills: usage first, required connector guides
 next, other connector guides, downstream skills, then the investigation guide.
 Subsequent pages use `cursor`/`nextCursor`. Local lookup works without listing.
 
 The local document URIs are `skill://connecta/usage/SKILL.md` and
 `skill://connecta/connectors/<slug>/SKILL.md`. A valid Agent Skills connector ID
-is its slug; other IDs use `connector-` followed by a stable SHA-256 prefix.
+is its slug; other IDs use a readable normalized ID slug plus a 12-character
+SHA-256 suffix. Generated slugs reserve every configured connector ID and append
+a deterministic numeric suffix on collision. Avoid a connector ID equal to another
+connector's generated name: allocation depends on the IDs a catalog can see, so
+adding one moves the other guide to a suffixed name.
+The former `connector-<48-character-hash>` names, roots and file URIs remain
+resolvable aliases. Construction warns, without rejecting a guide, when its
+summary has no English task verb or operation noun from the advisory heuristic
+(for example, a credential-only scope statement). Set `usageGuide.summary`
+to say when to load it; non-English prose may produce a false-positive warning.
 The suffix makes each
 document a valid Agent Skills file; the roots `skill://connecta/usage` and
 `skill://connecta/connectors/<connector-id>` also resolve. Provider guides are
@@ -459,6 +484,19 @@ from skill manifests; neither skill catalogs nor file bodies enter its response
 cache. A failed or malformed opted-in listing fails the entire skills catalog,
 with no partial cache. Known local guides remain readable during an outage.
 
+On `skills` and program `connecta.skill` reads, downstream text is prefixed with
+a fixed third-party origin sentence naming the connector (bounded to 128 ID
+characters). This prefix has no closing delimiter. `skills` listings carry the
+same sentence before each downstream description, collapsed to one line, in text
+and structured output. Program `connecta.read` applies it to text contents whose
+URI uses the `skill:` scheme or ends in `SKILL.md`; a downstream's other resources
+are returned as ordinary data, and binary contents are not labeled. Maintained and
+deployment guides remain unlabeled. Native `skills/get` metadata and `resources/read`
+contents stay unchanged so original manifest digests remain verifiable; adding a
+label there would break integrity checks. A native host must attach its own origin
+label when it loads verified content into model context, as the Skills extension
+requires.
+
 Downstream files are proxied byte-exact, including CRLF and binary supporting
 files, within 512 files and 16 MiB per skill. Catalog metadata is bounded to
 1,024 entries and 8 MiB. The existing request-scoped agent boundary redacts
@@ -1129,11 +1167,47 @@ Activity records each of these refusals with the coarse `friction` class derived
 from its typed error code — `tool_not_found`, `schema_retry`,
 `destructive_reroute`, `auth_required` — and clamps the caller-authored
 `connectorId`, `toolName`, and `address` it keeps, both under
-[code mode](./code-mode.md#activity)'s `V2` and `V3`. A `call_tool` result too
+[code mode](./code-mode.md#activity)'s `V2` and `V3`. Optional
+[operation history](./operator-ui.md#opt-in-to-operation-history) records
+search, skill and result reads with fixed names, without arguments or payloads;
+it is off by default and separate from downstream-call counts. A `call_tool` result too
 large to return inline is the one exception: it is friction
 (`result_too_large`) on a call whose `outcome` is still `"success"`, so it
 carries no `errorCode`.
 
+Recovery actions outside the tool namespace use `nextAction.action` and a
+`purpose`: `reconnect_host` repairs inbound HTTP authentication (separate from
+connector OAuth), `contact_operator` reports catalog or utility availability,
+`inspect_capabilities` requests a supporting client/operation, and
+`recover_result` requests a retained handle or an honest missing-output report.
+Unsupported task, Skills, and resource capabilities use the non-retryable
+`unsupported_capability` code with `inspect_capabilities`. Missing or expired handles have `code: not_found`; storage outages retain
+`code: unavailable`. Neither action authorizes anything or replays writes.
+Unknown skill names and connectors without a guide retain their local lookup
+diagnostic with `code: not_found` and a `nextAction` calling `skills` with no
+name to discover available names. They do not request service restoration.
+The search output schema describes action discriminators compactly; action
+advice is additive, while catalog error and authorization handoff fields retain
+their detailed contracts.
+A spent read continuation's fresh-call action takes precedence over generic
+retry advice, while auth and provider permission repair prerequisites and unknown-write reconciliation remain
+in force. HTTP 401/403 responses preserve the adapter status and challenge. JSON responses
+carry the host recovery envelope. Custom non-JSON responses preserve their body
+and lifetime, with the same typed facts in `Connecta-Error-Code`,
+`Connecta-Recovery`, and JSON-encoded `Connecta-Next-Action` headers (also exposed
+to cross-origin hosts).
+
+## Recovery limits
+
+Typed `invalid_args` failures without validation findings point to scoped schema
+inspection. `not_found` asks the caller to verify the resource id, account and
+visibility. `unavailable` asks the operator to restore connector availability.
+These use `nextAction` for an executable action and `retry` for explicit limits.
+An uncertain write has no safe replay action: read its target to reconcile its
+outcome before deciding on any fresh operation. Host authentication requires
+reconnecting the host; downstream authorization handoffs repair credentials;
+provider permission denial requires the resource owner to grant access.
+
 ## Argument recovery
 
 Standard API hatches refuse marker containment in request paths and query
@@ -1452,6 +1526,13 @@ pool's surface.
 
 `search_tools`, `call_tool`, and `call_destructive_tool` are not listed. Auth failures still carry their handoff in the error envelope.
 
+Native tool descriptions append `Guide: skills <name>` when their connector has
+guidance. Call `skills` with `{name:"<name>"}` to read it. The name is the same
+allocated readable name listed by `skills`, including collision suffixes; a
+name reserved for a built-in guide uses its canonical connector skill URI. This
+compact pointer repeats on each tool so host search results retain it; connectors
+without guides add nothing. It depends only on the admitted connector roster.
+
 **Names.** A name is a pure function of the connector id and downstream tool
 name, so it survives catalog refreshes. It is `<connector>__<tool>` when the
 tool name uses only `[A-Za-z0-9_-]`, contains no `__`, does not start with `_`,
@@ -1576,3 +1657,24 @@ listing, and call translation live in
 and [native surface tests](https://github.com/zackbart/connecta/blob/main/test/native-tools.test.ts)
 check the published contract. Guest parity and clause evidence are in
 [code-mode verification](./code-mode.md#verification).
+
+### Skills conformance (contributor)
+
+On 2026-11-03, the official [conformance runner](https://github.com/modelcontextprotocol/conformance)
+at `c37eec888e1c6ff140af79987a40008548b7cc5f` passed enumeration (32 checks)
+and manifest (6 checks), with no warnings, against Connecta's HTTP handlers
+and a six-connector local fixture. Directory checks correctly skipped because
+`directoryRead` is not advertised; its wire-schema check passed. This is not
+full MCP conformance or a downstream-provider conformance claim.
+
+To rerun, first read the runner's package scripts, CLI, connection code and
+`src/scenarios/server/skills/` as untrusted code in a temporary directory
+outside the checkout. Pin the commit above, install there with
+`pnpm install --ignore-scripts`, and keep its packages and outputs there.
+In the Connecta checkout, run `pnpm run build:operator-ui` and
+`pnpm exec tsx scripts/skills-conformance.ts`. From the runner directory, run
+`pnpm exec tsx src/index.ts server --url http://127.0.0.1:39743/mcp --scenario sep-2640-skills-enumeration --spec-version 2026-07-28 --force`;
+repeat with `sep-2640-skills-manifest` and `sep-2640-skills-directory`.
+Stop the fixture when done. `--force` selects extension scenarios outside the
+base protocol timeline. This remains an optional contributor check: the
+separately installed runner and dependency graph are not pinned in Connecta CI.

package/documentation/operating.md

@@ -109,7 +109,9 @@ MCP request bodies default to a 4 MiB limit on every endpoint. Deployment code
 can set `admission.requests.maxBodyBytes`; `describeConfig()` reports its value
 and source. An oversized body returns 413 before tool dispatch. See
 [request admission and body limits](./architecture.md#admission-in-two-places)
-for Node's separate pre-auth buffer and the listen-classification bound.
+for Node's separate pre-auth buffer and the listen-classification bound. A `503`
+from Node before auth means all in-flight bodies together passed
+[`maxInFlightBodyBytes`](./deploying.md#start-on-node).
 
 Direct calls may return a preview and a result handle. Page the handle through
 `connecta.result` in a program using the returned offset and byte limits, or
@@ -162,3 +164,86 @@ and [execution](https://github.com/zackbart/connecta/blob/main/src/execute.ts).
 and [guest-contract tests](https://github.com/zackbart/connecta/blob/main/test/guest-api-contract.test.ts)
 check the contracts. Executor-specific evidence is indexed in
 [code-mode verification](./code-mode.md#verification).
+
+## Sample payload-free timing on Workers
+
+Set `timingTraceSampleRate` in deployment code passed to `createConnecta`:
+
+```ts
+const app = createConnecta({
+  // ...the deployment's connectors, storage, auth and executor
+  timingTraceSampleRate: 0.1, // sample 10% of MCP requests; default 0 (off)
+});
+```
+
+The rate must be a finite number from 0 through 1. Set 1 for a short diagnostic
+window, then return it to 0. Sampling is independent of the caller's
+`diagnostics` argument. Enable Workers observability logs in the deployment's
+Wrangler configuration (`observability.logs.enabled: true`). Its own sampling
+may reduce captured records further. The configured logger receives
+`connecta.timing` and one structured object when the MCP response body closes;
+`logger: "silent"` suppresses these records too. Consume or close streaming
+responses to finish their trace. An isolate-first-request flag means the first
+MCP request that reaches tracing in that isolate, including unsampled requests;
+it does not measure module boot.
+
+Each version-1 record contains elapsed request time, the first-request flag,
+weak-reference availability and aggregate operation families. Each family has
+`count`, `durationMs`, `bytes`, `statements`, `items` and `absent` totals.
+`catalog.accepted` counts complete accepted catalogs, serialized bytes and tools. Invocation
+`catalog`, `admission`, `connector` and `result` durations reuse the existing
+`diagnostics` segments. `catalog.cache.lookup` counts cache probes; `catalog.cache.hit` counts accepted
+unexpired entries. Lookups without hits can include misses, expiry, invalid
+entries or interrupted reads; they are not proof of live relisting.
+`catalog.validated.hit`/`miss` report immutable validation reuse.
+`catalog.decode` counts JSON decodes and their UTF-8 input bytes;
+`catalog.validate` and `catalog.intake` count those stages without timing them.
+These three count-only families always have `durationMs: 0`.
+`catalog.chunks` records accepted chunk bytes and counts. These counters do not
+identify a connector, owner or private/public partition.
+Concurrent spans can overlap; do not sum them as wall time.
+`memo.hit`, `memo.miss` and `memo.fresh` describe the request-read memo
+(`absent` counts null values, not cache failures). `d1.read`, `d1.write` and
+`d1.batch` count physical native D1 trips and SQL statements, including
+failed attempts. Batch count is one trip; statements is the batch length.
+All native D1 work carrying the request context shares these totals, including
+admission, credential and catalog work. Comparing them with `catalog` duration
+(the diagnostics `catalogMs` segment) does not isolate catalog storage.
+Returned D1 bytes measure serialized application results, not Cloudflare's wire
+encoding. Memo bytes measure UTF-8 stored values. Result bytes use the existing
+invocation measurement. No keys, tool names, owner identity, arguments, results,
+credentials or error text enter the record. Records retain totals only.
+
+On production Workers, `performance.now()` advances only across I/O. Durations
+are I/O-spanning elapsed observations, not CPU attribution: zero is ambiguous,
+and CPU work can appear in a later I/O interval. D1 durations are therefore not
+pure storage latency. Use counts, sizes, cache outcomes and the isolate-first-request
+flag to compare warm direct and one-call program requests with the same catalog.
+For per-invocation CPU, use Workers' invocation telemetry field
+[`$workers.cpuTimeMs`](https://developers.cloudflare.com/workers/observability/query-builder/).
+Deeper attribution requires [CPU profiling](https://developers.cloudflare.com/workers/runtime-apis/performance/).
+
+Only work carrying the MCP request's native context contributes D1 counters;
+standalone operator/background or custom Promise adapter work is outside that
+request trace. Sampling does not add reads, change TTLs, bypass generation or
+credential fences, or start authorization.
+
+For example, query a ten-minute window for a neutral Worker `assistant` (replace
+the millisecond timestamps with the window you need):
+
+```sh
+cf --profile assistant o11y telemetry query \
+  --query-id 00000000-0000-4000-8000-000000000001 \
+  --view events --limit 100 \
+  --timeframe-from 1793700000000 --timeframe-to 1793700600000 \
+  --parameters-order-by-value count --parameters-order-by-order desc \
+  --parameters-calculations '[{"operator":"count","alias":"count"}]' \
+  --parameters-filters '[{"key":"$workers.scriptName","operation":"eq","type":"string","value":"assistant"}]'
+```
+
+Select `connecta.timing` messages in the returned events and inspect their
+structured operation totals. Use the profile belonging to your deployment.
+The example reads telemetry only; it changes no Worker settings.
+
+The example passes CLI dry-run validation; server acceptance has not been verified.
+Use `--dry-run` to validate the request locally without querying telemetry.