@zackbart/connecta 0.28.1 → 0.30.0

package/examples/worker/README.md

@@ -1,9 +1,17 @@
 # connecta — Cloudflare Worker example
 
+Agent setup guide for the Worker deployment.
+For deployment choices and upgrades, use [Deploying Connecta](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md).
+For connector changes, use [Integrating services](https://github.com/zackbart/connecta/blob/main/documentation/integrating.md).
+The [agent index](https://github.com/zackbart/connecta/blob/main/documentation/README.md) routes endpoint use and package
+maintenance. This README and [local agent instructions](./AGENTS.md) own the
+runnable Worker steps.
+
 A deployable Worker that aggregates a downstream remote MCP and an in-code HTTP
-API connector, guarded by Cloudflare Access, with state in a KV namespace. Its
-required Worker Loader binding backs the seven-tool surface and requires the
-Workers Paid plan.
+API connector, guarded by Cloudflare Access. It uses three Cloudflare resources
+and nothing else: one D1 database (`CONNECTA_DB`) for every piece of state, the
+Worker Loader binding (`LOADER`) behind the six-tool surface, which requires
+the Workers Paid plan, and one secret (`CREDENTIAL_ENCRYPTION_KEY`).
 
 This is also the **starting template for a deployment**: a real deployment
 should be its own repository that pins an exact `@zackbart/connecta` version and
@@ -12,15 +20,12 @@ migrations, and secrets.
 
 ## Files
 
-| File | What it is |
-| --- | --- |
-| `src/index.ts` | the Worker entrypoint — connector and auth configuration |
-| `src/cloudflare-kv.ts` | `KVStorage` over Workers KV (deployment-owned, not a package export) |
-| `src/d1-storage.ts` | `KVStorage` over D1 with atomic compare-and-set (optional; see below) |
-| `src/d1-activity.ts` | `ActivityStore` over D1 (deployment-owned; see below) |
-| `src/d1-activity-row.ts` | the row ↔ event mapping `d1-activity.ts` uses, including friction derived from `error_code` for rows written before that column existed |
-| `src/r2-artifact-blobs.ts` | artifact bodies in an R2 bucket, beside a D1-backed `kvArtifactStore` (optional) |
-| `wrangler.jsonc` | Worker name, vars, bindings, `compatibility_flags` |
+| 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) => …)`                                                   |
+| `wrangler.jsonc`                                       | Worker name, vars, bindings, `compatibility_flags`                                                                               |
+| `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)) |
 
 Keep `enable_request_signal` in `wrangler.jsonc`. On Workers it lets a live
 response's client disconnect abort its request, so connecta cancels the stream
@@ -30,13 +35,10 @@ on a later request if workerd ends one without delivering a signal or stream
 cancellation. Set it above the longest authorization, tool call, and response
 delivery your deployment expects to serve.
 
-`cloudflare-kv.ts`, `d1-storage.ts`, and `d1-activity.ts` deliberately live
-here rather than in the package: storage backends are deployment-owned, so the
-package ships only the generic `KVStorage` and `ActivityStore` contracts.
-Workers KV is eventually consistent across locations; use a strongly consistent
-`KVStorage` adapter, such as [`d1-storage.ts`](#strongly-consistent-storage-optional),
-when OAuth disconnect or credential rotation must become globally visible
-immediately.
+Storage is `d1Storage(env.CONNECTA_DB)` from `@zackbart/connecta/d1`, and
+activity history, when `CONNECTA_ACTIVITY` is `"on"`, is `d1ActivityStore` over
+the same database.
+See [Storage](#storage).
 
 ## Deploy
 
@@ -46,7 +48,7 @@ package from the repository root.
 ```sh
 npm install                                    # from the package root
 
-wrangler kv namespace create CONNECTA_KV       # paste the id into wrangler.jsonc
+wrangler d1 create connecta                    # paste the id into wrangler.jsonc
 
 cd examples/worker
 wrangler secret put DOWNSTREAM_TOKEN
@@ -79,8 +81,10 @@ attempt and add the narrowest matching entry rather than allowing its entire
 origin.
 
 Access then serves OAuth discovery and turns the client's opaque token into the
-trusted `ctx.access` identity connecta reads. A cron job or CI client uses an
-Access service token instead.
+trusted human `ctx.access` identity connecta reads. A cron job or CI client
+needs Access service headers to cross the edge and a stored `cta_` bearer to
+authenticate inside connecta. An Access service identity alone is refused.
+See [Machine tokens](#machine-tokens).
 
 Through the API, the relevant part of the application is:
 
@@ -115,8 +119,8 @@ on a deployed Worker's production identity.
 ### Optional resource management with Alchemy
 
 Keep this example's Worker on Wrangler. A copied deployment may use
-[Alchemy](https://alchemy.run) to manage its KV namespace, optional D1 databases
-and R2 bucket, and the Access application without adding Alchemy to connecta or
+[Alchemy](https://alchemy.run) to manage its D1 database, optional R2 bucket,
+and the Access application without adding Alchemy to connecta or
 changing this template. In that deployment, install `alchemy@2.0.0-beta.79`
 and `effect@4.0.0` at exact versions. The latter is connecta's own
 Effect pin; check `npm ls effect` for one resolved copy after installation.
@@ -135,14 +139,9 @@ export default Alchemy.Stack(
   "ConnectaResources",
   { providers: Cloudflare.providers(), state: Cloudflare.state() },
   Effect.gen(function* () {
-    const kv = yield* Cloudflare.KV.Namespace("ConnectaKV", { title: "connecta-kv" }).pipe(adopt(true));
-    const activity = yield* Cloudflare.D1.Database("ActivityDB", {
-      name: "connecta-activity", migrations: "./migrations/activity",
-    }).pipe(adopt(true));
-    const storage = yield* Cloudflare.D1.Database("StorageDB", {
-      name: "connecta-storage", migrations: "./migrations/storage",
+    const database = yield* Cloudflare.D1.Database("ConnectaDB", {
+      name: "connecta",
     }).pipe(adopt(true));
-    const blobs = yield* Cloudflare.R2.Bucket("ArtifactBlobs", { name: "connecta-artifacts" }).pipe(adopt(true));
     const access = yield* Cloudflare.Access.Application("ConnectaAccess", {
       type: "self_hosted",
       name: "Connecta",
@@ -160,42 +159,34 @@ export default Alchemy.Stack(
         },
       },
     }).pipe(adopt(true));
-    return { kvId: kv.namespaceId, activityId: activity.databaseId,
-      storageId: storage.databaseId, bucketName: blobs.bucketName,
+    return { databaseId: database.databaseId,
       accessId: access.applicationId };
   }),
 );
 ```
 
 Replace the Worker ID and example Access policy before applying this stack.
-Keep only the resources the deployment uses: `STORAGE_DB` replaces
-`CONNECTA_KV`; `ACTIVITY_DB` and R2 are optional. Copy the output IDs into the
-matching `wrangler.jsonc` bindings. Keep `LOADER` in `worker_loaders` and, when
-enabled, the Browser Rendering binding and cron trigger in the Wrangler-owned
-Worker configuration. Configure the main and artifact hostnames as Wrangler
-custom domain `routes` with `custom_domain: true`. The Worker-level Access
-destination covers both hostnames; verify both against the same application
-after domain setup. Continue to set secrets with `wrangler secret put` and to
-deploy the Worker with Wrangler. After its initial `wrangler deploy`, use
-`wrangler versions upload` and `wrangler versions deploy` for code updates;
-apply route and cron changes through Wrangler too.
+`CONNECTA_DB` is required. Copy the database ID into `wrangler.jsonc` and keep
+`LOADER` in `worker_loaders`. Configure the hostname as a Wrangler custom domain
+route with `custom_domain: true`. Verify it against the Worker-level Access
+application, set secrets with `wrangler secret put`, and deploy with Wrangler.
+After the initial `wrangler deploy`, use `wrangler versions upload` and
+`wrangler versions deploy` for code updates.
 
 The `adopt(true)` calls explicitly permit taking over matching existing
 resources; compare their live names, IDs, Access policy, and data before the
-first Alchemy deploy. Remove adoption where a resource is new. Put the D1 SQL
-from this README in the shown migration directories before deploying. With
-`migrations` configured, Alchemy copies an adopted database's Wrangler
-migration history once into `__alchemy_migrations`; the old history stays
-frozen. Review pending SQL before handing migrations over. Remote
+first Alchemy deploy. Remove adoption where a resource is new. The stack
+configures no `migrations`: connecta creates its tables on first use. Remote
 `Cloudflare.state()` bootstraps an account-level state-store Worker backed by a
 Durable Object and Secrets Store entries for its credentials. Retain them:
 deleting the state store loses Alchemy's record of what it owns.
 
-Verification for this optional path stops at the API and types. The fenced
-snippet was copied to an isolated `alchemy.run.ts` and passed `tsc --noEmit`
-with TypeScript 5.9.3, Alchemy 2.0.0-beta.79, and Effect 4.0.0, with
-`npm ls effect` confirming one resolved copy. No Alchemy deploy or adoption
-was run.
+Verification for this optional path stops at the API and types. The 0.28
+form of this snippet (a KV namespace and two D1 databases with `migrations`)
+was copied to an isolated `alchemy.run.ts` and passed `tsc --noEmit` with
+TypeScript 5.9.3, Alchemy 2.0.0-beta.79, and Effect 4.0.0, with `npm ls
+effect` confirming one resolved copy; this form only removes resources and the
+optional `migrations` field. No Alchemy deploy or adoption was run.
 [Alchemy's Worker resource](https://alchemy.run/cloudflare/compute/workers/)
 can declare `WorkerLoader`, domains, Browser Rendering, and cron wiring, but
 those properties are coupled to its script deploy. Its current full deploy
@@ -233,15 +224,17 @@ Then point an MCP client at `<PUBLIC_URL>/mcp`. The example explicitly enables
 authentication controls. The page labels tool safety, offers fixed repair
 prompts for classified failures, and shows client setup commands for endpoints
 the signed-in person may use. Those commands contain no token. There is no
-separate Credentials or Tokens tab.
+separate Credentials tab. The Access tokens page is available to permitted
+interactive operators.
 
 ## Select optional modules
 
 `cloudflareAccessAuth()` reads trusted identity after Access admits the Worker
-request. Humans may use their code-derived connector view; service identities
-can use MCP but cannot manage personal or shared auth as an interactive human.
+request. Humans may use their code-derived connector view and operator pages.
+Machines authenticate with `accessTokens(storage)` over the same D1 database;
+Access service headers alone never grant MCP access or interactive authority.
 Keep users, groups, and admission in Access. Connector visibility and management
-permissions belong in `src/index.ts`.
+permissions belong in `src/connecta.config.ts`.
 
 `identity.connectorAccess` selects discoverable and callable connectors.
 `credentialAdministration` separately allows shared credential and OAuth
@@ -250,8 +243,52 @@ account. Both management permissions default to none. Grant the intended
 owner's shared permissions explicitly, and grant users personal permissions
 only for connectors configured with `authScope: "personal"`. Static headers
 remain deployment configuration. `activityAccess` governs global history reads.
+`accessTokenManagement` separately allows interactive operators to create, rename,
+and revoke machine tokens. This example grants that permission to every signed-in
+human, matching its connector-management permissions; narrow all three for a team.
 See [inbound identity](../../documentation/auth.md#principals-visibility-and-operators).
 
+### Machine tokens
+
+`accessTokens(storage)` is always installed over `CONNECTA_DB`, with no new
+binding. Empty token storage admits no machine client. A human authenticated
+through Access can still sign in and bootstrap the first token. Open
+`<PUBLIC_URL>/`, select Access tokens, and create a named token. Save the
+returned `cta_` secret privately; it is returned once. UI-issued tokens retain
+the issuing human's principal, while connector and pool rules are evaluated
+on every request. They never grant interactive operator authority.
+
+A machine sends all three headers:
+
+```text
+CF-Access-Client-Id: <access-service-client-id>
+CF-Access-Client-Secret: <access-service-client-secret>
+Authorization: Bearer <stored-cta-token>
+```
+
+Permit the service credentials in the Worker-level Access application's policy.
+The service headers admit the request at the edge; connecta verifies the bearer
+against D1. Neither credential works alone for machine access. Doctor uses
+the same three credentials; see [Client authentication and activity](#client-authentication-and-activity).
+
+For programmatic bootstrap, trusted provisioning code that already holds this
+deployment's D1 binding can use the published API against that same storage:
+
+```ts
+import { AccessTokenManager } from "@zackbart/connecta/auth/access-tokens";
+import { d1Storage } from "@zackbart/connecta/d1";
+
+const manager = new AccessTokenManager(d1Storage(env.CONNECTA_DB));
+const { token } = await manager.create("ci-client", "trusted-provisioning");
+// Deliver token once to the client's secret store, outside logs and source control.
+```
+
+This creates a token without a human principal. The name is a label, never a
+grant. Provision only through trusted operator tooling; do not expose this
+code as a public route or mint a token at startup. Existing unrevoked `cta_`
+tokens survive a state migration into this same D1 namespace. Keep
+`accessTokens(storage)` configured and preserve the identity and pool rules.
+
 ### UI and encrypted credentials
 
 Import `operatorUi` from `@zackbart/connecta/ui` and set `ui: operatorUi()`.
@@ -270,37 +307,41 @@ the secret is configured. Keep this base64 32-byte key in Worker secrets:
 node -e "console.log(crypto.randomBytes(32).toString('base64'))"
 ```
 
-Reuse the same key and KV namespace during upgrades. Without the secret, omit
+Reuse the same key and D1 database during upgrades. Without the secret, omit
 the vault; declared credential slots remain unmanageable. Keep the key outside
-KV because it protects a copied namespace. Credential replacement takes effect
+D1 because it protects a copied database. Credential replacement takes effect
 on the next call without redeploying; no liveness probe runs in the background.
 With this vault, 0.25.0 seals existing downstream OAuth state on first read.
 Rolling back to 0.24.x then requires reauthorizing those OAuth connectors.
 
 The shipped Notion connector uses a deployment-owned static header and echo
 needs no secret. To exercise vault controls, declare a `credential` slot on an
-`api()` connector or use a provider such as `notion()` that declares its own.
+`api()` connector or use Notion's explicit `surface: "api"` integration
+interface, which declares its own slot.
 Authorized users manage that slot inside the connection. Configuring a vault
 does not create credentials or permissions by itself.
 
 ### Client authentication and activity
 
-Interactive MCP clients use Access Managed OAuth. Unattended clients use Access
-service tokens when needed. Connecta-issued `cta_` tokens and their management
-routes are removed; a configured Connecta bearer cannot cross the Access edge
-alone.
+Interactive MCP clients use Access Managed OAuth. Machine clients need both
+Access service credentials and a stored `cta_` bearer, provisioned as described
+in [Machine tokens](#machine-tokens). `accessTokens(storage)` is always enabled,
+and the example grants token management to every interactive Access operator.
+Keep token, connector, and pool grants in deployment code.
 
-Activity uses `activityHistory({ store: d1ActivityStore(env.ACTIVITY_DB) })`
-from `@zackbart/connecta/activity`. Enable the database and bindings described
-below. Omit the module and store wiring to record no history and show no
-Activity tab. Diagnostics remain independent; `logger: "silent"` suppresses
+Activity uses `activityHistory({ store: d1ActivityStore(env.CONNECTA_DB) })`,
+with `activityHistory` from `@zackbart/connecta/activity` and `d1ActivityStore`
+from `@zackbart/connecta/d1`. See [Activity history](#activity-history-optional).
+Omit the module and store wiring to record no history and show no Activity tab. Diagnostics remain independent; `logger: "silent"` suppresses
 them explicitly.
 
-Verify MCP health and the exact seven tools with:
+Verify MCP health and the exact six tools with:
 
 ```sh
-CF_ACCESS_CLIENT_ID=… CF_ACCESS_CLIENT_SECRET=… \
-  npx connecta doctor --url "$PUBLIC_URL"
+CF_ACCESS_CLIENT_ID='REPLACE_WITH_ACCESS_CLIENT_ID' \
+CF_ACCESS_CLIENT_SECRET='REPLACE_WITH_ACCESS_CLIENT_SECRET' \
+CONNECTA_TOKEN='cta_REPLACE_WITH_STORED_SECRET' \
+connecta doctor --url "$PUBLIC_URL"
 ```
 
 Doctor reports the configured `DynamicWorkerExecutor`, not a presumed Node
@@ -320,197 +361,194 @@ The required Worker Loader binding is checked into `wrangler.jsonc`:
 "worker_loaders": [{ "binding": "LOADER" }]
 ```
 
-`src/index.ts` constructs `DynamicWorkerExecutor` with only `env.LOADER` and
-serves the seven-tool surface. Do not add `bindings`, `modules`, or
+`src/connecta.config.ts` uses `workerExecutor({ loader: env.LOADER })` from
+`@zackbart/connecta/worker`. The adapter constructs the upstream
+`DynamicWorkerExecutor` with only the loader and a deadline, and disposes each
+run's loader and RPC handles when its lease ends, even if the guest has not
+settled. It serves the six-tool surface. Do not add `bindings`, `modules`, or
 `globalOutbound`; they grant guest code ambient authority. A copied deployment
 owns the package install — see
 [copied into its own repository](#copied-into-its-own-repository).
 
-## Strongly consistent storage (optional)
-
-`KVStorage` has an optional atomic `compareAndSet`, for a subsystem that must
-claim a key exactly once: artifacts commit every write by it, issuing access
-tokens requires it, and an OAuth handoff binds its owner with it when it is
-there. **Workers KV cannot provide it.** It is eventually
-consistent: two locations can each read a key as absent and both write, so
-`cloudflare-kv.ts` declares no `compareAndSet` rather than fake one with a read
-followed by a write. `src/d1-storage.ts` is a complete `KVStorage` over D1
-that does provide it, one SQL statement per claim, with TTLs honored at read
-time. It replaces the KV namespace rather than sitting beside it: every piece
-of connecta state lives in one store.
-
-1. Create the database and uncomment the `STORAGE_DB` entry of the
-   `d1_databases` binding in `wrangler.jsonc`, pasting in the id it prints:
-
-   ```sh
-   wrangler d1 create connecta-storage
-   ```
-
-2. Apply the schema (keep it in a deployment-owned `migrations/` directory):
-
-   ```sql
-   CREATE TABLE IF NOT EXISTS connecta_kv (
-     key           TEXT PRIMARY KEY,
-     value         TEXT NOT NULL,
-     expires_at_ms INTEGER
-   );
-
-   CREATE INDEX IF NOT EXISTS connecta_kv_expiry
-     ON connecta_kv (expires_at_ms);
-   ```
-
-3. In `src/index.ts`, add `STORAGE_DB: D1Database` to `Env` and build the store
-   from it:
-
-   ```ts
-   import { d1Storage } from "./d1-storage.js";
-
-   const storage = d1Storage(env.STORAGE_DB);
-   ```
+When upgrading an existing deployment, replace
+`import { DynamicWorkerExecutor } from "@cloudflare/codemode";` with
+`import { workerExecutor } from "@zackbart/connecta/worker";` and use
+`executor: workerExecutor({ loader: env.LOADER })` instead of
+`executor: new DynamicWorkerExecutor({ loader: env.LOADER })`. Keep
+`@cloudflare/codemode` installed as the optional peer. Direct upstream
+construction now throws at boot with this migration instruction; its private
+loader cannot release request-owned handles through Connecta's generic executor
+wrapper.
+
+## Storage
+
+Every piece of connecta state lives in the one D1 database bound as
+`CONNECTA_DB`: downstream OAuth grants, sealed vault credentials, catalogs,
+result paging, OAuth handoffs, access tokens, and activity.
+`d1Storage` creates its `connecta_kv` table on first use, and
+`d1ActivityStore` its `tool_call_activity` table, so there is no schema to
+apply. Every compare-and-set is one SQL statement, which D1 serializes on the
+database's primary: two isolates claiming the same key cannot both win.
+
+For reference, the tables connecta creates:
+
+```sql
+CREATE TABLE IF NOT EXISTS connecta_kv (
+  key           TEXT PRIMARY KEY,
+  value         TEXT NOT NULL,
+  expires_at_ms INTEGER
+);
+CREATE INDEX IF NOT EXISTS connecta_kv_expiry ON connecta_kv (expires_at_ms);
+-- tool_call_activity: one row per completed call, keyset-paged on
+-- (occurred_at_ms, id); see src/storage/sql.ts in the package.
+```
 
-   Switching an existing deployment starts from empty state: downstream OAuth
-   connections must be re-authorized and vault credentials re-entered, because
-   nothing copies them out of the KV namespace.
+### Upgrading from 0.28
+
+0.28 shipped three storage shapes in this example. Each moves to the one
+`CONNECTA_DB` binding:
+
+- **Already on `d1-storage.ts`** (one D1 database, possibly also holding
+  activity). The table is unchanged, so no data moves. Rename the binding in
+  `wrangler.jsonc` to `CONNECTA_DB`, keeping `database_name` and
+  `database_id`, replace the copied `d1-storage.ts` / `d1-activity.ts` imports
+  with `@zackbart/connecta/d1`, and delete those files. A deployment that
+  called `pruneActivity` from a cron drops that call: retention is
+  `d1ActivityStore(db, { retentionDays })`. A binding rename
+  changes only the name the Worker sees; the database and its rows stay. An
+  existing `tool_call_activity` table missing `actor_namespace`, `friction`,
+  `approval`, `client_name`, `client_version`, or `package_version` gets nullable
+  columns added on first use. Old rows keep unknown package and client facts;
+  new rows record the actual package version and validated request client facts.
+- **Activity and storage in two databases** (`ACTIVITY_DB` and `STORAGE_DB`).
+  Bind the storage database as `CONNECTA_DB`. Activity is history: either
+  start it fresh in `CONNECTA_DB`, or copy it once, before deploying 0.29 (so
+  the target has no `tool_call_activity` table yet), with
+  `wrangler d1 export connecta-activity --remote --table tool_call_activity --output activity.sql`
+  and `wrangler d1 execute connecta-storage --remote --file activity.sql`. Then
+  remove the `ACTIVITY_DB` binding.
+- **Workers KV** (`CONNECTA_KV` and `cloudflare-kv.ts`). Workers KV is no longer
+  supported: `createConnecta` refuses storage without `compareAndSet` at boot.
+  Copy its state into D1 once, as described below, so OAuth grants, vault
+  credentials, and `cta_` access tokens keep working.
+
+#### 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,
+   including One&Many's `CONNECTA_CREDENTIALS_KEY`.
+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 `wrangler deploy` while maintenance remains.
+   Run `connecta doctor` 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.
 
-## Artifacts (optional)
+## Activity history (optional)
 
-`artifacts()` from `@zackbart/connecta/artifacts` adds the built-in `artifacts`
-connector: team pages whose data lives in versioned JSON documents. Every write
-commits by compare-and-set, so the store needs the D1 storage above — Workers
-KV is refused at construction. Artifacts share the `connecta_kv` table and need
-no schema of their own. Bodies (page sources and documents) can stay in D1 rows,
-which the default limits keep well under D1's row size, or go to R2 with
-`src/r2-artifact-blobs.ts`:
+`d1ActivityStore(env.CONNECTA_DB)` from `@zackbart/connecta/d1` is a complete
+`ActivityStore` in the same database — keyset paging on
+`(occurred_at_ms, id)`, its table created on first use. `src/connecta.config.ts`
+switches it on only when the `CONNECTA_ACTIVITY` var is `"on"`, because
+retention is the deployment's decision:
 
 ```ts
-import { artifacts, kvArtifactStore } from "@zackbart/connecta/artifacts";
-import { r2ArtifactBlobs } from "./r2-artifact-blobs.js";
-
-createConnecta({
-  // …
-  publicUrl: env.PUBLIC_URL, // required: artifact links are shared
-  artifacts: artifacts({
-    store: kvArtifactStore(d1Storage(env.STORAGE_DB), {
-      blobs: r2ArtifactBlobs(env.ARTIFACTS_BUCKET), // optional
-    }),
-  }),
-});
+activity: env.CONNECTA_ACTIVITY === "on"
+  ? activityHistory({
+      store: d1ActivityStore(env.CONNECTA_DB, { retentionDays: 90 }),
+      deploymentId: "production",
+    })
+  : undefined,
 ```
 
-For R2, create the bucket (`wrangler r2 bucket create connecta-artifacts`) and
-add `"r2_buckets": [{ "binding": "ARTIFACTS_BUCKET", "bucket_name":
-"connecta-artifacts" }]` to `wrangler.jsonc` and `ARTIFACTS_BUCKET: R2Bucket`
-to `Env`. Nothing ever deletes a body: versions are immutable, a rollback
-points back at an old one, and a body written by a write that lost a conflict
-stays stored unreferenced.
-
-To refresh pages, keep the module in a variable, pass it to `createConnecta`,
-and assign it to `scheduledArtifacts.module` as shown in `src/index.ts`.
-Uncomment the hourly cron in `wrangler.jsonc`. An hourly tick starts at most
-10 due pages; each page's `manual`, `daily`, or `weekly` schedule lives in its
-versioned refresh configuration. Refresh programs use only shared connectors'
-explicitly read-only tools within the program owner's current grants. Revoking
-refresh or pool access stops future runs. D1's compare-and-set prevents two cron invocations
-from claiming the same page. Failed runs keep the last good data and show a
-stale banner without exposing downstream error text to readers.
-
-## Activity history (optional)
-
-`src/d1-activity.ts` is a complete `ActivityStore` over D1 — keyset paging on
-`(occurred_at_ms, id)` plus a batched retention pass — but the wiring in
-`src/index.ts` is **commented out**, so the example deploys without a database.
-To enable it:
-
-1. Create the database and uncomment the `d1_databases` binding in
-   `wrangler.jsonc`, pasting in the id it prints:
-
-   ```sh
-   wrangler d1 create connecta-activity
-   ```
-
-   ```jsonc
-   "d1_databases": [
-     { "binding": "ACTIVITY_DB", "database_name": "connecta-activity", "database_id": "…" }
-   ]
-   ```
-
-2. Apply the schema (keep it in a deployment-owned `migrations/` directory):
-
-   ```sql
-   CREATE TABLE IF NOT EXISTS tool_call_activity (
-     id             TEXT PRIMARY KEY,
-     occurred_at_ms INTEGER NOT NULL,
-     request_id     TEXT NOT NULL,
-     actor_kind     TEXT NOT NULL,
-     actor_id       TEXT,
-     actor_namespace TEXT,
-     connector_id   TEXT NOT NULL,
-     tool_name      TEXT NOT NULL,
-     source         TEXT NOT NULL,
-     outcome        TEXT NOT NULL,
-     duration_ms    INTEGER NOT NULL,
-     attempts       INTEGER NOT NULL,
-     error_code     TEXT,
-     friction       TEXT,
-     approval       TEXT,
-     server_name    TEXT NOT NULL,
-     server_version TEXT NOT NULL,
-     deployment_id  TEXT
-   );
-
-   CREATE INDEX IF NOT EXISTS tool_call_activity_recent
-     ON tool_call_activity (occurred_at_ms DESC, id DESC);
-   ```
-
-   **Already have this table?** `actor_namespace`, `friction`, and `approval`
-   were added after the original example, and `CREATE TABLE IF NOT EXISTS`
-   will not add them to a table that already exists. Add them as migrations:
-
-   ```sql
-   ALTER TABLE tool_call_activity ADD COLUMN actor_namespace TEXT;
-   ALTER TABLE tool_call_activity ADD COLUMN friction TEXT;
-   ALTER TABLE tool_call_activity ADD COLUMN approval TEXT;
-   ```
-
-   `approval` is history: it is set only on an `approved` row written before
-   0.28.0 removed program pauses — the scope a resumed program's approval
-   covered, `call` or `tool` — and is null on every row since. Keep the
-   column; the Activity tab still renders those older rows.
-
-   `friction` is stored rather than derived because one of its classes belongs
-   to a call that *succeeded*: a result too large to return inline is friction
-   for the agent and carries no error code. Rows written before the column keep
-   working — the mapping module derives their friction from `error_code` — and
-   `error_code IS NOT NULL` remains an honest count of failures.
-
-   Do this **before** deploying the updated `d1-activity.ts`: its `INSERT`
-   names the column, so against an un-migrated table every write fails with
-   `no such column`. Activity writes are best-effort by design — connecta logs
-   the failure and returns the tool result unharmed — so the symptom is not an
-   error your agent sees, it is an activity log that quietly stops recording.
-
-3. In `src/index.ts`, enable the `activityHistory` and `d1ActivityStore` imports,
-   the `ACTIVITY_DB` field on `Env`, and the `activity` option:
-
-   ```ts
-   import { activityHistory } from "@zackbart/connecta/activity";
-   import { d1ActivityStore } from "./d1-activity.js";
-
-   createConnecta({
-     // …
-     activity: activityHistory({
-       store: d1ActivityStore(env.ACTIVITY_DB),
-       deploymentId: "production",
-     }),
-   });
-   ```
-
-Events carry no arguments, results, generated code, or raw error messages.
-The Worker entrypoint already forwards `ctx` to `connecta.fetch`, which lets
-async activity writes settle on `waitUntil`.
-
-For retention, add a
-[Cron Trigger](https://developers.cloudflare.com/workers/configuration/cron-triggers/)
-(`triggers.crons` in `wrangler.jsonc` plus a `scheduled` handler — this example
-no longer ships one) and call `pruneActivity(env.ACTIVITY_DB, retentionDays)`
-from it.
+Each write prunes a bounded batch of rows older than `retentionDays` (90 by
+default), so no Cron Trigger is needed; change the number there. Events carry no arguments, results, generated code,
+or raw error messages. The Worker entrypoint already forwards `ctx` to
+`connecta.fetch`, which lets async activity writes settle on `waitUntil`.
+
+`friction` is stored rather than derived because one of its classes belongs to
+a call that _succeeded_: a result too large to return inline is friction for
+the agent and carries no error code. Rows written before the column derive
+their friction from `error_code`, and `error_code IS NOT NULL` remains an
+honest count of failures. `approval` is history, set only on `approved` rows
+written before 0.28.0 removed program pauses.
+
+Activity uses `d1ActivityStore` and the shared SQL row mapping. On first access,
+it adds nullable classification, result byte count, event kind, catalog-change
+counts, pool and actor-basis columns. Existing rows retain unknown facts. Personal
+rows require the checked `principal` actor basis before their ownership is trusted.
+Request IDs already
+exist in the table. Catalog-change events contain checked counts only; tool-call
+results and payloads are never stored.