@zackbart/connecta 0.31.0 → 0.33.0

package/documentation/code-mode.md

@@ -48,7 +48,7 @@ QuickJS subpath:
 import { createConnecta } from "@zackbart/connecta";
 import { quickJsExecutor } from "@zackbart/connecta/quickjs";
 
-createConnecta({ executor: quickJsExecutor() /* connectors, auth, storage… */ });
+createConnecta({ executor: quickJsExecutor(), readOnly: false /* connectors, auth, storage… */ });
 ```
 
 `quickJsExecutor()` runs each program in a disposable child process, with CPU,
@@ -61,7 +61,7 @@ On Workers the Worker Loader is the sandbox; Dynamic Workers require the Paid pl
 ```ts
 import { workerExecutor } from "@zackbart/connecta/worker";
 
-createConnecta({ executor: workerExecutor({ loader: env.LOADER }) });
+createConnecta({ executor: workerExecutor({ loader: env.LOADER }), readOnly: false /* … */ });
 ```
 
 The adapter uses only `loader` and an optional `timeout`. Its admission defaults
@@ -80,7 +80,7 @@ and cleanup at budget exhaustion, cancellation, and deadlines; the wrapper only
 
 ## What an executor must implement
 
-The Promise provider/result seam lives in `src/types.ts`. Custom implementations
+The Promise provider/result seam is declared in the installed `dist/types.d.ts`. Custom implementations
 also need the lifecycle wrapper above; structural compatibility alone is insufficient.
 
 ```ts
@@ -283,7 +283,10 @@ signature is byte-identical to the one `search_tools` returns.
 integration is ambiguous. `safety: "readOnly"` selects stored read verdicts;
 `"approvalRequired"` selects stored write verdicts; omitted or `"all"` selects
 both. Search and describe rows carry `classification`. These filters grant no
-authority and change no pool trust or call admission decision.
+authority and change no call admission decision. On a read-only endpoint,
+search and describe omit write tools (`W12`): a write is absent from every
+filter, and describing one is `unknown_tool`. `connecta.skill` guides are not
+filtered and may name such a write; calling it is still refused.
 
 **S2.** A requested object schema carries `inputKeys`, `requiredInputKeys`
 (declared properties only), and `outputKeys`: the names the rendered schema
@@ -394,10 +397,10 @@ and a 32 KiB bridge ceiling. `page` is zero-based and mutually exclusive with
 are at least four bytes wide and align both edges to UTF-8 boundaries.
 Follow `nextOffset`, reassemble inside the program, and return a reduced value.
 Before returning a page, the host rechecks current authentication, connector/tool
-grants, pool membership, and endpoint trust against both the original and current
-tool classification. A read-only endpoint cannot page a write result, so a
-direct write there returns an inline truncation notice without stashing the
-result or advertising a paging action. Binding
+grants, pool membership, and whether the endpoint is read-only against both the
+original and current tool classification. A read-only endpoint cannot page a
+write result; it never runs a write, so any write result it is asked for came
+from a writable endpoint. Binding
 mismatches, revoked access, and old entries without bindings are `not_found`, as
 are unknown or expired ids; a storage failure is `unavailable`. IDs are random UUIDs.
 The `get_result` meta-tool is removed.
@@ -477,10 +480,10 @@ Connecta passes an admitted decoded URI as an opaque MCP `resources/read`
 argument to the configured endpoint. It never fetches that
 URI or creates a connector from it.
 
-Resources are protocol reads in both `read-only` and `trusted` pools. A read
-requires a grant to the whole connector through the endpoint/pool and identity
-intersection. Exact-tool grants, including guarded grants, authorize no
-resources. An absent, hidden, tool-restricted or resource-incapable connector
+Resources are protocol reads on read-only and writable endpoints alike. A read
+requires the whole connector on the endpoint: plain `/mcp`, or a pool whose
+`tools` list the connector id. A pool listing only exact `connector.tool`
+addresses authorizes no resources. An absent, hidden, tool-restricted or resource-incapable connector
 fails with `unknown_address`. The URI and extra arguments cannot select a
 different credential owner or downstream subject. Personal credentials come
 from the admitted principal, just as they do for tool calls.
@@ -553,27 +556,27 @@ URL-elicitation hosts retain their existing flow.
 may do. A provider maps each downstream failure to the code that tells the
 caller what to do next, and never invents a cause it was not told.
 
-| Code                                 | Raised when                                                                                                                                                                                           | `retryable`   |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
-| `unknown_address`                    | no visible connector owns the tool address or grants the resource reader                                                                                                                              | false         |
-| `unknown_tool`                       | the connector has no such tool                                                                                                                                                                        | false         |
-| `destructive_tool_requires_approval` | a program in a read-only pool attempted a write (`E4`)                                                                                                                                                | false         |
-| `auth_required`                      | the credential is missing, expired, or rejected                                                                                                                                                       | false         |
-| `invalid_args`                       | arguments or discovery bounds were rejected                                                                                                                                                           | false         |
-| `not_found`                          | the downstream answered and the resource is not there — the one code that says skip this id rather than stop, raised only where the provider tells absence from a permission gap                      | false         |
-| `conflict`                           | the write named a base version someone else already moved past; nothing changed. `details.current` says where things stand (at most 20 whole-number entries) — re-read, reapply, retry with that base | false         |
-| `input_required_unsupported`         | a downstream asked for input; use `nextAction` for the equivalent direct call                                                                                                                         | false         |
-| `rate_limited`                       | the downstream reported a rate limit                                                                                                                                                                  | true          |
-| `unavailable`                        | the downstream is down or unreachable; optional sanitized `details.host` and `details.code` describe the transport failure without paths, queries, credentials, or provider prose                     | true          |
-| `timeout`                            | a call or sandbox deadline expired; details name operation, stage, elapsedMs, and deadlineMs                                                                                                          | per operation |
-| `program_error`                      | guest JavaScript failed; `details.name`, `line`, and a fixed repair hint describe it                                                                                                                  | false         |
-| `cancelled`                          | the run ended while this call was in flight (`E5`)                                                                                                                                                    | false         |
-| `connector_call_failed`              | anything else the connector threw                                                                                                                                                                     | per message   |
-| `catalog_lookup_failed`              | the connector's catalog could not be loaded                                                                                                                                                           | per cause     |
-| `result_processing_failed`           | the result could not be prepared                                                                                                                                                                      | per message   |
-| `result_too_large`                   | a discovery response exceeded its byte bound                                                                                                                                                          | false         |
-| `budget_exceeded`                    | the run exhausted a host-call, write, or emitted-output budget                                                                                                                                        | false         |
-| `write_outcome_unknown`              | a trusted-pool write was sent and no answer came back; it is never sent again (`W9`)                                                                                                                  | false         |
+| Code                         | Raised when                                                                                                                                                                                           | `retryable`   |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `unknown_address`            | no visible connector owns the tool address or grants the resource reader                                                                                                                              | false         |
+| `unknown_tool`               | the connector has no such tool                                                                                                                                                                        | false         |
+| `read_only_endpoint`         | a program on a read-only endpoint attempted a write (`E4`)                                                                                                                                            | false         |
+| `auth_required`              | the credential is missing, expired, or rejected                                                                                                                                                       | false         |
+| `invalid_args`               | arguments or discovery bounds were rejected                                                                                                                                                           | false         |
+| `not_found`                  | the downstream answered and the resource is not there — the one code that says skip this id rather than stop, raised only where the provider tells absence from a permission gap                      | false         |
+| `conflict`                   | the write named a base version someone else already moved past; nothing changed. `details.current` says where things stand (at most 20 whole-number entries) — re-read, reapply, retry with that base | false         |
+| `input_required_unsupported` | a downstream asked for input; use `nextAction` for the equivalent direct call                                                                                                                         | false         |
+| `rate_limited`               | the downstream reported a rate limit                                                                                                                                                                  | true          |
+| `unavailable`                | the downstream is down or unreachable; optional sanitized `details.host` and `details.code` describe the transport failure without paths, queries, credentials, or provider prose                     | true          |
+| `timeout`                    | a call or sandbox deadline expired; details name operation, stage, elapsedMs, and deadlineMs                                                                                                          | per operation |
+| `program_error`              | guest JavaScript failed; `details.name`, `line`, and a fixed repair hint describe it                                                                                                                  | false         |
+| `cancelled`                  | the run ended while this call was in flight (`E5`)                                                                                                                                                    | false         |
+| `connector_call_failed`      | anything else the connector threw                                                                                                                                                                     | per message   |
+| `catalog_lookup_failed`      | the connector's catalog could not be loaded                                                                                                                                                           | per cause     |
+| `result_processing_failed`   | the result could not be prepared                                                                                                                                                                      | per message   |
+| `result_too_large`           | a discovery response exceeded its byte bound                                                                                                                                                          | false         |
+| `budget_exceeded`            | the run exhausted a host-call, write, or emitted-output budget                                                                                                                                        | false         |
+| `write_outcome_unknown`      | a program write was sent and no answer came back; it is never sent again (`W9`)                                                                                                                       | false         |
 
 **E3.** `auth_required` carries the same recovery envelope as `call_tool`:
 `connector`, `operation`, `recovery` (`oauth`, `operator_config`, or
@@ -581,16 +584,13 @@ caller what to do next, and never invents a cause it was not told.
 sentence. A program cannot recover credentials — only an operator can — so stop
 and let the failure reach the model.
 
-**E4.** A tool classified as a write never runs in a
-program unless the pool is trusted (`W12`). It is refused with
-`destructive_tool_requires_approval` before validation and before anything is
-sent, `nextAction` carrying its canonical address to `call_destructive_tool`
-and a schema-filtered snapshot within the 512-byte echo budget. `argsRedacted`
-marks partial or withheld arguments; use the original arguments if this flag is
-set or `args` is absent. Snapshots are never clipped. The host's prompt on that
-call is the approval, and the only one: generated code can neither mint the
-capability nor approve its own write, and the model's short `reason` grants no
-authority and never goes downstream.
+**E4.** A tool classified as a write never runs on a read-only endpoint
+(`W12`). A program's call is refused with `read_only_endpoint` before
+validation and before anything is sent. The refusal carries no `nextAction` and
+echoes no arguments: no route on that endpoint writes, so the program reports
+it rather than retrying. Generated code can neither mint the capability nor
+change the endpoint; on a writable endpoint, approval of the program as a write
+belongs to the client.
 
 **E5.** Failures of the _execution_, not of a call, never appear inside the
 guest: admission rejection (`executor_overloaded`, retryable, with
@@ -631,7 +631,7 @@ Program diagnostic fields are bounded before transport, including escaped text;
 a large custom error name cannot turn a failure into a truncated success.
 
 **E7.** `retryable` for `unknown_address`, `unknown_tool`, and
-`destructive_tool_requires_approval` is pinned false, never inferred from an
+`read_only_endpoint` 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" } }`
 — scoped discovery keyed to the surface the caller has, since a program cannot
@@ -686,7 +686,7 @@ Caught call failures retain that connector visibility when catalog loading or
 tool resolution fails. Recovery messages listing configured connectors or
 local guides retain visibility of those contributors too.
 Each page rechecks current auth,
-grants, pool membership, and trust. Reading a stash inside a program carries
+grants, pool membership, and the endpoint's `readOnly`. Reading a stash inside a program carries
 its dependencies forward to any new return stash. The page cap is the smallest
 of the deployment cap and contributing connectors' effective `maxResultBytes`.
 Read-only endpoints cannot page write results. A UUID is a handle, never a grant.
@@ -737,9 +737,6 @@ and nonzero pad bits are rejected before collection. Size budgets still apply.
 MCP-native output a return value cannot carry: base64 is not projectable, so a
 block that fits the inline call limit (`S5`, `L6`) can use the separate
 emission transport budget instead of the `R2` return guard.
-The earlier alternatives are in [decision history](https://github.com/zackbart/connecta/blob/main/decisions/0001-ethos-verdict-table.md)
-([#267](https://github.com/zackbart/connecta/issues/267),
-[#270](https://github.com/zackbart/connecta/issues/270)).
 
 **M1.** `connecta.emit(result)` accepts a rich result from this program's
 `connecta.call` and forwards its original native content blocks, including
@@ -861,7 +858,7 @@ Programs and direct calls use the same invocation deadline and stages. A call's
 `timeoutMs` wins, then `calls.defaultTimeoutMs`, then `execute.hostCallTimeoutMs`
 (default 15,000). A guest may request a longer individual call, but the sandbox
 and request ceilings still bound the whole run. Timeout details are agent-facing;
-INV-6 operator records retain only checked classifications and numeric facts.
+operator records retain only checked classifications and numeric facts.
 A dispatched write timeout becomes `write_outcome_unknown` and retains its
 deadline details even when the program catches the failure. The final program
 error includes the first timeout in `details`; multiple write timeouts also
@@ -882,17 +879,17 @@ deadline past the ceiling means raising the ceiling too.
 **L4.** Per-execution bounds that are contract, identical in both executors
 because connecta enforces them above the sandbox:
 
-| Bound                                                                         | Value                                                                                                        |
-| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| Host calls per execution, shared by `search`, `describe`, `call`, and `read`  | 20 by default, `execute.maxHostCalls`                                                                        |
-| Trusted-pool writes per run, on top of the host calls they also spend (`W10`) | 10 by default, `execute.maxWrites`                                                                           |
-| Deadline per host call                                                        | 15 s, `execute.hostCallTimeoutMs`; one deadline covers catalog resolution, admission, and the connector call |
-| Discovery page                                                                | ≤ 100 tools, ≤ 256,000 serialized bytes                                                                      |
-| `describe` addresses                                                          | ≤ 100                                                                                                        |
-| `describe` nearby suggestions                                                 | ≤ 3 canonical addresses per failed entry                                                                     |
-| Caller text echoed by `describe` recovery                                     | ≤ 512 UTF-8 bytes per field, plus `…`                                                                        |
-| Result                                                                        | 24,000 serialized characters                                                                                 |
-| Logs presented to the model                                                   | 4,000 characters                                                                                             |
+| Bound                                                                                   | Value                                                                                                        |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Host calls per execution, shared by `search`, `describe`, `call`, and `read`            | 20 by default, `execute.maxHostCalls`                                                                        |
+| Writes per run on a writable endpoint, on top of the host calls they also spend (`W10`) | 10 by default, `execute.maxWrites`                                                                           |
+| Deadline per host call                                                                  | 15 s, `execute.hostCallTimeoutMs`; one deadline covers catalog resolution, admission, and the connector call |
+| Discovery page                                                                          | ≤ 100 tools, ≤ 256,000 serialized bytes                                                                      |
+| `describe` addresses                                                                    | ≤ 100                                                                                                        |
+| `describe` nearby suggestions                                                           | ≤ 3 canonical addresses per failed entry                                                                     |
+| Caller text echoed by `describe` recovery                                               | ≤ 512 UTF-8 bytes per field, plus `…`                                                                        |
+| Result                                                                                  | 24,000 serialized characters                                                                                 |
+| Logs presented to the model                                                             | 4,000 characters                                                                                             |
 
 Every `call`, `read`, `search`, and `describe` spends one host call on entry, before
 resolution, validation, or dispatch. Catching a local refusal refunds nothing.
@@ -901,7 +898,7 @@ The first call beyond the budget ends the host run with one non-retryable
 `try/catch` cannot swallow it. Later host access, including `emit`, stops; pending
 replies are withheld. The refusal reaches no connector, returns no partial result,
 and discards accepted emits (`M4`). Calls still resolving or awaiting admission
-are cancelled, including trusted-pool writes past their gate. Dispatched trusted-pool writes
+are cancelled, including writes past their gate. Dispatched writes
 drain under `W9`; unknown outcomes retain precedence. The lease then releases:
 QuickJS terminates its child, and the Worker adapter disposes RPC and loader
 handles independently of the guest deadline. Workers guest computation may
@@ -1003,22 +1000,22 @@ payload-free _by construction_ means the event has nowhere to put a payload.
 distinctive output is the program source — exactly what a payload-free history
 must never keep.
 
-**V5.** A trusted-pool write a program issues after it has already returned is not
+**V5.** A write a program issues after it has already returned is not
 sent and records nothing: it was never an attempt (`W9`).
 
 ## Writes
 
-Pool trust belongs to deployment code. The default `/mcp` endpoint uses
-`trust: "read-only"`; each named pool has its own `trust`, also defaulting to
-`"read-only"`. A trusted default endpoint does not make named pools trusted.
-The default preserves refusal of ordinary program writes. A deployment must opt into program writes explicitly.
+Whether an endpoint writes belongs to deployment code. Every deployment sets
+`readOnly` for `/mcp` explicitly; construction fails without it. Each named pool inherits
+the deployment's `readOnly` unless it sets its own, in either direction. The
+client owns approval; Connecta answers one question per endpoint: can it write.
 
 ```ts
 createConnecta({
   connectors, executor,
-  trust: "read-only",
+  readOnly: false, // required: false writes, true refuses every write call
   pools: {
-    automation: { tools: ["posthog"], trust: "trusted", grant },
+    reporting: { tools: ["posthog"], readOnly: true, members: analysts },
   },
   classification: {
     posthog: { exec: "read" }, // only for a deployment with a read-only exec contract
@@ -1027,6 +1024,9 @@ createConnecta({
 });
 ```
 
+The removed `trust` option, on the deployment or a pool, fails construction
+with a message naming `readOnly`.
+
 The registry computes one `classifyTool` verdict on each request-scoped
 published catalog entry. It caches and persists only raw downstream facts.
 Every caller consumes that stored verdict. Config cannot classify an individual
@@ -1044,7 +1044,7 @@ fail construction; unknown remote tool keys fail publication of the whole
 catalog. Overrides are exact tool names, including names containing dots.
 They are never inferred from descriptions or arguments.
 
-**W9.** Programs in trusted pools may write. A dispatched write is awaited even
+**W9.** Programs on a writable endpoint may write. A dispatched write is awaited even
 if the program does not await it, bounded by its host-call deadline. A write
 that reaches accounting after the program settles is not sent. An unanswered
 write makes the run fail `write_outcome_unknown` with
@@ -1054,7 +1054,7 @@ write is automatically retried, including an ambiguous timeout. A downstream
 refusal or a tool's `isError` can establish failure; a timeout or an unanswered
 transport failure leaves the outcome unknown.
 
-**W10.** `execute.maxWrites`, default 10, bounds writes in trusted programs in
+**W10.** `execute.maxWrites`, default 10, bounds a program's writes in
 addition to the host-call budget. It is checked after argument validation and
 before admission, so an over-budget write spends no permit.
 
@@ -1067,14 +1067,20 @@ reconciliation. Any new call must use the original arguments when its echo is
 partial or absent. A returned `writes` count cannot make a run safe to repeat.
 See [argument echo rules](./meta-tools.md#echo-budgets) for supported schema shapes.
 
-**W12.** `trusted` endpoints annotate `execute_code` as a write and permit
-program writes. `read-only` endpoints annotate it as read-only and refuse
-program writes before validation, with `call_destructive_tool` as the recovery.
-`call_tool` accepts only reads in either tier; `call_destructive_tool` may send
-writes in either tier. Approval belongs to the host. Trust grants no tool or
-connector access and cannot be set by guest code, request arguments, or a
-downstream catalog. `execute.approval`, `Connector.approval`, and per-tool
-approval exemptions are removed. `W1`–`W8` and `W11` remain retired.
+**W12.** Writable endpoints annotate `execute_code` as a write
+(`readOnlyHint: false, destructiveHint: true`) and permit program writes and
+`call_destructive_tool`; `call_tool` still accepts only reads and refuses a write
+with `destructive_tool_requires_approval`. Read-only endpoints annotate
+`execute_code` as read-only (`readOnlyHint: true, destructiveHint: false`),
+omit write tools from `search_tools`, `connecta.search`, and
+`connecta.describe`, and refuse every write call through `call_tool`,
+`call_destructive_tool`, and programs with `read_only_endpoint` before
+validation or dispatch. Guides and skills are documentation and may still name
+those tools. `tools/list` is the same six tools on both. Approval belongs to the client.
+`readOnly` grants no tool or connector access and cannot be set by guest code,
+request arguments, or a downstream catalog. `execute.approval`,
+`Connector.approval`, per-tool approval exemptions, and pool `trust` are
+removed. `W1`–`W8` and `W11` remain retired.
 
 ## Executor exceptions
 
@@ -1185,7 +1191,13 @@ brand check and reads only own string data descriptors for diagnostics; guest
 accessors, serialization hooks, and Proxy traps do not run. Other thrown objects
 receive a fixed description.
 
-## Verification
+## Contributor reference
+
+### Verification
+
+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)).
 
 `test/guest-contract-cases.ts` runs on QuickJS in `test/guest-api-contract-quickjs.node.test.ts`
 and on the Worker adapter with a real Miniflare Loader in `test/guest-api-contract.test.ts`.
@@ -1225,8 +1237,8 @@ rejection, and branded adapter acceptance across module copies.
 | `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue)                                                                                                                                                                                                                                                                                                                                                                                    |
 | `L6`, `X10`            | `test/guest-api-contract-quickjs.node.test.ts` and `test/guest-api-contract.test.ts` (whole oversized reads and one-write pageable handles), `test/sqlite-storage.node.test.ts` and `test/d1-storage.node.test.ts` (shared stash transfers), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.node.test.ts` (outer reply serialization failure settles the call)                                                        |
 | `V1`–`V4`              | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, the identity clamp, the one-attempt floor), `test/operator-view.test.ts`, `test/sql-storage-contract.ts`, run by `test/d1-storage.node.test.ts` and `test/sqlite-storage.node.test.ts` (historical pause and approval rows still render and round-trip)                              |
-| `V5`, `W9`             | `test/program-writes.test.ts` (an unawaited trusted-pool write finished and recorded, its unknown outcome reported, counts on a failed program, the classification table), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                                |
-| `W10`, `W12`           | `test/program-writes.test.ts` (a trusted-pool write runs and every other write keeps `E4`, the write budget, pool trust and override precedence, `call_tool` still refusing, search and describe verdicts, construction refusals), `test/operator-ui-model.test.ts`, `test/browser/operator-ui.spec.ts` (the badge)                                                                                                                                                                                                             |
+| `V5`, `W9`             | `test/program-writes.test.ts` (an unawaited program write finished and recorded, its unknown outcome reported, counts on a failed program, the classification table), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                                     |
+| `W10`, `W12`           | `test/program-writes.test.ts` (a writable endpoint's program write runs, a read-only endpoint omits writes from search and describe and refuses every write call on every path, including a write its guide names, a required deployment `readOnly`, the write budget, `readOnly` inheritance and overrides, `call_tool` still refusing, search and describe verdicts, construction refusals including retired `trust`), `test/operator-ui-model.test.ts`, `test/browser/operator-ui.spec.ts` (the badge)                       |
 | `M1`                   | `test/guest-api-contract.test.ts` (invalid emits throw catchably, accept nothing), `test/execute-emit.test.ts` (rejected shapes, bounded native snapshots, paging before metadata traversal, and cyclic presentation refusal)                                                                                                                                                                                                                                                                                                   |
 | `M2`, `M3`             | `test/guest-api-contract.test.ts` (delivery order, truncated return plus delivered blocks), `test/execute-emit.test.ts` (envelope, `structuredContent`, byte-for-byte no-emit path)                                                                                                                                                                                                                                                                                                                                             |
 | `M4`                   | `test/guest-api-contract.test.ts` (discard is visible), `test/execute-emit.test.ts` (structured and plain paths), `test/quickjs-executor.node.test.ts` (mid-run shutdown)                                                                                                                                                                                                                                                                                                                                                       |

package/documentation/deploying.md

@@ -27,20 +27,25 @@ path and pins the generated project's Connecta dependency to the CLI version:
 npx @zackbart/connecta init my-connecta
 cd my-connecta
 npm install
-npm run --silent provision-token -- "local-machine"
+npm run --silent rotate-token -- local-machine
 # Save the returned cta_ token privately. It is shown only once.
 npm start
 ```
 
-The client connects to `http://localhost:8787/mcp` with
-`Authorization: Bearer <returned-cta-token>`. The generated project always
-installs `accessTokens(storage)`. An empty database admits no MCP caller even
-though `/health` works. `CONNECTA_TOKEN` is only a client/doctor variable;
+The agent connects to its pool's agent endpoint,
+`http://localhost:8787/agent/local-machine`, with
+`Authorization: Bearer <returned-cta-token>`. People use `/mcp` and
+`/mcp/<pool>`, which refuse `cta_` tokens. Machine clients are the agents
+declared in `agents` in `src/connecta.config.ts`; the generated project declares
+`local-machine` and always installs `accessTokens(storage)`. An agent with no
+issued token admits no MCP caller even though `/health` works. Rotating with the
+same command replaces the token immediately. `CONNECTA_TOKEN` is only a client/doctor variable;
 it never configures server authentication. The local commands read the process
 environment and do not load `.env`; Docker Compose does.
 
-Edit `src/connecta.config.ts` for connectors, public URL, auth, identity rules,
-and optional modules. `src/index.ts` only constructs and starts the deployment.
+Edit `src/connecta.config.ts` for connectors, public URL, auth, maintainers,
+agents, pools, and optional modules. Lay out each agent's pools by
+[Organizing an agent's pools](./auth.md#organizing-an-agents-pools). `src/index.ts` only constructs and starts the deployment.
 Follow the [template README](../templates/node/README.md) for storage paths,
 backups, Docker provisioning, secrets, and optional modules. Run the deployment's
 `npm run typecheck` after configuration changes.
@@ -56,15 +61,77 @@ must be installed for the Worker executor.
 
 Attach Cloudflare Access to the Worker destination. Interactive MCP clients
 need Managed OAuth, Dynamic Client Registration, and the documented redirect
-allowlist. Machines need Access service headers at the edge plus a stored
-`cta_` bearer inside Connecta; service identity alone is refused. Keep
+allowlist. Machines are declared agents: they use `/agent/<pool>` with the
+agent's `cta_` bearer as their only credential, once the
+[agent bypass application](#agent-endpoints-behind-cloudflare-access) exists;
+Access service identity alone is refused. Keep
 `enable_request_signal`, construct Connecta once per isolate, and pass `ctx`
 through to `fetch`. The example owns those details and
 [the machine-token procedure](../examples/worker/README.md#machine-tokens).
 
+## Agent endpoints behind Cloudflare Access
+
+Agents use `/agent/<pool>`, which connecta authenticates with the `cta_` token
+alone and which ignores Access context entirely
+([agent endpoints](./auth.md#agent-endpoints)). Behind Access, the edge must
+let those requests through without an Access login or service token. The P0
+probe ([observations](./architecture.md#production-access-bypass-for-agent-endpoints))
+verified this shape on 2026-10-15:
+
+1. Keep the Worker-level application, whose destination is
+   `{ "type": "worker", "worker_id": "<the Worker script tag>" }`, exactly as
+   [Cloudflare Access on Workers](./auth.md#cloudflare-access-on-workers)
+   describes. It still protects every other path and supplies `ctx.access` to
+   human routes.
+2. For each hostname agents use (the `workers.dev` hostname, each Custom
+   Domain, each route host), add one more **self-hosted** Access application.
+   In the dashboard, set the domain to that hostname and the path to
+   `agent/*`. Give it a single policy whose action is **Bypass** and whose
+   include rule is **Everyone**. Through the API:
+
+   ```json
+   {
+     "type": "self_hosted",
+     "name": "connecta agents",
+     "destinations": [{ "type": "public", "uri": "connecta.example.com/agent/*" }],
+     "policies": [{ "name": "agents bypass", "decision": "bypass", "include": [{ "everyone": {} }] }]
+   }
+   ```
+
+   The more specific hostname-and-path application takes precedence over the
+   Worker-level one on matching paths only. Do not use a Worker destination
+   for it: a Worker destination belongs to one application, and a second one
+   is refused with 409 `destination belongs to another application`. For the
+   same reason a second hostname without Access is not an alternative.
+
+3. Point each agent at `https://<host>/agent/<pool>` with
+   `Authorization: Bearer cta_…` and drop its `CF-Access-Client-Id` and
+   `CF-Access-Client-Secret` headers. The pool must list `"agent:<name>"`.
+4. Verify after the change has settled. Access changes took 15–19 seconds to
+   settle in the probe, and while they propagate the edge can answer with
+   transient 500 (`error code: 1104`) or 404 (`error code: 1042` or `1043`)
+   responses, and in one round a 403 on a bypassed path after more than 30
+   seconds. Do not rely on a fixed wait: repeat these checks until they agree
+   for several consecutive rounds. Without credentials, `/agent/<pool>`
+   reaches connecta (its 401 carries `WWW-Authenticate: Bearer`, not Access's
+   403 page), while `/mcp` and `/` still get Access's refusal. Then run
+   `connecta doctor --pool <pool>` with the agent's token.
+
+The bypass makes `/agent/*` reachable from the internet without Access.
+Connecta answers there only an issued token of an agent listed in the pool,
+and gives every other spelling of the agent namespace a 404 before auth,
+because Access matches `/agent/*` after resolving dot segments, folding case,
+decoding unreserved escapes, and collapsing a leading `//`, while the Worker
+sees the raw path. Two cases were not tested: a human's `CF_Authorization`
+cookie on a bypassed path, whose `ctx.access` identity is unknown (connecta
+never reads it at `/agent/*`), and Custom Domains, which use the same
+documented hostname-and-path form but were not observed; only `workers.dev`
+was probed. Pinning the Worker-level application's AUD on human routes is
+recommended hardening that connecta does not yet do.
+
 ## Compose capabilities and access
 
-Both configurations use `defineConfig((env) => …)` and a required executor.
+Both configurations use `defineConfig((env) => …)`, a required executor, and a required `readOnly` choice.
 [Integrating services](./integrating.md) explains the `connectors` array.
 Configuration selects optional factories through explicit slots:
 
@@ -90,51 +157,86 @@ outside the database and source control, and preserve it across upgrades.
 existing-record migration.
 
 One deployment serves one tenant and may admit several people. Node uses Clerk
-for human auth; Access is Workers-only. Keep credential administration,
-personal connection, token management, and activity access explicit.
-[Auth](./auth.md#principals-visibility-and-operators) owns identity and grants;
+for human auth; Access is Workers-only. With inbound auth, `maintainers` is
+required: only they reach plain `/mcp` and the operator UI. Everyone else
+reaches a pool that lists them in `members`: people at `/mcp/<pool>`, agents
+at `/agent/<pool>`. Maintainers alone administer shared credentials, manage
+agent tokens, and read activity; members connect their own accounts on
+personal connectors in their pools.
+[Auth](./auth.md#principals-visibility-and-operators) owns maintainers and members;
 [Clerk setup](./auth.md#clerk-oauth-tokens-and-operator-sessions) owns resource-bound
 tokens and `aud_claim_enabled`. A person's operator session is not an MCP token.
 
-Root and named pools default to `read-only`. A `trusted` pool allows writes
-inside programs and marks `execute_code` as a write. Host approval remains the
-host's decision. Pool membership intersects the caller's grants; it never
-widens them. See [pools](./auth.md#pools) before changing trust.
+Every deployment must set `readOnly` in its configuration; startup fails without
+it, and the template and Worker example set `readOnly: false`. Each named pool
+inherits that value unless it sets its own. A writable endpoint (`false`) allows
+writes through `call_destructive_tool` and programs and marks `execute_code` as
+a write; the client decides what to approve. A read-only endpoint (`true`) omits
+write tools from search and describe and refuses every write call; provider
+guides may still name those tools. A pool serves exactly its `tools` to its
+`members`. See [pools](./auth.md#pools) before changing `readOnly`.
 
 ## Verify and diagnose
 
-With the deployment running, replace the placeholder with its saved client
-token and run doctor:
+With the deployment running, replace the placeholder with its saved agent
+token and run doctor against a pool that lists the agent:
+
+```sh
+CONNECTA_TOKEN='<stored-cta-token>' npx connecta doctor --url http://localhost:8787 --pool local-machine
+```
+
+Doctor checks health, the required executor, and the current six-tool set. A
+`cta_` token is checked at `/agent/<pool>` and needs `--pool`.
+For a Worker protected by Access, `/health` still needs edge admission even
+though `/agent/*` bypasses Access. Use an Access service token admitted by the
+Worker-level policy for that check, alongside the agent token:
 
 ```sh
-CONNECTA_TOKEN='<stored-cta-token>' npx connecta doctor --url http://localhost:8787
+CF_ACCESS_CLIENT_ID='<access-service-id>' CF_ACCESS_CLIENT_SECRET='<access-service-secret>' CONNECTA_TOKEN='<stored-cta-token>' npx connecta doctor --url https://connecta.example.com --pool assistant
 ```
 
-Doctor checks health, the required executor, and the current six-tool set.
-For a Worker protected by Access, follow the example's doctor credentials
-and service-header setup. If the operator UI is enabled, authenticated
+The service headers admit the health probe at the edge; only the `cta_` token
+authenticates the agent endpoint inside Connecta. If the operator UI is enabled, maintainer-authenticated
 `connecta doctor --config --url <public-url>` prints the caller-scoped
 configuration snapshot as JSON. It runs no diagnostic program and prints no
 raw HTTP failure body. [Operator UI](./operator-ui.md) describes the returned
-configuration, live facts, and permission rules.
+configuration, live facts, and permission rules. The config route is a human
+endpoint: an agent token cannot authenticate it.
 
 Health success alone does not prove a client can authenticate or reach an
 integration. Check client connection and a bounded read through a chosen
 connector; resolve credentials using [authorization recovery](./meta-tools.md#authorization-recovery).
 
+Use the failed check to choose the next step:
+
+| Symptom                             | Action                                                                                                                                           |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Connection refused or timeout       | Check the public URL, listening process/port, proxy, and Worker deployment.                                                                      |
+| `/health` fails behind Access       | Check the Worker-level Access policy and the two service headers above. Do not broaden the agent bypass.                                         |
+| Executor check fails                | Retain `quickJsExecutor()` and its peer on Node, or `workerExecutor({ loader })`, the codemode peer, and `LOADER` on Workers.                    |
+| MCP 401                             | Check the saved token, declared agent, and slot state; rotated/revoked tokens refuse. Use `/agent/<pool>` with `--pool`.                         |
+| MCP 404                             | Check the pool name and `members: ["agent:assistant"]`; an existing but inaccessible pool is deliberately indistinguishable from a missing one.  |
+| Doctor passes but a connector fails | Discover its tools in that pool, check credential status/account ownership, and perform a bounded read. Doctor does not prove downstream access. |
+
+After a fix, repeat doctor with the same client credentials and pool. Never
+paste a token or raw downstream failure body into a committed diagnostic log.
+
 ## Upgrade an existing deployment
 
 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.
 
-- [Managed tokens from v0.23](./auth.md#managed-client-tokens-and-upgrading-from-v023) keep their secrets when storage, namespaces, and grants are retained. Replace the old boolean config with `accessTokens(storage)`; machine tokens gain no operator authority.
+- [Migration to 0.33](./migration-0.33.md) maps every removed access option to `maintainers`, pool `members`, and `agents`, moves agents to `/agent/<pool>`, and covers pool owners, token revisions, operator contract v2 with its operator route changes, and the pre-auth listen fix.
+- [Tokens issued before agents](./auth.md#agent-tokens-and-upgrading-from-earlier-tokens) stop admitting until each machine's token is bound once to a declared agent with `npm run adopt-token -- <token-id> <agent>` (Node) or `AccessTokenManager.adopt`, which keeps its secret. Human-bound tokens stay refused; issue those agents new tokens. Pool members name `"agent:<name>"` instead of matching token record ids.
 - [Node storage from 0.28](../templates/node/README.md#storage) uses `connecta migrate-state` to copy the JSON state into SQLite. Activity JSONL is not imported.
 - [Worker storage from 0.28](../examples/worker/README.md#upgrading-from-028) copies KV into D1 with a one-shot migration.
 - [Notion, Vercel, and Cloudflare for 0.29](./provider-migration-0.29.md) change defaults and retained API tool names.
 - [Executor wiring](./code-mode.md#deploy-time-capability) requires branded shipped executors or a self-managed custom executor.
 
-## Implementation and evidence
+## Contributor reference
+
+### Implementation and evidence
 
 Check the [CLI](https://github.com/zackbart/connecta/blob/main/bin/connecta.mjs),
 [Node configuration](../templates/node/src/connecta.config.ts), and