@zackbart/connecta 0.15.1 → 0.16.0

package/documentation/call-admission.md

@@ -1,7 +1,143 @@
-# Call admission
+# Downstream call admission
 
-> **Stub.** The old manual was retired in the phase-1 docs restructure. This
-> document will be rewritten as an agent-facing guide — what the subsystem is
-> for, how to work on it, and what it must never do — once the ideas in
-> [ethos.md](../ethos.md) settle. The prior text lives in git history as
-> `docs/call-admission.md`.
+One admitted MCP request can fan out into many downstream calls. A program
+calls tools from loops, from `connecta.batch`, and from branches the caller
+never saw. The deployment-wide request pool
+([request admission](./request-admission.md)) bounds the envelope; it cannot
+see anything inside it. A provider that publishes "60 requests per minute"
+needs a bound that counts calls, not requests.
+
+So a connector may declare `callAdmission`: an optional per-runtime policy
+around its own `Connector.callTool` attempts.
+
+```ts
+const projects = api("projects", {
+  description: "Projects — issues and reports",
+  callAdmission: {
+    // Plural-ready public shape; this release requires exactly one rule.
+    rules: [{
+      maxConcurrency: 5,
+      maxQueueSize: 10,       // default 32
+      queueTimeoutMs: 2_000,  // default 5_000
+      retryAfterMs: 1_000,    // concurrency-overload hint
+      budget: { kind: "rolling-window", maxCalls: 60, windowMs: 60 * 60_000 },
+      partitionKey({ toolName, args }) {
+        return projectIdFor(toolName, args);
+      },
+    }],
+    maxPartitions: 1_024,     // default
+  },
+  tools: [/* … */],
+});
+```
+
+`api()`, `remoteMcp()`, and a hand-written `Connector` all accept it. Maintained
+prebuilt connections set it themselves — but only when the provider documents a
+number, which is convention
+[P12](./provider-conventions.md#p12--declare-an-admission-budget-only-when-the-provider-documents-a-number).
+An invented budget is a throttle with no source.
+
+## Policy contract
+
+`maxConcurrency` and `budget` are independently optional, but a rule must
+declare at least one — a rule that bounds nothing is a typo, not a policy.
+Queue settings require `maxConcurrency`, because there is nothing to queue
+behind without it, and `maxQueueSize: 0` is the fail-fast shape. Numeric bounds
+are finite whole numbers: concurrency, timeouts, budget values, and
+`maxPartitions` are positive; queue size and `retryAfterMs` may be zero.
+`budget.kind` must be `"rolling-window"`. Everything invalid throws during
+registry construction.
+
+The container is an array so a later release can add atomic rules over
+different partition dimensions, but **exactly one rule** is accepted today.
+Zero or several throw rather than imply semantics the runtime does not have.
+Multiple rules cannot be faked as sequential leases: consuming one rolling
+token before a later rule refuses would charge a call that never reached the
+provider — the exact accounting error a budget exists to prevent.
+
+Omitting `partitionKey` gives one connector-wide partition. A callback runs
+synchronously on model-supplied arguments and must return a non-secret string
+of at most 128 UTF-8 bytes. A throw or an invalid return is a typed local
+`connector_call_failed`; neither the callback text nor the arguments are
+surfaced. The callback is operator code and may abort the caller synchronously,
+so cancellation is rechecked after it returns — otherwise a cancelled call
+could still consume a budget entry.
+
+State retains the returned key, bounded timestamps, counters, signals, and
+promise continuations. Nothing copies arguments into the limiter; the queued
+waiter closure deliberately captures the `AbortSignal` rather than the input
+object, because closing over the input would retain its `args`. At most
+`maxPartitions` states are live, and an idle state is evicted only once its
+active calls, queue, and rolling-window history are all empty — eviction must
+not be a way to reset a live budget. Exhausted partition capacity is
+`rate_limited` with the configured retry hint, not a silent unbounded map.
+
+## Attempt semantics
+
+The registry owns the limiter, and `InvocationService.invoke` acquires a permit
+immediately before `Connector.callTool` and releases it in `finally`. Both call
+paths — top-level `call_tool` and a program's `connecta.call` or
+`connecta.batch` — reach that same seam, so a program cannot buy itself a
+second limit by taking the other route.
+
+- **A retry is another attempt.** It reacquires and can consume another budget
+  entry, because the provider counts it that way. Backoff never holds a
+  concurrency permit.
+- **A proactive short-window `rate_limited` refusal** participates in the
+  ordinary retry policy and counts as an attempt. Activity records the final
+  outcome and the attempt count.
+- **A queued cancellation consumes nothing.** It is removed from the queue with
+  no rolling-window entry charged.
+- **Caller cancellation is terminal.** It is non-retryable, releases its
+  permit, records a `cancelled` activity outcome, and is not connector-health
+  evidence.
+- **Budget exhaustion fails immediately** as `rate_limited`, `retryable: true`,
+  with the exact `retryAfterMs` to the next free slot. Concurrency overflow
+  uses the configured hint instead, because there is no exact answer.
+- **Local refusals are not connector health failures.** They are activity
+  errors, but no provider call happened, so poisoning the connector's health
+  with them would report the limiter's success as the downstream's failure.
+  `isCallAdmissionError` is what keeps `recordFailure` out of that path.
+
+Only tool execution is covered. Catalog `listTools`, status probes, credential
+checks, and authorization operations stay outside the budget: they are not the
+calls a provider is rate-limiting, and charging discovery for them would make
+a program's first search cost it capacity to act.
+
+Queue admission and connector execution have separate clocks. `queueTimeoutMs`
+bounds only the wait for a permit; a per-attempt `timeoutMs` starts after
+admission. A saturated call can therefore take up to their sum. With
+`diagnostics: true`, `admissionMs` reports the permit wait and `connectorMs`
+the admitted attempt — which is the only way to tell "the provider is slow"
+from "we are throttling ourselves".
+
+## Enforcement scope
+
+This is deliberately **per-runtime**. It completely contains fan-out inside one
+request, including a wide `connecta.batch` in one Worker isolate. A rolling
+budget is exact inside one Node process or Worker isolate, and best-effort
+across isolates, replicas, and restarts.
+
+KV cannot coordinate the invariant without atomic operations, and this release
+adds no Durable Object or other distributed coordinator. The async typed permit
+is the seam a coordinator would slot into later; until then the guide says what
+the bound actually is rather than implying a global one.
+
+## Observations
+
+`/health` exposes payload-free aggregates at
+`admission.downstreamCalls.connectors.<id>`: retained partition count, current
+active and queued gauges, cumulative admitted/queued/rejected/rate-limited/
+cancelled counts, and queue-wait count, total, and maximum. The open endpoint
+never exposes partition keys, tool arguments, or results — a partition key can
+be a customer identifier, which is precisely why it stays out of an unauthenticated
+payload. Ordinary payload-free activity records the final call outcome and its
+typed error code.
+
+## Tests that enforce this
+
+| Invariant | Suite |
+| --- | --- |
+| Independent partitions, exact rolling-window reset and retry, queued cancellation charging no budget, synchronous cancel during partition derivation, validated values snapshotted rather than read from mutable config, bounded partition state and contained `partitionKey` failures, empty and multi-rule policies refused | `test/call-admission.test.ts` (controller) |
+| One base-registry limiter shared by direct and program calls, batch bounds with input order preserved, cancellation threading, no dispatch or retry or health poisoning after cancellation, short proactive windows retried without poisoning health, payload-free `/health` aggregates | `test/call-admission.test.ts` (integration, Node + Workers) |
+| Where provider budgets are allowed to come from at all | [provider conventions P12](./provider-conventions.md#p12--declare-an-admission-budget-only-when-the-provider-documents-a-number), [provider audit](./provider-audit.md) |

package/documentation/cloudflare.md

@@ -2,7 +2,7 @@
 
 Import `cloudflare()` independently from
 `@zackbart/connecta/providers/cloudflare`. It is a deliberate, hand-written
-surface over Cloudflare's v4 REST API. Fifty-five tools combine ergonomic,
+surface over Cloudflare's v4 REST API. Fifty-two tools combine ergonomic,
 fully described operations for common work with three guarded escape hatches
 for the rest of Cloudflare's fast-moving control plane. Reads, JSON mutations,
 and raw/multipart uploads remain separate so safety routing does not depend on
@@ -144,7 +144,7 @@ projections:
 | DNS/cache | list and get records | create, update, delete, targeted/full purge |
 | Workers | scripts, settings, deployments | delete a script |
 | KV | namespaces, keys, bulk values | create/rename/delete namespace, bulk write/delete |
-| R2 | buckets, object metadata, metrics, CORS | create/update/delete bucket, delete object, replace/delete CORS |
+| R2 | buckets, object metadata, CORS | create/update/delete bucket, delete object |
 | Pages | projects, deployments, domains | retry/rollback/delete deployments, add/delete domains, purge build cache, delete project |
 
 Every named tool carries a complete hand-written input schema: closed
@@ -153,6 +153,39 @@ every constrained field, endpoint-specific pagination bounds, and a description
 on every property. `test/cloudflare-provider.test.ts` walks the surface and
 asserts those properties rather than leaving them as a claim.
 
+### What the named surface deliberately leaves out
+
+A named tool is a permanent line item in every deployment's catalog, so the
+surface was measured against the escape hatches rather than assumed to beat
+them ([#350](https://github.com/zackbart/connecta/issues/350), evidence in
+[`eval/current-version/results/issue-350-evidence.md`](../eval/current-version/results/issue-350-evidence.md)).
+Two named tools lost that comparison, and a third followed one of them off the
+surface to keep a policy pair on one route:
+
+- **R2 CORS writes.** `set_r2_cors` declared its rule list as free-form objects
+  — the untyped body this connection refuses everywhere else — so its schema
+  validated the bucket name and waved through the part of the call that
+  actually fails. It also returned Cloudflare's response unprojected and was
+  destructive either way, which left nothing for it to beat
+  `cloudflare_api_mutate` on. `delete_r2_cors` did not lose that comparison:
+  it returned a fixed `{deleted: true}` behind a closed output schema and
+  refused every malformed argument locally. It went anyway, because naming only
+  the delete would mean one CORS policy is set through the raw route and
+  cleared through a named tool. Read a policy with `get_r2_cors`; change one
+  with `cloudflare_api_mutate` at
+  `PUT`/`DELETE /accounts/{accountId}/r2/buckets/{bucketName}/cors`. This is the
+  same split the [DNS record types](#dns-record-types) already use: structured
+  bodies stay readable through named tools and writable through the
+  approval-gated raw route.
+- **R2 account metrics.** `get_r2_metrics` took one account id, put it in a
+  path, and returned the response untouched — `cloudflare_api_get` at
+  `/accounts/{accountId}/r2/metrics` does the same thing without a permanent
+  catalog line.
+
+The surviving 48 named tools all refuse malformed arguments locally, which is
+the one thing no escape hatch can do: a hatch's path is an opaque string, so it
+can only check that a path is a path.
+
 ### The whole-v4 escape hatch
 
 Cloudflare adds products and endpoints faster than a curated connector should
@@ -171,8 +204,14 @@ method classification into user input:
 
 All three accept explicit endpoint-specific headers, which supports R2
 jurisdictions, conditional requests, encryption controls, and object metadata.
-Authentication, host selection, content type, content length, and transfer
-framing remain connector-owned and cannot be overridden.
+`Authorization`, `Cookie`, `Host`, `Content-Length`, `Content-Type`, and
+`Transfer-Encoding` remain connector-owned and are refused: authentication,
+host selection, content type, and request framing are not the caller's to set.
+That refused list lives in the usage guide rather than in each header property
+description, because the compact renderer inlines a property description once
+per tool that shares it, and repeating it three times pushed
+`cloudflare_api_upload`'s compact input shape past the 1,024-byte discovery
+budget.
 
 Paths are relative to `/client/v4`. Absolute URLs, protocol-relative paths,
 `..` traversal, fragments, and embedded query strings are refused locally;
@@ -191,8 +230,8 @@ comes from Cloudflare's API reference.
 
 ### Where the `perPage` bounds come from
 
-`strictValidation` is on, so an out-of-range `perPage` is refused locally
-before it reaches Cloudflare. That is only a favor when the bound is really
+`api()` enforces every hand-written schema, so an out-of-range `perPage` is
+refused locally before it reaches Cloudflare. That is only a favor when the bound is really
 Cloudflare's, so the schemas record which ones are and the descriptions say so
 out loud:
 
@@ -260,8 +299,12 @@ Paginated lists add a `page` object derived from `result_info`:
 field to branch on.
 
 Some endpoints do not work that way, and the schemas say so rather than leaving
-an agent to discover it. `list_r2_buckets`, `list_r2_objects`, and
-`list_kv_keys` paginate by cursor and return `nextCursor` instead of `page`.
+an agent to discover it. `list_zone_rulesets`, `list_r2_buckets`,
+`list_r2_objects`, and `list_kv_keys` paginate by cursor and return
+`nextCursor` instead of `page`. On those four the `cursor` argument says the
+endpoint pages by cursor rather than page number, and the `nextCursor` result
+says it is the only signal and that no `page` object is coming — so the loop
+condition is legible from either end of one tool, without fetching the guide.
 `list_worker_scripts` reports no counters at all and omits `page` entirely.
 
 Projected resource reads expose `raw: true` where the provider's larger object
@@ -329,3 +372,10 @@ dashboard traffic of a human sharing the account is counted by Cloudflare but
 not by Connecta. `maxConcurrency` is the bound that actually protects a shared
 credential, because a single `execute_code` program can fan out far faster than
 the window notices.
+
+## Conventions
+
+This connection is audited against
+[the provider conventions](./provider-conventions.md). Its verdict per
+convention, including every recorded exception, is the Cloudflare section of
+[the provider audit](./provider-audit.md).

package/documentation/code-mode.md

@@ -8,10 +8,9 @@ it is specified in prose first and implemented second — the same discipline th
 [MCP spec bump](./mcp-2026-07-28.md) followed.
 
 Two executors implement this document: QuickJS in a child process on Node, and
-`DynamicWorkerExecutor` from `@cloudflare/codemode` on Workers. Divergence
-between them is a bug unless it appears in
-[Executor exceptions](#executor-exceptions), which names the reason. Anyone can
-implement a third executor from this document without reading either.
+`DynamicWorkerExecutor` from `@cloudflare/codemode` on Workers. Divergence between
+them is a bug unless it appears in [Executor exceptions](#executor-exceptions),
+which names the reason. Anyone can implement a third from this document alone.
 
 The [code-first exploration](./code-first-exploration.md) is the evidence behind
 the direction; [`ethos.md`](../ethos.md) carries the verdicts. Where its prototype
@@ -43,7 +42,7 @@ const connecta = createConnecta({
 CPU, wall-time, memory, stack, queue, result, log, and IPC bounds are configured
 on the executor. Server bundlers must keep the `@zackbart/connecta/quickjs`
 package files external so the child entry stays on disk. The
-[Node example](../examples/node/README.md) carries the complete setup.
+[Node template](../templates/node/README.md) carries the complete setup.
 
 On Cloudflare Workers, the Worker Loader binding provides the required sandbox:
 
@@ -54,9 +53,8 @@ createConnecta({
 });
 ```
 
-Dynamic Workers require the Workers Paid plan. The
-[Worker example](../examples/worker/README.md#code-mode) carries the complete
-required binding and package setup.
+Dynamic Workers require the Workers Paid plan. The complete required binding and
+package setup is in the [Worker example](../examples/worker/README.md#code-mode).
 
 ## What an executor must implement
 
@@ -64,6 +62,7 @@ The host side of the seam is two types in `src/types.ts` and nothing else.
 
 ```ts
 interface Executor {
+  readonly name?: string;                       // what /health and doctor report
   execute(code: string, providers: ExecutorProvider[]): Promise<ExecuteResult>;
   close?(): void | Promise<void>;
 }
@@ -113,11 +112,12 @@ Connecta passes exactly one provider, named `connecta`. An executor must:
 
 Optionally implement `AdmittingExecutor` (`acquire()` returning a lease whose
 `execute` runs once) for bounded admission (`L7`) and `close()` for shutdown;
-connecta wraps a plain `Executor` with `withExecutorAdmission` otherwise.
+connecta wraps a plain `Executor` with `withExecutorAdmission` otherwise. The
+optional `name` — else a class's constructor name, which a minifier may rewrite
+— is what [`/health` and `doctor`](./operations.md#the-cli) report.
 
-Note what is *not* on this list: [emitted output](#emitted-output) asks
-nothing of an executor — `connecta.emit` is just another provider function
-(`M8`).
+Note what is *not* on this list: [emitted output](#emitted-output) asks nothing
+of an executor — `connecta.emit` is just another provider function (`M8`).
 
 ## The program
 

package/documentation/connector-guides.md

@@ -1,7 +1,174 @@
 # Connector guides
 
-> **Stub.** The old manual was retired in the phase-1 docs restructure. This
-> document will be rewritten as an agent-facing guide — what the subsystem is
-> for, how to work on it, and what it must never do — once the ideas in
-> [ethos.md](../ethos.md) settle. The prior text lives in git history as
-> `docs/connector-guides.md`.
+Descriptions and schemas say *what* a connector's tools are. They do not say
+which tool to prefer, which id format an address quirk expects, how the service
+paginates, or how hard you may hammer it. A connector's optional `usageGuide`
+is where that goes — deployment-owned configuration, served by the `skills`
+meta-tool as `connector:<id>` and returned verbatim, with a bounded `summary`
+surfaced in discovery so an agent learns the guide exists at the moment it
+matters. See [meta-tools](./meta-tools.md#connector-guide-selection) for the
+discovery contract and [connectors](./connectors.md#catalog-contract) for how a
+guide is configured.
+
+## The shape of a guide
+
+`usageGuide` accepts a bare markdown string, which is still the shortest
+correct configuration, or the structured form:
+
+```ts
+const notion = remoteMcp("notion", {
+  url: "https://mcp.notion.com/mcp",
+  description: "Notion — pages, databases, comments",
+  auth: { type: "oauth" },
+  usageGuide: {
+    content: `# Notion usage
+
+Search before listing: \`notion.search\` covers pages and databases in one call.
+
+- Page ids are dashed UUIDs. Strip the trailing slug from a pasted URL first.
+- Paginate with \`start_cursor\`; \`page_size\` is capped at 100.
+- Writes replace blocks wholesale — read the block, merge, then write.
+`,
+    summary: "Search before listing; dashed-UUID page ids; cursor pagination",
+  },
+});
+```
+
+The field is on the `Connector` interface, not on a factory, so it works
+identically for `api()`, `remoteMcp()`, a prebuilt connection, and a
+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".
+
+`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
+connector whose id is literally `usage` is listed as `connector:usage`, and
+`skills({ name: "usage" })` still returns the built-in guide. Every miss —
+unknown name, unknown connector, connector with no guide — is an explicit
+error. Nothing silently falls back to the generic guide, because a generic
+answer to a specific question is worse than no answer.
+
+Discovery text is conditional on the deployment actually having a guide. The
+guide sentences in the `skills`, `search_tools`, `call_destructive_tool`, and
+`execute_code` descriptions appear only when at least one visible connector
+declares one — the connector set is fixed at construction, so this is stable
+per deployment, and a deployment with no guides pays no always-loaded context
+for a feature it does not use. The built-in `usage` skill is the deliberate
+exception: it stays byte-identical across every deployment, including its
+per-connector-guides section, so an agent that has read it once in a task never
+needs a deployment-local copy of it.
+
+## What belongs in a guide
+
+The test is not "is this true" but "can a schema carry it". If a schema can,
+fix the schema instead — a constraint in the schema is enforced, is visible at
+the moment of the call, and costs nothing to a caller who never fetches the
+guide.
+
+So a guide carries:
+
+- **Tool preference.** Which of two plausible tools is the right one, and the
+  fact that decides it.
+- **Sequence.** What must happen first — resolving a name to an id, listing a
+  parent before a child.
+- **Identity and address quirks.** The id format an address expects, the
+  difference between the id in the URL and the id the API wants.
+- **Pagination conventions.** The cursor field, the page cap, whether the
+  connector has more than one convention.
+- **Units and aliases.** What a bare number means; what the service calls the
+  thing the caller calls something else.
+- **Reduction advice.** Which fields matter, for a downstream whose results are
+  large and whose schemas you do not control.
+- **Rate-limit etiquette**, with the number.
+
+And a guide does not carry: anything readable off the schema, background on
+what the service is, marketing, a tool list, or a second copy of the tool
+descriptions. It is fetched into a live context window — every line that
+repeats the schema is a line that displaced one that did not.
+
+**Style.** Write for the agent, not the operator; the built-in `usage` skill
+(`src/skills.ts`) is the model. Concise and imperative, leading with the
+decision rather than the background ("Search before listing", not "Notion has a
+search API"). Prefer short bullets to prose. Name exact tool addresses and
+argument names. State a constraint with its number.
+
+## The `required` rule
+
+`required: true` on the structured form means: fetch this guide before every
+operation on this connector. It surfaces as `guideRequired: true` with
+`guideRequiredReasons: ["connector_required"]` on discovery results.
+
+It is an instruction, not a gate. Nothing refuses the call — connecta tells the
+agent to read the guide first and then believes it, because a server-side
+refusal here would be a policy engine, which
+[`ethos.md`](../ethos.md) refuses.
+
+Reserve it for connectors whose correct arguments or sequence *cannot* be
+expressed by the downstream tool schema at all: generic API wrappers whose one
+broad tool name carries no endpoint vocabulary, and cross-operation conventions
+no single schema can state. Two categories already produce the flag on their
+own and must not be hand-declared for it — an unannotated or write-capable tool
+(`approval_required`) and a compact schema that was capped
+(`schema_truncated`). `connector_required` and `approval_required` survive
+exact schema expansion; `schema_truncated` clears once describe returns the
+exact shape.
+
+The failure mode of over-declaring is quiet and expensive: an agent that must
+fetch a guide before every call pays that fetch on the calls where the schema
+was already complete and unambiguous. `required` earns its cost on connectors
+where the alternative is a wrong call, not on connectors where it is a slightly
+slower right one.
+
+## Provider conventions
+
+The maintained prebuilt connections come in two shapes, and each has its own
+convention set — including the shape of its usage guide, which is one of the
+few things both shapes fully own:
+
+- [Hand-written HTTP providers](./provider-conventions.md#hand-written-http-providers)
+  (H1–H14) — `api()` surfaces where Connecta owns every name, schema,
+  projection, and error. Cloudflare and Notion.
+- [Hosted-MCP proxies](./provider-conventions.md#hosted-mcp-proxies) (P1–P13) —
+  `remoteMcp()` wrappers where the downstream owns the catalog and Connecta
+  owns the endpoint, credential, classification, guide, and budget. Linear,
+  Stripe, and Mixpanel.
+
+Both sets are judged by one measure: what the convention saves the model that
+interacts with connecta, priced in discovery tokens, wrong-tool selection,
+argument retries, or result size. The same document defines
+[what a provider audit checks](./provider-conventions.md#what-the-audit-checks),
+so [#342](https://github.com/zackbart/connecta/issues/342) can run against it
+convention by convention rather than by taste.
+
+Two of those conventions decide how a guide is written, and they differ by
+shape. A hand-written provider's guide carries only what a schema cannot,
+because it owns the schemas and should fix them instead
+([H13](./provider-conventions.md#h13--the-guide-carries-only-what-a-schema-cannot)).
+A proxy's guide carries the reduction and identity-resolution advice its
+schemas will never carry, because it cannot change them
+([P7](./provider-conventions.md#p7--the-guide-carries-the-reduction-advice-the-schemas-cannot),
+[P8](./provider-conventions.md#p8--identity-resolution-comes-before-action)).
+
+## 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.

package/documentation/connectors.md

@@ -111,6 +111,11 @@ export const connecta = createConnecta({
 All three are ordinary `Connector` instances by the time the registry sees
 them. Nothing in the list is privileged by how it was authored.
 
+What a maintained connection owes an agent is written down rather than
+inherited from whoever wrote it last:
+[provider conventions](./provider-conventions.md), one set for hand-written
+HTTP surfaces and one for hosted-MCP proxies.
+
 Maintained provider guides:
 
 - [Cloudflare](./cloudflare.md)
@@ -119,6 +124,90 @@ Maintained provider guides:
 - [Notion](./notion.md)
 - [Stripe](./stripe.md)
 
+## The `api()` construction contract
+
+`api()` is the path every custom integration takes, and whatever it accepts is
+what an agent eventually reads. Three things are refused at construction rather
+than discovered in production
+([#340](https://github.com/zackbart/connecta/issues/340)):
+
+- **A tool with no description.** Discovery has nothing else to route on, and a
+  guess costs a call.
+- **A tool with no explicit boolean `annotations.readOnlyHint`.** `true`
+  declares a read and admits the tool to `call_tool` and `execute_code`;
+  `false` declares work that crosses `call_destructive_tool`, where the host
+  can ask a human. Connecta never infers the classification from a tool name,
+  description, schema, HTTP method, or the other annotations — an unclassified
+  tool is a bug in the deployment, not a puzzle to solve.
+- **An `inputSchema` the validator cannot compile.** Declaring one is optional;
+  declaring one that cannot be enforced is not. A schema that only reveals
+  itself on first use — an unresolvable `$ref`, say — fails that call as
+  non-retryable `invalid_args` rather than forwarding raw arguments to the
+  handler. `validateArgs: false` still opts out of enforcement for deployments
+  that want loose coercion; it does not opt out of the schema being real.
+
+None of this reaches a proxied catalog: hosted-MCP tools arrive as their
+downstream wrote them, and an unannotated or contradictory one stays
+fail-closed onto `call_destructive_tool`. The contract binds the surfaces we
+write, not the catalogs we relay.
+
+## The guarded fetch transport
+
+Every hand-written HTTP surface re-derives the same safety machinery, and two
+of them had already derived it slightly differently. `src/connectors/guarded-fetch.ts`
+is that machinery extracted once ([#341](https://github.com/zackbart/connecta/issues/341)):
+one `guardedFetch({ provider, baseUrl, headers, maxResponseBytes, authenticate })`
+factory returning the transport a connector sends every request through.
+
+What it owns is mechanical and provider-independent:
+
+- **Confinement.** A request path is provider-relative, carries no query or
+  fragment, and is re-checked against the base origin and path prefix *after*
+  `new URL` normalization — because normalization is how a path escapes a
+  prefix, not something to trust before it.
+- **Construction.** Query parameters are encoded rather than concatenated, a
+  JSON body is serialized with the `Content-Type` to match, and a pre-framed
+  body gets none, so `fetch` still picks the multipart boundary.
+- **Credential forwarding.** `authenticate` is called once per request and its
+  headers are applied last; a request header wearing one of their names is
+  refused rather than allowed to shadow it. A 3xx is refused outright — a
+  redirect is an instruction to re-send the credential to whatever origin the
+  `Location` names, and a confinement a redirect can undo was never one.
+- **Bounded reads.** `maxResponseBytes` is required, not defaulted: what counts
+  as an absurd response is a fact about the API, not about HTTP. A declared
+  `Content-Length` past the ceiling fails before a byte is read, and a
+  streaming body is abandoned at the ceiling rather than buffered past it.
+- **Normalization.** An unreachable provider becomes a retryable `unavailable`
+  instead of whatever `TypeError` the runtime threw, and `ctx.signal` rides
+  every request.
+
+What it deliberately does not own is meaning. It never reads a status code and
+never invents an authentication scheme: the provider's `authenticate` callback
+supplies the headers, and the provider's mapper turns one `GuardedResponse`
+into a result or a typed failure. That split is not fastidiousness. Notion's
+403 means a capability the integration was never granted — re-authorizing
+cannot fix it — while Cloudflare's means a token scope, and the two want
+opposite next moves. A helper that guessed would be wrong for one of them.
+
+Cloudflare and Notion both run on it. Their existing suites carried over
+unchanged, which proves the migration kept the behavior those suites cover —
+not that nothing changed. Three things did, and the changelog names them: a
+3xx is refused where both providers used to follow it, both now fail past
+their byte ceiling, and `cloudflare()`'s `baseUrl` is validated at
+construction. Each suite gained one test for the ceiling, because the one
+guard the helper was written to add is the one a provider's own mapper can
+most easily disarm: a bare `catch` around `response.json()` swallows the
+transport's refusal along with a parse error, and turns a response nobody was
+allowed to read into an empty success. A mapper re-throws
+`ConnectorCallError` and swallows only what it recognizes.
+
+It is **not exported this release**: the two migrations proved the shape
+preserves behavior for connectors that already had this machinery, not that it
+is the right shape for an author starting from nothing, and an unexported
+symbol costs nothing to reshape while a published one is a promise.
+The provider audit ([#342](https://github.com/zackbart/connecta/issues/342))
+supplies the third caller that would settle it.
+
 ## MCP version skew
 
 Connecta deliberately sits between protocol generations

package/documentation/linear.md

@@ -11,6 +11,7 @@ import { linear } from "@zackbart/connecta/providers/linear";
 const tracker = linear("product_tracker", {
   title: "Product issue tracking",
   purpose: "Issue and project planning for the platform team",
+  access: "read-write",
   instructions: "File bugs into the Platform team unless the request names another.",
 });
 ```
@@ -23,13 +24,21 @@ cannot change the connector's safety classification.
 
 ## Access modes
 
-Linear publishes two hosted endpoints, and `access` selects between them:
+Linear publishes two hosted endpoints, and `access` selects between them. It is
+**required**, with no default:
 
 | `access` | Endpoint | OAuth scopes |
 | --- | --- | --- |
-| `"read-write"` (default) | `https://mcp.linear.app/mcp` | `read`, `write` |
+| `"read-write"` | `https://mcp.linear.app/mcp` | `read`, `write` |
 | `"read-only"` | `https://mcp.linear.app/mcp/readonly` | `read` |
 
+There is no safe default to pick. Defaulting to `"read-write"` hands a
+deployment write access it never asked for; defaulting to `"read-only"` turns a
+deployment that does write into one whose every write fails at Linear — at
+runtime, where no agent can repair it. So the operator declares which one this
+is, and a deployment that forgot fails at construction with a message naming
+both options.
+
 Read-only is not a client-side filter. The endpoint advertises the `read` scope
 alone, so the token minted for it cannot reach Linear's write APIs — a stronger
 guarantee than any annotation Connecta applies. A deployment that only reports
@@ -63,6 +72,7 @@ also accepts a bearer token or a personal API key passed directly in the
 ```ts
 linear("automation_tracker", {
   purpose: "Headless release reporting",
+  access: "read-only",
   auth: {
     type: "headers",
     headers: { Authorization: env.LINEAR_API_KEY },
@@ -130,6 +140,7 @@ one. An operator who knows their workspace can supply one explicitly:
 ```ts
 linear("product_tracker", {
   purpose: "Issue and project planning for the platform team",
+  access: "read-write",
   callAdmission: {
     rules: [
       { budget: { kind: "rolling-window", maxCalls: 1_000, windowMs: 3_600_000 } },
@@ -141,3 +152,10 @@ linear("product_tracker", {
 A budget-only rule needs no queue. If you add `maxConcurrency` you are asking
 for a queue, and the admission controller then requires the rest of the queue
 settings at construction.
+
+## Conventions
+
+This connection is audited against
+[the provider conventions](./provider-conventions.md). Its verdict per
+convention, including every recorded exception, is the Linear section of
+[the provider audit](./provider-audit.md).