@zackbart/connecta 0.18.3 → 0.20.0

package/dist/routes/mcp.js

@@ -186,7 +186,7 @@ async function serveMcp(request, opts, baseUrl, actor, registry, runtimeContext)
             // it — without this line no host reads execute_code's _meta.ui, no host
             // fetches the shell, and the whole design is inert. This is the one
             // extension connecta advertises; the versioned extensions framework
-            // stays declined as a general surface (documentation/mcp-2026-07-28.md).
+            // stays declined as a general surface (https://github.com/zackbart/connecta/blob/main/records/mcp-2026-07-28.md).
             capabilities: {
                 extensions: {
                     [MCP_APPS_EXTENSION]: { mimeTypes: [PROGRAM_UI_MIME_TYPE] },

package/dist/routes/oauth.js

@@ -174,9 +174,9 @@ function html(body, status = 200, branding) {
  * list the flat 400 was meant to withhold. So zero-I/O refusals read the same
  * keys in the same `conn:<id>:` namespace, where an unconfigured id gets misses.
  *
- * This is deliberately *not* a constant-time claim, and documentation/connectors.md says
- * so in prose: a hit and a miss are not identical in a KV store, and a connector
- * shipping its own `verifyState` may do more or less work. What it
+ * This is deliberately *not* a constant-time claim: a hit and a miss are not
+ * identical in a KV store, and a connector shipping its own `verifyState` may
+ * do more or less work. What it
  * removes is the order-of-magnitude "no I/O versus a round trip" difference,
  * which is the only part of the signal that makes enumeration cheap.
  *

package/dist/routes/shared.d.ts

@@ -6,38 +6,39 @@ import type { DeferredWork } from "../connector-scope.js";
 import type { AdmissionController } from "../executor-admission.js";
 import type { Registry } from "../registry.js";
 import type { ConnectaBranding, Executor, InboundAuth, Logger } from "../types.js";
+export { msg } from "../errors.js";
 export interface ServerOptions {
     registry: Registry;
     auth: InboundAuth[];
-    publicUrl?: string;
+    publicUrl?: string | undefined;
     serverInfo: Implementation;
     logger: Logger;
-    activity?: ActivityStore;
-    activityReadGate?: ActivityReadGate;
-    activityDeploymentId?: string;
-    deploymentInfo?: Record<string, unknown>;
+    activity?: ActivityStore | undefined;
+    activityReadGate?: ActivityReadGate | undefined;
+    activityDeploymentId?: string | undefined;
+    deploymentInfo?: Record<string, unknown> | undefined;
     /** Deadline for call_tool/call_destructive_tool calls that pass no timeoutMs. Off when unset. */
-    defaultToolTimeoutMs?: number;
+    defaultToolTimeoutMs?: number | undefined;
     /** Per-connector deadline for the search/describe probe fan-out. Default 30_000. */
-    probeTimeoutMs?: number;
+    probeTimeoutMs?: number | undefined;
     /** Maximum simultaneous connector discovery operations. Default 4. */
-    discoveryConcurrency?: number;
+    discoveryConcurrency?: number | undefined;
     /** Aggregate serialized-byte budget for connecta.emit per run. Default 4_000_000. */
-    maxEmittedBytes?: number;
+    maxEmittedBytes?: number | undefined;
     /** Block-count budget for connecta.emit per run. Default 32. */
-    maxEmittedBlocks?: number;
+    maxEmittedBlocks?: number | undefined;
     /** Required sandbox backing the execute_code meta-tool. */
     executor: Executor;
     /** Sanitized identity of the configured sandbox, when it has one. */
-    executorName?: string;
+    executorName?: string | undefined;
     /** Global FIFO boundary for all non-preflight `/mcp` requests. */
     requestAdmission: AdmissionController;
     /** Encrypted connector-credential storage backing the Credentials page. */
-    credentialVault?: CredentialVault;
+    credentialVault?: CredentialVault | undefined;
     /** Hashed deployment access tokens backing MCP admission and the Tokens page. */
-    accessTokens?: AccessTokenManager;
+    accessTokens?: AccessTokenManager | undefined;
     /** Optional browser UI and OAuth result-page labels. */
-    branding?: ConnectaBranding;
+    branding?: ConnectaBranding | undefined;
 }
 export interface RuntimeExecutionContext {
     waitUntil(promise: Promise<unknown>): void;
@@ -51,7 +52,6 @@ export interface RouteContext {
     defer: DeferredWork | undefined;
     runtimeContext: RuntimeExecutionContext | undefined;
 }
-export declare function msg(err: unknown): string;
 export declare function privateJson(body: unknown, init?: ResponseInit): Response;
 /**
  * Bounded, escaped form of a caller-influenced value (an identity id or OAuth

package/dist/routes/shared.js

@@ -1,7 +1,5 @@
 import { operatorPageForPath } from "../ui.js";
-export function msg(err) {
-    return err instanceof Error ? err.message : String(err);
-}
+export { msg } from "../errors.js";
 export function privateJson(body, init = {}) {
     const headers = new Headers(init.headers);
     headers.set("Content-Type", "application/json");

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
 import type { Connector } from "./types.js";
-export declare const CONNECTA_INSTRUCTIONS = "Choose a route before discovery. For one read at an unknown address, use search_tools then call_tool; a known address needs only call_tool. For read-only reduction, multiple or dependent calls, loops, joins, or branches, use one execute_code program that discovers, calls, and returns the reduced answer. Only readOnlyHint: true tools run there. Keep unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool. After auth_required use authorize_connector. After a truncated direct result use fields or get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Fetch skills({ name: \"usage\" }) once for program syntax, selection, repair, examples, and runtime details.";
+export declare const CONNECTA_INSTRUCTIONS = "Choose a route before discovery. For one read at an unknown address, use search_tools then call_tool; a known address needs only call_tool. For read-only reduction, multiple or dependent calls, loops, joins, or branches, use one execute_code program that discovers, calls, and returns the reduced answer. Only readOnlyHint: true tools run there. Keep unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool. After auth_required use authorize_connector. After a truncated direct result use get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Fetch skills({ name: \"usage\" }) once for program syntax, selection, repair, examples, and runtime details.";
 /** Shared Connecta routing guidance, byte-identical across deployments. */
 export declare const USAGE_SKILL: string;
 /** The always-loaded MCP `instructions` string. */

package/dist/skills.js

@@ -1,4 +1,4 @@
-export const CONNECTA_INSTRUCTIONS = 'Choose a route before discovery. For one read at an unknown address, use search_tools then call_tool; a known address needs only call_tool. For read-only reduction, multiple or dependent calls, loops, joins, or branches, use one execute_code program that discovers, calls, and returns the reduced answer. Only readOnlyHint: true tools run there. Keep unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool. After auth_required use authorize_connector. After a truncated direct result use fields or get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Fetch skills({ name: "usage" }) once for program syntax, selection, repair, examples, and runtime details.';
+export const CONNECTA_INSTRUCTIONS = 'Choose a route before discovery. For one read at an unknown address, use search_tools then call_tool; a known address needs only call_tool. For read-only reduction, multiple or dependent calls, loops, joins, or branches, use one execute_code program that discovers, calls, and returns the reduced answer. Only readOnlyHint: true tools run there. Keep unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool. After auth_required use authorize_connector. After a truncated direct result use get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Fetch skills({ name: "usage" }) once for program syntax, selection, repair, examples, and runtime details.';
 const USAGE_SKILL_BASE = `# Connecta usage
 
 ## The surface
@@ -17,7 +17,7 @@ The minimum guest API is:
 - \`connecta.call("connector.tool", args)\` uses the canonical address and returns the unwrapped value.
 - \`connecta.search(args)\` returns \`{ tools, total, offset, limit, hasMore }\`; \`connecta.describe(args)\` returns \`{ tools }\`.
 - \`connecta.batch(calls)\` runs 2–10 independent calls. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails }\`.
-- \`console.log(...)\` is captured. \`connecta.emit(block)\` and \`connecta.ui(html, options?)\` produce rich output.
+- \`console.log(...)\` is captured. \`connecta.emit(block)\` and \`connecta.ui(html)\` produce rich output.
 
 ## Discover and select
 
@@ -39,10 +39,10 @@ Caught Connecta errors expose \`message\`, \`code\`, \`retryable\`, and \`detail
 
 - \`destructive_tool_requires_approval\`: stop the program and use the returned canonical address with top-level \`call_destructive_tool\`.
 - \`auth_required\`: let the failure reach the model, then use top-level \`authorize_connector\`, give its handoff to the operator, and retry after recovery.
-- A truncated direct-call result: retry \`call_tool\` with \`fields\`, or follow its \`get_result\` action. A truncated program result has no page handle; filter, map, or slice inside a new program.
+- A truncated direct-call result: follow its \`get_result\` action. A truncated program result has no page handle; filter, map, or slice inside a new program.
 - Unknown addresses and tools carry scoped search recovery. Use it inside the current run. Do not invent an address.
 
-For a direct call, \`fields\` selects JSON dot-paths and \`[]\` traverses arrays, for example \`results[].id\`. Projection misses return \`data\` plus \`$connecta\` feedback. \`resultMode: "value"\` unwraps the result. \`timeoutMs\` sets its deadline. \`maxRetries\` is honored only for safely annotated tools. \`diagnostics: true\` adds timing.
+For a direct call, \`resultMode: "value"\` unwraps the result. \`timeoutMs\` sets its deadline. \`maxRetries\` is honored only for safely annotated tools. \`diagnostics: true\` adds timing.
 
 \`get_result({ id, offset?, maxBytes? })\` returns \`{ text, offset, nextOffset?, totalBytes }\` for a direct-call result. Both sizes are byte counts: \`maxBytes\` must be a whole number at least 1 and defaults to the deployment cap; \`offset\` must be a whole number at least 0 and defaults to 0. An offset inside a multi-byte character moves back to its first byte, and the response reports the served offset. Follow \`nextOffset\` to reassemble pages. An unknown or expired id is an error.
 
@@ -64,7 +64,7 @@ Dependent calls, only when the second needs a value from the first:
 
 ## Rendering a view
 
-\`connecta.emit\` accepts text, image, or audio blocks and delivers them only on success. \`connecta.ui(html)\` renders one success-only display view outside model context. One argument is display-only. Bind read-only refresh or drill-down calls with \`{ reads: { name: { address, fixedArgs?, viewArgs? } } }\`; page markup calls \`connecta.read(name, args)\`. Admission and one shared budget apply to the UI and emitted content, not separate budgets. Fetch and check the data shape first. On empty or missing data, return a trimmed first record instead of rendering. Otherwise render returned variables and return the same initial summary because the model reads the return value, not the view. A second, invalid, or over-budget UI call throws catchably.
+\`connecta.emit\` accepts text, image, or audio blocks and delivers them only on success. \`connecta.ui(html)\` renders one success-only display view outside model context. The view has local HTML and JavaScript only: no network, connector calls, discovery, conversation messages, or host links. One shared budget applies to the UI and emitted content, not separate budgets. Fetch and check the data shape first. On empty or missing data, return a trimmed first record instead of rendering. Otherwise render returned variables and return the same summary because the model reads the return value, not the view. A second, invalid, or over-budget UI call throws catchably.
 
 `;
 /** Deployment-scoped guide routing appended to the shared usage guide. */

package/dist/timeout.d.ts

@@ -5,13 +5,14 @@
 export declare const DEFAULT_PROBE_TIMEOUT_MS = 30000;
 /** A finite, positive integer number of milliseconds, or undefined. */
 export declare function normalizeTimeoutMs(value: number | undefined): number | undefined;
-/**
- * Reject `promise` after `ms` if it has not settled, so one hung downstream
- * cannot stall a whole fan-out. This form bounds only the caller-facing wait;
- * use `withAbortableTimeout` when the operation accepts an AbortSignal and the
- * underlying work must stop too.
- */
-export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;
+/** Resolve after `ms`, or false when the caller aborts first. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<boolean>;
+export interface DeadlineOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    timeoutError: Error;
+}
+export declare function withDeadline<T>(operation: (signal: AbortSignal) => Promise<T>, options: DeadlineOptions): Promise<T>;
 /**
  * Give one operation a caller-facing deadline and the matching cancellation
  * signal. The timeout rejects with the stable, labelled error while aborting

package/dist/timeout.js

@@ -12,24 +12,53 @@ export function normalizeTimeoutMs(value) {
     }
     return Math.max(1, Math.trunc(value));
 }
-/**
- * Reject `promise` after `ms` if it has not settled, so one hung downstream
- * cannot stall a whole fan-out. This form bounds only the caller-facing wait;
- * use `withAbortableTimeout` when the operation accepts an AbortSignal and the
- * underlying work must stop too.
- */
-export function withTimeout(promise, ms, label) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => {
-            reject(new Error(`${label} timed out after ${ms}ms`));
-        }, ms);
-        promise.then((value) => {
+/** Resolve after `ms`, or false when the caller aborts first. */
+export function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
             clearTimeout(timer);
+            signal?.removeEventListener("abort", cancel);
             resolve(value);
-        }, (err) => {
+        };
+        const timer = setTimeout(() => finish(true), ms);
+        const cancel = () => finish(false);
+        signal?.addEventListener("abort", cancel, { once: true });
+        if (signal?.aborted)
+            cancel();
+    });
+}
+export function withDeadline(operation, options) {
+    const controller = new AbortController();
+    const forwardAbort = () => controller.abort(options.signal?.reason);
+    options.signal?.addEventListener("abort", forwardAbort, { once: true });
+    if (options.signal?.aborted)
+        forwardAbort();
+    let rejectAbort;
+    const aborted = new Promise((_, reject) => { rejectAbort = reject; });
+    const onAbort = () => rejectAbort(controller.signal.reason ?? options.timeoutError);
+    controller.signal.addEventListener("abort", onAbort, { once: true });
+    if (controller.signal.aborted)
+        onAbort();
+    const timer = options.timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => controller.abort(options.timeoutError), options.timeoutMs);
+    let work;
+    try {
+        work = operation(controller.signal);
+    }
+    catch (error) {
+        work = Promise.reject(error);
+    }
+    return Promise.race([work, aborted]).finally(() => {
+        controller.abort();
+        if (timer)
             clearTimeout(timer);
-            reject(err);
-        });
+        controller.signal.removeEventListener("abort", onAbort);
+        options.signal?.removeEventListener("abort", forwardAbort);
     });
 }
 /**
@@ -38,28 +67,8 @@ export function withTimeout(promise, ms, label) {
  * any in-flight work that honors the signal.
  */
 export function withAbortableTimeout(operation, ms, label) {
-    const controller = new AbortController();
-    return new Promise((resolve, reject) => {
-        const timeoutError = new Error(`${label} timed out after ${ms}ms`);
-        const timer = setTimeout(() => {
-            controller.abort(timeoutError);
-            reject(timeoutError);
-        }, ms);
-        let promise;
-        try {
-            promise = operation(controller.signal);
-        }
-        catch (err) {
-            clearTimeout(timer);
-            reject(err);
-            return;
-        }
-        promise.then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        }, (err) => {
-            clearTimeout(timer);
-            reject(err);
-        });
+    return withDeadline(operation, {
+        timeoutMs: ms,
+        timeoutError: new Error(`${label} timed out after ${ms}ms`),
     });
 }

package/dist/types.d.ts

@@ -311,8 +311,8 @@ export interface Connector {
      * download link minted by one of the connector's tools. Called only after
      * every built-in route misses, so a connector can never shadow `/mcp`,
      * `/`, `/credentials`, `/activity`, `/health`, or the credential API. The
-     * first connector to return a
-     * Response wins, in registration order; return null to decline.
+     * first connector to return a Response wins, in registration order; return
+     * null to decline. See documentation/architecture.md route 9.
      *
      * These routes are PUBLIC: connecta applies no auth gate to them. A
      * connector that serves data here MUST authenticate the request itself — for
@@ -351,7 +351,7 @@ export interface ExecutorProvider {
      * Optional trusted sandbox-side setup run after provider globals exist.
      * Connecta uses this to install lazy connector namespace proxies without
      * materializing one host closure per tool. This is host-authored code, never
-     * model input.
+     * model input. See documentation/code-mode.md#what-an-executor-must-implement.
      */
     prelude?: string;
 }

package/dist/ui.d.ts

@@ -26,11 +26,6 @@ export declare function resolveBranding(branding?: ConnectaBranding): ResolvedBr
  * `resolveBranding` does — a warning helper must never throw.
  */
 export declare function droppedBrandingUrls(branding?: ConnectaBranding): string[];
-/**
- * True only for absolute `http:`/`https:` URLs. Downstream connectors control
- * their `authorizationUrl`, so a hostile/misconfigured one could hand back a
- * `javascript:` (or other) scheme; gate it before it can become an href.
- */
 export declare function isSafeHttpUrl(url: unknown): boolean;
 /**
  * True for values allowed in the page's `<link rel="icon" href>`: an absolute
@@ -52,26 +47,7 @@ export declare function isSafeHttpUrl(url: unknown): boolean;
  * on its own it would accept an authority that happened to equal the probe host.
  */
 export declare function isSafeIconHref(href: unknown): boolean;
-/**
- * True only for an absolute `https:` URL — the gate every `uiAuth` URL passes:
- * `frontendApiUrl`, which becomes the operator shell's sign-in loader source,
- * and `signInUrl`/`signUpUrl`, which ClerkJS uses as *navigation targets* when
- * the operator signs in. With those three gated, no operator-config value
- * reaches the browser in a URL position — attribute or navigation — without
- * validation, and there is no exception left to remember.
- *
- * Stricter than `isSafeHttpUrl` on purpose: no `http:` carve-out, no loopback
- * carve-out, and no relative form. Nobody types `frontendApiUrl` — the shipped
- * Clerk adapter derives it from the publishable key, and Clerk's Frontend API is
- * always https — and a cleartext script source on an operator page would be a
- * downgrade even where a browser's mixed-content rules had not already blocked
- * it. `signInUrl`/`signUpUrl` *are* typed by the operator, but what belongs
- * there is a hosted Account Portal address (`https://accounts.<domain>` or
- * `https://<slug>.accounts.dev`), which is https as well; `http:` would carry a
- * sign-in over cleartext, and a path relative to this origin is meaningless
- * because this server hosts no sign-in page of its own. So the looser gate would
- * buy nothing real, and the same strictness holds for all three.
- */
+/** Absolute HTTPS gate for the `UiAuthConfig` URL fields documented in types.ts. */
 export declare function isSafeHttpsUrl(url: unknown): boolean;
 /**
  * Names of the `uiAuth` URLs an inbound-auth provider supplied that failed their

package/dist/ui.js

@@ -95,17 +95,19 @@ export function droppedBrandingUrls(branding) {
  * their `authorizationUrl`, so a hostile/misconfigured one could hand back a
  * `javascript:` (or other) scheme; gate it before it can become an href.
  */
-export function isSafeHttpUrl(url) {
+function safeUrl(url, schemes) {
     if (typeof url !== "string")
         return false;
     try {
-        const scheme = new URL(url).protocol;
-        return scheme === "http:" || scheme === "https:";
+        return schemes.includes(new URL(url).protocol);
     }
     catch {
         return false;
     }
 }
+export function isSafeHttpUrl(url) {
+    return safeUrl(url, ["http:", "https:"]);
+}
 /**
  * Only the second check's base; any origin works because the check is whether
  * the href stays on whatever origin it is resolved against. It is deliberately
@@ -149,35 +151,9 @@ export function isSafeIconHref(href) {
         return false;
     }
 }
-/**
- * True only for an absolute `https:` URL — the gate every `uiAuth` URL passes:
- * `frontendApiUrl`, which becomes the operator shell's sign-in loader source,
- * and `signInUrl`/`signUpUrl`, which ClerkJS uses as *navigation targets* when
- * the operator signs in. With those three gated, no operator-config value
- * reaches the browser in a URL position — attribute or navigation — without
- * validation, and there is no exception left to remember.
- *
- * Stricter than `isSafeHttpUrl` on purpose: no `http:` carve-out, no loopback
- * carve-out, and no relative form. Nobody types `frontendApiUrl` — the shipped
- * Clerk adapter derives it from the publishable key, and Clerk's Frontend API is
- * always https — and a cleartext script source on an operator page would be a
- * downgrade even where a browser's mixed-content rules had not already blocked
- * it. `signInUrl`/`signUpUrl` *are* typed by the operator, but what belongs
- * there is a hosted Account Portal address (`https://accounts.<domain>` or
- * `https://<slug>.accounts.dev`), which is https as well; `http:` would carry a
- * sign-in over cleartext, and a path relative to this origin is meaningless
- * because this server hosts no sign-in page of its own. So the looser gate would
- * buy nothing real, and the same strictness holds for all three.
- */
+/** Absolute HTTPS gate for the `UiAuthConfig` URL fields documented in types.ts. */
 export function isSafeHttpsUrl(url) {
-    if (typeof url !== "string")
-        return false;
-    try {
-        return new URL(url).protocol === "https:";
-    }
-    catch {
-        return false;
-    }
+    return safeUrl(url, ["https:"]);
 }
 /**
  * Names of the `uiAuth` URLs an inbound-auth provider supplied that failed their
@@ -303,18 +279,21 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
                         : {}),
                 };
             });
+            const credentialCard = {
+                label: c.credential.label,
+                ...(c.credential.description
+                    ? { description: c.credential.description }
+                    : {}),
+                ...(c.credential.placeholder
+                    ? { placeholder: c.credential.placeholder }
+                    : {}),
+            };
             try {
                 const metadata = await credentialVault.metadata(c.id);
                 const fields = credentialFields(metadata);
                 const shape = storedCredentialShape(c.credential, metadata?.fields ?? null);
                 credential = {
-                    label: c.credential.label,
-                    ...(c.credential.description
-                        ? { description: c.credential.description }
-                        : {}),
-                    ...(c.credential.placeholder
-                        ? { placeholder: c.credential.placeholder }
-                        : {}),
+                    ...credentialCard,
                     ...(fields?.length ? { fields } : {}),
                     configured: shape.state === "valid",
                     removable: Boolean(metadata),
@@ -341,13 +320,7 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
             catch {
                 const fields = credentialFields();
                 credential = {
-                    label: c.credential.label,
-                    ...(c.credential.description
-                        ? { description: c.credential.description }
-                        : {}),
-                    ...(c.credential.placeholder
-                        ? { placeholder: c.credential.placeholder }
-                        : {}),
+                    ...credentialCard,
                     ...(fields?.length ? { fields } : {}),
                     configured: false,
                     removable: true,

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.18.3";
+export declare const CONNECTA_VERSION = "0.20.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.18.3";
+export const CONNECTA_VERSION = "0.20.0";

package/documentation/call-admission.md

@@ -140,4 +140,4 @@ typed error code.
 | --- | --- |
 | 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) |
+| 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](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md) |

package/documentation/cloudflare.md

@@ -410,4 +410,4 @@ the window notices.
 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).
+[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).

package/documentation/code-mode.md

@@ -5,14 +5,14 @@ is promised: what it can reach, what it gets back, how failures look, what it
 may retry, what bounds it runs under, and what its execution leaves behind in
 the activity surface. It is the interface a model actually programs against, so
 it is specified in prose first and implemented second — the same discipline the
-[MCP spec bump](./mcp-2026-07-28.md) followed.
+[MCP spec bump](https://github.com/zackbart/connecta/blob/main/records/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 from this document alone.
 
-The [code-first exploration](./code-first-exploration.md) is the evidence behind
+The [code-first exploration](https://github.com/zackbart/connecta/blob/main/records/code-first-exploration.md) is the evidence behind
 the direction; [`ethos.md`](../ethos.md) carries the verdicts. Where its prototype
 and this document disagree, this document wins. Clause identifiers (`A1`, `E3`, …)
 are stable and cited by the tests in [Verification](#verification).
@@ -173,7 +173,7 @@ word gets `_` appended (`my-service.get.thing` → `my_service.get_thing`). The
 globals are lazy: no catalog is fetched until a program touches one. The
 bounded deployment inventory in the `execute_code` description shows each
 canonical connector id and labels the shortcut only when it differs; the
-[discovery guide](./meta-tools.md#discovery-context) defines that bound.
+[discovery guide](./meta-tools.md#discovery-context) defines that bound. The sugar is frozen: every expansion invents a collision class `A1` already solves ([#223](https://github.com/zackbart/connecta/issues/223)).
 
 **A3.** A shortcut that resolves to more than one tool fails closed with
 `ambiguous_tool_alias`, naming the colliding tool names and pointing at
@@ -426,7 +426,7 @@ on data nobody asked for.
 
 **R5.** `console.log`, `console.warn`, and `console.error` are captured in call order and returned as a single `logs` string, capped at 4,000 characters with a truncation marker. Logs survive failure — they ride along with the error result, which is what makes them worth writing. How a non-string argument renders is not contract (`X4`).
 
-**R6.** Nothing else is added to a normal program result. Passing `diagnostics: true` adds one request-local, payload-free `diagnostics` block; a program that emitted adds `emitted: N` and its blocks (`M2`). Omitted, `false`, and emit-free are byte-for-byte the ordinary response path.
+**R6.** Nothing else is added to a normal program result. Passing `diagnostics: true` adds one request-local, payload-free `diagnostics` block; a program that emitted adds `emitted: N` and its blocks (`M2`). Omitted, `false`, and emit-free are byte-for-byte the ordinary response path. Diagnostics exist so catalog, connector, and executor costs are distinguishable without persisting payloads or charging normal responses ([#247](https://github.com/zackbart/connecta/issues/247)).
 
 **R7.** Timing separates admission, provider setup, total executor wall time, catalog work, and connector work. Catalog and connector values are cumulative, so parallel work can exceed executor wall time. Each used operation kind (`search`, `describe`, `call`, `batch`) gets one aggregate with count, failures, duration, returned serialized bytes, and catalog/connector time; batch adds only its total child count.
 
@@ -437,7 +437,7 @@ on data nobody asked for.
 MCP-native output a return value cannot carry: base64 is not projectable, so a
 block that survives intake uncapped (`S5`) must not die at the `R2` exit
 guard. The argument and the refused alternatives live in the
-[design record](./rich-output-design.md) and `ethos.md`
+[design record](https://github.com/zackbart/connecta/blob/main/records/rich-output-design.md) and `ethos.md`
 ([#267](https://github.com/zackbart/connecta/issues/267),
 [#270](https://github.com/zackbart/connecta/issues/270)).
 
@@ -498,14 +498,14 @@ one MCP Apps view per successful run, assembled where composition already
 happens. Programs supply HTML content and nothing else — the only `ui://` URI in
 the system is connecta's build-time shell, so nothing a client could dereference
 is derived from anything a program said. The argument, the refused shapes, and
-the security posture live in the [design record](./mcp-ui-design.md)
+the security posture live in the [design record](https://github.com/zackbart/connecta/blob/main/records/mcp-ui-design.md)
 ([#266](https://github.com/zackbart/connecta/issues/266),
 [#277](https://github.com/zackbart/connecta/issues/277)); this section is the
 contract, and it wins where the two disagree.
 
-**U1.** `connecta.ui(html, options?)` accepts one non-empty HTML string and at
-most the bounded read manifest `V1` defines. The one-argument call stays
-display-only; every other shape throws catchably and accepts nothing.
+**U1.** `connecta.ui(html)` accepts exactly one non-empty HTML string. There is
+no options parameter, read manifest, or sugar form. Every other shape throws
+catchably and accepts nothing.
 
 **U2.** At most one payload per run. A second call throws catchably, naming the
 constraint; the first accepted payload stands. One tool result renders one view,
@@ -513,7 +513,7 @@ and last-wins would silently discard a payload the program deliberately
 supplied.
 
 **U3.** Delivered on success only, and out of model context: the tool result
-gains `_meta["connecta/ui"] = { html, reads? }` and the JSON envelope gains `ui: true`,
+gains `_meta["connecta/ui"] = { html }` and the JSON envelope gains `ui: true`,
 so the model learns a view rendered without seeing its bytes. `structuredContent`
 stays the envelope alone. The single-label `connecta/ui` prefix is deliberate —
 connecta has no domain to reverse, and fabricating one to satisfy MCP's
@@ -526,29 +526,31 @@ with `emittedDiscarded: N` when one failure discards both.
 
 **U4.** The payload spends the aggregate emit byte budget
 (`ConnectaConfig.execute.maxEmittedBytes`), measured at the call as the
-serialized bytes of `{ html, reads? }` — `M5`'s measurement. Over budget throws
+serialized bytes of `{ html }` — `M5`'s measurement. Over budget throws
 catchably, naming the budget and the room remaining, with nothing partially
 accepted. It spends no block count (`maxEmittedBlocks`: it is not a block) and no
 host-call budget (`L4`). One transport bound covers everything rich a program
 delivers.
 
 **U5.** One static shell: a connecta-authored HTML5 document at
-`ui://connecta/program-ui/v2`, mimeType `text/html;profile=mcp-app`, declared on
+`ui://connecta/program-ui/v3`, mimeType `text/html;profile=mcp-app`, declared on
 `execute_code` via `_meta.ui.resourceUri` together with an explicit
-`_meta.ui.visibility: ["model"]`. Only `call_tool` declares app visibility; all
-other tools say model-only. A `resources/read` handler answers exactly that
-URI and fails on any other; `resources/list` is served and returns an empty list.
+`_meta.ui.visibility: ["model"]`. The other six tools declare the same
+model-only visibility without a resource URI. Omission defaults to model and
+app visibility, which would let a display-only view call them. A
+`resources/read` handler answers exactly that URI and fails on any other;
+`resources/list` is served and returns an empty list.
 The version segment bumps whenever the shell's bytes change, because hosts cache
 templates by URI.
 
 **U6.** The shell renders the payload in a nested iframe
 (`srcdoc`, `sandbox="allow-scripts"`, no `allow-same-origin`) and declares no CSP
 domains, so the host applies its restrictive default and the `about:srcdoc` frame
-inherits `default-src 'none'; connect-src 'none'`. One argument stays display-only;
-a `V1` manifest installs only named `connecta.read`, with no direct network, raw
-tool calls, discovery, conversation, writes, or links. The shell participates in the Apps lifecycle —
-initialize, tool-result, size-changed, resource-teardown — and forwards no
-channel whatsoever from the inner frame to the host. That isolation makes
+inherits `default-src 'none'; connect-src 'none'`. The shell offers no direct
+network, tool calls, discovery, conversation messages, writes, or links. It
+participates in the Apps lifecycle — initialize, tool-result, size-changed,
+resource-teardown — and forwards no channel whatsoever from the inner frame to
+the host. That isolation makes
 program views fixed-height by construction: with no bridge there is no
 content-height signal, the shell reports only its own box, and content taller
 than that scrolls inside the inner frame rather than growing the view.
@@ -591,16 +593,14 @@ the same mistake as automatic host-side projection, refused in `ethos.md`
 
 **U13.** The always-loaded MCP instructions locate `connecta.ui(html)` before an
 agent chooses a route: it exists only inside `execute_code`, never in connector
-search, and carries `U12`'s mirrored-return duty. The detailed call, binding,
-budget, and repair rules live in the on-demand `usage` skill. The location
+search, and carries `U12`'s mirrored-return duty. The detailed call, budget,
+and repair rules live in the on-demand `usage` skill. The location
 distinction rides `initialize`, under a 1,000-character ceiling for the complete
 instructions string. This promotes existing contract, not capability: the
 seven-tool surface, guest API, catalog, Apps delivery, and runtime do not change
 ([#286](https://github.com/zackbart/connecta/issues/286),
 [#418](https://github.com/zackbart/connecta/issues/418)).
 
-Bounded view reads follow normative [`V1`–`V8`](./program-ui-read-calls.md) ([#287](https://github.com/zackbart/connecta/issues/287), [#289](https://github.com/zackbart/connecta/issues/289)).
-
 ## Retry semantics
 
 **Y1.** Connecta retries nothing beneath a program. `call_tool` accepts an
@@ -878,7 +878,7 @@ the upstream `Executor` shape assignable.
 | `U1`, `U2` | `test/guest-api-contract.test.ts` (invalid and repeated calls throw catchably, first payload stands), `test/execute-ui.test.ts` (every rejected shape) |
 | `U3` | `test/guest-api-contract.test.ts` (`_meta` payload and `ui: true`, identical on both executors), `test/execute-ui.test.ts` (`structuredContent`, byte-for-byte no-call path, discard structured and plain, coexistence with `emittedDiscarded`), `test/quickjs-executor.test.ts` (mid-run shutdown) |
 | `U4` | `test/execute-ui.test.ts` (one shared byte aggregate crossed in either order; block count and host-call budget untouched) |
-| `U5`, `U10`, `U11` | `test/server.test.ts` (the shell URI, mimeType, and body; every other URI fails; empty listing; `execute_code`'s `_meta.ui`; exactly one declared extension) |
+| `U5`, `U10`, `U11` | `test/server.test.ts` (the shell URI, mimeType, and body; every other URI fails; empty listing; exact model-only `_meta.ui` on all seven tools; exactly one declared extension) |
 | `U6` | `test/execute-ui.test.ts` (valid HTML5, `srcdoc` and sandbox attributes, no `allow-same-origin`, no path from the inner frame to the host) |
 | `U7`, `U8` | two arms passing one case table, `test/codemode-compat.test.ts` |
 | `U9` | `test/execute-ui.test.ts` (a `ui` byte aggregate distinct from `emitted`, absent when nothing was accepted) |