@zackbart/connecta 0.18.2 → 0.19.0

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.2";
+export declare const CONNECTA_VERSION = "0.19.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.2";
+export const CONNECTA_VERSION = "0.19.0";

package/documentation/architecture.md

@@ -14,8 +14,9 @@ stating before anything else.
 
 **Per isolate, built once.** `createConnecta(config)` returns
 `{ fetch, registry, close }`. The `Registry` owns the connector set, address
-resolution, catalog caches, connector health, and the per-connector call
-limiters. It is constructed once and lives as long as the isolate or process —
+resolution, catalog caches, observed output schemas, connector health, and the
+per-connector call limiters. It is constructed once and lives as long as the
+isolate or process —
 on Workers that means a lazy module-scope singleton, which is why both
 deployment shapes build it outside the request handler.
 
@@ -94,6 +95,7 @@ owns or hands out, and a change usually belongs in exactly one of them:
 | `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. |
+| `src/result-shapes.ts` | Bounded runtime-only inference and merging for output shapes learned from successful read-only calls whose providers declared none. |
 
 `src/meta-tools.ts` and `src/execute.ts` are two front doors onto the same
 three services. That is the point: a program's `connecta.call` and a top-level
@@ -142,6 +144,7 @@ src/
   registry.ts         connector set, addresses, health, call limiters
   catalog-service.ts  request-local catalog access, search, and describe
   catalog.ts          ranking, summaries, compact schema rendering
+  result-shapes.ts    passive runtime-only observed output schemas
   invocation.ts       one tool call, end to end
   catalog-drift.ts    vetted manifests and the counts a refresh produces
   credentials.ts      the AES-GCM connector vault over KVStorage

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).
@@ -149,10 +149,7 @@ a cycle, a `BigInt`, a function, a class instance — never round-trips: it eith
 ends the run with an error or is converted lossily, executor's choice (`X9`).
 Return JSON-shaped data and the question does not arise.
 
-**P4.** Nothing survives an execution. There is no module scope, cache, or
-scratch storage carried to the next program, and no request-bound object outlives
-the request that created it. Within one execution, host calls share one
-downstream request scope.
+**P4.** Nothing survives an execution. There is no module scope, cache, or scratch storage carried to the next program, and no request-bound object outlives the request that created it. Within one execution, host calls share one downstream request scope. `S9`'s host-owned output observation is catalog metadata, not guest memory: a later program receives no prior value or object, only a labeled field/type schema through discovery.
 
 **P5.** Plain JavaScript only. TypeScript syntax is a syntax error. Portable code
 does not import: QuickJS blocks imports, while Dynamic Workers expose the `X5`
@@ -176,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
@@ -223,7 +220,7 @@ const page = await connecta.search({
 });
 ```
 
-**S1.** Returns one flat page: `{ tools, total, offset, limit, hasMore }`, plus `nextOffset` when more remains and `matchMode: "partial"` when no tool matched every term. Top-level `search_tools` is different: it returns `{ connectors: [{ id, tools }], total, offset, limit, hasMore }`. Complete matches normally precede partial matches, but a partial candidate whose complete normalized tool name occurs in the normalized raw query competes by score; conversational cleanup applies only to scoring terms. Other candidates covering at least two terms fill the page after every complete match; when no complete match exists, the existing any-term fallback remains. Each entry in `tools` carries `address`, `name`, and — when requested — `description`, `inputSchema`, `outputSchema`, `annotations`, and the connector's `guide`. Tool rows expose neither lexical scores nor per-result coverage. An empty or whitespace-only query browses. Non-empty input with no ASCII lexical terms returns no tools and bounded no-match analysis; mixed input searches with its ASCII terms. Compact shapes omit property prose, put required fields first, and cap each shape at 1,024 UTF-8 bytes. Each enum node gets 256 of those bytes. About three near-cap enum nodes can therefore coexist while leaving the final quarter for surrounding syntax; the unchanged global fallback still applies above 1,024 bytes. A capped enum preserves whole values before `unknown` and an exact omitted-value count, while an empty enum renders as `never`. Either cap carries `inputSchemaTruncated` or `outputSchemaTruncated`; a shape-wide cap remains structurally valid with `unknown` types plus `/* truncated */`. Small enums remain complete. Use `connecta.describe` (or JSON search) for omitted exact constraints.
+**S1.** Returns one flat page: `{ tools, total, offset, limit, hasMore }`, plus `nextOffset` when more remains and `matchMode: "partial"` when no tool matched every term. Top-level `search_tools` is different: it returns `{ connectors: [{ id, tools }], total, offset, limit, hasMore }`. Complete matches normally precede partial matches, but a partial candidate whose complete normalized tool name occurs in the normalized raw query competes by score; conversational cleanup applies only to scoring terms. Other candidates covering at least two terms fill the page after every complete match; when no complete match exists, the existing any-term fallback remains. Each entry in `tools` carries `address`, `name`, and — when requested — `description`, `inputSchema`, `outputSchema`, `annotations`, and the connector's `guide`. An output shape learned under `S9` also carries `outputSchemaSource: "observed"`; provider declarations carry no source marker. Tool rows expose neither lexical scores nor per-result coverage. An empty or whitespace-only query browses. Non-empty input with no ASCII lexical terms returns no tools and bounded no-match analysis; mixed input searches with its ASCII terms. Compact shapes omit property prose, put required fields first, and cap each shape at 1,024 UTF-8 bytes. Each enum node gets 256 of those bytes. About three near-cap enum nodes can therefore coexist while leaving the final quarter for surrounding syntax; the unchanged global fallback still applies above 1,024 bytes. A capped enum preserves whole values before `unknown` and an exact omitted-value count, while an empty enum renders as `never`. Either cap carries `inputSchemaTruncated` or `outputSchemaTruncated`; a shape-wide cap remains structurally valid with `unknown` types plus `/* truncated */`. Small enums remain complete. Use `connecta.describe` (or JSON search) for omitted exact constraints.
 
 **S1a.** `connector` loads only the named catalog; omit it only when the integration is ambiguous, because an unscoped search fans out across every configured connector. `safety: "readOnly"` returns exactly the tools available through `connecta.call`, connector shortcuts, and `connecta.batch`; `"approvalRequired"` returns the complementary fail-closed class, including false, missing, and contradictory annotations. Omitted or `"all"` preserves the complete catalog. These filters grant no authority and change no admission decision.
 
@@ -265,7 +262,7 @@ carry a route-aware `nextAction`; a close miss may add three canonical `suggesti
 Catalog failures add only `retryAfterMs` when known. One bad address never fails the whole call. Each failed entry clamps its
 caller-authored `address` to 512 UTF-8 bytes with an `…` marker. Entry order
 correlates a clipped address with its request; successes keep canonical addresses. More than 100
-addresses is `invalid_args`; the same 256,000-byte ceiling applies.
+addresses is `invalid_args`; the same 256,000-byte ceiling applies. A success whose output shape came from `S9` carries `outputSchemaSource: "observed"` beside the rendered schema.
 
 ### connecta.call
 
@@ -304,6 +301,8 @@ the batch, and more than ten calls throws.
 
 **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.
 
+**S9.** A successful explicitly read-only call whose provider declared no `outputSchema` passively learns one from the unwrapped result. The observation retains field names and broad JSON types only: no arguments, scalar values, raw results, code, credentials, or errors. Property names may be user-authored. Objects stay open, every field stays optional, and search or describe labels the shape `outputSchemaSource: "observed"` so a model cannot mistake runtime evidence for a provider contract. Later observations merge fields and types in a process-local 256-entry LRU; a provider declaration always wins. Inference stops at depth 6, 128 schema nodes, 48 properties per object, 32 inspected array items, and 128 UTF-8 bytes per property name; `__proto__`, `constructor`, and `prototype` names are discarded. A tool definition over 64 KiB or an observed schema over 16 KiB is ignored. An entry expires after 24 hours and carries the exact serialized tool definition, so a changed catalog entry, process restart, or Worker isolate eviction starts cold. A failed call or failed result-processing step learns nothing, and any observation failure is discarded without changing a successful call. No discovery read, timer, refresh, background job, or storage adapter executes or persists work for this cache: the result-sampling refusal in [#282](https://github.com/zackbart/connecta/issues/282) stands.
+
 ### connecta.emit
 
 ```js
@@ -427,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.
 
@@ -438,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)).
 
@@ -499,7 +498,7 @@ 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.
@@ -600,7 +599,7 @@ 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)).
+Bounded view reads follow normative [`V1`–`V8`](https://github.com/zackbart/connecta/blob/main/records/program-ui-read-calls.md) ([#287](https://github.com/zackbart/connecta/issues/287), [#289](https://github.com/zackbart/connecta/issues/289)).
 
 ## Retry semantics
 
@@ -847,6 +846,7 @@ the upstream `Executor` shape assignable.
 | `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`, `X11` | both guest-contract executors (caught call, namespace, discovery, utility, batch-validation, budget, and forgery cases; typed batch equivalence) |
+| `S9` | `test/result-shapes.test.ts` (value exclusion, bounds, merging, LRU and time expiry, runtime isolation, read-only admission, declared precedence, definition invalidation, unwrapped MCP results, discovery provenance, copy isolation, and failure isolation) |
 | `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) |

package/documentation/connectors.md

@@ -160,6 +160,29 @@ is that machinery extracted once ([#341](https://github.com/zackbart/connecta/is
 one `guardedFetch({ provider, baseUrl, headers, maxResponseBytes, authenticate })`
 factory returning the transport a connector sends every request through.
 
+```ts
+const send = guardedFetch({
+  provider: "Billing",
+  baseUrl: "https://billing.internal.example/v1",
+  maxResponseBytes: 4 * 1024 * 1024,
+  headers: { Accept: "application/json" },
+  authenticate: async (ctx) => {
+    const token = await ctx.credential?.get();
+    if (!token) throw new ConnectorCallError("auth_required", "...");
+    return { Authorization: `Bearer ${token}` };
+  },
+});
+
+const invoice = await send(
+  { method: "GET", path: `/invoices/${id}` },
+  ctx,
+  (response) => {
+    if (!response.ok) throw billingFailure(response.status);
+    return response.json();
+  },
+);
+```
+
 What it owns is mechanical and provider-independent:
 
 - **Confinement.** A request path is provider-relative, carries no query or
@@ -212,7 +235,7 @@ supplies the third caller that would settle it.
 ## MCP version skew
 
 Connecta deliberately sits between protocol generations
-([full revision inventory](./mcp-2026-07-28.md)):
+([full revision inventory](https://github.com/zackbart/connecta/blob/main/records/mcp-2026-07-28.md)):
 
 - **Inbound:** `/mcp` serves both the 2026-07-28 revision and legacy 2025
   clients. Modern clients negotiate with `server/discover` and do not send
@@ -268,6 +291,16 @@ 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.
 
+That path also learns an observed output schema after a successful explicitly
+read-only call when the catalog declared none. The observation retains field
+names and broad JSON types rather than a result. Object fields stay optional,
+additional fields stay allowed, discovery labels the source `observed`, and any
+later provider declaration wins. Property names can be user-authored data, so
+the bounded cache stays in this process or Worker isolate and expires entries
+after 24 hours. An exact tool-definition comparison rejects stale shapes. This
+does not weaken the catalog completeness rule or the refusal of result sampling:
+no catalog read executes a tool.
+
 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

package/documentation/linear.md

@@ -179,4 +179,4 @@ settings at construction.
 This connection is audited against
 [the provider conventions](./provider-conventions.md). Its verdict per
 convention, including every recorded exception, is the Linear section of
-[the provider audit](./provider-audit.md).
+[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).

package/documentation/meta-tools.md

@@ -78,21 +78,35 @@ headed to `call_tool` or generated code; `safety: "approvalRequired"` finds the
 complementary set that must cross `call_destructive_tool`. Omitting `safety`,
 or setting it to `"all"`, preserves the complete configured catalog. This is
 only a discovery filter: it neither grants authority nor changes invocation admission.
-`includeSchemas: "compact"` adds each match's input and any declared output
-shape. Bounded plain-object schemas also expose `inputKeys`,
+`includeSchemas: "compact"` adds each match's input and any provider-declared
+output shape. When the provider declared none but an earlier successful call
+learned one, the same field carries the open observed schema beside
+`outputSchemaSource: "observed"`. That marker matters: observed fields and broad
+JSON types are routing evidence, not a provider contract, and every object field
+remains optional and open to unseen names. A provider declaration always wins.
+Bounded plain-object schemas also expose `inputKeys`,
 `requiredInputKeys`, and `outputKeys`; a zero-input object keeps
 `requiredInputKeys: []`, while an output object with no declared properties
 omits `outputKeys`. A truncated shape omits its corresponding list rather than
 repeating a large partial inventory. Matches carry declared
 behavior annotations. Lexical rank is only one signal: select a candidate whose
 required inputs are available, whose schema is complete enough for the call,
-and whose safety and declared outputs fit the work. A reducer uses `outputKeys`
+and whose safety and available outputs fit the work. A reducer uses `outputKeys`
 before inspecting the value; it does not assume a collection is named `items`
 or `results`. When that shape is sufficient, call the returned address directly. Reserve schema
 expansion through `connecta.describe` for a search without schemas, an
 ambiguous compact shape, or exact
 constraints that require `format: "json"`.
 
+Observed schemas originate no provider traffic. A successful explicitly
+read-only call the user already made contributes names and broad types after
+Connecta unwraps the result. Arguments, scalar values, raw results, code,
+credentials, and errors are not retained, though property names may themselves
+be user-authored. Shapes merge in a 256-entry runtime cache for 24 hours under
+the exact tool definition that produced them. A changed definition, process
+restart, or Worker isolate eviction starts cold. Observation cannot fail the
+call, and the declared catalog remains the fallback.
+
 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

package/documentation/mixpanel.md

@@ -145,4 +145,4 @@ either way and still needs restrained use.
 This connection is audited against
 [the provider conventions](./provider-conventions.md). Its verdict per
 convention, including every recorded exception, is the Mixpanel section of
-[the provider audit](./provider-audit.md).
+[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).

package/documentation/notion.md

@@ -268,4 +268,4 @@ from this connection, not hidden behind a generic call.
 This connection is audited against
 [the provider conventions](./provider-conventions.md). Its verdict per
 convention, including every recorded exception, is the Notion section of
-[the provider audit](./provider-audit.md).
+[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).