@zackbart/connecta 0.16.0 → 0.17.0

package/documentation/code-mode.md

@@ -53,8 +53,8 @@ createConnecta({
 });
 ```
 
-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).
+Dynamic Workers require the Workers Paid plan. The supported constructor passes only `loader`; `bindings`, `modules`, or
+`globalOutbound` grant ambient guest authority and violate `P2`. The [Worker example](../examples/worker/README.md#code-mode) carries the full setup.
 
 ## What an executor must implement
 
@@ -104,8 +104,8 @@ Connecta passes exactly one provider, named `connecta`. An executor must:
    uncaught tool failure keeps its type (`E1`).
 6. **Capture `console.log`, `console.warn`, and `console.error`** into `logs` in
    call order (`R5`), bounding what it retains.
-7. **Bound the guest**: wall clock, memory, stack, and CPU (`L3`, `L5`), with no
-   network, filesystem, environment, or import capability (`P2`).
+7. **Bound the guest**: wall clock, memory, stack, and CPU (`L3`, `L5`). Keep
+   ambient capabilities within the documented and tested `P2`/`X5` boundary.
 8. **Grant no ambient authority of its own.** Never back this with `eval` or
    `node:vm`: the sandbox is a containment layer on top of connecta's boundary,
    not a replacement for it, and every capability arrives through `fns`.
@@ -138,10 +138,10 @@ reinterpreted, so do not rely on it.
 It is host plumbing, callable but not contract: it takes a connector id and an
 unsanitized-or-sanitized tool name and can change shape without notice.
 
-Anything else a runtime happens to expose is outside the contract and must not
-be used, even where it exists. Neither executor grants network egress,
-filesystem access, credentials, or deployment configuration; what they leave
-lying around otherwise differs (`X5`).
+Anything else a runtime happens to expose is outside the portable contract and
+must not be used. QuickJS grants none of it. A loader-only Dynamic Worker denies
+external egress and filesystem access and keeps its environment maps empty, but
+it exposes the globals and runtime builtins described in `X5`.
 
 **P3.** Values cross the host bridge as JSON. Arguments must be
 JSON-serializable and results arrive as plain JSON values. A value outside JSON —
@@ -154,8 +154,9 @@ scratch storage carried to the next program, and no request-bound object outlive
 the request that created it. Within one execution, host calls share one
 downstream request scope.
 
-**P5.** Plain JavaScript only. TypeScript syntax is a syntax error, and there is
-no `import` or `require` to reach for.
+**P5.** Plain JavaScript only. TypeScript syntax is a syntax error. Portable code
+does not import: QuickJS blocks imports, while Dynamic Workers expose the `X5`
+runtime modules. Neither executor exposes `require`.
 
 ## Addressing
 
@@ -240,8 +241,8 @@ can set `includeSchemaKeys: false` to buy the bytes back.
 **S3.** Discovery is bounded and the bounds throw rather than silently shrink: a
 `limit` outside 1–100 is `invalid_args`, and a page whose serialized form
 exceeds 256,000 bytes is `result_too_large`, each with a hint naming the ways to
-ask for less. As with every failure, the *thrown* error carries only the message
-(`E1`); the code appears when the failure escapes the program uncaught.
+ask for less. The thrown error carries the stable `code`, `retryable`, and
+`details` fields (`E1`).
 
 ### connecta.describe
 
@@ -295,9 +296,7 @@ order. A success is `{ address, ok: true, data }`. A failure is
 field names the host's internal batch path uses. One failing call never rejects
 the batch, and more than ten calls throws.
 
-**S8.** `connecta.batch` is the classification channel: because a thrown host
-error crosses the bridge as a bare message (`E1`), a batch of one is the supported
-way for a program to *decide* something about a failure rather than report it.
+**S8.** Batch and thrown failures share one vocabulary (`E1`): an entry's `errorDetails.code` and `retryable` equal the fields on the error the same call would throw. Use batch for independent concurrency, not to recover lost type.
 
 ### connecta.emit
 
@@ -310,27 +309,20 @@ clauses are [Emitted output](#emitted-output) (`M1`–`M10`).
 
 ## Errors
 
-**E1.** There are four error channels, and only two of them are typed.
+**E1.** There are four error channels. Connecta failures are typed whether caught or uncaught.
 
 | Channel | Shape | Typed? |
 | --- | --- | --- |
-| A throw inside the program | `Error` with `message` only | no |
+| A caught Connecta host failure | `Error` with `message`, `code`, `retryable`, and `details` | yes |
 | `connecta.batch` outcome | `{ ok: false, error, errorDetails }` | yes |
 | An uncaught **tool or discovery** failure, as the model sees it | `{ error: { code, message, retryable, … } }` with `isError` | yes |
-| Anything else that ends the run (`E5`, `E6`, a bridge bound in `L6`) | error text | no |
+| Program or execution failure (`E5`, `E6`, a bridge bound in `L6`) | error text | no |
 
-The message-only throw is a hard limit of the guest bridge: both executors reduce a rejected
-host call to `new Error(message)`, dropping every own property. A program must
-therefore never branch on an error's fields and never parse its message. To
-classify, use `errorDetails`; to hand a failure to the model with its type
-intact, let it escape uncaught — connecta re-attaches the typed details on the
-way out. The model-facing version of this lives in `execute_code`'s description,
-not in the always-loaded usage skill, which `test/meta-tools.test.ts` caps at
-2,500 bytes — a budget the guide already spends nearly all of, so new text there
-displaces old rather than adding to what every request pays for.
+Both executor bridges reduce a rejected host call to `new Error(message)`. Connecta restores the typed failure in a trusted prelude with a per-execution authenticated frame (`X11`), without turning the rejection into a returned value.
+`message` remains the human text. `code` and `retryable` are the stable branch fields; `details` is the complete host classification. This covers `call`, connector shortcuts, `search`, `describe`, `emit`, `ui`, rejected batch input, and the host-call budget.
+Program-authored errors stay untyped, and code must never parse error prose.
 
-**E2.** The taxonomy. `retryable` is what connecta reports; `Y3` says what a
-program may do about it.
+**E2.** The taxonomy: `retryable` is what connecta reports, `Y3` what a program may do.
 
 | Code | Raised when | `retryable` |
 | --- | --- | --- |
@@ -340,15 +332,18 @@ program may do about it.
 | `destructive_tool_requires_approval` | the tool is not explicitly read-only | false |
 | `auth_required` | the credential is missing, expired, or rejected | false |
 | `invalid_args` | arguments or discovery bounds were rejected | false |
+| `not_found` | the downstream answered and the resource is not there — the one code that says skip this id rather than stop, raised only where the provider tells absence from a permission gap ([H11](./provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next)) | false |
 | `input_required_unsupported` | a downstream asked for mid-call input | false |
 | `rate_limited` | the downstream reported a rate limit | true |
 | `unavailable` | the downstream is down or unreachable | true |
 | `timeout` | the per-call 15-second deadline expired | true |
 | `cancelled` | the run ended while this call was in flight (`E5`) | false |
-| `connector_call_failed` | anything else the connector threw, and the host-call budget (`L4`) | per message |
+| `connector_call_failed` | anything else the connector threw | per message |
 | `batch_call_failed` | a `connecta.batch` entry connecta could not even attempt | per message |
 | `catalog_lookup_failed` | the connector's catalog could not be loaded | per cause |
 | `result_processing_failed` | the result could not be prepared | per message |
+| `result_too_large` | a discovery response exceeded its byte bound | false |
+| `budget_exceeded` | the run exhausted a host-call or emitted-output budget | false |
 
 **E3.** `auth_required` carries the same recovery envelope as `call_tool`:
 `connector`, `operation`, `recovery` (`oauth`, `operator_config`, or
@@ -608,25 +603,22 @@ annotation-gated `maxRetries`; code mode fixes it at zero, so one
 `connecta.call` is exactly one downstream attempt. The program is the retry
 loop, and its budget is visible to it (`L4`).
 
-**Y2.** A program may retry a failure whose `errorDetails.retryable` is true,
-learned through `connecta.batch` (`S8`). Every attempt spends host-call budget,
-so a retry loop that ignores the budget converts a transient failure into a
-budget failure.
+**Y2.** A program may retry a caught failure whose `retryable` is true, or a batch failure whose `errorDetails.retryable` is true (`S8`). Every attempt spends host-call budget, so an unchecked loop converts a transient failure into `budget_exceeded`.
 
 **Y3.** What must never be retried automatically:
 
 - anything with `retryable: false` — a policy refusal, a missing credential, a
   bad address, or malformed arguments will fail identically forever;
-- `rate_limited`, immediately. The sandbox has no timers, so a program cannot
-  wait out a window; retrying inside it is the harm the signal exists to
-  prevent. Return the failure and let the model, which can wait, re-issue with
-  `retryAfterMs` in hand.
+- `rate_limited`, immediately. A portable program has no timer, and a
+  Dynamic-Worker-only wait would spend the run's wall-clock budget on code that
+  fails on QuickJS. Return the failure and let the model, which can wait,
+  re-issue with `retryAfterMs` in hand.
 - a cancelled or timed-out *execution*: it is already over (`L1`).
 
 **Y4.** Connecta's own retry machinery beneath the meta-tools honours a
 connector-reported `Retry-After` exactly or not at all, and declines windows
 longer than 10 seconds rather than shortening them. A program sees the window
-verbatim as `errorDetails.retryAfterMs`.
+verbatim as `err.details.retryAfterMs` or `errorDetails.retryAfterMs`.
 
 ## Cancellation and limits
 
@@ -656,10 +648,7 @@ because connecta enforces them above the sandbox:
 | Result | 24,000 serialized characters |
 | Logs presented to the model | 4,000 characters |
 
-Exhausting the host-call budget fails that call like any other, with code
-`connector_call_failed` (`E2`) and a message naming the budget — no connector was
-reached, so nothing more specific is true. Retrying it is pointless: the budget
-does not refill inside one execution.
+Exhausting the host-call budget fails that call with non-retryable `budget_exceeded` (`E2`) and a message naming the budget. No connector is reached, and the budget does not refill inside one execution.
 
 **L5.** The guest is memory-, stack-, and CPU-bounded, and a program that
 exhausts a bound ends the run with an error instead of degrading the host. The
@@ -672,7 +661,7 @@ code safe to run at all.
 **L6.** A host call's serialized arguments and its serialized result are each
 bounded — QuickJS caps both at 256 KiB (`X10`) — and exceeding either fails that
 call, not the execution, so a program can catch it and ask for less. The failure
-is untyped text (`E1`). An over-bound *result* names the address the program
+is executor-owned untyped text, not a Connecta host failure (`E1`). An over-bound *result* names the address the program
 called, not the internal dispatcher behind the shortcut namespaces; an over-bound
 *argument* payload is refused before it is parsed, so it names no address at
 all — parsing it to write a better message would spend exactly the work the bound
@@ -750,11 +739,9 @@ Worker renders arguments with `String()` (so an object logs as
 latter two. Only the three captured everywhere are contract (`R5`); rendering is
 not.
 
-**X5. Leftover globals.** The QuickJS guest has no `fetch`, `process`, timers,
-`crypto`, or `WebSocket` at all. The Dynamic Worker guest has all of them:
-`fetch` exists but throws on use because outbound access is disabled,
-`process.env` is empty, and timers work. `P2` is the contract — a program that
-uses `setTimeout` is writing Workers-only code, and it will fail on Node.
+**X5. Leftover authority.** QuickJS blocks imports and has no `fetch`, `process`, timers, `crypto`, or `WebSocket`. A Dynamic Worker has those globals plus a non-contract set of runtime builtins through `import()` and `process.getBuiltinModule()`, including `node:path`, `node:crypto`, `node:net`, `node:tls`, `node:dns`, `node:module`, and `cloudflare:workers`. The upstream set can drift; this list is not an allowlist.
+The supported Worker construction is exactly `new DynamicWorkerExecutor({ loader })`. Do not pass `bindings`, `modules`, or `globalOutbound`: each can grant ambient configuration, code, or egress. Under it, `process.env`, lexical `this.env`, and `cloudflare:workers.env` are empty; `node:fs`, `node:http`, and `node:https` are unavailable through either access route; external `fetch`, `WebSocket`, `node:net`, and `node:tls` fail with workerd's outbound-denial error; DNS lookup ends unresolved; and `fetch("data:...")` resolves locally.
+`P2` is the portable contract. Programs use none of this runtime-only authority, including timers and `crypto`, because the same code fails on QuickJS. The `execute_code` description and served `usage` skill say so before an agent writes code.
 
 **X6. Stall detection.** QuickJS notices a program awaiting something that can
 never settle and fails fast; the Dynamic Worker waits for its deadline. The fast
@@ -786,11 +773,16 @@ a `process.send` with a hard ceiling. A program that returns a quarter-megabyte
 from one tool call therefore fails on Node and may succeed on Workers — reduce
 inside the program either way (`R1`).
 
+**X11. Typed host rejection.** Both executors rebuild Connecta's authenticated host-failure frame as a thrown guest `Error` (`E1`). The per-run secret stays in the trusted prelude closure, and the prelude locks `globalThis.Error`, so guest code and connector prose cannot forge the host transport frame.
+The human message is unchanged; a mismatched frame is ordinary untyped prose.
+
 ## Changes from earlier code mode
 
-Five behaviors changed with this contract, matching the changelog's Unreleased
+Six behaviors changed with this contract, matching the changelog's Unreleased
 entry. Programs that ran before still run.
 
+- **Caught Connecta failures expose their classification** (`E1`, `X11`). Their human message and thrown semantics stay unchanged; `code`, `retryable`, and `details` are additive.
+
 - **`connecta.batch` failures gained `errorDetails`** (`S7`). They carried only a
   message, which left a program unable to tell a policy refusal from a transient
   failure. Additive, and it reuses the host's internal batch field names, so a
@@ -833,7 +825,7 @@ the upstream `Executor` shape assignable.
 | Clauses | Test |
 | --- | --- |
 | `P1`, `P5` | `test/guest-api-contract.test.ts` (TypeScript syntax), `test/quickjs-executor.test.ts` (`normalizeCode`) |
-| `P2`, `X5` | `test/guest-api-contract.test.ts` (no usable network, no config) |
+| `P2`, `X5` | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.test.ts` (exact absent globals and blocked imports), `test/deployment-shapes.test.ts` (loader-only Worker construction) |
 | `P3`, `X9` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` |
 | `P4` | `test/guest-api-contract.test.ts` (no cross-run leakage), `test/execute.test.ts` (one catalog load per connector per execution) |
 | `A1`, `A2` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (sanitizing) |
@@ -846,8 +838,8 @@ the upstream `Executor` shape assignable.
 | `S5` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`unwrapMcpResult`) |
 | `S6` | `test/execute.test.ts` (fail-closed annotations, activity parity) |
 | `S7` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (batch cap) |
-| `S8`, `E1` | `test/guest-api-contract.test.ts` (typed batch outcomes) |
-| `E2`, `E8` | `test/guest-api-contract.test.ts` (code → `retryable`, batch and uncaught validation recovery), `test/meta-tools.test.ts` (direct, destructive, batch, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts` |
+| `S8`, `E1`, `X11` | both guest-contract executors (caught call, namespace, discovery, utility, batch-validation, budget, and forgery cases; typed batch equivalence) |
+| `E2`, `E8` | `test/guest-api-contract.test.ts` (code → `retryable`, caught, batch, and uncaught validation recovery), `test/meta-tools.test.ts` (direct, destructive, batch, provider fallback), `test/validate.test.ts` (bounded payload-free findings), `test/errors.test.ts` |
 | `E3` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (`auth_required`) |
 | `E4` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (destructive) |
 | `E5` | `test/guest-api-contract.test.ts` (execution-failure channel, in-flight `cancelled`), `test/execute.test.ts` (admission), `test/executor-admission.test.ts`, `test/quickjs-executor.test.ts` (mid-run shutdown) |

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`
@@ -229,7 +238,13 @@ results explain that no single tool covered every term and recommend splitting
 distinct intents. A true negative says that no matching capability is
 configured and recommends refining, connector-scoping, or browsing; when a
 connector catalog was unavailable, the response includes
-`unavailableConnectorCount` instead of making that stronger claim. A search
+`unavailableConnectorCount` instead of making that stronger claim. A no-match
+query whose terms name a configured connector's `id` or `title` never makes it
+either: connector identity is not in the lexical index — indexing it would move
+ranking for every query that already matches tools — so instead the guidance on
+an unscoped miss names up to three such connectors by ID and sends the caller
+to a scoped browse. Identity affects that one sentence and nothing else: no
+ranking, no result, and no new field. A search
 explicitly scoped to that unavailable connector also receives `catalogError` —
 the bounded classified failure (`code`, `message`, `retryable`, and any
 `retryAfterMs`) so the caller can tell a transient outage from one a deployment

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/notion.md

@@ -166,7 +166,7 @@ should do next, and two of Notion's are easy to mistranslate.
 | 400 (`validation_error`, `invalid_json`, `invalid_request`, `missing_version`, …) | `invalid_args` | every documented 400 is a malformed request |
 | 401 `unauthorized` | `auth_required` | the token is missing or invalid |
 | 403 `restricted_resource` | `connector_call_failed`, non-retryable | **not** `auth_required` |
-| 404 `object_not_found` | `connector_call_failed`, non-retryable | overloaded; see below |
+| 404 `object_not_found` | `connector_call_failed`, non-retryable | overloaded — deliberately **not** `not_found`; see below |
 | 409 `conflict_error` | `unavailable`, retryable | Notion says to retry |
 | 429 `rate_limited` | `rate_limited` + `retryAfterMs` | `Retry-After` seconds → ms |
 | 529 `service_overload` | `unavailable` + `retryAfterMs` | back off like a 429 |
@@ -184,7 +184,12 @@ whose message says an operator must change it in Notion.
 object that does not exist and for one that exists but has not been shared with
 the integration, and it will not say which. The message says both, because
 treating it as deletion is exactly how an agent concludes a page is gone when
-it was simply never shared.
+it was simply never shared. This is why the row above does not use `not_found`,
+which exists precisely to say "it is not there": the qualifier on that code
+([H11](./provider-conventions.md#h11--errors-are-mapped-to-what-the-caller-does-next))
+is that the provider must tell absence apart from a permission gap, and Notion
+does not. A program that skipped this id as missing would be right about half
+the time, which is the half that matters.
 
 ## Rate limiting