@orkestrel/toolbox 0.0.24 → 0.0.26

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

@@ -1,10 +1,11 @@
 import type { AgentInterface } from '@orkestrel/agent';
 import type { AgentRegistryInterface } from '@orkestrel/agent';
 import { ArrayShape } from '@orkestrel/contract';
+import type { AuditFault } from '@orkestrel/contract';
 import { BooleanShape } from '@orkestrel/contract';
 import type { Condition } from '@orkestrel/database';
 import type { ConditionConnector } from '@orkestrel/database';
-import type { ContractInterface } from '@orkestrel/contract';
+import { ContractInterface } from '@orkestrel/contract';
 import type { ContractShape } from '@orkestrel/contract';
 import type { ConversationStoreInterface } from '@orkestrel/agent';
 import type { DatabaseErrorCode } from '@orkestrel/database';
@@ -14,6 +15,7 @@ import type { Guard } from '@orkestrel/contract';
 import type { Include } from '@orkestrel/relation';
 import type { IndexMap } from '@orkestrel/database';
 import type { JSONRecord } from '@orkestrel/contract';
+import type { JSONSchema } from '@orkestrel/contract';
 import { JSONShape } from '@orkestrel/contract';
 import type { KeyFunction } from '@orkestrel/database';
 import type { LifecycleStatus } from '@orkestrel/workflow';
@@ -32,6 +34,7 @@ import type { TableInterface } from '@orkestrel/database';
 import type { TableMap } from '@orkestrel/database';
 import type { TerminalManagerInterface } from '@orkestrel/terminal';
 import type { ToolContext } from '@orkestrel/tool';
+import { ToolError } from '@orkestrel/tool';
 import type { ToolInterface } from '@orkestrel/tool';
 import type { ToolManagerInterface } from '@orkestrel/tool';
 import { UnionShape } from '@orkestrel/contract';
@@ -42,6 +45,7 @@ import type { WorkflowRegistry } from '@orkestrel/workflow';
 import type { WorkflowResult } from '@orkestrel/workflow';
 import type { WorkflowRunnerInterface } from '@orkestrel/workflow';
 import type { WorkflowStoreInterface } from '@orkestrel/workflow';
+import type { WorkspaceInterface } from '@orkestrel/workspace';
 import type { WorkspaceManagerInterface } from '@orkestrel/workspace';
 import type { WorkspaceStoreInterface } from '@orkestrel/workspace';
 
@@ -146,9 +150,12 @@ export declare interface AgentToolArguments {
  *   per-call `tools` list overrides (never merges with) this default.
  * - `system` — the default system prompt seeding the sub-agent's context; a per-call `system`
  *   overrides this.
- * - `depth` — this invocation's nesting depth (default `0`); a delegated sub-agent that itself
- *   calls this tool again runs at `depth + 1`, bounded by
- *   {@link import('./constants.js').AGENT_TOOL_DEPTH}.
+ * - `authority` — the registry key of the authority that decides the delegated sub-agent's tool
+ *   calls. A host's choice, never the call's. Tools named with no `authority` refuse before
+ *   `registry.build` runs, because an agent with tools needs one.
+ * - `depth` — this invocation's nesting depth, a nonnegative safe integer (default `0`); a delegated
+ *   sub-agent that itself calls this tool again runs at `depth + 1`, bounded by
+ *   {@link import('./constants.js').AGENT_TOOL_DEPTH}. Any other value throws at construction.
  * - `ancestry` — the sub-agent identifiers already in this delegation chain (default empty); a
  *   cycle (the resolved agent already present) is rejected with a typed `DEPTH`
  *   {@link import('./errors.js').ToolboxError}.
@@ -170,6 +177,7 @@ export declare interface AgentToolOptions {
     readonly provider?: string;
     readonly tools?: readonly string[];
     readonly system?: string;
+    readonly authority?: string;
     readonly depth?: number;
     readonly ancestry?: readonly string[];
     readonly store?: ConversationStoreInterface;
@@ -254,6 +262,35 @@ id: StringShape;
 values: JSONShape;
 }, false>]>;
 
+/**
+ * Builds an argument refusal from the supplied faults, auditing the schema when no faults were supplied.
+ *
+ * @remarks
+ * Uses the contract's union reporting: a selected arm names its own faults, and a value selecting
+ * no arm receives a bounded summary of alternatives. Supplied faults remain unchanged.
+ *
+ * @param schema - The compiled schema the arguments are held to
+ * @param value - The arguments the call sent
+ * @param faults - The faults admission reported
+ * @returns The `ToolError` to throw, with code `ARGUMENTS` and the faults in `context.faults`
+ *
+ * @example
+ * ```ts
+ * import { createContract, literalShape, objectShape, stringShape, unionShape } from '@orkestrel/contract'
+ * import { buildArgumentRefusal } from '@src/core'
+ *
+ * const { schema } = createContract(
+ * 	unionShape(
+ * 		objectShape({ operation: literalShape(['read']), path: stringShape() }),
+ * 		objectShape({ operation: literalShape(['list']) }),
+ * 	),
+ * )
+ * buildArgumentRefusal(schema, { operation: 'read' }, []).message
+ * // 'path: missing; expected string'
+ * ```
+ */
+export declare function buildArgumentRefusal(schema: JSONSchema, value: unknown, faults: readonly AuditFault[]): ToolError;
+
 /**
  * Represents the probe query and effective row limit {@link import('./helpers.js').clampQuery}
  * returns.
@@ -400,7 +437,8 @@ connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
  * targets deeper than {@link import('./constants.js').MAX_WORKFLOW_CHAIN} are rejected before
  * agent or runner activity. When {@link import('./types.js').AgentFunctionOptions.runner} is
  * supplied, the adapter binds a recursion-safe {@link createWorkflowTool} onto the agent's
- * `context.tools`, propagating opaque leaves, raw agents, lineage, and the native store. The
+ * `context.tools`, propagating opaque leaves, raw agents, lineage, and the native store. The agent
+ * needs an `authority` of its own to run that tool, because an agent with none denies every call. The
  * task's cancellation propagates through the Agent's native per-run signal seam:
  * `agent.generate({ signal: controller.signal })` resolves a partial `AgentResult` on a cancel
  * (never rejects), projected onto its exact JSON fields.
@@ -431,16 +469,20 @@ export declare function createAgentFunction(agent: AgentInterface, options?: Age
  * from `registry` and runs it to completion for one delegated `task`.
  *
  * @remarks
- * The universal tool-handler contract: validates the call args against
- * {@link import('./shapers.js').agentToolShape}, assembles an `AgentJobInput` (`task` seeds the
+ * The universal tool-handler contract: the Tool door holds the call args to
+ * {@link import('./shapers.js').agentToolShape}, refusing a malformed call with a `ToolError`
+ * carrying code `ARGUMENTS`. The handler assembles an `AgentJobInput` (`task` seeds the
  * sub-agent's conversation as a single `user` message; `provider` / `tools` / `system` fall
- * back to the tool's own {@link import('./types.js').AgentToolOptions} defaults), rehydrates the sub-agent through
+ * back to the tool's own {@link import('./types.js').AgentToolOptions} defaults, and `authority` is
+ * the tool's own, never the call's), rehydrates the sub-agent through
  * `registry.build`, runs it with `agent.generate()`, and returns the settled
- * `AgentResult.content` string (the sub-agent's final text). A missing / unresolvable `provider`, or a malformed call, throws a typed `TOOL`
+ * `AgentResult.content` string (the sub-agent's final text). A missing / unresolvable `provider`, or
+ * tools with no configured `authority`, throws a typed `TOOL`
  * {@link import('./errors.js').ToolboxError}; a delegation that would exceed
  * {@link import('./constants.js').AGENT_TOOL_DEPTH}, or re-enter an already-delegated agent (a
  * cycle), throws a typed `DEPTH` {@link import('./errors.js').ToolboxError}, each isolated
- * by the `ToolManagerInterface` into the canonical tool result's top-level `error`.
+ * by the `ToolManagerInterface` into the canonical tool result's top-level `error`. A `depth` that
+ * is not a nonnegative safe integer throws `TOOL` at construction.
  *
  * `AgentInterface` (`@orkestrel/agent`) exposes no teardown method — a bound sub-agent's
  * lifetime is the single `generate()` call this handler awaits; there is nothing to release
@@ -472,8 +514,9 @@ export declare function createAgentTool(registry: AgentRegistryInterface, option
  * addressed to {@link import('./types.js').AnswerToolOptions.to}, or answers one of them by id.
  *
  * @remarks
- * The universal tool-handler contract: validates the call args against
- * {@link import('./shapers.js').answerToolShape} (discriminated by `operation`). `'pending'`
+ * The universal tool-handler contract: the Tool door holds the call args to
+ * {@link import('./shapers.js').answerToolShape} (discriminated by `operation`), refusing malformed
+ * args with a `ToolError` carrying code `ARGUMENTS`. `'pending'`
  * returns a compact list (`{ id, from, schema }`) of every form addressed to `to`.
  * `'answer'` looks the form up by `id`, narrows the supplied `values` through `@orkestrel/form`,
  * and applies it through
@@ -527,9 +570,11 @@ export declare function createDatabaseDefinitionStore(driver?: DriverInterface):
  * {@link createWorkspaceTool}'s single-tool-many-operations shape).
  *
  * @remarks
- * The universal tool-handler contract: validates the call args against
- * {@link import('./shapers.js').databaseToolShape}, dispatches to the matching operation, and
- * returns a plain result on success. A database is resolved lazily and cached for the tool's
+ * The universal tool-handler contract: the Tool door holds the call args to
+ * {@link import('./shapers.js').databaseToolShape}, refusing malformed args with a `ToolError`
+ * carrying code `ARGUMENTS`. The handler dispatches to the matching operation and
+ * returns a plain result on success. A row a `'get'` misses is an explicit `null`. A `limit` that is
+ * not a positive safe integer throws `TOOL` at construction. A database is resolved lazily and cached for the tool's
  * lifetime — `'create'` mints one from `tables` ({@link import('./compilers.js').expandTables}) and
  * a registered `driver` key ({@link import('./types.js').DatabaseToolOptions.drivers}, default
  * `{ memory: () => createMemoryDriver() }`); any other operation addressing an uncached id falls
@@ -596,12 +641,13 @@ export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolI
  * description when `summary` is set, keeping the advertised tool list compact for a small model.
  * This tool is the on-demand expansion seam: given a registered tool's `name`, it looks the tool
  * up through `tools.tool(name)` and returns its full `description` (falling back to `summary` when a
- * tool has no `description` of its own, then a placeholder when it has neither).
+ * tool has no `description` of its own, then an explicit `null` when it has neither).
  *
- * The universal tool-handler contract: validates the call args against
- * {@link import('./shapers.js').describeToolShape}, returns the plain description string on
- * success, throws a typed `TOOL` {@link import('./errors.js').ToolboxError} on a malformed call
- * or an unknown tool name.
+ * The universal tool-handler contract: the Tool door holds the call args to
+ * {@link import('./shapers.js').describeToolShape}, refusing a malformed call with a `ToolError`
+ * carrying code `ARGUMENTS`. The handler returns the plain description on success, and throws a typed
+ * `TOOL` {@link import('./errors.js').ToolboxError} that lists the registered names on an unknown
+ * tool name.
  *
  * @param tools - The `ToolManagerInterface` (`@orkestrel/tool`) whose registered tools this
  *   tool can describe
@@ -631,20 +677,19 @@ export declare function createDescribeTool(tools: ToolManagerInterface): ToolInt
  * `@orkestrel/contract`'s `samplesToSchema` (tuned by {@link import('./types.js').EndpointToolOptions}'s
  * `format` / `enum`), wrapping a non-object root as `{ value: <schema> }` through `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`'s `schemaToShape` compiles it once (through `createContract`) into a
- * `ContractInterface` whose `.parse` runs on every call's `args` before `definition.execute` — a
+ * ({@link import('./types.js').EndpointToolOptions.strict} `true`), the enforced contract: the Tool
+ * door converts it through `@orkestrel/contract`'s lenient `schemaToShape` and compiles it on the
+ * first call, then runs on every call's `args` before `definition.execute` — 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.execute` receives the coerced value (for example `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').ToolboxError} carrying the compiled contract's
- * structured `explain` faults, and `definition.execute` 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`, the tool's `execute` passes through the model-supplied `args` to
- * `definition.execute` without re-validation — the raw-passthrough opt-out. The execution context
+ * string slot arrives as `'7'`), not the raw call value. A call whose `args` carries a key outside
+ * the closed inferred schema, misses a required key, or holds a value not coercible to its slot's
+ * type throws a `ToolError` with code `ARGUMENTS` (`@orkestrel/tool`) carrying `context.faults`, and
+ * `definition.execute` is never called. `format` annotations are never asserted (see
+ * {@link import('./types.js').EndpointToolOptions.strict}). With
+ * `strict: false`, the tool's `execute` passes through the model-supplied `args` to
+ * `definition.execute` without validation — the raw-passthrough opt-out. The execution context
  * the tool's `execute` receives reaches `definition.execute` unchanged whichever way `args` are
  * handled, so a handler that reads `context.signal` observes the caller's cancellation. Either way,
  * the definition's return flows back as the tool call's plain result; a throw propagates uncaught,
@@ -653,7 +698,7 @@ export declare function createDescribeTool(tools: ToolManagerInterface): ToolInt
  *
  * @param definition - The endpoint's identity, non-empty samples, and local handler (see
  *   {@link import('./types.js').EndpointDefinition})
- * @param options - Construction-time inference tuning and the validate opt-out (see
+ * @param options - Construction-time inference tuning and the strict opt-out (see
  *   {@link import('./types.js').EndpointToolOptions})
  * @returns A `ToolInterface` named `definition.name`
  *
@@ -686,7 +731,7 @@ export declare function createDescribeTool(tools: ToolManagerInterface): ToolInt
  * 	name: 'lookupUser',
  * 	arguments: { id: true, name: 'Ada' },
  * })
- * // rejected.error -> the TOOL ToolboxError message
+ * // rejected.error -> the ARGUMENTS ToolError message, which names `id`
  * ```
  */
 export declare function createEndpointTool(definition: EndpointDefinition, options?: EndpointToolOptions): ToolInterface;
@@ -697,14 +742,13 @@ export declare function createEndpointTool(definition: EndpointDefinition, optio
  * {@link createEndpointTool}, wraps one concrete endpoint).
  *
  * @remarks
- * The universal tool-handler contract: validates the call args against
+ * The universal tool-handler contract: the Tool door holds the call args to
  * {@link import('./shapers.js').inferToolShape} (`samples` non-empty, `format` / `enum` optional
- * booleans, `candidates` an optional array), infers a schema through `@orkestrel/contract`'s
+ * booleans, `candidates` an optional array), refusing malformed args with a `ToolError` carrying code
+ * `ARGUMENTS`. The handler infers a schema through `@orkestrel/contract`'s
  * `samplesToSchema`, wraps a non-object root as `{ value: <schema> }` through `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').ToolboxError}.
+ * resulting parameters record.
  *
  * 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
@@ -719,18 +763,14 @@ export declare function createEndpointTool(definition: EndpointDefinition, optio
  * normalizing parse accept this value", that is 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, a `valid: true` entry is
- * always also `coercible: true`. `@orkestrel/contract`'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, because
- * 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 each of them
+ * always also `coercible: true`. `faults` is `checker.audit(candidate)`, which reports against `is`'s
+ * strictness: a strictly-invalid but coercible candidate (`7` against a string slot) yields
+ * `{ valid: false, coercible: true, faults: [{ reason: 'type', ... }] }`, so every invalid candidate
+ * names why, an undeclared key included. `checker.is` / `.parse` / `.audit` are all total over
+ * JSON-safe input — a JSON-safe hostile candidate (a `__proto__`-carrying object, deeply nested data) reaches each of them
  * and yields a bounded, non-throwing per-candidate verdict; a non-JSON-safe candidate (for example 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').ToolboxError} a malformed `samples`/`format`/`enum` throws,
+ * throwing-getter `Proxy`) never reaches the checker at all — the Tool door refuses the whole call
+ * with the same `ToolError` a malformed `samples`/`format`/`enum` throws,
  * with no per-candidate verdict produced.
  *
  * @param options - Advertised `name` / `description` overrides (see
@@ -791,8 +831,9 @@ export declare function createMemoryDefinitionStore(): DefinitionStoreInterface;
  * and blocks until the addressed terminal answers, returning the resolved values record.
  *
  * @remarks
- * The universal tool-handler contract: validates the call args against
- * {@link import('./shapers.js').promptToolShape}, parses the call's schema through
+ * The universal tool-handler contract: the Tool door holds the call args to
+ * {@link import('./shapers.js').promptToolShape}, refusing a malformed call with a `ToolError`
+ * carrying code `ARGUMENTS`. The handler parses the call's schema through
  * `@orkestrel/form`, constructs the live form, and passes it to `TerminalManagerInterface.ask`.
  * `from` is fixed at construction
  * ({@link import('./types.js').PromptToolOptions.from}) — never read from the model-supplied
@@ -800,7 +841,7 @@ export declare function createMemoryDefinitionStore(): DefinitionStoreInterface;
  * `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
  * {@link import('./errors.js').ToolboxError}; an expired form re-surfaces as `EXPIRE`; an
  * unknown `to` (or any other `TerminalError`) re-surfaces as `TOOL`, naming the unknown terminal
- * and how many brokers the manager holds (`manager.count`). A schema `parseForm` refuses — an
+ * and the mounted terminals the manager's refusal lists, encoded and bounded. A schema `parseForm` refuses — an
  * unknown control, a duplicate field name, a `'select'` or `'checkbox'` field without usable
  * `choices` — throws a typed `TOOL` error up front, so a malformed schema never parks as a form
  * nobody can answer.
@@ -831,8 +872,10 @@ export declare function createPromptTool(options: PromptToolOptions): ToolInterf
  * single-tool-many-operations shape).
  *
  * @remarks
- * The universal tool-handler contract: validates the call args against
- * {@link import('./shapers.js').relationToolShape}, resolves the addressed
+ * The universal tool-handler contract: the Tool door holds the call args to
+ * {@link import('./shapers.js').relationToolShape}, refusing malformed args with a `ToolError`
+ * carrying code `ARGUMENTS`. A `limit` or `depth` that is not a positive safe integer throws `TOOL` at
+ * construction, and a row `'load'` misses is an explicit `null`. The handler resolves the addressed
  * {@link import('@orkestrel/relation').RelationManagerInterface} — an explicit `manager` field
  * must match a key of {@link import('./types.js').RelationToolOptions.managers}, an omitted one
  * resolves to the sole registered manager, either miss throwing a typed `TOOL`
@@ -961,7 +1004,12 @@ export declare function createWorkflowFunctions(runner: WorkflowRunnerInterface,
  * It is also the propagation carrier
  * {@link createAgentFunction} binds onto a wrapped agent's `context.tools`: because a tool
  * handler receives only the model-supplied `args`, the immutable lineage is closed over at bind
- * time. The authored target is appended and its zero-based depth derived from workflow tags.
+ * time. The authored target is appended and its zero-based depth derived from workflow tags. That
+ * bound tool wraps the containing workflow's id over no phases, and its empty-args call always
+ * refuses as a cycle before the runner, so the wrapper never runs.
+ *
+ * `parameters` advertises the flat form alone, so the tool is built `strict: false` and its handler
+ * runs the door ({@link import('./helpers.js').requireToolCall}) on the form the arguments take.
  *
  * **Widened authoring surface (additive — the canonical contract and runner stay strict and
  * unchanged).** A 2B model reliably calls the tool but cannot reliably emit the full nested
@@ -976,9 +1024,11 @@ export declare function createWorkflowFunctions(runner: WorkflowRunnerInterface,
  *   super-set.
  *
  * The universal tool-handler contract: returns the plain run summary
- * (`{ status, count, durable?, fault? }`) on success, throws a typed `ToolboxError` on Toolbox
- * boundary failures — malformed authored args (`TOOL`), or an over-deep / cyclic nested run
- * (`DEPTH`) — and preserves genuine runner `WorkflowError`s. The `ToolManagerInterface` isolates every throw into the canonical tool result's
+ * (`{ status, count, durable?, fault? }`) on success. Malformed authored args throw a `ToolError`
+ * with code `ARGUMENTS` (`@orkestrel/tool`) whose text lists what to correct, carrying
+ * `context.faults`; a wrapped definition the strict contract refuses throws `TOOL`, and an over-deep
+ * or cyclic nested run throws `DEPTH`. Genuine runner `WorkflowError`s are preserved, including
+ * `SCHEDULE` for a target with no task. The `ToolManagerInterface` isolates every throw into the canonical tool result's
  * top-level `error`, so nothing escapes the run. `options.lineage` is the propagation carrier
  * across a workflow → agent → workflow chain. Opaque `functions` remain host leaves; raw `agents`
  * are contextually adapted through {@link createWorkflowFunctions}; native checkpoint persistence
@@ -1048,17 +1098,20 @@ export declare function createWorkflowTool(definition: WorkflowDefinition, runne
  * active workspace by id (lenient — an unknown id is a no-op reporting `switched: false`, never a
  * throw).
  *
- * No-active rule (the ergonomic seam): a writing op (write / splice / prepend / append / move /
- * remove / replace) run when `manager.active` is `undefined` auto-creates and activates a default
- * workspace (`manager.add()`) so the model can start writing; a pure-read op (read / list /
- * has / search) against no active workspace returns the empty result (`undefined` / `[]` /
- * `false`), never creating one and never throwing.
- *
- * The handler conforms to the universal tool-handler contract: it `contract.parse`s
- * the args, throws a `TOOL` `ToolboxError` when no operation arm matched (a malformed / unknown
- * operation), else `switch`es on `op.operation` and returns the plain result — letting a
- * `WorkspaceError` raised by the live workspace (`MISSING` / `MODALITY` / `PATTERN` / `RANGE`)
- * propagate uncaught. The range edit is the flat `'splice'` op: its flat caret integers are
+ * No-active rule (the ergonomic seam): an op that can create the file it names (write / prepend /
+ * append) run when `manager.active` is `undefined` auto-creates and activates a default workspace
+ * (`manager.add()`) so the model can start writing; an op that edits a file that must already exist
+ * (splice / move / remove / replace) refuses with a `TOOL` `ToolboxError` and creates none; a
+ * pure-read op (read / list / has / search) against no active workspace returns the empty result
+ * (`null` / `[]` / `false`), never creating one and never throwing.
+ *
+ * The Tool door enforces the operation union through `contract`, repairing lossless scalar leaves
+ * and refusing malformed args with a `ToolError` carrying code `ARGUMENTS`. A selected operation
+ * reports its own faults; an unknown operation reports a bounded summary of alternatives.
+ * The handler then `switch`es on `op.operation` and returns the plain result
+ * — letting a `WorkspaceError` raised by the live workspace (`MISSING` / `MODALITY` / `PATTERN` /
+ * `RANGE`) propagate uncaught. `read` returns `null` for a path that holds no text, because JSON
+ * tells that from an empty file. The range edit is the flat `'splice'` op: its flat caret integers are
  * reassembled into a `Range` (`@orkestrel/workspace`) by `rangeOf` and fed to the workspace's
  * ranged `write`.
  *
@@ -1167,12 +1220,15 @@ export declare interface DatabaseDefinitionRow {
  * and keeps the row type flat (`definition` reads back as `unknown`).
  *
  * - **`set(definition)` upserts under the definition's own `id`** (no separate id param) — it
- *   writes the row `{ id: definition.id, definition }`.
+ *   writes the row `{ id: definition.id, definition }`, and first refuses what `get` would refuse,
+ *   so no row is written that `get` cannot read.
  * - **`get(id)` resolves the stored definition for an id**, narrowing the opaque JSON column back
  *   to a {@link DatabaseDefinition} ({@link import('../validators.js').isDatabaseDefinition} — the
- *   boundary narrow for an untrusted storage read), or `undefined` if none is stored
- *   or the stored blob is malformed.
- * - **`delete(id)` drops a definition by id**; an absent id is a no-op (no throw).
+ *   boundary narrow for an untrusted storage read), or `undefined` if no row is stored. A present
+ *   row whose blob is malformed or names another id throws, because reading it as absent would let
+ *   a later `set` overwrite it.
+ * - **`delete(id)` drops a definition by id** without reading it, the remedy for a refused row; an
+ *   absent id is a no-op (no throw).
  *
  * The public surface is exactly `get` / `set` / `delete` — no extra members (the method
  * bijection with {@link DefinitionStoreInterface}).
@@ -1201,8 +1257,8 @@ export declare class DatabaseDefinitionStore implements DefinitionStoreInterface
      * {@link DatabaseDefinition}.
      *
      * @param id - The database id to read
-     * @returns The stored {@link DatabaseDefinition}, or `undefined` when none is stored or the
-     *   stored blob is malformed
+     * @returns The stored {@link DatabaseDefinition}, or `undefined` when no row is stored
+     * @throws {ToolboxError} Thrown with code `DATABASE` when the row's blob is malformed or names another id, with the faults under `context.faults`
      */
     get(id: string): Promise<DatabaseDefinition | undefined>;
     /**
@@ -1210,6 +1266,7 @@ export declare class DatabaseDefinitionStore implements DefinitionStoreInterface
      *
      * @param definition - The config to persist; its own `id` is the row key (no separate id param)
      * @returns A promise settling after the row is written
+     * @throws {ToolboxError} Thrown with code `DATABASE` before any write when the definition fails the guard `get` reads, with the faults under `context.faults`
      */
     set(definition: DatabaseDefinition): Promise<void>;
     /**
@@ -1327,7 +1384,8 @@ export declare class DatabaseResolver {
  *   constructed with, used when a written row lacks its primary key. Omitted delegates to the
  *   database's default generator.
  * - `limit` — the `'records'` row cap — through {@link import('./helpers.js').clampQuery}
- *   — enforce when a call's `query.limit` is omitted or exceeds it. Defaults to
+ *   — enforce when a call's `query.limit` is omitted or exceeds it. A positive safe integer; any
+ *   other value throws at construction. Defaults to
  *   {@link import('./constants.js').DATABASE_TOOL_LIMIT}.
  * - `timeout` — a nonnegative safe-integer number of milliseconds. A fresh
  *   `AbortSignal.timeout(timeout)` is passed only to table operations whose current database API
@@ -1469,13 +1527,71 @@ operation: LiteralShape<readonly ["destroy"]>;
 id: StringShape;
 }, false>]>;
 
+/**
+ * Holds the compiled {@link import('./shapers.js').definitionShape}, whose `audit` fills the faults a
+ * refused stored definition carries.
+ *
+ * @example
+ * ```ts
+ * import { definitionContract } from '@orkestrel/toolbox'
+ *
+ * definitionContract.audit({ id: 'shop', driver: 'memory', tables: {}, keys: {} })
+ * // [{ reason: 'extra', path: ['keys'] }]
+ * ```
+ */
+export declare const definitionContract: ContractInterface<Readonly<{
+id: string;
+driver: string;
+tables: {
+readonly [k: string]: Readonly<{
+columns: {
+readonly [k: string]: "boolean" | "integer" | "number" | "string" | Readonly<{
+primitive: "boolean" | "integer" | "number" | "string";
+} & {
+optional?: boolean;
+}>;
+};
+} & {}>;
+};
+} & {
+primary?: {
+readonly [k: string]: string;
+};
+indexes?: {
+readonly [k: string]: readonly (readonly string[])[];
+};
+version?: number;
+}>>;
+
+/**
+ * Describes a stored {@link import('./types.js').DatabaseDefinition} exactly: the owned record
+ * {@link import('./stores/DatabaseDefinitionStore.js').DatabaseDefinitionStore} reads and writes.
+ *
+ * @remarks
+ * {@link import('./validators.js').isDatabaseDefinition} is the guard the store runs, and a lockstep
+ * test holds it to this shape. The compiled contract fills a refusal's faults.
+ */
+export declare const definitionShape: ObjectShape<    {
+id: StringShape;
+driver: StringShape;
+tables: ObjectShape<Record<never, never>, ObjectShape<    {
+columns: ObjectShape<Record<never, never>, UnionShape<readonly [LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<    {
+primitive: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
+optional: OptionalShape<BooleanShape>;
+}, false>]>>;
+}, false>>;
+primary: OptionalShape<ObjectShape<Record<never, never>, StringShape>>;
+indexes: OptionalShape<ObjectShape<Record<never, never>, ArrayShape<ArrayShape<StringShape>>>>;
+version: OptionalShape<NumberShape>;
+}, false>;
+
 /**
  * Represents the point-access persistence seam for {@link DatabaseDefinition} configs — the twin of
  * `@orkestrel/terminal`'s `TerminalStoreInterface`, storing a database's config-only blueprint
  * rather than a live handle. Every primitive is async; `delete` of an absent id is a no-op.
  */
 export declare interface DefinitionStoreInterface {
-    /** Resolves the persisted definition for `id`, or `undefined` when none is stored. */
+    /** Resolves the persisted definition for `id`, or `undefined` when none is stored; a present row an implementation cannot read as a definition throws. */
     get(id: string): Promise<DatabaseDefinition | undefined>;
     /** Inserts or replaces a definition under its own `id`, taking no separate id argument. */
     set(definition: DatabaseDefinition): Promise<void>;
@@ -1521,6 +1637,40 @@ export declare const DESCRIBE_TOOL_NAME = "describe";
  */
 export declare const DESCRIBE_TOOL_SUMMARY = "Return the full description of a named registered tool.";
 
+/**
+ * Describes a stored definition that names another id, naming the id it holds and the id it must hold.
+ *
+ * @param id - The database id the row is stored under
+ * @param held - The id the stored definition names
+ * @returns The refusal message
+ *
+ * @example
+ * ```ts
+ * import { describeDefinitionMismatch } from '@src/core'
+ *
+ * describeDefinitionMismatch('shop', 'other')
+ * // 'database "shop" holds a definition that names id "other"; its id must be "shop"; ...'
+ * ```
+ */
+export declare function describeDefinitionMismatch(id: string, held: string): string;
+
+/**
+ * Describes a stored definition this package refuses to read, naming its first fault and the remedy.
+ *
+ * @param id - The database id the row is stored under
+ * @param faults - The refused definition's faults
+ * @returns The refusal message
+ *
+ * @example
+ * ```ts
+ * import { describeDefinitionRefusal } from '@src/core'
+ *
+ * describeDefinitionRefusal('shop', [{ reason: 'extra', path: ['keys'] }])
+ * // 'database "shop" holds a definition this version refuses (extra key "keys" at the root; ...'
+ * ```
+ */
+export declare function describeDefinitionRefusal(id: string, faults: readonly AuditFault[]): string;
+
 /**
  * Represents the flat args {@link import('./factories.js').createDescribeTool} accepts — the
  * registered tool `name` whose full `description` a model wants back.
@@ -1552,13 +1702,13 @@ name: StringShape;
  * @remarks
  * `samples` must be non-empty — {@link import('./factories.js').createEndpointTool} throws a
  * typed `TOOL` {@link import('./errors.js').ToolboxError} at construction when it is empty,
- * because an empty sample set cannot infer a schema. By default ({@link EndpointToolOptions.validate}
+ * because an empty sample set cannot infer a schema. By default ({@link EndpointToolOptions.strict}
  * `true`) `execute` receives the parsed, normalized args record — a copy of the model-supplied
  * `args` with each scalar coerced to its inferred type (for example 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 `execute` at all (see
- * {@link EndpointToolOptions.validate}). With
- * `validate: false`, `execute` receives the model-supplied `args` verbatim (raw passthrough, never
+ * a call with an undeclared key, a missing required key, or a non-coercible value never reaches
+ * `execute` at all (see {@link EndpointToolOptions.strict}). With
+ * `strict: false`, `execute` receives the model-supplied `args` verbatim (raw passthrough, never
  * checked against the inferred schema). Either way `execute`'s return flows back as the tool
  * call's result; a throw propagates uncaught, isolated by the `ToolManagerInterface`
  * (`@orkestrel/tool`) into the canonical error envelope. When `samples` are non-object values,
@@ -1584,7 +1734,8 @@ export declare interface EndpointDefinition {
  * `ToolContext` second parameter, and the same `Promise<unknown> | unknown` return. A handler that
  * declares `args` alone still satisfies the type, the way a function declaring fewer parameters
  * than its contract does, so an endpoint definition written against the argument alone keeps
- * typechecking and reads no signal.
+ * typechecking and reads no signal. Under the default door `args` is a null-prototype record, on
+ * which `String(args)` and `args.hasOwnProperty()` throw; read it with `Object.hasOwn`.
  */
 export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>, context: ToolContext) => Promise<unknown> | unknown;
 
@@ -1595,32 +1746,28 @@ export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>,
  *
  * @remarks
  * `format` / `enum` default to `false`, matching `@orkestrel/contract`'s own
- * `ValueToSchemaOptions` defaults. `validate` defaults to `true`: the schema
- * `createEndpointTool` advertises as `parameters` (`samplesToSchema` and `schemaToObject`) is
- * compiled once at construction (through `@orkestrel/contract`'s `schemaToShape`) into a
- * `ContractInterface` used to `parse` every call's `args` before `execute` runs — a normalizing
+ * `ValueToSchemaOptions` defaults. `strict` mirrors `@orkestrel/tool`'s `ToolOptions.strict` and
+ * defaults to `true`: the schema `createEndpointTool` advertises as `parameters` (`samplesToSchema`
+ * and `schemaToObject`) is converted by the Tool door through `@orkestrel/contract`'s lenient
+ * `schemaToShape` on the first call, and runs on every call's `args` before `execute` — 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 `execute`
  * receives the coerced values (for example `7` sent for a string slot arrives at `execute` 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').ToolboxError}
- * carrying the structured `explain` faults, and `execute` 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 `execute` runs (the same leniency `@orkestrel/contract`'s own `parse`
- * grants a closed object generally), so `execute` may see fewer keys than the caller sent. Set
- * `validate: false` when the endpoint's own handler validates its arguments, or when `samples`
- * under-describe the real contract and the normalizing coercion would corrupt a call: the tool's
- * `execute` then passes the model-supplied `args` to the handler unchanged, unchecked and
- * unstripped.
+ * the raw call args. A call that carries a key the inferred (closed, `additionalProperties: false`)
+ * schema does not declare, misses a required key, or holds a value not coercible to its slot's type
+ * throws a `ToolError` with code `ARGUMENTS` (`@orkestrel/tool`) carrying `context.faults`, and
+ * `execute` is never called. Beyond that, 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. Set
+ * `strict: false` when the endpoint's own handler validates its arguments, or when `samples`
+ * under-describe the real contract and the door would refuse a real call: the tool's `execute` then
+ * passes the model-supplied `args` to the handler unchanged, unchecked and unstripped.
  */
 export declare interface EndpointToolOptions {
     readonly format?: boolean;
     readonly enum?: boolean;
-    readonly validate?: boolean;
+    readonly strict?: boolean;
 }
 
 /**
@@ -1692,6 +1839,9 @@ export declare function extendLineage(lineage: WorkflowLineage, tag: string): Wo
 /** Describes the flat dot-path relation include list, expanded through {@link import('./helpers.js').expandInclude}. */
 export declare const includeShape: OptionalShape<ArrayShape<StringShape>>;
 
+/** Describes a {@link import('./types.js').DatabaseDefinition}'s `indexes` map — table name to its index column groups. */
+export declare const indexesShape: ObjectShape<Record<never, never>, ArrayShape<ArrayShape<StringShape>>>;
+
 /**
  * Holds the schema-inference protocol {@link import('./factories.js').createInferTool} advertises —
  * the required `samples`, the optional `format`, `enum`, and `candidates` arguments, and a worked
@@ -1774,8 +1924,8 @@ export declare interface InferToolOptions {
  * 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').ToolboxError}. When
+ * `samples` requires at least one element (`min: 1`) — the Tool door refuses an empty array with
+ * a `ToolError` carrying code `ARGUMENTS` (`@orkestrel/tool`). 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
@@ -1805,24 +1955,54 @@ export declare function isAgentFunction(value: unknown): value is AgentFunction;
 export declare const isColumnPrimitive: Guard<ColumnPrimitive>;
 
 /**
- * Narrows an unknown value to a {@link ColumnSpec}.
+ * Narrows an unknown value to a {@link ColumnSpec} — a bare {@link ColumnPrimitive}, or exactly
+ * `{ primitive, optional? }`.
  *
  * @param value - The value to inspect
- * @returns True if `value` is a valid {@link ColumnPrimitive} shorthand or a `{ primitive, optional }` record with a valid `primitive`; false otherwise
+ * @returns True if `value` is a valid shorthand or an exact record with a valid `primitive`; false otherwise
  */
-export declare function isColumnSpec(value: unknown): value is ColumnSpec;
+export declare const isColumnSpec: Guard<ColumnSpec>;
 
 /**
- * Narrows an unknown value to a {@link DatabaseDefinition} — a non-empty `id` and `driver`, a
- * `tables` record whose every value is `{ columns: record of valid ColumnSpec }`, plus optional
- * `primary`, `indexes`, and finite `version` schema configuration. The boundary guard a
- * {@link import('./types.js').DefinitionStoreInterface} applies to an untrusted persisted blob
- * before trusting it as a definition (never an `as`).
+ * Narrows an unknown value to exactly a {@link DatabaseDefinition} — a non-empty `id` and `driver`,
+ * a {@link TableSpec}, plus optional `primary`, `indexes`, and finite `version` schema configuration,
+ * refusing every other key. The boundary guard a {@link import('./types.js').DefinitionStoreInterface}
+ * applies to an untrusted persisted blob before trusting it as a definition (never an `as`).
+ *
+ * @remarks
+ * A lockstep test holds this guard to {@link import('./shapers.js').definitionShape}.
  *
  * @param value - The value to inspect
  * @returns True if `value` is a complete {@link DatabaseDefinition}; false otherwise
  */
-export declare function isDatabaseDefinition(value: unknown): value is DatabaseDefinition;
+export declare const isDatabaseDefinition: Guard<DatabaseDefinition>;
+
+/**
+ * Narrows an unknown value to an `IndexMap` (`@orkestrel/database`) — table name to its index
+ * groups, each group a nonempty list of nonempty column names.
+ *
+ * @param value - The value to inspect
+ * @returns True if every value is a list of such groups; false otherwise
+ */
+export declare function isIndexMap(value: unknown): value is IndexMap;
+
+/**
+ * Narrows an unknown value to a `PrimaryMap` (`@orkestrel/database`) — table name to a nonempty
+ * primary-key column name.
+ *
+ * @param value - The value to inspect
+ * @returns True if every value is a nonempty string; false otherwise
+ */
+export declare function isPrimaryMap(value: unknown): value is PrimaryMap;
+
+/**
+ * Narrows an unknown value to a {@link TableSpec} — table name to exactly `{ columns }`, each column
+ * a valid {@link ColumnSpec}.
+ *
+ * @param value - The value to inspect
+ * @returns True if `value` is a table layout; false otherwise
+ */
+export declare function isTableSpec(value: unknown): value is TableSpec;
 
 /**
  * Narrows an unknown caught value to a {@link ToolboxError}.
@@ -1862,6 +2042,26 @@ export declare function isWorkflowLineage(value: unknown): value is WorkflowLine
  */
 export declare const keyShape: UnionShape<readonly [ArrayShape<UnionShape<readonly [StringShape, NumberShape]>>, StringShape, NumberShape]>;
 
+/**
+ * Caps the complete text of a refusal at `FAULT_TEXT_LIMIT` characters, saying where it stopped.
+ *
+ * @remarks
+ * A refusal goes back to a model whose context window can be small. Use this where a message joins
+ * parts this package cannot bound one by one: a head beside a report, or an upstream error's text.
+ *
+ * @param text - The refusal text
+ * @returns The text unchanged when it fits, otherwise cut to the limit and well formed
+ *
+ * @example
+ * ```ts
+ * import { limitRefusal } from '@src/core'
+ *
+ * limitRefusal('send steps') // 'send steps'
+ * limitRefusal('x'.repeat(5000)).length // 2048
+ * ```
+ */
+export declare function limitRefusal(text: string): string;
+
 /** Describes which registered relation manager to address — omitted resolves to the sole registered manager. */
 export declare const managerShape: OptionalShape<StringShape>;
 
@@ -1883,8 +2083,8 @@ export declare const MAX_WORKFLOW_CHAIN = 8;
  * {@link import('../factories.js').createMemoryDefinitionStore} builds. It implements the same
  * {@link DefinitionStoreInterface} contract as
  * {@link import('./DatabaseDefinitionStore.js').DatabaseDefinitionStore}: this store copies on
- * write and on read; the table-backed store narrows an untrusted stored blob and reports
- * `undefined` for a malformed one.
+ * write and on read; the table-backed store narrows an untrusted stored blob and refuses a malformed
+ * one.
  *
  * @remarks
  * A plain `Map<string, DatabaseDefinition>` (the definition is already pure,
@@ -2002,6 +2202,9 @@ concurrency: OptionalShape<NumberShape>;
 bail: OptionalShape<LiteralShape<readonly [true, false]>>;
 }, false>;
 
+/** Describes a {@link import('./types.js').DatabaseDefinition}'s `primary` map — table name to its primary-key column. */
+export declare const primaryShape: ObjectShape<Record<never, never>, StringShape>;
+
 /**
  * Holds the form protocol {@link import('./factories.js').createPromptTool} advertises — the
  * required `to` and `schema`, how a field declares its control and its rules, and a worked
@@ -2135,10 +2338,11 @@ export declare const RELATION_TOOL_SUMMARY = "Traverse and edit relationships be
  *   manager when exactly one is registered, else throws a typed `TOOL`
  *   {@link import('./errors.js').ToolboxError} naming the registered manager keys.
  * - `limit` — the row cap `'find'` / `'links'` enforce when a call's `limit` is omitted or
- *   exceeds it. Defaults to {@link import('./constants.js').RELATION_TOOL_LIMIT}.
+ *   exceeds it. A positive safe integer; any other value throws at construction. Defaults to
+ *   {@link import('./constants.js').RELATION_TOOL_LIMIT}.
  * - `depth` — the max dot-path segment count `'load'` / `'find'`'s `include` paths may reach
- *   ({@link import('./helpers.js').expandInclude}). Defaults to
- *   {@link import('./constants.js').RELATION_TOOL_DEPTH}.
+ *   ({@link import('./helpers.js').expandInclude}). A positive safe integer; any other value throws
+ *   at construction. Defaults to {@link import('./constants.js').RELATION_TOOL_DEPTH}.
  * - `name` / `description` — advertised tool overrides; default to
  *   {@link import('./constants.js').RELATION_TOOL_NAME} / {@link import('./constants.js').RELATION_TOOL_DESCRIPTION}.
  */
@@ -2197,6 +2401,89 @@ key: UnionShape<readonly [StringShape, NumberShape]>;
 relation: StringShape;
 }, false>]>;
 
+/**
+ * Renders the candidates a refusal offers, each encoded and length-capped and at most
+ * `REFUSAL_LIST_LIMIT` of them named, so a long or multiline name cannot fake or balloon the message.
+ *
+ * @param names - The candidates to offer
+ * @returns The encoded candidates joined with `, `, empty when there are none
+ *
+ * @example
+ * ```ts
+ * import { renderCandidates } from '@src/core'
+ *
+ * renderCandidates(['read', 'list']) // '"read", "list"'
+ * ```
+ */
+export declare function renderCandidates(names: readonly string[]): string;
+
+/**
+ * Reads the active workspace for an operation that edits a file that must already exist, or refuses.
+ *
+ * @param manager - The manager the workspace tool drives
+ * @param operation - The operation that needs an active workspace
+ * @returns The active workspace
+ * @throws {ToolboxError} Thrown with code `TOOL` when no workspace is active, and creates none
+ *
+ * @example
+ * ```ts
+ * import { createWorkspaceManager } from '@orkestrel/workspace'
+ * import { requireActiveWorkspace } from '@src/core'
+ *
+ * const manager = createWorkspaceManager()
+ * const workspace = manager.add()
+ * requireActiveWorkspace(manager, 'remove') === workspace // true
+ * ```
+ */
+export declare function requireActiveWorkspace(manager: WorkspaceManagerInterface, operation: string): WorkspaceInterface;
+
+/**
+ * Reads a call's arguments through a compiled contract, or refuses them with what to send.
+ *
+ * @remarks
+ * Uses the contract admission door and translates refusals to tool errors.
+ * Tools with object and union roots enforce `createTool`'s `contract` and use this helper to type
+ * the parsed arguments. The workflow tool uses this door under `strict: false` because it accepts
+ * several authoring forms while advertising the flat form.
+ *
+ * @param contract - The compiled contract of the arguments
+ * @param value - The arguments the call sent
+ * @returns The admitted value, which may retain input identity under a union
+ * @throws {import('@orkestrel/tool').ToolError} Thrown with code `ARGUMENTS`, carrying `context.faults` when the arguments could be read
+ *
+ * @example
+ * ```ts
+ * import { createContract, numberShape, objectShape } from '@orkestrel/contract'
+ * import { requireToolCall } from '@src/core'
+ *
+ * const contract = createContract(objectShape({ amount: numberShape() }))
+ * requireToolCall(contract, { amount: '3' }) // { amount: 3 }
+ * requireToolCall(contract, { amount: 3, extra: 1 }) // throws ToolError ('ARGUMENTS')
+ * ```
+ */
+export declare function requireToolCall<T>(contract: ContractInterface<T>, value: unknown): T;
+
+/**
+ * Picks the effective value of a positive numeric tool option: the configured value when it is a
+ * positive safe integer, and the fallback when it is omitted.
+ *
+ * @param value - The configured option, or `undefined`
+ * @param fallback - The default an omitted option takes
+ * @param subject - The name the refusal gives the option
+ * @returns The effective value
+ * @throws {ToolboxError} Thrown with code `TOOL` when `value` is present and is anything else, because `NaN` as a bound passes every comparison
+ *
+ * @example
+ * ```ts
+ * import { resolveBound } from '@src/core'
+ *
+ * resolveBound(undefined, 100, 'database limit') // 100
+ * resolveBound(25, 100, 'database limit') // 25
+ * resolveBound(0, 100, 'database limit') // throws ToolboxError ('TOOL')
+ * ```
+ */
+export declare function resolveBound(value: number | undefined, fallback: number, subject: string): number;
+
 /**
  * Picks the effective row limit a tool reads with — the requested count when it sits inside the
  * cap, the cap when it exceeds it, and `0` when either falls below zero.
@@ -2249,7 +2536,21 @@ export declare function resolveRelationManager(managers: Readonly<Record<string,
 export declare function resolveRelationModel(manager: RelationManagerInterface, name: string): ModelInterface;
 
 /**
- * Resolves an owned workflow input through the supplied flat or draft contracts.
+ * Resolves an owned workflow input through the supplied flat or draft contracts, or refuses it with
+ * what to send.
+ *
+ * @remarks
+ * Empty input is the wrapped definition. A `phases` key with no `steps` key takes the draft form,
+ * and everything else takes the advertised flat form, so a blob carrying both keys refuses `phases`
+ * as undeclared rather than ignoring it, and a blob carrying neither is told to send `steps`.
+ *
+ * @param owned - The call's owned JSON arguments
+ * @param definition - The wrapped definition empty input runs
+ * @param steps - The compiled flat form
+ * @param draft - The compiled draft form
+ * @returns The definition the input resolves to
+ * @throws {import('@orkestrel/tool').ToolError} Thrown with code `ARGUMENTS` when the chosen form refuses the input, carrying `context.faults`
+ *
  * @example
  * ```ts
  * import { createContract } from '@orkestrel/contract'
@@ -2260,7 +2561,7 @@ export declare function resolveRelationModel(manager: RelationManagerInterface,
  * resolveWorkflowTarget({}, definition, steps, createWorkflowDraftContract()) // definition
  * ```
  */
-export declare function resolveWorkflowTarget(owned: JSONRecord, definition: WorkflowDefinition, steps: ContractInterface<WorkflowSteps>, draft: ContractInterface<WorkflowDraft>): WorkflowDefinition | undefined;
+export declare function resolveWorkflowTarget(owned: JSONRecord, definition: WorkflowDefinition, steps: ContractInterface<WorkflowSteps>, draft: ContractInterface<WorkflowDraft>): WorkflowDefinition;
 
 /** Describes a loose row — a flat object of column name to JSON value. */
 export declare const rowShape: ObjectShape<Record<never, never>, JSONShape>;
@@ -2362,7 +2663,7 @@ export declare interface TaskDraft {
     readonly behavior?: string;
     /** Holds the extra attempts after the first on failure (a non-negative integer); persisted with the workflow. */
     readonly retries?: number;
-    /** Holds the per-attempt deadline in milliseconds (`0..MAX_TIMER_MS`); persisted with the workflow. */
+    /** Holds the per-attempt deadline in milliseconds (`1..MAX_TIMER_MS`); persisted with the workflow, and omitted for no deadline. */
     readonly timeout?: number;
 }
 
@@ -2413,9 +2714,10 @@ export declare class ToolboxError extends Error {
  * thrown, typed, code-bearing error, never a `{ error }` return.
  *
  * @remarks
- * `TOOL` — malformed calls and package-owned resolution or configuration failures, including
- * unknown tools, terminals, databases, drivers, relation managers, or models; invalid prompt
- * choices or include paths; disabled readonly mutations; and invalid infer/endpoint inputs.
+ * `TOOL` — package-owned resolution or configuration failures, including unknown tools, terminals,
+ * databases, drivers, relation managers, or models; invalid prompt choices or include paths;
+ * disabled readonly mutations; and invalid construction options. Malformed call arguments are a
+ * `ToolError` with code `ARGUMENTS` (`@orkestrel/tool`), carrying `context.faults`.
  * `DEPTH` — the delegation would exceed {@link import('./constants.js').AGENT_TOOL_DEPTH}, or
  * the resolved agent is already an ancestor (a cycle).
  * `DEADLOCK` — an `ask` call ({@link import('./factories.js').createPromptTool}) would form a
@@ -2426,7 +2728,9 @@ export declare class ToolboxError extends Error {
  * because the prompt id is unknown or already settled, or the terminal manager rejected the
  * answer.
  * `DATABASE` — a typed `@orkestrel/database` failure (`DatabaseError`), re-surfaced with the
- * granular {@link import('@orkestrel/database').DatabaseErrorCode} carried in `context.code`.
+ * granular {@link import('@orkestrel/database').DatabaseErrorCode} carried in `context.code`, or a
+ * stored definition {@link import('./stores/DatabaseDefinitionStore.js').DatabaseDefinitionStore}
+ * refuses, carrying `context.faults`.
  * `RELATION` — a typed `@orkestrel/relation` failure (`RelationError`), re-surfaced with the
  * granular {@link import('@orkestrel/relation').RelationErrorCode} carried in `context.code`.
  */
@@ -2691,7 +2995,7 @@ export declare const WORKSPACE_TOOL_SUMMARY = "Read and edit files in a workspac
  * the edit / read arms target.
  */
 export declare type WorkspaceOperation = 
-/** Reads a whole text file's text by `path` from the active workspace (a binary / absent path — or no active workspace — yields no content). */
+/** Reads a whole text file's text by `path` from the active workspace (a binary / absent path — or no active workspace — yields `null`). */
     {
     readonly operation: 'read';
     readonly path: string;