@orkestrel/tool 0.0.3 → 0.0.5

package/dist/src/core/index.d.cts

@@ -296,12 +296,12 @@ export declare interface AnswerToolOptions {
  * union directly, so `value` is typed as the full `string | boolean | readonly string[]` union
  * here (no lossy string-only fallback needed).
  */
-export declare const answerToolShape: UnionShape<[ ObjectShape<{
+export declare const answerToolShape: UnionShape<readonly [ ObjectShape<{
     operation: LiteralShape<readonly ["pending"]>;
 }, false>, ObjectShape<{
     operation: LiteralShape<readonly ["answer"]>;
     id: StringShape;
-    value: UnionShape<[ StringShape, BooleanShape, ArrayShape<StringShape>]>;
+    value: UnionShape<readonly [ StringShape, BooleanShape, ArrayShape<StringShape>]>;
 }, false>]>;
 
 /**
@@ -379,7 +379,7 @@ export declare type ColumnSpec = ColumnKind | Readonly<{
 }>;
 
 /** A {@link import('./types.js').ColumnSpec} — a bare {@link columnKindShape}, or `{ type, optional }`. */
-export declare const columnSpecShape: UnionShape<[ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
+export declare const columnSpecShape: UnionShape<readonly [ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
     type: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
     optional: OptionalShape<BooleanShape>;
 }, false>]>;
@@ -673,6 +673,153 @@ export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolI
  */
 export declare function createDescribeTool(tools: ToolManagerInterface): ToolInterface;
 
+/**
+ * Wrap one CONCRETE endpoint ({@link import('./types.js').EndpointDefinition}) as an LLM-callable
+ * `ToolInterface` — the endpoint half of the "existing API/DB → MCP tool" bridge (the other half,
+ * {@link createInferTool}, is a standalone inference utility).
+ *
+ * @remarks
+ * `parameters` is inferred ONCE at construction from `definition.samples` via
+ * `@orkestrel/contract`'s `samplesToSchema` (tuned by {@link import('./types.js').EndpointToolOptions}'s
+ * `format` / `enum`), wrapping a non-object root as `{ value: <schema> }` via `schemaToObject` —
+ * the SAME object-rooted schema is both the ADVERTISED `parameters` and, by default
+ * ({@link import('./types.js').EndpointToolOptions.validate} `true`), the ENFORCED contract:
+ * `@orkestrel/contract` 0.0.7's `schemaToShape` compiles it ONCE (via `createContract`) into a
+ * `ContractInterface` whose `.parse` runs on every call's `args` before `definition.invoke` — a
+ * NORMALIZING parse, not a strict type check: a scalar is COERCED to its inferred type where the
+ * house parsers coerce (a number to/from a numeric string, a boolean from `'1'`/`'0'`/`'true'`/
+ * `'false'`/`1`/`0`), so `definition.invoke` receives the COERCED value (e.g. `7` sent for a
+ * string slot arrives as `'7'`), not the raw call value. A call whose `args` fails to parse into
+ * a record — a required key missing, or a value not coercible to its slot's type — THROWS a
+ * typed `TOOL` {@link import('./errors.js').AgentToolError} carrying the compiled contract's
+ * structured `explain` faults, and `definition.invoke` is never called. `format` annotations are
+ * NEVER asserted, and a key outside the closed inferred schema is SILENTLY DROPPED rather than
+ * rejected (see {@link import('./types.js').EndpointToolOptions.validate}). With
+ * `validate: false`, `execute` PASSES THROUGH the model-supplied `args` to `definition.invoke`
+ * WITHOUT re-validation — the pre-0.0.7 behavior, preserved as an explicit opt-out. Either way,
+ * `invoke`'s return flows back as the tool call's plain result; a throw PROPAGATES uncaught,
+ * isolated by the `ToolManagerInterface` (`@orkestrel/agent`) into the canonical error envelope
+ * (AGENTS §14) — never caught or re-wrapped here.
+ *
+ * @param definition - The endpoint's identity, non-empty samples, and local handler (see
+ *   {@link import('./types.js').EndpointDefinition})
+ * @param options - Construction-time inference tuning + the validate opt-out (see
+ *   {@link import('./types.js').EndpointToolOptions})
+ * @returns A `ToolInterface` named `definition.name`
+ *
+ * @example
+ * ```ts
+ * import { createEndpointTool } from '@src/core'
+ * import { createToolManager } from '@orkestrel/agent'
+ *
+ * const tool = createEndpointTool({
+ * 	name: 'lookupUser',
+ * 	description: 'Look up a user by id.',
+ * 	samples: [{ id: '1', name: 'Ada' }, { id: '2', name: 'Bob' }],
+ * 	invoke: (args) => ({ id: args.id, name: 'Ada' }),
+ * })
+ * const tools = createToolManager()
+ * tools.add(tool)
+ *
+ * // conforming args (all required keys present) parse and reach `invoke`
+ * const result = await tools.execute({
+ * 	id: 'call-1',
+ * 	name: 'lookupUser',
+ * 	arguments: { id: '1', name: 'Ada' },
+ * })
+ * // result.value -> { id: '1', name: 'Ada' }
+ *
+ * // a nonconforming call (id is not coercible to the required string) is rejected before
+ * // `invoke` runs
+ * const rejected = await tools.execute({
+ * 	id: 'call-2',
+ * 	name: 'lookupUser',
+ * 	arguments: { id: true, name: 'Ada' },
+ * })
+ * // rejected.error -> the TOOL AgentToolError message
+ * ```
+ */
+export declare function createEndpointTool(definition: EndpointDefinition, options?: EndpointToolOptions): ToolInterface;
+
+/**
+ * Build a standalone LLM-callable tool that infers a JSON Schema from example values — the
+ * utility half of the "existing API/DB → MCP tool" bridge (the other half,
+ * {@link createEndpointTool}, wraps one CONCRETE endpoint).
+ *
+ * @remarks
+ * The universal tool-handler contract (AGENTS §14): validates the call args against
+ * {@link import('./shapers.js').inferToolShape} (`samples` non-empty, `format` / `enum` optional
+ * booleans, `candidates` an optional array), infers a schema via `@orkestrel/contract`'s
+ * `samplesToSchema`, wraps a non-object root as `{ value: <schema> }` via `schemaToObject` (mirrors
+ * the tool-parameters convention every other `create*Tool` factory advertises), and RETURNS the
+ * resulting parameters record. An empty `samples` array fails `inferToolShape`'s `min: 1` bound —
+ * `contract.parse` returns `undefined` and the handler throws a typed `TOOL`
+ * {@link import('./errors.js').AgentToolError}.
+ *
+ * When `candidates` is ABSENT, the return is the bare parameters record — unchanged from before
+ * this array existed. When `candidates` is PRESENT (any array, including empty), the handler
+ * compiles a SEPARATE per-call contract from the RAW inferred schema (via `@orkestrel/contract`'s
+ * `schemaToShape`, NOT the `schemaToObject`-wrapped parameters — a bare-value sample checks a
+ * bare-value candidate) and returns `{ parameters, checks }`, one check per candidate at the same
+ * index. Every entry has a UNIFORM shape — `{ index, valid, coercible }`, with `faults` added ONLY
+ * when `valid` is `false`: `valid` is the STRICT guard verdict (`checker.is(candidate)`), the
+ * OPPOSITE of {@link createEndpointTool}'s enforcement, which coerces (`7` becomes `'7'` for a
+ * string slot) — here a conformance report answers "does this value conform AS-IS": `7` against a
+ * string slot is `valid: false`, full stop. `coercible` answers a SEPARATE question — "would the
+ * NORMALIZING parse accept this value", i.e. would {@link createEndpointTool}'s default enforcement
+ * admit it (`checker.parse(candidate) !== undefined`) — computed for every candidate regardless of
+ * `valid`; by the house parse/guard round-trip guarantee (AGENTS §14), a `valid: true` entry is
+ * ALWAYS also `coercible: true`. `@orkestrel/contract` 0.0.7's `explain` mirrors the normalizing
+ * `parse`'s leniency, not `is`'s strictness — so a strictly-invalid but coercible candidate (`7`
+ * against a string slot) yields `{ valid: false, coercible: true, faults: [] }`: EMPTY faults, since
+ * the mismatch the normalizing parse would silently fix is not one `explain` reports. `faults`
+ * therefore only ever populates for a NON-coercible mismatch — a wrong type the parse can't coerce
+ * (a boolean in a string slot), a missing required key, or an out-of-enum value — where
+ * `coercible: false`. `checker.is` / `.parse` / `.explain` are all total over JSON-safe input — a
+ * JSON-safe hostile candidate (a `__proto__`-carrying object, deeply nested data) reaches all three
+ * and yields a bounded, non-throwing per-candidate verdict; a NON-JSON-safe candidate (e.g. a
+ * throwing-getter `Proxy`) never reaches the checker at all — it fails the OUTER `args` parse
+ * against {@link import('./shapers.js').inferToolShape} and rejects the WHOLE call with the same
+ * `TOOL` {@link import('./errors.js').AgentToolError} a malformed `samples`/`format`/`enum` throws,
+ * with no per-candidate verdict produced.
+ *
+ * @param options - Advertised `name` / `description` overrides (see
+ *   {@link import('./types.js').InferToolOptions})
+ * @returns A `ToolInterface` (named {@link import('./constants.js').INFER_TOOL_NAME} by default)
+ *
+ * @example
+ * ```ts
+ * import { createInferTool } from '@src/core'
+ * import { createToolManager } from '@orkestrel/agent'
+ *
+ * const tool = createInferTool()
+ * const tools = createToolManager()
+ * tools.add(tool)
+ *
+ * const result = await tools.execute({
+ * 	id: 'call-1',
+ * 	name: 'infer',
+ * 	arguments: { samples: [{ id: 1, name: 'Ada' }, { id: 2, name: 'Bob' }] },
+ * })
+ * // result.value -> { type: 'object', properties: { id: {...}, name: {...} }, ... }
+ *
+ * // with candidates, the result is wrapped with per-candidate verdicts
+ * const checked = await tools.execute({
+ * 	id: 'call-2',
+ * 	name: 'infer',
+ * 	arguments: {
+ * 		samples: [{ id: 1, name: 'Ada' }],
+ * 		candidates: [{ id: 2, name: 'Bob' }, { id: 'x', name: 'Cy' }],
+ * 	},
+ * })
+ * // checked.value -> { parameters: {...}, checks: [
+ * //   { index: 0, valid: true, coercible: true },
+ * //   { index: 1, valid: false, coercible: false, faults: [...] },
+ * // ] }
+ * ```
+ */
+export declare function createInferTool(options?: InferToolOptions): ToolInterface;
+
 /**
  * Create the in-memory {@link DefinitionStoreInterface} — a process-lifetime `Map` of database
  * definitions, the DEFAULT store the upcoming database / relation tools will persist their
@@ -1111,6 +1258,66 @@ export declare class DatabaseDefinitionStore implements DefinitionStoreInterface
     delete(id: string): Promise<void>;
 }
 
+/**
+ * Resolve database definitions into cached live handles for database tools.
+ *
+ * @example
+ * ```ts
+ * import { DatabaseResolver } from '@orkestrel/tool'
+ *
+ * const resolver = new DatabaseResolver(handles, drivers, key, store)
+ * const database = await resolver.resolve('shop')
+ * ```
+ */
+export declare class DatabaseResolver {
+    #private;
+    /**
+     * Create a database resolver over the tool's live state and optional definition store.
+     *
+     * @param handles - Initial live database handles cached by id
+     * @param drivers - Driver factories keyed by definition driver name
+     * @param key - Key generator supplied to newly created databases
+     * @param store - Optional persistent definition store
+     */
+    constructor(handles: ReadonlyMap<string, DatabaseInterface>, drivers: Readonly<Record<string, () => DriverInterface>>, key: KeyFunction, store?: DefinitionStoreInterface);
+    /**
+     * Determine whether a live database is cached by id.
+     *
+     * @param id - Database id
+     * @returns Whether a live handle is cached
+     */
+    has(id: string): boolean;
+    /**
+     * Read a cached database without consulting the definition store.
+     *
+     * @param id - Database id
+     * @returns The cached live database, or `undefined`
+     */
+    get(id: string): DatabaseInterface | undefined;
+    /**
+     * Cache a live database by id.
+     *
+     * @param id - Database id
+     * @param database - Live database handle
+     * @returns Nothing
+     */
+    set(id: string, database: DatabaseInterface): void;
+    /**
+     * Remove a cached live database by id.
+     *
+     * @param id - Database id
+     * @returns Nothing
+     */
+    delete(id: string): void;
+    /**
+     * Resolve a cached or stored database by id.
+     *
+     * @param id - Database definition id
+     * @returns The cached or newly constructed live database
+     */
+    resolve(id: string): Promise<DatabaseInterface>;
+}
+
 /**
  * Map a caught error to the {@link AgentToolErrorCode} the upcoming database tool should throw
  * with — the pure classification step of that factory's error handling, mirroring
@@ -1177,11 +1384,11 @@ export declare interface DatabaseToolOptions {
  * `'aggregate'` carry an optional `criteria` (the SERIALIZED form — `values` is ALWAYS an array,
  * even for a single-value operator, so a caller never chains method calls or guesses arity).
  */
-export declare const databaseToolShape: UnionShape<[ ObjectShape<{
+export declare const databaseToolShape: UnionShape<readonly [ ObjectShape<{
     operation: LiteralShape<readonly ["create"]>;
     id: StringShape;
     tables: ObjectShape<Record<never, never>, ObjectShape<{
-        columns: ObjectShape<Record<never, never>, UnionShape<[ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
+        columns: ObjectShape<Record<never, never>, UnionShape<readonly [ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
             type: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
             optional: OptionalShape<BooleanShape>;
         }, false>]>>;
@@ -1195,7 +1402,7 @@ export declare const databaseToolShape: UnionShape<[ ObjectShape<{
     operation: LiteralShape<readonly ["get"]>;
     id: StringShape;
     table: StringShape;
-    key: UnionShape<[ ArrayShape<UnionShape<[ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+    key: UnionShape<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
 }, false>, ObjectShape<{
     operation: LiteralShape<readonly ["records"]>;
     id: StringShape;
@@ -1256,28 +1463,28 @@ export declare const databaseToolShape: UnionShape<[ ObjectShape<{
     operation: LiteralShape<readonly ["add"]>;
     id: StringShape;
     table: StringShape;
-    row: UnionShape<[ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
+    row: UnionShape<readonly [ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
 }, false>, ObjectShape<{
     operation: LiteralShape<readonly ["set"]>;
     id: StringShape;
     table: StringShape;
-    row: UnionShape<[ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
+    row: UnionShape<readonly [ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
 }, false>, ObjectShape<{
     operation: LiteralShape<readonly ["update"]>;
     id: StringShape;
     table: StringShape;
-    key: UnionShape<[ ArrayShape<UnionShape<[ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+    key: UnionShape<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
     changes: ObjectShape<Record<never, never>, JSONShape>;
 }, false>, ObjectShape<{
     operation: LiteralShape<readonly ["remove"]>;
     id: StringShape;
     table: StringShape;
-    key: UnionShape<[ ArrayShape<UnionShape<[ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+    key: UnionShape<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
 }, false>, ObjectShape<{
     operation: LiteralShape<readonly ["migrate"]>;
     id: StringShape;
     tables: ObjectShape<Record<never, never>, ObjectShape<{
-        columns: ObjectShape<Record<never, never>, UnionShape<[ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
+        columns: ObjectShape<Record<never, never>, UnionShape<readonly [ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
             type: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
             optional: OptionalShape<BooleanShape>;
         }, false>]>>;
@@ -1349,6 +1556,76 @@ export declare const describeToolShape: ObjectShape<{
     name: StringShape;
 }, false>;
 
+/**
+ * One concrete endpoint {@link import('./factories.js').createEndpointTool} wraps as an
+ * LLM-callable `ToolInterface` — the advertised identity, a non-empty set of example values its
+ * `parameters` are inferred from, and the local handler that runs a call.
+ *
+ * @remarks
+ * `samples` MUST be non-empty — {@link import('./factories.js').createEndpointTool} throws a
+ * typed `TOOL` {@link import('./errors.js').AgentToolError} at CONSTRUCTION when it is empty,
+ * since an empty sample set cannot infer a schema. By DEFAULT ({@link EndpointToolOptions.validate}
+ * `true`) `invoke` receives the PARSED, NORMALIZED args record — a copy of the model-supplied
+ * `args` with each scalar coerced to its inferred type (e.g. a number sent for a string slot
+ * arrives coerced to a string), checked against the same schema advertised as `parameters` — and
+ * a call with a missing required key or a non-coercible value never reaches `invoke` at all (see
+ * {@link EndpointToolOptions.validate}). With
+ * `validate: false`, `invoke` receives the model-supplied `args` VERBATIM (raw passthrough, never
+ * checked against the inferred schema). Either way `invoke`'s return flows back as the tool
+ * call's result; a throw PROPAGATES uncaught, isolated by the `ToolManagerInterface`
+ * (`@orkestrel/agent`) into the canonical error envelope. When `samples` are non-object values,
+ * the advertised schema wraps them under a single required `value` property, so `invoke` receives
+ * an `args` record of the shape `{ value: ... }` — never the bare value.
+ */
+export declare interface EndpointDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly samples: readonly unknown[];
+    readonly invoke: EndpointHandler;
+}
+
+/**
+ * The handler {@link import('./types.js').EndpointDefinition.invoke} implements — mirrors
+ * `@orkestrel/agent`'s `ToolOptions.execute` signature EXACTLY (same `Readonly<Record<string,
+ * unknown>>` argument, same `Promise<unknown> | unknown` return) so
+ * `execute: (args) => definition.invoke(args)` typechecks with zero assertions in
+ * {@link import('./factories.js').createEndpointTool}.
+ */
+export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>) => Promise<unknown> | unknown;
+
+/**
+ * Construction-time tuning for {@link import('./factories.js').createEndpointTool} — the
+ * inferred `parameters` schema's `format` / `enum` constraints, and whether that same schema is
+ * ENFORCED at `execute` time.
+ *
+ * @remarks
+ * `format` / `enum` default to `false`, matching `@orkestrel/contract`'s own
+ * `ValueToSchemaOptions` defaults. `validate` defaults to `true`: the schema
+ * `createEndpointTool` advertises as `parameters` (`samplesToSchema` + `schemaToObject`) is
+ * compiled ONCE at construction (via `@orkestrel/contract` 0.0.7's `schemaToShape`) into a
+ * `ContractInterface` used to `parse` every call's `args` before `invoke` runs — a NORMALIZING
+ * parse: a scalar value is COERCED to its inferred type where the house parsers coerce (a number
+ * to/from a numeric string, a boolean from `'1'`/`'0'`/`'true'`/`'false'`/`1`/`0`), so `invoke`
+ * receives the COERCED values (e.g. `7` sent for a string slot arrives at `invoke` as `'7'`), not
+ * the raw call args. A call whose `args` fails to parse — a required key missing, or a value not
+ * coercible to its slot's type — THROWS a typed `TOOL` {@link import('./errors.js').AgentToolError}
+ * carrying the structured `explain` faults, and `invoke` is never called. Beyond that coercion,
+ * enforcement is STRUCTURAL — required keys, `enum` membership, and numeric bounds — `format`
+ * annotations (`email`, `date-time`, `uuid`, `uri`, ...) are NEVER asserted, mirroring
+ * `@orkestrel/contract`'s own widening-only law for `schemaToShape`: a `format: true`-tuned
+ * endpoint still ACCEPTS a non-conforming string in a format-tagged slot. A key NOT present in
+ * the inferred (closed, `additionalProperties: false`) schema is NEVER a rejection either — it is
+ * SILENTLY DROPPED before `invoke` runs (the same leniency `@orkestrel/contract`'s own `parse`
+ * grants a closed object generally), so `invoke` may see fewer keys than the caller sent. Set
+ * `validate: false` to restore the PRE-0.0.7 behavior exactly — `execute` passes the
+ * model-supplied `args` straight to `invoke` UNCHANGED, unchecked and unstripped.
+ */
+export declare interface EndpointToolOptions {
+    readonly format?: boolean;
+    readonly enum?: boolean;
+    readonly validate?: boolean;
+}
+
 /**
  * Expand the relation tool's FLAT dot-path `include` list into a live `@orkestrel/relation`
  * {@link Include} tree — the pure leaf {@link import('./factories.js').createRelationTool} calls
@@ -1408,6 +1685,54 @@ export declare function expandTables(spec: TableSpec): TablesShape;
 /** Flat dot-path relation include list, expanded via {@link import('./helpers.js').expandInclude}. */
 export declare const includeShape: OptionalShape<ArrayShape<StringShape>>;
 
+export declare const INFER_TOOL_DESCRIPTION: string;
+
+/**
+ * The name {@link import('./factories.js').createInferTool} advertises by default — the key a
+ * model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+ */
+export declare const INFER_TOOL_NAME = "infer";
+
+/**
+ * The lean {@link import('@orkestrel/agent').ToolInterface.summary} {@link import('./factories.js').createInferTool}
+ * advertises in place of {@link INFER_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
+ * (`@orkestrel/agent`) advertises `summary ?? description`, so this one-sentence text stands in
+ * for the full teaching description; the full text stays retrievable via
+ * {@link import('./factories.js').createDescribeTool}.
+ */
+export declare const INFER_TOOL_SUMMARY = "Infer a JSON Schema (as advertised tool parameters) from one or more example values. Call describe('infer') for the required fields.";
+
+/**
+ * Options for {@link import('./factories.js').createInferTool} — advertised name/description
+ * overrides only; `format` / `enum` are RUNTIME call arguments (see
+ * {@link import('./shapers.js').inferToolShape}), not construction-time options, since a model
+ * chooses them per call.
+ */
+export declare interface InferToolOptions {
+    readonly name?: string;
+    readonly description?: string;
+}
+
+/**
+ * The shape of {@link import('./factories.js').createInferTool}'s call arguments — one or more
+ * example `samples` to infer a JSON Schema from, plus per-call `format` / `enum` toggles and an
+ * optional `candidates` array to check against the inferred schema.
+ *
+ * @remarks
+ * `samples` requires at least one element (`min: 1`) — an empty array parses to `undefined`,
+ * surfaced by the handler as a typed `TOOL` {@link import('./errors.js').AgentToolError}. When
+ * `candidates` is present (any array, including empty), the handler compiles a contract from the
+ * freshly inferred schema and checks each candidate against it with a STRICT guard (`.is`, no
+ * coercion) — the opposite of {@link import('./factories.js').createEndpointTool}'s NORMALIZING
+ * `.parse` enforcement.
+ */
+export declare const inferToolShape: ObjectShape<{
+    samples: ArrayShape<JSONShape>;
+    format: OptionalShape<BooleanShape>;
+    enum: OptionalShape<BooleanShape>;
+    candidates: OptionalShape<ArrayShape<JSONShape>>;
+}, false>;
+
 /**
  * Type guard narrowing an unknown caught value to an {@link AgentToolError}.
  *
@@ -1442,7 +1767,7 @@ export declare function isColumnSpec(value: unknown): value is ColumnSpec;
 export declare function isDatabaseDefinition(value: unknown): value is DatabaseDefinition;
 
 /** One key value — a string or number; the array form (multiple keys, positional) resolves FIRST per AGENTS §9.2. */
-export declare const keyShape: UnionShape<[ ArrayShape<UnionShape<[ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+export declare const keyShape: UnionShape<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
 
 /** Map one {@link import('./types.js').ColumnKind} to its primitive `@orkestrel/database` shape — the leaf {@link columnShape} wraps. */
 export declare function kindShape(kind: ColumnKind): ContractShape;
@@ -1653,7 +1978,7 @@ export declare const RELATION_TOOL_NAME = "relation";
 export declare const RELATION_TOOL_SUMMARY = "Traverse and edit relationships between database rows \u2014 one operation per call (load, find, link, unlink, links), chosen by the 'operation' field. Call describe('relation') for the include-path syntax.";
 
 /** One key value — a string or number; the array form (multiple keys, positional) resolves FIRST per AGENTS §9.2. */
-export declare const relationKeyShape: UnionShape<[ ArrayShape<UnionShape<[ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+export declare const relationKeyShape: UnionShape<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
 
 /**
  * Resolve which registered {@link RelationManagerInterface} a relation-tool call addresses — the
@@ -1729,11 +2054,11 @@ export declare interface RelationToolOptions {
  * fetches rows (pagination / sort only) with `include` attached. `'link'` / `'unlink'` write /
  * remove a `through` junction row; `'links'` lists a `through` relation's linked keys.
  */
-export declare const relationToolShape: UnionShape<[ ObjectShape<{
+export declare const relationToolShape: UnionShape<readonly [ ObjectShape<{
     operation: LiteralShape<readonly ["load"]>;
     manager: OptionalShape<StringShape>;
     model: StringShape;
-    key: UnionShape<[ ArrayShape<UnionShape<[ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+    key: UnionShape<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
     include: OptionalShape<ArrayShape<StringShape>>;
 }, false>, ObjectShape<{
     operation: LiteralShape<readonly ["find"]>;
@@ -1748,21 +2073,21 @@ export declare const relationToolShape: UnionShape<[ ObjectShape<{
     operation: LiteralShape<readonly ["link"]>;
     manager: OptionalShape<StringShape>;
     model: StringShape;
-    key: UnionShape<[ StringShape, NumberShape]>;
+    key: UnionShape<readonly [ StringShape, NumberShape]>;
     relation: StringShape;
-    target: UnionShape<[ StringShape, NumberShape]>;
+    target: UnionShape<readonly [ StringShape, NumberShape]>;
 }, false>, ObjectShape<{
     operation: LiteralShape<readonly ["unlink"]>;
     manager: OptionalShape<StringShape>;
     model: StringShape;
-    key: UnionShape<[ StringShape, NumberShape]>;
+    key: UnionShape<readonly [ StringShape, NumberShape]>;
     relation: StringShape;
-    target: UnionShape<[ StringShape, NumberShape]>;
+    target: UnionShape<readonly [ StringShape, NumberShape]>;
 }, false>, ObjectShape<{
     operation: LiteralShape<readonly ["links"]>;
     manager: OptionalShape<StringShape>;
     model: StringShape;
-    key: UnionShape<[ StringShape, NumberShape]>;
+    key: UnionShape<readonly [ StringShape, NumberShape]>;
     relation: StringShape;
 }, false>]>;
 
@@ -1770,10 +2095,10 @@ export declare const relationToolShape: UnionShape<[ ObjectShape<{
 export declare const rowShape: ObjectShape<Record<never, never>, JSONShape>;
 
 /** One or many loose rows — the array form resolves FIRST per AGENTS §9.2. */
-export declare const rowsShape: UnionShape<[ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
+export declare const rowsShape: UnionShape<readonly [ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
 
 /** A single row key (not an array) — used by `'link'` / `'unlink'` / `'links'`, which address exactly one owning row. */
-export declare const singleKeyShape: UnionShape<[ StringShape, NumberShape]>;
+export declare const singleKeyShape: UnionShape<readonly [ StringShape, NumberShape]>;
 
 /**
  * The shape of ONE flat step — `{ name }` — the building block of {@link workflowStepsShape}.
@@ -1812,7 +2137,7 @@ export declare type TableSpec = Readonly<Record<string, Readonly<{
 
 /** A {@link import('./types.js').TableSpec} — table name to `{ columns }`, each column a {@link columnSpecShape}. */
 export declare const tableSpecShape: ObjectShape<Record<never, never>, ObjectShape<{
-    columns: ObjectShape<Record<never, never>, UnionShape<[ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
+    columns: ObjectShape<Record<never, never>, UnionShape<readonly [ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
         type: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
         optional: OptionalShape<BooleanShape>;
     }, false>]>>;
@@ -2266,7 +2591,7 @@ export declare interface WorkspaceToolOptions {
  * the model can move between) and `switch` (re-point the active one by `id`) — let a model
  * DISCOVER then CHOOSE which workspace the edit / read arms target.
  */
-export declare const workspaceToolShape: UnionShape<[ ObjectShape<{
+export declare const workspaceToolShape: UnionShape<readonly [ ObjectShape<{
     operation: LiteralShape<readonly ["read"]>;
     path: StringShape;
 }, false>, ObjectShape<{