@zackbart/connecta 0.28.1 → 0.30.0

package/dist/catalog.js

@@ -29,8 +29,7 @@ class SchemaWork {
     }
     text(value) {
         // Check code units first so encoding a hostile scalar is itself bounded.
-        if (value.length > this.byteLimit ||
-            schemaEncoder.encode(value).length > this.byteLimit) {
+        if (value.length > this.byteLimit || schemaEncoder.encode(value).length > this.byteLimit) {
             throw schemaSizeExceeded;
         }
         return value;
@@ -206,12 +205,7 @@ function inflectionVariants(base) {
         `${base}es`,
         `${base}ed`,
         ...(base.endsWith("e") ? [`${base}d`] : []),
-        ...(base.endsWith("y")
-            ? [
-                `${base.slice(0, -1)}ies`,
-                `${base.slice(0, -1)}ied`,
-            ]
-            : []),
+        ...(base.endsWith("y") ? [`${base.slice(0, -1)}ies`, `${base.slice(0, -1)}ied`] : []),
     ];
 }
 function matchingTokenCandidates(term) {
@@ -221,12 +215,8 @@ function matchingTokenCandidates(term) {
         ...(term.endsWith("es") ? [term.slice(0, -2)] : []),
         ...(term.endsWith("ed") ? [term.slice(0, -2)] : []),
         ...(term.endsWith("d") ? [term.slice(0, -1)] : []),
-        ...(term.endsWith("ies")
-            ? [`${term.slice(0, -3)}y`]
-            : []),
-        ...(term.endsWith("ied")
-            ? [`${term.slice(0, -3)}y`]
-            : []),
+        ...(term.endsWith("ies") ? [`${term.slice(0, -3)}y`] : []),
+        ...(term.endsWith("ied") ? [`${term.slice(0, -3)}y`] : []),
     ];
     for (const base of possibleBases) {
         if (base && inflectionVariants(base).includes(term)) {
@@ -292,10 +282,7 @@ export function lexicalCorpusStatistics(toolSets, query) {
     }
     const documentFrequency = new Map(terms.map((term) => [
         term,
-        new Set([
-            ...(nameMatches.get(term) ?? []),
-            ...(descriptionMatches.get(term) ?? []),
-        ]).size,
+        new Set([...(nameMatches.get(term) ?? []), ...(descriptionMatches.get(term) ?? [])]).size,
     ]));
     return {
         documentCount: toolSets.reduce((total, tools) => total + tools.length, 0),
@@ -306,15 +293,12 @@ export function lexicalCorpusStatistics(toolSets, query) {
 }
 function inverseDocumentFrequency(term, statistics) {
     const frequency = statistics.documentFrequency.get(term) ?? 0;
-    return Math.log(1 +
-        (statistics.documentCount - frequency + 0.5) /
-            (frequency + 0.5));
+    return Math.log(1 + (statistics.documentCount - frequency + 0.5) / (frequency + 0.5));
 }
 function scoreDocument(doc, phrase, terms, mode, statistics) {
     if (!phrase)
         return { score: 0, matchedTermCount: 0 };
-    const matchedTerms = terms.filter((term) => statistics.nameMatches.get(term)?.has(doc.tool) ||
-        statistics.descriptionMatches.get(term)?.has(doc.tool));
+    const matchedTerms = terms.filter((term) => statistics.nameMatches.get(term)?.has(doc.tool) || statistics.descriptionMatches.get(term)?.has(doc.tool));
     if (mode === "all" && matchedTerms.length !== terms.length)
         return null;
     if (matchedTerms.length === 0)
@@ -349,7 +333,7 @@ function scoreDocument(doc, phrase, terms, mode, statistics) {
 function queryContainsExactName(doc, phrase) {
     if (!doc.name || !phrase)
         return false;
-    return (` ${phrase} `).includes(` ${doc.name} `);
+    return ` ${phrase} `.includes(` ${doc.name} `);
 }
 /**
  * Rank a connector's tools while caching its normalized plain-data index.
@@ -497,16 +481,13 @@ function renderConstraints(base, schema, byteLimit, onTruncated) {
     const kept = [];
     for (const entry of entries) {
         const candidate = ` /* ${[...kept, entry].join("; ")} */`;
-        if (byteLimit !== undefined &&
-            schemaEncoder.encode(candidate).length > byteLimit) {
+        if (byteLimit !== undefined && schemaEncoder.encode(candidate).length > byteLimit) {
             onTruncated?.();
             continue;
         }
         kept.push(entry);
     }
-    return kept.length === 0
-        ? base
-        : `${grouped(base)} /* ${kept.join("; ")} */`;
+    return kept.length === 0 ? base : `${grouped(base)} /* ${kept.join("; ")} */`;
 }
 /**
  * `grouped` for the TypeScript dialect, whose JSDoc prose and string literals
@@ -535,8 +516,7 @@ function groupedType(part) {
         else if (char === "}" || char === ")" || char === "]" || char === ">") {
             nesting -= 1;
         }
-        else if (nesting === 0 &&
-            (part.startsWith(" | ", i) || part.startsWith(" & ", i))) {
+        else if (nesting === 0 && (part.startsWith(" | ", i) || part.startsWith(" & ", i))) {
             return `(${part})`;
         }
     }
@@ -557,9 +537,7 @@ function typescriptPrimitive(type) {
         return "unknown[]";
     if (type === "object")
         return "Record<string, unknown>";
-    return ["string", "number", "boolean", "null"].includes(type)
-        ? type
-        : "unknown";
+    return ["string", "number", "boolean", "null"].includes(type) ? type : "unknown";
 }
 function boundedParts(work, separator, prefix, suffix) {
     // Check each addition before joining so a rejected schema never creates a
@@ -594,9 +572,7 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
     const ungrouped = options.work.ungrouped;
     // A `[]` suffix binds tighter than `|` and `&`, so an element rendered at
     // operator level needs parentheses or it reads as its last member's array.
-    const element = (rendered) => ts
-        ? groupedType(rendered)
-        : ungrouped.has(rendered) ? `(${rendered})` : rendered;
+    const element = (rendered) => ts ? groupedType(rendered) : ungrouped.has(rendered) ? `(${rendered})` : rendered;
     if (depth > 4) {
         if (!ts)
             return "…";
@@ -617,9 +593,7 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             if (key !== "nullable")
                 base[key] = s[key];
         }
-        const rendered = declaresShape(base)
-            ? renderSchema(base, defs, seen, depth, options)
-            : "unknown";
+        const rendered = declaresShape(base) ? renderSchema(base, defs, seen, depth, options) : "unknown";
         return rendered === "unknown" ? rendered : `${rendered} | null`;
     }
     const constrain = (rendered) => {
@@ -635,17 +609,14 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
     };
     // Conditions cannot be expressed by a single static shape. Preserve the
     // base and send callers to the exact schema instead of hiding the rules.
-    if (s.dependentSchemas !== undefined || s.if !== undefined ||
-        s.then !== undefined || s.else !== undefined) {
+    if (s.dependentSchemas !== undefined || s.if !== undefined || s.then !== undefined || s.else !== undefined) {
         options.work.truncated = true;
         const base = Object.create(null);
         for (const key of propertyNames(s, options.work)) {
             if (!["dependentSchemas", "if", "then", "else"].includes(key))
                 base[key] = s[key];
         }
-        const rendered = declaresShape(base)
-            ? renderSchema(base, defs, seen, depth, options)
-            : "unknown";
+        const rendered = declaresShape(base) ? renderSchema(base, defs, seen, depth, options) : "unknown";
         const result = `${rendered} /* conditional */`;
         if (ungrouped.has(rendered))
             ungrouped.add(result);
@@ -666,9 +637,7 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
                 own[key] = s[key];
         }
         const parts = boundedParts(options.work, " & ", "", "");
-        const groupParts = declaresShape(own)
-            ? s.allOf.length > 0
-            : s.allOf.length > 1;
+        const groupParts = declaresShape(own) ? s.allOf.length > 0 : s.allOf.length > 1;
         if (declaresShape(own)) {
             const rendered = renderSchema(own, defs, seen, depth, options);
             parts.add(groupParts ? group(rendered) : rendered);
@@ -771,17 +740,13 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             parts.add(renderSchema(item, defs, seen, depth + 1, options));
         }
         if (s.items !== false) {
-            const rest = s.items === undefined || s.items === true
-                ? "unknown"
-                : renderSchema(s.items, defs, seen, depth + 1, options);
+            const rest = s.items === undefined || s.items === true ? "unknown" : renderSchema(s.items, defs, seen, depth + 1, options);
             parts.add(`...${element(rest)}[]`);
         }
         return parts.finish();
     }
     if (type === "array" || s.items) {
-        const items = s.items
-            ? renderSchema(s.items, defs, seen, depth + 1, options)
-            : "unknown";
+        const items = s.items ? renderSchema(s.items, defs, seen, depth + 1, options) : "unknown";
         return `${element(items)}[]`;
     }
     if (type === "object" || s.properties) {
@@ -789,10 +754,7 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
         const required = new Set(schemaRequired(s, options.work));
         const declaredKeys = propertyNames(props, options.work);
         const keys = options.requiredFirst
-            ? [
-                ...declaredKeys.filter((key) => required.has(key)),
-                ...declaredKeys.filter((key) => !required.has(key)),
-            ]
+            ? [...declaredKeys.filter((key) => required.has(key)), ...declaredKeys.filter((key) => !required.has(key))]
             : declaredKeys;
         const additional = s.additionalProperties;
         const index = ts && additional !== null && typeof additional === "object"
@@ -813,16 +775,13 @@ function renderSchemaNode(schema, defs, seen, depth, options) {
             }
             options.work.text(key);
             if (ts) {
-                const doc = options.propertyDescriptions && typeof description === "string" &&
-                    description.trim()
+                const doc = options.propertyDescriptions && typeof description === "string" && description.trim()
                     ? `/** ${typescriptDoc(description)} */ `
                     : "";
                 parts.add(`${doc}${typescriptKey(key)}${optional}: ${rendered}`);
                 continue;
             }
-            const comment = options.propertyDescriptions && typeof description === "string"
-                ? ` // ${description}`
-                : "";
+            const comment = options.propertyDescriptions && typeof description === "string" ? ` // ${description}` : "";
             parts.add(`${key}${optional}: ${rendered}${comment}`);
         }
         if (index !== undefined)
@@ -855,7 +814,9 @@ function resolveDefinition(schema, name) {
     const defs = schema.$defs;
     return definitions && Object.hasOwn(definitions, name)
         ? definitions[name]
-        : defs && Object.hasOwn(defs, name) ? defs[name] : undefined;
+        : defs && Object.hasOwn(defs, name)
+            ? defs[name]
+            : undefined;
 }
 /** Render and cache a compact TypeScript-like representation of JSON Schema. */
 export function compactSchema(schema) {
@@ -884,7 +845,9 @@ function truncatedDiscoverySchema(schema, work) {
     try {
         keys = objectKeys(schema, schema, new Set(), 0, work);
     }
-    catch { /* An exhausted walk has no reliable key inventory. */ }
+    catch {
+        /* An exhausted walk has no reliable key inventory. */
+    }
     if (!keys)
         return `unknown${COMPACT_DISCOVERY_TRUNCATION}`;
     const required = new Set(keys.required);
@@ -896,8 +859,7 @@ function truncatedDiscoverySchema(schema, work) {
     for (const key of ordered) {
         const part = `${JSON.stringify(key)}${required.has(key) ? "" : "?"}: unknown`;
         const candidate = `{ ${[...parts, part].join(", ")} }${COMPACT_DISCOVERY_TRUNCATION}`;
-        if (schemaEncoder.encode(candidate).length >
-            MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
+        if (schemaEncoder.encode(candidate).length > MAX_COMPACT_DISCOVERY_SCHEMA_BYTES) {
             break;
         }
         parts.push(part);
@@ -954,16 +916,11 @@ const OBSERVED_OUTPUT_MARKER = "/* observed, not declared */ ";
  */
 export function typescriptSignature(input, output, options) {
     const renderedInput = typescriptType(input, options.description);
-    const renderedOutput = output
-        ? typescriptType(output, options.description)
-        : undefined;
-    const args = renderedInput.text === "{}" ||
-        renderedInput.text === "Record<string, unknown>"
+    const renderedOutput = output ? typescriptType(output, options.description) : undefined;
+    const args = renderedInput.text === "{}" || renderedInput.text === "Record<string, unknown>"
         ? "args?: {}"
         : `args: ${renderedInput.text}`;
-    const result = renderedOutput
-        ? `${options.observed ? OBSERVED_OUTPUT_MARKER : ""}${renderedOutput.text}`
-        : "unknown";
+    const result = renderedOutput ? `${options.observed ? OBSERVED_OUTPUT_MARKER : ""}${renderedOutput.text}` : "unknown";
     return {
         text: `(${args}) => Promise<${result}>`,
         inputTruncated: renderedInput.truncated,
@@ -978,10 +935,14 @@ function boundedCompactSchema(schema, description, typescript = false) {
         propertyDescriptions: description,
         requiredFirst: !description,
         enumByteLimit: description ? work.byteLimit : MAX_COMPACT_DISCOVERY_ENUM_BYTES,
-        onEnumTruncated: () => { work.truncated = true; },
+        onEnumTruncated: () => {
+            work.truncated = true;
+        },
         renderConstraints: true,
         constraintByteLimit: description ? work.byteLimit : MAX_COMPACT_DISCOVERY_CONSTRAINT_BYTES,
-        onConstraintTruncated: () => { work.truncated = true; },
+        onConstraintTruncated: () => {
+            work.truncated = true;
+        },
     };
     try {
         const text = renderSchema(schema, schema, new Set(), 0, options);
@@ -1002,7 +963,9 @@ function boundedCompactSchema(schema, description, typescript = false) {
                     truncated: true,
                 };
             }
-            catch { /* Fall through to a bounded key-only shape. */ }
+            catch {
+                /* Fall through to a bounded key-only shape. */
+            }
         }
         return { text: truncatedDiscoverySchema(schema, work), truncated: true };
     }
@@ -1054,9 +1017,7 @@ function objectKeys(schema, defs, seen, depth, work) {
             if (key !== "allOf")
                 own[key] = s[key];
         }
-        const parts = declaresShape(own)
-            ? [objectKeys(own, defs, seen, depth, work)]
-            : [];
+        const parts = declaresShape(own) ? [objectKeys(own, defs, seen, depth, work)] : [];
         for (const member of s.allOf) {
             const keys = objectKeys(member, defs, seen, depth + 1, work);
             if (!keys)
@@ -1065,9 +1026,7 @@ function objectKeys(schema, defs, seen, depth, work) {
         }
         // An allOf whose members are not all object shapes renders as an
         // intersection with a non-object half; no single key list describes it.
-        return parts.every((part) => part !== undefined)
-            ? mergedKeys(parts)
-            : undefined;
+        return parts.every((part) => part !== undefined) ? mergedKeys(parts) : undefined;
     }
     const reference = s.$ref ?? s.$dynamicRef;
     if (typeof reference === "string") {

package/dist/concurrency.js

@@ -1,10 +1,9 @@
+import { CONFIG_DEFAULTS } from "./config-defaults.js";
 import { Effect } from "effect";
 import { runEdge } from "./runtime/run.js";
-const DEFAULT_DISCOVERY_CONCURRENCY = 4;
+const DEFAULT_DISCOVERY_CONCURRENCY = CONFIG_DEFAULTS.discovery.concurrency;
 export function resolveDiscoveryConcurrency(value) {
-    return value !== undefined && Number.isInteger(value) && value > 0
-        ? value
-        : DEFAULT_DISCOVERY_CONCURRENCY;
+    return value !== undefined && Number.isInteger(value) && value > 0 ? value : DEFAULT_DISCOVERY_CONCURRENCY;
 }
 /**
  * Run `fn` over `items` with at most `limit` operations in flight, settling

package/dist/config-defaults.d.ts

@@ -0,0 +1,39 @@
+export declare const CONFIG_DEFAULTS: {
+    readonly discovery: {
+        readonly concurrency: 4;
+        readonly catalogTtlSeconds: 300;
+        readonly catalogMinTtlSeconds: 0;
+        readonly catalogMaxTtlSeconds: 86400;
+        readonly probeTimeoutMs: 30000;
+    };
+    readonly calls: {
+        readonly maxResultBytes: 24000;
+    };
+    readonly results: {
+        readonly maxStashBytes: number;
+        readonly maxStashEntries: 64;
+    };
+    readonly execute: {
+        readonly maxEmittedBytes: 4000000;
+        readonly maxEmittedBlocks: 32;
+        readonly maxHostCalls: 20;
+        readonly hostCallTimeoutMs: 15000;
+        readonly watchdogMs: 120000;
+        readonly maxWrites: 10;
+    };
+    readonly admission: {
+        readonly requests: {
+            readonly concurrency: 16;
+            readonly maxQueueSize: 32;
+            readonly queueTimeoutMs: 5000;
+            readonly retryAfterMs: 1000;
+            readonly maxDurationMs: 300000;
+        };
+        readonly code: {
+            readonly concurrency: 2;
+            readonly maxQueueSize: 8;
+            readonly queueTimeoutMs: 5000;
+            readonly retryAfterMs: 1000;
+        };
+    };
+};

package/dist/config-defaults.js

@@ -0,0 +1,46 @@
+// Every configuration default, defined once.
+//
+// The schema in src/config.ts applies these when a deployment omits a value,
+// and `describeConfig()` reports them as `source: "default"`. The modules that
+// enforce each bound read the same numbers for the fallbacks their own
+// constructors keep, so a test that builds a Registry or an execute tool
+// directly sees the deployment's defaults rather than a second copy of them.
+export const CONFIG_DEFAULTS = {
+    discovery: {
+        concurrency: 4,
+        catalogTtlSeconds: 300,
+        catalogMinTtlSeconds: 0,
+        catalogMaxTtlSeconds: 86_400,
+        probeTimeoutMs: 30_000,
+    },
+    calls: {
+        maxResultBytes: 24_000,
+    },
+    results: {
+        maxStashBytes: 8 * 1024 * 1024,
+        maxStashEntries: 64,
+    },
+    execute: {
+        maxEmittedBytes: 4_000_000,
+        maxEmittedBlocks: 32,
+        maxHostCalls: 20,
+        hostCallTimeoutMs: 15_000,
+        watchdogMs: 120_000,
+        maxWrites: 10,
+    },
+    admission: {
+        requests: {
+            concurrency: 16,
+            maxQueueSize: 32,
+            queueTimeoutMs: 5_000,
+            retryAfterMs: 1_000,
+            maxDurationMs: 300_000,
+        },
+        code: {
+            concurrency: 2,
+            maxQueueSize: 8,
+            queueTimeoutMs: 5_000,
+            retryAfterMs: 1_000,
+        },
+    },
+};

package/dist/config-schema.d.ts

@@ -0,0 +1,181 @@
+/** One configuration field: its input type, resolved type, and optionality. */
+export interface Field<In, Out, Opt extends boolean = boolean> {
+    /** Whether a deployment may omit the field. */
+    readonly optional: Opt;
+    /** Resolve a present (own, not `undefined`) value or throw. */
+    readonly parse: (value: unknown, path: string) => Out;
+    /** Resolve an omitted value: its default, `undefined`, or a throw. */
+    readonly absent: (path: string) => Out;
+    /** Child fields of a closed object, walked for unknown keys. */
+    readonly shape?: Shape;
+    /** Element field of an array or record, walked for unknown keys. */
+    readonly element?: Field<unknown, unknown>;
+    /** Whether `element` describes record values rather than array items. */
+    readonly keyed?: boolean;
+    /** Closed object shapes chosen by the string at one key, walked for unknown keys. */
+    readonly variants?: Variants;
+    /** Whether a closed object carries behaviour, so the walk returns it as given. */
+    readonly instance?: boolean;
+    /** Whether a record's values must be strings: header values, extra parameters. */
+    readonly strings?: boolean;
+    /** Phantom input type; never set. */
+    readonly __in?: In;
+}
+type AnyField = Field<any, any, boolean>;
+export type Shape = {
+    readonly [key: string]: AnyField;
+};
+/** A discriminated union of closed objects: `cases[value[key]]`, else `cases[otherwise]`. */
+interface Variants {
+    readonly key: string;
+    readonly cases: Readonly<Record<string, Shape>>;
+    readonly otherwise?: string;
+}
+type InputOf<F> = F extends Field<infer In, unknown, boolean> ? In : never;
+type OutputOf<F> = F extends Field<unknown, infer Out, boolean> ? Out : never;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * What a deployment writes for an object schema. Optional fields also accept
+ * an explicit `undefined`, so an optional module can be wired as
+ * `vault: key ? encryptedCredentialVault(storage, key) : undefined`.
+ */
+export type ConfigInput<S extends Shape> = Simplify<{
+    -readonly [K in keyof S as S[K]["optional"] extends true ? K : never]?: InputOf<S[K]> | undefined;
+} & {
+    -readonly [K in keyof S as S[K]["optional"] extends true ? never : K]: InputOf<S[K]>;
+}>;
+/** What core reads for an object schema: every default already applied. */
+export type ConfigOutput<S extends Shape> = Simplify<{
+    readonly [K in keyof S]: OutputOf<S[K]>;
+}>;
+/** A structural configuration mistake, thrown before construction does work. */
+export declare class ConfigError extends TypeError {
+    readonly name = "ConfigError";
+}
+interface WholeOptions {
+    /** Smallest accepted value. */
+    min: 0 | 1;
+    /** Largest accepted value, when there is one. */
+    max?: number;
+    /** Unit named in the `max` refusal, e.g. "milliseconds". */
+    unit?: string;
+}
+/** A safe integer at or above `min`; the default applies only when omitted. */
+export declare function whole(options: WholeOptions & {
+    default: number;
+}): Field<number, number, true>;
+export declare function whole(options: WholeOptions): Field<number, number | undefined, true>;
+/** A non-negative finite number, fractions allowed. */
+export declare function seconds(options: {
+    default: number;
+}): Field<number, number, true>;
+export declare function text(): Field<string, string | undefined, true>;
+/**
+ * A value core checks by shape and passes through untouched: a connector, a
+ * module, an executor. `check` throws its own message for a wrong value;
+ * `resolve` maps the accepted value (or `undefined`, when omitted) to what
+ * core reads.
+ */
+export declare function opaque<In, Out = In | undefined>(options?: {
+    check?: (value: unknown, path: string) => void;
+    resolve?: (value: In | undefined) => Out;
+}): Field<In, Out, true>;
+/** A function, never called, read, or serialized by configuration. */
+export declare function fn<F extends (...args: never[]) => unknown>(): Field<F, F | undefined, true>;
+/** The same field, but a deployment must supply it. */
+export declare function required<In, Out>(field: Field<In, Out, boolean>, message?: (path: string) => string): Field<In, Exclude<Out, undefined>, false>;
+/**
+ * A closed object. Its keys are the shape's keys; anything else is refused
+ * by the unknown-key walk before any value is read. An omitted object
+ * resolves to its children's defaults.
+ */
+export declare function object<S extends Shape>(shape: S): Field<ConfigInput<S>, ConfigOutput<S>, true> & {
+    readonly shape: S;
+};
+/** A list whose items each satisfy `item`. */
+export declare function array<In, Out>(item: Field<In, Out, boolean>): Field<In[], readonly Exclude<Out, undefined>[] | undefined, true>;
+/** An object keyed by caller-chosen names, each value satisfying `value`. */
+export declare function record<In, Out>(value: Field<In, Out, boolean>): Field<Record<string, In>, Readonly<Record<string, Exclude<Out, undefined>>> | undefined, true>;
+/**
+ * A map of caller-chosen names to strings, such as static headers or extra
+ * OAuth parameters. The walk copies it through property descriptors, so an
+ * accessor is refused by path unrun and a non-string value by path unechoed.
+ */
+export declare function strings(): Field<Record<string, string>, Readonly<Record<string, string>> | undefined, true>;
+/**
+ * A closed object that carries behaviour, such as an `api()` tool. The walk
+ * checks it like any closed object (own keys declared, no own accessor, and
+ * no inherited accessor at a declared key) but returns the original rather
+ * than a copy, so a prototype method keeps its receiver and a handler that
+ * reads `#private` fields still finds them. It may be a class instance.
+ */
+export declare function instance<F extends AnyField>(field: F): F & {
+    readonly instance: true;
+};
+/**
+ * A closed object whose allowed keys depend on a discriminant, such as
+ * `remoteMcp({ auth: { type: "headers", headers } })`. An omitted
+ * discriminant selects `otherwise` when given; an omitted one without it, an
+ * unrecognized one, or a value that is not an object throws with its path and
+ * the valid values, so no union falls through to "no case". Only the walk
+ * reads variants; the factory validates the remaining values itself.
+ */
+export declare function variants(key: string, cases: Readonly<Record<string, Shape>>, otherwise?: string): Field<unknown, unknown, true>;
+/**
+ * A closed object for the unknown-key walk only: each named key may hold
+ * anything, which its factory validates. For the options of a built-in
+ * factory, where `object()` would resolve values the factory already owns.
+ */
+export declare function keys<const K extends string>(...names: K[]): {
+    readonly [P in K]: Field<unknown, unknown, true>;
+};
+/** Every key of every member of a union, so a shape can be checked against it. */
+type KeysOfUnion<T> = T extends unknown ? keyof T : never;
+/**
+ * The closed options of a built-in factory, checked against its options type:
+ * a key the type declares but the shape omits, or the reverse, fails to
+ * compile, so the runtime walk cannot drift from the published type.
+ */
+export declare function optionsOf<T>(): <S extends { readonly [K in Exclude<KeysOfUnion<T>, symbol>]-?: AnyField; }>(shape: S & Record<Exclude<keyof S, KeysOfUnion<T>>, never>) => Field<unknown, unknown, true> & {
+    readonly shape: S;
+};
+/**
+ * Refuse a factory's unknown options and accessors before it reads any value,
+ * naming each path: `api("crm").maxResultByte`. Returns the options as a
+ * plain copy read through property descriptors, which the factory reads in
+ * place of what it was given, so no getter or Proxy trap of the caller's runs
+ * later either. Custom implementations a factory accepts (stores, handlers,
+ * executors) are `opaque()` in its shape and pass through untouched; an
+ * object that carries behaviour (an `api()` tool) is `instance()`, checked in
+ * place and passed through as given.
+ */
+export declare function assertKnownOptions<T>(value: T, path: string, field: AnyField): T;
+/**
+ * Read a configuration value the way the schema sees it: every own key it
+ * does not declare, as paths, and the value as a plain copy built only from
+ * the property descriptors this walk inspected. Callers resolve that copy,
+ * never the original, so no property is read through `[[Get]]` twice or at
+ * all: no getter runs, a Proxy's `get` trap never fires, and no value is
+ * echoed.
+ *
+ * Unknown keys anywhere are reported first. With none, a declared key holding
+ * an accessor is refused by path, since a plain configuration object has no
+ * reason to compute a value, and a getter that throws or changes between
+ * reads would break the one-read guarantee. Only own string keys count, so a
+ * prototype contributes nothing. A closed object or record slot takes a
+ * plain object only; an array or class instance there is refused by path.
+ * Arrays are walked by the same rules, the items of an `opaque()` array
+ * included (`allowedOrigins`, `auth`); an `instance()` object (an `api()`
+ * tool) is checked the same way but returned as given; any other `opaque()`
+ * value (a connector, module, executor, storage, or logger) is never entered
+ * and passes through as configured. Configuration is operator-authored and
+ * trusted: the walk refuses mistakes by path without echoing a value; it is
+ * not a sandbox for hostile objects.
+ */
+export declare function readPlain(value: unknown, path: string, field: AnyField): {
+    unknown: string[];
+    value: unknown;
+};
+export {};