@zackbart/connecta 0.18.1 → 0.18.3

package/documentation/meta-tools.md

@@ -78,21 +78,35 @@ 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. Bounded plain-object schemas also expose `inputKeys`,
+`includeSchemas: "compact"` adds each match's input and any provider-declared
+output shape. When the provider declared none but an earlier successful call
+learned one, the same field carries the open observed schema beside
+`outputSchemaSource: "observed"`. That marker matters: observed fields and broad
+JSON types are routing evidence, not a provider contract, and every object field
+remains optional and open to unseen names. A provider declaration always wins.
+Bounded plain-object schemas also expose `inputKeys`,
 `requiredInputKeys`, and `outputKeys`; a zero-input object keeps
 `requiredInputKeys: []`, while an output object with no declared properties
 omits `outputKeys`. A truncated shape omits its corresponding list rather than
 repeating a large partial inventory. Matches carry declared
 behavior annotations. Lexical rank is only one signal: select a candidate whose
 required inputs are available, whose schema is complete enough for the call,
-and whose safety and declared outputs fit the work. A reducer uses `outputKeys`
+and whose safety and available outputs fit the work. A reducer uses `outputKeys`
 before inspecting the value; it does not assume a collection is named `items`
 or `results`. When that shape is sufficient, call the returned address directly. Reserve schema
 expansion through `connecta.describe` for a search without schemas, an
 ambiguous compact shape, or exact
 constraints that require `format: "json"`.
 
+Observed schemas originate no provider traffic. A successful explicitly
+read-only call the user already made contributes names and broad types after
+Connecta unwraps the result. Arguments, scalar values, raw results, code,
+credentials, and errors are not retained, though property names may themselves
+be user-authored. Shapes merge in a 256-entry runtime cache for 24 hours under
+the exact tool definition that produced them. A changed definition, process
+restart, or Worker isolate eviction starts cold. Observation cannot fail the
+call, and the declared catalog remains the fallback.
+
 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
@@ -310,6 +324,11 @@ handoff:
   declared credential label and field names/guidance; or
 - `unavailable`: an honest deployment/configuration message.
 
+The class follows what the connector declares, not how it was authored: a
+`remoteMcp()` connection using `auth: { type: "credential" }` declares a slot
+and no OAuth flow, so it lands in `operator_config` beside every `api()`
+credential.
+
 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

package/documentation/mixpanel.md

@@ -50,6 +50,25 @@ password, not ordinary configuration. Mixpanel currently labels service-account
 MCP authentication beta. Prefer OAuth unless the deployment is intentionally
 headless.
 
+The same service account can arrive from `/credentials` instead, and there the
+operator pastes the readable pair rather than an encoded blob:
+
+```ts
+mixpanel("automation_analytics", {
+  purpose: "Headless release-health reporting",
+  auth: { type: "credential" },
+});
+```
+
+The slot renders as "Service account" and takes `username:secret`. Connecta
+base64-encodes it and sends Mixpanel's documented `Bearer Basic` framing, so the
+operator never has to encode anything by hand. **The two paths take different
+strings:** the `headers` example above wants the already-encoded blob
+(`echo -n "username:secret" | base64`), and this one wants the plaintext pair.
+Migrating from one to the other means decoding, not copying. Until a value is
+saved the connector is present and reports `auth_required`. See
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
+
 ## Conditional input contracts
 
 Mixpanel's hosted descriptions enforce three cross-field conditions that its

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 |
@@ -247,8 +247,10 @@ in.
 | `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 |
 | `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-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 |
+| `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` / `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 |
 | `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 |

package/documentation/provider-conventions.md

@@ -412,33 +412,49 @@ retries.
 
 OAuth per connector instance, stored in connector-scoped storage, is the
 default. The provider's own headless credential — a personal API key, a
-restricted key, a service account — is supported through explicit `headers`
-auth, documented as a secret rather than configuration, and paired with the
-narrowest mode the deployment can use. `requireHttps` is set. Recovery from an
-expired authorization is the ordinary `auth_required` → `authorize_connector`
-route.
+restricted key, a service account — is supported two ways: explicit `headers`
+auth, documented as a secret rather than configuration, and `{ type:
+"credential" }`, which declares an operator slot and takes the same secret from
+`/credentials` instead. Either way it is paired with the narrowest mode the
+deployment can use, and the framing matches the provider's *published* contract
+for the MCP endpoint — not a convention borrowed from that provider's other
+APIs, and not this repository's earlier example, which is the same claim wearing
+a circle. `requireHttps` is set. Recovery from an expired authorization is the
+ordinary `auth_required` → `authorize_connector` route, which returns the
+consent URL for OAuth and the `/credentials` handoff for a declared slot.
 
 *Why:* one route back from an expired credential is what keeps a failed call
 from becoming an abandoned task. *Cost:* wrong-tool selection.
 
-### P10 — There is no credential test; the equivalent check happens at construction
+### P10 — Nothing probes a credential unasked; a declared slot may be tested on request
 
-A proxy declares no operator credential slot and implements neither
-`testCredential` nor `testCredentials`. `remoteMcp()` has no `credential`
-option, and neither shape of proxy credential is vault-managed: OAuth lives in
+A proxy declares an operator credential slot exactly when its auth is `{ type:
+"credential" }`, and then it inherits H12 whole
+([#439](https://github.com/zackbart/connecta/issues/439)). The other two shapes
+declare no slot and hold nothing for the credentials page: OAuth lives in
 connector-scoped storage and is exercised by the authorization flow itself,
-while a headless key arrives as deployment configuration in `headers`, so there
-is nothing for the operator credentials page to hold or test. H12's guarantee is
-still owed, and a proxy pays it in two other places: construction throws when a
-recognizable credential contradicts the declared mode (P4), and a dead or
-revoked credential fails loudly at use as `auth_required` with the
-`authorize_connector` route attached (P9). Connecta never probes a downstream to
-see whether a credential is still alive — that shape is `removed` in the ethos
-([#179](https://github.com/zackbart/connecta/issues/179)). A provider that later
-does take a vault-managed secret inherits H12 whole.
+while a `headers` key arrives as deployment configuration. H12 is owed in every
+shape, and a proxy pays it in two places that do not depend on a slot:
+construction throws when a recognizable credential contradicts the declared mode
+(P4) — a check a vault-managed key cannot get, because there is nothing in the
+deployment file to read — and a dead, revoked, or absent credential fails loudly
+at use as `auth_required` with the `authorize_connector` route attached (P9).
+
+`testCredential` exists only behind the operator-pressed Test action on
+`/credentials`, and only for a declared slot. It connects with the stored value
+and reports how many tools the downstream served, which is the whole honest
+check for a proxy: which account, project, or mode a key reaches is the
+provider's answer, not Connecta's. That is not the shape
+[#179](https://github.com/zackbart/connecta/issues/179) removed. What was
+removed is the *unasked* probe — a liveness call every deployment pays on a
+schedule or at startup to answer a question only a misconfigured one has. A
+human clicking Test has asked, `api()` has had that button since the vault
+existed, and nothing here probes on its own: no timer, no warmup, no check on
+the read path.
 
 *Why:* an unasked-for liveness probe spends a call on every deployment to answer
-a question only a misconfigured one has. *Cost:* result size.
+a question only a misconfigured one has; a requested one spends a call the
+person requesting it chose. *Cost:* result size.
 
 ### P11 — Connecta classifies the transport; the downstream owns the tool error
 
@@ -666,8 +682,8 @@ than by reading:
 | P4 | endpoint or mode option exists, with the documented default (or no default, where none is safe) |
 | P5 | reads and writes are named lists; an unlisted tool resolves to not-read-only; a reviewed destructive name beats a contradictory `readOnlyHint: true` |
 | P6, P8 | the guide contains the catalog-varies note and the id-resolution rule |
-| P9 | `auth` defaults to OAuth and `requireHttps` is set |
-| P10 | no `credential`, `testCredential`, or `testCredentials` on the wrapper; the mode/key contradiction throws at construction instead |
+| P9 | `auth` defaults to OAuth and `requireHttps` is set; a credential-auth shape frames the key the way the provider's MCP documentation does |
+| P10 | a `credential` slot exactly when auth is `{ type: "credential" }`; `testCredential` runs only from the operator's Test action, never on a timer or a read path; the mode/key contradiction still throws at construction |
 | P11 | an authorization failure surfaces as `auth_required`; a downstream tool error is returned unchanged, with no code chosen from its prose |
 | P12 | a declared budget matches a citable documented limit, or the absence is justified in the guide |
 | P13 | classification lists are maintained in one place per provider and built into the manifest the wrapper classifies from, so the drift check compares against the same fact the caller is served |

package/documentation/revenuecat.md

@@ -80,6 +80,26 @@ connectors: [
 ]
 ```
 
+Neither key has to be a runtime secret. Declare the slot instead and each
+connector's key is pasted, tested, and rotated on `/credentials`:
+
+```ts
+connectors: [
+  revenuecat("bepresent_ios", {
+    purpose: "Subscription state for the BePresent iOS project",
+    auth: { type: "credential", credential: { label: "API v2 secret key" } },
+  }),
+  revenuecat("biblescroll", {
+    purpose: "Subscription state for the BibleScroll project",
+    auth: { type: "credential", credential: { label: "API v2 secret key" } },
+  }),
+]
+```
+
+Two ids, two slots, two single-project catalogs — the `credential` option is
+optional, and omitting it gives the same "API v2 secret key" label. See
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
+
 That is config-as-code doing what an account model would otherwise do: one
 credential per connector, each with its own catalog, storage namespace, health,
 and admission counters. The two share a title, because Connecta cannot know
@@ -116,7 +136,9 @@ Keys are prefixed `sk_`, are issued read-only or write-enabled, and can be
 revoked at any time by a project Admin. RevenueCat's setup guidance is to "use
 a write-enabled key if you plan to create/modify resources"; "a read-only key
 works if you only need to view data". Keep the key in the runtime's secret
-store, never in the deployment file.
+store, never in the deployment file — or declare
+`auth: { type: "credential" }` and let the operator hold it in the vault
+instead, which is the shape the two-project example above uses.
 
 **Connecta does not filter writes for a read-only key.** It has no way to tell
 which kind a key is without spending a call, so every write in the catalog is

package/documentation/storage-and-credentials.md

@@ -34,6 +34,61 @@ Credential mutation is intentionally narrower than MCP access:
 The vault is read for each call. Once an operator saves a replacement,
 the agent can retry immediately without restarting or redeploying Connecta.
 
+## A remote MCP connector's static credential
+
+`remoteMcp()` accepts a third auth shape beside OAuth and literal headers:
+
+```ts
+remoteMcp("revenuecat_bepresent", {
+  url: "https://mcp.revenuecat.ai/mcp",
+  auth: { type: "credential", credential: { label: "API v2 secret key" } },
+});
+```
+
+The connector, its endpoint, and the credential *slot* stay declared in code;
+only the secret arrives through `/credentials`. That is the same boundary
+`api()` has always had, and the reason a project-wide key no longer has to be a
+Worker secret or an environment variable
+([#439](https://github.com/zackbart/connecta/issues/439)).
+
+`header` defaults to `Authorization` and `scheme` to `Bearer`. `scheme: null`
+sends the stored value verbatim, which is what Linear's personal API keys
+expect. A scheme whose last token is `Basic` declares HTTP Basic credentials, so
+the stored `user:secret` is base64-encoded first — `"Basic"` produces
+`Basic <base64>`, and Mixpanel's documented `"Bearer Basic"` produces
+`Bearer Basic <base64>`. There is one reserved `value` field and no multi-field
+header composition: named `credential.fields` are refused at construction.
+
+A stored value is checked before anything frames it: a line break or other
+control character — what a key pasted across two lines leaves behind — is
+refused as `auth_required` with a message naming the problem and never the
+value. That check exists because the runtime that rejects such a header quotes
+the whole offending value back in its `TypeError`, and that message would
+otherwise reach the agent, the operator page, and the activity log. Behind it,
+any error whose message quotes the credential or the header it became is
+discarded whole and replaced; nothing is masked or truncated, because a
+redaction that keeps part of a secret is still a leak.
+
+An empty slot is not a boot failure and not a silently absent connector. The
+connector is present, its status reads `auth_required`, calls fail with the same
+typed error a missing OAuth grant produces, and `authorize_connector` returns
+the `/credentials` handoff. With no vault configured at all, the failure names
+`credentials.encryptionKey`, and Connecta already warned at startup.
+
+The vault is read before any cached downstream client is trusted, so a rotation
+lands on the next call rather than the next deploy. Connecta compares a SHA-256
+digest of the value the cached client connected with; a different digest closes
+that client and reconnects. The plaintext lives in the connect attempt's local
+scope, never on connector state, never in a log, and never in a status or error
+message. A cleartext `http://` destination warns at construction here exactly as
+it does for literal headers — who owns the secret changed, not what the wire
+carries.
+
+`/credentials`' Test action connects with the stored value and reports how many
+tools the downstream served. That is the whole honest check for a proxy: which
+account, project, or mode the key reaches is the provider's answer, not
+Connecta's.
+
 ## Downstream OAuth
 
 `remoteMcp()` stores dynamic client registration, tokens, PKCE material, state,

package/documentation/stripe.md

@@ -95,12 +95,32 @@ Use a restricted key, not a secret key, and scope it to the operations the
 agent actually needs; Stripe's own guidance is to "limit your agent's access to
 exactly the functionality it requires". Keep it in the runtime's secret store.
 
+The same key can come from `/credentials` instead:
+
+```ts
+stripe("stripe_sandbox", {
+  mode: "sandbox",
+  purpose: "Automated billing rehearsal",
+  auth: { type: "credential" },
+});
+```
+
+`mode` is required either way — a static key answers for exactly one
+environment and cannot report which. The literal-header form is checked against
+the key's `_live_`/`_test_` prefix at construction; an operator-managed key is
+not in the deployment file to read, so the declared mode stands alone and a key
+pointed at the other environment fails at Stripe. Declare the mode carefully:
+that check is the one guard Connecta can offer, and this shape does not get it.
+See
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
+
 Organization accounts in one OAuth session are not Stripe Connect connected
 accounts. Connect platforms can act as a connected account with
 `connectedAccount`, which adds Stripe's documented `Stripe-Account` header at
 connector construction. Stripe does not support OAuth for connected-account
-calls, so this requires a restricted key through `headers` auth and throws
-otherwise:
+calls, and `Stripe-Account` is a second header beside the credential's own,
+which the operator-managed shape does not assemble — so this requires a
+restricted key through `headers` auth and throws otherwise:
 
 ```ts
 stripe("merchant_42", {

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.1 | 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.18.3 | 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.1
+npm pkg set dependencies.@zackbart/connecta=0.18.3
 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.1 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.18.3 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.1 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.18.3 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,34 @@ 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.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
+it. The release adds a third `auth` shape to `remoteMcp()` and every maintained
+hosted connection — `{ type: "credential" }` — under which the connector
+declares an operator slot on `/credentials` and reads the pasted value on each
+request. A deployment carrying a static key as a runtime secret
+(`auth: { type: "headers", headers: { Authorization: env.KEY } }`) keeps
+working unchanged; moving it behind `/credentials` is an edit to the connector's
+`auth` and one paste on the operator page, and needs `credentials.encryptionKey`
+configured — a deployment without a vault gets a startup warning and
+`recovery: "unavailable"` at use for that connector, not a boot failure. Two
+Linear notes: the `headers` example in `documentation/linear.md` now shows
+`Bearer ${key}` (Linear's MCP server documents that framing), and the credential
+shape sends `Bearer` by default; a `headers` connector already sending a bare
+key is untouched.
+
 ### 0.18.0 → 0.18.1
 
 Nothing throws, no option moves, and every deployment crosses this on the

package/ethos.md

@@ -111,11 +111,11 @@ proposing one without a new argument is not.
 | 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)) |
 ## 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 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.
@@ -131,6 +131,7 @@ Breaking one is not a bug fix — it is a design change wearing a disguise.
   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
@@ -145,5 +146,4 @@ Breaking one is not a bug fix — it is a design change 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/worker/src/index.ts

@@ -123,6 +123,11 @@ function build(env: Env) {
         auth: {
           type: "headers",
           headers: { Authorization: `Bearer ${env.DOWNSTREAM_TOKEN}` },
+          // The vault-backed alternative for a downstream that authenticates
+          // with a static key: the operator pastes it at /credentials and
+          // rotates it there, so no Worker secret holds it.
+          //   type: "credential",
+          //   credential: { label: "Notion internal integration token" },
         },
       }),
       api("echo", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.18.1",
+  "version": "0.18.3",
   "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.",

package/templates/node/package.json

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