@zackbart/connecta 0.24.3 → 0.25.0

package/ethos.md

@@ -4,92 +4,89 @@ Connecta’s scope, refusals, and invariants. Contradictions require a design de
 
 ## What this is
 
-- **One MCP endpoint.** Agents reach configured connectors through JavaScript
-  and seven meta-tools. Every deployment requires an executor.
-- **Config-as-code.** One tenant and connector set; identities receive
-  config-derived views. Maintained providers, `remoteMcp()`, and `api()` obey
-  the same connector contract.
-- **Safe by default.** Only explicitly read-only tools run inside a program.
-  Others cross `call_destructive_tool`; the host owns human approval.
-- **One fetch-native core.** Web APIs support Node and Workers. Platform code
-  and optional features use explicit subpath imports.
+- **One MCP endpoint.** Agents reach configured connectors through JavaScript,
+  a required executor, and seven meta-tools, eight planned.
+- **Config-as-code.** One tenant and connector set; identities get
+  config-derived views. Maintained providers, `remoteMcp()`, and `api()` share
+  one connector contract.
+- **Safe by default.** Programs run only explicitly read-only tools unasked;
+  others cross `call_destructive_tool` or, planned, pause. The host owns approval.
+- **One fetch-native core.** Web APIs on Node and Workers; platform code and
+  optional features behind explicit subpaths; Effect inside, Promises outside.
 - **Human auth management.** Optional pages show status and payload-free history.
   Explicit permissions allow credential changes and OAuth. Capabilities stay in code.
 
 ## What this isn't
 
-No runtime registration, admin-editable capabilities, policy engine, approvals,
-or pauses. No schema ingestion, accounts, groups, protocol sessions, or server
-push. Inbound providers own identity; personal state remains within one tenant.
-Credentials fail at use, without background probes. Breaking changes remain
-acceptable; version numbers signal change, not stability.
+No runtime registration, admin-editable capabilities, or policy engine; config
+may only exempt a tool from asking. No schema ingestion, accounts, or groups;
+personal state remains within one tenant. Breaking changes remain acceptable;
+version numbers signal change, not stability.
 
 ## Decisions
 
 Revisiting a verdict requires a new argument. Accepted designs live in
-subsystem guides and the CHANGELOG.
+subsystem guides and the CHANGELOG; `planned` ones bind review before either
+carries them.
 
 | Decision | Verdict | Why |
 | --- | --- | --- |
-| OpenAPI / GraphQL ingestion | refused | the disease is a tool nobody chose — a document authored it; hand-written literals, even through a shared factory, are still authorship |
+| OpenAPI / GraphQL ingestion | refused | the disease is a document-authored tool nobody chose; hand-written literals, even through a shared factory, are still authorship |
 | Multi-tenancy / account model | refused | one deployment per tenant; inbound auth owns identity |
-| Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
+| Approvals and pauses | planned | a program pauses host-side at its first unapproved write until the destructive-annotated `resume_execution` repeats that exact call, the host's prompt approving it or its tool; an expiring journal replays the run, never re-sending unknown outcomes |
 | Runtime connector registration | refused | config-as-code is the security model |
-| Optional deployment modules | accepted | explicit imports and typed config slots select UI, activity history, credential vault, and inbound auth; discovery, execution, invocation, and enforcement stay in core |
-| Generic plugin lifecycle or marketplace | refused | modules organize deployment code; runtime installation and discovery add no required behavior |
-| Connecta-issued access tokens | removed | inbound identity providers own client authentication; configured bearer auth remains an optional adapter |
-| Provider registry / marketplace | refused | prebuilt connections are imports; discovery happens in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| Optional deployment modules | accepted | typed slots select UI, activity, vault, and inbound auth; core keeps discovery, execution, invocation, and enforcement |
+| Artifacts module | planned | a built-in connector, not a meta-tool: team-only sandboxed pages over stored JSON, never calling tools. Immutable versions let writes skip approval. Supersedes [#287](https://github.com/zackbart/connecta/issues/287) on executor's artifacts |
+| Plugin lifecycle, provider registry, or marketplace | refused | modules are deployment code, not runtime installs; prebuilt connections are imports, discovered in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| Connecta-issued access tokens | removed | inbound providers authenticate clients; bearer auth stays an optional adapter |
 | Expanded Notion page create/update options | refused | different workflows, not missing fields; use `api()` ([#408](https://github.com/zackbart/connecta/issues/408)) |
-| Protocol sessions & server push | refused | stateless per request |
-| Resources & prompts aggregation | refused | tools only; clients own presentation ([#266](https://github.com/zackbart/connecta/issues/266)) |
-| Elicitation passthrough | refused | no route through a stateless aggregator |
+| Resources, prompts, and downstream MCP Apps templates | refused | tools only; clients own presentation ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Protocol sessions, server push, elicitation passthrough | refused | stateless per request; elicitation has no route |
 | Repository formatter | refused | style is authored, not enforced |
-| Host-side projection of program results | refused | a program projects; a heuristic drops fields invisibly ([#223](https://github.com/zackbart/connecta/issues/223)) |
-| `get_result` paging for program results | refused | paging rewards the unprojected return code mode exists to remove ([#223](https://github.com/zackbart/connecta/issues/223)) |
+| Host-side projection or paging of program results | refused | a program projects: heuristics drop fields invisibly, paging rewards unprojected returns ([#223](https://github.com/zackbart/connecta/issues/223)) |
 | Native Tasks for oversized results | refused | tasks solve duration, `get_result` solves size ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Widening the `Executor` result contract | refused | `{ result, error?, logs? }` is the `@cloudflare/codemode` parity guarantee ([#267](https://github.com/zackbart/connecta/issues/267)) |
-| Erasable TypeScript in `execute_code` | refused | 24 MB dependency in the core, no measured agent benefit ([#419](https://github.com/zackbart/connecta/issues/419)) |
-| Guest-minted `resource` / `resource_link` blocks | refused | a program can never mint a URI a client may dereference ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Erasable TypeScript in `execute_code` | refused | a 24 MB core dependency, no measured agent benefit ([#419](https://github.com/zackbart/connecta/issues/419)) |
+| Guest-minted `resource` / `resource_link` blocks | refused | no program mints a URI a client may dereference ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Provenance tracking for emitted content | refused | everything a program emits is program output ([#267](https://github.com/zackbart/connecta/issues/267)) |
-| Result sampling on the catalog surface | refused | sampling is execution and cannot ride a catalog read ([#282](https://github.com/zackbart/connecta/issues/282)) |
+| Result sampling on the catalog surface | refused | sampling is execution, not a catalog read ([#282](https://github.com/zackbart/connecta/issues/282)) |
 | Legacy embedded `UIResource` delivery | refused | superseded upstream, rendered by no client we face ([#266](https://github.com/zackbart/connecta/issues/266)) |
-| Effect as the core effect system | refused | −4% of the core for +75 KB gzip and a second async paradigm; re-measure at v4 stable ([#470](https://github.com/zackbart/connecta/issues/470)) |
-| Shared bounded queue under both admission controllers | refused | built and measured −17 lines for a hook-parameterised abstraction ([#453](https://github.com/zackbart/connecta/issues/453)) |
+| Effect as the core effect system | accepted | lifetimes held the bugs: the rewrite closed leaked permits, hung waits, and cross-request races. Overturns [#470](https://github.com/zackbart/connecta/issues/470) |
+| Shared bounded queue under both admission controllers | refused | built: −17 lines bought a hook-parameterised abstraction ([#453](https://github.com/zackbart/connecta/issues/453)) |
 | MCP Apps rendering and `connecta.ui` | removed | clients render returned data |
 | Connector shortcut globals | removed | canonical addresses need no sanitization |
 | `connecta.batch` | removed | JavaScript promises suffice |
 | Automatic direct-call retries | removed | callers own retry timing |
-| Connector HTTP routes | removed | deployments own custom routes |
-| Caller-selected toolkits | removed | config derives every view; config-declared, grant-gated pools at `/mcp/<pool>` are not caller-selected ([#178](https://github.com/zackbart/connecta/issues/178), [#531](https://github.com/zackbart/connecta/issues/531)) |
+| Connector HTTP routes | removed | deployments own custom routes; artifact viewing is the planned exception |
+| Caller-selected toolkits | removed | config derives every view, grant-gated `/mcp/<pool>` pools included ([#178](https://github.com/zackbart/connecta/issues/178), [#531](https://github.com/zackbart/connecta/issues/531)) |
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
 | Classic (executor-free) surface | removed | an executor is mandatory ([#273](https://github.com/zackbart/connecta/issues/273)) |
-| Per-result lexical query coverage | removed | did not earn its response bytes in a precommitted gate ([#323](https://github.com/zackbart/connecta/issues/323)) |
-| Stabilized workflows | gated | needs programs that actually recur ([#225](https://github.com/zackbart/connecta/issues/225)) |
+| Per-result lexical query coverage | removed | failed a precommitted response-bytes gate ([#323](https://github.com/zackbart/connecta/issues/323)) |
+| Stabilized workflows | planned | only as artifact refresh: scheduled read-only programs, shared credentials ([#225](https://github.com/zackbart/connecta/issues/225)) |
 | Semantic tool search | gated | keyword search has not been shown to fail ([#27](https://github.com/zackbart/connecta/issues/27)) |
 | MRTR / `input_required` passthrough | gated | relayable statelessly; no host or downstream emits it yet ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Downstream `ttlMs` cache hints | gated | needs refresh-churn evidence ([#206](https://github.com/zackbart/connecta/issues/206)) |
-| Downstream MCP Apps template passthrough | refused | clients own presentation; Connecta serves tools and data |
 | Worker Access inbound auth | provisional | Managed OAuth and Clerk migration need production evidence ([#506](https://github.com/zackbart/connecta/issues/506)) |
 | Program UI tool calls | removed | duplicated calls without improving retrieval ([#287](https://github.com/zackbart/connecta/issues/287), [#484](https://github.com/zackbart/connecta/issues/484)) |
 
 ## Invariants
 
-Tests beside subsystem documentation enforce these invariants. Breaking one
-requires a design decision.
+Tests beside subsystem documentation enforce these; breaking one requires a
+design decision.
 
 - **Fail-closed read-only.** A missing, false, or contradictory annotation never gets the benefit of the doubt.
 - **Generated code cannot mint capabilities.** Admission, credentials, and classification are enforced below the sandbox.
-- **Only explicitly read-only work runs inside the sandbox.** Everything else crosses `call_destructive_tool`.
-- **Nothing request-bound survives a request.** No transport, stream, signal, or awaited promise outlives it.
-- **A downstream catalog is complete or it is a failure.** A partial catalog is never cached, persisted, or served.
+- **Only explicitly read-only work runs unasked in the sandbox.** Everything else crosses `call_destructive_tool` or, planned, `resume_execution` or a config exemption.
+- **Nothing request-bound survives a request.** No transport, stream, signal, or awaited promise outlives it; a paused journal is data, not a request.
+- **A downstream catalog is complete or it is a failure.** A partial one is never cached, persisted, or served.
 - **Activity is payload-free by construction.** The event type has nowhere to put arguments, results, code, or raw errors.
 - **An observed shape is never a declaration.** Names and broad types only, labeled, and gone behind any declared schema.
-- **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector and, for personal auth, its owning principal; rendered by nothing.
-- **Import-graph purity.** Nothing reachable from the root entry imports a `node:` builtin.
-- **The published surface is a boundary.** Heavyweight or platform-bound code goes behind an optional-peer subpath.
-- **Human routes manage auth, never capability.** Visibility grants use, not credential administration. Shared and personal auth mutations require separate config-derived permissions, both denied by default. Activity has its own read permission.
-- **Omitted modules do no work.** Core imports no UI bundle, encrypted vault implementation, activity implementation, or bearer adapter. OAuth callbacks remain available without UI.
-- **Status reads do not start authorization.** OAuth starts through an explicit authorized action; loading the UI never creates a consent flow.
+- **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector (and principal, for personal auth), rendered by nothing.
+- **Import-graph purity.** Nothing reachable from the root entry imports a `node:` builtin or `effect/testing`.
+- **The published surface is a boundary.** Heavyweight or platform-bound code goes behind an optional-peer subpath; Effect is the one hard dependency, named by no published type.
+- **Human routes manage auth, never capability.** Visibility grants use, not administration. Shared and personal auth mutations need separate config-derived permissions, both denied by default, and activity reads their own. Planned: viewing artifacts.
+- **Omitted modules do no work.** Core imports no UI bundle, vault, activity, or bearer implementation. OAuth callbacks work without UI.
+- **Status reads do not start authorization.** Only an explicit authorized action starts OAuth, never a page load.
 - **Structural mistakes throw at construction.** Booting into the wrong shape is worse than not booting.
 
 Connecta simplifies [executor](https://github.com/UsefulSoftwareCo/executor).

package/examples/worker/AGENTS.md

@@ -37,7 +37,8 @@ This repository is deployment configuration, not a copy of Connecta itself.
   A configured Connecta bearer cannot cross the Access edge alone. Connecta-issued
   tokens are removed. UI, vault, and activity use explicit optional imports;
   auth changes require code-derived shared or personal management permissions.
-- Run the repository's `npm run check:examples` after configuration changes.
+- After configuration changes, typecheck: inside the connecta repository that
+  is `npm run check:examples`; a copied deployment runs its own `tsc --noEmit`.
   After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and
   complete their browser authorization flows before calling setup complete.
 

package/examples/worker/README.md

@@ -8,7 +8,7 @@ Workers Paid plan.
 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
 owns only its connector configuration, auth policy, domain, bindings,
-migrations, and secrets. See [the Cloudflare guide](../../documentation/cloudflare.md).
+migrations, and secrets.
 
 ## Files
 
@@ -16,15 +16,18 @@ migrations, and secrets. See [the Cloudflare guide](../../documentation/cloudfla
 | --- | --- |
 | `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 |
 | `wrangler.jsonc` | Worker name, vars, bindings, `compatibility_flags` |
 
-`cloudflare-kv.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 when
-OAuth disconnect, credential rotation, or access-token issuance/revocation must
-become globally visible immediately.
+`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.
 
 ## Deploy
 
@@ -144,9 +147,12 @@ See [inbound identity](../../documentation/auth.md#principals-visibility-and-ope
 ### UI and encrypted credentials
 
 Import `operatorUi` from `@zackbart/connecta/ui` and set `ui: operatorUi()`.
-Branding belongs in `operatorUi({ branding })`. Omit the import and option to
-serve no UI routes; OAuth callbacks still work in core for authorized
-interactive MCP callers.
+Branding belongs in `operatorUi({ branding })`, including `branding.theme`:
+`accent`, `radius`, `fontFamily`, `monoFamily`, and `colorScheme`. Every other
+color is mixed from those, so one accent themes the whole page. A value that
+fails its gate falls back to the default, and the startup warning names it. Omit
+the import and option to serve no UI routes; OAuth callbacks still work in core
+for authorized interactive MCP callers.
 
 Import `encryptedCredentialVault` from `@zackbart/connecta/credentials` and set
 `vault: encryptedCredentialVault(storage, env.CREDENTIAL_ENCRYPTION_KEY)` when
@@ -172,8 +178,7 @@ does not create credentials or permissions by itself.
 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. See the [migration guide](../../documentation/upgrading.md#0240-optional-modules)
-if an older deployment still issues tokens.
+alone.
 
 Activity uses `activityHistory({ store: d1ActivityStore(env.ACTIVITY_DB) })`
 from `@zackbart/connecta/activity`. Enable the database and bindings described
@@ -211,6 +216,50 @@ serves the seven-tool surface. Do not add `bindings`, `modules`, or
 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. **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);
+   ```
+
+   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.
+
 ## Activity history (optional)
 
 `src/d1-activity.ts` is a complete `ActivityStore` over D1 — keyset paging on
@@ -295,8 +344,7 @@ To enable it:
    });
    ```
 
-Events carry no arguments, results, generated code, or raw error messages — see
-[activity history](../../documentation/operator-ui.md).
+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`.
 

package/examples/worker/src/d1-storage.ts

@@ -0,0 +1,116 @@
+import type { KVStorage } from "@zackbart/connecta";
+
+/**
+ * KVStorage over a D1 database, with the atomic `compareAndSet` that Workers
+ * KV cannot offer. Apply the `connecta_kv` schema in README.md § "Strongly
+ * consistent storage" before first use.
+ *
+ * Every compare-and-set is a single SQL statement. D1 runs one database's
+ * statements one at a time against its primary, so the comparison and the
+ * write cannot interleave with another request's: of fifty concurrent claims
+ * on an absent key, exactly one changes a row.
+ *
+ * Expiry is judged by the Worker's clock at each call, the same `Date.now()`
+ * the core uses. An expired row reads as absent immediately and is removed
+ * physically by later writes, a bounded batch at a time, so no request starts
+ * a background job and no cron is required.
+ */
+export function d1Storage(db: D1Database): KVStorage {
+  // Every statement that tests liveness binds the current time as ?2.
+  const live = "(expires_at_ms IS NULL OR expires_at_ms > ?2)";
+  const expiresAt = (now: number, ttlSeconds?: number) =>
+    ttlSeconds ? now + ttlSeconds * 1000 : null;
+  const changed = (result: D1Result) => result.meta.changes > 0;
+  return {
+    async get(key) {
+      const row = await db
+        .prepare(`SELECT value FROM connecta_kv WHERE key = ?1 AND ${live}`)
+        .bind(key, Date.now())
+        .first<{ value: string }>();
+      return row?.value ?? null;
+    },
+    async set(key, value, opts) {
+      const now = Date.now();
+      await db.batch([
+        db
+          .prepare(
+            `DELETE FROM connecta_kv WHERE key IN (
+              SELECT key FROM connecta_kv WHERE expires_at_ms <= ?1 LIMIT 16
+            )`,
+          )
+          .bind(now),
+        db
+          .prepare(
+            `INSERT INTO connecta_kv (key, value, expires_at_ms)
+             VALUES (?1, ?2, ?3)
+             ON CONFLICT (key) DO UPDATE SET
+               value = excluded.value, expires_at_ms = excluded.expires_at_ms`,
+          )
+          .bind(key, value, expiresAt(now, opts?.ttlSeconds)),
+      ]);
+    },
+    async delete(key) {
+      await db.prepare("DELETE FROM connecta_kv WHERE key = ?1").bind(key).run();
+    },
+    async list(prefix) {
+      const { results } = await db
+        .prepare(
+          `SELECT key FROM connecta_kv
+           WHERE key >= ?1 AND substr(key, 1, length(?1)) = ?1 AND ${live}`,
+        )
+        .bind(prefix, Date.now())
+        .all<{ key: string }>();
+      // Sort in JavaScript: SQLite orders UTF-8 bytes, the contract orders
+      // the UTF-16 code units every other adapter sorts by.
+      return results.map((row) => row.key).sort();
+    },
+    async compareAndSet(key, expected, next, opts) {
+      const now = Date.now();
+      if (next === null && expected === null) {
+        // Nothing to write; the claim holds exactly when no live row exists.
+        const row = await db
+          .prepare(`SELECT 1 AS present FROM connecta_kv WHERE key = ?1 AND ${live}`)
+          .bind(key, now)
+          .first();
+        return row === null;
+      }
+      if (next === null) {
+        return changed(
+          await db
+            .prepare(
+              `DELETE FROM connecta_kv WHERE key = ?1 AND ${live} AND value = ?3`,
+            )
+            .bind(key, now, expected)
+            .run(),
+        );
+      }
+      const expiry = expiresAt(now, opts?.ttlSeconds);
+      if (expected === null) {
+        // Insert, or take over a row that has expired. A live row makes the
+        // upsert's WHERE false, so nothing changes and the claim is refused.
+        return changed(
+          await db
+            .prepare(
+              `INSERT INTO connecta_kv (key, value, expires_at_ms)
+               VALUES (?1, ?3, ?4)
+               ON CONFLICT (key) DO UPDATE SET
+                 value = excluded.value, expires_at_ms = excluded.expires_at_ms
+               WHERE connecta_kv.expires_at_ms IS NOT NULL
+                 AND connecta_kv.expires_at_ms <= ?2`,
+            )
+            .bind(key, now, next, expiry)
+            .run(),
+        );
+      }
+      return changed(
+        await db
+          .prepare(
+            `UPDATE connecta_kv SET value = ?4, expires_at_ms = ?5
+             WHERE key = ?1 AND ${live} AND value = ?3`,
+          )
+          .bind(key, now, expected, next, expiry)
+          .run(),
+      );
+    },
+  };
+}

package/examples/worker/src/index.ts

@@ -11,9 +11,9 @@ import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
  * wrangler.jsonc backs the seven-tool surface.
  *
  * The operator surface is wired here except for activity history, which needs
- * a database this example does not create for you: sign-in, the credential
- * vault, and access-token issuance are on, and activity is three commented
- * lines below. README.md § "The operator surface" walks through all four.
+ * a database this example does not create for you: sign-in and the credential
+ * vault are on, and activity is three commented lines below. README.md
+ * § "Select optional modules" walks through all three.
  *
  * Setup (this example has no package.json of its own — it self-references the
  * installed `@zackbart/connecta` package):
@@ -50,8 +50,8 @@ interface Env {
   CONNECTA_KV: KVNamespace;
   /**
    * Base64 32-byte AES key encrypting operator-managed credentials in KV.
-   * Unset means no vault: /credentials stays read-only and connecta says so at
-   * startup. Never put it in KV — it is what protects KV.
+   * Unset means no vault: credential management is unavailable in the operator
+   * UI. Never put it in KV, since it is what protects KV.
    */
   CREDENTIAL_ENCRYPTION_KEY: string;
   DOWNSTREAM_TOKEN: string;
@@ -90,22 +90,19 @@ function build(env: Env) {
     //   activityAccess: ({ id }) => id === "ACCESS_USER_UUID",
     // },
     // Connectors that declare a `credential` slot become editable by every
-    // signed-in human who can see that connector at /credentials, encrypted
-    // with this key before anything reaches KV. A saved replacement takes
+    // signed-in human who can see that connector, inside its connection on /,
+    // encrypted with this key before anything reaches KV. A saved replacement takes
     // effect on the next call — no redeploy, and no liveness probe:
     // credentials fail at use.
     //
-    // The key is the vault, not the page: /credentials is a list of connector
-    // slots, so it stays hidden until a connector declares one. Neither
-    // connector below does — Notion here carries a deployment-owned static
-    // header and echo has no secret at all — so this example ships the vault
-    // ready and the page empty. Declare a slot (see the commented shape on
-    // `echo`, or use a provider connector like `notion()`, which declares its
-    // own) and the page appears on the next load.
+    // The key is the vault, not the form: a credential form appears only on a
+    // connector that declares a slot. Neither connector below does — Notion
+    // here carries a deployment-owned static header and echo has no secret at
+    // all — so this example ships the vault ready and nothing to fill in.
+    // Declare a slot (see the commented shape on `echo`, or use a provider
+    // connector like `notion()`, which declares its own) and the form appears
+    // on the next load.
     vault: encryptedCredentialVault(storage, env.CREDENTIAL_ENCRYPTION_KEY),
-    // Eligible human operators can create named, revocable MCP Bearer tokens
-    // at /tokens. Under Worker-level Access those tokens are a rollback tool,
-    // not standalone edge credentials: Access still runs before connecta.
     ui: operatorUi(),
     identity: { credentialAdministration: () => "all", personalConnection: () => "all" },
     // Payload-free activity at /activity, off until a database exists to hold
@@ -124,8 +121,8 @@ function build(env: Env) {
           type: "headers",
           headers: { Authorization: `Bearer ${env.DOWNSTREAM_TOKEN}` },
           // The vault-backed alternative for a downstream that authenticates
-          // with a static key: the operator pastes it at /credentials and
-          // rotates it there, so no Worker secret holds it.
+          // with a static key: the operator manages it inside its connection
+          // in the operator UI, so no Worker secret holds it.
           //   type: "credential",
           //   credential: { label: "Notion internal integration token" },
         },
@@ -135,8 +132,8 @@ function build(env: Env) {
       }),
       api("echo", {
         description: "Echo — text transforms",
-        // What a vault-backed connector adds — an operator edits this slot at
-        // /credentials and the handler reads it with
+        // What a vault-backed connector adds — an operator edits this slot
+        // inside its connection in the operator UI and the handler reads it with
         // `await ctx.credential?.get()`, so the secret never lives in source
         // or in a Worker variable:
         //   credential: { label: "API token" },

package/examples/worker/wrangler.jsonc

@@ -27,15 +27,27 @@
     { "binding": "CONNECTA_KV", "id": "replace-with-kv-namespace-id" }
   ],
 
-  // Activity history. Create with `wrangler d1 create connecta-activity`,
-  // paste the id, apply the schema in README.md, then uncomment the matching
-  // lines in src/index.ts. Off by default so this example deploys without a
-  // database.
+  // D1 databases, off by default so this example deploys without one.
+  // Uncomment the array and keep the entries you use.
+  //
+  // ACTIVITY_DB: activity history. Create with `wrangler d1 create
+  // connecta-activity`, paste the id, apply the schema in README.md, then
+  // uncomment the matching lines in src/index.ts.
+  //
+  // STORAGE_DB: strongly consistent storage with compare-and-set, in place of
+  // CONNECTA_KV. Create with `wrangler d1 create connecta-storage`, paste the
+  // id, apply the schema in README.md § "Strongly consistent storage", then
+  // pass `d1Storage(env.STORAGE_DB)` as `storage` in src/index.ts.
   // "d1_databases": [
   //   {
   //     "binding": "ACTIVITY_DB",
   //     "database_name": "connecta-activity",
   //     "database_id": "replace-with-d1-database-id"
+  //   },
+  //   {
+  //     "binding": "STORAGE_DB",
+  //     "database_name": "connecta-storage",
+  //     "database_id": "replace-with-d1-database-id"
   //   }
   // ],
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.24.3",
+  "version": "0.25.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
@@ -116,7 +116,7 @@
     "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
     "build:operator-ui": "node scripts/build-operator-ui.mjs",
     "check:operator-ui": "node scripts/build-operator-ui.mjs --check",
-    "build": "npm run build:operator-ui && npm run clean && tsc -p tsconfig.build.json",
+    "build": "npm run build:operator-ui && npm run clean && tsc -p tsconfig.build.json && node scripts/prune-declarations.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.operator-ui.json --noEmit",
     "test": "vitest run",
     "test:browser:install": "playwright install chromium",
@@ -129,10 +129,16 @@
     "check:examples": "tsc -p tsconfig.template.node.json && tsc -p tsconfig.examples.worker.json",
     "check:security": "npm audit --omit=dev --audit-level=moderate",
     "check:package": "node scripts/check-package.mjs",
-    "load:admission": "npm run build && node eval/admission-load.mjs",
+    "check:declarations": "node scripts/check-declarations.mjs --dist .",
+    "check:bundle": "node scripts/bundle-size.mjs",
     "providers:check": "tsx scripts/drift-check.mjs --specs --docs",
     "drift:check": "tsx scripts/drift-check.mjs",
-    "check": "npm run check:docs && npm run check:operator-ui && npm run check:lint && npm run check:unused && npm run typecheck && npm run test && npm run build && npm run check:examples",
+    "eval:selftest": "tsx eval/selftest.ts",
+    "eval:agent": "tsx eval/run-agent.ts",
+    "eval:smoke": "tsx eval/run-smoke.ts",
+    "eval:perf": "tsx eval/run-perf.ts",
+    "eval:report": "tsx eval/report.ts",
+    "check": "npm run check:docs && npm run check:operator-ui && npm run check:lint && npm run check:unused && npm run typecheck && npm run test && npm run test:browser && npm run build && npm run check:declarations && npm run check:bundle && npm run check:examples",
     "release:check": "npm run check && npm run check:security && npm run check:package",
     "prepack": "npm run check"
   },
@@ -140,6 +146,7 @@
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/client": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
+    "effect": "4.0.0-rc.117",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/templates/node/.env.example

@@ -23,14 +23,14 @@ CONNECTA_STATE_FILE=
 # Each of these is read only once the matching block in src/index.ts is
 # uncommented. Setting one on its own changes nothing.
 
-# Operator sign-in with Clerk. Only a signed-in operator may write a credential
-# or issue an access token; the bearer above is a client key, not an admin key.
+# Operator sign-in with Clerk. Only a signed-in operator may write a
+# credential; the bearer above is a client key, not an admin key.
 # Also run `npm install @clerk/backend` — it is an optional peer.
 CLERK_PUBLISHABLE_KEY=
 CLERK_SECRET_KEY=
 
 # Credential vault. Base64-encoded 32-byte AES key encrypting the values an
-# operator saves at /credentials. Generate one with:
+# operator saves inside a connection on /. Generate one with:
 #   node -e "console.log(crypto.randomBytes(32).toString('base64'))"
 # Keep it here or in a secret store — never in the state file it protects, and
 # never in source control. Losing it makes stored credentials unreadable.

package/templates/node/AGENTS.md

@@ -19,7 +19,6 @@ This repository is deployment configuration, not a copy of Connecta itself.
   alone never grants it. Configured bearer auth is a client option, not a human
   management identity. Connecta-issued access tokens are removed.
   `src/file-activity.ts` remains the deployment-owned history store.
-
 - Run `npm run typecheck` after configuration changes. With the server running,
   run `CONNECTA_TOKEN=... npm run doctor` before calling setup complete.
 - `Dockerfile` and `docker-compose.yml` containerize *this* source; they are
@@ -27,9 +26,11 @@ This repository is deployment configuration, not a copy of Connecta itself.
   `src/index.ts`, never in a divergent container entrypoint.
 - Moving this deployment to a newer Connecta is its own procedure, and it is
   not a re-`init` — `connecta init` refuses to merge into an existing path on
-  purpose. Follow
-  [the upgrade guide](https://github.com/zackbart/connecta/blob/main/documentation/upgrading.md),
-  which also ships at `node_modules/@zackbart/connecta/documentation/upgrading.md`.
+  purpose. Bump the exact `@zackbart/connecta` pin in `package.json`, then read
+  the [changelog](https://github.com/zackbart/connecta/blob/main/CHANGELOG.md)
+  for every release in between — it also ships at
+  `node_modules/@zackbart/connecta/CHANGELOG.md`. Each release opens with what
+  breaks and what a deployment can ignore.
 
 Do not add alternate entrypoints, policy layers, generated connector catalogs,
 or runtime connector registration. Keep the deployment small enough to review

package/templates/node/README.md

@@ -74,7 +74,8 @@ connector where each person should connect their own downstream account.
 ### Credential vault
 
 Import `encryptedCredentialVault` from `@zackbart/connecta/credentials`, then
-set `vault: encryptedCredentialVault(storage, credentialKey)`. Set
+set `vault: encryptedCredentialVault(storage, credentialKey)` — `storage` is
+the `fileStorage` binding `src/index.ts` already passes to `createConnecta`. Set
 `CONNECTA_CREDENTIAL_KEY` to a base64 32-byte AES key:
 
 ```sh

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.24.3",
+    "@zackbart/connecta": "0.25.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {