@zackbart/connecta 0.16.0 → 0.17.0

package/documentation/upgrading.md

@@ -0,0 +1,478 @@
+# Upgrading an existing deployment
+
+For the agent working *inside* a generated deployment rather than inside this
+repository. You did not create this project, you cannot re-run `connecta init`
+over it, and the thing you are holding is two files' worth of the owner's
+intent wrapped in eight files of template that has moved on without it.
+
+The shape of the job is fixed by two facts. A deployment is
+[config-as-code](../ethos.md): `src/index.ts` is the product, everything around
+it is scaffolding. And `connecta init` **refuses to merge into an existing
+path** — deliberately, because an initializer that overwrites is an initializer
+that eventually overwrites a connector set. So an upgrade is not a re-init. It
+is: read what you have, bump the pin, reconcile the scaffolding against the
+current template with the deployment's own generation as the base, migrate what
+the release notes broke, and prove it with `connecta doctor`.
+
+Work on a branch. Every step below is reversible until you delete the old
+lockfile, and you want the diff reviewable by whoever owns this deployment.
+
+## Read what you have first
+
+Three questions, in order. Answer all three before editing anything — the
+second and third are what stop you from "restoring" a file the owner changed on
+purpose.
+
+### 1. What version is it pinned to
+
+```sh
+node -p "require('./package.json').dependencies['@zackbart/connecta']"
+```
+
+`init` writes that pin as an **exact** version, never a range, because the
+generated deployment and the package are separate release units
+([operations](./operations.md#deployment-as-a-release-unit)). So the pin is
+also a fact about history: it is the version of the CLI that generated this
+project, unless someone has bumped it since — which `package-lock.json` will
+tell you.
+
+```sh
+node -p "require('./package-lock.json').packages['node_modules/@zackbart/connecta'].version"
+```
+
+Pin and lockfile agreeing means nobody has touched the dependency by hand. They
+disagreeing is the first thing to reconcile, and the lockfile is usually the
+truth about what has actually been running.
+
+A deployment with no `@zackbart/connecta` entry at all, or one carrying a range
+(`^0.14.0`), was not produced by `connecta init` — treat it as the pre-template
+case below.
+
+### 2. Which template generation it came from
+
+The pin answers this, and the file layout corroborates it. Two generations
+exist so far:
+
+| Generation | Versions | Layout |
+| --- | --- | --- |
+| **pre-template** | before 0.10.2 | no `connecta init` existed; hand-written, or copied from the retired `examples/node` |
+| **A** | 0.10.2 – 0.15.1 | `.env.example`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `src/index.ts`, `tsconfig.json` |
+| **B** | 0.16.0 – 0.17.0 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
+
+Generation A is a decade in template years and identifying it precisely does
+not matter, because you are about to reconstruct it exactly rather than guess
+at it. What matters is the boundary: a project with no `Dockerfile` is a
+generation A project, and the whole container story is a change it has never
+seen.
+
+### 3. What this deployment changed
+
+Regenerate the deployment's *own* starting point and diff against it. `init`
+pins from the CLI package's version, so an old CLI reproduces its own
+generation byte for byte:
+
+```sh
+SCRATCH=$(mktemp -d)                                        # keep this shell
+(cd "$SCRATCH" && npx @zackbart/connecta@0.15.1 init base)  # ← the pin from step 1
+```
+
+`$SCRATCH` is the one scratch path for the whole upgrade — the reconcile step
+below generates the current template into it too, and every later command
+resolves against it. Run the rest from the deployment root:
+
+```sh
+diff -ru "$SCRATCH/base" . --exclude node_modules --exclude package-lock.json
+```
+
+Everything that differs is deployment-owned and survives this upgrade
+unconditionally. Everything identical is scaffolding you may replace without
+asking. Expect the interesting half to be:
+
+- **`src/index.ts`** — the connector set, `auth`, `storage`, `publicUrl`, and
+  whichever operator blocks were uncommented. This file is never overwritten,
+  only edited.
+- **`package.json`** — extra dependencies (`@clerk/backend` if operator
+  sign-in is on, provider SDKs the owner added, anything a handler imports)
+  and extra scripts.
+- **`.env.example` / deployment docs** — variables the owner's connectors read.
+- Whole files that are not in any generation: extra `src/*.ts` modules behind
+  `api()` handlers, CI workflows, infrastructure.
+
+Write the list down before you touch anything. You will use it twice: once to
+know what to preserve, once to know what to re-verify at the end.
+
+## The upgrade
+
+### Bump the pin and install
+
+```sh
+npm pkg set dependencies.@zackbart/connecta=0.17.0
+npm install
+```
+
+Exact, not a range. The reason `init` pins exactly applies just as much on the
+way up: a deployment whose connector safety classifications can move under it
+during an unrelated `npm install` is not reviewable.
+
+`quickjs-emscripten` is a direct dependency of the generated project and an
+optional peer of the package (`^0.32.0`), so npm will tell you if the pin the
+template ships has fallen out of range. Match the template's pin rather than
+inventing one. If operator sign-in is enabled, `@clerk/backend` (`^3.12.0`) is
+the other optional peer — also a direct dependency of the deployment, because
+optional peers never install with core.
+
+Do not run the build yet. Reconcile first, so a single typecheck answers for
+both the new package and the new scaffolding.
+
+### Reconcile the scaffolding
+
+Generate the *current* template beside the base you already made, into the same
+`$SCRATCH`:
+
+```sh
+(cd "$SCRATCH" && npx @zackbart/connecta@0.17.0 init current)
+```
+
+You now have a three-way merge with a real base: `$SCRATCH/base` is what this
+deployment started as, `$SCRATCH/current` is what `init` produces today, and the
+deployment is the third leg. For every file:
+
+| base vs current | deployment vs base | Do |
+| --- | --- | --- |
+| unchanged | unchanged | nothing |
+| unchanged | changed | keep the deployment's version |
+| changed | unchanged | take `$SCRATCH/current`'s version |
+| changed | changed | merge by hand — this is the only file class that needs judgment |
+
+`diff3` or `git merge-file` will do the mechanical part. From the deployment
+root, with the deployment's file first, the base second, and the current
+template third:
+
+```sh
+git merge-file -p src/index.ts "$SCRATCH/base/src/index.ts" \
+  "$SCRATCH/current/src/index.ts" > "$SCRATCH/merged-index.ts"
+```
+
+New files in `$SCRATCH/current` that exist in neither base nor deployment are
+pure additions — copy them in. For generation A that is the entire container story
+(`Dockerfile`, `docker-compose.yml`, `.dockerignore`) plus
+`src/file-activity.ts`.
+
+Two things are worth knowing before you accept the merge:
+
+- **`.env.example` is not decoration.** The 0.16.0 template ships
+  `CONNECTA_TOKEN=` **empty** on purpose: both Compose and `src/index.ts`
+  refuse to start until an operator sets it, where the old `replace-me` value
+  started a healthy, port-published deployment whose bearer token was a string
+  published in a public repository. Take the empty value. Adding the
+  deployment's own variables underneath is the merge; restoring a placeholder
+  bearer is not.
+- **`src/index.ts` is a merge, not a takeover.** What you are adopting from
+  `$SCRATCH/current` is the environment reading (`PUBLIC_URL`, `CONNECTA_STATE_FILE`,
+  treating empty as unset — that is what lets one source serve both `npm start`
+  and the container) and the commented operator blocks. What you are keeping is
+  every connector, every credential slot, every handler, and every operator
+  block this deployment had already uncommented. If a block is live here and
+  commented in the current template, live wins.
+
+`AGENTS.md` (and the `CLAUDE.md` symlink beside it) is the deployment's
+instruction file for the next agent. Take the current one, then re-append
+whatever the owner added — it is usually the only "template" file with real
+local content in it.
+
+### The pre-template case
+
+A deployment older than 0.10.2 has no base to diff against. Do not try to
+manufacture one. Instead:
+
+1. `SCRATCH=$(mktemp -d)`, then
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.17.0 init current)` — there is no
+   `base` leg here, only the current template to read from.
+2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
+   `src/index.ts`**.
+3. Port the deployment's existing configuration into the new `src/index.ts` by
+   hand, one connector at a time, reading each version boundary below as you
+   go.
+
+It is more work and it is honest work: a project of that vintage predates the
+executor requirement, the seven-tool surface, and the `api()` construction
+contract, so it needs a read anyway.
+
+## Version boundaries
+
+Only what breaks an existing deployment is listed. Everything else in
+[`CHANGELOG.md`](../CHANGELOG.md) is additive, and a boundary absent from this
+list is a boundary you can cross with a version bump. The sections run newest
+first, so cross them bottom-up: start at the oldest one still above this
+deployment's pin and work back up the page, because each boundary assumes the
+older ones are already done.
+
+### 0.16.1 → 0.17.0
+
+Two construction rules need a deployment check.
+
+**A Dynamic Worker executor is loader-only.** The supported construction is
+exactly:
+
+```ts
+new DynamicWorkerExecutor({ loader: env.LOADER })
+```
+
+Remove `bindings`, `modules`, or `globalOutbound` from that options object.
+Those fields grant guest code ambient configuration, code, or egress. This is
+the supported sandbox boundary rather than a new Connecta-side inspection of
+the third-party executor object. The shipped Worker example was already
+loader-only, and Node deployments use `quickJsExecutor()`, so neither needs a
+change (#390).
+
+**An explicit guide summary must fit discovery.** Connecta normalizes
+whitespace in `usageGuide.summary` and refuses registry construction when the
+result is longer than 120 characters. Shorten it to 120 characters or fewer,
+or omit it and let Connecta derive a bounded summary from the guide's opening
+prose. A blank explicit summary still takes the derived-summary path (#392).
+
+### 0.16.0 → 0.16.1
+
+Nothing throws, and a Node deployment crosses this on the version bump alone.
+The one thing that can stop the upgrade is npm, and only on a Worker:
+`@cloudflare/codemode` is now a declared optional peer at `^0.4.4 || ^0.5.0`,
+so a `package.json` holding it below that range fails `npm install` with an
+`ERESOLVE` conflict instead of installing. Move the pin into the range this
+release is tested against. Separately, `cloudflare()` no longer names
+`list_zone_settings` — read one setting with `get_zone_setting`, write one with
+`update_zone_setting` — and Cloudflare's 404 now arrives as `not_found` rather
+than `connector_call_failed`, which matters only to a program that branches on
+the code.
+
+### 0.15.x → 0.16.0
+
+The largest one, and it fails loudly. Every item here throws at construction or
+fails a specific call; none of it degrades quietly.
+
+**`api()` enforces its construction contract.** Every hand-written tool now
+needs three things, checked when the connector is built:
+
+- a non-empty `description` — it is what an agent reads to choose the tool;
+- an explicit boolean `annotations.readOnlyHint` — `true` for a read, `false`
+  for work that must cross `call_destructive_tool`;
+- an `inputSchema`, if it ships one, that the validator can actually compile.
+
+The throw names the failing address (`connectorId.toolName`), so this is a
+mechanical walk through `src/index.ts`. The one judgment call is the
+classification, and the safe answer is written down for you: **a tool that used
+to ship unannotated becomes `readOnlyHint: false`**, because unannotated
+already routed through `call_destructive_tool`. That is the routing it had.
+Writing `true` onto a tool you have not read is not an upgrade, it is a
+capability change.
+
+Connecta infers the classification from nothing — not a name, not a verb, not
+an HTTP method, not the other annotations. There is no flag that restores the
+old forgiving behavior.
+
+**`ApiOptions.strictValidation` is gone.** Delete it. Fail-closed schema
+handling is the only behavior left, so the option had nothing to switch. A
+schema that only reveals itself as unenforceable on first use — an unresolvable
+`$ref`, say — now fails that call as non-retryable `invalid_args` instead of
+forwarding raw arguments to the handler. `validateArgs: false` still exists and
+still means what it said: opting out of enforcement, not out of the schema
+being real.
+
+**`linear()` requires `access`.** Construction throws naming both options.
+`access: "read-write"` preserves an existing deployment's behavior exactly;
+`"read-only"` binds the connector to Linear's read-only endpoint, whose token
+cannot reach the write APIs at all. There is no default because neither guess
+is safe — one hands out writes nobody asked for, the other breaks a writing
+deployment at Linear, at runtime, where no agent can repair it
+([linear](./linear.md)).
+
+**`mixpanel()` declares no call-admission budget.** The old hardcoded 600
+calls/hour transcribed a limit Mixpanel meters *per user*, which a per-runtime
+counter cannot approximate in either direction. Nothing throws — the ceiling is
+simply absent. If this deployment was relying on it, pass `callAdmission`
+explicitly ([call admission](./call-admission.md)). The default title also now
+carries the region (`Mixpanel (us)`), and an unknown `region` throws.
+
+**Three Cloudflare tools are gone; the connection ships 52.** `set_r2_cors`,
+`delete_r2_cors`, and `get_r2_metrics`. Grep the deployment — and any prompt,
+skill, or runbook around it — for those names. No capability is lost:
+`get_r2_cors` still reads a bucket's policy, CORS writes go through
+`cloudflare_api_mutate` at
+`PUT`/`DELETE /accounts/{accountId}/r2/buckets/{bucketName}/cors`, and metrics
+through `cloudflare_api_get` at `/accounts/{accountId}/r2/metrics`
+([cloudflare](./cloudflare.md)).
+
+**`cloudflare()` checks an overridden `baseUrl` at construction.** A
+non-loopback plain-http origin, URL-embedded credentials, or a query or
+fragment now throws where the option is written rather than on the first call.
+A deployment pointing Cloudflare at an http proxy must move it to https or bind
+it to loopback. The default base is unaffected, so a deployment that never set
+`baseUrl` reads nothing here.
+
+**Cloudflare and Notion refuse redirects and bound their reads.** Both now send
+`redirect: "manual"`; a 3xx fails as non-retryable `connector_call_failed`
+rather than re-sending the connector's credential to whatever origin `Location`
+names. Both also cap the response they will read — 8 MiB for Cloudflare, 4 MiB
+for Notion — checked against a declared `Content-Length` and again while the
+body streams. Visible only to a deployment that was pulling something enormous
+through a tool call, such as a `cloudflare_api_get` on a large R2 object. These
+are ceilings on absurdity; anything near them was already past whatever
+`maxResultBytes` the deployment set.
+
+**The shipped defaults fail closed.** Covered under `.env.example` above, and
+repeated here because it is the item most likely to be "fixed" backwards: an
+empty `CONNECTA_TOKEN` that refuses to boot is the intended state of a fresh
+`.env.example`, not a regression.
+
+### 0.13.x → 0.14.x
+
+No API breaks. One behavior change worth knowing: vetted annotations on a
+prebuilt connection no longer argue with an explicit downstream annotation in
+either direction, so a name the downstream explicitly marks `readOnlyHint:
+true` that no release has classified is now callable from `execute_code`
+instead of failing closed onto the approval path. Silence on an unclassified
+name still means not read-only. The one branch that still outranks the
+downstream is a name a release reviewed and filed destructive.
+
+### 0.12.x → 0.13.0
+
+No API breaks; text changed under existing deployments. Served tool
+descriptions and the MCP `instructions` string were rewritten, and `skills({})`
+now summarizes a connector guide from its first body line rather than its
+heading — a guide opening `# Acme` that listed as "Acme" now lists as the
+sentence beneath it. If this deployment's connectors carry usage guides, read
+their first lines ([connector guides](./connector-guides.md)).
+
+### 0.10.x → 0.11.0
+
+The executor boundary. **Every deployment must configure an executor** and
+serves exactly seven tools; construction refuses to boot without one. On Node
+that is `quickJsExecutor()` from `@zackbart/connecta/quickjs`; on Workers,
+`new DynamicWorkerExecutor({ loader: env.LOADER })` from
+`@cloudflare/codemode` plus its paid-plan Worker Loader binding.
+
+The top-level `list_connectors`, `describe_tools`, and `batch_call`
+registrations are gone. Their equivalents live inside `execute_code` as
+`connecta.search`, `connecta.describe`, and `connecta.batch`
+([code mode](./code-mode.md)). Anything outside the deployment that called
+those three by name — a client config, a prompt, a script — is what actually
+breaks here; the deployment file itself only has to gain the executor and drop
+`surface`.
+
+### 0.6.x → 0.7.0
+
+Only a pre-template deployment is still down here; every generation A project
+was born above this line. Three breaks, and the config one is in the table
+below.
+
+**A connector implementing `finishAuth` without `verifyState` can no longer
+complete OAuth** (#62). The callback refuses with the same opaque 400 as every
+other refusal, exchanges no code, and logs one operator-grade line naming the
+connector and the missing hook. `verifyState` is optional in the type system and
+required in practice wherever `finishAuth` is present, so nothing throws at
+construction — the flow simply stops completing, which is the one item in this
+guide you find by reading rather than by building. It reaches hand-written
+connectors only: the shipped `remoteMcp` OAuth provider has always implemented
+it. The old behavior was exchanging an authorization code with no CSRF guard at
+all, so this is not a hook to stub out with `() => true`.
+
+**`/`, `/credentials`, and `/activity` are core-owned routes** (#57). They
+previously fell through to connector `handleRequest` and then to a 404, so a
+connector that served any of the three is now shadowed without warning. `GET /`
+returns the operator shell where 0.6.1 returned 404, and a non-GET on those
+routes or on `/ui` returns 405 instead of falling through. Move such a handler
+to a path the core does not own: `handleRequest` still runs for everything the
+built-in routes miss, so it can add a route and never shadow one
+([architecture](./architecture.md)).
+
+### Removed options that throw
+
+These fail at construction with their migration named rather than falling back
+to a default, because silently ignoring a removed option is how a deployment
+ends up running a policy its config file says it has:
+
+| Option | Removed in | Do |
+| --- | --- | --- |
+| `toolkits`, `unscoped` | 0.8.1 (#178) | delete; deploy one instance per audience |
+| `credentials.health`, `credentialHealth` | 0.8.1 (#179) | delete; credentials fail at use |
+| `surface` | 0.11.0 (#273) | delete; there is one seven-tool surface |
+| `calls.maxBatchResultBytes` | 0.11.0 (#273) | delete; program batching is bounded by `execute_code`'s own limits |
+| flat v0.6 config paths | 0.7.0 | move into their groups — one complete migration error lists them ([operations](./operations.md#configuration)) |
+
+## Verify
+
+In order, and do not skip the last one — the first three prove the package
+works, not that this deployment does.
+
+```sh
+npm run typecheck                      # ships with the template
+CONNECTA_TOKEN=dev-token npm start     # in one shell
+CONNECTA_TOKEN=dev-token npm run doctor    # in another
+```
+
+`connecta doctor` is the gate. It asserts `/health` reports ok, that
+`tools/list` is exactly the seven prescribed names — `authorize_connector`,
+`call_destructive_tool`, `call_tool`, `execute_code`, `get_result`,
+`search_tools`, `skills` — and that `execute_code` actually runs a program in
+the sandbox. It names the executor the deployment reports rather than assuming
+one: `QuickJS executed` on the Node template, `DynamicWorkerExecutor executed`
+on a Worker. It also *reports* catalog drift without failing on it; drifted
+counts here are a maintainer's next task, not a failed upgrade.
+
+Then exercise this deployment's own connectors, which doctor knows nothing
+about — it holds a bearer, and a client key does not get to learn a
+deployment's configuration topology. One program covers discovery and a call:
+
+```js
+// execute_code — an empty query browses the catalog
+async () => {
+  const page = await connecta.search({ query: "", limit: 100 });
+  return {
+    total: page.total,
+    connectors: [...new Set(page.tools.map((t) => t.address.split(".")[0]))],
+  };
+};
+```
+
+Walk the list from the inventory you wrote down: every connector the owner
+configured should appear, every credential slot should still be listed at
+`/credentials`, and at least one real read per connector should return data.
+A connector whose catalog is empty after an upgrade is usually a credential
+that did not survive a state-file path change, not a broken release.
+
+If the container half is now in play, `cp .env.example .env`, set
+`CONNECTA_TOKEN`, and `docker compose up -d --build`, then point doctor at it.
+Commit the `package-lock.json` that `npm install` wrote on the host — that is
+what puts the image build on the reproducible `npm ci` path instead of
+resolving the pin again inside a layer.
+
+## What not to do
+
+Five refusals. Each one is somebody's plausible shortcut, and each one produces
+a deployment that is quieter and wrong.
+
+- **Do not re-init over the top.** `connecta init` refuses to merge into an
+  existing path and that refusal is load-bearing. Working around it — into a
+  scratch directory and then `cp -r` over the deployment, or by deleting the
+  project and regenerating — is how a connector set becomes a `time` connector.
+  Scratch directories are for reading and diffing, never for copying wholesale.
+- **Do not weaken a fail-closed default to get green.** `readOnlyHint: true` on
+  a tool you have not read, a restored `CONNECTA_TOKEN=replace-me`,
+  `validateArgs: false` to silence a schema that will not compile, an
+  annotation "corrected" to match what the downstream claims: all of these turn
+  a construction error into a running deployment with a wider blast radius than
+  it had yesterday. The construction throw is the feature. Fix the input.
+- **Do not pin back.** A deployment that boots on 0.15.1 and throws on 0.16.0
+  is a deployment telling you which line to fix, with the address in the error
+  message. Reverting the pin keeps the same defect and buries the report.
+- **Do not copy Connecta internals into the deployment.** If something the
+  deployment needs is not exported, that is a package issue to file, not a file
+  to vendor. A deployment that carries a copy of a provider cannot be upgraded
+  by anyone, including you, next time.
+- **Do not add a second project shape.** No alternate entrypoint, no second
+  container recipe, no parallel configuration path beside `src/index.ts`. There
+  are exactly two deployment shapes — [`templates/node/`](../templates/node/)
+  and the Worker example — and a third that is a diff away from one of them is
+  a shape this repository has already deleted once.
+
+When something here disagrees with [`ethos.md`](../ethos.md), the ethos wins
+and this guide is what needs fixing.

package/ethos.md

@@ -49,8 +49,8 @@ order, and amending it is a design decision, not a drive-by edit.
   changes declared capability, no policy engine, no approvals, no pauses.
 - **Not a schema ingester.** No OpenAPI or GraphQL → tools. Generated tool
   sprawl is the disease the meta-tools treat, not a feature to add.
-- **Not multi-tenant.** No accounts dimension, no per-user credential store,
-  no org hierarchy. Two accounts on one service are two connector instances.
+- **Not multi-tenant.** No Connecta account model, per-user credential store, or org hierarchy; credentials, storage, admission, and health stay connector-scoped.
+  Provider-owned sessions may expose provider-native account scope only through live schemas. Metadata never proves account identity; Connecta never invents or normalizes selectors, and ambiguity stops.
 - **Not stateful.** No protocol sessions, no server push. Scope resolves per
   request — which is also where the MCP spec itself has now arrived.
 - **Not a nanny.** Credentials fail loudly at use; connecta never probes one.
@@ -84,7 +84,7 @@ proposing one without a new argument is not.
 | Operator boundary reworded: authentication material, never declared capability | accepted | supersedes "observable, never administrable", which had stopped describing the surface: operator routes already rotate credentials, issue and revoke access tokens, and drive downstream OAuth, each under its own accepted row, and the owner has decided the surface stays actionable — so the boundary now says what is actually true, that operator routes may manage authentication material for capabilities declared in deployment configuration and may not change the connector set, the declared tool catalog or annotations, requested OAuth scopes, admission policy, authorization rules, or caller tool scope; the claim is deliberately about *declared* capability, and twice so, because replacing an API token with a broader-scoped one widens downstream reach and no browser page can honestly promise otherwise, and because a remote MCP server's catalog is discovered rather than declared — connecta declares the connector, its credential slot, and its admission policy, while the tools that server serves are its own answer, so storing a credential or finishing an OAuth flow can legitimately take an `mcp()` connector from no tools to N, which is discovery arriving, not an operator editing the deployment ([#338](https://github.com/zackbart/connecta/issues/338)) |
 | Structured result surface | accepted | canonical `structuredContent` plus complete compact `content`; summary-only text is gated on host-forwarding evidence ([#191](https://github.com/zackbart/connecta/issues/191)) |
 | Code mode (`execute_code`) | accepted | the primary read, discovery, and composition surface: smaller serialized definitions, far smaller results once composition and projection happen before the model sees them, and a cold-start model that read the interface without help ([exploration](./documentation/code-first-exploration.md), [#224](https://github.com/zackbart/connecta/issues/224)) |
-| Code-first as the default; the eval gate retired | accepted | owner decision, 2026-07-30: one operator, no deploy-time flip; [`eval/code-first-gate`](./eval/code-first-gate/README.md) survives as measurement, but nothing waits on its verdict ([#222](https://github.com/zackbart/connecta/issues/222), [#224](https://github.com/zackbart/connecta/issues/224)) |
+| Code-first as the default; the eval gate retired | accepted | owner decision, 2026-07-30: one operator, no deploy-time flip; [`eval/code-first-gate`](https://github.com/zackbart/connecta/blob/main/eval/code-first-gate/README.md) survives as measurement, but nothing waits on its verdict ([#222](https://github.com/zackbart/connecta/issues/222), [#224](https://github.com/zackbart/connecta/issues/224)) |
 | Surface consolidation to seven tools | accepted | `list_connectors`, `describe_tools`, and `batch_call` fold into the program surface, deleting the routing choice between direct calls, batches, discovery, and execution; `call_tool` stays because a simple call is not cheaper through code ([#224](https://github.com/zackbart/connecta/issues/224)) |
 | Classic (executor-free) surface | removed | supersedes its provisional retention under [#224](https://github.com/zackbart/connecta/issues/224) — an executor is mandatory, and a deployment without one refuses to boot rather than serving a fallback shape ([#273](https://github.com/zackbart/connecta/issues/273)) |
 | Connector shortcut namespaces in programs | accepted | sugar over canonical addressing, kept but frozen — every expansion invents a collision class `<connectorId>.<toolName>` already solved ([#223](https://github.com/zackbart/connecta/issues/223)) |
@@ -97,6 +97,7 @@ proposing one without a new argument is not.
 | MRTR / `input_required` passthrough | gated | statelessly relayable via `requestState`, but no host or downstream emits it yet; fails loudly until adoption evidence ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Native Tasks for oversized results | refused | tasks solve duration, `get_result` solves size; paging on a polling extension adds round trips for nothing ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Downstream `ttlMs` cache hints | gated | fixed TTL + fingerprint is battle-tested and catalog reads are ~3 ms; earns its way in with refresh-churn evidence ([#176](https://github.com/zackbart/connecta/issues/176)) |
+| Inbound-demand catalog stale-while-revalidate | accepted | an agent-facing catalog read may return a complete, fingerprint-verified entry inside its configured stale window and move the refresh that same read demanded onto the runtime's existing deferred-work channel; this originates no timer, schedule, warmup, or credential probe, and operator status remains blocking — one refresh per connector is shared across agent and operator requests, a deferred owner uses a fresh bounded signal and connector scope and closes that scope, and invalidation is rechecked before stale publication, so no request-bound capability survives and no partial or pre-invalidation catalog gains authority ([#396](https://github.com/zackbart/connecta/issues/396)) |
 | Rich program output (`connecta.emit`) | accepted | one host-collected emission channel: programs emit strictly validated text/image/audio blocks, delivered after the result envelope on success only; budgets fail loudly at the emit call ([design record](./documentation/rich-output-design.md), [#267](https://github.com/zackbart/connecta/issues/267)) |
 | Result-channel widening of the `Executor` contract | refused | `ExecuteResult` stays `{ result, error?, logs? }` — structural compatibility with `@cloudflare/codemode` is the parity guarantee; emission rides the provider bridge instead ([#267](https://github.com/zackbart/connecta/issues/267)) |
 | Guest-emitted `resource` / `resource_link` blocks | refused | a program can never mint a URI a client may dereference, and the carve-out this row waited on does not need one: `connecta.ui` takes HTML content, and the only `ui://` URI is connecta's build-time shell ([design record](./documentation/mcp-ui-design.md), [#266](https://github.com/zackbart/connecta/issues/266), [#267](https://github.com/zackbart/connecta/issues/267)) |
@@ -108,7 +109,6 @@ proposing one without a new argument is not.
 | View-initiated mutation calls from program UI | gated | live-read utility says nothing about write consent: a click is not approval, stale/replayed effects need a host-tested story, and the ordinary destructive path keeps the action in the transcript ([#287](https://github.com/zackbart/connecta/issues/287)) |
 | Result sampling on the catalog surface (`sample` / `dryRun`) | refused | sampling is execution and cannot ride a catalog read; most tools carry required arguments no sampler can invent, and undeclared `outputSchema` (measured 0/30 and 3/30 on real deployments) is a real gap that is not a sampleable one — a program that checks the shape before rendering already hands back the first record inside the run it was going to make anyway, at zero new surface ([#282](https://github.com/zackbart/connecta/issues/282)) |
 | Legacy embedded `UIResource` delivery | refused | superseded upstream and rendered by none of the clients connecta faces; per-request minted URIs also fight the caching the Apps spec assumes ([#266](https://github.com/zackbart/connecta/issues/266)) |
-
 ## Invariants
 
 One line each; the enforcing tests live beside the subsystem documentation.

package/examples/worker/README.md

@@ -60,9 +60,15 @@ things, because two of them are not part of connecta and never install with it:
 npm install @zackbart/connecta @cloudflare/codemode @clerk/backend
 ```
 
-`@cloudflare/codemode` is the executor behind `execute_code`, and
-`@clerk/backend` is the optional peer behind `@zackbart/connecta/auth/clerk` —
-which `src/index.ts` imports at the top level, so wrangler must resolve it at
+Both are optional peers of `@zackbart/connecta` — declared in its manifest,
+never installed with it, and each carrying the range this release supports.
+`@cloudflare/codemode` is the executor behind `execute_code`, published as
+`^0.4.4 || ^0.5.0`: install a version inside that and npm stays quiet, install
+one outside and npm says so at install time instead of leaving a Worker to
+discover the skew in production ([#376](https://github.com/zackbart/connecta/issues/376)).
+
+`@clerk/backend` is the peer behind `@zackbart/connecta/auth/clerk`, which
+`src/index.ts` imports at the top level, so wrangler must resolve it at
 build time. Miss it and the build stops at
 `Could not resolve "@clerk/backend"`, which is a missing peer rather than a
 broken example. Drop `clerkAuth` from `auth` if this deployment has no operator
@@ -146,9 +152,10 @@ The required Worker Loader binding is checked into `wrangler.jsonc`:
 "worker_loaders": [{ "binding": "LOADER" }]
 ```
 
-`src/index.ts` constructs `DynamicWorkerExecutor` from `env.LOADER` and serves
-the seven-tool surface. The executor package is one of the installs a copied
-deployment owns — see
+`src/index.ts` constructs `DynamicWorkerExecutor` with only `env.LOADER` and
+serves the seven-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).
 
 ## Activity history (optional)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.16.0",
+  "version": "0.17.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.",
@@ -46,6 +46,7 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./package.json": "./package.json",
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.js"
@@ -115,19 +116,23 @@
   },
   "peerDependencies": {
     "@clerk/backend": "^3.12.0",
+    "@cloudflare/codemode": "^0.4.4 || ^0.5.0",
     "quickjs-emscripten": "^0.32.0"
   },
   "peerDependenciesMeta": {
     "@clerk/backend": {
       "optional": true
     },
+    "@cloudflare/codemode": {
+      "optional": true
+    },
     "quickjs-emscripten": {
       "optional": true
     }
   },
   "devDependencies": {
     "@clerk/backend": "^3.12.0",
-    "@cloudflare/codemode": "^0.4.4",
+    "@cloudflare/codemode": "^0.5.0",
     "@cloudflare/vitest-pool-workers": "^0.18.8",
     "@cloudflare/workers-types": "^4.20250101.0 || ^5.0.0",
     "@playwright/test": "^1.62.0",

package/templates/node/AGENTS.md

@@ -23,6 +23,11 @@ This repository is deployment configuration, not a copy of Connecta itself.
 - `Dockerfile` and `docker-compose.yml` containerize *this* source; they are
   the same deployment, not a second one. Configuration belongs in `.env` and
   `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`.
 
 Do not add alternate entrypoints, policy layers, generated connector catalogs,
 or runtime connector registration. Keep the deployment small enough to review

package/templates/node/package.json

@@ -12,7 +12,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.16.0",
+    "@zackbart/connecta": "0.17.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {