@orkestrel/tool 0.0.2 → 0.0.3

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

@@ -2,14 +2,32 @@ import { AgentInterface } from '@orkestrel/agent';
 import { AgentRegistryInterface } from '@orkestrel/agent';
 import { ArrayShape } from '@orkestrel/contract';
 import { BooleanShape } from '@orkestrel/contract';
+import { ColumnSchema } from '@orkestrel/database';
+import { Condition } from '@orkestrel/database';
+import { Connector } from '@orkestrel/database';
 import { ContractInterface } from '@orkestrel/contract';
+import { ContractShape } from '@orkestrel/contract';
 import { ConversationStoreInterface } from '@orkestrel/agent';
+import { Criteria } from '@orkestrel/database';
+import { DatabaseErrorCode } from '@orkestrel/database';
+import { DatabaseInterface } from '@orkestrel/database';
+import { Direction } from '@orkestrel/database';
+import { DriverInterface } from '@orkestrel/database';
+import { Include } from '@orkestrel/relation';
+import { JSONShape } from '@orkestrel/contract';
+import { KeyFunction } from '@orkestrel/database';
 import { LiteralShape } from '@orkestrel/contract';
+import { ModelInterface } from '@orkestrel/relation';
 import { NumberShape } from '@orkestrel/contract';
 import { ObjectShape } from '@orkestrel/contract';
 import { OptionalShape } from '@orkestrel/contract';
 import { PromptType } from '@orkestrel/terminal';
+import { RelationErrorCode } from '@orkestrel/relation';
+import { RelationManagerInterface } from '@orkestrel/relation';
 import { StringShape } from '@orkestrel/contract';
+import { TableInterface } from '@orkestrel/database';
+import { TableSchema } from '@orkestrel/database';
+import { TablesShape } from '@orkestrel/database';
 import { TerminalManagerInterface } from '@orkestrel/terminal';
 import { ToolInterface } from '@orkestrel/agent';
 import { ToolManagerInterface } from '@orkestrel/agent';
@@ -119,6 +137,9 @@ export declare interface AgentToolArguments {
  * (`DEADLOCK`), a prompt that expired before it was answered (`EXPIRE`), or an answer that
  * failed to apply (`ANSWER`) — the last three thrown by
  * {@link import('./factories.js').createPromptTool} / {@link import('./factories.js').createAnswerTool}.
+ * The upcoming database / relation tools (SRC-1's later units) will throw it too: a typed
+ * `@orkestrel/database` failure re-surfaces as `DATABASE`, a typed `@orkestrel/relation` failure
+ * as `RELATION` — each carrying the package's own granular error code in `context`.
  *
  * @remarks
  * Carries a machine-readable `code` (see {@link import('./types.js').AgentToolErrorCode}) and
@@ -160,8 +181,12 @@ export declare class AgentToolError extends Error {
  * `ANSWER` — {@link import('./factories.js').createAnswerTool}'s answer call failed to apply
  * (an unknown prompt id, a rejected value, or the terminal itself unknown —
  * `TerminalAnswerResult.error`, `@orkestrel/terminal`).
+ * `DATABASE` — a typed `@orkestrel/database` failure (`DatabaseError`), re-surfaced with the
+ * granular {@link import('@orkestrel/database').DatabaseErrorCode} carried in `context`.
+ * `RELATION` — a typed `@orkestrel/relation` failure (`RelationError`), re-surfaced with the
+ * granular {@link import('@orkestrel/relation').RelationErrorCode} carried in `context`.
  */
-export declare type AgentToolErrorCode = 'TOOL' | 'DEPTH' | 'DEADLOCK' | 'EXPIRE' | 'ANSWER';
+export declare type AgentToolErrorCode = 'TOOL' | 'DEPTH' | 'DEADLOCK' | 'EXPIRE' | 'ANSWER' | 'DATABASE' | 'RELATION';
 
 /**
  * Options for {@link import('./factories.js').createAgentTool} — the sub-agent delegation
@@ -219,7 +244,7 @@ export declare const agentToolShape: ObjectShape<{
     provider: OptionalShape<StringShape>;
     tools: OptionalShape<ArrayShape<StringShape>>;
     system: OptionalShape<StringShape>;
-}>;
+}, false>;
 
 export declare const ANSWER_TOOL_DESCRIPTION: string;
 
@@ -273,11 +298,42 @@ export declare interface AnswerToolOptions {
  */
 export declare const answerToolShape: UnionShape<[ ObjectShape<{
     operation: LiteralShape<readonly ["pending"]>;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["answer"]>;
     id: StringShape;
     value: UnionShape<[ StringShape, BooleanShape, ArrayShape<StringShape>]>;
-}>]>;
+}, false>]>;
+
+/**
+ * Clamp a `'records'` call's criteria to a row cap, and build the PROBE criteria 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(criteria?.limit ?? cap, cap)`, floored at `0` (so a caller can never
+ * exceed the configured cap by supplying a larger `criteria.limit`). The returned probe criteria
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { clampCriteria } from '@src/core'
+ *
+ * const { criteria, limit } = clampCriteria(undefined, 100)
+ * // limit === 100, criteria.limit === 101 — a probe fetching one extra row
+ * const rows = await table.records(criteria)
+ * const truncated = rows.length > limit // true when storage had more than `limit` rows
+ * ```
+ *
+ * @param criteria - The live criteria to clamp (or `undefined`)
+ * @param cap - The row-count ceiling
+ * @returns The PROBE criteria (`limit` bumped by one) and the effective `limit`
+ */
+export declare function clampCriteria(criteria: Criteria | undefined, cap: number): Readonly<{
+    criteria: Criteria;
+    limit: number;
+}>;
 
 /**
  * Normalize an LLM-supplied answer `value` to the type {@link PromptType} `form` expects, so a
@@ -301,6 +357,33 @@ export declare const answerToolShape: UnionShape<[ ObjectShape<{
  */
 export declare function coerceAnswer(form: PromptType, value: unknown): string | boolean | readonly string[];
 
+/** One column's declared type — a primitive shorthand, or `integer` for a whole-number `number`. */
+export declare type ColumnKind = '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"]>;
+
+/** Map a column NAME + its live `@orkestrel/database` `ContractShape` to a {@link ColumnSchema} — the leaf {@link tableSchema} maps over. */
+export declare function columnSchema(name: string, shape: ContractShape): ColumnSchema;
+
+/** 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;
+
+/**
+ * One table column's spec — either a bare {@link ColumnKind} shorthand, or `{ type, optional }`
+ * when the column may be absent from a row.
+ */
+export declare type ColumnSpec = ColumnKind | Readonly<{
+    type: ColumnKind;
+    optional?: boolean;
+}>;
+
+/** A {@link import('./types.js').ColumnSpec} — a bare {@link columnKindShape}, or `{ type, optional }`. */
+export declare const columnSpecShape: UnionShape<[ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
+    type: 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
@@ -343,6 +426,14 @@ 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. */
+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"]>;
+    values: ArrayShape<JSONShape>;
+    connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
+}, false>;
+
 /**
  * Wrap a live `AgentInterface` (`@orkestrel/agent`) as a {@link WorkflowFunction}
  * (`@orkestrel/workflow`) — the OPT-IN adapter that runs the agent to a settled result, folding
@@ -465,6 +556,87 @@ 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`
+ * layer — the driver-pluggable twin of {@link createMemoryDefinitionStore}, storing each
+ * database's definition as one opaque JSON column.
+ *
+ * @param driver - The {@link DriverInterface} backing the table (default an in-memory driver)
+ * @returns A {@link DefinitionStoreInterface}
+ *
+ * @example
+ * ```ts
+ * import { createDatabaseDefinitionStore } from '@src/core'
+ *
+ * const store = createDatabaseDefinitionStore() // in-memory by default
+ * ```
+ */
+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
+ * {@link createWorkspaceTool}'s single-tool-many-operations shape).
+ *
+ * @remarks
+ * The universal tool-handler contract (AGENTS §14): 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
+ * 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
+ * `TOOL` {@link import('./errors.js').AgentToolError}). When a `store` is configured, `'create'`
+ * persists the new {@link import('./types.js').DatabaseDefinition} and `'destroy'` deletes it.
+ *
+ * `'migrate'` re-declares a LIVE handle's tables via `DatabaseInterface.import` (the SAME driver
+ * and storage, a NEW typed view) and calls its `migrate` against the OLD deployed schema —
+ * derived from the handle's OWN `export()` (via {@link import('./helpers.js').tableSchema}), so it
+ * works for any handle, config-tracked or caller-supplied via
+ * {@link import('./types.js').DatabaseToolOptions.databases}. `'records'` clamps its `criteria` to
+ * {@link import('./types.js').DatabaseToolOptions.limit} (default
+ * {@link import('./constants.js').DATABASE_TOOL_LIMIT}) via
+ * {@link import('./helpers.js').clampCriteria}, reporting `truncated` when storage held more rows
+ * than the cap. Every operation's `criteria` is normalized via
+ * {@link import('./helpers.js').criteriaOf} (defaults an omitted condition `connector` to `'and'`).
+ * When {@link import('./types.js').DatabaseToolOptions.readonly} is `true`, every mutating
+ * operation throws a typed `TOOL` `AgentToolError` before doing anything. When
+ * {@link import('./types.js').DatabaseToolOptions.timeout} is set, every `@orkestrel/database` call
+ * this tool makes is given a fresh `AbortSignal.timeout(timeout)`. A typed `@orkestrel/database`
+ * failure (`DatabaseError`) re-surfaces as a typed `DATABASE` `AgentToolError` carrying the
+ * original {@link import('@orkestrel/database').DatabaseErrorCode} in `context.code`
+ * ({@link import('./helpers.js').databaseToolCode}); an `AgentToolError` 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
+ * the {@link import('./types.js').DatabaseDefinition} schema persists in `store`, never rows;
+ * durable rows need a persistent driver factory registered in
+ * {@link import('./types.js').DatabaseToolOptions.drivers}. `'destroy'` closes whatever handle is
+ * cached for the id, including an embedder-supplied
+ * {@link import('./types.js').DatabaseToolOptions.databases} handle — the embedder relinquishes
+ * that handle's lifecycle to this tool for any id it wires in. This tool assumes the
+ * single-writer, non-reentrant model `@orkestrel/database` itself assumes — concurrent calls
+ * against one id are NOT serialized by this tool. `'get'` is uncapped by
+ * {@link import('./types.js').DatabaseToolOptions.limit} (bounded only by the caller's `key` array
+ * size), unlike `'records'` / `'find'` / `'links'`.
+ *
+ * @param options - The tool's configuration (see {@link import('./types.js').DatabaseToolOptions})
+ * @returns A `ToolInterface` (named {@link import('./constants.js').DATABASE_TOOL_NAME} by default)
+ *
+ * @example
+ * ```ts
+ * import { createDatabaseTool } from '@src/core'
+ *
+ * const tool = createDatabaseTool()
+ * await tool.execute({
+ * 	operation: 'create',
+ * 	id: 'shop',
+ * 	tables: { products: { columns: { name: 'string', price: 'number' } } },
+ * })
+ * ```
+ */
+export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolInterface;
+
 /**
  * Build 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
@@ -501,6 +673,22 @@ export declare function createAnswerTool(options: AnswerToolOptions): ToolInterf
  */
 export declare function createDescribeTool(tools: ToolManagerInterface): 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
+ * `DatabaseDefinition` configs through.
+ *
+ * @returns A {@link DefinitionStoreInterface}
+ *
+ * @example
+ * ```ts
+ * import { createMemoryDefinitionStore } from '@src/core'
+ *
+ * const store = createMemoryDefinitionStore()
+ * ```
+ */
+export declare function createMemoryDefinitionStore(): DefinitionStoreInterface;
+
 /**
  * Build an LLM-callable prompt tool — the ASK side of the terminal seam. Asks
  * {@link import('./types.js').PromptToolOptions.to} a question and BLOCKS until it answers,
@@ -537,6 +725,55 @@ export declare function createDescribeTool(tools: ToolManagerInterface): ToolInt
  */
 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
+ * single-tool-many-operations shape).
+ *
+ * @remarks
+ * The universal tool-handler contract (AGENTS §14): 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').AgentToolError}
+ * ({@link import('./helpers.js').relationManagerOf}) — then resolves `model` against it
+ * ({@link import('./helpers.js').relationModelOf}, 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
+ * 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
+ * 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').clampCriteria}'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
+ * row.
+ *
+ * A typed `@orkestrel/relation` failure (`RelationError`) re-surfaces as a typed `RELATION`
+ * `AgentToolError` carrying the original {@link import('@orkestrel/relation').RelationErrorCode}
+ * in `context.code`; a typed `@orkestrel/database` failure underneath it (`DatabaseError`)
+ * re-surfaces as a typed `DATABASE` `AgentToolError`, mirroring {@link createDatabaseTool}'s error
+ * mapping; an `AgentToolError` thrown by this tool's own guards (malformed args, an unknown
+ * manager/model) passes through unwrapped.
+ *
+ * @param options - The tool's configuration (see {@link import('./types.js').RelationToolOptions})
+ * @returns A `ToolInterface` (named {@link import('./constants.js').RELATION_TOOL_NAME} by default)
+ *
+ * @example
+ * ```ts
+ * import { createRelationTool } from '@src/core'
+ *
+ * const tool = createRelationTool({ managers: { shop: manager } })
+ * await tool.execute({ operation: 'load', model: 'accounts', key: 'acc1', include: ['contacts'] })
+ * ```
+ */
+export declare function createRelationTool(options: RelationToolOptions): ToolInterface;
+
 /**
  * Wrap a registered tool as a {@link WorkflowFunction} (`@orkestrel/workflow`) — the OPT-IN
  * adapter that lets a `function`-form task run a `@orkestrel/agent` tool BY NAME.
@@ -712,6 +949,355 @@ export declare function createWorkflowTool(definition: WorkflowDefinition, runne
  */
 export declare function createWorkspaceTool(options?: WorkspaceToolOptions): ToolInterface;
 
+/**
+ * Normalize the database tool's parsed SERIALIZED criteria into a live `@orkestrel/database`
+ * {@link Criteria} — 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 criteria - The parsed criteria (or `undefined`)
+ * @returns The equivalent live `Criteria`, or `undefined` when `criteria` is `undefined`
+ */
+export declare function criteriaOf(criteria: Readonly<{
+    conditions?: readonly Readonly<{
+        column: string;
+        operator: Condition['operator'];
+        values: readonly unknown[];
+        connector?: Connector;
+    }>[];
+    order?: readonly Readonly<{
+        column: string;
+        direction: Direction;
+    }>[];
+    limit?: number;
+    offset?: number;
+}> | undefined): Criteria | undefined;
+
+/** The SERIALIZED criteria form — conditions, order, and pagination. */
+export declare const criteriaShape: ObjectShape<{
+    conditions: OptionalShape<ArrayShape<ObjectShape<{
+        column: StringShape;
+        operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
+        values: ArrayShape<JSONShape>;
+        connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
+    }, false>>>;
+    order: OptionalShape<ArrayShape<ObjectShape<{
+        column: StringShape;
+        direction: LiteralShape<readonly ["ascending", "descending"]>;
+    }, false>>>;
+    limit: OptionalShape<NumberShape>;
+    offset: OptionalShape<NumberShape>;
+}, false>;
+
+/**
+ * The DESCRIPTION the upcoming database tool will advertise — a multi-line guide that teaches a
+ * small model the operation list, the SERIALIZED criteria form, and the {@link import('./types.js').TableSpec}
+ * column DSL.
+ *
+ * @remarks
+ * The criteria form is deliberately SERIALIZED (never fluent) — every condition is a flat object
+ * `{ column, operator, values, connector? }` where `values` is ALWAYS an array, even for a
+ * single-value operator (`{ column: 'age', operator: 'from', values: [18] }`), so a small model
+ * never has to chain method calls or guess whether a value is scalar or a list.
+ */
+export declare const DATABASE_TOOL_DESCRIPTION: string;
+
+/** The default cap on rows a `records` / `remove` call returns (or acts on) when the caller omits `criteria.limit` — the upcoming database tool's default row ceiling. */
+export declare const DATABASE_TOOL_LIMIT = 1000;
+
+/** The database tool's mutating operations — disabled by `DatabaseToolOptions.readonly`. */
+export declare const DATABASE_TOOL_MUTATIONS: Set<string>;
+
+/**
+ * The name the upcoming `createDatabaseTool` factory will advertise by default — the key a model
+ * calls and the `ToolManagerInterface` (`@orkestrel/agent`) 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.
+ */
+export declare const DATABASE_TOOL_NAME = "database";
+
+/**
+ * The lean {@link import('@orkestrel/agent').ToolInterface.summary} the upcoming database tool
+ * will advertise 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, migrate, destroy), chosen by the 'operation' field. Call describe('database') for the full operation list, the criteria form, and the column DSL.";
+
+/**
+ * One database's CONFIG-ONLY definition — `id` + `driver` + {@link TableSpec} (+ optional `keys`),
+ * the pure-JSON blueprint the upcoming database / relation tools build a live database from.
+ *
+ * @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})
+ * on demand. `keys`, when present, maps a table name to its primary-key column (omitted ⇒ the
+ * driver's default primary key).
+ */
+export declare interface DatabaseDefinition {
+    readonly id: string;
+    readonly driver: string;
+    readonly tables: TableSpec;
+    readonly keys?: Readonly<Record<string, string>>;
+}
+
+/** One opaque persisted row — the shape a `TableInterface<DatabaseDefinitionRow>`-backed store reads/writes; `definition` is narrowed with {@link import('./helpers.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
+ * 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}.
+ *
+ * @remarks
+ * The store is driver-agnostic: it holds a single {@link TableInterface} whose backend (memory,
+ * JSON, SQLite, IndexedDB) is chosen by whoever builds it (the factories), so a JSON / SQLite /
+ * IndexedDB backend swaps in WITHOUT touching a consumer — the same seam as
+ * {@link import('./MemoryDefinitionStore.js').MemoryDefinitionStore}. The driver defaults to
+ * memory ({@link import('../factories.js').createDatabaseDefinitionStore} passes
+ * `createMemoryDriver()`), so it ALSO works in memory out of the box; you opt into the durable
+ * plumbing by passing a JSON / SQLite / IndexedDB driver.
+ *
+ * The {@link DatabaseDefinition} is stored as ONE OPAQUE JSON COLUMN — the table is a row of
+ * `{ id; definition }` ({@link DatabaseDefinitionRow}). The definition is already a COMPLETE,
+ * self-contained, pure-JSON CONFIG payload (never a live handle), so storing it whole is lossless
+ * AND keeps the row type flat (`definition` reads back as `unknown`).
+ *
+ * - **`set(definition)` upserts under the definition's OWN `id`** (no separate id param) — it
+ *   writes the row `{ id: definition.id, definition }`.
+ * - **`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
+ *   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
+ * bijection with {@link DefinitionStoreInterface}).
+ *
+ * @example
+ * ```ts
+ * import { createDatabaseDefinitionStore, createMemoryDriver } from '@src/core'
+ *
+ * const store = createDatabaseDefinitionStore(createMemoryDriver()) // a durable driver swaps in here
+ * await store.set({ id: 'shop', driver: 'memory', tables: {} }) // persist the config (one JSON column)
+ * const definition = await store.get('shop')
+ * await store.delete('shop')
+ * ```
+ */
+export declare class DatabaseDefinitionStore implements DefinitionStoreInterface {
+    #private;
+    /**
+     * Wrap 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`. */
+    get(id: string): Promise<DatabaseDefinition | undefined>;
+    /** Insert or replace under the definition's OWN `id` (no separate id param) — the row is `{ id, definition }`. */
+    set(definition: DatabaseDefinition): Promise<void>;
+    /** Drop a definition by id; an absent id is a no-op (no throw). */
+    delete(id: string): Promise<void>;
+}
+
+/**
+ * Map a caught error to the {@link AgentToolErrorCode} the upcoming database tool should throw
+ * with — the pure classification step of that factory's error handling, mirroring
+ * {@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}).
+ *
+ * @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
+ *   call's `id` field addresses.
+ * - `store` — the {@link DefinitionStoreInterface} the `'create'` / `'migrate'` operations persist
+ *   their {@link DatabaseDefinition} CONFIG through, and `'destroy'` deletes from; also the source
+ *   `'get'`/every other operation resolves an id from when it isn't already cached. Omitted means
+ *   no persistence — a database created without a store lives only for the tool's lifetime.
+ * - `drivers` — registry of driver-name to `() => DriverInterface` factories a `'create'` call's
+ *   `driver` field (or a persisted definition's `driver`) resolves against. Defaults to
+ *   `{ memory: () => createMemoryDriver() }` (`@orkestrel/database`).
+ * - `key` — the `KeyFunction` (`@orkestrel/database`) every minted database is constructed with,
+ *   used when a written row lacks its primary key. Defaults to `generateUUID`.
+ * - `limit` — the row cap `'records'` / `'remove'` — via {@link import('./helpers.js').clampCriteria}
+ *   — enforce when a call's `criteria.limit` is omitted or exceeds it. Defaults to
+ *   {@link import('./constants.js').DATABASE_TOOL_LIMIT}.
+ * - `timeout` — milliseconds; when set, every `@orkestrel/database` call this tool makes is given
+ *   a fresh `AbortSignal.timeout(timeout)` per tool call.
+ * - `readonly` — when `true`, every mutating operation (`'create'` / `'add'` / `'set'` /
+ *   `'update'` / `'remove'` / `'migrate'` / `'destroy'`) throws a typed `TOOL`
+ *   {@link import('./errors.js').AgentToolError} before doing anything.
+ * - `name` / `description` — advertised tool overrides; default to
+ *   {@link import('./constants.js').DATABASE_TOOL_NAME} / {@link import('./constants.js').DATABASE_TOOL_DESCRIPTION}.
+ */
+export declare interface DatabaseToolOptions {
+    readonly name?: string;
+    readonly description?: string;
+    readonly databases?: Readonly<Record<string, DatabaseInterface>>;
+    readonly store?: DefinitionStoreInterface;
+    readonly drivers?: Readonly<Record<string, () => DriverInterface>>;
+    readonly key?: KeyFunction;
+    readonly limit?: number;
+    readonly timeout?: number;
+    readonly readonly?: boolean;
+}
+
+/**
+ * The shape of {@link import('./factories.js').createDatabaseTool}'s call arguments —
+ * discriminated by `operation` into the 12 database operations (`'create'` / `'tables'` /
+ * `'get'` / `'records'` / `'count'` / `'aggregate'` / `'add'` / `'set'` / `'update'` /
+ * `'remove'` / `'migrate'` / `'destroy'`).
+ *
+ * @remarks
+ * Every arm carries `id` (the database id). `'create'` / `'migrate'` carry `tables` (the
+ * {@link import('./types.js').TableSpec} column DSL, compiled via
+ * {@link import('./helpers.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 `criteria` (the SERIALIZED form — `values` is ALWAYS an array,
+ * even for a single-value operator, so a caller never chains method calls or guesses arity).
+ */
+export declare const databaseToolShape: UnionShape<[ ObjectShape<{
+    operation: LiteralShape<readonly ["create"]>;
+    id: StringShape;
+    tables: ObjectShape<Record<never, never>, ObjectShape<{
+        columns: ObjectShape<Record<never, never>, UnionShape<[ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
+            type: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
+            optional: OptionalShape<BooleanShape>;
+        }, false>]>>;
+    }, false>>;
+    driver: OptionalShape<StringShape>;
+    keys: OptionalShape<ObjectShape<Record<never, never>, StringShape>>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["tables"]>;
+    id: StringShape;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["get"]>;
+    id: StringShape;
+    table: StringShape;
+    key: UnionShape<[ ArrayShape<UnionShape<[ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["records"]>;
+    id: StringShape;
+    table: StringShape;
+    criteria: OptionalShape<ObjectShape<{
+        conditions: OptionalShape<ArrayShape<ObjectShape<{
+            column: StringShape;
+            operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
+            values: ArrayShape<JSONShape>;
+            connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
+        }, false>>>;
+        order: OptionalShape<ArrayShape<ObjectShape<{
+            column: StringShape;
+            direction: LiteralShape<readonly ["ascending", "descending"]>;
+        }, false>>>;
+        limit: OptionalShape<NumberShape>;
+        offset: OptionalShape<NumberShape>;
+    }, false>>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["count"]>;
+    id: StringShape;
+    table: StringShape;
+    criteria: OptionalShape<ObjectShape<{
+        conditions: OptionalShape<ArrayShape<ObjectShape<{
+            column: StringShape;
+            operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
+            values: ArrayShape<JSONShape>;
+            connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
+        }, false>>>;
+        order: OptionalShape<ArrayShape<ObjectShape<{
+            column: StringShape;
+            direction: LiteralShape<readonly ["ascending", "descending"]>;
+        }, false>>>;
+        limit: OptionalShape<NumberShape>;
+        offset: OptionalShape<NumberShape>;
+    }, false>>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["aggregate"]>;
+    id: StringShape;
+    table: StringShape;
+    function: LiteralShape<readonly ["count", "sum", "average", "minimum", "maximum"]>;
+    column: StringShape;
+    criteria: OptionalShape<ObjectShape<{
+        conditions: OptionalShape<ArrayShape<ObjectShape<{
+            column: StringShape;
+            operator: LiteralShape<readonly ["equals", "not", "above", "below", "from", "to", "between", "like", "glob", "starts", "ends", "any", "none", "absent", "present"]>;
+            values: ArrayShape<JSONShape>;
+            connector: OptionalShape<LiteralShape<readonly ["and", "or"]>>;
+        }, false>>>;
+        order: OptionalShape<ArrayShape<ObjectShape<{
+            column: StringShape;
+            direction: LiteralShape<readonly ["ascending", "descending"]>;
+        }, false>>>;
+        limit: OptionalShape<NumberShape>;
+        offset: OptionalShape<NumberShape>;
+    }, false>>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["add"]>;
+    id: StringShape;
+    table: StringShape;
+    row: UnionShape<[ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["set"]>;
+    id: StringShape;
+    table: StringShape;
+    row: UnionShape<[ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["update"]>;
+    id: StringShape;
+    table: StringShape;
+    key: UnionShape<[ ArrayShape<UnionShape<[ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+    changes: ObjectShape<Record<never, never>, JSONShape>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["remove"]>;
+    id: StringShape;
+    table: StringShape;
+    key: UnionShape<[ ArrayShape<UnionShape<[ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["migrate"]>;
+    id: StringShape;
+    tables: ObjectShape<Record<never, never>, ObjectShape<{
+        columns: ObjectShape<Record<never, never>, UnionShape<[ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
+            type: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
+            optional: OptionalShape<BooleanShape>;
+        }, false>]>>;
+    }, false>>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["destroy"]>;
+    id: StringShape;
+}, false>]>;
+
+/**
+ * The point-access persistence seam (AGENTS §5 — Stores) 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.
+ */
+export declare interface DefinitionStoreInterface {
+    get(id: string): Promise<DatabaseDefinition | undefined>;
+    set(definition: DatabaseDefinition): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
 /**
  * The DESCRIPTION {@link import('./factories.js').createDescribeTool} advertises.
  *
@@ -761,7 +1347,33 @@ export declare interface DescribeToolArguments {
  */
 export declare const describeToolShape: ObjectShape<{
     name: StringShape;
-}>;
+}, false>;
+
+/**
+ * Expand the relation tool's FLAT dot-path `include` list into a live `@orkestrel/relation`
+ * {@link Include} tree — the pure leaf {@link import('./factories.js').createRelationTool} calls
+ * before a `'load'` / `'find'` call.
+ *
+ * @remarks
+ * Each path splits on `'.'` into a chain of relation names, deep-merged into one nested
+ * `Include` object with a leaf `true`. A longer path SUBSUMES a shorter sibling's bare `true` —
+ * `'contacts'` followed by `'contacts.account'` yields `{ contacts: { account: true } }`, never
+ * overwriting the deeper chain. An EMPTY segment (`''`, from a leading/trailing/doubled `.`) or a
+ * path whose segment count exceeds `depth` throws a typed `TOOL` {@link AgentToolError}.
+ *
+ * @param paths - The flat dot-path `include` list (or `undefined` — yields `{}`)
+ * @param depth - The max segment count a single path may reach
+ * @returns The equivalent nested {@link Include}
+ *
+ * @example
+ * ```ts
+ * import { expandInclude } from '@src/core'
+ *
+ * expandInclude(['contacts', 'contacts.account'], 3)
+ * // { contacts: { account: true } }
+ * ```
+ */
+export declare function expandInclude(paths: readonly string[] | undefined, depth: number): Include;
 
 /**
  * Expand a flat {@link WorkflowSteps} blob into a strict {@link WorkflowDefinition} — each step
@@ -782,6 +1394,20 @@ export declare const describeToolShape: ObjectShape<{
  */
 export declare function expandSteps(flat: WorkflowSteps): WorkflowDefinition;
 
+/**
+ * Compile a {@link TableSpec} into the `@orkestrel/database` {@link TablesShape} 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.
+ *
+ * @param spec - The small-model-facing table layout
+ * @returns The compiled `TablesShape` a `@orkestrel/database` `createDatabase` call accepts
+ */
+export declare function expandTables(spec: TableSpec): TablesShape;
+
+/** Flat dot-path relation include list, expanded via {@link import('./helpers.js').expandInclude}. */
+export declare const includeShape: OptionalShape<ArrayShape<StringShape>>;
+
 /**
  * Type guard narrowing an unknown caught value to an {@link AgentToolError}.
  *
@@ -801,6 +1427,29 @@ export declare function expandSteps(flat: WorkflowSteps): WorkflowDefinition;
  */
 export declare function isAgentToolError(value: unknown): value is AgentToolError;
 
+/** Narrow an unknown value to a {@link import('./types.js').ColumnKind}. */
+export declare function isColumnKind(value: unknown): value is ColumnKind;
+
+/** Narrow an unknown value to a {@link ColumnSpec} — a valid {@link import('./types.js').ColumnKind} shorthand, or `{ type, optional }` with a valid `type`. */
+export declare function isColumnSpec(value: unknown): value is ColumnSpec;
+
+/**
+ * Narrow an unknown value to a {@link DatabaseDefinition} — a non-empty `id` + `driver`, a
+ * `tables` record whose every value is `{ columns: record of valid ColumnSpec }`, and an optional
+ * `keys` record of strings. The boundary guard a {@link import('./types.js').DefinitionStoreInterface}
+ * applies to an untrusted persisted blob before trusting it as a definition (never an `as`).
+ */
+export declare function isDatabaseDefinition(value: unknown): value is DatabaseDefinition;
+
+/** One key value — a string or number; the array form (multiple keys, positional) resolves FIRST per AGENTS §9.2. */
+export declare const keyShape: UnionShape<[ ArrayShape<UnionShape<[ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+
+/** 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;
+
+/** 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
  * {@link import('./factories.js').createAgentFunction} and
@@ -815,6 +1464,51 @@ export declare function isAgentToolError(value: unknown): value is AgentToolErro
  */
 export declare const MAX_WORKFLOW_DEPTH = 8;
 
+/**
+ * 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}.
+ *
+ * @remarks
+ * A plain `Map<string, DatabaseDefinition>` (AGENTS §21 — the definition is already pure,
+ * self-contained CONFIG-only JSON, so no encoding is needed for the memory tier). There is NO
+ * idle-TTL and NO eviction: a persisted definition lives until an explicit `delete`. A durable
+ * backend (JSON / SQLite / IndexedDB) swaps in through the SAME interface without touching a
+ * consumer — its driver-pluggable twin is
+ * {@link import('./DatabaseDefinitionStore.js').DatabaseDefinitionStore} (the definition as one
+ * opaque JSON column).
+ *
+ * - **`get` resolves the persisted definition for an id**, or `undefined` if none is stored.
+ * - **`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
+ * bijection with {@link DefinitionStoreInterface}).
+ *
+ * @example
+ * ```ts
+ * import { createMemoryDefinitionStore } from '@src/core'
+ *
+ * const store = createMemoryDefinitionStore()
+ * await store.set({ id: 'shop', driver: 'memory', tables: {} })
+ * const definition = await store.get('shop')
+ * await store.delete('shop')
+ * ```
+ */
+export declare class MemoryDefinitionStore implements DefinitionStoreInterface {
+    #private;
+    get(id: string): Promise<DatabaseDefinition | undefined>;
+    set(definition: DatabaseDefinition): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+/** 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. */
 export declare interface PhaseDraft {
     readonly id?: string;
@@ -842,10 +1536,10 @@ export declare const phaseDraftShape: ObjectShape<{
         run: OptionalShape<StringShape>;
         retries: OptionalShape<NumberShape>;
         timeout: OptionalShape<NumberShape>;
-    }>>;
+    }, false>>;
     concurrency: OptionalShape<NumberShape>;
     bail: OptionalShape<LiteralShape<readonly [true, false]>>;
-}>;
+}, false>;
 
 export declare const PROMPT_TOOL_DESCRIPTION: string;
 
@@ -912,7 +1606,7 @@ export declare const promptToolShape: ObjectShape<{
         name: StringShape;
         value: StringShape;
         description: OptionalShape<StringShape>;
-    }>>>;
+    }, boolean | ContractShape>>>;
     mask: OptionalShape<StringShape>;
     min: OptionalShape<NumberShape>;
     max: OptionalShape<NumberShape>;
@@ -926,9 +1620,160 @@ export declare const promptToolShape: ObjectShape<{
         numeric: OptionalShape<BooleanShape>;
         integer: OptionalShape<BooleanShape>;
         alphanumeric: OptionalShape<BooleanShape>;
-    }>>;
+    }, boolean | ContractShape>>;
     timeout: 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. */
+export declare const RELATION_TOOL_DEPTH = 3;
+
+/**
+ * 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
+ * An include path is a FLAT dot-separated string (`'contacts.account'`), never a nested object —
+ * the same small-model ergonomic lever the other tools in this package use for flat args.
+ */
+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. */
+export declare const RELATION_TOOL_LIMIT = 1000;
+
+/**
+ * The name `createRelationTool` advertises by default — the key a model calls and the
+ * `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+ */
+export declare const RELATION_TOOL_NAME = "relation";
+
+/**
+ * The lean {@link import('@orkestrel/agent').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<[ ArrayShape<UnionShape<[ 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 AgentToolError} 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 AgentToolErrorCode} 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.
+ *
+ * @remarks
+ * - `managers` — the live `RelationManagerInterface` (`@orkestrel/relation`) registry a call's
+ *   optional `manager` field addresses by name; REQUIRED (unlike the database tool's lazily
+ *   resolved handles, a relation manager's relations are declared up front and cannot be minted
+ *   on demand from a tool call). A call that omits `manager` resolves to the SOLE registered
+ *   manager when exactly one is registered, else throws a typed `TOOL`
+ *   {@link import('./errors.js').AgentToolError} naming the registered manager keys.
+ * - `limit` — the row cap `'find'` / `'links'` enforce when a call's `limit` is omitted or
+ *   exceeds it. Defaults to {@link import('./constants.js').RELATION_TOOL_LIMIT}.
+ * - `depth` — the max dot-path segment count `'load'` / `'find'`'s `include` paths may reach
+ *   ({@link import('./helpers.js').expandInclude}). Defaults to
+ *   {@link import('./constants.js').RELATION_TOOL_DEPTH}.
+ * - `name` / `description` — advertised tool overrides; default to
+ *   {@link import('./constants.js').RELATION_TOOL_NAME} / {@link import('./constants.js').RELATION_TOOL_DESCRIPTION}.
+ */
+export declare interface RelationToolOptions {
+    readonly name?: string;
+    readonly description?: string;
+    readonly managers: Readonly<Record<string, RelationManagerInterface>>;
+    readonly limit?: number;
+    readonly depth?: number;
+}
+
+/**
+ * The shape of {@link import('./factories.js').createRelationTool}'s call arguments —
+ * discriminated by `operation` into the 5 relation operations (`'load'` / `'find'` / `'link'` /
+ * `'unlink'` / `'links'`).
+ *
+ * @remarks
+ * `'load'` fetches one or more rows (positional key/array) with `include` attached. `'find'`
+ * fetches rows (pagination / sort only) with `include` attached. `'link'` / `'unlink'` write /
+ * remove a `through` junction row; `'links'` lists a `through` relation's linked keys.
+ */
+export declare const relationToolShape: UnionShape<[ ObjectShape<{
+    operation: LiteralShape<readonly ["load"]>;
+    manager: OptionalShape<StringShape>;
+    model: StringShape;
+    key: UnionShape<[ ArrayShape<UnionShape<[ StringShape, NumberShape]>>, StringShape, NumberShape]>;
+    include: OptionalShape<ArrayShape<StringShape>>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["find"]>;
+    manager: OptionalShape<StringShape>;
+    model: StringShape;
+    include: OptionalShape<ArrayShape<StringShape>>;
+    limit: OptionalShape<NumberShape>;
+    offset: OptionalShape<NumberShape>;
+    sort: OptionalShape<StringShape>;
+    direction: OptionalShape<LiteralShape<readonly ["ascending", "descending"]>>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["link"]>;
+    manager: OptionalShape<StringShape>;
+    model: StringShape;
+    key: UnionShape<[ StringShape, NumberShape]>;
+    relation: StringShape;
+    target: UnionShape<[ StringShape, NumberShape]>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["unlink"]>;
+    manager: OptionalShape<StringShape>;
+    model: StringShape;
+    key: UnionShape<[ StringShape, NumberShape]>;
+    relation: StringShape;
+    target: UnionShape<[ StringShape, NumberShape]>;
+}, false>, ObjectShape<{
+    operation: LiteralShape<readonly ["links"]>;
+    manager: OptionalShape<StringShape>;
+    model: StringShape;
+    key: UnionShape<[ StringShape, NumberShape]>;
+    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. */
+export declare const rowShape: ObjectShape<Record<never, never>, JSONShape>;
+
+/** One or many loose rows — the array form resolves FIRST per AGENTS §9.2. */
+export declare const rowsShape: UnionShape<[ ArrayShape<ObjectShape<Record<never, never>, JSONShape>>, ObjectShape<Record<never, never>, JSONShape>]>;
+
+/** A single row key (not an array) — used by `'link'` / `'unlink'` / `'links'`, which address exactly one owning row. */
+export declare const singleKeyShape: UnionShape<[ StringShape, NumberShape]>;
 
 /**
  * The shape of ONE flat step — `{ name }` — the building block of {@link workflowStepsShape}.
@@ -939,7 +1784,39 @@ export declare const promptToolShape: ObjectShape<{
  */
 export declare const stepShape: ObjectShape<{
     name: StringShape;
-}>;
+}, false>;
+
+/**
+ * Build one {@link TableSchema} from a table NAME and its `@orkestrel/database` `TableExport` —
+ * the "deployed" schema shape `DatabaseInterface.migrate` diffs against, derived from a LIVE
+ * handle's `export()` rather than a re-declared {@link TableSpec}, so it works for ANY handle
+ * (config-tracked or caller-supplied).
+ *
+ * @param name - The table name
+ * @param table - The table's `TableExport` (`{ key, columns }`, `@orkestrel/database`)
+ * @returns The equivalent {@link TableSchema} (`indexes` empty — this package declares none)
+ */
+export declare function tableSchema(name: string, table: Readonly<{
+    key: string;
+    columns: Readonly<Record<string, ContractShape>>;
+}>): TableSchema;
+
+/**
+ * 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}
+ * compiles into an `@orkestrel/database` `TablesShape`.
+ */
+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}. */
+export declare const tableSpecShape: ObjectShape<Record<never, never>, ObjectShape<{
+    columns: ObjectShape<Record<never, never>, UnionShape<[ LiteralShape<readonly ["string", "integer", "number", "boolean"]>, ObjectShape<{
+        type: LiteralShape<readonly ["string", "integer", "number", "boolean"]>;
+        optional: OptionalShape<BooleanShape>;
+    }, false>]>>;
+}, false>>;
 
 /**
  * A draft task — a `TaskDefinition` (`@orkestrel/workflow`) with OPTIONAL `id` / `name`.
@@ -972,7 +1849,7 @@ export declare const taskDraftShape: ObjectShape<{
     run: OptionalShape<StringShape>;
     retries: OptionalShape<NumberShape>;
     timeout: OptionalShape<NumberShape>;
-}>;
+}, false>;
 
 /**
  * Map a caught error to the {@link AgentToolErrorCode} the terminal-tool factory should throw
@@ -1086,12 +1963,12 @@ export declare const workflowDraftShape: ObjectShape<{
             run: OptionalShape<StringShape>;
             retries: OptionalShape<NumberShape>;
             timeout: OptionalShape<NumberShape>;
-        }>>;
+        }, false>>;
         concurrency: OptionalShape<NumberShape>;
         bail: OptionalShape<LiteralShape<readonly [true, false]>>;
-    }>>;
+    }, false>>;
     bail: OptionalShape<LiteralShape<readonly [true, false]>>;
-}>;
+}, false>;
 
 /**
  * One flat step — `{ name }` — the building block of a {@link WorkflowSteps} blob.
@@ -1136,8 +2013,8 @@ export declare const workflowStepsShape: ObjectShape<{
     name: OptionalShape<StringShape>;
     steps: ArrayShape<ObjectShape<{
         name: StringShape;
-    }>>;
-}>;
+    }, false>>;
+}, false>;
 
 /**
  * The ancestry identifier of a workflow in a run chain — `workflow:<id>`.
@@ -1392,29 +2269,29 @@ export declare interface WorkspaceToolOptions {
 export declare const workspaceToolShape: UnionShape<[ ObjectShape<{
     operation: LiteralShape<readonly ["read"]>;
     path: StringShape;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["list"]>;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["has"]>;
     path: StringShape;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["search"]>;
     query: StringShape;
     regex: OptionalShape<BooleanShape>;
     exact: OptionalShape<BooleanShape>;
     limit: OptionalShape<NumberShape>;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["replace"]>;
     query: StringShape;
     replacement: StringShape;
     regex: OptionalShape<BooleanShape>;
     exact: OptionalShape<BooleanShape>;
     limit: OptionalShape<NumberShape>;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["write"]>;
     path: StringShape;
     content: StringShape;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["splice"]>;
     path: StringShape;
     content: StringShape;
@@ -1422,26 +2299,26 @@ export declare const workspaceToolShape: UnionShape<[ ObjectShape<{
     fromColumn: NumberShape;
     toLine: NumberShape;
     toColumn: NumberShape;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["prepend"]>;
     path: StringShape;
     content: StringShape;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["append"]>;
     path: StringShape;
     content: StringShape;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["move"]>;
     from: StringShape;
     to: StringShape;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["remove"]>;
     path: StringShape;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["workspaces"]>;
-}>, ObjectShape<{
+}, false>, ObjectShape<{
     operation: LiteralShape<readonly ["switch"]>;
     id: StringShape;
-}>]>;
+}, false>]>;
 
 export { }