@zackbart/connecta 0.31.0 → 0.32.0

package/documentation/architecture.md

@@ -85,20 +85,20 @@ table, security headers. Route _order_ is the contract — several routes would
 behave differently if they were reachable in another order — so read the table
 top to bottom.
 
-| Order | Route                                                     | Notes                                                                                                                                                                                                                                                              |
-| ----- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 0     | MCP Origin check                                          | A disallowed `Origin` on `/mcp*` is a fixed 403 before redirects, admission, auth, or preflight — costing no permit and no auth lookup. Originless requests are admitted.                                                                                          |
-| 0     | HTTPS upgrade                                             | 308 to an HTTPS `publicUrl`, with path and query _assigned_ onto it rather than resolved against it, so a `//host` pathname cannot replace the origin. `/health` is exempt: a loopback probe must not need public DNS.                                             |
-| 0     | Cloudflare Access (Worker, when enabled)                  | Edge admission ahead of this table; an admitted invocation carries trusted identity in `ctx.access`.                                                                                                                                                               |
-| 1     | `/oauth/client-metadata/<connectorId>`                    | Public GET-only CIMD for configured self-hosted OAuth connectors; fixed `publicUrl`, no auth or storage.                                                                                                                                                           |
-| 1     | Mounted UI routes                                         | Before wildcard OPTIONS, so mutation routes refuse preflight rather than inheriting MCP CORS. No UI module, no routes.                                                                                                                                             |
-| 1     | `/connect/<connectorId>`, `/oauth/callback/<connectorId>` | GET-only browser OAuth routes, before wildcard OPTIONS. Both verify the initiating user and management permission, independent of the UI.                                                                                                                          |
-| 2     | MCP preflight                                             | Allowed `OPTIONS` on `/mcp*`: 204 without admission or auth.                                                                                                                                                                                                       |
-| 2     | Other `OPTIONS`                                           | Auth metadata first, otherwise compatibility CORS preflight.                                                                                                                                                                                                       |
-| 3     | `/.well-known/*`                                          | Auth metadata, or 404.                                                                                                                                                                                                                                             |
-| 4     | `/health`                                                 | Open and payload-free: health, executor, admission, and deployment metadata.                                                                                                                                                                                       |
-| 6     | `/mcp`, `/mcp/<pool>`                                     | Admission, then auth, then a request-local MCP server. Body-confirmed modern listens skip admission and are refused after auth and SDK validation. An undeclared pool, a refusing grant, and a throwing grant are one identical 404; see [pools](./auth.md#pools). |
-| 7     | Other paths                                               | 404. Custom HTTP routes belong to the deployment.                                                                                                                                                                                                                  |
+| Order | Route                                                     | Notes                                                                                                                                                                                                                                                                                |
+| ----- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 0     | MCP Origin check                                          | A disallowed `Origin` on `/mcp*` is a fixed 403 before redirects, admission, auth, or preflight — costing no permit and no auth lookup. Originless requests are admitted.                                                                                                            |
+| 0     | HTTPS upgrade                                             | 308 to an HTTPS `publicUrl`, with path and query _assigned_ onto it rather than resolved against it, so a `//host` pathname cannot replace the origin. `/health` is exempt: a loopback probe must not need public DNS.                                                               |
+| 0     | Cloudflare Access (Worker, when enabled)                  | Edge admission ahead of this table; an admitted invocation carries trusted identity in `ctx.access`.                                                                                                                                                                                 |
+| 1     | `/oauth/client-metadata/<connectorId>`                    | Public GET-only CIMD for configured self-hosted OAuth connectors; fixed `publicUrl`, no auth or storage.                                                                                                                                                                             |
+| 1     | Mounted UI routes                                         | Before wildcard OPTIONS, so mutation routes refuse preflight rather than inheriting MCP CORS. No UI module, no routes.                                                                                                                                                               |
+| 1     | `/connect/<connectorId>`, `/oauth/callback/<connectorId>` | GET-only browser OAuth routes, before wildcard OPTIONS. Both verify the initiating user and management permission, independent of the UI.                                                                                                                                            |
+| 2     | MCP preflight                                             | Allowed `OPTIONS` on `/mcp*`: 204 without admission or auth.                                                                                                                                                                                                                         |
+| 2     | Other `OPTIONS`                                           | Auth metadata first, otherwise compatibility CORS preflight.                                                                                                                                                                                                                         |
+| 3     | `/.well-known/*`                                          | Public auth metadata, or 404. Protected-resource discovery does not authenticate callers or evaluate endpoint grants.                                                                                                                                                                |
+| 4     | `/health`                                                 | Open and payload-free: health, executor, admission, and deployment metadata.                                                                                                                                                                                                         |
+| 6     | `/mcp`, `/mcp/<pool>`                                     | Admission, then auth, then a request-local MCP server. Body-confirmed modern listens skip admission and are refused after auth and SDK validation. An undeclared pool, a refusing endpoint grant, and a throwing endpoint grant are one identical 404; see [pools](./auth.md#pools). |
+| 7     | Other paths                                               | 404. Custom HTTP routes belong to the deployment.                                                                                                                                                                                                                                    |
 
 Every response leaves through `withSecurityHeaders`. HTML uses one common
 security-header helper, including status and error pages. Operator shells
@@ -131,12 +131,17 @@ An admitted non-preflight `/mcp` request then takes five steps in
 3. **Narrow to the pool.** On `/mcp/<pool>`, look the name up, run its grant
    against the identity, then `intersectAccess` the pool with the identity's own
    access. A pool can never widen a view; anything else is a 404 naming no pool.
+   The endpoint's `readOnly` is the pool's own value, else the deployment's;
+   plain `/mcp` uses the deployment's. It travels to the meta-tools and the
+   program as one boolean that drops writes from `CatalogService` search and
+   describe and makes `writeRefusal` (`src/tool-safety.ts`) refuse every write
+   call. Guides and skills are not filtered.
 4. **Derive the registry view.** One `registry.scoped(...)` call with those
    connector ids, exact `connector.tool` addresses when the identity declares a
    narrower slice, and the subject and principal keys. Personal connectors use
    the principal partition and result paging the subject partition with principal,
    endpoint/pool, origin, connector, and tool bindings. Paging rechecks current
-   grants, pool membership, and trust; no caller parameter selects a partition (`test/identity-scope.test.ts`).
+   grants, pool membership, and the endpoint's `readOnly`; no caller parameter selects a partition (`test/identity-scope.test.ts`).
 5. **Serve.** Refuse `?toolkit=` with a 404 — the toolkits are gone
    ([#178](https://github.com/zackbart/connecta/issues/178)) but their URLs were
    handed out, and retiring a scoping boundary into fail-open is worse than any
@@ -217,13 +222,15 @@ or hands out, and a change usually belongs in exactly one of them:
 | `src/invocation.ts`      | One tool call: argument validation, call admission, one-attempt timeout, provider retry hints, result unwrapping, size capping, and the activity record.                                                                         |
 | `src/catalog.ts`         | Ranking, description summarizing, and the compact and TypeScript schema renderers discovery shows.                                                                                                                               |
 | `src/result-shapes.ts`   | Bounded runtime-only inference and merging for output shapes learned from successful read-only calls whose providers declared none.                                                                                              |
-| `src/program-writes.ts`  | Trusted-pool write accounting: write budgets, dispatch draining, and known or unknown outcomes.                                                                                                                                  |
+| `src/program-writes.ts`  | Program write accounting on writable endpoints: write budgets, dispatch draining, and known or unknown outcomes.                                                                                                                 |
 
 `src/meta-tools.ts` and `src/execute.ts` are two front doors onto the same two
 services, `CatalogService` and `InvocationService`. That is the point: a
 program's `connecta.call` and a top-level `call_tool` reach
 `InvocationService.invoke` by different routes and get the same admission, the
-same credential resolution, and the same fail-closed read-only check.
+same credential resolution, and the same fail-closed read-only check: one
+`writeRefusal` decision per call, from the stored classification, the calling
+surface, and the endpoint's `readOnly`.
 `test/execute.test.ts` asserts the parity directly, because a sandbox path that
 quietly diverges is how generated code would mint a capability.
 
@@ -723,18 +730,26 @@ connection context `create` supplies, the maintained text, then deployment
 instructions, which append and never replace. `src/provider.ts` imports neither
 transport, so an `api()` provider gains no MCP client or Effect graph from it
 (`test/purity.node.test.ts`). The factory carries its `definition`, which build and
-check tools read instead of keeping provider lists. All twenty providers
-live in their own folders. The eight hosted implementations, including the
+check tools read instead of keeping provider lists. Providers
+live in their own folders. Hosted implementations, including the
 MCP branches of Notion, Vercel, and Cloudflare, use reviewed presets over
-`remoteMcp({ classify })`. The eleven API-only factories retain an internal
+`remoteMcp({ classify })`. The migrated API-only factories retain an internal
 adapter to the same definition and description-stamping path. GitHub composes hosted tools with a scope-enforced REST complement.
-A `"dual"` provider lets `auth` select the implementation
+A `"dual"` provider selects one implementation at construction, usually through `auth`
 ([decision 0005](https://github.com/zackbart/connecta/blob/main/decisions/0005-auth-selects-implementation.md)):
 `variants(["auth", "type"], …)` closes each case's options, and
 `byAuth()` in `src/providers/_shared/rest/dispatch.ts` sends OAuth to
 `hostedOAuth()` (`remoteMcp()`, OAuth only, the reviewed classification) and a
-key to Connecta's REST connector. Stripe, Notion, Cloudflare, and Vercel are dual; `auth` is required.
-The REST connector (`src/providers/_shared/rest/`) serves
+key to Connecta's REST connector. Stripe, Notion, Cloudflare, and Vercel require `auth`. Mixpanel is also dual,
+with explicit `via: "mcp" | "api"` and MCP as the unchanged default: service accounts
+reach both implementations, so auth cannot distinguish them. API mode requires
+operator-managed service-account credentials and never falls back to MCP.
+Mixpanel uses the same REST transport, operation matching and value-safety engine
+for a narrow reviewed subset. Its official contracts are YAML and app identity
+has no published response schema, so its guide and drift record carry explicit
+manual review evidence instead of claiming a machine-checkable JSON pin.
+
+The generic REST connector (`src/providers/_shared/rest/`) serves
 `<vendor>_api_search`, `_api_details`, `_api_read`, and `_api_write` over an
 `OperationIndex` that `npm run providers:spec` compiles offline from the
 provider's pinned `openapi.source.json` into `openapi.generated.ts`.

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,