@zackbart/connecta 0.18.2 → 0.19.0

package/documentation/operations.md

@@ -75,7 +75,7 @@ optional.
 | `connectors` | — (required) | the connector set ([connectors](./connectors.md)) |
 | `executor` | — (required) | the sandbox `execute_code` runs in ([code mode](./code-mode.md#what-an-executor-must-implement)) |
 | `auth?` | none ⇒ open (dev only) | one `InboundAuth` or an array; bearer providers are checked before Clerk ([inbound auth](./auth.md)) |
-| `storage?` | `memoryStorage()` | the one state seam ([storage](./storage-and-credentials.md)) |
+| `storage?` | `memoryStorage()` | the one state seam for catalogs, result paging, credentials, and access tokens ([storage](./storage-and-credentials.md)) |
 | `publicUrl?` | per-request origin | public base URL; an HTTPS value also redirects inbound HTTP |
 | `logger?` | `console`, prefixed `[connecta]` | `{ debug, info, warn, error }` |
 | `branding?` | neutral Connecta defaults | operator-page and OAuth result-page labels and marks |
@@ -150,7 +150,7 @@ are in it and that no unshippable path leaked in — including any
 Cloudflare-named connector or storage path (`connectors/cloudflare`,
 `storage/cloudflare`) anywhere in the artifact, `dist/` and `examples/` alike —
 derives the shipped guide list from which guides still carry a stub marker,
-hands the packed path list to `scripts/check-packed-links.mjs`, and then runs
+hands the packed path list to `check-doc-links --packed`, and then runs
 `connecta init` and builds and runs the generated deployment's own container.
 
 That last step enforces the packed-link policy, which is one sentence: **every
@@ -224,7 +224,6 @@ in.
 | `catalog.test.ts` | lexical ranking and the compact schema renderer — `const`, `allOf` beside siblings, `$ref`, the depth limit, per-schema caching, and 2020-12 keyword compatibility |
 | `clerk.test.ts` | protected-resource metadata, the browser sign-in config, OAuth and session tokens, cached best-effort activity labels with their caps, the hand-applied `azp` rejection, and the `allowedDomains` allowlist including every lookalike that must not be repaired into a match |
 | `cloudflare-provider.test.ts` | `cloudflare()` construction, tool surface, request building, projections, typed failures, and credential test |
-| `cloudflare-registry.test.ts` | the same provider inside a real deployment: discovery including compact page bounds, addressing, and admission through the registry |
 | `code-first-surface.test.ts` | the seven-tool surface itself — an executor required, every removed option and top-level tool refused, compact always-loaded routing pinned below 1,000 characters, complete on-demand usage served, and `connecta.ui` findable before connector search |
 | `codemode-compat.test.ts` | the `Executor` seam staying structurally compatible with `@cloudflare/codemode`'s `DynamicWorkerExecutor`, enforced by `tsc` |
 | `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds failing construction, and one complete migration error for legacy own-properties |
@@ -238,24 +237,30 @@ in.
 | `executor-admission.test.ts` | the portable bounded FIFO both pools use: active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown |
 | `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, and response handling |
 | `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, typed inline describe recovery, discovery, utility, batch, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
-| `linear-provider.test.ts` / `linear-registry.test.ts` | the Linear proxy's construction, classification, and guide; then the same connector inside a real deployment |
-| `meta-tools.test.ts` | the registry-backed meta-tools: bounded discovery with page and address maxima, compact descriptions and the complete on-demand usage skill, compact and JSON schemas with constraints, typed describe recovery and suggestions, structured errors, connector-guide selection and summary bounds, stored-credential drift, catalog health, field projection, truncation and `get_result`, per-connector result bounds, probe timeouts, and unavailable or unknown browse recovery |
-| `mixpanel-provider.test.ts` / `mixpanel-registry.test.ts` | the Mixpanel proxy, its conditional-input guide and complete reviewed schema-digest manifest, then the same connector inside a real deployment |
-| `notion-provider.test.ts` / `notion-registry.test.ts` | Notion's deliberate tool surface, including declined expanded page inputs, request construction, lean projections, both pagination conventions, error mapping, and writes; then the connector in a real deployment |
+| `linear-provider.test.ts` | the Linear proxy's construction, classification, and guide |
+| `meta-tools-call.test.ts` | registry-backed calls: structured errors, field projection, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, and offset alignment |
+| `meta-tools-search.test.ts` | registry-backed discovery: bounded search with page and address maxima, compact and JSON schemas with constraints, typed describe recovery and suggestions, and structured-result compatibility |
+| `meta-tools.test.ts` | the remaining registry-backed meta-tools: the complete on-demand usage skill, connector-guide selection and summary bounds, stored-credential drift, catalog health, authorization, probe timeouts, and unavailable or unknown browse recovery |
+| `mixpanel-provider.test.ts` | the Mixpanel proxy, its conditional-input guide and complete reviewed schema-digest manifest |
+| `notion-provider.test.ts` | Notion's deliberate tool surface, including declined expanded page inputs, request construction, lean projections, both pagination conventions, error mapping, and writes |
 | `operator-boundary.test.ts` | the operator row of the decisions table, after every mutation route: authentication material managed without moving a declared structure, and the one honest exception — a credential write making a remote catalog appear, which is discovery arriving, not an operator editing the deployment |
 | `operator-store.test.ts` | `src/operator-ui/app/store.ts` against a fake browser: the Clerk listener, `gate()`, the generation fence, and the request path |
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
-| `registry.test.ts` | construction and id validation, startup warnings, address resolution, catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
+| `provider-registry.test.ts` | all six maintained providers inside real deployments: boot, description, address, catalog, storage, credential, admission, and activity isolation; plus provider-specific discovery and guide contracts |
+| `registry.test.ts` | construction and id validation, startup warnings, address resolution, version 2 catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
 | `remote-mcp.test.ts` | `remoteMcp()` against an in-process server through the `_transportFactory` seam: passthrough, downstream `isError`, Workers-safe output-schema validation, request-scoped client reuse and at-most-once scope close; plus the real transport's manual redirect policy, destination guard, credential containment, and downstream session termination |
-| `remote-mcp-credential.test.ts` | `remoteMcp()` drawing a static key from `/credentials`: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, `lastError`, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
+| `remote-mcp-credential.test.ts` | `remoteMcp()` drawing a static key from `/credentials`: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, the payload-free activity event, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
 | `remote-mcp-pagination.test.ts` | the `tools/list` cursor chain in both directions — exact cursor handoff, first-wins dedup, a failed later page rejecting rather than returning its prefix, the runaway backstops, the tool-metadata re-prime across pages, and paginated catalogs reaching the discovery path |
 | `request-admission.test.ts` | `/mcp` bounded before auth, the stable 503 and `Retry-After`, health and operator responsiveness under saturation, payload-free counters, queued cancellation, shutdown rejection while active work drains, and the separate fallback code pool |
-| `revenuecat-provider.test.ts` / `revenuecat-registry.test.ts` | the RevenueCat proxy's per-project key scoping and account-wide OAuth guides, its purpose-bearing summary, the argued borderline verdicts in its digest-free manifest, and the deliberately unclassified `render-paywall-screenshot`; then two project-scoped keys as two connectors in a real deployment |
+| `result-shapes.test.ts` | passive output-shape learning: value-free bounded inference, merging, 256-entry LRU eviction, 24-hour expiry, runtime isolation, read-only admission, declared-schema precedence, definition-change invalidation, discovery provenance, and failure isolation |
+| `revenuecat-provider.test.ts` | the RevenueCat proxy's per-project key scoping and account-wide OAuth guides, its purpose-bearing summary, the argued borderline verdicts in its digest-free manifest, and the deliberately unclassified `render-paywall-screenshot` |
 | `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory → complete usage skill → `call_tool`), conditional guide pointers, open routes, Clerk `.well-known` metadata without network, code mode, and deferred catalog reads through both discovery surfaces |
 | `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: every built-in answered ahead of connector routes inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
 | `startup-warnings.test.ts` | every construction-time `logger.warn` and, as importantly, the conditions that must *not* trigger one: open mode with a credential or OAuth connector, `publicUrl` unset beside OAuth, dropped branding and `uiAuth` URLs, a missing `verifyState`, a credential test-hook mismatch, and an unusable `calls.maxResultBytes` |
-| `stripe-provider.test.ts` / `stripe-registry.test.ts` | the Stripe proxy's mixed-mode OAuth and fixed-mode header contracts, admission, exact account selectors, and no-guess rule; then fixed credentials in a real deployment |
-| `ui.test.ts` | the server shell and `/ui/*` routes and the app's pure state rules from `view.ts` — filtering, page routing and capability states, credential management, gated `/ui/data` with broken-connector isolation and registry-owned catalog-observation containment, and the URL safety gates |
+| `stripe-provider.test.ts` | the Stripe proxy's mixed-mode OAuth and fixed-mode header contracts, admission, exact account selectors, and no-guess rule |
+| `operator-view.test.ts` | the app's pure state rules from `view.ts`: filtering, page routing, capability states, activity summaries, drift display, and identity reset |
+| `ui-credentials.test.ts` | credential-management routes: save, test, delete, validation, authentication, same-origin checks, and multi-field credential shapes |
+| `ui.test.ts` | the server shell and remaining `/ui/*` routes: gated `/ui/data` with broken-connector isolation and registry-owned catalog-observation containment, plus the URL safety gates |
 | `validate.test.ts` | `validateToolInput()` — a returned (not thrown) `invalid_args` naming the path, `additionalProperties: false` enforcement, per-schema validator caching, and an unusable schema passed through with one warning |
 
 ### Node-bound (`NODE_ONLY_SUITES`)
@@ -281,15 +286,15 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | `quickjs-log-limits.test.ts` | bounded `console.*` capture — per-entry cut, cumulative character and transport budgets, escape-heavy floods preserving the guest result | runs the Node QuickJS child-process executor |
 | `suite-partition.test.ts` | this partition, including itself: every `*.test.ts` in exactly one list, stale entries and empty reasons refused | walks the test directory to guard the partition |
 | `template-file-activity.test.ts` | the Node template's own activity store — persistence across restart, torn-line repair, newest-first paging, and compaction past the slack window | runs it against real files |
-| `upgrade-guide.test.ts` | the [upgrade guide](./upgrading.md)'s claims about somebody else's deployment — the generated file inventory, the seven tool names doctor demands, version boundaries that actually shipped, a bump target that is this release, and the three places a reader finds it | reads the guide, the template tree, and the CLI with Node filesystem APIs |
-| `version.test.ts` | `CONNECTA_VERSION` matching `package.json` | reads `package.json` with Node filesystem APIs |
+| `upgrade-guide.test.ts` | the [upgrade guide](./upgrading.md)'s claims about somebody else's deployment — the generated file inventory, the seven tool names doctor demands, version boundaries that actually shipped, the exact newest boundary and generation B endpoint matching this release, a bump target that is this release, and the three places a reader finds it | reads the guide, the template tree, and the CLI with Node filesystem APIs |
+| `version.test.ts` | `CONNECTA_VERSION` matching `package.json` and the Node template's exact dependency pin | reads both package manifests with Node filesystem APIs |
 
 ### Outside `npm run check`
 
 | Suite | Covers |
 | --- | --- |
 | `browser/operator-ui.spec.ts` | the operator wiring in a real browser: Clerk loader order across its version redirect and a real load failure, the shell staying open until authentication, credential and access-token and OAuth flows end to end, drift shown without naming a tool, and every failure and empty state |
-| `browser/program-ui.spec.ts` | the Apps shell in a real browser: a bound view merging fixed and declared arguments and correlating concurrent reads, and the one-string payload receiving no read bridge ([program UI read calls](./program-ui-read-calls.md)) |
+| `browser/program-ui.spec.ts` | the Apps shell in a real browser: a bound view merging fixed and declared arguments and correlating concurrent reads, and the one-string payload receiving no read bridge ([program UI read calls](https://github.com/zackbart/connecta/blob/main/records/program-ui-read-calls.md)) |
 
 **The `_transportFactory` seam.** `RemoteMcpOptions._transportFactory` is
 internal, not public API: when set, `remoteMcp()` uses that `Transport` instead

package/documentation/provider-conventions.md

@@ -651,7 +651,7 @@ runs this document against each of the six providers and returns a verdict per
 convention: **meets**, **misses** (with the fix), or **not applicable** (with
 the reason). A convention is never quietly skipped, and an accepted miss is
 recorded as a provider-specific exception with its argument, not left blank.
-Its six reports live in [provider-audit.md](./provider-audit.md), and the
+Its six reports live in [provider-audit.md](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md), and the
 mechanically checkable half of the hand-written bar runs on every test run in
 [`test/provider-conventions.test.ts`](https://github.com/zackbart/connecta/blob/main/test/provider-conventions.test.ts) —
 so a convention that was met once stays met, or fails loudly.

package/documentation/revenuecat.md

@@ -298,4 +298,4 @@ still needs restrained use.
 This connection is audited against
 [the provider conventions](./provider-conventions.md). Its verdict per
 convention is the RevenueCat section of
-[the provider audit](./provider-audit.md).
+[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).

package/documentation/stripe.md

@@ -251,4 +251,4 @@ about rather than read:
 This connection is audited against
 [the provider conventions](./provider-conventions.md). Its verdict per
 convention, including every recorded exception, is the Stripe section of
-[the provider audit](./provider-audit.md).
+[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).

package/documentation/upgrading.md

@@ -57,7 +57,7 @@ exist so far:
 | --- | --- | --- |
 | **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.18.2 | 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 |
+| **B** | 0.16.0 – 0.19.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
@@ -106,7 +106,7 @@ know what to preserve, once to know what to re-verify at the end.
 ### Bump the pin and install
 
 ```sh
-npm pkg set dependencies.@zackbart/connecta=0.18.2
+npm pkg set dependencies.@zackbart/connecta=0.19.0
 npm install
 ```
 
@@ -130,7 +130,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.18.2 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.19.0 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -186,7 +186,7 @@ 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.18.2 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.19.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`**.
@@ -207,6 +207,26 @@ 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.18.3 → 0.19.0
+
+Nothing changes for a deployment. Bump the version and reconcile the template
+as usual; no configuration, storage, runtime, or model-facing boundary moved.
+The release deletes unreachable compatibility code and consolidates source and
+tests behind the same public behavior. Six design records also moved out of the
+npm package and now live only at their GitHub URLs. They were maintainer history,
+not deployment documentation.
+
+### 0.18.2 → 0.18.3
+
+Nothing throws for an existing deployment, and the version bump alone crosses
+this boundary. Successful explicitly read-only calls whose provider declares
+no output schema now teach later discovery the result's field names and broad
+JSON types. The open optional-field shape is labeled
+`outputSchemaSource: "observed"`, lives only in a bounded runtime cache, and
+starts cold after 24 hours, a process restart, or Worker isolate eviction. No
+configuration or storage migration is involved, and discovery still never
+executes a tool.
+
 ### 0.18.1 → 0.18.2
 
 Nothing throws for an existing deployment, and the version bump alone crosses

package/ethos.md

@@ -1,149 +1,103 @@
 # connecta — ethos
 
 What connecta is, what it refuses to be, and the invariants every change must
-preserve. This file is deliberately terse. When a proposed change contradicts a
-line here, either the change is wrong or this file needs amending — in that
-order, and amending it is a design decision, not a drive-by edit.
+preserve. Deliberately terse: when a change contradicts a line here, either the
+change is wrong or this file needs amending — in that order, and amending it is
+a design decision, not a drive-by edit.
 
 ## What this is
 
-- **One MCP endpoint, one programmable surface.** Every integration you've
-  deliberately chosen sits behind a capability catalog that agents reach by
-  writing ordinary JavaScript, ringed by a few explicit tools — for the
-  boundaries code must not cross, and for the jobs a program is the wrong
-  shape for.
+- **One MCP endpoint, one programmable surface.** Every integration you chose
+  sits behind a capability catalog that agents reach by writing JavaScript,
+  ringed by a few explicit tools for the boundaries code must not cross.
 - **A deployment is a small config-as-code file.** Changing what agents can
-  reach is an edit and a redeploy. One deployment, one tenant, one audience —
-  more audiences means more deployments.
-- **Curated when available, open when not.** Prefer an explicitly imported
-  prebuilt connection when Connecta maintains one: it carries the provider's
-  known-good endpoint, authentication defaults, tool ergonomics, and concise
-  usage guidance. `remoteMcp()` and `api()` remain equal, first-class
-  primitives for custom and unsupported integrations. Every path produces the
-  same `Connector`: same addresses, same catalog, same safety rules.
+  reach is an edit and a redeploy. One deployment, one tenant, one audience.
+- **Curated when available, open when not.** Prefer a maintained prebuilt
+  connection; `remoteMcp()` and `api()` stay first-class for everything else.
+  Every path yields the same `Connector` with the same rules.
 - **Seven tools, an executor required.** The primary surface is a program, so
-  every deployment runs an executor — a Dynamic Worker on Cloudflare, QuickJS
-  behind its optional-peer subpath on Node — and one without refuses to boot
-  ([#273](https://github.com/zackbart/connecta/issues/273)). Every meta-tool
-  earns its keep: the default answer to "agents need X" is the program
-  surface, and a capability has to be shown inexpressible through it before
-  it earns a top-level tool
-  ([#224](https://github.com/zackbart/connecta/issues/224)). Packaging is
-  unchanged: required describes the deployment, never the dependencies.
-- **Safe by default.** Only tools explicitly annotated read-only are callable
-  without crossing the destructive boundary — directly or from generated code;
-  everything else goes through `call_destructive_tool`, where the MCP host can
-  put the question to a human. Approval is the host's job; connecta makes the
-  question visible.
-- **One fetch-native core, two runtimes.** The same code runs unchanged on
-  Cloudflare Workers and in Node — a Worker or a Docker stack, your pick. Web
-  APIs only in the core; Node touches live behind explicit subpaths.
+  every deployment runs an executor and one without refuses to boot. A
+  capability earns a top-level tool only by being inexpressible as a program.
+- **Safe by default.** Only tools explicitly annotated read-only run without
+  crossing `call_destructive_tool`, where the host can ask a human. Approval is
+  the host's job; connecta makes the question visible.
+- **One fetch-native core, two runtimes.** Web APIs only in the core; Node
+  touches live behind explicit subpaths. Cloudflare Worker or Docker, your pick.
 - **Observable, actionable only over authentication material.** Operator pages
-  show connector status, masked credentials, and payload-free activity — and
-  they act: rotate a credential, issue or revoke an access token, run a
-  downstream OAuth flow. Declared capability is what they cannot touch.
+  show status and payload-free activity and may rotate credentials, issue
+  tokens, and run OAuth. Declared capability they cannot touch.
 
 ## What this isn't
 
-- **Not a platform.** No runtime connector registration, no admin UI that
-  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 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.
-- **Not a promise to strangers — yet.** Built for its author's deployments
-  first, published openly. Breaking changes are cheap and the version number
-  signals change, not stability.
+- **Not a platform.** No runtime registration, admin-editable capability,
+  policy engine, approvals, or pauses.
+- **Not a schema ingester.** No OpenAPI or GraphQL → tools.
+- **Not multi-tenant.** No account model or per-user credential store; scope
+  stays connector-level, and ambiguity stops rather than guesses.
+- **Not stateful.** No protocol sessions, no server push; scope resolves per
+  request.
+- **Not a nanny.** Credentials fail loudly at use; nothing probes one.
+- **Not a promise to strangers — yet.** Breaking changes are cheap; the version
+  number signals change, not stability.
 
 ## Decisions
 
-The record of shapes considered and refused. Proposing one again is allowed;
-proposing one without a new argument is not.
+Shapes considered and turned down. Proposing one again without a new argument
+is not allowed. Accepted designs live in their subsystem guide and the
+CHANGELOG, not here.
 
 | Decision | Verdict | Why |
 | --- | --- | --- |
-| OpenAPI / GraphQL ingestion | refused | generated tools are the disease; hand-write `api()` |
-| Multi-tenancy / account model | refused | one deployment per tenant; deploy again instead |
+| 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 |
+| Multi-tenancy / account model | refused | one deployment per tenant; deploy again |
 | Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
 | Runtime connector registration | refused | config-as-code is the security model |
-| Prebuilt connections as the preferred authoring path | accepted | an a-la-carte provider constructor, imported and constructed in the deployment file, encodes maintained defaults for providers connecta actually uses — preferred *when maintained*, with no promise of one per provider; it returns exactly one ordinary `Connector` with no extra privileges — never a bundle, a group, a preset, or a registry — its tools are hand-written or proxied from a downstream MCP catalog, never generated from a schema document; its vetted annotations classify what the downstream leaves unannotated and otherwise preserve explicit annotations, with one fail-closed exception: a release-reviewed destructive classification outranks a contradictory downstream `readOnlyHint: true`, because Connecta has independently established that the tool mutates existing state; `remoteMcp()` and `api()` stay first-class ([#297](https://github.com/zackbart/connecta/issues/297), [#315](https://github.com/zackbart/connecta/issues/315)) |
-| Guarded raw REST escape hatches in a prebuilt connection | accepted | a large, fast-moving provider cannot be honestly represented by a small frozen list: a GET-only tool may expose provider-relative reads, while JSON mutations and explicit-content uploads stay separate and always cross the destructive boundary; the connector owns authentication, rate limits, error mapping, URL confinement, and safe method classification, while the provider token remains the capability boundary — this is not schema ingestion, runtime connector registration, or permission widening |
-| Expanded Notion page create/update options | refused | the maintained writes own explicit parents, authored content, property replacement, and reversible trash; workspace-private creation, placement, richer media, coordination locks, asynchronous templates, and irreversible child erasure are different ownership, ordering, file, coordination, or deletion workflows, not missing fields — keep the approval names honest and use a custom `api()` connector when a deployment needs one ([#408](https://github.com/zackbart/connecta/issues/408), [#409](https://github.com/zackbart/connecta/issues/409)) |
-| Hosted-provider drift detection during catalog refreshes | accepted | a vetted classification is a claim about somebody else's catalog, and an allowlist nobody can tell is stale is an allowlist that is wrong — so each maintained hosted-MCP proxy ships the tool names, classifications, and (once a release records them) schemas it reviewed, and compares them against the live listing *inside* a catalog refresh the deployment already asked for; the boundary is the piggyback itself, which is what keeps this from being proactive credential liveness wearing a new hat ([#179](https://github.com/zackbart/connecta/issues/179)): no scheduled job, no background request, no credential probe, and not one byte of network traffic that would not have happened anyway; what it produces is four counts — unclassified additions, names no longer served, explicit annotation conflicts, schema changes — on connector status, `connecta doctor`, and one payload-free activity event with nowhere to put a tool name or a schema; the two read surfaces answer for the runtime that served the refresh, because the observation is isolate-local and only the activity event is durable, and unknown tools already fail closed, so drift costs approval round trips and stale guidance rather than capability ([#343](https://github.com/zackbart/connecta/issues/343)) |
-| Provider registry / integration marketplace | refused | prebuilt connections are imports, not listings; discovery happens in documentation, never at runtime ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| Provider registry / marketplace | refused | prebuilt connections are imports; discovery happens in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
+| 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; connecta's own Apps shell is the one `resources/read` carve-out ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Resources & prompts aggregation | refused | tools only; the Apps shell is the one `resources/read` carve-out ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Elicitation passthrough | refused | no route through a stateless aggregator |
 | Repository formatter | refused | style is authored, not enforced |
-| Toolkits (scoped views) | removed | never earned its keep; deploy per audience ([#178](https://github.com/zackbart/connecta/issues/178)) |
+| 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)) |
+| 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)) |
+| 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)) |
+| 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)) |
+| Toolkits (scoped views) | removed | deploy per audience ([#178](https://github.com/zackbart/connecta/issues/178)) |
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
-| Agent credential recovery | accepted | one `auth_required` route through `authorize_connector`; only an operator handles secrets ([#192](https://github.com/zackbart/connecta/issues/192)) |
-| Operator-issued MCP access tokens | accepted | named, revocable authentication gives header-capable clients a small alternative to OAuth; tokens identify callers but never scope tools or become operator credentials |
-| 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`](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)) |
-| Always-loaded routing, on-demand execution detail | accepted | every conversation pays for MCP instructions and seven serialized definitions, so they carry only route selection, the fail-closed boundary, and the minimum guest syntax; selection detail, examples, runtime differences, and repair live in the existing byte-identical `usage` skill, fetched at most once per task — no new skill surface or deployment option ([#418](https://github.com/zackbart/connecta/issues/418)) |
-| 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)) |
-| Automatic host-side projection of program results | refused | the measured win was program-authored projection; a host heuristic drops fields a program chose to return and is invisible in the transcript ([#223](https://github.com/zackbart/connecta/issues/223)) |
-| Caller-visible execution diagnostics | accepted | optional request-local timing and size aggregates make catalog, connector, and executor costs distinguishable without persisting payloads, adding a tool, or charging normal responses context ([#247](https://github.com/zackbart/connecta/issues/247)) |
-| `get_result` paging for program results | refused | paging rewards the unprojected return code mode exists to remove; a program can shrink anything ([#223](https://github.com/zackbart/connecta/issues/223)) |
-| Stabilized workflows (programs → versioned scripts/skills) | gated | earns a surface only once real traffic shows programs that actually recur ([#225](https://github.com/zackbart/connecta/issues/225)) |
-| Semantic tool search | gated | keyword search has not been shown to be the thing failing; earns its way in through [#222](https://github.com/zackbart/connecta/issues/222)'s harness ([#27](https://github.com/zackbart/connecta/issues/27)) |
-| Per-result lexical query coverage | removed | verbose, indexed, and trailing shapes did not earn their response-token cost: the coverage-off arm beat the verbose wire, the first compact wire regressed efficiency, and the trailing wire failed its precommitted 30-run clean-route gate (13/30 vs 9/30, +13.3 pp, Fisher p=0.422); preserve the mixed complete/partial ranking from [#326](https://github.com/zackbart/connecta/issues/326), but do not revive serialized coverage without new causal evidence ([#322](https://github.com/zackbart/connecta/issues/322), [#323](https://github.com/zackbart/connecta/issues/323)) |
-| 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)) |
-| Erasable TypeScript in `execute_code` | refused | a location-preserving prototype accepted annotations, return types, assertions, aliases, interfaces, and erased generics at ~8.3 µs median transform cost, but `ts-blank-space` drags a 23.68 MB installed TypeScript dependency into the fetch-native core and no runnable agent arm established a first-run or repair benefit; the plain-JavaScript contract stands until new measured model evidence earns that package and parity cost ([evidence](https://github.com/zackbart/connecta/blob/main/eval/current-version/results/issue-419-evidence.md), [#419](https://github.com/zackbart/connecta/issues/419)) |
-| 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)) |
-| Provenance tracking for emitted content | refused | everything a program emits is program output; handles or attribution labels are capability-shaped machinery that changes no client's trust posture ([#267](https://github.com/zackbart/connecta/issues/267)) |
-| Program-generated UI (`connecta.ui` + the Apps shell) | accepted | one MCP Apps view per successful run: the program supplies HTML only, delivered in result `_meta`, which hosts keep out of model context, and rendered by connecta's static shell inside the host's sandboxed frame ([design record](./documentation/mcp-ui-design.md), [#266](https://github.com/zackbart/connecta/issues/266)) |
-| Serving connecta's own UI template via `resources/read` | accepted | a narrow carve-out from the resources-aggregation refusal, not a reversal of it: one static build-time shell at one URI, an empty `resources/list`, nothing downstream ever listed or aggregated ([#266](https://github.com/zackbart/connecta/issues/266)) |
-| Downstream MCP Apps template passthrough | gated | proxying downstream `resources/read` earns its way in when a downstream connector actually ships an Apps template ([#266](https://github.com/zackbart/connecta/issues/266)) |
-| View-initiated read calls from program UI | accepted | named bindings materially improve refresh, cursor pagination, and drill-down without persistence or a new tool; the trusted shell delegates only to the existing fail-closed `call_tool`, and the one-string UI remains display-only ([evidence](./documentation/program-ui-read-calls.md), [#287](https://github.com/zackbart/connecta/issues/287), [#289](https://github.com/zackbart/connecta/issues/289)) |
-| 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)) |
+| 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)) |
+| 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 | gated | needs a downstream that ships one ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| View-initiated mutation calls from program UI | gated | a click is not approval ([#287](https://github.com/zackbart/connecta/issues/287)) |
+
 ## Invariants
 
 One line each; the enforcing tests live beside the subsystem documentation.
-Breaking one is not a bug fix — it is a design change wearing a disguise.
+Breaking one is a design change wearing a disguise.
 
-- **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
-  read-only classification are enforced below the sandbox; nothing a program
-  does widens what it can reach.
-- **Only explicitly read-only work runs inside the sandbox.** Unannotated,
-  write-capable, and destructive tools cross `call_destructive_tool`, where the
-  host can ask a human.
-- **Nothing request-bound survives a request.** No transport, stream, abort
-  state, or later-awaited promise outlives the request that made it.
-- **A downstream catalog is complete or it is a failure.** A partial catalog
-  is never cached, persisted, or served as if it were small.
-- **Activity is payload-free by construction.** The event type has nowhere to
-  put arguments, results, code, or raw error text.
-- **Credentials never leave the host.** Encrypted at rest, readable only by
-  the owning connector, never rendered by any surface.
-- **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, never into core.
-- **Operator routes manage authentication material, never declared
-  capability.** Authenticating a declared capability is allowed; the connector
-  set, declared catalog and annotations, OAuth scopes, admission, authorization
-  rules, and caller tool scope take a config edit. A downstream catalog is
-  discovered, not declared — remote MCP tools appear when its credential does.
-- **Structural mistakes throw at construction.** A deployment that boots into
-  the wrong shape is worse than one that refuses to boot.
+- **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.
+- **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, 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.
+- **Operator routes manage authentication material, never declared capability.** A downstream catalog is discovered, not declared.
+- **Structural mistakes throw at construction.** Booting into the wrong shape is worse than not booting.
 
----
-Connecta began as a radical simplification of [executor](https://github.com/UsefulSoftwareCo/executor); the table above is the record of that simplification holding.
+Connecta began as a radical simplification of
+[executor](https://github.com/UsefulSoftwareCo/executor); this file is the
+record of that simplification holding.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.18.2",
+  "version": "0.19.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.",
@@ -105,12 +105,11 @@
     "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 scripts/admission-load.mjs",
+    "load:admission": "npm run build && node eval/admission-load.mjs",
     "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",
     "release:check": "npm run check && npm run check:security && npm run check:package",
-    "prepack": "npm run check",
-    "prepublishOnly": "npm run check:security"
+    "prepack": "npm run check"
   },
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",

package/templates/node/package.json

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