@zackbart/connecta 0.10.1 → 0.10.2

package/documentation/connector-guides.md

@@ -0,0 +1,7 @@
+# Connector guides
+
+> **Stub.** The old manual was retired in the phase-1 docs restructure. This
+> document will be rewritten as an agent-facing guide — what the subsystem is
+> for, how to work on it, and what it must never do — once the ideas in
+> [ethos.md](../ethos.md) settle. The prior text lives in git history as
+> `docs/connector-guides.md`.

package/documentation/connectors.md

@@ -0,0 +1,63 @@
+# Connectors
+
+Connectors are the boundary between Connecta's fixed meta-tool surface and
+downstream capabilities. `api()` defines a deliberate HTTP API surface;
+`remoteMcp()` aggregates another MCP endpoint. Both publish the same tool
+definitions and pass through the same catalog, read-only admission, invocation,
+result-size, and activity paths.
+
+Connector instances are deployment configuration. They are not registered or
+reconfigured at runtime. Request-local clients, transports, abort signals, and
+catalogs must be released with the request that created them.
+
+## MCP version skew
+
+Connecta deliberately sits between protocol generations
+([full revision inventory](./mcp-2026-07-28.md)):
+
+- **Inbound:** `/mcp` serves both the 2026-07-28 revision and legacy 2025
+  clients. Modern clients negotiate with `server/discover` and do not send
+  `initialize`; legacy clients retain their initialize flow. The endpoint
+  remains stateless in both cases.
+- **Outbound:** `remoteMcp()` probes modern downstreams and falls back to the
+  byte-compatible legacy flow. Legacy downstreams are normal supported
+  deployments, not a temporary exception.
+- **Legacy sessions:** Connecta's own endpoint creates no protocol session, but
+  a stateful legacy downstream can still issue `Mcp-Session-Id`. Closing a
+  request scope explicitly sends the legacy DELETE before closing its transport.
+  SDK v2 `Client.close()` does not do that on Connecta's behalf, so
+  `terminateSession` remains required and tested.
+- **Modern cache hints:** `tools/list` is deployment-fixed and returns a
+  one-hour private cache hint. Downstream hints do not alter Connecta's existing
+  five-minute fingerprinted catalog cache; that remains gated in
+  [#206](https://github.com/zackbart/connecta/issues/206).
+- **Multi-round-trip results:** a downstream `input_required` result becomes a
+  non-retryable `input_required_unsupported` failure. `call_tool`, the
+  `execute_code` host bridge, and classic's `batch_call` all preserve the
+  structured code. Relaying the
+  opaque `requestState` is architecturally possible but gated until real hosts
+  and downstreams adopt it.
+
+The compatibility policy has no automatic sunset. Dropping a revision,
+session cleanup, or cursor tolerance requires an explicit design decision and
+replacement evidence.
+
+## Catalog contract
+
+A downstream catalog is complete or it is a failure. Follow every page until
+the cursor ends, preserve schemas and annotations, and never cache or serve a
+partial walk. The fixed TTL is paired with a schema fingerprint so a changed
+catalog invalidates persisted results even within the time window.
+
+Tool calls must use the shared invocation path. That keeps direct calls, batch
+children, and code-mode host calls aligned on safety, retries, admission,
+timeouts, validation, result guards, and typed failures.
+
+## Authentication
+
+OAuth-backed MCP connectors persist their registration and tokens through the
+connector-scoped storage context. Those values are bound to the authorization
+server issuer discovered and validated by the SDK; see
+[storage and credentials](./storage-and-credentials.md#downstream-oauth).
+The callback route validates `state` before passing the complete callback query
+to the SDK so RFC 9207 `iss` validation is not lost.

package/documentation/mcp-2026-07-28.md

@@ -0,0 +1,46 @@
+# MCP 2026-07-28 revision inventory
+
+This is Connecta's disposition of every change in the 2026-07-28 MCP revision.
+It records what SDK v2 owns, what Connecta implements, and what remains
+deliberately gated. The migration is tracked in
+[#176](https://github.com/zackbart/connecta/issues/176).
+
+| # | Change | Verdict | Connecta action |
+| --- | --- | --- | --- |
+| 1 | Sessions and `Mcp-Session-Id` removed | adopt inbound; retain outbound legacy support | `/mcp` stays stateless. Keep `mcp-session-id` CORS compatibility and explicit DELETE for stateful legacy downstreams; v2 `Client.close()` does not terminate those sessions. |
+| 2 | `initialize` removed; version and capabilities move to per-request `_meta` | adopt via SDK | Modern clients use the v2 envelope; legacy initialize remains served indefinitely. |
+| 3 | `server/discover` required | adopt via SDK | The fetch-native handler serves discovery and the outbound client uses it for negotiation. |
+| 4 | `subscriptions/listen` server push | decline | Connecta emits no notifications and remains request-scoped. |
+| 5 | Multi-round-trip results on Connecta's own surface | decline | Credential recovery remains the accepted `auth_required` tool-result flow. |
+| 6 | Downstream `resultType: "input_required"` | handle; gate passthrough | Return the structured non-retryable `input_required_unsupported` failure through direct, batch, and code-mode invocation. |
+| 7 | `resultType` required on results | adopt via SDK | Modern results are stamped `complete`; legacy results without the field remain accepted. |
+| 8 | `ttlMs` and `cacheScope` on cacheable lists | adopt | `tools/list` returns `ttlMs: 3_600_000` and `cacheScope: "private"`. |
+| 9 | Honor downstream list cache hints | gated | Keep the fixed five-minute TTL plus fingerprint until refresh-churn evidence warrants complexity ([#206](https://github.com/zackbart/connecta/issues/206)). |
+| 10 | Native Tasks extension | refuse | Tasks address duration, while `get_result` addresses response size. Polling plus paging would add round trips without replacing the stash. |
+| 11 | Extensions capability framework | decline | No client consumes a Connecta extension declaration. |
+| 12 | `Mcp-Method` and `Mcp-Name` POST headers | adopt | SDK v2 handles the headers; CORS allows `mcp-method, mcp-name`. |
+| 13 | RFC 9207 `iss` validation and `application_type` | adopt via SDK | The callback preserves all query parameters for SDK validation. |
+| 14 | Credentials keyed to issuer; re-register when AS changes | adopt | Version-2 credential envelopes store issuer; mismatch advances the generation epoch and invalidates registration and tokens. |
+| 15 | Client ID Metadata Documents replace DCR | gated | DCR is grandfathered. Publishing deployment-specific CIMD remains [#207](https://github.com/zackbart/connecta/issues/207). |
+| 16 | Full JSON Schema 2020-12 and arbitrary `structuredContent` | verify | Exotic-keyword schemas pass through compact discovery and the 2020-12 input validator. |
+| 17 | Protocol error-code updates | adopt via SDK | Connecta has no source-level dependency on protocol error numbers. |
+| 18 | Roots, Sampling, Logging, and HTTP+SSE deprecated | no-op | Connecta does not aggregate or initiate these surfaces. |
+
+## Compatibility decisions
+
+The inbound handler serves both revisions from one endpoint. The outbound
+client automatically negotiates modern service and falls back to legacy
+initialize. The legacy session termination test proves that explicit
+`terminateSession` remains necessary: SDK v2 closes the client transport but
+does not send the downstream's session DELETE.
+
+MRTR passthrough is gated rather than permanently refused. A stateless relay
+could carry `requestState`, but Connecta has no host contract for exposing the
+embedded input request, no downstream adoption evidence, and no annotation
+model for the resumed call. Until those arrive, a loud typed failure is safer
+than discarding the intermediate result or hanging.
+
+Native Tasks and downstream cache hints do not replace existing mechanisms.
+`get_result` pages oversized completed data; Tasks poll unfinished work.
+Connecta's fingerprinted catalog cache already produces roughly 3 ms reads, so
+downstream hint handling must earn its complexity with measured churn.

package/documentation/meta-tools.md

@@ -0,0 +1,167 @@
+# Meta-tools
+
+Connecta keeps one small tool surface in model context and resolves downstream
+tools behind it. `search_tools` finds addresses, the call tools enforce safety
+annotations, and `get_result` pages bounded results.
+
+## Which surface a deployment serves
+
+The `executor` decides it, and there is nothing else to configure
+([#224](https://github.com/zackbart/connecta/issues/224)):
+
+| | `tools/list` | Discovery breadth and batching |
+| --- | --- | --- |
+| **executor configured** | seven: `execute_code`, `search_tools`, `call_tool`, `call_destructive_tool`, `authorize_connector`, `get_result`, `skills` | `connecta.search`, `connecta.describe`, `connecta.batch` inside a program |
+| **no executor** | nine: the above minus `execute_code`, plus `list_connectors`, `describe_tools`, `batch_call` | those three top-level tools |
+
+Code-first is what a model sees. Four overlapping ways to reach one connector
+became two: `search_tools` then `call_tool` for a single cold read — measurably
+cheaper direct than through a program — and `execute_code` for everything wider.
+The fold is worth 19.6% of the serialized tool definitions measured against the
+ten-tool shape an executor-backed deployment used to serve — 10,675B to 8,587B —
+and, more durably, one fewer routing decision a model makes before doing any
+work. Note which baseline that is: the executor-free nine serialize to 7,207B,
+so the seven-tool surface is *larger* than the row below it in that table. It
+buys the program with those bytes. The [guest API contract](./code-mode.md) is
+what a program is promised.
+
+`execute_code` accepts optional `diagnostics: true` when a caller is measuring
+a workflow. It adds only compact request-local timing and serialized-size
+aggregates; normal calls carry no diagnostics block or response-context cost.
+The measurements never contain program source, arguments, values, addresses,
+credentials, logs, or raw error text.
+
+Classic is the compatibility surface: what an executor-free deployment
+necessarily serves, since the program surface the fold depends on is not there.
+It is supported and tested, not an equal citizen in the docs. `surface:
+"classic"` beside an executor is the only override; it produces the ten-tool
+shape the [eval gate](../eval/code-first-gate/README.md)'s *incremental* arm
+measures. That gate's control arm is executor-free classic and needs no
+override.
+
+Nothing became unreachable. `connecta.describe` takes the same addresses and
+formats as `describe_tools`, `connecta.batch` runs the same 1–10 parallel
+read-only calls as `batch_call` and returns the same typed outcomes, and an
+unfiltered `connecta.search({})` browses every catalog a program can reach —
+the part of `list_connectors` a model used. Live connector probing was the rest
+of it, and that is an operator concern: the operator pages and `/health` own it.
+
+## Discovery context
+
+Start an unknown-address lookup with two to four distinctive action/object
+terms, not the full request, and omit `limit` so the default eight-result page
+stays small. Set `safety: "readOnly"` when the result is headed to `call_tool`
+or generated code; `safety: "approvalRequired"` finds the complementary set
+that must cross `call_destructive_tool`. Omitting `safety`, or setting it to
+`"all"`, preserves the complete configured catalog. This is only a discovery
+filter: it neither grants authority nor changes invocation admission.
+`includeSchemas: "compact"` adds each match's input and any
+declared output shape; matches also carry declared behavior annotations. When
+that shape is sufficient, call the returned address directly. Reserve schema
+expansion — `connecta.describe` in a program, `describe_tools` on the classic
+surface — for a search without schemas, an ambiguous compact shape, or exact
+constraints that require `format: "json"`.
+
+Compact search is deliberately a routing view, not a second copy of connector
+documentation. Tool purposes are capped at 160 characters, connector
+descriptions and property prose are omitted, required input fields render
+before optional ones, and each input or output shape is capped at 1,024 UTF-8
+bytes. A capped object becomes a valid required-first shape with `unknown`
+types; other shapes become `unknown /* truncated */`. The match also carries
+`inputSchemaTruncated` or `outputSchemaTruncated`; repeat the search with
+`includeSchemas: "json"` or use the existing describe path when exact
+constraints matter.
+
+## Result representation
+
+For object results, `structuredContent` is the canonical full-fidelity value.
+`content` carries the same complete value as compact JSON for clients that only
+consume text. Keeping both follows MCP's backwards-compatibility guidance;
+removing or summarizing the text copy is deferred until host-forwarding
+measurements demonstrate that supported clients do not need it.
+
+Plain-text guidance and errors remain text-only. A downstream MCP tool's native
+content blocks also pass through unchanged when `call_tool` uses MCP result
+mode; they are not a duplicated Connecta object result. Newly stashed JSON and
+downstream content envelopes use compact serialization, so `get_result` byte
+offsets and totals refer to that exact compact text.
+
+`fields` keeps its historical flat `{ "<path>": value }` result when every
+requested dot-path resolves, except that an exact downstream `$connecta` field
+is always escaped under `data`. If any path misses—or that reserved name is
+selected—the result carries matches under `data` and reserves `$connecta` for a
+`type: "field_projection"` recovery record naming each `unmatchedFields`
+entry. The discriminator means downstream fields named `data`, `projection`,
+or `$connecta` remain ordinary values nested under `data`, never apparent
+metadata. A declared output schema contributes a bounded `availableFields`
+list and a `schemaCoverage` verdict. Only a completely analyzed, closed schema
+can label paths `invalidFields`; open, patterned, tuple, unresolvable, cyclic,
+`$ref`-sibling, or traversal-limited shapes stay `partial`. Traversal bounds
+depth, nodes, path count, individual path characters/bytes, and cumulative path
+characters/bytes before sorting or rendering. Without a schema, Connecta
+reports only observed misses and does not pretend it knows the complete runtime
+shape. API values and JSON-parseable downstream MCP text blocks follow the same
+rule.
+
+## Lexical discovery
+
+`search_tools` tokenizes tool names and descriptions at punctuation and
+camel-case boundaries. Exact whole-token matches carry the most weight; a small
+set of inflectional variants preserves singular/plural and verb-form recall
+without allowing arbitrary mid-word substring matches. Ranking weights each
+query term by its document frequency across the available catalogs in that
+search, so a rare domain term outranks a ubiquitous action while action terms
+still distinguish `get`, `list`, `search`, and write operations. If no tool
+covers every non-conversational term, the same scorer falls back to any-term
+matching and marks the result `matchMode: "partial"`.
+
+Every partial or no-match lexical search also returns bounded `queryAnalysis`;
+an all-term result needs no recovery advice. `representedTerms` occur in the
+current page, `otherResultTerms` occur only in another result, and
+`unmatchedTerms` have no lexical match in the catalogs that answered. Partial
+results explain that no single tool covered every term and recommend splitting
+distinct intents. A true negative says that no matching capability is
+configured and recommends refining, connector-scoping, or browsing; when a
+connector catalog was unavailable, the response includes
+`unavailableConnectorCount` instead of making that stronger claim. Analysis
+from a connector-filtered search includes `connectorScope` and speaks only
+about that connector; `unknownConnector` distinguishes an unconfigured ID from
+a known connector with no match. Analysis covers at most eight distinct terms
+of at most 64 displayed characters each, marks longer input `truncated`, and
+never changes lexical ranking.
+
+## Authorization recovery
+
+Every typed `auth_required` call failure uses the same envelope:
+
+```json
+{
+  "code": "auth_required",
+  "message": "...",
+  "retryable": false,
+  "connector": "service",
+  "operation": "service.read",
+  "recovery": "oauth",
+  "nextAction": {
+    "tool": "authorize_connector",
+    "arguments": { "connector": "service" },
+    "operatorHandoff": "Give the URL and instructions it returns to the operator."
+  },
+  "retry": "Retry service.read after the operator completes recovery."
+}
+```
+
+`recovery` is `oauth`, `operator_config`, or `unavailable`. Call
+`authorize_connector` only after this error. It returns the class-specific
+handoff:
+
+- `oauth`: an `authorizationUrl` and consent instructions;
+- `operator_config`: an `operatorUrl` ending in `/credentials`, plus the
+  declared credential label and field names/guidance; or
+- `unavailable`: an honest deployment/configuration message.
+
+The tool accepts no secret. `force` applies only to OAuth and may discard its
+stored grant before restarting consent. Static credential values are written
+only through the same-origin, Clerk-operator credential route. After OAuth
+consent or an operator update, retry the original operation; a static update is
+read from the vault on the next call and needs no redeploy.

package/documentation/operations.md

@@ -0,0 +1,7 @@
+# Operations
+
+> **Stub.** The old manual was retired in the phase-1 docs restructure. This
+> document will be rewritten as an agent-facing guide — what the subsystem is
+> for, how to work on it, and what it must never do — once the ideas in
+> [ethos.md](../ethos.md) settle. The prior text lives in git history as
+> `docs/operations.md`.

package/documentation/operator-ui.md

@@ -0,0 +1,7 @@
+# Operator UI
+
+> **Stub.** The old manual was retired in the phase-1 docs restructure. This
+> document will be rewritten as an agent-facing guide — what the subsystem is
+> for, how to work on it, and what it must never do — once the ideas in
+> [ethos.md](../ethos.md) settle. The prior text lives in git history as
+> `docs/operator-ui.md`.

package/documentation/request-admission.md

@@ -0,0 +1,7 @@
+# Request admission
+
+> **Stub.** The old manual was retired in the phase-1 docs restructure. This
+> document will be rewritten as an agent-facing guide — what the subsystem is
+> for, how to work on it, and what it must never do — once the ideas in
+> [ethos.md](../ethos.md) settle. The prior text lives in git history as
+> `docs/request-admission.md`.

package/documentation/storage-and-credentials.md

@@ -0,0 +1,54 @@
+# Storage and credentials
+
+The core `KVStorage` seam supports `get`, `set`, and `delete`; adapters may also
+implement `list(prefix)`. Named access tokens require listing because every
+token is an independent record rather than one shared, race-prone manifest.
+The built-in memory and file adapters implement it, as does the Cloudflare KV
+example.
+
+Connectors may declare an operator-managed `credential` slot. When
+`credentials.encryptionKey` is configured, Connecta encrypts values in the
+deployment storage and exposes read-only access only through that connector's
+`ctx.credential`. Values, masked values, call arguments, and raw errors never
+enter model-facing recovery responses or activity records.
+
+Proactive credential liveness probing was **removed in 0.9** by ethos decision
+([#179](https://github.com/zackbart/connecta/issues/179)). The vault, local
+credential-shape drift detection, and operator-triggered credential tests remain.
+
+Credentials fail at use. A typed `auth_required` response directs the agent to
+`authorize_connector`, which returns one of the recovery modes documented in
+[meta-tools](./meta-tools.md#authorization-recovery). A declared slot with a
+configured vault returns a secret-free `/credentials` handoff. A missing vault
+returns `recovery: "unavailable"` and names `credentials.encryptionKey`;
+Connecta also warns at startup.
+
+Credential mutation is intentionally narrower than MCP access:
+
+- a static bearer may call tools and receive the operator handoff, but it
+  cannot write credentials;
+- only an admitted Clerk user may use the same-origin credential mutation
+  routes; and
+- saving, replacing, testing, or removing a value never returns that value.
+
+The vault is read for each call. Once an operator saves a replacement,
+the agent can retry immediately without restarting or redeploying Connecta.
+
+## Downstream OAuth
+
+`remoteMcp()` stores dynamic client registration, tokens, PKCE material, state,
+and the pending authorization URL in the connector's storage namespace.
+Registration and token envelopes are bound to the validated authorization
+server `issuer`. An unbound pre-0.9 envelope is upgraded in place on its first
+issuer-aware read, preserving the existing grant.
+
+If later discovery resolves a different issuer, Connecta does not send the old
+client identifier or tokens to it. The provider publishes a new generation
+epoch, makes every older credential namespace unreadable, cleans up the retired
+values, and lets the SDK begin registration and authorization again. The same
+epoch fence prevents an older isolate or late token exchange from resurrecting
+the retired grant.
+
+The OAuth callback verifies the one-shot `state` first, then hands the complete
+query string—including RFC 9207 `iss`—to the SDK transport. One-shot state,
+verifier, and pending URL are cleared only after a successful exchange.

package/ethos.md

@@ -0,0 +1,132 @@
+# 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.
+
+## 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.
+- **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.
+- **Two equal ways in.** `remoteMcp()` proxies a downstream MCP server;
+  `api()` hand-writes a deliberate tool surface over a plain HTTP API. Both
+  come out identical: same addresses, same catalog, same safety rules.
+- **Every meta-tool earns its keep**, and the bar has gone up. The default
+  answer to "agents need X" is the program surface: a capability has to be
+  shown inexpressible through it before it earns a top-level tool, and one
+  that isn't worth its context cost still goes. Seven tools counting
+  `execute_code` where a deployment has an executor, which is what a model
+  sees by default; nine where it doesn't
+  ([#224](https://github.com/zackbart/connecta/issues/224)).
+- **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.
+- **An executor is the assumed posture.** The primary surface is a program, so
+  the deployment connecta is written toward has one — a Dynamic Worker on
+  Cloudflare, QuickJS behind its optional-peer subpath on Node. Configuring one
+  is what selects the code-first surface; executor-free stays supported as
+  compatibility, not as an equal citizen. Packaging is unchanged: assumed is
+  about defaults, never about dependencies.
+- **Observable, never administrable.** Operator pages show connector status,
+  masked credentials, and payload-free activity. They can rotate a secret;
+  they cannot add a connector, change policy, or alter what an agent can call.
+
+## What this isn't
+
+- **Not a platform.** No runtime connector registration, no admin UI that
+  changes behavior, no policy engine, no approvals, no pauses.
+- **Not a schema ingester.** No OpenAPI or GraphQL → tools. Generated tool
+  sprawl is the disease the meta-tools treat, not a feature to add.
+- **Not multi-tenant.** No accounts dimension, no per-user credential store,
+  no org hierarchy. Two accounts on one service are two connector instances.
+- **Not 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 are stored safely and fail loudly at use;
+  connecta doesn't probe them behind your back.
+- **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.
+
+## Decisions
+
+The record of shapes considered and refused. Proposing one again is allowed;
+proposing one without a new argument is not.
+
+| 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 |
+| Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
+| Runtime connector registration | refused | config-as-code is the security model |
+| Protocol sessions & server push | refused | stateless per request |
+| Resources & prompts aggregation | refused | tools only |
+| 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)) |
+| 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 |
+| 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 (the exploration estimated ~32%, the shipped fold measures 19.6% — see the consolidation row), 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)) |
+| Code-first as the user-facing default | accepted | owner decision, 2026-07-30: "we don't need a deploy time flip, I'm the only one who uses it… We already decided it's good let's just do it." One operator, one deployment, and the exploration plus the smoke runs were enough judgment for him; the gate below was written for a user base connecta does not have ([#224](https://github.com/zackbart/connecta/issues/224)) |
+| The repeated per-model eval as the flip's gate | removed | it decided a question the owner has now decided himself; [`eval/code-first-gate`](./eval/code-first-gate/README.md) remains as measurement — the arms are real deployment shapes and it still reports which surface performs — but nothing waits on its verdict ([#222](https://github.com/zackbart/connecta/issues/222)) |
+| Surface consolidation to seven tools | accepted | folding `list_connectors`, `describe_tools`, and `batch_call` into the program surface deletes the overlapping routing choice between direct calls, batches, discovery, and execution; `call_tool` stays because a simple call is not cheaper through code. Measured at 19.6% fewer serialized definition bytes than the ten-tool shape the same deployment used to serve (10,675B → 8,587B), correcting the exploration's ~32% ([#224](https://github.com/zackbart/connecta/issues/224)) |
+| Executor-assumed posture | accepted | the primary surface is a program, so a deployment without an executor can only ever be the compatibility shape; packaging invariants are untouched ([#224](https://github.com/zackbart/connecta/issues/224)) |
+| Classic surface retention | accepted | what an executor-free deployment necessarily serves, the rollback path, and the eval's control arm; `surface: "classic"` alongside an executor is the only knob, and whether classic is ever removed is a separate future decision ([#224](https://github.com/zackbart/connecta/issues/224)) |
+| 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)) |
+| 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)) |
+
+## 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.
+
+- **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.
+- **No runtime admin.** If a browser could change what an agent can reach,
+  that feature is a non-goal wearing a disguise.
+- **Structural mistakes throw at construction.** A deployment that boots into
+  the wrong shape is worse than one that refuses to boot.
+
+---
+
+Connecta began as a radical simplification of
+[executor](https://github.com/UsefulSoftwareCo/executor). The table above is
+the record of that simplification holding.

package/examples/node/README.md

@@ -0,0 +1,53 @@
+# connecta — Node repository example
+
+This example runs against the current package source. For an independently
+installable deployment, use the root initializer instead:
+
+```sh
+npx @zackbart/connecta init my-connecta
+```
+
+From the package repository, run this example with:
+
+```sh
+npm install
+CONNECTA_TOKEN=dev-token npx tsx examples/node/src/index.ts
+```
+
+It serves the prescribed seven-tool code-first surface: `execute_code` in a
+bounded QuickJS child plus the six explicit boundary tools.
+
+- MCP endpoint: `http://localhost:8787/mcp`, with
+  `Authorization: Bearer dev-token`
+- Operator pages: Connections at `http://localhost:8787/`, Credentials at
+  `/credentials`, and Activity at `/activity` (paste the same token; this
+  bearer-only example cannot manage credentials)
+- Health: `http://localhost:8787/health`
+
+`PORT` defaults to `8787`; `CONNECTA_TOKEN` is required. Use a long random
+value outside this local example.
+
+## The deployment contract
+
+Keep this deployment small:
+
+- Edit `src/index.ts` to change connectors, auth, storage, and the public URL.
+- Keep `executor: quickJsExecutor()` unless you deliberately want the classic
+  compatibility surface.
+- Keep secrets in environment variables or an external secret store. Never put
+  tokens in `src/index.ts`, connector guides, or committed JSON.
+- Add application code only when implementing a deliberate `api()` connector.
+  Do not copy Connecta internals into the deployment.
+- Run the repository's `npm run check` after a package change.
+
+`fileStorage("./.connecta-state.json")` persists downstream OAuth tokens and
+tool catalogs across restarts. `memoryStorage()` is sufficient only when the
+deployment needs neither. Add `remoteMcp(...)` entries for downstream MCP
+servers or `api(...)` connectors for HTTP APIs you deliberately expose.
+Downstream OAuth also requires `publicUrl` to be an origin the browser can
+reach.
+
+Docker packaging of the same code-first shape is
+[repository-only](https://github.com/zackbart/connecta/tree/main/examples/docker).
+The standalone template used by the initializer is in
+[`../../templates/node/`](../../templates/node/).

package/examples/node/src/index.ts

@@ -0,0 +1,73 @@
+/**
+ * connecta on Node.
+ *
+ * One MCP endpoint aggregating two in-code HTTP API connectors behind the
+ * seven-tool code-first surface (execute_code in a QuickJS/WASM sandbox plus the
+ * six explicit tools), guarded by a static bearer token, with OAuth/cache state
+ * on disk.
+ *
+ * Run:
+ *   CONNECTA_TOKEN=dev-token npx tsx examples/node/src/index.ts
+ *   # then point an MCP client at http://localhost:8787/mcp with
+ *   #   Authorization: Bearer dev-token
+ */
+import { api, bearerToken, createConnecta } from "@zackbart/connecta";
+import { fileStorage, listen } from "@zackbart/connecta/node";
+import { quickJsExecutor } from "@zackbart/connecta/quickjs";
+
+const token = process.env.CONNECTA_TOKEN;
+if (!token) {
+  throw new Error(
+    "CONNECTA_TOKEN is required. Refusing to start without inbound auth.",
+  );
+}
+const port = Number(process.env.PORT ?? 8787);
+
+const connecta = createConnecta({
+  // fileStorage persists downstream-OAuth/cache state across restarts.
+  // Swap for memoryStorage() if you don't need persistence.
+  storage: fileStorage("./.connecta-state.json"),
+  auth: bearerToken(token, { subjectId: "operator" }),
+  // Downstream OAuth callbacks use this deployment origin.
+  publicUrl: `http://localhost:${port}`,
+  // Code mode: QuickJS runs model-written JS in a bounded disposable child.
+  // This line is also what selects the seven-tool code-first surface; remove it
+  // to serve the nine classic meta-tools instead.
+  executor: quickJsExecutor(),
+  connectors: [
+    api("time", {
+      description: "Time — current timestamp",
+      tools: [
+        {
+          name: "get_now",
+          description: "Return the current time as an ISO 8601 timestamp.",
+          inputSchema: { type: "object", properties: {} },
+          annotations: { readOnlyHint: true },
+          handler: async () => ({ now: new Date().toISOString() }),
+        },
+      ],
+    }),
+    api("text", {
+      description: "Text — string utilities",
+      tools: [
+        {
+          name: "upper",
+          description: "Uppercase the given text.",
+          inputSchema: {
+            type: "object",
+            properties: { text: { type: "string" } },
+            required: ["text"],
+          },
+          annotations: { readOnlyHint: true },
+          handler: async ({ text }: { text: string }) => ({
+            text: text.toUpperCase(),
+          }),
+        },
+      ],
+    }),
+  ],
+});
+
+listen(connecta, port);
+
+console.log(`connecta listening on http://localhost:${port}/mcp`);