@zackbart/connecta 0.18.1 → 0.18.3

package/dist/registry.d.ts

@@ -113,6 +113,10 @@ export interface RegistryView {
     observedSuccessAt(id: string): string | undefined;
     /** Local declared-vs-stored credential mismatch, with no downstream I/O. */
     credentialDriftFor(id: string): Promise<string | undefined>;
+    /** Value-free shape learned from successful calls, never a provider declaration. */
+    observedOutputSchema(connectorId: string, definition: ToolDef): ToolDef["outputSchema"] | undefined;
+    /** Passively learn one successful unwrapped result; failures stay isolated. */
+    observeOutputShape(connectorId: string, definition: ToolDef, value: unknown): void;
     statusFor(id: string, baseUrl: string, requestScope?: object, callOptions?: ConnectorOperationOptions): Promise<ConnectorStatus>;
     invalidateStored(id: string): Promise<void>;
 }
@@ -141,6 +145,7 @@ export declare class Registry implements RegistryView {
     private readonly health;
     /** Last drift counts reported to activity, per connector, in this runtime. */
     private readonly reportedDrift;
+    private readonly observedOutputSchemas;
     private readonly ttlMs;
     private readonly staleMs;
     private readonly persistToolCatalog;
@@ -203,6 +208,8 @@ export declare class Registry implements RegistryView {
      * separate from any connector's `conn:<id>:` namespace. Backs get_result.
      */
     resultsStorage(): KVStorage;
+    observedOutputSchema(connectorId: string, definition: ToolDef): ToolDef["outputSchema"] | undefined;
+    observeOutputShape(connectorId: string, definition: ToolDef, value: unknown): void;
     /** Resolve "<connectorId>.<toolName>" → connector + tool name. */
     resolveAddress(address: string): {
         connector: Connector;

package/dist/registry.js

@@ -7,6 +7,7 @@ import { boundedCatalogDrift } from "./catalog-drift.js";
 import { fingerprintSerializedCatalog, snapshotCatalog, } from "./catalog-fingerprint.js";
 import { MAX_CATALOG_CHUNK_BYTES, MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES, } from "./catalog-limits.js";
 import { mapSettledWithConcurrency } from "./concurrency.js";
+import { ObservedOutputSchemas } from "./result-shapes.js";
 import { GUIDE_SUMMARY_LENGTH, normalizeGuideSummary, } from "./skills.js";
 import { withAbortableTimeout } from "./timeout.js";
 const ID_RE = /^[a-z0-9_-]+$/;
@@ -133,6 +134,7 @@ export class Registry {
     health = new HealthLog();
     /** Last drift counts reported to activity, per connector, in this runtime. */
     reportedDrift = new Map();
+    observedOutputSchemas;
     ttlMs;
     staleMs;
     persistToolCatalog;
@@ -140,6 +142,7 @@ export class Registry {
     maxResultBytes;
     constructor(connectors, opts) {
         this.opts = opts;
+        this.observedOutputSchemas = new ObservedOutputSchemas();
         this.ttlMs =
             (opts.toolCacheTtlSeconds ?? DEFAULT_TTL_SECONDS) * 1000;
         this.staleMs =
@@ -342,6 +345,12 @@ export class Registry {
     resultsStorage() {
         return namespaced(this.opts.storage, "results:");
     }
+    observedOutputSchema(connectorId, definition) {
+        return this.observedOutputSchemas.get(connectorId, definition);
+    }
+    observeOutputShape(connectorId, definition, value) {
+        this.observedOutputSchemas.observe(connectorId, definition, value);
+    }
     /** Resolve "<connectorId>.<toolName>" → connector + tool name. */
     resolveAddress(address) {
         const parts = splitAddress(address);

package/dist/result-shapes.d.ts

@@ -0,0 +1,13 @@
+import type { JsonSchema, ToolDef } from "./types.js";
+/**
+ * Passive, process-local output-shape learning. Provider declarations always
+ * win; observations are an open, optional-field routing aid and never a
+ * replacement contract.
+ */
+export declare class ObservedOutputSchemas {
+    private readonly entries;
+    private cacheKey;
+    private set;
+    get(connectorId: string, definition: ToolDef): JsonSchema | undefined;
+    observe(connectorId: string, definition: ToolDef, value: unknown): void;
+}

package/dist/result-shapes.js

@@ -0,0 +1,331 @@
+import { isExplicitlyReadOnly } from "./tool-safety.js";
+const OBSERVATION_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_CACHED_SHAPES = 256;
+const MAX_DEFINITION_BYTES = 64 * 1024;
+const MAX_SCHEMA_BYTES = 16 * 1024;
+const MAX_SCHEMA_DEPTH = 6;
+const MAX_SCHEMA_NODES = 128;
+const MAX_OBJECT_PROPERTIES = 48;
+const MAX_ARRAY_ITEMS = 32;
+const MAX_PROPERTY_NAME_BYTES = 128;
+const UNSAFE_PROPERTY_NAMES = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+const encoder = new TextEncoder();
+function broadType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return typeof value;
+        case "number":
+            return Number.isFinite(value) ? "number" : undefined;
+        case "object":
+            return "object";
+        default:
+            return undefined;
+    }
+}
+function serializedSchema(schema) {
+    try {
+        const text = JSON.stringify(schema);
+        return encoder.encode(text).byteLength <= MAX_SCHEMA_BYTES
+            ? text
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function cloneSchema(schema) {
+    const serialized = serializedSchema(schema);
+    if (!serialized)
+        return undefined;
+    try {
+        return JSON.parse(serialized);
+    }
+    catch {
+        return undefined;
+    }
+}
+function definitionIdentity(definition) {
+    try {
+        const serialized = JSON.stringify(definition);
+        return encoder.encode(serialized).byteLength <= MAX_DEFINITION_BYTES
+            ? serialized
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function schemaType(schema) {
+    return typeof schema.type === "string" ? schema.type : undefined;
+}
+function safePropertyName(name) {
+    return (!UNSAFE_PROPERTY_NAMES.has(name) &&
+        encoder.encode(name).byteLength <= MAX_PROPERTY_NAME_BYTES);
+}
+function boundedPropertyNames(value) {
+    const names = [];
+    for (const name in value) {
+        if (!Object.hasOwn(value, name) || !safePropertyName(name))
+            continue;
+        names.push(name);
+        if (names.length >= MAX_OBJECT_PROPERTIES)
+            break;
+    }
+    return names.sort();
+}
+function unionBranches(schema) {
+    return Array.isArray(schema.anyOf)
+        ? schema.anyOf
+        : [schema];
+}
+function branchOrder(schema) {
+    return ["null", "boolean", "number", "string", "array", "object"].indexOf(schemaType(schema) ?? "");
+}
+function mergeSchemas(left, right) {
+    const leftType = schemaType(left);
+    const rightType = schemaType(right);
+    if (leftType === "object" && rightType === "object") {
+        const leftProperties = left.properties && typeof left.properties === "object"
+            ? left.properties
+            : {};
+        const rightProperties = right.properties && typeof right.properties === "object"
+            ? right.properties
+            : {};
+        const properties = Object.create(null);
+        for (const key of [...new Set([
+                ...Object.keys(leftProperties),
+                ...Object.keys(rightProperties),
+            ])].sort()) {
+            const leftProperty = leftProperties[key];
+            const rightProperty = rightProperties[key];
+            properties[key] =
+                leftProperty && rightProperty
+                    ? mergeSchemas(leftProperty, rightProperty)
+                    : (leftProperty ?? rightProperty);
+        }
+        return { type: "object", properties };
+    }
+    if (leftType === "array" && rightType === "array") {
+        const leftItems = left.items && typeof left.items === "object"
+            ? left.items
+            : undefined;
+        const rightItems = right.items && typeof right.items === "object"
+            ? right.items
+            : undefined;
+        return {
+            type: "array",
+            ...(leftItems || rightItems
+                ? {
+                    items: leftItems && rightItems
+                        ? mergeSchemas(leftItems, rightItems)
+                        : (leftItems ?? rightItems),
+                }
+                : {}),
+        };
+    }
+    if (leftType && leftType === rightType)
+        return left;
+    const byType = new Map();
+    for (const branch of [...unionBranches(left), ...unionBranches(right)]) {
+        const type = schemaType(branch);
+        if (!type)
+            continue;
+        const existing = byType.get(type);
+        byType.set(type, existing ? mergeSchemas(existing, branch) : branch);
+    }
+    const branches = [...byType.values()].sort((a, b) => branchOrder(a) - branchOrder(b));
+    return branches.length === 1 ? branches[0] : { anyOf: branches };
+}
+function inferSchema(value, budget, depth = 0) {
+    const type = broadType(value);
+    if (!type || depth > MAX_SCHEMA_DEPTH || budget.nodes >= MAX_SCHEMA_NODES) {
+        return undefined;
+    }
+    budget.nodes++;
+    if (type !== "object" && type !== "array")
+        return { type };
+    const object = value;
+    if (budget.seen.has(object))
+        return undefined;
+    budget.seen.add(object);
+    try {
+        if (type === "array") {
+            let items;
+            for (const item of value.slice(0, MAX_ARRAY_ITEMS)) {
+                const inferred = inferSchema(item, budget, depth + 1);
+                if (inferred)
+                    items = items ? mergeSchemas(items, inferred) : inferred;
+                if (budget.nodes >= MAX_SCHEMA_NODES)
+                    break;
+            }
+            return { type: "array", ...(items ? { items } : {}) };
+        }
+        const properties = Object.create(null);
+        const record = value;
+        for (const key of boundedPropertyNames(record)) {
+            const inferred = inferSchema(record[key], budget, depth + 1);
+            if (inferred)
+                properties[key] = inferred;
+            if (budget.nodes >= MAX_SCHEMA_NODES)
+                break;
+        }
+        return { type: "object", properties };
+    }
+    finally {
+        budget.seen.delete(object);
+    }
+}
+function boundSchema(schema, budget, depth = 0) {
+    if (depth > MAX_SCHEMA_DEPTH || budget.nodes >= MAX_SCHEMA_NODES) {
+        return undefined;
+    }
+    budget.nodes++;
+    if (Array.isArray(schema.anyOf)) {
+        const branches = schema.anyOf
+            .slice(0, 6)
+            .map((branch) => boundSchema(branch, budget, depth + 1))
+            .filter((branch) => Boolean(branch));
+        return branches.length >= 2 ? { anyOf: branches } : branches[0];
+    }
+    const type = schemaType(schema);
+    if (!type)
+        return undefined;
+    if (type === "array") {
+        const items = schema.items && typeof schema.items === "object"
+            ? boundSchema(schema.items, budget, depth + 1)
+            : undefined;
+        return { type: "array", ...(items ? { items } : {}) };
+    }
+    if (type === "object") {
+        const source = schema.properties && typeof schema.properties === "object"
+            ? schema.properties
+            : {};
+        const properties = Object.create(null);
+        let included = 0;
+        for (const key of Object.keys(source).sort()) {
+            if (included >= MAX_OBJECT_PROPERTIES ||
+                !safePropertyName(key)) {
+                continue;
+            }
+            const property = boundSchema(source[key], budget, depth + 1);
+            if (property) {
+                properties[key] = property;
+                included++;
+            }
+            if (budget.nodes >= MAX_SCHEMA_NODES)
+                break;
+        }
+        return { type: "object", properties };
+    }
+    return { type };
+}
+function observedSchema(value) {
+    try {
+        const inferred = inferSchema(value, { nodes: 0, seen: new WeakSet() });
+        const schema = inferred
+            ? boundSchema(inferred, { nodes: 0 })
+            : undefined;
+        return schema && serializedSchema(schema) ? schema : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Passive, process-local output-shape learning. Provider declarations always
+ * win; observations are an open, optional-field routing aid and never a
+ * replacement contract.
+ */
+export class ObservedOutputSchemas {
+    entries = new Map();
+    cacheKey(connectorId, definition) {
+        return JSON.stringify([connectorId, definition.name]);
+    }
+    set(key, entry) {
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        while (this.entries.size > MAX_CACHED_SHAPES) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+    }
+    get(connectorId, definition) {
+        try {
+            const key = this.cacheKey(connectorId, definition);
+            if (definition.outputSchema) {
+                this.entries.delete(key);
+                return undefined;
+            }
+            if (!isExplicitlyReadOnly(definition)) {
+                this.entries.delete(key);
+                return undefined;
+            }
+            const identity = definitionIdentity(definition);
+            if (!identity) {
+                this.entries.delete(key);
+                return undefined;
+            }
+            const entry = this.entries.get(key);
+            if (!entry)
+                return undefined;
+            if (entry.definition !== identity || entry.expiresAt <= Date.now()) {
+                this.entries.delete(key);
+                return undefined;
+            }
+            this.entries.delete(key);
+            this.entries.set(key, entry);
+            return cloneSchema(entry.schema);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    observe(connectorId, definition, value) {
+        try {
+            const key = this.cacheKey(connectorId, definition);
+            if (definition.outputSchema) {
+                this.entries.delete(key);
+                return;
+            }
+            if (!isExplicitlyReadOnly(definition)) {
+                this.entries.delete(key);
+                return;
+            }
+            const identity = definitionIdentity(definition);
+            const inferred = observedSchema(value);
+            if (!identity) {
+                this.entries.delete(key);
+                return;
+            }
+            if (!inferred)
+                return;
+            const current = this.entries.get(key);
+            const merged = boundSchema(current &&
+                current.definition === identity &&
+                current.expiresAt > Date.now()
+                ? mergeSchemas(current.schema, inferred)
+                : inferred, { nodes: 0 });
+            if (!merged || !serializedSchema(merged))
+                return;
+            this.set(key, {
+                definition: identity,
+                expiresAt: Date.now() + OBSERVATION_TTL_MS,
+                schema: merged,
+            });
+        }
+        catch {
+            // Observation is an optimization. A provider success stays successful.
+        }
+    }
+}

package/dist/skills.js

@@ -23,13 +23,13 @@ The minimum guest API is:
 
 Search inside the run and finish the task there. A discovery-only program wastes a round trip. Use 2–4 distinctive action/object terms, not the full request. Use separate short searches for distinct operations.
 
-For top-level \`search_tools\`, omit \`limit\` initially (the default is 10), then page with a limit up to 50 if needed. Empty or whitespace-only queries browse all tools. A non-empty query with no ASCII terms returns no matches; mixed input searches with its ASCII terms. \`includeSchemas: "compact"\` adds bounded input and declared output shapes. Plain objects expose \`inputKeys\`, \`requiredInputKeys\`, and \`outputKeys\`; truncation flags mark incomplete shapes; matches also carry declared annotations.
+For top-level \`search_tools\`, omit \`limit\` initially (the default is 10), then page with a limit up to 50 if needed. Empty or whitespace-only queries browse all tools. A non-empty query with no ASCII terms returns no matches; mixed input searches with its ASCII terms. \`includeSchemas: "compact"\` adds bounded input and available output shapes. An observed shape carries \`outputSchemaSource: "observed"\`; treat it as routing evidence rather than a provider contract. Plain objects expose \`inputKeys\`, \`requiredInputKeys\`, and \`outputKeys\`; truncation flags mark incomplete shapes; matches also carry declared annotations.
 
 - \`connecta.search({})\` loads all catalogs. Pass \`connector: "<id>"\` when the integration is obvious. Use \`safety: "readOnly"\` for program calls. These inputs filter discovery; they grant no authority.
-- Request \`includeSchemas: "compact"\`. Check address, purpose, annotations, required inputs, truncation, safety, and declared outputs. Never select only because a result ranks first or has fewer required inputs.
+- Request \`includeSchemas: "compact"\`. Check address, purpose, annotations, required inputs, truncation, safety, and available outputs. Never select only because a result ranks first or has fewer required inputs.
 - Supply every \`requiredInputKey\` from the task or a prior result. For dependencies, match the earlier \`outputKey\` to the later required key. An empty required-key list does not permit invented arguments. Missing \`outputKeys\` means inspect \`outputSchema\`.
 - Use \`connecta.describe({ address })\` or \`{ addresses }\` when a compact schema is truncated or insufficient. Use \`format: "json"\` only for exact constraints. Write the property names the schema displays; never guess positions or aliases.
-- Reduce through declared output keys. Do not guess collection roots such as \`items\` or \`results\`. If a match or result key is missing, inspect, re-search, or describe inside the same run instead of returning discovery for another call.
+- Reduce through available output keys. Treat an observed key as a hint, since later results may omit it or add others. Do not guess collection roots such as \`items\` or \`results\`. If a match or result key is missing, inspect, re-search, or describe inside the same run instead of returning discovery for another call.
 
 Only tools explicitly annotated \`readOnlyHint: true\` are reachable. The catalog, credential, admission, and read-only gates run below the sandbox; code cannot widen its authority.
 

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.1";
+export declare const CONNECTA_VERSION = "0.18.3";

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.1";
+export const CONNECTA_VERSION = "0.18.3";

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/code-mode.md

@@ -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`
@@ -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
@@ -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

@@ -268,6 +268,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
@@ -294,3 +304,28 @@ server issuer discovered and validated by the SDK; see
 [storage and credentials](./storage-and-credentials.md#downstream-oauth).
 The callback route validates `state` before passing the complete callback query
 to the SDK so RFC 9207 `iss` validation is not lost.
+
+A remote MCP connector that authenticates with a static key has two ways to
+receive one. `{ type: "headers", headers }` bakes the literal value into the
+deployment file, which suits a secret the runtime already holds.
+`{ type: "credential" }` declares the slot instead and lets an operator paste
+the key at `/credentials`, where it is encrypted at rest and rotatable without
+a redeploy:
+
+```ts
+remoteMcp("revenuecat_bepresent", {
+  url: "https://mcp.revenuecat.ai/mcp",
+  auth: {
+    type: "credential",
+    credential: { label: "API v2 secret key" },
+  },
+});
+```
+
+Header name and framing are configurable — `header` defaults to
+`Authorization`, `scheme` to `Bearer`, `scheme: null` sends the value bare, and
+a `Basic` framing base64-encodes a `user:secret` pair. Every maintained hosted
+connection takes the shape through its existing `auth` option and fills in its
+own label and framing. The full behavior, including rotation and the empty-slot
+state, is in
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).

package/documentation/linear.md

@@ -65,9 +65,12 @@ connection; it now answers 404.
 ## Authentication
 
 OAuth 2.1 with dynamic client registration is the default and keeps each
-connector instance's flow and tokens in its connector-scoped storage. Linear
-also accepts a bearer token or a personal API key passed directly in the
-`Authorization` header, which suits a headless deployment:
+connector instance's flow and tokens in its connector-scoped storage. Linear's
+MCP server also "supports passing OAuth token and API keys directly in the
+`Authorization: Bearer <yourtoken>` header instead of using the interactive
+authentication flow" ([Linear MCP docs](https://linear.app/docs/mcp)), which
+suits a headless deployment. Note the framing: the bare-`Authorization`
+convention is Linear's *GraphQL* API, and this endpoint is not that.
 
 ```ts
 linear("automation_tracker", {
@@ -75,7 +78,7 @@ linear("automation_tracker", {
   access: "read-only",
   auth: {
     type: "headers",
-    headers: { Authorization: env.LINEAR_API_KEY },
+    headers: { Authorization: `Bearer ${env.LINEAR_API_KEY}` },
   },
 });
 ```
@@ -85,6 +88,24 @@ configuration. A personal API key carries the acting user's full workspace
 permissions, so pair it with `access: "read-only"` unless the deployment
 genuinely writes.
 
+The same key can arrive from `/credentials` instead, which is what a deployment
+with no secret store — or an operator who rotates keys without a redeploy —
+wants:
+
+```ts
+linear("automation_tracker", {
+  purpose: "Headless release reporting",
+  access: "read-only",
+  auth: { type: "credential" },
+});
+```
+
+The slot renders as "Personal API key" and Connecta sends the stored value as
+`Authorization: Bearer <key>`, the framing Linear's MCP page documents; pass
+`credential` or `scheme` to override either. Until the operator saves a value
+the connector is present and reports `auth_required`. See
+[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
+
 ## Safety classification
 
 The wrapper classifies Linear's documented `list_*`, `get_*`, and