@zackbart/connecta 0.37.1 → 0.38.0

package/documentation/migration-0.34.md

@@ -1,9 +1,7 @@
 # Migration to 0.34
 
-Use this guide when upgrading an existing deployment from 0.33 to 0.34.
-[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover the
-general procedure; [the agent index](./README.md) routes other work. Upgrades
-from earlier versions must also apply the intervening migrations.
+Apply the [general upgrade procedure](./deploying.md#upgrade-an-existing-deployment)
+when moving from 0.33 to 0.34, including intervening migrations for older versions.
 
 No storage migration, token rotation or required configuration field is added.
 Review the following changes before updating the package pin.

package/documentation/migration-retired-layouts.md

@@ -0,0 +1,74 @@
+# Migrate before past-layout support is removed
+
+Use this guide before upgrading to the release that removes the pre-0.29
+storage and OAuth layout migrations. [Deployment upgrades](./deploying.md#upgrade-an-existing-deployment)
+cover the general procedure; [the agent index](./README.md) routes other work.
+Apply intervening configuration and provider migrations too.
+
+**0.37.1 is the last bridge release containing these migrations.** A deployment
+with Workers KV, a JSON state file, or OAuth layout-2 grants must first upgrade
+to exactly `@zackbart/connecta@0.37.1` and finish the relevant migrations there.
+Installing the bridge release alone does not migrate unused grants or storage.
+Deployments already using D1 or SQLite with layout-3 grants need no conversion.
+Keep the existing database, connector ids, owner partitions, and vault key.
+
+## Before updating the package pin
+
+1. Back up the source state and destination database securely, including expiry
+   metadata, and preserve the credential encryption key. Stop traffic and all
+   background writers; drain OAuth callbacks and refreshes. Keep a recoverable
+   0.37.1 deployment and its installed package until verification completes.
+2. For Workers KV, use 0.37.1's installed
+   `examples/worker/scripts/copy-kv-to-d1.mjs` and `kv-to-d1.wrangler.jsonc`.
+   Follow that version's `examples/worker/README.md#upgrading-from-028`:
+   wait for stable KV, run `--maintenance`, resolve invalid entries and
+   conflicts, run `--maintenance --verify`, switch to D1 under maintenance,
+   verify, then run `--maintenance --mark-live` before reopening traffic.
+   The underlying API is `copyKvToD1(kv, db, { source })` from
+   `@zackbart/connecta/d1`; finish every returned cursor, verify hashes and
+   expiries, and call `markKvToD1Live(db, source)` before cutover. Never copy
+   stale KV over a database that has accepted new writes.
+3. For Node's pre-SQLite JSON state, stop the server and run the bridge CLI:
+
+   ```sh
+   npx --yes --package=@zackbart/connecta@0.37.1 connecta migrate-state .connecta-state.json .connecta.sqlite
+   ```
+
+   It copies live entries with their expiry, keeps existing destination keys,
+   and leaves the JSON file unchanged. The old activity JSONL is not imported.
+   Use the destination SQLite file for subsequent starts.
+
+4. While still running 0.37.1 over the SQL destination, open **every OAuth
+   grant once, for every connector and owner partition** through its normal
+   authorized connection. This includes dormant personal grants. The first
+   grant read converts layout 2 to the single layout-3 `oauth:grant` record
+   and deletes historical keys. Merely listing configuration is insufficient.
+   Grants too old to have issuer binding, invalid ciphertext, and pending
+   consents require fresh authorization on the bridge release.
+5. Verify each existing OAuth connection, vault credential and agent token,
+   including every personal owner. Confirm layout-3 grant records and no
+   pending layout-2 cleanup using trusted storage tooling without printing
+   credential bodies. Only then upgrade the package pin to the removing release.
+
+## Removed interfaces and stale state
+
+| Removed path                                                                                                                       | Behavior after upgrading                                                                                                                                                                                                                                                                                                | Recovery                                                                                                                                       |
+| ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| OAuth layout-2 reader and cleanup                                                                                                  | An owner with only old keys has no usable grant. Reads return absent, credentials are never opened or copied, and a warning says to authorize again or migrate on 0.37.1. Calls require consent. Old keys remain untouched. Existing layout-3 grants, including those with an obsolete cleanup marker, remain readable. | Connect again. To preserve an old grant instead, restore a consistent pre-upgrade backup and run the bridge procedure.                         |
+| `copyKvToD1`, `markKvToD1Live`, their types/error, and copy script/config                                                          | Named imports fail; no KV copy runs. A KV adapter without atomic compare-and-set is refused at construction. A fresh D1 database contains none of the old credentials or tokens. The `/d1` subpath still exports `d1Storage` and `d1ActivityStore`.                                                                     | Stop writers and restore a consistent backup with 0.37.1, then copy and verify before cutover.                                                 |
+| `importStateFile`, `StateFileImport`, and `connecta migrate-state`                                                                 | Named imports fail; the CLI command exits nonzero with usage. The SQLite adapter never reads the JSON file, so a fresh database has no old credentials or tokens.                                                                                                                                                       | Import on 0.37.1 while stopped, then point the deployment at that SQLite file.                                                                 |
+| Retired `execute.resumableWrites`, `execute.pausedRunTtlSeconds`, `identity`, `grant`, and deployment/pool `trust` migration hints | Construction still rejects these as ordinary unknown configuration options. It no longer expands identity keys or prints replacement instructions. Pool `grant` is also rejected.                                                                                                                                       | Remove obsolete options. Follow [migration to 0.33](./migration-0.33.md) for `maintainers`, pool `members`, `agents`, and explicit `readOnly`. |
+
+A rollback after accepting new SQL writes can resurrect revoked credentials or
+spent refresh tokens. Recover from a consistent backup under maintenance rather
+than merging old KV/JSON state into a live database. If preserving old auth is
+unnecessary, reconnect credentials and issue fresh agent tokens in the current
+SQL deployment; revoke superseded credentials at their providers.
+
+## Verify
+
+Run `connecta doctor --pool <pool>` with each agent's token. Open each shared
+and personal OAuth connection and make a controlled read. Confirm authorization
+works without an unsupported-layout warning, the intended SQL database is used,
+and the operator UI shows expected credentials and activity. Remove one-shot
+migration routes and bindings after successful cutover.

package/documentation/operator-tests.md

@@ -26,22 +26,15 @@ last seen are fixed. The restricted state is the member fixture from
 use its maintainer fixture, which covers every runs-as kind and agent pools,
 with `test/fixtures/operator-console.ts` crowding the team pool so its avatar
 stack collapses to "+3".
-Collections use their corresponding browser types.
-`test/operator-visual-fixtures.test.ts` validates contract versions, connector
-IDs, granted tools, matrix cells, classification, provenance, and secret
-exclusion on Node and Workers, and runs `expectMemberViewWithholds` on the
-member body. A fixture's config cannot silently become a stale copy of the
-server serializer.
+Collections use their corresponding browser types. Real contract serialization,
+member projection and secret withholding are exercised through
+`test/operator-contract.test.ts` and `test/operator-contract-server.test.ts`.
 
 `test/browser/operator-visual.spec.ts` intercepts API reads and serves the real
-hashed assets and HTML with the production CSP. Loading responses wait on an
-explicit gate. Error responses use fixed HTTP failures. The map trace focuses its
-node instead of hovering it: the capture scrolls to the top first, which would
-move the node out from under a pointer and drop the highlight, so the test waits
-for `.map-svg.tracing` before capturing. Screenshots use a fixed
-clock, UTC, en-US, locally hosted fonts, disabled animations, hidden carets,
-and a 1280 × 900 viewport. Narrow fixtures use 390 × 844. Every test waits for
-its state and fonts before capturing.
+hashed assets and HTML with the production CSP. It captures populated Overview
+and connector Connection pages in light and dark themes: four screenshots.
+Each capture waits for the heading, page content and fonts, with a fixed clock,
+and resets scrolling before the full-page image.
 
 ## Loading and recovery probes
 
@@ -52,115 +45,22 @@ The suite also checks default v2 compatibility, the unchanged member projection,
 blocked custom connectors and bounded essential token-slot failure.
 `test/ui.test.ts` checks complete detail schemas and independent sibling scope cleanup.
 
-`test/oauth-stored-observation.test.ts` covers absent, disconnected, tokenless,
-sealed/unreadable and issuer-mismatched grants, owner isolation, both built-in
-connector paths and custom connectors. Storage spies require zero auth mutations,
-including migration and resealing. `test/operator-store.test.ts` counts scoped
-refresh/focus/mutation/poll requests, coalescing and bounded retries, and verifies
-stale admission blocks privileged reads, connection writes and token actions while
+`test/operator-store.test.ts` counts scoped refresh/focus/mutation/poll requests,
+coalescing and bounded retries, and verifies stale admission blocks privileged reads, connection writes and token actions while
 retaining the snapshot. Late reads, role/identity changes and concurrent polls
 exercise publication fences. Browser recovery and flow suites use real routes to
 check a usable shell with a stalled connector, OAuth return and scoped Refresh.
 
-## Page and state matrix
-
-Each row runs empty, loading, error, populated, and restricted-viewer fixtures
-in both light and dark themes, for 90 screenshots. The restricted viewer is a
-pool member, who gets the member page, with no tabs, on every path.
-
-| Page or tab          | Empty state                          | Loading/error request | Restricted viewer (member)          |
-| -------------------- | ------------------------------------ | --------------------- | ----------------------------------- |
-| Overview             | No connectors: nothing to map        | Config                | Member page at `/`                  |
-| Endpoints            | Root endpoint without tools          | Config                | Member page: endpoints, accounts    |
-| Connectors           | No connectors                        | Config                | Member page, no connector request   |
-| Connector Tools      | Empty catalog                        | Config                | Member page, no connector request   |
-| Connector Connection | Deployment-managed auth              | Config                | Member page, no connector request   |
-| Connector Activity   | No calls                             | Activity              | Member page, no activity request    |
-| Tokens               | No declared agents                   | Token list            | Member page, no token request       |
-| Activity             | No calls                             | Activity              | Member page, no activity request    |
-| Settings             | Snapshot without connectors or pools | Config                | Member page, no configuration facts |
-
-Populated Overview has a failing connector, auth and credential problems
-and a tokenless agent in its attention list. Populated Endpoints shows who can use each endpoint; populated Tokens has one
-agent per slot state, with pools and last seen.
-
-Another 60 screenshots cover the Overview map on the frozen v2 maintainer, one
-person's trace, and the narrow map list; configured, mismatched, unreadable and multifield
-credentials; all three OAuth client mechanisms; clean and unobserved drift;
-historical Activity; client setup; schema dialog; read/write filters; narrow
-Settings; narrow sign-in and Connection; deployment branding; `/mcp`
-and an agent pool expanded with every runs-as kind; command search; narrow
-endpoints; the connector × endpoint matrix, one cell's open popover, and the
-narrow matrix; a new token's one-time secret dialog; and the member page, wide
-and narrow. `endpoints-expanded` and `narrow-endpoints` include the team row
-collapsed to "+3". The base
-populated Activity fixture includes grouped calls, an ungrouped legacy row,
-classification/result size/client facts, and a catalog-change event.
-
-`test/browser/operator-matrix.spec.ts` serves the frozen v2 fixtures to the
-real shell. It covers the matrix's table semantics, cell names, status dots,
-runs-as labels in each kind's popover, popover keyboard behavior, placement at a short viewport, the in-flow
-fallback without CSS anchors, and the absence of `style` attributes, agent URLs on Endpoints, the member page (its
-received body checked with `expectMemberViewWithholds`, `/ui/data` answering 404
-and never requested, no maintainer fact rendered, no maintainer request sent),
-the 401 sign-in and 404 no-access gates on `/ui/api/config` with no maintainer
-navigation, the shared recovery banner on Tokens and Activity through a failed
-refresh that stalls past its deadline (one focusable Retry, no maintainer
-request until Retry succeeds), an open client setup drawer closed by a failed
-refresh with focus on Retry, Tokens under recovery (an open rotate question
-closes with focus on Retry and nothing sent; an unseen secret dialog stays open
-over the banner until dismissed), payload sentinels, CSP, and the refusal of a v1 body. Matrix coverage excludes retired grants from
-its live counts and pie, keeps their names inspectable in the popover, and
-renders an unavailable catalog as a dashed empty ring with "?" and an unknown
-accessible name. Cell names distinguish equal grants against different live
-catalog sizes. `test/operator-endpoints.test.ts` covers those view-model cases,
-including a known empty catalog versus an unavailable one.
-`test/operator-connection-map.test.ts` also checks that a failed or unobserved
-catalog counts no tools, which the map draws as a muted dash, while a known
-empty catalog counts zero.
-`test/browser/operator-overview.spec.ts` covers the Overview on the frozen v2
-fixtures: the status pill, stat labels and numbers, map columns, dashed read-only grants and dotted
-tokenless access; attention rows with their fix links, a copied fix prompt equal
-to the catalogue's text, config order through a staggered full refresh, prototype-named
-connector IDs during loading and failure, and stable single-card height when
-its catalog empties. A single long-id, long-title card at 320, 390, 1024 and
-1440px covers all eight status labels, both auth scopes, with and without the
-Read-only badge, tools and an action. Text rows stay single-line, full text
-remains accessible, links stay focusable, and the detail header and Overview
-attention rows retain their height; the hover
-sentence replacing the legend, and dimming; keyboard focus in column order with each node's sentence
-as its accessible name, Enter opening an endpoint's row and a connector; the
-narrow list, whose caller chips link where their map nodes do; an empty deployment; and a member at `/` getting the member page
-with no maintainer read, plus CSP and no `style` attributes.
-`test/browser/operator-console.spec.ts` covers UI-3: who-can-use chips by
-label, raw id and agent mark and "+N" from the keyboard; Tokens rows,
-issue with the once-only secret dialog, in-row rotate and revoke questions,
-503, 499 and 409 failures that send exactly one request, slots missing from
-the list or left unresolved shown with disabled controls until Refresh; and the
-member page (its received body checked with `expectMemberViewWithholds`, no
-tabs, Search or maintainer fact, OAuth Connect, Reconnect and Disconnect sent as
-`?mode=continue`, `?mode=restart` and `DELETE`, the credential `actions`
-shapes, a refresh that drops an action closing its confirmation, a failed or
-stalled refresh keeping member chrome with Retry, a consent that outlasts the
-OAuth poll window), plus keyboard, sentinels, CSP and no `style` attributes.
-`test/operator-console.test.ts` covers the chip, slot-row and member-page view
-models. `test/browser/operator-scheme.spec.ts` holds the main bundle and checks the
-first painted background: saved dark on a light system paints dark, a pinned
-light deployment paints light over saved dark, and throwing storage keeps the
-system scheme while the released bundle settles on the normal bearer gate, and a
-sign-in there raises no error. The real-route token test in `test/browser/operator-ui.spec.ts` serves
-the contract, `/ui/data` and the slot routes from one real v2 deployment and
-checks that each mutation sent a distinct 22-character `expect`.
-`test/operator-store.test.ts` serves `/ui/api/config` from its own mock, so
-each test's data and detail answers stay separate, and covers role changes: a
-maintainer demoted after a failed refresh keeps no maintainer state and sends
-no maintainer request, and a promoted member loads maintainer data fresh. It
-also drives UI-3's slot fence with a session-token read held open: reloads and
-contract refreshes that move or drop a slot before dispatch, late results that
-cannot overwrite newer evidence, unknown and unreadable outcomes that only a
-later list read settles, revisions sent as `expect` and compared with the
-contract, an identity change that leaves the next identity's fence alone, and
-member actions whose `manage` a refresh changes.
+## Browser behavior evidence
+
+| Suite                                    | Assertions                                                                                                                                                                                 |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `test/browser/operator-matrix.spec.ts`   | Members see their own page on every path, get scoped setup links, and never request maintainer data.                                                                                       |
+| `test/browser/operator-overview.spec.ts` | Overview health, counts and map edges; per-caller status and principal-refusal copy without secret fix prompts.                                                                            |
+| `test/browser/operator-console.spec.ts`  | Token issue/rotate/revoke confirmations and once-only secret display; member credential fields and OAuth connect/reconnect/disconnect controls.                                            |
+| `test/browser/operator-pages.spec.ts`    | Resolved read/write filters, inert schema text, Activity history/grouping, and legacy URL redirects.                                                                                       |
+| `test/browser/operator-shell.spec.ts`    | Clerk loader and child-script behavior under CSP, with inline and foreign scripts blocked.                                                                                                 |
+| `test/browser/operator-ui.spec.ts`       | Identity changes cancel reads and close popups, OAuth polling stays scoped, token mutations use real routes and distinct revisions, and declared agents show scoped credentials and usage. |
 
 Screenshots cover presentation. Keep unit and server tests for INV-6 sentinels,
 secret disclosure, auth and grant boundaries, CSRF, identity fences, cancellation,

package/documentation/operator-ui.md

@@ -699,10 +699,9 @@ the page's styles.
 
 `src/operator-ui/config-summary.ts` maps the snapshot and its provenance to
 those tiles: one table of limit labels, the formatters, and the walk that turns
-an unmapped key into an Other tile. `app/config-tiles.tsx` draws them, and
-`test/operator-config-summary.test.ts` checks formatting, provenance, unknown
-keys, an empty deployment, and that a real deployment's snapshot leaves no key
-unmapped.
+an unmapped key into an Other tile. `app/config-tiles.tsx` draws them.
+`test/browser/operator-flows.spec.ts` checks Settings provenance through the
+production UI and real routes.
 
 The contract type is [contract.ts](https://github.com/zackbart/connecta/blob/main/src/operator-ui/contract.ts).
 [UI routes](https://github.com/zackbart/connecta/blob/main/src/routes/ui.ts) and

package/documentation/provider-auth-migration.md

@@ -1,15 +1,9 @@
 # Provider auth migration
 
-Hosted selections described in this historical migration are now removed.
-For Stripe, Vercel, Cloudflare, Notion, Mixpanel, and GitHub hosted connections,
-use the [current hosted MCP migration guide](./hosted-mcp-migration.md).
-The API migrations below remain applicable.
-
-Use this upgrade guide when moving a Stripe, Vercel, or Cloudflare
-deployment from 0.30 to 0.31, where `auth` selects each provider's
-implementation.
-[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
-version changes; [integrating services](./integrating.md) covers new connectors.
+This guide covers the 0.30-to-0.31 change to auth-selected implementations.
+For current versions, follow [deployment upgrades](./deploying.md#upgrade-an-existing-deployment)
+and [hosted MCP migration](./hosted-mcp-migration.md); hosted selectors below
+are historical.
 
 A dual provider requires `auth`. `{ type: "oauth" }` connects the vendor's
 hosted MCP server, OAuth only. A key type connects Connecta's REST connector

package/documentation/provider-migration-0.29.md

@@ -1,20 +1,9 @@
 # Notion, Vercel and Cloudflare migration for 0.29
 
-Hosted selections described in this historical migration are now removed.
-For Stripe, Vercel, Cloudflare, Notion, Mixpanel, and GitHub hosted connections,
-use the [current hosted MCP migration guide](./hosted-mcp-migration.md).
-The API migrations below remain applicable.
-
-Use this upgrade guide for an existing deployment.
-[Deployment upgrades](./deploying.md#upgrade-an-existing-deployment) cover other
-version changes; [integrating services](./integrating.md) covers new connectors.
-[The agent index](./README.md) routes package maintenance separately.
-
-This was the Phase 1 item 5d migration input for [Phase 5 release #709](https://github.com/zackbart/connecta/issues/709),
-which shipped as 0.29.0.
-Deployments that use Notion or Cloudflare must check their actual grants and
-connector ids in deployment configuration before that release.
-The provider audit establishes available auth modes, not production OAuth grants.
+This guide records the 0.29 Notion, Vercel and Cloudflare option changes.
+For upgrades to current versions, use [deployment upgrades](./deploying.md#upgrade-an-existing-deployment)
+and [hosted MCP migration](./hosted-mcp-migration.md); the hosted selectors below
+are historical and cannot be used in current configuration.
 
 Cloudflare's part of this guide is superseded: `cloudflare()` now selects its
 implementation by `auth` and its key connector is complete on its own. Follow

package/examples/worker/AGENTS.md

@@ -67,12 +67,10 @@ tokens, upgrading, and diagnosis with `connecta doctor` to their procedures.
 - All state lives in the one D1 database bound as `CONNECTA_DB`, through
   `d1Storage` (and `d1ActivityStore`) from `@zackbart/connecta/d1`. Do not add
   a KV namespace, a second database, or a copied storage adapter; connecta
-  creates its own tables. The only KV binding is in `kv-to-d1.wrangler.jsonc`,
-  which is never deployed. It exists for the one-shot copy from a 0.28 Workers
-  KV deployment (README.md § "Upgrading from 0.28"). Back up, block traffic
-  and background writers, drain, wait for stable KV, copy and verify, deploy
-  while maintenance remains, then mark cutover before reopening traffic. Never
-  rerun stale KV after cutover. Retain backups before removing KV.
+  creates its own tables. Pre-0.29 Workers KV state must be copied on
+  Connecta 0.37.1 before upgrading past that bridge release; follow the installed
+  package's `documentation/migration-retired-layouts.md`. The current example
+  includes no KV copy script or binding.
 - Add application logic only inside deliberate `api()` connector handlers.
   Do not copy or modify Connecta package internals here.
 - Prefer `api()` when the agent must see an exact reviewed capability set;

package/examples/worker/README.md

@@ -21,14 +21,13 @@ migrations, and secrets.
 
 ## Files
 
-| File                                                   | What it is                                                                                                                                                        |
-| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/index.ts`                                         | the Worker entrypoint — starts the configuration, under 30 lines                                                                                                  |
-| `src/connecta.config.ts`                               | connectors, auth, storage, and optional modules, as `defineConfig((env) => …)`                                                                                    |
-| `alchemy.run.ts`                                       | the deployment: Worker, vars, secrets, D1, Worker Loader, and both Access applications                                                                            |
-| `wrangler.jsonc`                                       | local `wrangler dev` only, with a simulated Access identity; never used to deploy                                                                                 |
-| `gitignore`                                            | the copied deployment's `.gitignore`, shipped under this name because npm strips `.gitignore` ([Copied into its own repository](#copied-into-its-own-repository)) |
-| `scripts/copy-kv-to-d1.mjs`, `kv-to-d1.wrangler.jsonc` | one-shot copy of a 0.28 Workers KV deployment's state into D1, run once and deleted ([Upgrading from 0.28](#upgrading-from-028))                                  |
+| File                     | What it is                                                                                                                                                        |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/index.ts`           | the Worker entrypoint — starts the configuration, under 30 lines                                                                                                  |
+| `src/connecta.config.ts` | connectors, auth, storage, and optional modules, as `defineConfig((env) => …)`                                                                                    |
+| `alchemy.run.ts`         | the deployment: Worker, vars, secrets, D1, Worker Loader, and both Access applications                                                                            |
+| `wrangler.jsonc`         | local `wrangler dev` only, with a simulated Access identity; never used to deploy                                                                                 |
+| `gitignore`              | the copied deployment's `.gitignore`, shipped under this name because npm strips `.gitignore` ([Copied into its own repository](#copied-into-its-own-repository)) |
 
 Construct Connecta once per isolate and pass `ctx` through to `fetch`, as the
 example entrypoint does.
@@ -261,31 +260,10 @@ the Access policy or application.
 
 ### Let agents through Access
 
-`ConnectaAgents` in `alchemy.run.ts` is a second self-hosted Access
-application whose destination is `<PUBLIC_URL host>/agent/*`, with a single
-policy whose action is **Bypass** and whose include rule is **Everyone**. The
-Worker-level application still protects every other path. Never bypass any
-other path. To serve agents on another hostname too, add a destination for it,
-for example `{ type: "public", uri: "agents.example.com/agent/*" }`. Through the
-Access API, the application is:
-
-```json
-{
-  "type": "self_hosted",
-  "name": "connecta agents",
-  "destinations": [{ "type": "public", "uri": "connecta.example.com/agent/*" }],
-  "policies": [{ "name": "agents bypass", "decision": "bypass", "include": [{ "everyone": {} }] }]
-}
-```
-
-It must be a hostname-and-path (`public`) destination: a second Worker
-destination is refused because the Worker-level application owns it. Changes
-took 15–19 seconds to settle when probed, occasionally longer, with transient
-edge errors meanwhile. Do not rely on a fixed wait; repeat
-[Verify after deploying](#verify-after-deploying). Connecta ignores Access
-context on `/agent/*` and refuses every other spelling of that namespace before
-auth. [Deploying Connecta](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md#agent-endpoints-behind-cloudflare-access)
-records the untested cases and the propagation details.
+`ConnectaAgents` in `alchemy.run.ts` declares the agent bypass. Follow
+[Agent endpoints behind Cloudflare Access](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md#agent-endpoints-behind-cloudflare-access)
+for the hostname-and-path application, API JSON, matching rules and controls.
+Repeat [Verify after deploying](#verify-after-deploying) after Access changes.
 
 ### Moving a Wrangler-deployed Worker to Alchemy
 
@@ -357,7 +335,7 @@ it reports, run Alchemy and Wrangler only on a trusted machine, keep
 `alchemy dev` and `wrangler dev` bound to localhost, and give the API token
 only the four permissions in [Deploy](#deploy) and a short expiry.
 
-`wrangler` serves only `wrangler dev` and `scripts/copy-kv-to-d1.mjs`. A
+`wrangler` serves local `wrangler dev`. A
 `tsconfig.json` like the following lets `tsc --noEmit`
 resolve `D1Database`, `WorkerLoader`, and `ExecutionContext`, and checks the
 stack:
@@ -623,87 +601,14 @@ Each shape moves to the one `CONNECTA_DB` binding:
 
 #### Copying Workers KV state into D1
 
-Storage keys did not change in 0.29. `copyKvToD1(kv, db, { source })` from
-`@zackbart/connecta/d1` preserves live keys, exact values including vault
-ciphertext, and absolute expiries. The source is the KV namespace id. Counts
-and failures name only families, never keys or values. Oversized UTF-8 strings
-or rows are skipped and counted as invalid against D1's
-[2,000,000-byte limit](https://developers.cloudflare.com/d1/platform/limits/).
-A different live D1 value or expiry is a conflict, kept by default.
-
-Use a maintenance window. Copying while either deployment serves can restore
-revoked tokens, stale refresh tokens, or disconnected connectors. A rerun is
-safe only while the source remains stable and D1 has no new application writes.
-The script reads the source id from `kv-to-d1.wrangler.jsonc` and checks two
-consecutive listing/hash passes before a copy or verification pass. The config
-uses remote KV and D1 bindings and is never deployed.
-
-Prepare the new configuration without deploying it. Use the existing activity
-D1 database as `CONNECTA_DB`, keeping its name and id; otherwise create one
-with `wrangler d1 create connecta`. Remove `kv_namespaces` and copied adapters.
-Configuration lives in `src/connecta.config.ts` and
-`src/index.ts` is the entry point. Set the plain var `CONNECTA_ACTIVITY = "on"`
-so preserved activity remains visible. Bind only `CONNECTA_DB` and `LOADER` for storage/execution;
-keep existing auth vars and the credential secret.
-Fill in the copy config's namespace id and the same D1 database name/id,
-then `wrangler login` and check the prepared deployment with a dry run.
-
-1. Back up KV with a bulk export including values and expiration metadata.
-   Export D1 with `wrangler d1 export <db> --remote --output before-cutover.sql`.
-   Store backups securely and preserve the exact credential encryption key,
-   whatever secret name the deployment stores it under.
-2. Block traffic using maintenance mode or turn the route off. Stop cron,
-   queue consumers, scheduled jobs, and every other KV/D1 writer. Drain all
-   in-flight requests, including OAuth callbacks and token refreshes.
-3. Wait at least **60 seconds after the last write**, or the longest configured
-   KV `cacheTtl`, whichever is greater. KV propagation can take longer, so this
-   is a minimum, not proof of consistency. See
-   [KV consistency](https://developers.cloudflare.com/kv/concepts/how-kv-works/).
-   Confirm a stable source with two consecutive listing/hash passes that match;
-   the script performs this check. If they differ, stay in maintenance, wait
-   longer, and repeat. Expiring entries may also require another pass.
-4. Copy **before switching traffic** with
-   `node scripts/copy-kv-to-d1.mjs --maintenance`. Resolve all `invalid` and
-   `conflicts` counts under maintenance; either makes the script exit non-zero.
-   An oversized entry requires a deliberate per-family remediation, not a
-   retry of the same value. Overwrite only families explicitly reviewed as
-   stale in D1, for example `--maintenance --overwrite-family catalog`.
-   Token/OAuth/vault families require the operator to confirm D1 rows are stale
-   and also pass `--confirm-stale-d1`; never infer this from a conflict alone.
-   There is no blanket `--overwrite`. Then run
-   `node scripts/copy-kv-to-d1.mjs --maintenance --verify`. It compares SHA-256
-   hashes of exact values and absolute expiries for live source keys, reports
-   `verified` / `mismatches` counts by family only, and exits non-zero on any
-   invalid entry or mismatch. Keep traffic and writers stopped until these
-   counts are resolved. A verification pass does not rewrite copied entries.
-5. Deploy the D1 configuration with the deployment's `wrangler deploy` while maintenance remains.
-   Run `connecta doctor --pool <pool>` using Access service credentials plus a
-   stored `cta_` bearer through `CONNECTA_TOKEN`. Verify an existing
-   OAuth connector without re-consent, an existing `cta_` token, a connector
-   using a vault credential, and prior activity in the Activity view. Run
-   these controlled checks with other traffic and background writers blocked.
-6. Seal the source with
-   `node scripts/copy-kv-to-d1.mjs --maintenance --mark-live`, then reopen
-   traffic and background writers. The permanent D1 marker refuses later
-   copies. Never rerun after traffic resumes. `--i-know-this-is-stale` is only
-   an emergency override after stopping writers again and assessing stale KV;
-   it does not make stale tokens or credentials safe to restore.
-   Retain backups before deleting the KV namespace. After a clean observation
-   period, remove the copy script/config and delete KV with
-   `wrangler kv namespace delete --namespace-id <id>`.
-
-An in-Worker copy can call
-`copyKvToD1(env.CONNECTA_KV, env.CONNECTA_DB, { source: namespaceId, cursor })`
-from a guarded one-off route under the same maintenance procedure. Each call
-reads at most `maxKeys` keys, default 500. For near-limit rows use 200 or fewer
-so additional byte-bounded D1 batches fit the invocation's query budget.
-Loop until `done`, passing each returned cursor. Tokens keep KV's raw cursor
-in D1 for seven days, are bound to the source id, and are atomically consumed.
-Unknown, spent, or foreign-source tokens are refused without echoing them.
-On failure, use the error's replacement token or restart under maintenance.
-Call `markKvToD1Live(db, namespaceId)` before reopening traffic, and remove the
-route and KV binding. The source stability check is the operator's duty when
-using the API directly. Remote bindings remain unverified until deploy day.
+Complete this conversion on Connecta 0.37.1 before installing the release
+that removes migrations. The current `/d1` subpath provides `d1Storage` and
+`d1ActivityStore`; it no longer exports `copyKvToD1`, `markKvToD1Live`, or
+migration types, and this example no longer includes the copy script/config.
+Use the 0.37.1 package's Worker example under maintenance, verify the copy,
+mark cutover, and open every owner's OAuth grant on that bridge release.
+Follow [Retired layout migrations](../../documentation/migration-retired-layouts.md)
+for the required order and recovery. Never copy stale KV into a live database.
 
 ## Activity history (optional)
 

package/guides/connecting-agents.md

@@ -68,14 +68,11 @@ sequenceDiagram
     C-->>H: Serve the pool's permitted tools
 ```
 
-Anyone who obtains either token can act as the agent. Trust the Vercel
-project code and build steps that can obtain its tokens, and enable only
-environments that should have the pool's access.
-
-The [token management guide](../documentation/auth.md#issue-rotate-or-revoke-an-agent-token)
+[Safety and trust](./safety-and-trust.md#a-credential-proves-an-agent-not-a-person)
+explains who can act with these credentials. The
+[token management guide](../documentation/auth.md#issue-rotate-or-revoke-an-agent-token)
 and [Vercel identity guide](../documentation/auth.md#vercel-workload-credentials)
-own availability, setup, rotation, and revocation. If both methods are
-enabled, stopping one does not stop the other.
+own setup, rotation, and revocation.
 
 ## An optional integration for Eve
 
@@ -114,29 +111,9 @@ identity. Instructions help the model use tools; they grant no permissions.
 
 ## Decide whether writes need a person
 
-The helper defaults to unattended execution of authorized writes. Connecting
-an agent does not automatically add an approval step.
-
-```mermaid
-flowchart TB
-    Call["Agent requests a change"] --> Ask{"App asks for approval?"}
-    Ask -->|Yes| Approved{"Person approves?"}
-    Approved -->|No| Stop["Stop"]
-    Approved -->|Yes| Pool{"Connecta allows this write?"}
-    Ask -->|No| Pool
-    Pool -->|No| Refuse["Refuse before sending"]
-    Pool -->|Yes| Send["Send the change"]
-```
-
-For an interactive Eve agent, `gateWrites: true` asks before tools not marked
-read-only. An explicit Eve approval policy takes precedence. If the agent
-must never update data, use a read-only pool.
-
-Approval may rely on an earlier tool label. A writable pool can execute a
-newly classified write without a fresh approval; a read-only pool refuses it.
-[Safety and trust](./safety-and-trust.md) explains the boundary, and the
-[helper guide](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md#approval-and-writes)
-explains the policy mechanics.
+Agree on an approval policy before enabling writes. See
+[approval boundaries](./safety-and-trust.md#read-only-blocks-actions-that-change-data)
+and the [Eve helper's approval setup](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md#approval-and-writes).
 
 ## When accounts or audiences differ
 

package/guides/how-it-works.md

@@ -115,8 +115,8 @@ unbounded data.
 
 With meta-tools, one discovered read can use a direct call. Finding an unfamiliar
 action, combining several calls, or reducing a large answer belongs in a program.
-On a writable endpoint, a program may also change data. The AI app decides
-whether to ask for approval before running it.
+On a writable endpoint, a program may also change data; see
+[approval boundaries](./safety-and-trust.md#read-only-blocks-actions-that-change-data).
 
 The [endpoint workflow](../documentation/operating.md) and
 [code reference](../documentation/code-mode.md) explain the mechanics.

package/guides/safety-and-trust.md

@@ -71,7 +71,10 @@ or contradictory read hints count as writes, but a service can mislabel an
 action and an operator can override its label. Use restricted service
 credentials as another boundary where possible.
 
-The AI app owns approvals. It may ask based on an earlier tool label. If a
+The Eve helper defaults to unattended authorized writes. For interactive use,
+`gateWrites: true` asks before tools not marked read-only; an explicit Eve
+approval policy takes precedence. The AI app owns approvals. It may ask based
+on an earlier tool label. If a
 read becomes a write, a writable pool can execute it without a fresh
 approval; a read-only pool refuses it. Connecta does not pause a program to
 ask a person partway through.