@zackbart/connecta 0.16.0 → 0.17.0

package/documentation/operations.md

@@ -8,15 +8,27 @@ needs most.
 
 `createConnecta(config)` returns `{ fetch, registry, close }`. `fetch` takes
 the Workers `(request, env, ctx)` signature; passing `ctx` through is what lets
-connecta hand deferred work — best-effort activity writes — to `ctx.waitUntil`
-instead of losing it when the response returns.
+connecta hand deferred work to `ctx.waitUntil` instead of losing it when the
+response returns. That work is best-effort activity writes and the bounded
+refresh an agent catalog read already demanded while it served a complete stale
+entry. Node's adapter tracks the same promises and drains them on shutdown.
 
 An `executor` is required. A deployment without one throws at construction
 rather than serving a smaller surface
 ([#273](https://github.com/zackbart/connecta/issues/273)): Node uses
 `quickJsExecutor()` from `@zackbart/connecta/quickjs`, Workers use
 `new DynamicWorkerExecutor({ loader: env.LOADER })` from
-`@cloudflare/codemode`.
+`@cloudflare/codemode`. The Worker executor must stay loader-only: `bindings`,
+`modules`, and `globalOutbound` grant ambient guest authority.
+
+Both executor packages are optional peers: they never install with connecta,
+and a deployment installs the one its runtime needs. The manifest publishes the
+range each release supports — `^0.32.0` for `quickjs-emscripten`,
+`^0.4.4 || ^0.5.0` for `@cloudflare/codemode` — so npm answers the version
+question at install time rather than leaving a deployment to discover the skew
+when a program runs ([#376](https://github.com/zackbart/connecta/issues/376)).
+The version this repository tests against is one the published range admits,
+and `test/package-surface.test.ts` fails if the two ever drift apart.
 
 There are exactly two deployment shapes.
 [`templates/node/`](../templates/node/) is what `connecta init` copies — the
@@ -75,7 +87,7 @@ optional.
 | `discovery.concurrency?` | 4 | connector catalogs/status probes in flight at once |
 | `discovery.catalogTtlSeconds?` | 300 | fresh TTL for cached tool lists |
 | `discovery.persistCatalog?` | true | persist serializable catalogs as a manifest plus revision-addressed chunks |
-| `discovery.staleCatalogSeconds?` | 3600 | how long an expired catalog stays usable as a failure fallback |
+| `discovery.staleCatalogSeconds?` | 3600 | how long a complete expired catalog stays usable for agent SWR and as a refresh-failure fallback |
 | `discovery.probeTimeoutMs?` | 30_000 | per-connector deadline for catalog fan-out; a timed-out connector degrades alone. Not a tool-call deadline |
 | `calls.defaultTimeoutMs?` | **unset (opt-in)** | deadline for calls that pass no `timeoutMs`. Bounds one attempt, so retries can still extend total duration |
 | `calls.maxResultBytes?` | 50_000 | inline result cap before truncation and `get_result` paging; a connector may override it. Invalid values warn and fall back |
@@ -108,9 +120,13 @@ deployment repository
 ```
 
 An upgrade is an intentional dependency change followed by a normal build.
-Instances must not share KV namespaces, D1 databases, secrets, or encryption
-keys. Keeping deployment configuration private is sensible even though this
-package is public.
+Doing it to a deployment somebody else generated — reading its pin, diffing it
+against the template generation it came from, and crossing the version
+boundaries that break construction — is [upgrading](./upgrading.md), which is
+written for the agent sitting inside that deployment rather than inside this
+repository. Instances must not share KV namespaces, D1 databases, secrets, or
+encryption keys. Keeping deployment configuration private is sensible even
+though this package is public.
 
 ## Verification
 
@@ -118,7 +134,7 @@ package is public.
 
 | Script | What it gates |
 | --- | --- |
-| `check:docs` | local Markdown targets and fragments, guide and ethos size caps, duplicate heading anchors, a resurrected `docs/`, stale manual references |
+| `check:docs` | local Markdown targets and fragments — including the `github.com` and `raw.githubusercontent.com` URLs that point back into this repository — guide and ethos size caps, duplicate heading anchors, a resurrected `docs/`, stale manual references |
 | `check:operator-ui` | the committed browser bundle matches its source, byte for byte |
 | `check:lint` | Oxlint's correctness category only — style is authored, not enforced |
 | `check:unused` | Knip's unused-export and dependency gate |
@@ -130,11 +146,38 @@ package is public.
 `npm run release:check` adds `check:security` (`npm audit --omit=dev
 --audit-level=moderate`) and `check:package`, and is what CI runs on every push
 and pull request. `check:package` packs the tarball, asserts the required files
-are in it and that no platform-specific implementation or unshippable path
-leaked in, derives the shipped guide list from which guides still carry a stub
-marker, checks that every packed doc's `documentation/` link resolves to
-something the tarball carries, and then runs `connecta init` and builds and
-runs the generated deployment's own container.
+are in it and that no unshippable path leaked in — including any
+Cloudflare-named connector or storage path (`connectors/cloudflare`,
+`storage/cloudflare`) anywhere in the artifact, `dist/` and `examples/` alike —
+derives the shipped guide list from which guides still carry a stub marker,
+hands the packed path list to `scripts/check-packed-links.mjs`, and then runs
+`connecta init` and builds and runs the generated deployment's own container.
+
+That last step enforces the packed-link policy, which is one sentence: **every
+relative link in shipped Markdown must resolve to a path the tarball carries,
+and a target that is repository-only is cited as an absolute
+`https://github.com/zackbart/connecta/blob/main/...` URL** (the
+`raw.githubusercontent.com` form for an image, which is how the README hero
+still renders on npmjs.com). The tarball is built output, not a checkout: it
+carries no `eval/`, `test/`, `scripts/`, or `assets/`, so a relative pointer
+into any of them is a dead end for the reader who installed the package, and
+the fix is never to ship those directories — that would undo the trim of
+[#346](https://github.com/zackbart/connecta/issues/346). A repository URL keeps
+the citation verifiable in both directions: an outside reader can follow it, and
+`check:docs` resolves it back to the checkout and fails when the cited file
+moves ([#378](https://github.com/zackbart/connecta/issues/378)). `CHANGELOG.md`
+is exempt from both gates, because release notes quote the paths that existed
+when they shipped.
+
+The Worker example ships in the tarball, its Cloudflare KV and D1 adapters
+included: it is the Workers starting template a consumer copies. That is not a
+hole in the published surface, because nothing under `examples/` appears in the
+`exports` map — every export target resolves into `dist/`, so those adapters
+are reference source rather than an importable subpath. They also clear the
+platform-specific gate above on their names (`cloudflare-kv.ts`,
+`d1-activity.ts`) rather than by exemption: that gate is a blunt pattern over
+the whole artifact, so an example file renamed into `storage/cloudflare` would
+fail the pack even though nothing about the published surface had changed.
 
 Two more runners are deliberately outside `check`:
 
@@ -181,7 +224,7 @@ in.
 | `catalog.test.ts` | lexical ranking and the compact schema renderer — `const`, `allOf` beside siblings, `$ref`, the depth limit, per-schema caching, and 2020-12 keyword compatibility |
 | `clerk.test.ts` | protected-resource metadata, the browser sign-in config, OAuth and session tokens, cached best-effort activity labels with their caps, the hand-applied `azp` rejection, and the `allowedDomains` allowlist including every lookalike that must not be repaired into a match |
 | `cloudflare-provider.test.ts` | `cloudflare()` construction, tool surface, request building, projections, typed failures, and credential test |
-| `cloudflare-registry.test.ts` | the same provider inside a real deployment: discovery, addressing, and admission through the registry |
+| `cloudflare-registry.test.ts` | the same provider inside a real deployment: discovery including compact page bounds, addressing, and admission through the registry |
 | `code-first-surface.test.ts` | the seven-tool surface itself — an executor required and both runtime configurations named, every removed option and removed top-level tool refused, and `connecta.ui` findable before an agent chooses catalog search |
 | `codemode-compat.test.ts` | the `Executor` seam staying structurally compatible with `@cloudflare/codemode`'s `DynamicWorkerExecutor`, enforced by `tsc` |
 | `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds failing construction, and one complete migration error for legacy own-properties |
@@ -189,28 +232,28 @@ in.
 | `d1-activity-example.test.ts` | the Worker example's deployment-owned D1 activity store: actor namespace round-trip, payload-free friction reconstructed from the persisted code, and agreement with the package's friction table |
 | `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and races, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality, bounded diagnostics, and HTML escaping |
 | `errors.test.ts` | `ConnectorCallError` codes, retryable defaults and overrides, `retryAfterMs` round-trip, typed-over-heuristic classification, `AbortError` as a retryable timeout, and framing errors |
-| `execute.test.ts` | the code-mode host bridge: identifier sanitization, MCP-result unwrapping, sandbox provider construction, fail-closed filtering of destructive and unannotated tools, and MCP/code-mode invocation parity |
+| `execute.test.ts` | the code-mode host bridge: identifier sanitization, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, fail-closed filtering of destructive and unannotated tools, and MCP/code-mode invocation parity |
 | `execute-emit.test.ts` | `connecta.emit` (M1–M10) — block validation, budgets, the provider, delivery after the result envelope on success only, and the defaults |
 | `execute-ui.test.ts` | `connecta.ui` (U1–U9) — validation, multiplicity and budget, the provider, `_meta` delivery, and the Apps shell |
 | `executor-admission.test.ts` | the portable bounded FIFO both pools use: active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown |
 | `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, and response handling |
-| `guest-api-contract.test.ts` | the executor-independent half of the guest API contract cases, including the serialized truncation envelope, capped logs, truncation reported as success, and an in-flight host call failing when the run ends |
+| `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, discovery, utility, batch, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
 | `linear-provider.test.ts` / `linear-registry.test.ts` | the Linear proxy's construction, classification, and guide; then the same connector inside a real deployment |
-| `meta-tools.test.ts` | the registry-backed meta-tools: bounded discovery with page and address maxima, concise and full descriptions, compact and JSON schemas, structured errors, `skills` and connector-guide selection, stored-credential drift, catalog-lookup health accounting, `fields` selection, truncation and `get_result` offset validation and character alignment, per-connector `maxResultBytes`, probe timeouts, and empty-query browse of an unavailable or unconfigured catalog |
-| `mixpanel-provider.test.ts` / `mixpanel-registry.test.ts` | the Mixpanel proxy, then the same connector inside a real deployment |
+| `meta-tools.test.ts` | the registry-backed meta-tools: bounded discovery with page and address maxima, concise and full descriptions, compact and JSON schemas with numeric and string constraints, structured errors, `skills` and connector-guide selection including paragraph-aware summaries and configured-summary construction bounds, stored-credential drift, catalog-lookup health accounting, `fields` selection including total and partial misses below nested arrays, truncation and `get_result` offset validation and character alignment, per-connector `maxResultBytes`, probe timeouts, and empty-query browse of an unavailable or unconfigured catalog |
+| `mixpanel-provider.test.ts` / `mixpanel-registry.test.ts` | the Mixpanel proxy, its conditional-input guide and complete reviewed schema-digest manifest, then the same connector inside a real deployment |
 | `notion-provider.test.ts` / `notion-registry.test.ts` | Notion's tool surface, request construction, lean projections, both pagination conventions, error mapping, and writes; then the connector in a real deployment |
 | `operator-boundary.test.ts` | the operator row of the decisions table, after every mutation route: authentication material managed without moving a declared structure, and the one honest exception — a credential write making a remote catalog appear, which is discovery arriving, not an operator editing the deployment |
 | `operator-store.test.ts` | `src/operator-ui/app/store.ts` against a fake browser: the Clerk listener, `gate()`, the generation fence, and the request path |
-| `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), 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 convention and result-cap warnings, address resolution, tool-cache TTL, and broken-connector isolation |
+| `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-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 |
-| `server.test.ts` | end-to-end `/mcp` (401 → initialize instructions → seven tools → usage skill → `call_tool`), the open routes, Clerk `.well-known` metadata with no network, and an end-to-end code-mode run |
+| `server.test.ts` | end-to-end `/mcp` (401 → initialize instructions → seven tools → usage skill → `call_tool`), the open routes, Clerk `.well-known` metadata with no network, an end-to-end code-mode run, and `waitUntil` reaching agent catalog reads through both `search_tools` and `execute_code` |
 | `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: every built-in answered ahead of connector routes inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
 | `startup-warnings.test.ts` | every construction-time `logger.warn` and, as importantly, the conditions that must *not* trigger one: open mode with a credential or OAuth connector, `publicUrl` unset beside OAuth, dropped branding and `uiAuth` URLs, a missing `verifyState`, a credential test-hook mismatch, and an unusable `calls.maxResultBytes` |
-| `stripe-provider.test.ts` / `stripe-registry.test.ts` | the Stripe proxy's endpoint modes and admission, then the connector in a real deployment |
-| `ui.test.ts` | the server shell and `/ui/*` routes and the app's pure state rules from `view.ts` — filtering, page routing and capability states, credential management, gated `/ui/data` with broken-connector isolation, and the URL safety gates |
+| `stripe-provider.test.ts` / `stripe-registry.test.ts` | the Stripe proxy's endpoint modes, admission, multi-account OAuth guidance, and no-guess account selection; then the connector in a real deployment |
+| `ui.test.ts` | the server shell and `/ui/*` routes and the app's pure state rules from `view.ts` — filtering, page routing and capability states, credential management, gated `/ui/data` with broken-connector isolation and registry-owned catalog-observation containment, and the URL safety gates |
 | `validate.test.ts` | `validateToolInput()` — a returned (not thrown) `invalid_args` naming the path, `additionalProperties: false` enforcement, per-schema validator caching, and an unusable schema passed through with one warning |
 
 ### Node-bound (`NODE_ONLY_SUITES`)
@@ -220,14 +263,15 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 
 | Suite | Covers | Why Node |
 | --- | --- | --- |
-| `deployment-shapes.test.ts` | the Worker as the only example, one Node template that is also its own container, the same source running locally and in the container, the full operator surface in both, a template that cannot start on its own `.env.example`, a Worker README naming every optional peer its entrypoint imports, and the initializer's `.gitignore` staying in step | walks the template and example trees with Node filesystem APIs |
-| `doc-links.test.ts` | the documentation checker itself — local file and fragment resolution, duplicate heading slugs, fenced-code exclusion, and useful failures | spawns the Node checker against filesystem fixtures |
+| `deployment-shapes.test.ts` | the Worker as the only example with a loader-only sandbox, one Node template that is also its own container, the same source running locally and in the container, the full operator surface in both, a template that cannot start on its own `.env.example`, a Worker README naming every optional peer its entrypoint imports, and the initializer's `.gitignore` staying in step | walks the template and example trees with Node filesystem APIs |
+| `doc-links.test.ts` | the documentation checker itself — local file and fragment resolution, repository URLs resolved back to the checkout, duplicate heading slugs, fenced-code exclusion, and useful failures | spawns the Node checker against filesystem fixtures |
 | `doctor-cli.test.ts` | `connecta doctor`'s executor line end to end — the sandbox the deployment reports is the one named, an unidentifiable executor gets an executor-neutral line, and a hostile name is bounded and stripped before it reaches a terminal | spawns the CLI against a Node HTTP deployment over real sockets |
-| `drift-check.test.ts` | the maintainer drift checker — recorded touched endpoints, a quiet revision bump, clear failures for an unavailable spec/manifest/credential, `$ref` traversal, and one well-formed row per endpoint | spawns the Node checker against filesystem fixtures |
+| `drift-check.test.ts` | the maintainer drift checker — hosted-provider credential framing, recorded touched endpoints, a quiet revision bump, clear failures for an unavailable spec/manifest/credential, `$ref` traversal, and one well-formed row per endpoint | spawns the Node checker against filesystem fixtures |
 | `file-storage.test.ts` | `fileStorage()` across instances, logical TTL plus physical pruning without clobbering a newer value, and corrupt-file quarantine | exercises the Node filesystem storage adapter |
-| `guest-api-contract-quickjs.test.ts` | the shared guest-contract cases on the real QuickJS executor | runs the contract cases on the Node QuickJS executor |
+| `guest-api-contract-quickjs.test.ts` | the shared guest-contract cases on the real QuickJS executor, including identical caught failure codes, its exact absent globals, and blocked runtime imports | runs the contract cases on the Node QuickJS executor |
 | `node.test.ts` | the `listen()` adapter propagating an HTTP client disconnect through the Web `Request` and the MCP handler into a program's connector call, releasing both admission permits | exercises the Node HTTP adapter over real TCP sockets |
-| `package-surface.test.ts` | the published boundary — built output shipped, only generic factories, platform storage kept in examples, Clerk and QuickJS behind optional subpaths, every provider independently importable, and the Cloudflare provider free of bare specifiers | walks the package tree with Node filesystem APIs |
+| `packed-links.test.ts` | the packed-link gate itself — shipped targets and repository URLs accepted, relative links into unshipped paths and directories rejected with the citation to write instead, reference definitions seen, fenced examples ignored, the changelog exempt | spawns the Node packed-link gate against filesystem fixtures |
+| `package-surface.test.ts` | the published boundary — built output shipped, the `exports` map carrying exactly the documented subpaths plus `./package.json`, only generic factories, platform storage kept in examples, Clerk and QuickJS behind optional subpaths, every provider independently importable, and the Cloudflare provider free of bare specifiers | walks the package tree with Node filesystem APIs |
 | `purity.test.ts` | the import-graph guardrail ([architecture](./architecture.md#import-graph-purity)) — the core stays Workers-clean | walks the source import graph with Node filesystem APIs |
 | `quickjs-child-entry.test.ts` | a missing QuickJS child entry failing before `fork()`, with the expected path and the bundler-externalization constraint | mocks Node child-process and filesystem APIs |
 | `quickjs-child-stderr.test.ts` | abnormal child exits retaining only an 8 KiB stderr tail, included in the parent-side diagnostic | mocks Node child-process streams |
@@ -235,13 +279,14 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | `quickjs-log-limits.test.ts` | bounded `console.*` capture — per-entry cut, cumulative character and transport budgets, escape-heavy floods preserving the guest result | runs the Node QuickJS child-process executor |
 | `suite-partition.test.ts` | this partition, including itself: every `*.test.ts` in exactly one list, stale entries and empty reasons refused | walks the test directory to guard the partition |
 | `template-file-activity.test.ts` | the Node template's own activity store — persistence across restart, torn-line repair, newest-first paging, and compaction past the slack window | runs it against real files |
+| `upgrade-guide.test.ts` | the [upgrade guide](./upgrading.md)'s claims about somebody else's deployment — the generated file inventory, the seven tool names doctor demands, version boundaries that actually shipped, a bump target that is this release, and the three places a reader finds it | reads the guide, the template tree, and the CLI with Node filesystem APIs |
 | `version.test.ts` | `CONNECTA_VERSION` matching `package.json` | reads `package.json` with Node filesystem APIs |
 
 ### Outside `npm run check`
 
 | Suite | Covers |
 | --- | --- |
-| `browser/operator-ui.spec.ts` | the operator wiring in a real browser: the shell staying open until authentication, credential and access-token and OAuth flows end to end, drift shown without naming a tool, and every failure and empty state |
+| `browser/operator-ui.spec.ts` | the operator wiring in a real browser: Clerk loader order across its version redirect and a real load failure, the shell staying open until authentication, credential and access-token and OAuth flows end to end, drift shown without naming a tool, and every failure and empty state |
 | `browser/program-ui.spec.ts` | the Apps shell in a real browser: a bound view merging fixed and declared arguments and correlating concurrent reads, and the one-string payload receiving no read bridge ([program UI read calls](./program-ui-read-calls.md)) |
 
 **The `_transportFactory` seam.** `RemoteMcpOptions._transportFactory` is

package/documentation/operator-ui.md

@@ -44,6 +44,14 @@ every operator-configured URL stay in `src/ui.ts`, where they are gated before
 they can become an attribute; the bundle renders everything that has a state.
 Two roots share one store: `#operatorNav` and `#operatorContent`.
 
+The Clerk loader is intentionally blocking. The inline operator bundle calls
+`boot()` as soon as the parser reaches the end of the body, so a deferred Clerk
+script would make an expected parse-time gap look like a permanent network
+failure. Blocking also preserves the existing failure path: after a real
+loader error, the parser continues and `boot()` renders the Clerk load message.
+Clerk's redirect from the major-version loader URL to its pinned asset keeps
+the same ordering.
+
 ## Rules that are not obvious
 
 - **No operator data in the shell.** Every page serves the same markup. Connector,
@@ -93,9 +101,11 @@ well as Node and there is no DOM in either:
   something calls them when the identity actually changes. It typechecks in the
   DOM-lib program (`tsconfig.operator-ui.json`) because it imports the store.
 - `test/browser/operator-ui.spec.ts` — the wiring, in a real browser:
+  Clerk loader order across its version redirect and a real load failure, plus
   credential, token, and OAuth flows end to end, including their failure and
-  empty states. Run it with `npm run test:browser` (`npm run test:browser:install`
-  once, for Chromium). It is not part of `npm run check`.
+  empty states. Run it with `npm run test:browser`
+  (`npm run test:browser:install` once, for Chromium). It is not part of
+  `npm run check`.
 
 ## Why the bundle is committed
 

package/documentation/provider-audit.md

@@ -14,7 +14,7 @@ error, not a finding, so the proxy reports have no H rows.
 Every miss below is fixed in the same change that recorded it
 ([#342](https://github.com/zackbart/connecta/issues/342)), except where the row
 says otherwise. The mechanically checkable half of the hand-written bar is now
-a test — [`test/provider-conventions.test.ts`](../test/provider-conventions.test.ts)
+a test — [`test/provider-conventions.test.ts`](https://github.com/zackbart/connecta/blob/main/test/provider-conventions.test.ts)
 walks the shipped surface of both `api()` providers on every run, so these
 verdicts cannot rot quietly back into prose. The proxies' mechanical rows live
 in their own suites, because what they assert is the wrapper's identity,
@@ -104,14 +104,14 @@ deliberate surface.
 | Convention | Verdict | Notes |
 | --- | --- | --- |
 | P1 add, never rewrite | meets | annotations only |
-| P2 identity | meets | required `purpose`, `instructions` appended, classification untouchable from there |
+| P2 identity | meets | required `purpose`, `instructions` appended, classification untouchable from there; purpose states deployment routing intent and the guide says it is not proof of authenticated account identity |
 | P3 routing fact | meets | production versus sandbox appears in the title, the description, and the guide's first line |
 | P4 endpoint default | meets | exemplary, and the model for the second clause: one published endpoint, `mode` required with no default, and construction throws when a recognizable key prefix contradicts the declared mode without reading anything it cannot classify |
 | P5 classification | meets | including the two verdicts that needed an argument — `stripe_api_read` is a read because the tool is the boundary, `create_refund` is destructive despite its name |
 | P6 catalog varies | **missed → fixed** | the doc already knew this (`get_balance_summary` is Treasury and gated; a `create_customer` example survives in Stripe's prose but not its tool table), but the *guide* did not say it, and the guide is what reaches the agent. Added |
 | P7 reduction advice | **missed → fixed** | bare string; the derived summary was "Mode: production. Account purpose: …", spending the 120-character budget on the operator's prose. Now a declared, mode-shaped summary. `required` unset: the four generic tools are the routing decision and the mode warning already rides the title and description |
-| P8 identity resolution | **missed → fixed** | Stripe's writes take ids and the guide never said where they come from. Added: the typed prefixes (`cus_`, `sub_`, `ch_`, `pi_`, `in_`, `acct_`), the rule that a plausible-looking id belongs to a different object or to nobody, and the read tools that produce a real one |
-| P9 authentication | meets | OAuth default, `requireHttps`, restricted key documented as a secret and paired with the narrowest scope. The `auth_required` → `authorize_connector` route was added to the guide alongside P8, since a proxy's only recovery instruction lives there |
+| P8 identity resolution | **missed → fixed** | Stripe's writes take ids and the guide never said where they come from. Added: the typed prefixes (`cus_`, `sub_`, `ch_`, `pi_`, `in_`, `acct_`), the rule that a plausible-looking one belongs to a different object or to nobody, and the read tools that produce a real one. The guide now also accounts for OAuth sessions tied to several organization accounts: connector metadata is not identity proof, the exact selector must come from the live tool schema, and an ambiguous target or selection mechanism stops rather than becoming a guessed argument or header ([#404](https://github.com/zackbart/connecta/issues/404)) |
+| P9 authentication | meets | OAuth default, `requireHttps`, restricted key documented as a secret and paired with the narrowest scope. The guide distinguishes organization accounts within an OAuth session from Connect connected accounts, whose calls reject OAuth and use a deployment-configured restricted key plus `Stripe-Account`. The `auth_required` → `authorize_connector` route was added alongside P8, since a proxy's only recovery instruction lives there |
 | P10 no credential test | meets | no credential slot; the mode/key contradiction throws at construction instead, which is where P10 says the H12 guarantee gets paid |
 | P11 transport vs tool error | meets | inherited from `remoteMcp()`; the guide now also says that a rejected argument or plan restriction arrives in Stripe's own words and is not an authorization problem |
 | P12 admission budget | meets | a citable documented number (100/s live, 25/s sandbox), transcribed per mode, with `maxConcurrency` labeled as Connecta's own conservative choice |

package/documentation/provider-conventions.md

@@ -50,21 +50,28 @@ floor. From `src/catalog.ts` and `src/catalog-service.ts`:
   `fullDescriptions: true`. Prose past those points reaches an agent only when
   it pays for the expansion.
 - **A compact schema renders into at most 1,024 UTF-8 bytes**, and any single
-  enum node into at most 256. Past either cap the renderer keeps what fits and
-  degrades the rest — a prefix of the enum plus `unknown`, a required-first
-  object with `unknown` types, or `unknown /* truncated */` — and flags the
-  match, which costs a describe round trip to recover.
+  enum or constraint annotation into at most 256. Numeric bounds, string
+  length bounds, patterns, and formats ride beside their TypeScript-like type.
+  Past a cap the renderer keeps what fits and degrades the rest — a prefix of
+  the enum plus `unknown`, a shape without the constraints that did not fit, a
+  required-first object with `unknown` types, or
+  `unknown /* truncated */` — and flags the match, which costs a describe
+  round trip to recover.
 - **`inputKeys`, `requiredInputKeys`, and `outputKeys` come only from bounded
   plain-object schemas.** A top-level `anyOf` has no keys to list, so a caller
   learns nothing about the arguments without expanding the schema.
-- **A guide summary is capped at 120 characters**, defaulting to the guide's
-  first meaningful body line.
+- **A guide summary is bounded at 120 characters.** A configured value past
+  the bound refuses construction. An omitted one defaults to the guide's first
+  meaningful body paragraph, joined across physical line wraps and shortened
+  at a readable boundary.
 - **Search returns a connector's `id`, `title`, `guide`, and `guideSummary` —
   never its `description`.** The description reaches an agent only as the
-  fallback summary for a guide with no usable body line. Routing facts belong
-  in the title and the guide's first line; a routing fact that lives only in
+  fallback summary for a guide with no usable body paragraph. Routing facts belong
+  in the title and the guide's opening paragraph; a routing fact that lives only in
   the connector description has been written into a field the model does not
-  read.
+  read. Neither the `id` nor the `title` is a lexical document, so a term drawn
+  from one of them is not a search hit — it is a no-match whose guidance names
+  the connector and points at a scoped browse.
 
 Two construction-time checks enforce the floor beneath all of this. The hard
 one is `api()` itself: since
@@ -108,7 +115,10 @@ write never hides behind a neutral one. Escape hatches are named
 `<provider>_api_<class>` so they sort together and read as generic.
 
 *Why:* the name is the only thing lexical search indexes besides the
-description, and it is what an agent skims first. *Cost:* wrong-tool selection.
+description, and it is what an agent skims first. A connector's `id` and
+`title` are displayed, not indexed — a search for one of them matches no tool,
+and the miss is answered by guidance naming that connector rather than by a
+ranked result. *Cost:* wrong-tool selection.
 
 ### H3 — The selection sentence fits in 160 characters; the whole description in 240
 
@@ -136,7 +146,8 @@ wrong-tool selection.
 Every tool carries a hand-written `inputSchema`: a plain object at the top
 level, `additionalProperties: false`, an accurate `required` list, an `enum` on
 every constrained field, explicit numeric bounds on every page size and count,
-and a description on every property — nested objects and array items included,
+explicit string bounds where length or shape is constrained, and a description
+on every property — nested objects and array items included,
 because a caller composing an array element is reading that element's fields,
 not the parent's prose. `api()` enforces the enforceability half for free since
 [#340](https://github.com/zackbart/connecta/issues/340): a schema the validator
@@ -160,10 +171,12 @@ argument retries.
 ### H7 — Schemas fit the compact renderer, or selection does not depend on the part that is cut
 
 Keep the common path's compact input and output shapes inside 1,024 bytes and
-each enum node inside 256. Where a legitimate enum genuinely cannot fit — 21
-DNS record types — the truncation is acceptable only if the tool's name and
-description already carry enough for selection, so the caller expands the
-schema to *call*, not to *choose*.
+each enum or constraint annotation inside 256. Numeric and string constraints
+render when they fit. Search drops complete constraints that do not fit and
+sets the existing truncation flag; compact describe keeps them. Where a
+legitimate enum genuinely cannot fit — 21 DNS record types — the truncation is
+acceptable only if the tool's name and description already carry enough for
+selection, so the caller expands the schema to *call*, not to *choose*.
 
 *Why:* a truncated compact shape costs a describe round trip. *Cost:* discovery
 tokens.
@@ -217,6 +230,37 @@ convenient reading. A call that can only fail is refused locally as
 `invalid_args` before the round trip. Provider error prose is never parsed to
 invent a classification.
 
+**A downstream 404 is `not_found` — when the provider means it.** The code
+exists because the next move is none of the others': you do not wait, you do
+not send the agent to `authorize_connector`, you do not repair the argument
+object. You re-address — look the id up again, or accept the absence and carry
+on — and a program looping over ids inside `execute_code` can continue past
+`not_found` where `connector_call_failed` would have to abort the run, reading
+the code off a `connecta.batch` entry's `errorDetails` rather than off a caught
+error, which the guest bridge has already stripped to prose. That
+control-flow difference is the H11 test being met; it is not a label for the
+cause.
+
+The qualifier is the whole rule. Map a status to `not_found` only where the
+provider distinguishes absence from a permission gap. Where it does not —
+Notion returns `object_not_found` both for an object that is gone and for one
+that was never shared with the integration, and will not say which — the honest
+code stays `connector_call_failed` (or `auth_required`, where a credential
+really is the fix) and the message states the ambiguity, exactly as the
+paragraph above requires. Cloudflare is the other side of the pair: a token
+that may not touch a resource is refused with 401 or 403, so its 404 is an
+absence and maps to `not_found`. Neither connector's mapping changed shape when
+the code arrived; one of them changed codes.
+
+Two boundaries. `not_found` is about a resource the *downstream* owns: an
+address connecta cannot resolve is already framed as `unknown_address` or
+`unknown_tool` and never reaches a connector. And it never appears on the
+hosted-MCP proxy path, because `P1` forbids re-shaping downstream framing and
+prose is never parsed to invent a classification — a proxied server's own
+missing-resource error arrives as that server wrote it. The two paths do not
+diverge on the rule; they diverge on who is entitled to apply it, which is the
+same split every other code already has.
+
 *Why:* a misrouted error sends an agent down a recovery path that cannot
 succeed. *Cost:* argument retries.
 
@@ -508,7 +552,7 @@ whether or not anybody noticed it arrived.
 ([#351](https://github.com/zackbart/connecta/issues/351)): a human at a laptop,
 before a release, with local credentials and the published specifications in
 front of them. It lives in
-[`scripts/drift-check.mjs`](../scripts/drift-check.mjs) and ships nowhere —
+[`scripts/drift-check.mjs`](https://github.com/zackbart/connecta/blob/main/scripts/drift-check.mjs) and ships nowhere —
 `scripts/` is outside the package, no runtime module imports it, and nothing it
 reads becomes a runtime input.
 
@@ -525,10 +569,15 @@ One credential per provider comes from the environment —
 `CONNECTA_DRIFT_LINEAR_KEY`, `CONNECTA_DRIFT_STRIPE_KEY`,
 `CONNECTA_DRIFT_MIXPANEL_KEY` — and a missing or dead one stops the run with a
 message naming it rather than reporting an empty catalog as mass removal.
+Linear and bare Stripe values use their documented bearer or Basic framing.
+Mixpanel's beta service-account form is provider-specific:
+`user:secret` becomes `Bearer Basic <base64(user:secret)>`, exactly as its MCP
+documentation requires. A value that already includes whitespace is treated
+as a complete Authorization value and passes through unchanged.
 
 **Touched endpoints.** A hand-written provider is written against a published
 OpenAPI document and calls a few dozen of its operations, so
-[`scripts/drift/`](../scripts/drift/) commits exactly those: method, path, the
+[`scripts/drift/`](https://github.com/zackbart/connecta/tree/main/scripts/drift) commits exactly those: method, path, the
 specification revision a release reviewed the endpoint at, whether the
 operation was deprecated at that revision, and a digest of that endpoint's
 contract. `--specs` fetches each provider's published document and reports four
@@ -580,7 +629,7 @@ the reason). A convention is never quietly skipped, and an accepted miss is
 recorded as a provider-specific exception with its argument, not left blank.
 Its five reports live in [provider-audit.md](./provider-audit.md), and the
 mechanically checkable half of the hand-written bar runs on every test run in
-[`test/provider-conventions.test.ts`](../test/provider-conventions.test.ts) —
+[`test/provider-conventions.test.ts`](https://github.com/zackbart/connecta/blob/main/test/provider-conventions.test.ts) —
 so a convention that was met once stays met, or fails loudly.
 
 Hand-written providers are audited against H1–H14; hosted-MCP proxies against
@@ -620,7 +669,7 @@ beats the escape hatch — is a reading, and the audit reports it as one. The
 Cloudflare keep/prune half of that judgment was made in
 [#350](https://github.com/zackbart/connecta/issues/350): 30 keep, 18 improve,
 3 prune, measured per tool in
-[`eval/current-version/results/issue-350-evidence.md`](../eval/current-version/results/issue-350-evidence.md).
+[`eval/current-version/results/issue-350-evidence.md`](https://github.com/zackbart/connecta/blob/main/eval/current-version/results/issue-350-evidence.md).
 Its eighteen `improve` rows are H8 and H9 misses on tools that clearly earn
 their place, so they are this audit's work, not a second removal argument.
 

package/documentation/stripe.md

@@ -17,9 +17,15 @@ const billing = stripe("stripe_live", {
 });
 ```
 
-The `id` owns the ordinary connector namespaces; use a different id for every
-Stripe account. `purpose` is required because an agent choosing between two
-instances needs to know which account answers the question. Account
+The `id` owns the ordinary connector namespaces. Choose a connector boundary
+for its credential or OAuth session, mode, and business purpose — not
+automatically for each Stripe account. One OAuth session may cover more than
+one account in the same Stripe organization. Use separate connectors when the
+credential, production/sandbox mode, or business purpose differs.
+
+`purpose` is required because it tells an agent where the deployment intends
+to route a question. The connector id, title, and purpose are configuration,
+not proof of which account the authenticated Stripe session will use. Account
 `instructions` are appended to the maintained guide and cannot change the
 connector's safety classification.
 
@@ -53,9 +59,9 @@ one. That check reads nothing it cannot classify — an OAuth connector, or a
 credential shape this release does not recognize, is left alone rather than
 guessed at — and the error names only the two modes, never the key.
 
-Deploy both side by side. Two instances are isolated exactly like two
-hand-written connectors with different ids: separate addresses, catalogs,
-credentials, storage, admission counters, and health.
+Deploy production and sandbox side by side. Two instances are isolated exactly
+like two hand-written connectors with different ids: separate addresses,
+catalogs, credentials, storage, admission counters, and health.
 
 ```ts
 connectors: [
@@ -74,7 +80,20 @@ connectors: [
 
 OAuth is the default and the option Stripe recommends: it supports dynamic
 client registration and PKCE, and each connector instance keeps its own flow
-and tokens in connector-scoped storage. Stripe also accepts a
+and tokens in connector-scoped storage. Stripe's current
+[session-management documentation](https://docs.stripe.com/mcp#manage-mcp-client-sessions)
+says one OAuth session can be tied to more than one account in the same Stripe
+organization. It does not say every session has multiple accounts.
+
+That scope changes what an agent must prove before an account-scoped call. It
+must resolve the intended organization account, inspect the selected tool's
+live input schema, and carry only the exact account or context field that
+schema exposes. If more than one account fits, or the live schema exposes no
+clear selection mechanism, the agent stops and asks. It never guesses from the
+connector id, title, or purpose, and it never invents an MCP argument or
+request header.
+
+Stripe also accepts a
 [restricted API key](https://docs.stripe.com/keys#create-restricted-api-key) as
 a bearer token for headless agents:
 
@@ -93,9 +112,12 @@ 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.
 
-Connect platforms can act as a connected account with `connectedAccount`, which
-adds Stripe's `Stripe-Account` header. Stripe does not support OAuth for
-connected-account calls, so this requires `headers` auth and throws otherwise:
+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:
 
 ```ts
 stripe("merchant_42", {
@@ -109,9 +131,10 @@ stripe("merchant_42", {
 });
 ```
 
-Administrators must enable MCP access in the Stripe Dashboard, and Stripe
-manages that setting **separately for sandbox and live mode**. A connector that
-boots but cannot list tools is usually a dashboard toggle, not a bad key.
+Administrators must enable MCP access in the Stripe Dashboard. Stripe scopes
+OAuth session management and MCP access **separately for sandbox and live
+mode**. A connector that boots but cannot list tools is usually a dashboard
+toggle, not a bad key.
 
 ## The eleven tools, and what they are classified as
 
@@ -158,7 +181,7 @@ serves, an unclassified and unannotated `create_customer` lands on the approval
 path. Expect the undocumented Treasury tools Stripe alludes to to arrive
 unclassified as well — annotated ones will be taken at their word.
 
-The upshot is that this account's tool list is not a fixed set, and the usage
+The upshot is that this connection's tool list is not a fixed set, and the usage
 guide tells the agent so: search this connector for what it actually exposes
 rather than assuming a documented tool is present. The guide also names the id
 discipline the downstream schemas cannot enforce — Stripe ids are typed
@@ -166,6 +189,14 @@ prefixes (`cus_`, `sub_`, `ch_`, `pi_`, `in_`, `acct_`), a plausible-looking one
 belongs to a different object or to nobody, and the id a write takes comes from
 `stripe_api_search` or a list read rather than from a guess.
 
+Account selection comes before that object-id rule. The served guide warns
+that the connector metadata states routing intent rather than authenticated
+identity. It tells the agent to use only selectors in the live tool schema and
+to stop when the account or selection mechanism is ambiguous. It also keeps
+organization-account selection separate from the restricted-key-only Connect
+path, so an agent cannot repair uncertainty by fabricating `Stripe-Account` as
+a tool argument.
+
 Stripe publishes no stability or deprecation policy for this tool set and
 invites tool requests by email, so treat the list as unversioned. `get_balance_summary`
 is Treasury, which Stripe labels public preview and gates behind an access