@zackbart/connecta 0.18.3 → 0.20.0

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)) |
-| Passive observed output schemas | accepted | the sampling refusal stands: discovery originates no call and invents no arguments; instead, a successful explicitly read-only call whose provider declared no `outputSchema` records field names and broad JSON types only, under strict depth, breadth, property-name, node, and byte bounds, then merges that open optional-field shape in a 256-entry process-local cache for 24 hours; property names may be user-authored, search and describe label the shape `outputSchemaSource: "observed"`, a materially changed tool definition cannot inherit it, a provider declaration always wins, and no argument, scalar value, raw result, code, credential, or error is retained; this is new evidence rather than a rewrite of #282's facts: Blacksmith measured a value-free warm shape cache cutting one Linear code-mode task from 116.6 s / $1.91 to 56.6 s / $1.06, while live Connecta catalogs measured 246/378 missing on BePresent and 0/90 missing on OneMany ([study](https://www.blacksmith.sh/blog/code-smith-code-mode), [#442](https://github.com/zackbart/connecta/issues/442)) |
-| 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)) |
+| Program UI tool calls | removed | the read bridge added a second contract without improving agent data retrieval; views are display-only again ([#287](https://github.com/zackbart/connecta/issues/287), [#484](https://github.com/zackbart/connecta/issues/484)) |
+
 ## 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.
+One line each; the enforcing tests live beside the subsystem documentation.
+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.
-- **An observed shape is never a declaration.** It contains field names and broad JSON types only, remains open and optional, is labeled on discovery, and disappears behind any provider-declared output schema.
-- **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.3",
+  "version": "0.20.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.3",
+    "@zackbart/connecta": "0.20.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/documentation/code-first-exploration.md

@@ -1,292 +0,0 @@
-# Code-first Connecta: exploration findings
-
-> **Read as a record, not as current policy.** This is the exploration that
-> started the arc, kept as written. Two of its conclusions have since been
-> overtaken, and [`ethos.md`](../ethos.md)'s decisions table is the authority
-> where they disagree:
->
-> - **The ~32% definition-size reduction was an estimate.** The shipped fold
->   measures **19.6%** on the same 10-tools-to-7 comparison (10,675B → 8,587B).
->   The prototype's seven descriptions were thinner than the ones connecta
->   actually ships.
-> - **The "require repeated pinned-model evaluation before changing the default"
->   constraint below was dropped.** The owner decided the default directly on
->   2026-07-30 and [#224](https://github.com/zackbart/connecta/issues/224)
->   shipped it; the ethos records the eval-as-gate as `removed` and
->   [`eval/code-first-gate`](https://github.com/zackbart/connecta/blob/main/eval/code-first-gate/README.md) continues as
->   measurement that nothing waits on.
-
-## Executive summary
-
-We explored whether Connecta should make code execution the primary interface
-for connector work instead of exposing a growing collection of top-level
-meta-tools.
-
-The experiment supports that direction.
-
-A code-first surface was easier for a cold-start model to use than expected,
-materially reduced fixed tool-schema context, and was especially effective for
-workflows involving discovery, fan-out, joins, retries, and large-result
-projection. QuickJS added measurable runtime overhead, but not enough to be
-meaningful beside model generation and downstream service latency in normal
-agent work.
-
-The recommendation is to evolve Connecta toward:
-
-- one programmable, read-oriented execution surface;
-- a very small set of explicit tools for consequential writes, authorization,
-  and result retrieval;
-- policy, credentials, egress, and auditing enforced below generated code; and
-- the current tool surface retained as a compatibility path and evaluation
-  control while the new path matures — a retention that ended with #273, which
-  made the executor mandatory and deleted the classic surface outright.
-
-This was an exploratory spike, not a production implementation. The next agent
-should use these findings as a design brief rather than porting the prototype
-wholesale.
-
-## What we were testing
-
-The central question was:
-
-> Can a model use ordinary JavaScript against typed Connecta capabilities as
-> its default tool interface, while preserving Connecta's safety boundaries and
-> improving context efficiency?
-
-The prototype made `execute_code` the normal path for reads and composition.
-Generated code could discover tools, call read-only connector operations,
-parallelize work, join results, retry transient failures, and project large
-responses before returning anything to the model.
-
-High-consequence operations did not move into the sandbox. Writes still had to
-cross the explicit destructive-call boundary, where policy and human approval
-remain visible.
-
-We compared this with the existing surface using the same in-memory connectors
-and scenarios. We also gave the code-first interface to a pinned Terra model
-with no conversation history to test whether the interface was legible without
-the context of the experiment.
-
-## What we observed
-
-### 1. The model-facing surface became smaller
-
-The prototype reduced the visible surface from 10 tools to 7 and reduced
-serialized tool definitions by about 32%.
-
-That reduction matters beyond the raw token count. It removes overlapping
-routing choices between direct calls, batches, discovery, and execution. The
-model decides what program to write; JavaScript handles the deterministic
-control flow between capabilities.
-
-This is likely the largest long-term simplification. New connectors can expand
-the typed capability catalog without expanding the always-loaded top-level
-toolbox at the same rate.
-
-### 2. Composition is where code mode clearly wins
-
-The most compelling results came from tasks where intermediate data did not
-need to return to the model:
-
-- Discovery performed inside a workflow used one MCP call instead of two and
-  returned about 77% fewer bytes.
-- Projecting a large event export down to three identifiers returned about 93%
-  fewer bytes.
-- A dependent account-and-usage join reduced three MCP calls to two.
-- Parallel fan-out and repeated warm reads returned fewer bytes while keeping
-  orchestration deterministic inside one execution.
-
-These are not merely transport savings. They also reduce the number of points
-where the model must inspect an intermediate result and decide the next action.
-
-### 3. Simple calls do not become intrinsically cheaper
-
-A single cold lookup returned more bytes and took longer through code mode than
-through a direct tool call. A retry scenario showed the same tradeoff.
-
-This does not undermine code-first as the model-facing abstraction. It does
-mean we should not confuse a simpler interface with a universally faster
-execution path. Connecta can preserve one code-shaped interface while
-optimizing simple calls beneath it later, if measurement shows that is useful.
-
-### 4. Perceived user speed should be effectively unchanged
-
-With the built package, the first QuickJS execution was roughly 63–67 ms.
-Later executions in the same child were generally 1.6–2.8 ms. QuickJS/WASM
-initialization itself was only about 6 ms; most cold cost came from starting
-the Node child, loading modules, and IPC.
-
-That overhead is real but normally small compared with model inference and
-network-bound connector calls. Users are unlikely to perceive it as a distinct
-delay. Optimizing the child lifecycle may eventually be worthwhile, but it
-should not block the product direction.
-
-### 5. A cold-start model could use the interface successfully
-
-The pinned Terra sample completed all 10 behavioral scenarios. It made no
-invalid top-level tool selections, and every ordinary first program was valid
-JavaScript that ran without repair. The one repair was deliberately induced by
-giving it malformed discovery arguments.
-
-The scenarios covered:
-
-- a simple lookup;
-- parallel fan-out;
-- a dependent join;
-- discovery within execution;
-- projection of a large result;
-- a safely retried read;
-- colliding connector names addressed canonically;
-- typed batch failures;
-- malformed-argument repair; and
-- discovery of a destructive operation followed by sandbox refusal.
-
-This is encouraging evidence of interface legibility, not a statistical model
-benchmark. It was one sample from one pinned model.
-
-### 6. The safety boundary belongs below generated code
-
-The experiment reinforced that sandboxing alone is not the security model.
-Generated code must remain unable to grant itself capabilities.
-
-Connecta's durable boundary should continue to provide:
-
-- short-lived, brokered credentials rather than raw secrets;
-- request-scoped capability and connector policy;
-- read-only identities and narrowly scoped OAuth grants;
-- controlled network egress;
-- an explicit path for destructive or irreversible operations;
-- complete traces of programs, calls, outputs, and policy decisions; and
-- retry semantics appropriate to each operation.
-
-The sandbox should be treated as an additional containment layer. Admission,
-authorization, credentials, and destructive-action policy remain authoritative
-outside it.
-
-### 7. QuickJS remains the right default runtime for now
-
-We compared the available Bellard QuickJS and QuickJS-NG variants. Both
-initialized in roughly 6 ms, and their local transformation performance was
-effectively equivalent for this use case. The comparison provided no reason to
-switch engines.
-
-QuickJS remains a good Node default because it provides explicit memory, stack,
-and interrupt limits behind a small host interface. Running it in a child
-process also contains interpreter and WASM failure. Cloudflare deployments
-should continue using the platform-native Dynamic Worker executor.
-
-The current binding can be upgraded and re-evaluated separately. Changing the
-engine is not the solution to child-process startup cost.
-
-## What the experiment proved—and what it did not
-
-The evidence is strong enough to treat code-first as Connecta's intended
-product direction. It showed that the interface can be smaller, that a capable
-model can understand it cold, that composition and projection produce large
-context savings, and that the explicit write boundary can remain intact.
-
-It did not establish:
-
-- success rates across repeated prompt variations;
-- behavior across multiple model families and versions;
-- performance against a large real-world connector catalog;
-- production reliability under concurrency and partial failure;
-- the best final guest API; or
-- whether direct connector shortcut namespaces are worth their additional
-  complexity.
-
-The existing surface should therefore remain available during the transition
-as a compatibility mode, rollback path, and experimental control. It was, and
-then it was not: #224 made code-first the default and #273 removed the second
-shape entirely. The open questions above outlived the control arm rather than
-being settled by it.
-
-## Recommended product shape
-
-The smallest promising surface is:
-
-1. `execute_code` as the default read, discovery, transformation, and
-   composition interface.
-2. A canonical in-program API such as `connecta.search`,
-   `connecta.describe`, `connecta.call`, and `connecta.batch`.
-3. An explicit destructive-call tool for writes and irreversible actions.
-4. Explicit authorization and deferred-result tools where those boundaries
-   cannot safely live inside execution.
-5. Skills that teach domain playbooks without adding more always-loaded verbs.
-
-Canonical addressing should remain available even if ergonomic connector
-shortcuts are offered. It prevents sanitized-name collisions and gives
-generated programs a stable escape hatch.
-
-## Suggested implementation sequence
-
-### Phase 1: establish the evaluation gate
-
-Turn the exploratory scenarios into a repeatable evaluation suite before
-changing the default surface. Run at least 20 independent samples per task and
-model, with prompt variation.
-
-That suite was built under
-[`eval/code-first-gate`](https://github.com/zackbart/connecta/blob/main/eval/code-first-gate/README.md). Its recorded results
-remain as measurement history; the runnable comparison was retired when #273
-removed the alternate deployment shapes.
-
-Capture:
-
-- task success;
-- invalid tool selection;
-- syntax and runtime failures;
-- repair turns;
-- MCP calls;
-- request, response, and total transcript tokens;
-- time to first correct answer; and
-- attempted safety-boundary violations.
-
-Keep results separated by model and version. The model's ability to write and
-repair code is the independent variable, so blended scores would hide the
-signal we care about.
-
-### Phase 2: define the code-first contract
-
-Specify the guest API, error shapes, projection behavior, retry semantics,
-canonical addressing, cancellation, limits, and audit events before optimizing
-the runtime.
-
-The current architecture already has useful foundations: request-local
-catalogs, centralized invocation, admission control, and lazy connector
-capabilities. Build the new surface on those rather than recreating parallel
-logic in the executor.
-
-### Phase 3: consolidate the surface
-
-This phase is complete: code-first became the default in #224, then #273 made
-the executor mandatory and removed the deployment choice. Consequential writes
-remain outside the sandbox. New top-level read tools still require a measured
-case that cannot be expressed safely or clearly through the programmable
-surface.
-
-### Phase 4: stabilize successful workflows
-
-When an agent repeatedly discovers the same successful program, allow it to
-become a versioned script, test, or skill. Run that stabilized workflow
-deterministically and bring the model back only when inputs or interfaces
-change.
-
-This progression—tool mode to code mode to stabilized mode—is where the
-largest reliability and cost gains are likely to emerge.
-
-## Decision
-
-Proceed with code-first as the next direction for Connecta, with three
-constraints:
-
-1. Treat the current evidence as a strong exploratory result, not a completed
-   production validation.
-2. Preserve explicit external governance for writes and other consequential
-   actions.
-3. Require repeated pinned-model evaluation before changing the default for
-   users.
-
-The next implementation should optimize for a coherent, minimal contract and
-measurable behavior—not for preserving every detail of the exploratory
-prototype.