@zackbart/connecta 0.16.1 → 0.17.0

package/documentation/connector-guides.md

@@ -40,13 +40,17 @@ hand-written connector. It is deployment-owned configuration like everything
 else here: an edit and a redeploy, never a runtime registration.
 
 `content` is returned byte for byte by `skills({ name: "connector:<id>" })`.
-`summary` is normalized and capped at 120 characters for discovery. Omit it and
-connecta derives the same bounded line the skills listing uses: the first
-meaningful body line, with frontmatter, fences, rules, comments, and table rows
-skipped, a heading used only when the guide has no body, and the connector's
-description as the last resort. A derived summary is usually worse than a
-written one — it was written to open a document, not to answer "is this guide
-relevant to what I am about to do".
+`summary` is normalized and must fit 120 characters. A longer configured value
+refuses construction instead of silently changing the operator's words. Omit
+it and connecta derives the same bounded summary the skills listing uses: the
+first meaningful body paragraph, joined across Markdown's physical line wraps,
+with frontmatter, fences, rules, comments, and tables skipped. When the
+paragraph does not fit, connecta keeps a useful complete sentence when one
+fits, then prefers a clause or word boundary before adding an ellipsis. A heading is used
+only when the guide has no body, and the connector's description is the last
+resort. A derived summary is usually worse than a written one — it was written
+to open a document, not to answer "is this guide relevant to what I am about
+to do".
 
 `connector:<id>` is the only address for a guide, and built-in skill names are
 bare identifiers, so a guide can never shadow or be shadowed by `usage`: a
@@ -160,15 +164,16 @@ schemas will never carry, because it cannot change them
 ## Tests that enforce this
 
 `test/meta-tools.test.ts` owns the guide behavior end to end: the skills
-listing carrying one entry per guided connector, summaries derived from the
-first meaningful line and falling back to the connector description when the
-guide is all markup, whitespace-only guides treated as no guide, content
-returned verbatim including surrounding padding, identical content in two
-deployments staying isolated, every miss erroring rather than falling back to
-the generic guide with an identically labelled skills list on each branch, the
-`guide` pointer in search output, and `guideRequired` appearing for
-connector-required conventions, approval-bound tools, and truncated schemas —
-and being absent from a search that asked for no schemas. `test/server.test.ts`
-owns the conditional half: it compares a guide-free deployment's four tool
-descriptions against a guided one's, and asserts the `usage` skill is
-byte-identical between them.
+listing carrying one entry per guided connector, summaries joining a
+hard-wrapped opening paragraph and shortening at readable boundaries,
+configured summaries refusing construction past the bound, heading and
+description fallbacks, markup skipping, whitespace-only guides treated as no
+guide, content returned verbatim including surrounding padding, identical
+content in two deployments staying isolated, every miss erroring rather than
+falling back to the generic guide with an identically labelled skills list on
+each branch, the `guide` pointer in search output, and `guideRequired`
+appearing for connector-required conventions, approval-bound tools, and
+truncated schemas — and being absent from a search that asked for no schemas.
+`test/server.test.ts` owns the conditional half: it compares a guide-free
+deployment's four tool descriptions against a guided one's, and asserts the
+`usage` skill is byte-identical between them.

package/documentation/connectors.md

@@ -252,6 +252,17 @@ 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.
 
+Agent reads use a complete entry inside `staleCatalogSeconds` immediately and
+defer the refresh that read already demanded. Every live refresh is
+single-flight per connector in one runtime. A blocking operator or direct read
+joins an agent-owned refresh and awaits it; an agent stale read joins an
+operator-owned refresh without awaiting it. The first refresh owns the context
+and deadline. A deferred first refresh owns a fresh scope and signal, then
+closes that scope. Operator status and direct registry reads still await
+freshness. The operator page reports whether the last agent read in this runtime
+was fresh or stale; this payload-free timestamp is not persisted. No timer or
+idle warmup originates downstream traffic.
+
 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.
@@ -259,7 +270,8 @@ timeouts, validation, result guards, and typed failures.
 Connector usage guides are configuration too. `usageGuide` accepts the
 historical markdown string or `{ content, summary?, required? }`; the latter
 lets discovery explain what the guide covers without loading it. The summary
-is only a bounded routing hint. Mark a guide `required` only when no complete
+is a 120-character routing hint; a longer configured value refuses construction
+instead of being silently shortened. Mark a guide `required` only when no complete
 tool schema can describe correct use, such as a generic operation wrapper or a
 mandatory cross-tool sequence. Mutations and truncated compact schemas already
 produce automatic review requirements. Two deployments may reuse the same

package/documentation/meta-tools.md

@@ -89,14 +89,16 @@ 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. Within that unchanged total, each enum node may spend at most 256 UTF-8
-bytes. This lets about three near-cap enum nodes coexist while reserving the
-remaining quarter for surrounding syntax; the global fallback still applies
-when the complete shape exceeds 1,024 bytes. A large enum keeps the longest
-whole-value prefix that fits, then adds `unknown` and a comment with the exact
-omitted-value count. An empty enum renders as the valid `never` type. A capped
-object becomes a valid required-first shape with `unknown` types; other shapes
-become `unknown /* truncated */`. Either cap marks the match with
+bytes. Within that unchanged total, each enum node and each constraint
+annotation may spend at most 256 UTF-8 bytes. Numeric bounds, string length
+bounds, patterns, and formats render beside their type. A constraint that does
+not fit is dropped whole. If constraints push the full shape over 1,024 bytes,
+search retries the shape without them. Compact describe keeps all declared
+constraints. A large enum keeps the longest whole-value prefix that fits, then
+adds `unknown` and a comment with the exact omitted-value count. An empty enum
+renders as the valid `never` type. A capped object becomes a valid
+required-first shape with `unknown` types; other shapes become
+`unknown /* truncated */`. Any cap marks the match with
 `inputSchemaTruncated` or `outputSchemaTruncated`; repeat the search with
 `includeSchemas: "json"` or use the existing describe path when exact
 constraints matter. Small enums and both exact paths remain complete.
@@ -107,12 +109,13 @@ A connector may attach a deployment-owned guide as markdown, preserving the
 original `usageGuide: string` configuration, or as
 `{ content, summary?, required? }`. The structured form does not register a
 connector or create a shared runtime template. `content` remains the markdown
-returned verbatim by `skills`; `summary` is normalized and capped at 120
-characters for discovery. When it is absent, Connecta derives the same bounded
-fallback used by the skills listing: the first meaningful body line, with a
-heading used only when the guide has no body. `required: true` is reserved for generic
-API wrappers and cross-operation conventions a complete downstream schema
-cannot express.
+returned verbatim by `skills`; `summary` is normalized and refuses construction
+when it exceeds 120 characters. When it is absent, Connecta derives the same
+bounded fallback used by the skills listing: the first meaningful body
+paragraph, joined across physical Markdown line wraps and shortened at a
+sentence, clause, or word boundary, with a heading used only when the guide has
+no body. `required: true` is reserved for generic API wrappers and
+cross-operation conventions a complete downstream schema cannot express.
 
 Search and describe results keep the existing `guide: "connector:<id>"`
 pointer and add `guideSummary`. A matching tool also carries
@@ -170,12 +173,18 @@ can shrink anything before it returns.
 
 `fields` keeps its historical flat `{ "<path>": value }` result when every
 requested dot-path resolves. Dot notation traverses objects; append `[]` to an
-array field before continuing, as in `results[].id`. An exact downstream
+array field before continuing, as in `results[].id`. Empty arrays resolve to
+empty arrays. 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. When a miss matches a declared array path except for `[]`, the record
-also carries the traversal hint. The discriminator means downstream fields
+entry. A path that resolves for only some array elements stays in `data` and
+appears in `partialFields`; its unresolved positions serialize as `null`, while
+the recovery record distinguishes them from genuine downstream nulls. A path
+that misses every element appears in `unmatchedFields` and is omitted from
+`data`. Both lists scale with requested paths, never with array length. When a
+miss matches a declared array path except for `[]`, the record also carries the
+traversal hint. 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`

package/documentation/mixpanel.md

@@ -50,6 +50,26 @@ password, not ordinary configuration. Mixpanel currently labels service-account
 MCP authentication beta. Prefer OAuth unless the deployment is intentionally
 headless.
 
+## Conditional input contracts
+
+Mixpanel's hosted descriptions enforce three cross-field conditions that its
+input schemas do not encode. Connecta preserves those schemas unchanged under
+[P1](./provider-conventions.md#p1--normalize-by-adding-never-by-rewriting), so
+the maintained guide carries the missing call guidance:
+
+- `Get-Business-Context` requires `project_id` or `organization_id`.
+- `Get-Property-Values` requires `properties` or the deprecated `property`
+  alias. Event property values also require `event`.
+- `List-Properties` accepts `names` or `query`, never both.
+
+A read-only live audit on 2026-08-13 confirmed all three refusals against the
+US hosted endpoint. They are reported upstream as
+[`mixpanel/mixpanel-headless#202`](https://github.com/mixpanel/mixpanel-headless/issues/202).
+The vetted catalog records the same audit's schema digests for all 63 tools,
+so a later schema correction or regression appears by tool name in the
+maintainer drift check. The guide can then shrink when the downstream schema
+becomes complete; Connecta does not absorb the defect permanently.
+
 The wrapper classifies the documented observational tools as reads and the
 documented create, update, edit, merge, dismiss, duplicate, and delete tools as
 writes. An unfamiliar tool the downstream leaves unannotated fails closed onto

package/documentation/operations.md

@@ -8,15 +8,18 @@ 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
@@ -84,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 |
@@ -221,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 |
@@ -229,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`)
@@ -260,12 +263,12 @@ 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 |
+| `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 |
 | `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 |
@@ -283,7 +286,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 
 | 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

@@ -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,19 +50,24 @@ 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. 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
@@ -141,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
@@ -165,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.
@@ -561,6 +569,11 @@ 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

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

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.16.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.17.0 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
 
 Generation A is a decade in template years and identifying it precisely does
 not matter, because you are about to reconstruct it exactly rather than guess
@@ -106,7 +106,7 @@ know what to preserve, once to know what to re-verify at the end.
 ### Bump the pin and install
 
 ```sh
-npm pkg set dependencies.@zackbart/connecta=0.16.1
+npm pkg set dependencies.@zackbart/connecta=0.17.0
 npm install
 ```
 
@@ -130,7 +130,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.16.1 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.17.0 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -186,7 +186,7 @@ A deployment older than 0.10.2 has no base to diff against. Do not try to
 manufacture one. Instead:
 
 1. `SCRATCH=$(mktemp -d)`, then
-   `(cd "$SCRATCH" && npx @zackbart/connecta@0.16.1 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.17.0 init current)` — there is no
    `base` leg here, only the current template to read from.
 2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
    `src/index.ts`**.
@@ -207,6 +207,30 @@ 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.16.1 → 0.17.0
+
+Two construction rules need a deployment check.
+
+**A Dynamic Worker executor is loader-only.** The supported construction is
+exactly:
+
+```ts
+new DynamicWorkerExecutor({ loader: env.LOADER })
+```
+
+Remove `bindings`, `modules`, or `globalOutbound` from that options object.
+Those fields grant guest code ambient configuration, code, or egress. This is
+the supported sandbox boundary rather than a new Connecta-side inspection of
+the third-party executor object. The shipped Worker example was already
+loader-only, and Node deployments use `quickJsExecutor()`, so neither needs a
+change (#390).
+
+**An explicit guide summary must fit discovery.** Connecta normalizes
+whitespace in `usageGuide.summary` and refuses registry construction when the
+result is longer than 120 characters. Shorten it to 120 characters or fewer,
+or omit it and let Connecta derive a bounded summary from the guide's opening
+prose. A blank explicit summary still takes the derived-summary path (#392).
+
 ### 0.16.0 → 0.16.1
 
 Nothing throws, and a Node deployment crosses this on the version bump alone.