@zackbart/connecta 0.16.1 → 0.17.0

package/dist/routes/mcp.js

@@ -234,6 +234,9 @@ async function serveMcp(request, opts, baseUrl, actor, registry, runtimeContext)
                 ? { discoveryConcurrency: opts.discoveryConcurrency }
                 : {}),
             requestSignal: request.signal,
+            ...(runtimeContext?.waitUntil
+                ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
+                : {}),
         });
         registerExecuteTool(server, registry, {
             baseUrl,
@@ -241,6 +244,9 @@ async function serveMcp(request, opts, baseUrl, actor, registry, runtimeContext)
             logger: opts.logger,
             ...(activity ? { activity } : {}),
             requestSignal: request.signal,
+            ...(runtimeContext?.waitUntil
+                ? { defer: runtimeContext.waitUntil.bind(runtimeContext) }
+                : {}),
             ...(opts.discoveryConcurrency !== undefined
                 ? { discoveryConcurrency: opts.discoveryConcurrency }
                 : {}),

package/dist/skills.d.ts

@@ -10,6 +10,10 @@ export declare function hasConnectorGuides(connectors: readonly Connector[]): bo
 export declare function connectorSkillName(connectorId: string): string;
 /** The connector's guide, or undefined when it declares none (or a blank one). */
 export declare function connectorGuide(connector: Connector): string | undefined;
+/** Discovery budget for one connector-guide summary, including an ellipsis. */
+export declare const GUIDE_SUMMARY_LENGTH = 120;
+/** Normalize authored and derived summaries under one construction contract. */
+export declare function normalizeGuideSummary(summary: string): string | undefined;
 /** Bounded, decision-useful discovery summary for a connector guide. */
 export declare function connectorGuideSummary(connector: Connector): string | undefined;
 /** Whether correct use always depends on conventions outside the tool schema. */

package/dist/skills.js

@@ -17,24 +17,24 @@ Use exact addresses from discovery; never invent one. Search 2–4 distinctive a
 
 ## Inside a program
 
-One async arrow function. The only capabilities are one global per connector (\`<connectorId>.<toolName>(args)\`), the \`connecta\` functions, and \`console.log\`.
+Portable code uses only connector globals (\`<connectorId>.<toolName>(args)\`), \`connecta\`, and \`console.*\`. QuickJS blocks imports and lacks fetch/process/timers/crypto/WebSocket. Dynamic Workers require only \`{ loader }\`; bindings/modules/globalOutbound violate it. Then env maps are empty; node:fs/http/https absent; outbound fetch/WebSocket/node:net/tls denied; DNS unresolved. Runtime builtins remain through import() and process.getBuiltinModule(), including node:path and cloudflare:workers; the set can drift. Timers/process/crypto/WebSocket and data: fetch remain. Avoid them; QuickJS fails.
 
 - \`connecta.search({})\` loads all catalogs; pass \`connector: "<id>"\` when obvious to load one. \`safety: "readOnly"\` keeps executable calls. Neither grants authority. Matches carry \`address\` and annotations.
 - Exact schemas: \`connecta.describe({ address: "connector.tool" })\` for one, \`{ addresses: [...] }\` for many; \`format: "json"\` only for exact constraints.
-- Two to ten independent calls: \`connecta.batch([...])\`. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails: { code, retryable } }\` — how a program tells a policy refusal from a transient failure.
-- Search inside the run, not before it; return only the reduction the answer needs, never raw payloads.
+- Caught Connecta errors have \`message\`, \`code\`, \`retryable\`, and \`details\`; branch on fields. For 2–10 independent calls, \`connecta.batch([...])\` returns success data or an \`errorDetails\` whose code and retryable flag match the throw.
+- Search inside the run; return only the reduction the answer needs, never raw payloads.
 - Only tools annotated \`readOnlyHint: true\` are reachable; the gate, credentials, and admission are enforced below the sandbox — nothing a program does widens its reach.
 
 ## Rendering a view
 
-\`connecta.ui(html)\` renders a display-only view on success for the client, never for the model. Fetch first, check the shape in code. On a surprise — empty array, missing key — return a trimmed first record instead of rendering: the wrong view becomes the sample you needed. Otherwise render from the variables you return; the model reads the return value, not the view.
+\`connecta.ui(html)\` renders one success-only display view, never for the model. Fetch and check the shape first. On empty or missing data, return a trimmed first record instead of rendering. Otherwise render returned variables; the model reads the return value, not the view.
 
 `;
 /** Deployment-scoped guide routing appended to the shared usage guide. */
 const CONNECTOR_GUIDES_SECTION = `
 ## Per-connector guides
 
-When a connector here ships a deployment-scoped usage guide, \`skills({})\` and discovery return the exact \`guide\` name plus a bounded \`guideSummary\` saying what it covers. Fetch only a listed or carried name with \`skills({ name: <guide> })\`; never infer one from a connector id. \`guideRequired: true\` is a hard stop: fetch before calling. \`guideRequiredReasons\` says why — \`connector_required\` and \`approval_required\` stand however you expand the schema; \`schema_truncated\` clears once describe returns the exact one. Otherwise fetch when the summary names a connector-specific sequence, unit, pagination rule, alias, or generic API convention relevant to the task. A read-only call whose compact schema is complete and unambiguous may proceed without fetching an otherwise irrelevant guide. Connector guides do not replace the shared Connecta usage guide and never apply to another deployment implicitly.
+Connector guides appear in \`skills({})\` and discovery with an exact \`guide\` name and bounded \`guideSummary\`. Fetch only a listed or carried name with \`skills({ name: <guide> })\`; never infer one from a connector id. \`guideRequired: true\` is a hard stop. \`guideRequiredReasons\` says why: \`connector_required\` and \`approval_required\` stand after schema expansion; \`schema_truncated\` clears after exact describe. Otherwise fetch for a relevant sequence, unit, pagination rule, alias, or API convention. A read-only call with a complete compact schema may skip an irrelevant guide. Connector guides never apply to another deployment.
 `;
 /** Shared Connecta routing guidance, byte-identical across deployments. */
 export const USAGE_SKILL = USAGE_SKILL_BASE + CONNECTOR_GUIDES_SECTION;
@@ -80,17 +80,63 @@ export function connectorGuide(connector) {
     const content = typeof guide === "string" ? guide : guide?.content;
     return content && content.trim() !== "" ? content : undefined;
 }
-const SUMMARY_LENGTH = 120;
+/** Discovery budget for one connector-guide summary, including an ellipsis. */
+export const GUIDE_SUMMARY_LENGTH = 120;
 /** A `---`/`***`/`___` rule, which also opens and closes YAML frontmatter. */
 const RULE_RE = /^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
 /** A fenced code block's delimiter. */
 const FENCE_RE = /^\s*(?:```|~~~)/;
+/** Markdown blocks that end a paragraph without a blank physical line. */
+const HEADING_RE = /^\s*#{1,6}/;
+const LIST_ITEM_RE = /^\s*(?:[-*+]\s+|\d+[.)]\s+)/;
+const SETEXT_UNDERLINE_RE = /^\s*=+\s*$/;
+const TABLE_DELIMITER_RE = /^\s*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?\s*$/;
+const OPENS_CLAUSE_RE = /^(?:The|A|An)\b/u;
+const ARTICLE_RE = /^(?:the|a|an)\b/u;
 /**
  * Markup that carries no summary text of its own: horizontal rules, HTML
  * comments, and table rows. Skipped so a guide that opens with one is
  * summarized by its first real line instead of by punctuation.
  */
 const NOT_SUMMARY_RE = /^\s*(?:<!--|\|)|^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
+/** A standard Markdown table starts with a pipe-bearing row and delimiter. */
+function startsTable(lines, index) {
+    const header = lines[index] ?? "";
+    const delimiter = lines[index + 1] ?? "";
+    return header.includes("|") && TABLE_DELIMITER_RE.test(delimiter);
+}
+/** True when a sentence-looking period belongs to an abbreviation. */
+function isAbbreviation(text, end) {
+    const token = text.slice(0, end).match(/\S+$/u)?.[0] ?? "";
+    // These introduce an example or restatement even before a capitalized word.
+    if (/^(?:e\.g|i\.e)\.$/iu.test(token))
+        return true;
+    // An initial or title belongs to the proper name that follows it.
+    if (/^[A-Z]\.$/u.test(token))
+        return true;
+    if (/^(?:Mr|Mrs|Ms|Dr|Prof|Sr|Jr|St)\.$/iu.test(token))
+        return true;
+    if (!/^(?:[A-Za-z]\.){2,}$/u.test(token) &&
+        !/^(?:vs|etc|approx|dept|fig|no)\.$/iu.test(token)) {
+        return false;
+    }
+    // Initialisms can end a sentence or extend a name ("U.S. East region").
+    // The mistakes are asymmetric: a false ending presents a fragment as a
+    // complete thought, while a missed ending gets an honest ellipsis. Count
+    // the period only with narrow evidence of a new clause: an article in one
+    // of its first two words. This is grammar evidence, not a starter-word list.
+    const following = text
+        .slice(end)
+        .match(/^[)\]}'"”’]*\s+(\S+)(?:\s+(\S+))?/u);
+    if (!following)
+        return false;
+    const [, nextWord, afterNext] = following;
+    const startsClause = nextWord !== undefined &&
+        /^\p{Lu}/u.test(nextWord) &&
+        (OPENS_CLAUSE_RE.test(nextWord) ||
+            (afterNext !== undefined && ARTICLE_RE.test(afterNext)));
+    return !startsClause;
+}
 /** Drop a leading YAML frontmatter block — metadata, not summary text. */
 function withoutFrontmatter(lines) {
     let start = 0;
@@ -102,33 +148,107 @@ function withoutFrontmatter(lines) {
     const close = lines.findIndex((line, i) => i > start && RULE_RE.test(line));
     return close === -1 ? lines : lines.slice(close + 1);
 }
+/** Normalize authored and derived summaries under one construction contract. */
+export function normalizeGuideSummary(summary) {
+    const normalized = summary.replace(/\s+/g, " ").trim();
+    return normalized === "" ? undefined : normalized;
+}
 /**
- * One line describing a guide, for the cheap list view: the guide's first
- * meaningful line (heading marks and list bullets stripped), falling back to
- * the connector's own description when the guide opens with nothing but
- * markup.
+ * Shorten a normalized summary at the strongest readable boundary available.
+ * A complete sentence needs no ellipsis; clause and word cuts do, so discovery
+ * never presents an unfinished fragment as the guide's complete thought.
  */
 function boundedSummary(summary) {
-    const line = summary.replace(/\s+/g, " ").trim();
-    if (line === "")
+    const normalized = normalizeGuideSummary(summary);
+    if (!normalized)
         return undefined;
-    return line.length <= SUMMARY_LENGTH
-        ? line
-        : `${line.slice(0, SUMMARY_LENGTH - 1).trimEnd()}…`;
+    if (normalized.length <= GUIDE_SUMMARY_LENGTH)
+        return normalized;
+    const contentBudget = GUIDE_SUMMARY_LENGTH - 1;
+    let sentenceEnd = 0;
+    const sentenceBoundary = /[.!?…。！？](?:[)\]}'"”’]+)?(?=\s|$)/gu;
+    for (const match of normalized.matchAll(sentenceBoundary)) {
+        const end = (match.index ?? 0) + match[0].length;
+        if (end > GUIDE_SUMMARY_LENGTH)
+            break;
+        const punctuationEnd = (match.index ?? 0) + 1;
+        if (match[0].startsWith(".") &&
+            isAbbreviation(normalized, punctuationEnd)) {
+            continue;
+        }
+        // Do not mistake another short fragment for a useful complete thought.
+        if (end >= 24)
+            sentenceEnd = end;
+    }
+    if (sentenceEnd > 0)
+        return normalized.slice(0, sentenceEnd);
+    const available = normalized.slice(0, contentBudget);
+    let clauseEnd = 0;
+    const clauseBoundary = /[,;:](?=\s)|\s[—–-](?=\s)/g;
+    for (const match of available.matchAll(clauseBoundary)) {
+        const end = match.index ?? 0;
+        // Prefer a clause only when it retains most of the discovery budget.
+        if (end >= 80)
+            clauseEnd = end;
+    }
+    if (clauseEnd > 0) {
+        return `${available.slice(0, clauseEnd).trimEnd()}…`;
+    }
+    const wordEnd = available.search(/\s+\S*$/);
+    if (wordEnd > 0) {
+        const prefix = available
+            .slice(0, wordEnd)
+            .trimEnd()
+            .replace(/[,;:([{—–-]+$/u, "")
+            .trimEnd();
+        if (prefix !== "")
+            return `${prefix}…`;
+    }
+    let hardEnd = contentBudget;
+    const code = normalized.charCodeAt(hardEnd - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        hardEnd--;
+    return `${normalized.slice(0, hardEnd)}…`;
 }
+/**
+ * One thought describing a guide for the cheap list view: the first meaningful
+ * paragraph, joined across physical lines, with headings and the connector
+ * description as fallbacks when the guide opens with markup alone.
+ */
 function summarizeGuide(connector, guide) {
+    const lines = withoutFrontmatter(guide.split("\n"));
     let inFence = false;
+    let inComment = false;
     let headingFallback;
-    for (const raw of withoutFrontmatter(guide.split("\n"))) {
+    for (let index = 0; index < lines.length; index++) {
+        const raw = lines[index] ?? "";
+        if (inComment) {
+            if (raw.includes("-->"))
+                inComment = false;
+            continue;
+        }
         if (FENCE_RE.test(raw)) {
             inFence = !inFence;
             continue;
         }
         if (inFence)
             continue;
+        if (raw.trimStart().startsWith("<!--")) {
+            if (!raw.includes("-->"))
+                inComment = true;
+            continue;
+        }
+        if (startsTable(lines, index)) {
+            index++;
+            while (index + 1 < lines.length &&
+                (lines[index + 1] ?? "").includes("|")) {
+                index++;
+            }
+            continue;
+        }
         if (raw.trim() === "" || NOT_SUMMARY_RE.test(raw))
             continue;
-        const heading = /^\s*#{1,6}/.test(raw);
+        const heading = HEADING_RE.test(raw);
         const line = raw
             // `\s*` (not `\s+`) so a bare `#` strips to nothing and is skipped, and
             // an unspaced `#Heading` is still read as a heading.
@@ -142,7 +262,24 @@ function summarizeGuide(connector, guide) {
             headingFallback ??= boundedSummary(line);
             continue;
         }
-        return boundedSummary(line) ?? line;
+        const paragraph = [line];
+        while (index + 1 < lines.length) {
+            const next = lines[index + 1] ?? "";
+            if (next.trim() === "" ||
+                startsTable(lines, index + 1) ||
+                FENCE_RE.test(next) ||
+                HEADING_RE.test(next) ||
+                LIST_ITEM_RE.test(next) ||
+                SETEXT_UNDERLINE_RE.test(next) ||
+                NOT_SUMMARY_RE.test(next)) {
+                break;
+            }
+            paragraph.push(next.trim());
+            index++;
+            if (paragraph.join(" ").length > GUIDE_SUMMARY_LENGTH)
+                break;
+        }
+        return boundedSummary(paragraph.join(" ")) ?? line;
     }
     if (headingFallback)
         return headingFallback;
@@ -155,6 +292,8 @@ export function connectorGuideSummary(connector) {
     if (!guide)
         return undefined;
     const configured = typeof connector.usageGuide === "object"
+        // Registry construction rejects over-budget configured summaries. Keep
+        // normalization here so direct Connector callers see the same text.
         ? boundedSummary(connector.usageGuide.summary ?? "")
         : undefined;
     return configured ?? summarizeGuide(connector, guide);

package/dist/types.d.ts

@@ -180,6 +180,12 @@ export interface CatalogDriftReport extends CatalogDriftCounts {
     /** When the observation was taken; never when a probe was scheduled. */
     observedAt: string;
 }
+/** The last agent-facing catalog read this runtime served for one connector. */
+export interface CatalogAccessObservation {
+    /** Fresh means the read used a live or unexpired catalog; stale means SWR. */
+    state: "fresh" | "stale";
+    observedAt: string;
+}
 export interface ConnectorStatus {
     state: ConnectorStatusState;
     /** When state === "auth_required", the URL the operator should open. */
@@ -193,6 +199,11 @@ export interface ConnectorStatus {
      * isolate or process has seen nothing, not that nothing drifted.
      */
     catalogDrift?: CatalogDriftReport;
+    /**
+     * The last agent-facing catalog read in this runtime. This payload-free
+     * observation is not persisted and operator reads do not replace it.
+     */
+    catalogAccess?: CatalogAccessObservation;
 }
 /** The whole plugin contract — the one open seam. */
 export interface Connector {
@@ -313,8 +324,9 @@ export interface ConnectorUsageGuide {
     /** Markdown returned verbatim by `skills({ name: "connector:<id>" })`. */
     content: string;
     /**
-     * Bounded discovery hint describing the conventions the guide covers. When
-     * omitted, Connecta derives a summary from the guide's first meaningful line.
+     * Discovery hint describing the conventions the guide covers. Whitespace is
+     * normalized, and a value over 120 characters throws at construction. When
+     * omitted, Connecta derives a bounded summary from the first body paragraph.
      */
     summary?: string;
     /**

package/dist/ui.js

@@ -374,6 +374,9 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
             // `boundedCatalogDrift`, so what lands here cannot carry a name or a
             // schema even if the plugin seam returned one.
             ...(status.catalogDrift ? { catalogDrift: status.catalogDrift } : {}),
+            ...(status.catalogAccess
+                ? { catalogAccess: status.catalogAccess }
+                : {}),
             ...(c.disconnectAuth && c.startAuth ? { oauth: true } : {}),
             ...(credential ? { credential } : {}),
         };
@@ -461,7 +464,7 @@ export function renderUiHtml(uiAuth, mcpUrl = "/mcp", branding, nonce, page = "c
             : `<span class="product">${escapeHtmlAttr(brand.productName)}</span>`
         : "";
     const clerkScript = clerk && clerkScriptOrigin
-        ? `<script${nonceAttr} defer crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(clerk.publishableKey)}" src="${escapeHtmlAttr(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
+        ? `<script${nonceAttr} crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(clerk.publishableKey)}" src="${escapeHtmlAttr(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
         : "";
     return `<!doctype html>
 <html lang="en">

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.16.1";
+export declare const CONNECTA_VERSION = "0.17.0";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.16.1";
+export const CONNECTA_VERSION = "0.17.0";

package/documentation/architecture.md

@@ -26,7 +26,10 @@ ethos invariant, not a style preference: a client retained across requests on
 Workers is a cross-request capability leak, and a promise awaited after the
 response is work the runtime may have already torn down. Deferred work has one
 sanctioned channel — `ctx.waitUntil`, threaded through `fetch(request, env,
-ctx)` and used for best-effort activity writes.
+ctx)`. Best-effort activity writes use it. An agent read that already demanded
+an expired catalog refresh may also use it while serving a complete catalog
+inside its stale window. That refresh owns a new scope and deadline; it never
+carries the inbound scope or signal past the request.
 
 The registry is deliberately on the long side of that line and the MCP server
 deliberately on the short side. A fresh `McpServer` per request is what makes
@@ -87,8 +90,8 @@ owns or hands out, and a change usually belongs in exactly one of them:
 
 | Module | Owns |
 | --- | --- |
-| `src/registry.ts` | The connector set, id validation, address resolution, connector health, per-connector call limiters, and the drift snapshot. Construction-time refusal of structural mistakes lives here. |
-| `src/catalog-service.ts` | Tool listing: cold-load coalescing, TTL, persistence as manifest plus revision-addressed chunks, stale fallback, and the completeness rule — a partial catalog is a failure, never a cache write. |
+| `src/registry.ts` | The connector set, address resolution, catalog TTL/persistence/completeness, shared refresh single-flight, connector health, per-connector call limiters, and drift. Construction-time refusals live here. |
+| `src/catalog-service.ts` | Request-local tool listing, search, and describe. It coalesces reads inside one request and opts agent reads into the runtime's deferred catalog channel when one exists. |
 | `src/invocation.ts` | One tool call: argument validation, call admission, per-attempt timeout, retry with the connector's own `Retry-After` honoured exactly or declined, result unwrapping, size capping, and the activity record. |
 | `src/catalog.ts` | Ranking, description summarizing, and the compact schema renderer discovery shows. |
 
@@ -137,7 +140,7 @@ src/
   apps-shell.ts       the one build-time MCP Apps template
   skills.ts           MCP instructions, the usage skill, connector guides
   registry.ts         connector set, addresses, health, call limiters
-  catalog-service.ts  catalog loading, caching, persistence, stale fallback
+  catalog-service.ts  request-local catalog access, search, and describe
   catalog.ts          ranking, summaries, compact schema rendering
   invocation.ts       one tool call, end to end
   catalog-drift.ts    vetted manifests and the counts a refresh produces

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,24 +309,18 @@ 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 |
-
-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.
+| Program or execution failure (`E5`, `E6`, a bridge bound in `L6`) | error text | no |
+
+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` what a program may do.
 
@@ -339,16 +332,18 @@ displaces old rather than adding to what every request pays for.
 | `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, classified off `errorDetails` per `E1` and never off a caught error, 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 |
+| `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) |