@zackbart/connecta 0.30.0 → 0.32.0

package/documentation/auth.md

@@ -6,15 +6,15 @@
 and package maintenance. This guide owns identity, grants, and downstream
 credential contracts; use [deployment setup](./deploying.md) for runnable steps.
 
-| Task                                                  | Sections                                                                                                                                                                      |
-| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Connect a machine or migrate an old client            | [Managed tokens](#managed-client-tokens-and-upgrading-from-v023), [static bearer migration](#migrating-static-bearer-clients)                                                 |
-| Configure caller visibility, trust, or auth ownership | [Principals and operators](#principals-visibility-and-operators), [pools](#pools), [shared and personal auth](#shared-and-personal-auth)                                      |
-| Set up human sign-in                                  | [Access on Workers](#cloudflare-access-on-workers), [Clerk tokens and sessions](#clerk-oauth-tokens-and-operator-sessions), [management](#human-authentication-management)    |
-| Enable credential or connection controls              | [Management permissions](#management-permissions), [start/restart/disconnect](#starting-restarting-and-disconnecting)                                                         |
-| Diagnose consent or token refresh                     | [State at rest](#downstream-oauth-state-at-rest), [callbacks](#consents-and-callbacks), [refresh failures](#refresh-failures), [safe errors](#what-a-servers-errors-may-say)  |
-| Configure a downstream OAuth client or HTTP handler   | [Client registration](#downstream-oauth-client-registration), [api() OAuth](#downstream-oauth-on-api), [request-local bearer tokens](#request-local-downstream-bearer-tokens) |
-| Review browser or downstream URL boundaries           | [Origins](#origins), [advertised URLs](#urls-a-downstream-advertises), [one server per grant](#one-server-per-grant)                                                          |
+| Task                                                                | Sections                                                                                                                                                                      |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Connect a machine or migrate an old client                          | [Managed tokens](#managed-client-tokens-and-upgrading-from-v023), [static bearer migration](#migrating-static-bearer-clients)                                                 |
+| Configure caller visibility, read-only endpoints, or auth ownership | [Principals and operators](#principals-visibility-and-operators), [pools](#pools), [shared and personal auth](#shared-and-personal-auth)                                      |
+| Set up human sign-in                                                | [Access on Workers](#cloudflare-access-on-workers), [Clerk tokens and sessions](#clerk-oauth-tokens-and-operator-sessions), [management](#human-authentication-management)    |
+| Enable credential or connection controls                            | [Management permissions](#management-permissions), [start/restart/disconnect](#starting-restarting-and-disconnecting)                                                         |
+| Diagnose consent or token refresh                                   | [State at rest](#downstream-oauth-state-at-rest), [callbacks](#consents-and-callbacks), [refresh failures](#refresh-failures), [safe errors](#what-a-servers-errors-may-say)  |
+| Configure a downstream OAuth client or HTTP handler                 | [Client registration](#downstream-oauth-client-registration), [api() OAuth](#downstream-oauth-on-api), [request-local bearer tokens](#request-local-downstream-bearer-tokens) |
+| Review browser or downstream URL boundaries                         | [Origins](#origins), [advertised URLs](#urls-a-downstream-advertises), [one server per grant](#one-server-per-grant)                                                          |
 
 [Credential recognition and admission](#credential-recognition-and-admission)
 defines refusal precedence.
@@ -90,6 +90,7 @@ createConnecta({
       principal.id === "your-operator-id",
   },
   connectors, executor,
+  readOnly: false, // required: true refuses every write call
 });
 ```
 
@@ -101,7 +102,7 @@ the identity namespaces and connector/pool grant callbacks too; storage
 compatibility translates no configuration and invents no grants. `access_token`
 actor ids, the `connecta:access-tokens:v1` activity namespace, friendly names,
 and stored principals carry over; a token without a principal stays unbound.
-Every request evaluates current identity, tool, and pool grants, and a token
+Every request evaluates current identity, tool, and endpoint grants, and a token
 never becomes an interactive operator. Names are labels, never permissions. A
 UI-issued token belongs to the issuing human's principal, and any explicitly
 permitted token manager can list, rename, or revoke deployment tokens. Machine tokens manage neither tokens nor connection credentials; operators
@@ -163,6 +164,10 @@ deployment's anonymous admission. Otherwise, or on `undefined`, the call fails
 `auth_required` before any request leaves. Arguments, headers, and programs
 never reach it; a deployment's own connectors still cannot read the caller.
 
+The deployment's top-level `grant` decides who may use plain `/mcp`; named
+pools use their own grants. These endpoint decisions receive the admitted
+identity below and never widen its connector access.
+
 `identity.connectorAccess` returns `"all"` (the default) or grants, for
 discovery and use alike: a connector id opens every tool on it, a
 `connector.tool` address that tool alone, and
@@ -206,6 +211,7 @@ createConnecta({
     },
   },
   connectors: [issues, campaigns, billing], executor,
+  readOnly: false, // required: true refuses every write call
 });
 ```
 
@@ -215,12 +221,12 @@ grant both connectors in full. Unknown or unprincipalled identities get `[]`.
 Use a stable authenticated principal or subject, never request headers or tool
 arguments. A token's stored principal is vouched for by inbound auth. Pools narrow their endpoint, not plain `/mcp`.
 
-| Catalog change                                           | Guarded exact grant                                                                                      | Unrestricted exact string grant                                     |
-| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| New name                                                 | Excluded until reviewed and added                                                                        | Excluded until reviewed and added                                   |
-| Removed or renamed name                                  | Unreachable; warned when the scoped view reads the catalog                                               | Same                                                                |
-| Stored write verdict after overrides and provider review | Removed from discovery and every invocation path, including `call_destructive_tool` and trusted programs | Still granted; `call_tool` refuses writes and write paths take over |
-| Schema change alone                                      | Does not revoke, unless it breaks a reviewed digest: then it is a write, as above                        | Same as above                                                       |
+| Catalog change                                           | Guarded exact grant                                                                                                     | Unrestricted exact string grant                                     |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| New name                                                 | Excluded until reviewed and added                                                                                       | Excluded until reviewed and added                                   |
+| Removed or renamed name                                  | Unreachable; warned when the scoped view reads the catalog                                                              | Same                                                                |
+| Stored write verdict after overrides and provider review | Removed from discovery and every invocation path, including `call_destructive_tool` and programs on a writable endpoint | Still granted; `call_tool` refuses writes and write paths take over |
+| Schema change alone                                      | Does not revoke, unless it breaks a reviewed digest: then it is a write, as above                                       | Same as above                                                       |
 
 The example assumes both exact tools were reviewed as read-only; names imply no safety.
 Review schemas, annotations, and downstream behavior
@@ -236,7 +242,7 @@ Failed remote loads are errors, not empty catalogs. A transient first-page tool
 listing failure may serve complete facts in the same auth partition for five
 minutes after expiry. Failed pagination, permission and auth failures do not
 use this fallback. The expired deadline cannot authorize auth recovery. Personal OAuth ownership and credential
-administration are separate from visibility; program writes follow the endpoint's trust tier and host approval. `test/identity-scope.test.ts` exercises these boundaries.
+administration are separate from visibility; writes follow the endpoint's `readOnly` setting and client approval. `test/identity-scope.test.ts` exercises these boundaries.
 
 ## Migrating static bearer clients
 
@@ -284,6 +290,8 @@ createConnecta({
   storage,
   accessTokens: accessTokens(storage),
   auth: clerkAuth({ publishableKey, secretKey }),
+  readOnly: false, // required; pools without their own readOnly inherit it
+  grant: ({ actor }) => actor.kind !== "access_token", // machines use their pools
   pools: {
     support: {
       tools: ["linear", "notion.search_pages", "notion.fetch_page"],
@@ -293,6 +301,11 @@ createConnecta({
       tools: ["calendar.create_event"],
       grant: ({ actor }) => actor.kind === "access_token" && actor.id === calendarTokenId,
     },
+    reporting: {
+      tools: ["linear", "notion"],
+      readOnly: true,
+      grant: ({ principal }) => analysts.has(principal?.id ?? ""),
+    },
   },
   identity: { connectorAccess },
   connectors, executor,
@@ -302,14 +315,59 @@ createConnecta({
 Without configured `auth`, an open deployment has one anonymous, non-interactive
 identity; grants like these return false and every pool path 404s.
 
-| Rule         | Contract                                                                                                                                                                                                                                                     |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Scope        | `/mcp/<pool>` intersects pool tools with the identity's `connectorAccess`, never widening it. Plain `/mcp` is unchanged; the resolver remains the security boundary.                                                                                         |
-| Grant        | Defaults to deny; only literal `true` admits. Other returns, throws, and undeclared names produce an identical 404 status, body, and headers, after auth. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content. |
-| Timing       | Declared names await grants, so timing is not hidden. Keep grants pure and fast and names unsecret; names grant no access. The operator log records the refusal reason.                                                                                      |
-| Construction | Malformed names, unknown options or connectors, empty pools, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load.                                                                                            |
-| Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                         |
-| Drift        | No wildcards; tool grants are exact names. Missing live tools are unreachable and warned once while in a bounded 1,024-entry FIFO.                                                                                                                           |
+The optional top-level `grant: (identity) => boolean | Promise<boolean>`
+controls plain `/mcp`. Omitted, it admits everyone who passes auth, including
+anonymous callers on an open deployment. Configured, only literal `true`
+admits; other returns and throws deny. A refusal has the same 404 status,
+body bytes, and headers as a refused or undeclared pool, after auth. The
+operator log records `default_grant_denied` or `default_grant_threw`, never
+the callback's error text. Invalid config values throw at construction.
+Named pools use only their own grants, so a caller refused at `/mcp` may
+still use a pool that grants it.
+
+Protected-resource metadata stays public at both default aliases,
+`/.well-known/oauth-protected-resource` and
+`/.well-known/oauth-protected-resource/mcp`, just as at named-pool aliases.
+Discovery does not authenticate callers or evaluate endpoint grants, so fresh
+OAuth clients can discover how to authenticate. The grant applies after auth
+to MCP requests and result/page handles. Handles remain bound
+to their originating endpoint; paging rechecks the current endpoint grant,
+identity, and connector access. A granting pool cannot read a `/mcp` handle,
+and `/mcp` cannot read that pool's handle.
+
+`describeConfig().hasGrant` and the operator UI report whether plain `/mcp`
+has a configured grant without exposing callback source. `describeConfig()`
+does not evaluate it. Operator catalog, config, activity, and connector auth
+routes require the same default endpoint grant after their own authentication.
+A refused caller gets a private JSON 404; the UI provides no per-pool view.
+The public HTML shell carries no catalog data.
+
+Each endpoint is writable or read-only. The deployment's `readOnly` sets the
+plain `/mcp` endpoint and is required: a deployment that omits it fails at
+construction and must choose `true` or `false`. A pool inherits it unless the
+pool sets its own `readOnly`, in either direction. A writable endpoint lets
+`call_destructive_tool` and programs write, and the MCP client decides what to
+approve. On a read-only endpoint, write tools are absent from `search_tools`
+results, `connecta.search`, and `connecta.describe`, and `call_tool`,
+`call_destructive_tool`, and program writes are refused with
+`read_only_endpoint` before validation or dispatch. Reads, including reads
+through `call_destructive_tool`, still run.
+Guides are documentation, not discovery: provider `SKILL.md` and usage guides,
+surfaced through `queryAnalysis.guideSummary`, `skills`, `connecta.skill`, and
+skill `resources/read`, are the same on every endpoint and may name tools a
+read-only endpoint refuses.
+Resource reads, grants, and `connectorAccess`, including guarded
+`requireReadOnly` grants, are the same on both. The removed `trust` option fails
+construction with a message naming `readOnly`.
+
+| Rule         | Contract                                                                                                                                                                                                                                                                |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Scope        | `/mcp/<pool>` intersects pool tools with the identity's `connectorAccess`, never widening it. Plain `/mcp` serves the identity's `connectorAccess` after its optional top-level `grant` admits it.                                                                      |
+| Grant        | Pool grants default to deny; only literal `true` admits. Other returns, throws, and undeclared names produce an identical 404 status, body, and headers, after auth. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content. |
+| Timing       | Declared names await grants, so timing is not hidden. Keep grants pure and fast and names unsecret; names grant no access. The operator log records the refusal reason.                                                                                                 |
+| Construction | Malformed names, unknown options or connectors, empty pools, a non-boolean `readOnly`, a retired `trust`, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load.                                                          |
+| Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                                    |
+| Drift        | No wildcards; tool grants are exact names. Missing live tools are unreachable and warned once while in a bounded 1,024-entry FIFO.                                                                                                                                      |
 
 ## Shared and personal auth
 
@@ -809,6 +867,7 @@ createConnecta({
     activityAccess: ({ id }) => id === "owner-id",
   },
   connectors, executor,
+  readOnly: false, // required: true refuses every write call
 });
 ```
 
@@ -821,7 +880,7 @@ Access trusts the identity validated at the Worker edge.
 
 ```ts
 import { cloudflareAccessAuth } from "@zackbart/connecta/auth/cloudflare-access";
-createConnecta({ auth: cloudflareAccessAuth(), connectors, executor });
+createConnecta({ auth: cloudflareAccessAuth(), connectors, executor, readOnly: false });
 ```
 
 The adapter trusts only `ctx.access`, which Cloudflare attaches after validating
@@ -1011,7 +1070,7 @@ fallbacks, including a failed listing followed by cached annotations, cannot
 authorize a re-run. Normal calls retain their existing stale-fallback behavior.
 Before an accepted retry restarts any call, it rechecks every entered read.
 A write classification, changed classification digest, or stale catalog returns
-`auth_replay_refused` with reconciliation guidance, including in trusted programs.
+`auth_replay_refused` with reconciliation guidance, including in programs on a writable endpoint.
 Pre-invocation credential-resolution eligibility is unchanged.
 Custom vaults may implement the host-only `requestStateKey` method; without it, the
 deployment retains the ordinary handoff. It must return a stable,

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
@@ -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,7 +480,7 @@ 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
+Resources are protocol reads on read-only and writable endpoints alike. 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
@@ -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.
@@ -882,17 +882,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 +901,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 +1003,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, grant },
   },
   classification: {
     posthog: { exec: "read" }, // only for a deployment with a read-only exec contract
@@ -1027,6 +1027,9 @@ createConnecta({
 });
 ```
 
+The removed `trust` option, on the deployment or a pool, fails construction
+with a message naming `readOnly` (`INV-11`).
+
 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 +1047,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 +1057,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 +1070,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
 
@@ -1225,8 +1234,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

@@ -64,7 +64,7 @@ through to `fetch`. The example owns those details and
 
 ## 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:
 
@@ -96,10 +96,15 @@ personal connection, token management, and activity access explicit.
 [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. Pool membership intersects
+the caller's grants; it never widens them. See [pools](./auth.md#pools) before
+changing `readOnly`.
 
 ## Verify and diagnose