@orkestrel/toolbox 0.0.10 → 0.0.12

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

@@ -14,6 +14,7 @@ import { Include } from '@orkestrel/relation';
 import { IndexMap } from '@orkestrel/database';
 import { JSONShape } from '@orkestrel/contract';
 import { KeyFunction } from '@orkestrel/database';
+import { LifecycleStatus } from '@orkestrel/workflow';
 import { LiteralShape } from '@orkestrel/contract';
 import { ModelInterface } from '@orkestrel/relation';
 import { NumberShape } from '@orkestrel/contract';
@@ -34,21 +35,20 @@ import { UnionShape } from '@orkestrel/contract';
 import { WorkflowDefinition } from '@orkestrel/workflow';
 import { WorkflowFault } from '@orkestrel/workflow';
 import { WorkflowFunction } from '@orkestrel/workflow';
-import { WorkflowFunctions } from '@orkestrel/workflow';
+import { WorkflowRegistry } from '@orkestrel/workflow';
 import { WorkflowResult } from '@orkestrel/workflow';
 import { WorkflowRunnerInterface } from '@orkestrel/workflow';
-import { WorkflowStatus } from '@orkestrel/workflow';
 import { WorkflowStoreInterface } from '@orkestrel/workflow';
 import { WorkspaceManagerInterface } from '@orkestrel/workspace';
 import { WorkspaceStoreInterface } from '@orkestrel/workspace';
 
 /**
- * The maximum nesting depth a delegation chain (agent tool → sub-agent → agent tool → …) may
+ * Holds the maximum nesting depth a delegation chain (agent tool → sub-agent → agent tool → …) may
  * reach — the bound {@link import('./factories.js').createAgentTool}'s depth/cycle guard
  * enforces.
  *
  * @remarks
- * Deliberately a SEPARATE constant from {@link MAX_WORKFLOW_DEPTH} (rather than the two guards
+ * Deliberately a SEPARATE constant from {@link MAX_WORKFLOW_CHAIN} (rather than the two guards
  * sharing one reference): the two guards bound DIFFERENT chains (workflow nesting vs. agent
  * delegation) that happen to share a value today, and keeping this bound decoupled means a
  * future change to one never silently shifts the other. Same numeric value by convention, not
@@ -57,34 +57,34 @@ import { WorkspaceStoreInterface } from '@orkestrel/workspace';
 export declare const AGENT_TOOL_DEPTH = 8;
 
 /**
- * The description {@link import('./factories.js').createAgentTool} advertises — a short guide
+ * Holds the description {@link import('./factories.js').createAgentTool} advertises — a short guide
  * covering the required task and optional provider, tools, and system overrides.
  */
 export declare const AGENT_TOOL_DESCRIPTION: string;
 
 /**
- * The name {@link import('./factories.js').createAgentTool} advertises by default — the key a
+ * Holds the name {@link import('./factories.js').createAgentTool} advertises by default — the key a
  * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
  */
 export declare const AGENT_TOOL_NAME = "agent";
 
 /**
- * The lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createAgentTool}
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createAgentTool}
  * advertises in place of {@link AGENT_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
  * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable via
+ * for the full teaching description; the full text stays retrievable through
  * {@link import('./factories.js').createDescribeTool}.
  */
 export declare const AGENT_TOOL_SUMMARY = "Delegate a task to a sub-agent and return its result; each call runs one sub-agent turn to completion. Call describe('agent') for the optional provider/tools/system overrides.";
 
-/** A contextual agent adapter carrying immutable metadata for Toolbox composition. */
+/** Represents a contextual agent adapter carrying immutable metadata for Toolbox composition. */
 export declare type AgentFunction = WorkflowFunction & {
     readonly category: 'agent';
     readonly lineage: WorkflowLineage;
 };
 
 /**
- * Options for {@link import('./factories.js').createAgentFunction} — the OPT-IN adapter that
+ * Represents the options for {@link import('./factories.js').createAgentFunction} — the OPT-IN adapter that
  * wraps a live `AgentInterface` (`@orkestrel/agent`) as an {@link AgentFunction} with immutable
  * lineage metadata and optional nested-workflow composition.
  *
@@ -103,27 +103,13 @@ export declare type AgentFunction = WorkflowFunction & {
 export declare interface AgentFunctionOptions {
     readonly runner?: WorkflowRunnerInterface;
     readonly lineage?: WorkflowLineage;
-    readonly functions?: WorkflowFunctions;
+    readonly functions?: WorkflowRegistry;
     readonly agents?: WorkflowAgents;
     readonly store?: WorkflowStoreInterface;
 }
 
 /**
- * The ancestry identifier of an agent in a run chain — `agent:<name>`.
- *
- * @remarks
- * The agent counterpart of {@link workflowTag}: {@link import('./factories.js').createAgentFunction}
- * / {@link import('./factories.js').createWorkflowTool} guard against re-entering an agent or
- * workflow already in the chain (this package's typed `DEPTH` `ToolboxError`). The
- * `agent:` namespace keeps it distinct from a same-string workflow id.
- *
- * @param name - The agent's identifier / registry name
- * @returns The namespaced ancestry tag (`agent:<name>`)
- */
-export declare function agentTag(name: string): string;
-
-/**
- * The FLAT args {@link import('./factories.js').createAgentTool} accepts — a delegated `task`
+ * Represents the FLAT args {@link import('./factories.js').createAgentTool} accepts — a delegated `task`
  * plus the minimal optional `AgentJobInput` (`@orkestrel/agent`) fields a caller may override
  * per-call.
  *
@@ -140,7 +126,7 @@ export declare interface AgentToolArguments {
 }
 
 /**
- * Options for {@link import('./factories.js').createAgentTool} — the sub-agent delegation
+ * Represents the options for {@link import('./factories.js').createAgentTool} — the sub-agent delegation
  * defaults, the nesting-depth / cycle guard bookkeeping, and the advertised tool overrides.
  *
  * @remarks
@@ -166,7 +152,7 @@ export declare interface AgentToolArguments {
  *   audit log rather than colliding). Omitted ⇒ no persistence from this tool.
  *
  * Conversation persistence for a delegated sub-agent has TWO independent seams, composable
- * together: this `store` slot persists EACH delegation's conversation individually, and/or an
+ * together: this `store` slot persists EACH delegation's conversation individually, and an
  * `AgentRegistryInterface` built with `AgentRegistryOptions.store` (`@orkestrel/agent`) backs
  * EVERY agent it builds — including ones built through this tool — with a store-backed
  * `ConversationManagerInterface` of its own. Neither is required; either or both may be used.
@@ -183,7 +169,7 @@ export declare interface AgentToolOptions {
 }
 
 /**
- * The shape of {@link import('./types.js').AgentToolArguments} —
+ * Describes the shape of {@link import('./types.js').AgentToolArguments} —
  * {@link import('./factories.js').createAgentTool}'s advertised `parameters`.
  *
  * @remarks
@@ -197,32 +183,32 @@ export declare const agentToolShape: ObjectShape<{
     system: OptionalShape<StringShape>;
 }, false>;
 
-/** The pending/answer protocol {@link import('./factories.js').createAnswerTool} advertises. */
+/** Holds the pending/answer protocol {@link import('./factories.js').createAnswerTool} advertises. */
 export declare const ANSWER_TOOL_DESCRIPTION: string;
 
 /**
- * The name {@link import('./factories.js').createAnswerTool} advertises by default — the key a
+ * Holds the name {@link import('./factories.js').createAnswerTool} advertises by default — the key a
  * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
  */
 export declare const ANSWER_TOOL_NAME = "answer";
 
 /**
- * The lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createAnswerTool}
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createAnswerTool}
  * advertises in place of {@link ANSWER_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
  * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable via
+ * for the full teaching description; the full text stays retrievable through
  * {@link import('./factories.js').createDescribeTool}.
  */
 export declare const ANSWER_TOOL_SUMMARY = "List forms addressed to this terminal, or answer one by id with a values record. Call describe('answer') for the required fields.";
 
 /**
- * Options for {@link import('./factories.js').createAnswerTool} — the live
+ * Represents the options for {@link import('./factories.js').createAnswerTool} — the live
  * {@link TerminalManagerInterface} (`@orkestrel/terminal`) to list / answer prompts through, the
  * terminal name `to`, and the advertised tool overrides.
  *
  * @remarks
  * - `manager` — the terminal manager whose `pending(to)` / `answer(to, id, values)` the tool's
- *   handler calls — `pending` lists the forms currently addressed to `to`, `answer` resolves
+ *   handler calls — `pending` lists the forms addressed to `to`, `answer` resolves
  *   one by `id`. A failed `answer` (`TerminalAnswerError`) re-surfaces as a typed
  *   `ANSWER` {@link import('./errors.js').ToolboxError}.
  * - `to` — the terminal identity this tool lists / answers prompts FOR.
@@ -237,7 +223,7 @@ export declare interface AnswerToolOptions {
 }
 
 /**
- * The shape of {@link import('./factories.js').createAnswerTool}'s call arguments — discriminated
+ * Describes the shape of {@link import('./factories.js').createAnswerTool}'s call arguments — discriminated
  * by `operation`: `'pending'` lists the forms addressed to this tool's terminal, while `'answer'`
  * resolves one by `id` with a complete `values` record.
  *
@@ -254,13 +240,26 @@ export declare const answerToolShape: UnionShape<readonly [ ObjectShape<{
 }, false>]>;
 
 /**
- * Clamp a `'records'` call's query to a row cap, and build the PROBE query the caller reads
+ * Represents the PROBE query and effective row limit {@link import('./helpers.js').clampQuery} returns.
+ *
+ * @remarks
+ * `limit` is the effective ceiling — `min(query?.limit ?? cap, cap)`, floored at `0`. `query`
+ * requests one row MORE than that, so a caller detects truncation from the returned row count
+ * without a separate `count` round trip.
+ */
+export declare interface ClampedQuery {
+    readonly query: QueryInput;
+    readonly limit: number;
+}
+
+/**
+ * Clamps a `'records'` call's query to a row cap, and builds the PROBE query the caller reads
  * with — the pure leaf {@link import('./factories.js').createDatabaseTool}'s `'records'` operation
  * uses to detect truncation without a separate `count` round trip.
  *
  * @remarks
- * The effective limit is `min(query?.limit ?? cap, cap)`, floored at `0` (so a caller can never
- * exceed the configured cap by supplying a larger `query.limit`). The returned probe query
+ * {@link resolveLimit} picks the effective limit, so a caller can never exceed the configured cap
+ * by supplying a larger `query.limit`, and can never drive it below `0`. The returned probe query
  * requests ONE MORE row than the effective limit (`limit: effective + 1`) — if storage returns
  * that many, the caller knows the true result was truncated (`rows.length > effective`) and slices
  * back down to `effective` before returning.
@@ -279,38 +278,50 @@ export declare const answerToolShape: UnionShape<readonly [ ObjectShape<{
  * @param cap - The row-count ceiling
  * @returns The PROBE query (`limit` bumped by one) and the effective `limit`
  */
-export declare function clampQuery(query: QueryInput | undefined, cap: number): Readonly<{
-    query: QueryInput;
-    limit: number;
-}>;
+export declare function clampQuery(query: QueryInput | undefined, cap: number): ClampedQuery;
 
-/** One column's declared type — a primitive shorthand, or `integer` for a whole-number `number`. */
-export declare type ColumnKind = 'string' | 'integer' | 'number' | 'boolean';
+/** Represents one column's declared primitive — a shorthand, or `integer` for a whole-number `number`. */
+export declare type ColumnPrimitive = 'string' | 'integer' | 'number' | 'boolean';
 
-/** A {@link import('./types.js').ColumnKind} literal — the leaf {@link columnSpecShape} wraps. */
-export declare const columnKindShape: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
-
-/** Compile one {@link ColumnSpec} into its `@orkestrel/database` column shape — the per-column leaf {@link expandTables} maps over. */
-export declare function columnShape(spec: ColumnSpec): ContractShape;
+/** Describes a {@link import('./types.js').ColumnPrimitive} literal — the leaf {@link columnSpecShape} wraps. */
+export declare const columnPrimitiveShape: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
 
 /**
- * One table column's spec — either a bare {@link ColumnKind} shorthand, or `{ type, optional }`
- * when the column may be absent from a row.
+ * Represents one table column's spec — either a bare {@link ColumnPrimitive} shorthand, or
+ * `{ primitive, optional }` when the column may be absent from a row.
  */
-export declare type ColumnSpec = ColumnKind | Readonly<{
-    type: ColumnKind;
+export declare type ColumnSpec = ColumnPrimitive | Readonly<{
+    primitive: ColumnPrimitive;
     optional?: boolean;
 }>;
 
-/** A {@link import('./types.js').ColumnSpec} — a bare {@link columnKindShape}, or `{ type, optional }`. */
+/** Describes a {@link import('./types.js').ColumnSpec} — a bare {@link columnPrimitiveShape}, or `{ primitive, optional }`. */
 export declare const columnSpecShape: UnionShape<readonly [ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
-    type: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
+    primitive: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
     optional: OptionalShape<BooleanShape>;
 }, false>]>;
 
 /**
- * Complete a {@link WorkflowDraft} into a strict {@link WorkflowDefinition} — synthesize any
- * MISSING `id` deterministically + positionally, and default any MISSING `name` to its
+ * Compiles one {@link ColumnSpec} into its `@orkestrel/database` column shape — the per-column leaf
+ * {@link expandTables} maps over.
+ *
+ * @param spec - The column spec to compile
+ * @returns The `@orkestrel/database` column shape, wrapped in `optionalShape` when the spec declares `optional: true`
+ */
+export declare function compileColumn(spec: ColumnSpec): ContractShape;
+
+/**
+ * Compiles one {@link import('./types.js').ColumnPrimitive} into its primitive
+ * `@orkestrel/database` shape — the leaf {@link compileColumn} wraps.
+ *
+ * @param primitive - The declared column primitive
+ * @returns The matching primitive `@orkestrel/database` shape
+ */
+export declare function compileColumnPrimitive(primitive: ColumnPrimitive): ContractShape;
+
+/**
+ * Completes a {@link WorkflowDraft} into a strict {@link WorkflowDefinition} — synthesizes any
+ * MISSING `id` deterministically + positionally, and defaults any MISSING `name` to its
  * (now-resolved) `id`.
  *
  * @remarks
@@ -318,7 +329,7 @@ export declare const columnSpecShape: UnionShape<readonly [ LiteralShape<readonl
  * `phase-<i>`, and task `j` of that phase is `<phaseId>-task-<j>` (so a provided phase id flows
  * into its tasks' synthesized ids). A PROVIDED `id` / `name` at any level is kept VERBATIM —
  * synthesis touches only the omitted ones. A missing `name` defaults to the resolved `id` (never
- * the other way round), so the result always has both. `run`, `description`, the per-phase
+ * the other way round), so the result always has both. `behavior`, `description`, the per-phase
  * `concurrency` / `bail`, the per-task `retries` / `timeout`, and the workflow `bail` carry over
  * unchanged. The result is a complete {@link WorkflowDefinition}; the caller still validates it
  * against the STRICT contract.
@@ -329,7 +340,7 @@ export declare const columnSpecShape: UnionShape<readonly [ LiteralShape<readonl
 export declare function completeDraft(draft: WorkflowDraft): WorkflowDefinition;
 
 /**
- * Complete one {@link PhaseDraft} into a strict phase definition — the per-phase step of
+ * Completes one {@link PhaseDraft} into a strict phase definition — the per-phase step of
  * {@link completeDraft} (phase `index` → `phase-<index>` when its id is omitted).
  *
  * @param phase - The draft phase
@@ -339,7 +350,7 @@ export declare function completeDraft(draft: WorkflowDraft): WorkflowDefinition;
 export declare function completePhaseDraft(phase: PhaseDraft, index: number): WorkflowDefinition['phases'][number];
 
 /**
- * Complete one {@link TaskDraft} into a strict task definition — the per-task leaf step of
+ * Completes one {@link TaskDraft} into a strict task definition — the per-task leaf step of
  * {@link completeDraft} (task `index` of phase `<phaseId>` → `<phaseId>-task-<index>` when its id
  * is omitted).
  *
@@ -350,7 +361,7 @@ export declare function completePhaseDraft(phase: PhaseDraft, index: number): Wo
  */
 export declare function completeTaskDraft(task: TaskDraft, phaseId: string, index: number): WorkflowDefinition['phases'][number]['tasks'][number];
 
-/** One SERIALIZED WHERE condition — `values` is ALWAYS an array, even for a single-value operator. */
+/** Describes one SERIALIZED WHERE condition — `values` is ALWAYS an array, even for a single-value operator. */
 export declare const conditionShape: ObjectShape<{
     column: StringShape;
     operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
@@ -359,7 +370,7 @@ export declare const conditionShape: ObjectShape<{
 }, false>;
 
 /**
- * Wrap a live `AgentInterface` (`@orkestrel/agent`) as a {@link WorkflowFunction}
+ * Wraps a live `AgentInterface` (`@orkestrel/agent`) as a {@link WorkflowFunction}
  * (`@orkestrel/workflow`) — the opt-in adapter that runs the agent to a settled result and carries
  * immutable lineage metadata for contextual Toolbox composition.
  *
@@ -367,7 +378,7 @@ export declare const conditionShape: ObjectShape<{
  * Composes into a caller's registry like any other behavior; the pure workflow runner has no
  * knowledge of agents itself. A root adapter derives its workflow lineage from the controller,
  * while a contextual adapter requires an exact match. Repeated agents, repeated workflows, and
- * targets deeper than {@link import('./constants.js').MAX_WORKFLOW_DEPTH} are rejected before
+ * 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
@@ -397,14 +408,14 @@ export declare const conditionShape: ObjectShape<{
 export declare function createAgentFunction(agent: AgentInterface, options?: AgentFunctionOptions): AgentFunction;
 
 /**
- * Build an LLM-callable sub-agent delegation tool — resolves a live, seeded `AgentInterface`
+ * Builds an LLM-callable sub-agent delegation tool — resolves a live, seeded `AgentInterface`
  * from `registry` and runs it to completion for ONE delegated `task`.
  *
  * @remarks
- * The universal tool-handler contract (AGENTS §14): validates the call args against
+ * The universal tool-handler contract: validates the call args against
  * {@link import('./shapers.js').agentToolShape}, 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 via
+ * back to the tool's own {@link import('./types.js').AgentToolOptions} defaults), 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`
  * {@link import('./errors.js').ToolboxError}; a delegation that would exceed
@@ -438,16 +449,16 @@ export declare function createAgentFunction(agent: AgentInterface, options?: Age
 export declare function createAgentTool(registry: AgentRegistryInterface, options?: AgentToolOptions): ToolInterface;
 
 /**
- * Build an LLM-callable answer tool — the ANSWER side of the terminal seam. Lists the forms
- * currently addressed to {@link import('./types.js').AnswerToolOptions.to}, or answers one of
+ * Builds an LLM-callable answer tool — the ANSWER side of the terminal seam. Lists the forms
+ * addressed to {@link import('./types.js').AnswerToolOptions.to}, or answers one of
  * them by id.
  *
  * @remarks
- * The universal tool-handler contract (AGENTS §14): validates the call args against
+ * The universal tool-handler contract: validates the call args against
  * {@link import('./shapers.js').answerToolShape} (discriminated by `operation`). `'pending'`
- * returns a compact list (`{ id, from, schema }`) of every form currently addressed to `to`.
+ * 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 via
+ * and applies it through
  * `TerminalManagerInterface.answer` — a rejected / unknown / unresolvable outcome
  * (`TerminalAnswerResult.error`) re-surfaces as a typed `ANSWER` `ToolboxError`; success returns
  * `{ answered: id }`. `to` is FIXED at construction
@@ -476,7 +487,7 @@ export declare function createAgentTool(registry: AgentRegistryInterface, option
 export declare function createAnswerTool(options: AnswerToolOptions): ToolInterface;
 
 /**
- * Create a {@link DefinitionStoreInterface} backed by one table of the `@orkestrel/database`
+ * Creates a {@link DefinitionStoreInterface} backed by one table of the `@orkestrel/database`
  * layer — the driver-pluggable twin of {@link createMemoryDefinitionStore}, storing each
  * database's definition as one opaque JSON column.
  *
@@ -493,15 +504,15 @@ export declare function createAnswerTool(options: AnswerToolOptions): ToolInterf
 export declare function createDatabaseDefinitionStore(driver?: DriverInterface): DefinitionStoreInterface;
 
 /**
- * Build an LLM-callable database tool — create, query, and mutate `@orkestrel/database`
- * databases through one `operation`-discriminated call (AGENTS §14, matching
+ * Builds an LLM-callable database tool — it creates, queries, and mutates `@orkestrel/database`
+ * databases through one `operation`-discriminated call (matching
  * {@link createWorkspaceTool}'s single-tool-many-operations shape).
  *
  * @remarks
- * The universal tool-handler contract (AGENTS §14): validates the call args against
+ * 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
- * lifetime — `'create'` mints one from `tables` ({@link import('./helpers.js').expandTables}) and
+ * 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
  * back to {@link import('./types.js').DatabaseToolOptions.store} (an unknown id throws a typed
@@ -510,10 +521,10 @@ export declare function createDatabaseDefinitionStore(driver?: DriverInterface):
  *
  * `'records'` clamps its `query` to
  * {@link import('./types.js').DatabaseToolOptions.limit} (default
- * {@link import('./constants.js').DATABASE_TOOL_LIMIT}) via
+ * {@link import('./constants.js').DATABASE_TOOL_LIMIT}) through
  * {@link import('./helpers.js').clampQuery}, reporting `truncated` when storage held more rows
- * than the cap. Every operation's `query` is normalized via
- * {@link import('./helpers.js').queryOf} (defaults an omitted condition `connector` to `'and'`).
+ * than the cap. Every operation's `query` is normalized through
+ * {@link import('./helpers.js').normalizeQuery} (defaults an omitted condition `connector` to `'and'`).
  * When {@link import('./types.js').DatabaseToolOptions.readonly} is `true`, every mutating
  * operation throws a typed `TOOL` `ToolboxError` before doing anything. A configured
  * {@link import('./types.js').DatabaseToolOptions.timeout} is passed as a fresh
@@ -522,7 +533,7 @@ export declare function createDatabaseDefinitionStore(driver?: DriverInterface):
  * not an outer deadline for resolution, construction, schema inspection, `get`, or `close`. A typed `@orkestrel/database`
  * failure (`DatabaseError`) re-surfaces as a typed `DATABASE` `ToolboxError` carrying the
  * original {@link import('@orkestrel/database').DatabaseErrorCode} in `context.code`
- * ({@link import('./helpers.js').databaseToolCode}); an `ToolboxError` thrown by this tool's own
+ * ({@link import('./helpers.js').inferDatabaseCode}); an `ToolboxError` thrown by this tool's own
  * guards passes through unwrapped.
  *
  * A lazily re-minted database over the DEFAULT in-memory driver yields an EMPTY database — only
@@ -555,7 +566,7 @@ export declare function createDatabaseDefinitionStore(driver?: DriverInterface):
 export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolInterface;
 
 /**
- * Build an LLM-callable tool that returns the FULL `description` of another registered tool by
+ * Builds an LLM-callable tool that returns the FULL `description` of another registered tool by
  * name — the counterpart to the lean `summary` the other tools in this package advertise
  * (`AGENT_TOOL_SUMMARY` / `WORKFLOW_TOOL_SUMMARY` / `WORKSPACE_TOOL_SUMMARY`).
  *
@@ -564,10 +575,10 @@ export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolI
  * tool.description` — a lean one-sentence summary stands in for a tool's full teaching
  * 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 via `tools.tool(name)` and returns its full `description` (falling back to `summary` when a
+ * 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).
  *
- * The universal tool-handler contract (AGENTS §14): validates the call args against
+ * 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.
@@ -591,32 +602,32 @@ 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
+ * Wraps 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
+ * `parameters` is inferred ONCE at construction from `definition.samples` through
  * `@orkestrel/contract`'s `samplesToSchema` (tuned by {@link import('./types.js').EndpointToolOptions}'s
- * `format` / `enum`), wrapping a non-object root as `{ value: <schema> }` via `schemaToObject` —
+ * `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` 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
+ * `@orkestrel/contract`'s `schemaToShape` compiles it ONCE (through `createContract`) into a
+ * `ContractInterface` whose `.parse` 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.invoke` receives the COERCED value (e.g. `7` sent for a
+ * `'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.invoke` is never called. `format` annotations are
+ * 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`, `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,
+ * `validate: false`, the tool's `execute` PASSES THROUGH the model-supplied `args` to
+ * `definition.execute` WITHOUT re-validation — the raw-passthrough opt-out. Either way, the
+ * definition's return flows back as the tool call's plain result; a throw PROPAGATES uncaught,
  * isolated by the `ToolManagerInterface` (`@orkestrel/tool`) into the canonical error envelope
- * (AGENTS §14) — never caught or re-wrapped here.
+ * — never caught or re-wrapped here.
  *
  * @param definition - The endpoint's identity, non-empty samples, and local handler (see
  *   {@link import('./types.js').EndpointDefinition})
@@ -633,12 +644,12 @@ export declare function createDescribeTool(tools: ToolManagerInterface): ToolInt
  * 	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' }),
+ * 	execute: (args) => ({ id: args.id, name: 'Ada' }),
  * })
  * const tools = createToolManager()
  * tools.add(tool)
  *
- * // conforming args (all required keys present) parse and reach `invoke`
+ * // conforming args (all required keys present) parse and reach the definition's `execute`
  * const result = await tools.execute({
  * 	id: 'call-1',
  * 	name: 'lookupUser',
@@ -647,7 +658,7 @@ export declare function createDescribeTool(tools: ToolManagerInterface): ToolInt
  * // result.value -> { id: '1', name: 'Ada' }
  *
  * // a nonconforming call (id is not coercible to the required string) is rejected before
- * // `invoke` runs
+ * // the definition's `execute` runs
  * const rejected = await tools.execute({
  * 	id: 'call-2',
  * 	name: 'lookupUser',
@@ -659,15 +670,15 @@ export declare function createDescribeTool(tools: ToolManagerInterface): ToolInt
 export declare function createEndpointTool(definition: EndpointDefinition, options?: EndpointToolOptions): ToolInterface;
 
 /**
- * Build a standalone LLM-callable tool that infers a JSON Schema from example values — the
+ * Builds 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
+ * The universal tool-handler contract: 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
+ * booleans, `candidates` an optional array), 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`
@@ -675,7 +686,7 @@ export declare function createEndpointTool(definition: EndpointDefinition, optio
  *
  * 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
+ * compiles a SEPARATE per-call contract from the RAW inferred schema (through `@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
@@ -683,10 +694,10 @@ export declare function createEndpointTool(definition: EndpointDefinition, optio
  * 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
+ * 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 guarantee (AGENTS §14), a `valid: true` entry is
- * ALWAYS also `coercible: true`. `@orkestrel/contract` 0.0.7's `explain` mirrors the normalizing
+ * `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, since
  * the mismatch the normalizing parse would silently fix is not one `explain` reports. `faults`
@@ -694,7 +705,7 @@ export declare function createEndpointTool(definition: EndpointDefinition, optio
  * (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
+ * 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,
@@ -738,8 +749,8 @@ export declare function createEndpointTool(definition: EndpointDefinition, optio
 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
+ * Creates the in-memory {@link DefinitionStoreInterface} — a process-lifetime `Map` of database
+ * definitions, the DEFAULT store the database and relation tools persist their
  * `DatabaseDefinition` configs through.
  *
  * @returns A {@link DefinitionStoreInterface}
@@ -754,11 +765,11 @@ export declare function createInferTool(options?: InferToolOptions): ToolInterfa
 export declare function createMemoryDefinitionStore(): DefinitionStoreInterface;
 
 /**
- * Build an LLM-callable form tool — the ASK side of the terminal seam. Asks
+ * Builds an LLM-callable form tool — the ASK side of the terminal seam. Asks
  * a multi-field form and BLOCKS until it answers, returning the resolved values record.
  *
  * @remarks
- * The universal tool-handler contract (AGENTS §14): validates the call args against
+ * The universal tool-handler contract: validates the call args against
  * {@link import('./shapers.js').promptToolShape}, parses the call's schema through
  * `@orkestrel/form`, constructs the live form, and passes it to `TerminalManagerInterface.ask`.
  * `from` is FIXED at construction
@@ -767,7 +778,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
- * plus the known ones (`manager.terminals()`).
+ * and how many brokers the manager holds (`manager.count`).
  *
  * @param options - The live manager, the fixed `from` identity, and advertised overrides (see
  *   {@link import('./types.js').PromptToolOptions})
@@ -790,32 +801,33 @@ export declare function createMemoryDefinitionStore(): DefinitionStoreInterface;
 export declare function createPromptTool(options: PromptToolOptions): ToolInterface;
 
 /**
- * Build an LLM-callable relation tool — traverse and edit `@orkestrel/relation` relationships
- * through one `operation`-discriminated call (AGENTS §14, matching {@link createDatabaseTool}'s
+ * Builds an LLM-callable relation tool — it traverses and edits `@orkestrel/relation` relationships
+ * through one `operation`-discriminated call (matching {@link createDatabaseTool}'s
  * single-tool-many-operations shape).
  *
  * @remarks
- * The universal tool-handler contract (AGENTS §14): validates the call args against
+ * The universal tool-handler contract: validates the call args against
  * {@link import('./shapers.js').relationToolShape}, 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`
  * {@link import('./errors.js').ToolboxError}
- * ({@link import('./helpers.js').relationManagerOf}) — then resolves `model` against it
- * ({@link import('./helpers.js').relationModelOf}, same typed-`TOOL`-on-miss shape), and
+ * ({@link import('./helpers.js').resolveRelationManager}) — then resolves `model` against it
+ * ({@link import('./helpers.js').resolveRelationModel}, same typed-`TOOL`-on-miss shape), and
  * dispatches to the matched operation, RETURNING a plain result on success.
  *
  * `'load'` / `'find'` expand the call's FLAT dot-path `include` list into a live
- * `@orkestrel/relation` `Include` tree via {@link import('./helpers.js').expandInclude}, capped
+ * `@orkestrel/relation` `Include` tree through {@link import('./helpers.js').expandInclude}, capped
  * at {@link import('./types.js').RelationToolOptions.depth} (default
  * {@link import('./constants.js').RELATION_TOOL_DEPTH}) — a path exceeding the cap, or carrying an
  * empty segment, throws a typed `TOOL` error. `'load'` dispatches on whether `key` is an array
- * (positional many-key form, AGENTS §9.2) or a single key. `'find'` and `'links'` clamp their
+ * (positional many-key form — an array key is read as many keys rather than one) or a single key.
+ * `'find'` and `'links'` clamp their
  * result to {@link import('./types.js').RelationToolOptions.limit} (default
- * {@link import('./constants.js').RELATION_TOOL_LIMIT}) — `'find'` probes one row past the
- * effective limit (mirroring {@link import('./helpers.js').clampQuery}'s idiom) to report
- * `truncated`; `'links'` (which has no upstream pagination) fetches the FULL linked-key list and
- * slices/truncates it the same way. `'link'` / `'unlink'` write / remove one `through` junction
+ * {@link import('./constants.js').RELATION_TOOL_LIMIT}), taken through
+ * {@link import('./helpers.js').resolveLimit} — `'find'` probes one row past the effective limit to
+ * report `truncated`; `'links'` (which has no upstream pagination) fetches the FULL linked-key
+ * list and slices/truncates it the same way. `'link'` / `'unlink'` write / remove one `through` junction
  * row.
  *
  * A typed `@orkestrel/relation` failure (`RelationError`) re-surfaces as a typed `RELATION`
@@ -839,7 +851,7 @@ export declare function createPromptTool(options: PromptToolOptions): ToolInterf
 export declare function createRelationTool(options: RelationToolOptions): ToolInterface;
 
 /**
- * Wrap a registered tool as a {@link WorkflowFunction} (`@orkestrel/workflow`) — the OPT-IN
+ * Wraps a registered tool as a {@link WorkflowFunction} (`@orkestrel/workflow`) — the OPT-IN
  * adapter that lets a `function`-form task run a `@orkestrel/tool` tool BY NAME.
  *
  * @remarks
@@ -870,14 +882,14 @@ export declare function createRelationTool(options: RelationToolOptions): ToolIn
 export declare function createToolFunction(tools: ToolManagerInterface, name: string): WorkflowFunction;
 
 /**
- * Compile the lenient workflow draft contract used by {@link createWorkflowTool}.
+ * Compiles the lenient workflow draft contract used by {@link createWorkflowTool}.
  *
  * @returns The compiled {@link import('./types.js').WorkflowDraft} contract
  */
 export declare function createWorkflowDraftContract(): ContractInterface<WorkflowDraft>;
 
 /**
- * Compose opaque host functions and raw agents into one immutable workflow registry.
+ * Composes opaque host functions and raw agents into one immutable workflow registry.
  *
  * @remarks
  * This is the target-aware composition boundary used by direct runner consumers and
@@ -903,10 +915,10 @@ export declare function createWorkflowDraftContract(): ContractInterface<Workflo
  * await runner.execute(definition, { functions })
  * ```
  */
-export declare function createWorkflowFunctions(runner: WorkflowRunnerInterface, options?: WorkflowToolOptions): WorkflowFunctions;
+export declare function createWorkflowFunctions(runner: WorkflowRunnerInterface, options?: WorkflowToolOptions): WorkflowRegistry;
 
 /**
- * Wrap a {@link WorkflowDefinition} as an LLM-callable tool — it ADVERTISES the SIMPLE flat
+ * Wraps a {@link WorkflowDefinition} as an LLM-callable tool — it ADVERTISES the SIMPLE flat
  * authoring shape (`{ name?, steps: [{ name }] }`) as its `parameters` so even a small model can
  * author a complete tree, and its handler EXPANDS / COMPLETES the authored blob, validates it
  * against the STRICT contract, and runs it through `runner`, forwarding the caller's optional
@@ -932,7 +944,7 @@ export declare function createWorkflowFunctions(runner: WorkflowRunnerInterface,
  * - the full nested {@link WorkflowDefinition} — the advanced escape-hatch, accepted as the draft
  *   super-set.
  *
- * The universal tool-handler contract (AGENTS §14): returns the plain run summary
+ * 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
@@ -963,15 +975,15 @@ export declare function createWorkflowFunctions(runner: WorkflowRunnerInterface,
 export declare function createWorkflowTool(definition: WorkflowDefinition, runner: WorkflowRunnerInterface, options?: WorkflowToolOptions): ToolInterface;
 
 /**
- * Build an LLM-callable workspace-editing tool — it ADVERTISES the `operation`-discriminated
- * 13-op union ({@link import('./shapers.js').workspaceToolShape}) as its `parameters`, and its
+ * Builds an LLM-callable workspace-editing tool — it ADVERTISES the `operation`-discriminated
+ * union ({@link import('./shapers.js').workspaceToolShape}) as its `parameters`, and its
  * handler PARSES the model-supplied args against that contract and DISPATCHES the matched
  * operation against the manager's ACTIVE workspace (the registry ops drive the manager itself),
  * returning the plain result. A malformed operation throws this package's `ToolboxError`; a
  * genuine workspace-domain failure propagates `@orkestrel/workspace`'s typed `WorkspaceError`.
  * EITHER drives a caller-supplied {@link WorkspaceToolOptions.manager} directly, OR
  * constructs a fresh `WorkspaceManagerInterface` (`@orkestrel/workspace`) over
- * {@link import('./types.js').WorkspaceToolOptions.store} (via `@orkestrel/workspace`'s
+ * {@link import('./types.js').WorkspaceToolOptions.store} (through `@orkestrel/workspace`'s
  * `createWorkspaceManager`); neither given constructs a manager backed by
  * `@orkestrel/workspace`'s in-memory store default.
  *
@@ -986,15 +998,15 @@ export declare function createWorkflowTool(definition: WorkflowDefinition, runne
  *
  * NO-ACTIVE RULE (the ergonomic seam): a WRITING op (write / splice / prepend / append / move /
  * remove / replace) run when `manager.active` is `undefined` AUTO-CREATES + activates a default
- * workspace (`manager.add()`) so the model can just start writing; a pure-READ op (read / list /
+ * 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 (AGENTS §14): it `contract.parse`s
+ * 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 (`MODALITY` / `PATTERN` / `RANGE`) PROPAGATE
- * uncaught. The range edit is the FLAT `'splice'` op: its four flat caret integers are
+ * `WorkspaceError` raised by the live workspace (`MISSING` / `MODALITY` / `PATTERN` / `RANGE`)
+ * PROPAGATE uncaught. The range edit is the FLAT `'splice'` op: its four flat caret integers are
  * reassembled into a `Range` (`@orkestrel/workspace`) by `rangeOf` and fed to the workspace's
  * ranged `write`.
  *
@@ -1015,9 +1027,9 @@ export declare function createWorkflowTool(definition: WorkflowDefinition, runne
 export declare function createWorkspaceTool(options?: WorkspaceToolOptions): ToolInterface;
 
 /**
- * The DESCRIPTION the upcoming database tool will advertise — a multi-line guide that teaches a
- * small model the operation list, the SERIALIZED query form, and the {@link import('./types.js').TableSpec}
- * column DSL.
+ * Holds the description {@link import('./factories.js').createDatabaseTool} advertises — a
+ * multi-line guide that teaches a small model the operation list, the SERIALIZED query form, and
+ * the {@link import('./types.js').TableSpec} column DSL.
  *
  * @remarks
  * The query form is deliberately SERIALIZED (never fluent) — every condition is a flat object
@@ -1027,37 +1039,33 @@ export declare function createWorkspaceTool(options?: WorkspaceToolOptions): Too
  */
 export declare const DATABASE_TOOL_DESCRIPTION: string;
 
-/** The default cap on rows a `records` call returns when the caller omits `query.limit` — the upcoming database tool's default row ceiling. */
+/** Holds the default cap on rows a `records` call returns when the caller omits `query.limit` — the database tool's default row ceiling. */
 export declare const DATABASE_TOOL_LIMIT = 1000;
 
-/** The runtime-frozen database-tool mutation names disabled by `DatabaseToolOptions.readonly`. */
+/** Lists the runtime-frozen database-tool mutation names disabled by `DatabaseToolOptions.readonly`. */
 export declare const DATABASE_TOOL_MUTATIONS: readonly string[];
 
 /**
- * The name the upcoming `createDatabaseTool` factory will advertise by default — the key a model
- * calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
- *
- * @remarks
- * SRC-1 of a 3-unit spine: this unit lands the persistence + schema foundation
- * ({@link import('./types.js').DatabaseDefinition}, {@link import('./types.js').DefinitionStoreInterface},
- * {@link import('./helpers.js').expandTables}); `createDatabaseTool` itself is built in a later unit.
+ * Holds the name {@link import('./factories.js').createDatabaseTool} advertises by default — the key
+ * a model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
  */
 export declare const DATABASE_TOOL_NAME = "database";
 
 /**
- * The lean {@link import('@orkestrel/tool').ToolInterface.summary} the upcoming database tool
- * will advertise in place of {@link DATABASE_TOOL_DESCRIPTION}.
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary}
+ * {@link import('./factories.js').createDatabaseTool} advertises in place of
+ * {@link DATABASE_TOOL_DESCRIPTION}.
  */
 export declare const DATABASE_TOOL_SUMMARY = "Create and query a database \u2014 one operation per call (create, tables, get, records, count, aggregate, add, set, update, remove, destroy), chosen by the 'operation' field. Call describe('database') for the full operation list, the query form, and the column DSL.";
 
 /**
- * One database's CONFIG-ONLY definition — `id` + `driver` + {@link TableSpec}, with optional
+ * Represents one database's CONFIG-ONLY definition — `id` + `driver` + {@link TableSpec}, with optional
  * `primary`, `indexes`, and `version` schema configuration.
  *
  * @remarks
  * A `DatabaseDefinition` is NEVER a live handle — it is the durable, serializable config a
  * {@link DefinitionStoreInterface} persists and a tool factory turns into a real
- * `@orkestrel/database` `DatabaseInterface` (via `createDatabase` + {@link import('./helpers.js').expandTables})
+ * `@orkestrel/database` `DatabaseInterface` (through `createDatabase` + {@link import('./compilers.js').expandTables})
  * on demand. `primary` maps table names to primary-key columns; `indexes` maps table names to
  * index column groups; `version` opts a capable driver into open-time schema reconciliation.
  */
@@ -1070,14 +1078,14 @@ export declare interface DatabaseDefinition {
     readonly version?: number;
 }
 
-/** One opaque persisted row — the shape a `TableInterface<DatabaseDefinitionRow>`-backed store reads/writes; `definition` is narrowed with {@link import('./helpers.js').isDatabaseDefinition} on read. */
+/** Represents one opaque persisted row — the shape a `TableInterface<DatabaseDefinitionRow>`-backed store reads/writes; `definition` is narrowed with {@link import('./validators.js').isDatabaseDefinition} on read. */
 export declare interface DatabaseDefinitionRow {
     readonly id: string;
     readonly definition: unknown;
 }
 
 /**
- * A {@link DefinitionStoreInterface} backed by one table of the `@orkestrel/database` layer — a
+ * Represents a {@link DefinitionStoreInterface} backed by one table of the `@orkestrel/database` layer — a
  * database's durable CONFIG state IS a row, so persistence reduces to keyed point-access
  * (`get` / `set` / `delete`) over a {@link TableInterface}, the driver-pluggable twin of the
  * plain-`Map` {@link import('./MemoryDefinitionStore.js').MemoryDefinitionStore}.
@@ -1099,12 +1107,12 @@ export declare interface DatabaseDefinitionRow {
  * - **`set(definition)` upserts under the definition's OWN `id`** (no separate id param) — it
  *   writes the row `{ id: definition.id, definition }`.
  * - **`get(id)` resolves the stored definition for an id**, narrowing the opaque JSON column back
- *   to a {@link DatabaseDefinition} ({@link import('../helpers.js').isDatabaseDefinition} — the
- *   AGENTS §14 boundary narrow for an untrusted storage read), or `undefined` if none is stored
+ *   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).
  *
- * The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the §22 method
+ * The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the method
  * bijection with {@link DefinitionStoreInterface}).
  *
  * @example
@@ -1120,22 +1128,65 @@ export declare interface DatabaseDefinitionRow {
 export declare class DatabaseDefinitionStore implements DefinitionStoreInterface {
     #private;
     /**
-     * Wrap a table as a definition store.
+     * Wraps a table as a definition store.
      *
      * @param table - The {@link TableInterface} holding the definitions — its row is the
      *   {@link DatabaseDefinitionRow} `{ id; definition }` shape (the definition one opaque JSON column)
      */
     constructor(table: TableInterface<DatabaseDefinitionRow>);
-    /** Resolve the persisted definition for `id`, narrowing the opaque JSON column back to a `DatabaseDefinition`. */
+    /**
+     * Resolves the persisted definition for `id`, narrowing the opaque JSON column back to a
+     * {@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
+     */
     get(id: string): Promise<DatabaseDefinition | undefined>;
-    /** Insert or replace under the definition's OWN `id` (no separate id param) — the row is `{ id, definition }`. */
+    /**
+     * Inserts or replaces a definition under its OWN `id` — the written row is `{ id, definition }`.
+     *
+     * @param definition - The config to persist; its own `id` is the row key (no separate id param)
+     * @returns A promise settling once the row is written
+     */
     set(definition: DatabaseDefinition): Promise<void>;
-    /** Drop a definition by id; an absent id is a no-op (no throw). */
+    /**
+     * Drops the definition stored under `id`.
+     *
+     * @param id - The database id to drop; an absent id is a no-op, never a throw
+     * @returns A promise settling once no row is stored under `id`
+     */
     delete(id: string): Promise<void>;
 }
 
 /**
- * Resolve database definitions into cached live handles for database tools.
+ * Represents the SERIALIZED wire query a database-tool call carries — the parsed form of
+ * {@link import('./shapers.js').queryShape}, which
+ * {@link import('./helpers.js').normalizeQuery} normalizes into a live `@orkestrel/database`
+ * {@link QueryInput}.
+ *
+ * @remarks
+ * Every condition is FLAT and its `values` is ALWAYS an array, even for a single-value operator.
+ * `connector` is optional because the LAST condition joins nothing forward; `normalizeQuery` defaults an
+ * omitted one to `'and'`. `order` / `limit` / `offset` carry over to the live query unchanged.
+ */
+export declare interface DatabaseQueryInput {
+    readonly conditions?: ReadonlyArray<Readonly<{
+        column: string;
+        operator: Condition['operator'];
+        values: readonly unknown[];
+        connector?: ConditionConnector;
+    }>>;
+    readonly order?: ReadonlyArray<Readonly<{
+        column: string;
+        direction: OrderDirection;
+    }>>;
+    readonly limit?: number;
+    readonly offset?: number;
+}
+
+/**
+ * Resolves database definitions into cached live handles for database tools.
  *
  * @example
  * ```ts
@@ -1148,7 +1199,7 @@ export declare class DatabaseDefinitionStore implements DefinitionStoreInterface
 export declare class DatabaseResolver {
     #private;
     /**
-     * Create a database resolver over the tool's live state and optional definition store.
+     * Creates 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
@@ -1157,21 +1208,21 @@ export declare class DatabaseResolver {
      */
     constructor(handles: ReadonlyMap<string, DatabaseInterface>, drivers: Readonly<Record<string, () => DriverInterface>>, generator?: KeyFunction, store?: DefinitionStoreInterface);
     /**
-     * Determine whether a live database is cached by id.
+     * Determines whether a live database is cached by id.
      *
      * @param id - Database id
-     * @returns Whether a live handle is cached
+     * @returns True if a live handle is cached; false otherwise
      */
     has(id: string): boolean;
     /**
-     * Read a cached database without consulting the definition store.
+     * Reads 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.
+     * Caches a live database by id.
      *
      * @param id - Database id
      * @param database - Live database handle
@@ -1179,14 +1230,14 @@ export declare class DatabaseResolver {
      */
     set(id: string, database: DatabaseInterface): void;
     /**
-     * Remove a cached live database by id.
+     * Removes a cached live database by id.
      *
      * @param id - Database id
      * @returns Nothing
      */
     delete(id: string): void;
     /**
-     * Resolve a cached or stored database by id.
+     * Resolves a cached or stored database by id.
      *
      * @param id - Database definition id
      * @returns The cached or newly constructed live database
@@ -1195,23 +1246,12 @@ export declare class DatabaseResolver {
 }
 
 /**
- * Map a caught error to the {@link ToolboxErrorCode} the upcoming database tool should throw
- * with — the pure classification step of that factory's error handling, mirroring
- * {@link terminalToolCode}'s idiom for `@orkestrel/database`.
- *
- * @param error - The value caught from a `@orkestrel/database` table operation
- * @returns The granular {@link DatabaseErrorCode}, or `undefined` if `error` is not a `DatabaseError`
- */
-export declare function databaseToolCode(error: unknown): DatabaseErrorCode | undefined;
-
-/**
- * Options for {@link import('./factories.js').createDatabaseTool} — SRC-2 of the 3-unit database
- * / relation spine, built over the SRC-1 foundation ({@link DatabaseDefinition},
- * {@link DefinitionStoreInterface}, {@link import('./helpers.js').expandTables}).
+ * Represents the options for {@link import('./factories.js').createDatabaseTool} — the live handles, definition
+ * store, driver registry, key generator, row cap, timeout, and readonly gate the tool composes.
  *
  * @remarks
- * - `databases` — live `DatabaseInterface` handles to seed the tool's cache with (e.g. a
- *   caller-constructed database it should manage alongside store-backed ones); keyed by the id a
+ * - `databases` — live `DatabaseInterface` handles to seed the tool's cache with (for example a
+ *   caller-constructed database it manages alongside store-backed ones); keyed by the id a
  *   call's `id` field addresses.
  * - `store` — the {@link DefinitionStoreInterface} the `'create'` operation persists its
  *   {@link DatabaseDefinition} CONFIG through, and `'destroy'` deletes from; also the source
@@ -1223,7 +1263,7 @@ export declare function databaseToolCode(error: unknown): DatabaseErrorCode | un
  * - `generator` — the optional `KeyFunction` (`@orkestrel/database`) every minted database is
  *   constructed with, used when a written row lacks its primary key. Omitted delegates to the
  *   database's default generator.
- * - `limit` — the `'records'` row cap — via {@link import('./helpers.js').clampQuery}
+ * - `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
  *   {@link import('./constants.js').DATABASE_TOOL_LIMIT}.
  * - `timeout` — a nonnegative safe-integer number of milliseconds. A fresh
@@ -1250,15 +1290,15 @@ export declare interface DatabaseToolOptions {
 }
 
 /**
- * The shape of {@link import('./factories.js').createDatabaseTool}'s call arguments —
+ * Describes the shape of {@link import('./factories.js').createDatabaseTool}'s call arguments —
  * discriminated by `operation` into the 11 database operations (`'create'` / `'tables'` /
  * `'get'` / `'records'` / `'count'` / `'aggregate'` / `'add'` / `'set'` / `'update'` /
  * `'remove'` / `'destroy'`).
  *
  * @remarks
  * Every arm carries `id` (the database id). `'create'` carries `tables` (the
- * {@link import('./types.js').TableSpec} column DSL, compiled via
- * {@link import('./helpers.js').expandTables}); `'get'` / `'update'` / `'remove'` carry `key`
+ * {@link import('./types.js').TableSpec} column DSL, compiled through
+ * {@link import('./compilers.js').expandTables}); `'get'` / `'update'` / `'remove'` carry `key`
  * (one key or an array of keys, positional); `'add'` / `'set'` carry `row` (one row or an array of
  * rows); `'update'` also carries `changes` (a loose partial row); `'records'` / `'count'` /
  * `'aggregate'` carry an optional `query` (the SERIALIZED form — `values` is ALWAYS an array,
@@ -1269,7 +1309,7 @@ export declare const databaseToolShape: UnionShape<readonly [ ObjectShape<{
     id: StringShape;
     tables: ObjectShape<Record<never, never>, ObjectShape<{
         columns: ObjectShape<Record<never, never>, UnionShape<readonly [ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
-            type: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
+            primitive: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
             optional: OptionalShape<BooleanShape>;
         }, false>]>>;
     }, false>>;
@@ -1368,7 +1408,7 @@ export declare const databaseToolShape: UnionShape<readonly [ ObjectShape<{
 }, false>]>;
 
 /**
- * The point-access persistence seam (AGENTS §5 — Stores) for {@link DatabaseDefinition} configs —
+ * Represents the point-access persistence seam for {@link DatabaseDefinition} configs —
  * the twin of `@orkestrel/terminal`'s `TerminalStoreInterface`, storing a database's CONFIG-ONLY
  * blueprint (never a live handle). Every primitive is async; `delete` of an absent id is a no-op.
  */
@@ -1379,7 +1419,7 @@ export declare interface DefinitionStoreInterface {
 }
 
 /**
- * Derive the zero-based workflow nesting depth from a valid lineage.
+ * Derives the zero-based workflow nesting depth from a valid lineage.
  *
  * @param lineage - The workflow/agent chain
  * @returns Zero for an empty/root lineage, then one per nested workflow
@@ -1387,7 +1427,7 @@ export declare interface DefinitionStoreInterface {
 export declare function deriveWorkflowDepth(lineage: WorkflowLineage): number;
 
 /**
- * The DESCRIPTION {@link import('./factories.js').createDescribeTool} advertises.
+ * Holds the DESCRIPTION {@link import('./factories.js').createDescribeTool} advertises.
  *
  * @remarks
  * Deliberately short — unlike the workflow / workspace / agent tools, this one has no authoring
@@ -1396,38 +1436,38 @@ export declare function deriveWorkflowDepth(lineage: WorkflowLineage): number;
 export declare const DESCRIBE_TOOL_DESCRIPTION = "Return the full description of a registered tool by its name. Required: name - the registered tool name (see another tool listing for available names).";
 
 /**
- * The name {@link import('./factories.js').createDescribeTool} advertises by default — the key a
+ * Holds the name {@link import('./factories.js').createDescribeTool} advertises by default — the key a
  * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
  *
  * @remarks
- * Net-new: pairs with the other three tools' lean {@link AGENT_TOOL_SUMMARY} /
- * {@link WORKFLOW_TOOL_SUMMARY} / {@link WORKSPACE_TOOL_SUMMARY} — a model that reads only the
+ * Pairs with the lean {@link AGENT_TOOL_SUMMARY} / {@link WORKFLOW_TOOL_SUMMARY} /
+ * {@link WORKSPACE_TOOL_SUMMARY} — a model that reads only the
  * advertised summary can call `describe` with that tool's registered name to get its full
  * teaching description back.
  */
 export declare const DESCRIBE_TOOL_NAME = "describe";
 
 /**
- * The lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createDescribeTool}
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createDescribeTool}
  * advertises — this tool needs no teaching of its own, so its summary and description are both
  * short.
  */
 export declare const DESCRIBE_TOOL_SUMMARY = "Return the full description of a named registered tool.";
 
 /**
- * The FLAT args {@link import('./factories.js').createDescribeTool} accepts — the registered
+ * Represents the FLAT args {@link import('./factories.js').createDescribeTool} accepts — the registered
  * tool `name` whose full `description` a model wants back.
  *
  * @remarks
  * `name` must match a tool registered on the {@link import('@orkestrel/tool').ToolManagerInterface}
- * the describe tool was built over — it is looked up via `tools.tool(name)`.
+ * the describe tool was built over — it is looked up through `tools.tool(name)`.
  */
 export declare interface DescribeToolArguments {
     readonly name: string;
 }
 
 /**
- * The shape of {@link import('./types.js').DescribeToolArguments} —
+ * Describes the shape of {@link import('./types.js').DescribeToolArguments} —
  * {@link import('./factories.js').createDescribeTool}'s advertised `parameters`.
  *
  * @remarks
@@ -1438,7 +1478,7 @@ export declare const describeToolShape: ObjectShape<{
 }, false>;
 
 /**
- * One concrete endpoint {@link import('./factories.js').createEndpointTool} wraps as an
+ * Represents 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.
  *
@@ -1446,36 +1486,36 @@ export declare const describeToolShape: ObjectShape<{
  * `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,
  * 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
+ * `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 `invoke` at all (see
+ * a call with a missing required key or a non-coercible value never reaches `execute` 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
+ * `validate: 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,
- * the advertised schema wraps them under a single required `value` property, so `invoke` receives
+ * the advertised schema wraps them under a single required `value` property, so `execute` 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;
+    readonly execute: EndpointHandler;
 }
 
 /**
- * The handler {@link import('./types.js').EndpointDefinition.invoke} implements — mirrors
+ * Represents the handler {@link import('./types.js').EndpointDefinition.execute} implements — mirrors
  * `@orkestrel/tool`'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
+ * `execute: (args) => definition.execute(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
+ * Represents the 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.
  *
@@ -1483,23 +1523,25 @@ export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>)
  * `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
+ * compiled ONCE at construction (through `@orkestrel/contract`'s `schemaToShape`) into a
+ * `ContractInterface` used to `parse` every call's `args` before `execute` 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
+ * 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 `invoke` is never called. Beyond that coercion,
+ * 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 `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.
+ * 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.
  */
 export declare interface EndpointToolOptions {
     readonly format?: boolean;
@@ -1508,7 +1550,7 @@ export declare interface EndpointToolOptions {
 }
 
 /**
- * Expand the relation tool's FLAT dot-path `include` list into a live `@orkestrel/relation`
+ * Expands 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
  * before a `'load'` / `'find'` call.
  *
@@ -1534,13 +1576,13 @@ export declare interface EndpointToolOptions {
 export declare function expandInclude(paths: readonly string[] | undefined, depth: number): Include;
 
 /**
- * Expand a flat {@link WorkflowSteps} blob into a strict {@link WorkflowDefinition} — each step
+ * Expands a flat {@link WorkflowSteps} blob into a strict {@link WorkflowDefinition} — each step
  * becomes a one-task phase, IN ORDER.
  *
  * @remarks
  * The expansion of the tool's ADVERTISED surface: the deliberately-reduced flat form. Each
  * {@link import('./types.js').WorkflowStep} maps to a phase holding exactly one task: the step's
- * `name` becomes the task's `run` (the behavior-registry key). Ids/names are auto-filled
+ * `name` becomes the task's `behavior` (the behavior-registry key). Ids/names are auto-filled
  * positionally — it builds an ids-omitted {@link WorkflowDraft} and delegates to
  * {@link completeDraft}, so the two lenient surfaces share ONE synthesis path (step `i` → phase
  * `phase-<i>`, its task `phase-<i>-task-0`). The optional `name` becomes both the workflow's
@@ -1554,7 +1596,7 @@ export declare function expandInclude(paths: readonly string[] | undefined, dept
 export declare function expandSteps(flat: WorkflowSteps): WorkflowDefinition;
 
 /**
- * Compile a {@link TableSpec} into the `@orkestrel/database` {@link TableMap} it configures —
+ * Compiles a {@link TableSpec} into the `@orkestrel/database` {@link TableMap} it configures —
  * each {@link ColumnSpec} maps to the matching primitive shaper (`'string'` → `stringShape()`,
  * `'integer'` → `integerShape()`, `'number'` → `numberShape()`, `'boolean'` → `booleanShape()`),
  * wrapped in `optionalShape` when the column declares `optional: true`. Total, pure.
@@ -1565,7 +1607,7 @@ export declare function expandSteps(flat: WorkflowSteps): WorkflowDefinition;
 export declare function expandTables(spec: TableSpec): TableMap;
 
 /**
- * Append one tag to a workflow lineage and return a frozen copy.
+ * Appends one tag to a workflow lineage and returns a frozen copy.
  *
  * @param lineage - The valid chain to extend
  * @param tag - The workflow or agent tag to append
@@ -1573,29 +1615,68 @@ export declare function expandTables(spec: TableSpec): TableMap;
  */
 export declare function extendLineage(lineage: WorkflowLineage, tag: string): WorkflowLineage;
 
-/** Flat dot-path relation include list, expanded via {@link import('./helpers.js').expandInclude}. */
+/** Describes the flat dot-path relation include list, expanded through {@link import('./helpers.js').expandInclude}. */
 export declare const includeShape: OptionalShape<ArrayShape<StringShape>>;
 
-/** The schema-inference protocol {@link import('./factories.js').createInferTool} advertises. */
+/** Holds the schema-inference protocol {@link import('./factories.js').createInferTool} advertises. */
 export declare const INFER_TOOL_DESCRIPTION: string;
 
 /**
- * The name {@link import('./factories.js').createInferTool} advertises by default — the key a
+ * Holds the name {@link import('./factories.js').createInferTool} advertises by default — the key a
  * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
  */
 export declare const INFER_TOOL_NAME = "infer";
 
 /**
- * The lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createInferTool}
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createInferTool}
  * advertises in place of {@link INFER_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
  * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable via
+ * for the full teaching description; the full text stays retrievable through
  * {@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
+ * Maps a caught error to the granular {@link DatabaseErrorCode} (`@orkestrel/database`) the code
+ * {@link import('./factories.js').createDatabaseTool} throws with — the pure classification step
+ * of that factory's error handling, mirroring {@link inferTerminalCode}'s idiom for
+ * `@orkestrel/database`.
+ *
+ * @param error - The value caught from a `@orkestrel/database` table operation
+ * @returns The granular {@link DatabaseErrorCode}, or `undefined` if `error` is not a `DatabaseError`
+ */
+export declare function inferDatabaseCode(error: unknown): DatabaseErrorCode | undefined;
+
+/**
+ * Maps a caught error to the granular {@link RelationErrorCode} (`@orkestrel/relation`) the code
+ * {@link import('./factories.js').createRelationTool} throws with — the pure classification step
+ * of that factory's error handling, mirroring {@link inferTerminalCode}'s idiom for
+ * `@orkestrel/relation`.
+ *
+ * @param error - The value caught from a `@orkestrel/relation` operation
+ * @returns The granular {@link RelationErrorCode}, or `undefined` if `error` is not a `RelationError`
+ */
+export declare function inferRelationCode(error: unknown): RelationErrorCode | undefined;
+
+/**
+ * Maps a caught error to the {@link ToolboxErrorCode} the terminal-tool factory throws with — the
+ * pure classification step of that factory's error handling.
+ *
+ * @remarks
+ * Narrows `error` with {@link isTerminalError} (`@orkestrel/terminal`) first: a non-`TerminalError`
+ * value returns `undefined`, telling the caller this mapper does not apply (rethrow / handle
+ * otherwise). For a genuine `TerminalError`, `'DEADLOCK'` maps to `'DEADLOCK'`, `'EXPIRE'` maps
+ * to `'EXPIRE'`, and every other {@link import('@orkestrel/terminal').TerminalErrorCode}
+ * (`'TARGET'`, `'LIMIT'`, `'CANCEL'`, `'DRIVER'`, `'DESTROYED'`) maps to the generic `'TOOL'`
+ * code. The mapper only classifies — the factory performs the actual throw.
+ *
+ * @param error - The value caught from a terminal-manager operation (`ask` / `answer` / …)
+ * @returns The mapped {@link ToolboxErrorCode}, or `undefined` if `error` is not a `TerminalError`
+ */
+export declare function inferTerminalCode(error: unknown): ToolboxErrorCode | undefined;
+
+/**
+ * Represents the 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.
@@ -1606,7 +1687,7 @@ export declare interface InferToolOptions {
 }
 
 /**
- * The shape of {@link import('./factories.js').createInferTool}'s call arguments — one or more
+ * Describes 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.
  *
@@ -1626,33 +1707,46 @@ export declare const inferToolShape: ObjectShape<{
 }, false>;
 
 /**
- * Narrow an unknown callable to Toolbox's frozen contextual agent adapter metadata.
+ * Narrows an unknown callable to Toolbox's frozen contextual agent adapter metadata.
  *
  * @param value - The value to inspect
- * @returns Whether it is a frozen {@link AgentFunction} with a frozen valid lineage
+ * @returns True if it is a frozen {@link AgentFunction} with a frozen valid lineage; false otherwise
  */
 export declare function isAgentFunction(value: unknown): value is AgentFunction;
 
-/** Narrow an unknown value to a {@link import('./types.js').ColumnKind}. */
-export declare function isColumnKind(value: unknown): value is ColumnKind;
+/**
+ * Narrows an unknown value to a {@link ColumnPrimitive}.
+ *
+ * @param value - The value to inspect
+ * @returns True if `value` is `'string'`, `'integer'`, `'number'`, or `'boolean'`; false otherwise
+ */
+export declare function isColumnPrimitive(value: unknown): value is ColumnPrimitive;
 
-/** Narrow an unknown value to a {@link ColumnSpec} — a valid {@link import('./types.js').ColumnKind} shorthand, or `{ type, optional }` with a valid `type`. */
+/**
+ * Narrows an unknown value to a {@link ColumnSpec}.
+ *
+ * @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
+ */
 export declare function isColumnSpec(value: unknown): value is ColumnSpec;
 
 /**
- * Narrow an unknown value to a {@link DatabaseDefinition} — a non-empty `id` + `driver`, a
+ * Narrows an unknown value to a {@link DatabaseDefinition} — a non-empty `id` + `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`).
+ *
+ * @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;
 
 /**
- * Type guard narrowing an unknown caught value to an {@link ToolboxError}.
+ * Narrows an unknown caught value to an {@link ToolboxError}.
  *
  * @param value - The value to test (typically a `catch` binding)
- * @returns `true` when `value` is an {@link ToolboxError}
+ * @returns True if `value` is an {@link ToolboxError}; false otherwise
  *
  * @example
  * ```ts
@@ -1668,32 +1762,21 @@ export declare function isDatabaseDefinition(value: unknown): value is DatabaseD
 export declare function isToolboxError(value: unknown): value is ToolboxError;
 
 /**
- * Narrow an unknown value to a valid alternating workflow lineage.
+ * Narrows an unknown value to a valid alternating workflow lineage.
  *
  * @param value - The value to inspect
- * @returns Whether `value` is a unique, nonempty-tagged workflow/agent chain
+ * @returns True if `value` is a unique, nonempty-tagged workflow/agent chain; false otherwise
  */
 export declare function isWorkflowLineage(value: unknown): value is WorkflowLineage;
 
-/** One key value — a string or number; the array form (multiple keys, positional) resolves FIRST per AGENTS §9.2. */
+/** Describes one key value for the database tool and the relation tool — a string or number; the array form (multiple keys, positional) resolves FIRST, so an array argument is read as many keys rather than one. */
 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;
-
-/**
- * Build a validated, copied, and frozen workflow lineage value.
- *
- * @param lineage - The configured chain; omitted means a direct root
- * @returns An immutable caller-isolated lineage
- */
-export declare function lineageOf(lineage?: WorkflowLineage): WorkflowLineage;
-
-/** Which registered relation manager to address — omitted resolves to the sole registered manager. */
+/** Describes which registered relation manager to address — omitted resolves to the sole registered manager. */
 export declare const managerShape: OptionalShape<StringShape>;
 
 /**
- * The maximum nesting depth a workflow → agent → workflow chain may reach — the bound
+ * Holds the maximum nesting depth a workflow → agent → workflow chain may reach — the bound
  * {@link import('./factories.js').createAgentFunction} and
  * {@link import('./factories.js').createWorkflowTool}'s depth/cycle guards enforce.
  *
@@ -1702,16 +1785,19 @@ export declare const managerShape: OptionalShape<StringShape>;
  * workflows is allowed, while a ninth nested workflow is rejected with this package's typed
  * `DEPTH` `ToolboxError`.
  */
-export declare const MAX_WORKFLOW_DEPTH = 8;
+export declare const MAX_WORKFLOW_CHAIN = 8;
 
 /**
- * The in-memory {@link DefinitionStoreInterface} — a process-lifetime `Map` of
+ * Represents the in-memory {@link DefinitionStoreInterface} — a process-lifetime `Map` of
  * {@link DatabaseDefinition}s keyed by database id, the DEFAULT store
- * {@link import('../factories.js').createMemoryDefinitionStore} builds. The EXACT twin of
- * {@link import('./DatabaseDefinitionStore.js').DatabaseDefinitionStore}.
+ * {@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.
  *
  * @remarks
- * A plain `Map<string, DatabaseDefinition>` (AGENTS §21 — the definition is already pure,
+ * A plain `Map<string, DatabaseDefinition>` (the definition is already pure,
  * self-contained CONFIG-only JSON, so no encoding is needed for the memory tier). Values are
  * structured-cloned on both write and read, keeping caller mutation outside the store. There is NO
  * idle-TTL and NO eviction: a persisted definition lives until an explicit `delete`. A durable
@@ -1724,7 +1810,7 @@ export declare const MAX_WORKFLOW_DEPTH = 8;
  * - **`set` inserts / replaces under the definition's OWN `id`** (no separate id param).
  * - **`delete` drops a definition by id**; an absent id is a no-op (no throw).
  *
- * The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the §22 method
+ * The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the method
  * bijection with {@link DefinitionStoreInterface}).
  *
  * @example
@@ -1739,31 +1825,72 @@ export declare const MAX_WORKFLOW_DEPTH = 8;
  */
 export declare class MemoryDefinitionStore implements DefinitionStoreInterface {
     #private;
+    /**
+     * Resolves the persisted definition for `id`, copied out of the backing `Map`.
+     *
+     * @param id - The database id to read
+     * @returns The stored {@link DatabaseDefinition}, or `undefined` when none is stored
+     */
     get(id: string): Promise<DatabaseDefinition | undefined>;
+    /**
+     * Inserts or replaces a definition under its OWN `id`, copied into the backing `Map`.
+     *
+     * @param definition - The config to persist; its own `id` is the key (no separate id param)
+     * @returns A promise settling once the definition is stored
+     */
     set(definition: DatabaseDefinition): Promise<void>;
+    /**
+     * Drops the definition stored under `id`.
+     *
+     * @param id - The database id to drop; an absent id is a no-op, never a throw
+     * @returns A promise settling once no definition is stored under `id`
+     */
     delete(id: string): Promise<void>;
 }
 
-/** One sort term. */
+/**
+ * Returns the canonical workflow lineage — validated, copied, and frozen.
+ *
+ * @param lineage - The configured chain; omitted means a direct root
+ * @returns An immutable caller-isolated lineage
+ */
+export declare function normalizeLineage(lineage?: WorkflowLineage): WorkflowLineage;
+
+/**
+ * Returns the canonical live `@orkestrel/database` {@link QueryInput} for the database tool's
+ * parsed SERIALIZED query — each condition's OMITTED `connector` defaults to `'and'`.
+ *
+ * @remarks
+ * The wire form ({@link import('./shapers.js').databaseToolShape}) lets a caller drop `connector`
+ * on the last condition (it has nothing to join FORWARD to); the compiled `Condition` a live
+ * `@orkestrel/database` table call accepts always carries one, so this fills the gap. `order` /
+ * `limit` / `offset` pass through unchanged. Pure and total.
+ *
+ * @param query - The parsed query (or `undefined`)
+ * @returns The equivalent live `QueryInput`, or `undefined` when `query` is `undefined`
+ */
+export declare function normalizeQuery(query: DatabaseQueryInput | undefined): QueryInput | undefined;
+
+/** Describes one sort term. */
 export declare const orderShape: ObjectShape<{
     column: StringShape;
     direction: LiteralShape<readonly ["ascending", "descending"]>;
 }, false>;
 
-/** A draft phase — a `PhaseDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name` and {@link TaskDraft} tasks. */
+/** Represents a draft phase — a `PhaseDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name` and {@link TaskDraft} tasks. */
 export declare interface PhaseDraft {
     readonly id?: string;
     readonly name?: string;
     readonly description?: string;
     readonly tasks: readonly TaskDraft[];
-    /** Max tasks in flight at once (a resource throttle); omitted ⇒ unbounded. */
+    /** Caps the tasks in flight at once (a resource throttle); omitted ⇒ unbounded. */
     readonly concurrency?: number;
-    /** The per-phase failure-policy OVERRIDE; omitted ⇒ inherits the workflow `bail`. */
+    /** Holds the per-phase failure-policy OVERRIDE; omitted ⇒ inherits the workflow `bail`. */
     readonly bail?: boolean;
 }
 
 /**
- * The shape of a PHASE in a draft workflow — identical to a strict phase shape EXCEPT `id` and
+ * Describes the shape of a PHASE in a draft workflow — identical to a strict phase shape EXCEPT `id` and
  * `name` are OPTIONAL, and its tasks are {@link taskDraftShape}s.
  */
 export declare const phaseDraftShape: ObjectShape<{
@@ -1774,7 +1901,7 @@ export declare const phaseDraftShape: ObjectShape<{
         id: OptionalShape<StringShape>;
         name: OptionalShape<StringShape>;
         description: OptionalShape<StringShape>;
-        run: OptionalShape<StringShape>;
+        behavior: OptionalShape<StringShape>;
         retries: OptionalShape<NumberShape>;
         timeout: OptionalShape<NumberShape>;
     }, false>>;
@@ -1782,26 +1909,26 @@ export declare const phaseDraftShape: ObjectShape<{
     bail: OptionalShape<LiteralShape<readonly [true, false]>>;
 }, false>;
 
-/** The full form protocol {@link import('./factories.js').createPromptTool} advertises. */
+/** Holds the full form protocol {@link import('./factories.js').createPromptTool} advertises. */
 export declare const PROMPT_TOOL_DESCRIPTION: string;
 
 /**
- * The name {@link import('./factories.js').createPromptTool} advertises by default — the key a
+ * Holds the name {@link import('./factories.js').createPromptTool} advertises by default — the key a
  * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
  */
 export declare const PROMPT_TOOL_NAME = "ask";
 
 /**
- * The lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createPromptTool}
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createPromptTool}
  * advertises in place of {@link PROMPT_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
  * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable via
+ * for the full teaching description; the full text stays retrievable through
  * {@link import('./factories.js').createDescribeTool}.
  */
 export declare const PROMPT_TOOL_SUMMARY = "Ask another terminal a multi-field form and BLOCK until it answers; the call resolves with the values record. Call describe('ask') for the schema.";
 
 /**
- * Options for {@link import('./factories.js').createPromptTool} — the live
+ * Represents the options for {@link import('./factories.js').createPromptTool} — the live
  * {@link TerminalManagerInterface} (`@orkestrel/terminal`) to `ask` through, the terminal name
  * `from`, and the advertised tool overrides.
  *
@@ -1823,7 +1950,7 @@ export declare interface PromptToolOptions {
 }
 
 /**
- * The shape of {@link import('./factories.js').createPromptTool}'s call arguments — `to` names the
+ * Describes the shape of {@link import('./factories.js').createPromptTool}'s call arguments — `to` names the
  * terminal identity and `schema` carries the complete multi-field form document.
  *
  * @remarks
@@ -1835,35 +1962,7 @@ export declare const promptToolShape: ObjectShape<{
     schema: JSONShape;
 }, false>;
 
-/**
- * Normalize the database tool's parsed SERIALIZED query into a live `@orkestrel/database`
- * {@link QueryInput} — default each condition's OMITTED `connector` to `'and'`.
- *
- * @remarks
- * The wire form ({@link import('./shapers.js').databaseToolShape}) lets a caller drop `connector`
- * on the last condition (it has nothing to join FORWARD to); the compiled `Condition` a live
- * `@orkestrel/database` table call accepts always carries one, so this fills the gap. `order` /
- * `limit` / `offset` pass through unchanged. Pure and total.
- *
- * @param query - The parsed query (or `undefined`)
- * @returns The equivalent live `QueryInput`, or `undefined` when `query` is `undefined`
- */
-export declare function queryOf(query: Readonly<{
-    conditions?: ReadonlyArray<Readonly<{
-        column: string;
-        operator: Condition['operator'];
-        values: readonly unknown[];
-        connector?: ConditionConnector;
-    }>>;
-    order?: ReadonlyArray<Readonly<{
-        column: string;
-        direction: OrderDirection;
-    }>>;
-    limit?: number;
-    offset?: number;
-}> | undefined): QueryInput | undefined;
-
-/** The SERIALIZED query form — conditions, order, and pagination. */
+/** Describes the SERIALIZED query form — conditions, order, and pagination. */
 export declare const queryShape: ObjectShape<{
     conditions: OptionalShape<ArrayShape<ObjectShape<{
         column: StringShape;
@@ -1879,11 +1978,11 @@ export declare const queryShape: ObjectShape<{
     offset: OptionalShape<NumberShape>;
 }, false>;
 
-/** The default cap on how many `include` path segments deep a `load` / `find` call may traverse — the relation tool's default include-depth ceiling. */
+/** Holds the default cap on how many `include` path segments deep a `load` / `find` call may traverse — the relation tool's default include-depth ceiling. */
 export declare const RELATION_TOOL_DEPTH = 3;
 
 /**
- * The DESCRIPTION the relation tool advertises — a multi-line guide that teaches a small model
+ * Holds the DESCRIPTION the relation tool advertises — a multi-line guide that teaches a small model
  * the operation list and the flat dot-path `include` syntax.
  *
  * @remarks
@@ -1892,64 +1991,23 @@ export declare const RELATION_TOOL_DEPTH = 3;
  */
 export declare const RELATION_TOOL_DESCRIPTION: string;
 
-/** The default cap on rows a `find` / `links` call returns when the caller omits `limit` — the relation tool's default row ceiling. */
+/** Holds the default cap on rows a `find` / `links` call returns when the caller omits `limit` — the relation tool's default row ceiling. */
 export declare const RELATION_TOOL_LIMIT = 1000;
 
 /**
- * The name `createRelationTool` advertises by default — the key a model calls and the
+ * Holds the name `createRelationTool` advertises by default — the key a model calls and the
  * `ToolManagerInterface` (`@orkestrel/tool`) registers under.
  */
 export declare const RELATION_TOOL_NAME = "relation";
 
 /**
- * The lean {@link import('@orkestrel/tool').ToolInterface.summary} the relation tool advertises
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} the relation tool advertises
  * in place of {@link RELATION_TOOL_DESCRIPTION}.
  */
 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<readonly [ ArrayShape<UnionShape<readonly [ StringShape, NumberShape]>>, StringShape, NumberShape]>;
-
-/**
- * Resolve which registered {@link RelationManagerInterface} a relation-tool call addresses — the
- * pure manager-resolution leaf {@link import('./factories.js').createRelationTool} calls on
- * every operation.
- *
- * @remarks
- * An explicit `name` must match a key of `managers` (a miss throws a typed `TOOL`
- * {@link ToolboxError} naming the registered managers). An OMITTED `name` resolves to the sole
- * registered manager when exactly one is registered, else throws the same typed error.
- *
- * @param managers - The tool's registered `RelationManagerInterface` map
- * @param name - The call's optional `manager` field
- * @returns The resolved {@link RelationManagerInterface}
- */
-export declare function relationManagerOf(managers: Readonly<Record<string, RelationManagerInterface>>, name: string | undefined): RelationManagerInterface;
-
-/**
- * Resolve a `model` name against a live {@link RelationManagerInterface} — the pure model-lookup
- * leaf {@link import('./factories.js').createRelationTool} calls on every operation, mirroring
- * {@link relationManagerOf}'s guard shape.
- *
- * @param manager - The resolved {@link RelationManagerInterface}
- * @param name - The call's `model` field
- * @returns The model's {@link ModelInterface}
- */
-export declare function relationModelOf(manager: RelationManagerInterface, name: string): ModelInterface;
-
-/**
- * Map a caught error to the {@link ToolboxErrorCode} the upcoming relation tool should throw
- * with — the pure classification step of that factory's error handling, mirroring
- * {@link terminalToolCode}'s idiom for `@orkestrel/relation`.
- *
- * @param error - The value caught from a `@orkestrel/relation` operation
- * @returns The granular {@link RelationErrorCode}, or `undefined` if `error` is not a `RelationError`
- */
-export declare function relationToolCode(error: unknown): RelationErrorCode | undefined;
-
 /**
- * Options for {@link import('./factories.js').createRelationTool} — SRC-3 (the final unit) of
- * the 3-unit database / relation spine.
+ * Represents the options for {@link import('./factories.js').createRelationTool}.
  *
  * @remarks
  * - `managers` — the live `RelationManagerInterface` (`@orkestrel/relation`) registry a call's
@@ -1975,7 +2033,7 @@ export declare interface RelationToolOptions {
 }
 
 /**
- * The shape of {@link import('./factories.js').createRelationTool}'s call arguments —
+ * Describes the shape of {@link import('./factories.js').createRelationTool}'s call arguments —
  * discriminated by `operation` into the 5 relation operations (`'load'` / `'find'` / `'link'` /
  * `'unlink'` / `'links'`).
  *
@@ -2021,20 +2079,71 @@ export declare const relationToolShape: UnionShape<readonly [ ObjectShape<{
     relation: StringShape;
 }, false>]>;
 
-/** A loose row — a flat object of column name to JSON value; the array form (multiple rows) resolves FIRST per AGENTS §9.2. */
+/**
+ * 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.
+ *
+ * @remarks
+ * The one place the database tool's `'records'` clamp ({@link clampQuery}) and the relation tool's
+ * `'find'` / `'links'` truncation both take their ceiling from, so a negative construction-time
+ * option can never reach a slice. Pure and total.
+ *
+ * @example
+ * ```ts
+ * import { resolveLimit } from '@src/core'
+ *
+ * resolveLimit(undefined, 100) // 100 — an omitted request takes the cap
+ * resolveLimit(500, 100) // 100 — a request over the cap is clamped down
+ * resolveLimit(-1, 100) // 0 — a negative request floors at zero
+ * ```
+ *
+ * @param requested - The caller's requested row count (or `undefined`)
+ * @param cap - The row-count ceiling
+ * @returns The effective row limit, never below `0` and never above `cap`
+ */
+export declare function resolveLimit(requested: number | undefined, cap: number): number;
+
+/**
+ * Resolves which registered {@link RelationManagerInterface} a relation-tool call addresses — the
+ * pure manager-resolution leaf {@link import('./factories.js').createRelationTool} calls on
+ * every operation.
+ *
+ * @remarks
+ * An explicit `name` must match a key of `managers` (a miss throws a typed `TOOL`
+ * {@link ToolboxError} naming the registered managers). An OMITTED `name` resolves to the sole
+ * registered manager when exactly one is registered, else throws the same typed error.
+ *
+ * @param managers - The tool's registered `RelationManagerInterface` map
+ * @param name - The call's optional `manager` field
+ * @returns The resolved {@link RelationManagerInterface}
+ */
+export declare function resolveRelationManager(managers: Readonly<Record<string, RelationManagerInterface>>, name: string | undefined): RelationManagerInterface;
+
+/**
+ * Resolves a `model` name against a live {@link RelationManagerInterface} — the pure model-lookup
+ * leaf {@link import('./factories.js').createRelationTool} calls on every operation, mirroring
+ * {@link resolveRelationManager}'s guard shape.
+ *
+ * @param manager - The resolved {@link RelationManagerInterface}
+ * @param name - The call's `model` field
+ * @returns The model's {@link ModelInterface}
+ */
+export declare function resolveRelationModel(manager: RelationManagerInterface, name: string): ModelInterface;
+
+/** Describes a loose row — a flat object of column name to JSON value; the array form (multiple rows) resolves FIRST, so an array argument is read as many rows rather than one. */
 export declare const rowShape: ObjectShape<Record<never, never>, JSONShape>;
 
-/** One or many loose rows — the array form resolves FIRST per AGENTS §9.2. */
+/** Describes one or many loose rows — the array form resolves FIRST, so an array argument is read as many rows rather than one. */
 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. */
+/** Describes a single row key (not an array) — used by `'link'` / `'unlink'` / `'links'`, which address exactly one owning row. */
 export declare const singleKeyShape: UnionShape<readonly [ StringShape, NumberShape]>;
 
 /**
- * The shape of ONE flat step — `{ name }` — the building block of {@link workflowStepsShape}.
+ * Describes the shape of ONE flat step — `{ name }` — the building block of {@link workflowStepsShape}.
  *
  * @remarks
- * `name` is the REGISTERED behavior name the step runs (it becomes the task's `run`). The tool
+ * `name` is the REGISTERED behavior name the step runs (it becomes the task's `behavior`). The tool
  * expands each step into a one-task phase, in order ({@link import('./helpers.js').expandSteps}).
  */
 export declare const stepShape: ObjectShape<{
@@ -2042,24 +2151,66 @@ export declare const stepShape: ObjectShape<{
 }, false>;
 
 /**
- * A database's table layout — one entry per table, each a flat map of column name to
- * {@link ColumnSpec}. The small-model-facing DSL {@link import('./helpers.js').expandTables}
+ * Builds the plain success summary {@link import('./factories.js').createWorkflowTool} returns on
+ * a completed run — the universal tool-handler contract: return a plain value on success,
+ * appearing identically over BOTH the agent loop and MCP.
+ *
+ * @remarks
+ * The summary is LEAN: the workflow's terminal `status`, settled-task count, and exact optional
+ * native persistence outcome. It carries no synthetic `id` / `name`: a tool handler has no call
+ * id; the `ToolManagerInterface` (`@orkestrel/tool`) supplies the canonical envelope's identity.
+ *
+ * @param result - The terminal `WorkflowResult` (`@orkestrel/workflow`) the run produced
+ * @returns The plain success summary — `{ status, count, durable?, fault? }`
+ */
+export declare function summarizeWorkflow(result: WorkflowResult): WorkflowToolResult;
+
+/**
+ * Represents a database's table layout — one entry per table, each a flat map of column name to
+ * {@link ColumnSpec}. The small-model-facing DSL {@link import('./compilers.js').expandTables}
  * compiles into an `@orkestrel/database` `TableMap`.
  */
 export declare type TableSpec = Readonly<Record<string, Readonly<{
     columns: Readonly<Record<string, ColumnSpec>>;
 }>>>;
 
-/** A {@link import('./types.js').TableSpec} — table name to `{ columns }`, each column a {@link columnSpecShape}. */
+/** Describes 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<readonly [ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
-        type: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
+        primitive: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
         optional: OptionalShape<BooleanShape>;
     }, false>]>>;
 }, false>>;
 
 /**
- * A draft task — a `TaskDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name`.
+ * Returns the ancestry identifier of an agent in a run chain — `agent:<name>`.
+ *
+ * @remarks
+ * The agent counterpart of {@link tagWorkflow}: {@link import('./factories.js').createAgentFunction}
+ * / {@link import('./factories.js').createWorkflowTool} guard against re-entering an agent or
+ * workflow already in the chain (this package's typed `DEPTH` `ToolboxError`). The
+ * `agent:` namespace keeps it distinct from a same-string workflow id.
+ *
+ * @param name - The agent's identifier / registry name
+ * @returns The namespaced ancestry tag (`agent:<name>`)
+ */
+export declare function tagAgent(name: string): string;
+
+/**
+ * Returns the ancestry identifier of a workflow in a run chain — `workflow:<id>`.
+ *
+ * @remarks
+ * Namespacing keeps a workflow id and a {@link tagAgent} agent name in ONE set without
+ * collision, so re-entering a workflow OR an agent already in the chain is a single `includes`
+ * check.
+ *
+ * @param id - The workflow definition's `id`
+ * @returns The namespaced ancestry tag (`workflow:<id>`)
+ */
+export declare function tagWorkflow(id: string): string;
+
+/**
+ * Represents a draft task — a `TaskDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name`.
  *
  * @remarks
  * The tool synthesizes a missing `id` positionally and defaults a missing `name` to its `id`
@@ -2070,46 +2221,29 @@ export declare interface TaskDraft {
     readonly id?: string;
     readonly name?: string;
     readonly description?: string;
-    /** The behavior reference — a registry key resolved against a workflow's functions registry at construction; omitted ⇒ a deliberate JSON `null` no-op. */
-    readonly run?: string;
-    /** Extra attempts after the first on failure (a non-negative integer); persisted with the workflow. */
+    /** Holds the registry key resolved against a workflow's functions registry at construction; omitted ⇒ a deliberate JSON `null` no-op. */
+    readonly behavior?: string;
+    /** Holds the extra attempts after the first on failure (a non-negative integer); persisted with the workflow. */
     readonly retries?: number;
-    /** The per-attempt deadline in milliseconds (`0..MAX_TIMER_MS`); persisted with the workflow. */
+    /** Holds the per-attempt deadline in milliseconds (`0..MAX_TIMER_MS`); persisted with the workflow. */
     readonly timeout?: number;
 }
 
 /**
- * The shape of a {@link import('./types.js').TaskDraft} — identical to a strict task shape
+ * Describes the shape of a {@link import('./types.js').TaskDraft} — identical to a strict task shape
  * EXCEPT `id` and `name` are OPTIONAL.
  */
 export declare const taskDraftShape: ObjectShape<{
     id: OptionalShape<StringShape>;
     name: OptionalShape<StringShape>;
     description: OptionalShape<StringShape>;
-    run: OptionalShape<StringShape>;
+    behavior: OptionalShape<StringShape>;
     retries: OptionalShape<NumberShape>;
     timeout: OptionalShape<NumberShape>;
 }, false>;
 
 /**
- * Map a caught error to the {@link ToolboxErrorCode} the terminal-tool factory should throw
- * with — the pure classification step of that factory's error handling.
- *
- * @remarks
- * Narrows `error` with {@link isTerminalError} (`@orkestrel/terminal`) first: a non-`TerminalError`
- * value returns `undefined`, telling the caller this mapper does not apply (rethrow / handle
- * otherwise). For a genuine `TerminalError`, `'DEADLOCK'` maps to `'DEADLOCK'`, `'EXPIRE'` maps
- * to `'EXPIRE'`, and every other {@link import('@orkestrel/terminal').TerminalErrorCode}
- * (`'TARGET'`, `'LIMIT'`, `'CANCEL'`, `'DRIVER'`, `'DESTROYED'`) maps to the generic `'TOOL'`
- * code. The mapper only classifies — the factory performs the actual throw.
- *
- * @param error - The value caught from a terminal-manager operation (`ask` / `answer` / …)
- * @returns The mapped {@link ToolboxErrorCode}, or `undefined` if `error` is not a `TerminalError`
- */
-export declare function terminalToolCode(error: unknown): ToolboxErrorCode | undefined;
-
-/**
- * A package-owned tool-call failure: malformed input or unresolved configuration (`TOOL`),
+ * Represents a package-owned tool-call failure: malformed input or unresolved configuration (`TOOL`),
  * delegation depth/cycle rejection (`DEPTH`), prompt failure (`DEADLOCK` / `EXPIRE` / `ANSWER`),
  * or a translated upstream database/relation failure (`DATABASE` / `RELATION`).
  *
@@ -2138,9 +2272,8 @@ export declare class ToolboxError extends Error {
 }
 
 /**
- * The seven-value machine-readable code a thrown
- * {@link import('./errors.js').ToolboxError} carries (AGENTS §14: a thrown, typed,
- * code-bearing error, never a `{ error }` return).
+ * Represents the machine-readable code a thrown {@link import('./errors.js').ToolboxError} carries — a
+ * thrown, typed, code-bearing error, never a `{ error }` return.
  *
  * @remarks
  * `TOOL` — malformed calls and package-owned resolution or configuration failures, including
@@ -2163,26 +2296,26 @@ export declare class ToolboxError extends Error {
 export declare type ToolboxErrorCode = 'TOOL' | 'DEPTH' | 'DEADLOCK' | 'EXPIRE' | 'ANSWER' | 'DATABASE' | 'RELATION';
 
 /**
- * The description {@link import('./factories.js').createWorkflowTool} advertises — the flat
+ * Holds the description {@link import('./factories.js').createWorkflowTool} advertises — the flat
  * authoring form, its worked example, and the advanced nested definition form.
  */
 export declare const WORKFLOW_TOOL_DESCRIPTION: string;
 
 /**
- * A complete FLAT authoring example — the PRIMARY way a small model authors a workflow through
+ * Holds a complete FLAT authoring example — the PRIMARY way a small model authors a workflow through
  * {@link import('./factories.js').createWorkflowTool}: `{ name, steps: [{ name }] }`.
  *
  * @remarks
  * Each step becomes a one-task phase, in
  * order; a step's `name` is a REGISTERED behavior name (not a label) — the registry key its
- * task's `run` resolves against. The tool expands this
+ * task's `behavior` resolves against. The tool expands this
  * ({@link import('./helpers.js').expandSteps}) into a valid `WorkflowDefinition`
  * (`@orkestrel/workflow`). It is embedded VERBATIM in {@link WORKFLOW_TOOL_DESCRIPTION}.
  */
 export declare const WORKFLOW_TOOL_FLAT_EXAMPLE: WorkflowSteps;
 
 /**
- * The name {@link import('./factories.js').createWorkflowTool} advertises by default — the key a
+ * Holds the name {@link import('./factories.js').createWorkflowTool} advertises by default — the key a
  * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under, and the name
  * {@link import('./factories.js').createAgentFunction} binds the depth/cycle-aware workflow tool
  * under onto a wrapped agent's `context.tools`.
@@ -2191,12 +2324,12 @@ export declare const WORKFLOW_TOOL_FLAT_EXAMPLE: WorkflowSteps;
  * The propagation seam's well-known key: when
  * `createAgentFunction`'s `runner` option is supplied, it adds a `createWorkflowTool`-built tool
  * under this name to the agent's `context.tools`, so it can author + run a NESTED workflow
- * (bounded by {@link MAX_WORKFLOW_DEPTH}).
+ * (bounded by {@link MAX_WORKFLOW_CHAIN}).
  */
 export declare const WORKFLOW_TOOL_NAME = "workflow";
 
 /**
- * A minimal NESTED authoring example — the ADVANCED escape-hatch form a model may use instead of
+ * Holds a minimal NESTED authoring example — the ADVANCED escape-hatch form a model may use instead of
  * the flat shape: a full `WorkflowDefinition` (`@orkestrel/workflow`).
  *
  * @remarks
@@ -2206,25 +2339,25 @@ export declare const WORKFLOW_TOOL_NAME = "workflow";
 export declare const WORKFLOW_TOOL_NESTED_EXAMPLE: WorkflowDefinition;
 
 /**
- * The lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createWorkflowTool}
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createWorkflowTool}
  * advertises in place of {@link WORKFLOW_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
  * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable via
+ * for the full teaching description; the full text stays retrievable through
  * {@link import('./factories.js').createDescribeTool}.
  */
 export declare const WORKFLOW_TOOL_SUMMARY = "Author and run a multi-phase workflow in one call \u2014 phases run in sequence, tasks within a phase run concurrently. Call describe('workflow') for the full authoring schema and examples.";
 
-/** Raw live agents keyed by the workflow function names that invoke them. */
+/** Represents raw live agents keyed by the workflow function names that invoke them. */
 export declare type WorkflowAgents = Readonly<Record<string, AgentInterface>>;
 
 /**
- * A draft workflow — a `WorkflowDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name`
+ * Represents a draft workflow — a `WorkflowDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name`
  * at all three levels (workflow / phase / task).
  *
  * @remarks
  * The lenient authoring form {@link import('./factories.js').createWorkflowDraftContract}
  * validates and {@link import('./helpers.js').completeDraft} completes into a strict
- * `WorkflowDefinition`. `run` stays optional (a plain name string); the `bail` policy carries
+ * `WorkflowDefinition`. `behavior` stays optional (a plain name string); the `bail` policy carries
  * over.
  */
 export declare interface WorkflowDraft {
@@ -2232,18 +2365,18 @@ export declare interface WorkflowDraft {
     readonly name?: string;
     readonly description?: string;
     readonly phases: readonly PhaseDraft[];
-    /** Failure policy: `false` (default) continues gracefully, `true` halts on the first failure. */
+    /** Holds the failure policy: `false` (default) continues gracefully, `true` halts on the first failure. */
     readonly bail?: boolean;
 }
 
 /**
- * The shape of a DRAFT workflow — identical to a strict workflow shape EXCEPT `id` and `name`
+ * Describes the shape of a DRAFT workflow — identical to a strict workflow shape EXCEPT `id` and `name`
  * are OPTIONAL at all three levels (workflow / phase / task), so a small model can omit the six
  * identity strings and let the tool synthesize them positionally.
  *
  * @remarks
  * The lenient counterpart {@link import('./factories.js').createWorkflowDraftContract} compiles.
- * `run` stays optional like the strict form; omission is the deliberate JSON `null` no-op. A
+ * `behavior` stays optional like the strict form; omission is the deliberate JSON `null` no-op. A
  * provided `id` / `name` still has `minLength: 1` (so
  * an explicitly-empty `id: ''` is REJECTED, not auto-filled). After
  * {@link import('./helpers.js').completeDraft} fills the missing ids/names, the result is
@@ -2262,7 +2395,7 @@ export declare const workflowDraftShape: ObjectShape<{
             id: OptionalShape<StringShape>;
             name: OptionalShape<StringShape>;
             description: OptionalShape<StringShape>;
-            run: OptionalShape<StringShape>;
+            behavior: OptionalShape<StringShape>;
             retries: OptionalShape<NumberShape>;
             timeout: OptionalShape<NumberShape>;
         }, false>>;
@@ -2272,23 +2405,23 @@ export declare const workflowDraftShape: ObjectShape<{
     bail: OptionalShape<LiteralShape<readonly [true, false]>>;
 }, false>;
 
-/** One immutable workflow/agent call chain, beginning with a workflow tag. */
+/** Represents one immutable workflow/agent call chain, beginning with a workflow tag. */
 export declare type WorkflowLineage = readonly string[];
 
 /**
- * One flat step — `{ name }` — the building block of a {@link WorkflowSteps} blob.
+ * Represents one flat step — `{ name }` — the building block of a {@link WorkflowSteps} blob.
  *
  * @remarks
- * `name` is the REGISTERED behavior name the step runs (it becomes the task's `run`, NOT a
+ * `name` is the REGISTERED behavior name the step runs (it becomes the task's `behavior`, NOT a
  * human label) — resolved against a workflow-level functions registry at construction.
  */
 export declare interface WorkflowStep {
-    /** The registered behavior name this step runs (becomes the task's `run`). */
+    /** Names the registered behavior this step runs (becomes the task's `behavior`). */
     readonly name: string;
 }
 
 /**
- * The FLAT authoring blob {@link import('./factories.js').createWorkflowTool} advertises —
+ * Represents the FLAT authoring blob {@link import('./factories.js').createWorkflowTool} advertises —
  * `{ name?, steps }` — the simplest surface a small model can fill.
  *
  * @remarks
@@ -2302,7 +2435,7 @@ export declare interface WorkflowSteps {
 }
 
 /**
- * The FLAT authoring shape {@link import('./factories.js').createWorkflowTool} advertises as its
+ * Describes the FLAT authoring shape {@link import('./factories.js').createWorkflowTool} advertises as its
  * `parameters` — the simplest surface a small model can fill: `{ name?, steps: [{ name }] }`.
  *
  * @remarks
@@ -2322,20 +2455,7 @@ export declare const workflowStepsShape: ObjectShape<{
 }, false>;
 
 /**
- * The ancestry identifier of a workflow in a run chain — `workflow:<id>`.
- *
- * @remarks
- * Namespacing keeps a workflow id and an {@link agentTag} agent name in ONE set without
- * collision, so re-entering a workflow OR an agent already in the chain is a single `includes`
- * check.
- *
- * @param id - The workflow definition's `id`
- * @returns The namespaced ancestry tag (`workflow:<id>`)
- */
-export declare function workflowTag(id: string): string;
-
-/**
- * Options for {@link import('./factories.js').createWorkflowTool} and
+ * Represents the options for {@link import('./factories.js').createWorkflowTool} and
  * {@link import('./factories.js').createWorkflowFunctions} — lineage-aware composition of opaque
  * leaves, raw agents, and native workflow persistence.
  *
@@ -2348,40 +2468,25 @@ export declare function workflowTag(id: string): string;
  */
 export declare interface WorkflowToolOptions {
     readonly lineage?: WorkflowLineage;
-    readonly functions?: WorkflowFunctions;
+    readonly functions?: WorkflowRegistry;
     readonly agents?: WorkflowAgents;
     readonly store?: WorkflowStoreInterface;
 }
 
-/** The JSON-safe run summary returned by {@link import('./factories.js').createWorkflowTool}. */
+/** Represents the JSON-safe run summary returned by {@link import('./factories.js').createWorkflowTool}. */
 export declare interface WorkflowToolResult {
-    /** The workflow's native terminal status. */
-    readonly status: WorkflowStatus;
-    /** The number of settled task results. */
+    /** Holds the run's terminal {@link LifecycleStatus}. */
+    readonly status: LifecycleStatus;
+    /** Holds the tally of settled task results. */
     readonly count: number;
-    /** Whether the native runner stored its final state; omitted when no store was supplied. */
+    /** Reports whether the native runner stored its final state; omitted when no store was supplied. */
     readonly durable?: boolean;
-    /** The native runner's first persistence failure; omitted when none occurred. */
+    /** Holds the native runner's first persistence failure; omitted when none occurred. */
     readonly fault?: WorkflowFault;
 }
 
 /**
- * Build the plain success summary {@link import('./factories.js').createWorkflowTool} returns on
- * a completed run — the universal tool-handler contract (AGENTS §14): return a plain value on
- * success, appearing identically over BOTH the agent loop and MCP.
- *
- * @remarks
- * The summary is LEAN: the workflow's terminal `status`, settled-task count, and exact optional
- * native persistence outcome. It carries no synthetic `id` / `name`: a tool handler has no call
- * id; the `ToolManagerInterface` (`@orkestrel/tool`) supplies the canonical envelope's identity.
- *
- * @param result - The terminal `WorkflowResult` (`@orkestrel/workflow`) the run produced
- * @returns The plain success summary — `{ status, count, durable?, fault? }`
- */
-export declare function workflowToolSummary(result: WorkflowResult): WorkflowToolResult;
-
-/**
- * The description {@link import('./factories.js').createWorkspaceTool} advertises — the
+ * Holds the description {@link import('./factories.js').createWorkspaceTool} advertises — the
  * operation-keyed workspace protocol, all supported operations, and worked examples.
  *
  * @remarks
@@ -2391,7 +2496,7 @@ export declare function workflowToolSummary(result: WorkflowResult): WorkflowToo
 export declare const WORKSPACE_TOOL_DESCRIPTION: string;
 
 /**
- * A valid {@link import('./types.js').WorkspaceOperation} object — the canonical example embedded
+ * Holds a valid {@link import('./types.js').WorkspaceOperation} object — the canonical example embedded
  * VERBATIM in {@link WORKSPACE_TOOL_DESCRIPTION}.
  *
  * @remarks
@@ -2402,25 +2507,25 @@ export declare const WORKSPACE_TOOL_DESCRIPTION: string;
 export declare const WORKSPACE_TOOL_EXAMPLE: WorkspaceOperation;
 
 /**
- * The name {@link import('./factories.js').createWorkspaceTool} advertises by default — the key a
+ * Holds the name {@link import('./factories.js').createWorkspaceTool} advertises by default — the key a
  * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
  */
 export declare const WORKSPACE_TOOL_NAME = "workspace";
 
 /**
- * The lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createWorkspaceTool}
+ * Holds the lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createWorkspaceTool}
  * advertises in place of {@link WORKSPACE_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
  * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
- * for the full teaching description; the full text stays retrievable via
+ * for the full teaching description; the full text stays retrievable through
  * {@link import('./factories.js').createDescribeTool}.
  */
 export declare const WORKSPACE_TOOL_SUMMARY = "Read and edit files in a workspace \u2014 one operation per call (read, write, list, search, replace, splice, move, remove, plus workspace switching), chosen by the 'operation' field. Call describe('workspace') for the full operation list and fields.";
 
 /**
- * One operation an agent invokes through {@link import('./factories.js').createWorkspaceTool} — a
- * FLAT, descriptive tagged union over the 13 workspace edit / read / navigation actions,
- * discriminated by the `operation` literal (AGENTS §4.8: a discriminant is named for its axis —
- * the action being performed — NEVER `kind`).
+ * Represents one operation an agent invokes through {@link import('./factories.js').createWorkspaceTool} — a
+ * FLAT, descriptive tagged union over the workspace edit, read, and navigation actions,
+ * discriminated by the `operation` literal (a discriminant is named for its axis — the action
+ * being performed — NEVER `kind`).
  *
  * @remarks
  * This is the SOURCE OF TRUTH the tool contract is typed to
@@ -2436,22 +2541,22 @@ export declare const WORKSPACE_TOOL_SUMMARY = "Read and edit files in a workspac
  * the edit / read arms target.
  */
 export declare type WorkspaceOperation = 
-/** Read 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 no content). */
     {
     readonly operation: 'read';
     readonly path: string;
 }
-/** List every file in the ACTIVE workspace (path / state / size / lines / kind summaries); `[]` when no workspace is active. */
+/** Lists every file in the ACTIVE workspace (path / state / size / lines / kind summaries); `[]` when no workspace is active. */
 | {
     readonly operation: 'list';
 }
-/** Whether a file exists at `path` in the ACTIVE workspace (`false` when no workspace is active). */
+/** Reports whether a file exists at `path` in the ACTIVE workspace (`false` when no workspace is active). */
 | {
     readonly operation: 'has';
     readonly path: string;
 }
 /**
-* Scan every text file for `query`, returning each hit (path + 1-based line / column + the line).
+* Scans every text file for `query`, returning each hit (path + 1-based line / column + the line).
 *
 * @remarks
 * `regex` treats `query` as a regular-expression source (default `false` — a literal substring);
@@ -2465,7 +2570,7 @@ export declare type WorkspaceOperation =
     readonly limit?: number;
 }
 /**
-* Replace `query` with `replacement` across every text file, returning the tally.
+* Replaces `query` with `replacement` across every text file, returning the tally.
 *
 * @remarks
 * Same matching axes as `search`: `regex` (default `false`), `sensitive` (default `true`),
@@ -2479,21 +2584,21 @@ export declare type WorkspaceOperation =
     readonly sensitive?: boolean;
     readonly limit?: number;
 }
-/** Write (create or overwrite) the whole file at `path` with `content`. */
+/** Writes (creates or overwrites) the whole file at `path` with `content`. */
 | {
     readonly operation: 'write';
     readonly path: string;
     readonly content: string;
 }
 /**
-* Splice `content` into an existing text file, replacing the 1-based range
+* Splices `content` into an existing text file, replacing the 1-based range
 * `(fromLine, fromColumn)` (INCLUSIVE) → `(toLine, toColumn)` (EXCLUSIVE).
 *
 * @remarks
 * The FLAT range edit — the four positive-integer caret components reassemble into a `Range`
-* (`@orkestrel/workspace`) via `rangeOf`. An empty span (`from === to`) inserts; a span past
+* (`@orkestrel/workspace`) through `rangeOf`. An empty span (`from === to`) inserts; a span past
 * the end is clamped. An inverted / sub-1 range throws `RANGE`; a binary target throws
-* `MODALITY`.
+* `MODALITY`; a missing target throws `MISSING`.
 */
 | {
     readonly operation: 'splice';
@@ -2504,41 +2609,41 @@ export declare type WorkspaceOperation =
     readonly toLine: number;
     readonly toColumn: number;
 }
-/** Prepend `content` to the start of the file at `path` (creating it when absent). */
+/** Prepends `content` to the start of the file at `path` (creating it when absent). */
 | {
     readonly operation: 'prepend';
     readonly path: string;
     readonly content: string;
 }
-/** Append `content` to the end of the file at `path` (creating it when absent). */
+/** Appends `content` to the end of the file at `path` (creating it when absent). */
 | {
     readonly operation: 'append';
     readonly path: string;
     readonly content: string;
 }
-/** Re-key the file `from` → `to` (overwriting an occupied target). */
+/** Re-keys the file `from` → `to` (overwriting an occupied target). */
 | {
     readonly operation: 'move';
     readonly from: string;
     readonly to: string;
 }
-/** Remove the file at `path` from the workspace. */
+/** Removes the file at `path` from the workspace. */
 | {
     readonly operation: 'remove';
     readonly path: string;
 }
-/** List the workspaces the model can move between — each `{ id, files, active }` — so it can choose an `id` to `switch` to. */
+/** Lists the workspaces the model can move between — each `{ id, files, active }` — so it can choose an `id` to `switch` to. */
 | {
     readonly operation: 'workspaces';
 }
-/** Re-point the manager's ACTIVE workspace to the one with `id` (an unknown `id` is a lenient no-op). The edit / read arms target the active workspace from then on. */
+/** Re-points the manager's ACTIVE workspace to the one with `id` (an unknown `id` is a lenient no-op). The edit / read arms target the active workspace from then on. */
 | {
     readonly operation: 'switch';
     readonly id: string;
 };
 
 /**
- * Options for {@link import('./factories.js').createWorkspaceTool} — EITHER a caller-built
+ * Represents the options for {@link import('./factories.js').createWorkspaceTool} — EITHER a caller-built
  * {@link WorkspaceManagerInterface} to drive directly, OR a {@link WorkspaceStoreInterface} the
  * tool constructs a fresh manager over; neither given constructs a manager over
  * `@orkestrel/workspace`'s in-memory store.
@@ -2546,7 +2651,7 @@ export declare type WorkspaceOperation =
  * @remarks
  * - `manager` — drive THIS manager directly (its `active` workspace is what every edit / read
  *   operation targets). Takes priority over `store` when both are supplied.
- * - `store` — construct a manager over this durable {@link WorkspaceStoreInterface} (via
+ * - `store` — construct a manager over this durable {@link WorkspaceStoreInterface} (through
  *   `@orkestrel/workspace`'s `createWorkspaceManager`) — used only when `manager` is omitted.
  *   The store only backs the manager's own `open` / `save` operations: the tool's edits are
  *   NOT auto-persisted — durability requires an explicit caller `save` on the manager
@@ -2562,10 +2667,10 @@ export declare interface WorkspaceToolOptions {
 }
 
 /**
- * The shape of a {@link import('./types.js').WorkspaceOperation} — a descriptive tagged union
- * over the 13 workspace edit / read / navigation operations, discriminated by the `operation`
- * literal (never a bare `kind`; AGENTS §4.4). Each variant leads with its `operation`
- * discriminant then its FLAT fields, every field via `stringShape` / `optionalShape` /
+ * Describes the shape of a {@link import('./types.js').WorkspaceOperation} — a descriptive tagged union
+ * over the workspace edit, read, and navigation operations, discriminated by the `operation`
+ * literal (never a bare `kind`). Each variant leads with its `operation`
+ * discriminant then its FLAT fields, every field through `stringShape` / `optionalShape` /
  * `integerShape({ min: 1 })` / `booleanShape`, each carrying a strong field-level `description`.
  *
  * @remarks