@orkestrel/tool 0.0.2 → 0.0.3

package/dist/src/core/index.cjs

@@ -1,6 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _orkestrel_contract = require("@orkestrel/contract");
 let _orkestrel_terminal = require("@orkestrel/terminal");
+let _orkestrel_database = require("@orkestrel/database");
+let _orkestrel_relation = require("@orkestrel/relation");
 let _orkestrel_agent = require("@orkestrel/agent");
 let _orkestrel_workflow = require("@orkestrel/workflow");
 //#region src/core/constants.ts
@@ -296,6 +298,133 @@ var ANSWER_TOOL_DESCRIPTION = [
 		value: true
 	})
 ].join("\n");
+/**
+* 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.
+*/
+var 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}.
+*/
+var DATABASE_TOOL_SUMMARY = "Create and query a database — 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.";
+/**
+* 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.
+*/
+var DATABASE_TOOL_DESCRIPTION = [
+	"Create and query a database. Every call is ONE operation, chosen by the \"operation\" field.",
+	"",
+	"Operations (each takes the fields listed):",
+	"- create    { \"operation\": \"create\", \"id\": \"<database id>\", \"tables\": { \"<table>\": { \"columns\": { \"<column>\": \"string\" | \"integer\" | \"number\" | \"boolean\" | { \"type\": \"string\", \"optional\": true } } } } } — define a new database.",
+	"- tables    { \"operation\": \"tables\", \"id\": \"<database id>\" } — list a database's table names.",
+	"- get       { \"operation\": \"get\", \"id\": \"<database id>\", \"table\": \"<table>\", \"key\": \"<row key>\" } — fetch one row by its primary key.",
+	"- records   { \"operation\": \"records\", \"id\": \"<database id>\", \"table\": \"<table>\", \"criteria\"?: <Criteria> } — list rows matching criteria.",
+	"- count     { \"operation\": \"count\", \"id\": \"<database id>\", \"table\": \"<table>\", \"criteria\"?: <Criteria> } — count rows matching criteria.",
+	"- aggregate { \"operation\": \"aggregate\", \"id\": \"<database id>\", \"table\": \"<table>\", \"column\": \"<column>\", \"function\": \"count\" | \"sum\" | \"average\" | \"minimum\" | \"maximum\", \"criteria\"?: <Criteria> } — compute an aggregate.",
+	"- add       { \"operation\": \"add\", \"id\": \"<database id>\", \"table\": \"<table>\", \"row\": { ... } } — insert a row (fails on a duplicate key).",
+	"- set       { \"operation\": \"set\", \"id\": \"<database id>\", \"table\": \"<table>\", \"row\": { ... } } — upsert a row.",
+	"- update    { \"operation\": \"update\", \"id\": \"<database id>\", \"table\": \"<table>\", \"key\": \"<row key>\", \"row\": { ... } } — patch an existing row.",
+	"- remove    { \"operation\": \"remove\", \"id\": \"<database id>\", \"table\": \"<table>\", \"key\": \"<row key>\" } — delete a row by key.",
+	"- migrate   { \"operation\": \"migrate\", \"id\": \"<database id>\", \"tables\": { ... } } — replace the table layout in place.",
+	"- destroy   { \"operation\": \"destroy\", \"id\": \"<database id>\" } — drop a database entirely.",
+	"",
+	"Criteria form — SERIALIZED, never fluent. A condition is a flat object; \"values\" is ALWAYS an array, even for one value:",
+	"  { \"conditions\": [ { \"column\": \"age\", \"operator\": \"from\", \"values\": [18], \"connector\": \"and\" } ], \"order\"?: [...], \"offset\"?: 0, \"limit\"?: 100 }",
+	"  operators: equals, not, above, below, from, to, between, like, glob, starts, ends, any, none, absent, present.",
+	"  \"connector\" joins this condition to the next (\"and\" | \"or\"); omit on the last condition.",
+	"",
+	"Column DSL (used by \"create\"/\"migrate\" \"tables\"): a column is either a bare type string (\"string\" | \"integer\" | \"number\" | \"boolean\"), or { \"type\": \"<type>\", \"optional\": true } when the column may be absent from a row.",
+	"Example — create a database:",
+	JSON.stringify({
+		operation: "create",
+		id: "shop",
+		tables: { products: { columns: {
+			name: "string",
+			price: "number",
+			notes: {
+				type: "string",
+				optional: true
+			}
+		} } }
+	}),
+	"Example — query with criteria:",
+	JSON.stringify({
+		operation: "records",
+		id: "shop",
+		table: "products",
+		criteria: { conditions: [{
+			column: "price",
+			operator: "below",
+			values: [50]
+		}] }
+	})
+].join("\n");
+/** 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. */
+var DATABASE_TOOL_LIMIT = 1e3;
+/** The database tool's mutating operations — disabled by `DatabaseToolOptions.readonly`. */
+var DATABASE_TOOL_MUTATIONS = /* @__PURE__ */ new Set([
+	"create",
+	"add",
+	"set",
+	"update",
+	"remove",
+	"migrate",
+	"destroy"
+]);
+/**
+* The name `createRelationTool` advertises by default — the key a model calls and the
+* `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+*/
+var RELATION_TOOL_NAME = "relation";
+/**
+* The lean {@link import('@orkestrel/agent').ToolInterface.summary} the relation tool advertises
+* in place of {@link RELATION_TOOL_DESCRIPTION}.
+*/
+var RELATION_TOOL_SUMMARY = "Traverse and edit relationships between database rows — one operation per call (load, find, link, unlink, links), chosen by the 'operation' field. Call describe('relation') for the include-path syntax.";
+/**
+* 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.
+*/
+var RELATION_TOOL_DESCRIPTION = [
+	"Traverse and edit relationships between database rows. Every call is ONE operation, chosen by the \"operation\" field. \"manager\" is optional (omit it when only one relation manager is registered).",
+	"",
+	"Operations (each takes the fields listed):",
+	"- load   { \"operation\": \"load\", \"model\": \"<model>\", \"key\": \"<row key>\", \"include\"?: [\"<path>\", ...] } — fetch one (or, with an array key, several) row(s) with related rows attached.",
+	"- find   { \"operation\": \"find\", \"model\": \"<model>\", \"include\"?: [\"<path>\", ...], \"limit\"?: <n>, \"offset\"?: <n>, \"sort\"?: \"<column>\", \"direction\"?: \"ascending\"|\"descending\" } — list rows, each with related rows attached.",
+	"- link   { \"operation\": \"link\", \"model\": \"<model>\", \"key\": \"<row key>\", \"relation\": \"<relation>\", \"target\": \"<related row key>\" } — connect two rows through a \"through\" relation.",
+	"- unlink { \"operation\": \"unlink\", \"model\": \"<model>\", \"key\": \"<row key>\", \"relation\": \"<relation>\", \"target\": \"<related row key>\" } — disconnect two rows.",
+	"- links  { \"operation\": \"links\", \"model\": \"<model>\", \"key\": \"<row key>\", \"relation\": \"<relation>\" } — list every key linked to a row through a \"through\" relation.",
+	"",
+	"\"include\" is a FLAT dot-path array (not nested objects) — each string names a chain of relations to attach, up to the configured depth cap. Example: \"contacts.account\" attaches each row's contacts, and each contact's account.",
+	"Example — load a row with two levels of relations:",
+	JSON.stringify({
+		operation: "load",
+		model: "orders",
+		key: "1",
+		include: ["contacts.account"]
+	})
+].join("\n");
+/** The default cap on rows a `find` / `links` call returns when the caller omits `limit` — the relation tool's default row ceiling. */
+var RELATION_TOOL_LIMIT = 1e3;
+/** The default cap on how many `include` path segments deep a `load` / `find` call may traverse — the relation tool's default include-depth ceiling. */
+var RELATION_TOOL_DEPTH = 3;
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -306,6 +435,9 @@ var ANSWER_TOOL_DESCRIPTION = [
 * (`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
@@ -676,6 +808,304 @@ var workspaceToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_cont
 	operation: (0, _orkestrel_contract.literalShape)(["switch"], { description: "Switch the active workspace to the one with this id (get ids from the \"workspaces\" operation). Edit and read operations then target it." }),
 	id: (0, _orkestrel_contract.stringShape)({ description: "The id of the workspace to make active (from the \"workspaces\" listing)." })
 }));
+/** A {@link import('./types.js').ColumnKind} literal — the leaf {@link columnSpecShape} wraps. */
+var columnKindShape = (0, _orkestrel_contract.literalShape)([
+	"string",
+	"integer",
+	"number",
+	"boolean"
+], { description: "A column type: \"string\" | \"integer\" | \"number\" | \"boolean\"." });
+/** A {@link import('./types.js').ColumnSpec} — a bare {@link columnKindShape}, or `{ type, optional }`. */
+var columnSpecShape = (0, _orkestrel_contract.unionShape)(columnKindShape, (0, _orkestrel_contract.objectShape)({
+	type: columnKindShape,
+	optional: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Whether the column may be absent from a row." }))
+}));
+/** A {@link import('./types.js').TableSpec} — table name to `{ columns }`, each column a {@link columnSpecShape}. */
+var tableSpecShape = (0, _orkestrel_contract.recordShape)((0, _orkestrel_contract.objectShape)({ columns: (0, _orkestrel_contract.recordShape)(columnSpecShape, { description: "Column name to its type." }) }), { description: "Table name to its column layout." });
+/** One key value — a string or number; the array form (multiple keys, positional) resolves FIRST per AGENTS §9.2. */
+var keyShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.unionShape)((0, _orkestrel_contract.stringShape)(), (0, _orkestrel_contract.numberShape)()), { description: "Multiple row keys, positional — a miss at an index is undefined there." }), (0, _orkestrel_contract.stringShape)({ description: "One row key." }), (0, _orkestrel_contract.numberShape)({ description: "One row key." }));
+/** A loose row — a flat object of column name to JSON value; the array form (multiple rows) resolves FIRST per AGENTS §9.2. */
+var rowShape = (0, _orkestrel_contract.recordShape)((0, _orkestrel_contract.jsonShape)(), { description: "A row as a flat object of column name to value." });
+/** One or many loose rows — the array form resolves FIRST per AGENTS §9.2. */
+var rowsShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contract.arrayShape)(rowShape, { description: "Multiple rows." }), rowShape);
+/** One SERIALIZED WHERE condition — `values` is ALWAYS an array, even for a single-value operator. */
+var conditionShape = (0, _orkestrel_contract.objectShape)({
+	column: (0, _orkestrel_contract.stringShape)({ description: "The column this condition applies to." }),
+	operator: (0, _orkestrel_contract.literalShape)([
+		"equals",
+		"not",
+		"above",
+		"below",
+		"from",
+		"to",
+		"between",
+		"like",
+		"glob",
+		"starts",
+		"ends",
+		"any",
+		"none",
+		"absent",
+		"present"
+	], { description: "The comparison operator." }),
+	values: (0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.jsonShape)(), { description: "The operand values the operator needs (always an array, even for one value)." }),
+	connector: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.literalShape)(["and", "or"], { description: "Joins this condition to the next; omit on the last condition." }))
+});
+/** One sort term. */
+var orderShape = (0, _orkestrel_contract.objectShape)({
+	column: (0, _orkestrel_contract.stringShape)({ description: "The column to sort by." }),
+	direction: (0, _orkestrel_contract.literalShape)(["ascending", "descending"], { description: "The sort direction." })
+});
+/** The SERIALIZED criteria form — conditions, order, and pagination. */
+var criteriaShape = (0, _orkestrel_contract.objectShape)({
+	conditions: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)(conditionShape, { description: "The WHERE conditions, folded left to right." })),
+	order: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)(orderShape, { description: "The sort terms, applied in order." })),
+	limit: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.integerShape)({
+		min: 0,
+		description: "Max rows to return."
+	})),
+	offset: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.integerShape)({
+		min: 0,
+		description: "Rows to skip before returning."
+	}))
+});
+/**
+* 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).
+*/
+var databaseToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["create"], { description: "Define a new database." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	}),
+	tables: tableSpecShape,
+	driver: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The registered driver key. Defaults to \"memory\"."
+	})),
+	keys: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.recordShape)((0, _orkestrel_contract.stringShape)(), { description: "Table name to its primary-key column." }))
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["tables"], { description: "List a database's table names." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	})
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["get"], { description: "Fetch one or more rows by primary key." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	}),
+	table: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The table name."
+	}),
+	key: keyShape
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["records"], { description: "List rows matching criteria." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	}),
+	table: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The table name."
+	}),
+	criteria: (0, _orkestrel_contract.optionalShape)(criteriaShape)
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["count"], { description: "Count rows matching criteria." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	}),
+	table: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The table name."
+	}),
+	criteria: (0, _orkestrel_contract.optionalShape)(criteriaShape)
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["aggregate"], { description: "Compute an aggregate over a column." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	}),
+	table: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The table name."
+	}),
+	function: (0, _orkestrel_contract.literalShape)([
+		"count",
+		"sum",
+		"average",
+		"minimum",
+		"maximum"
+	], { description: "The aggregate function." }),
+	column: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The column to aggregate."
+	}),
+	criteria: (0, _orkestrel_contract.optionalShape)(criteriaShape)
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["add"], { description: "Insert one or more rows (fails on a duplicate key)." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	}),
+	table: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The table name."
+	}),
+	row: rowsShape
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["set"], { description: "Upsert one or more rows." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	}),
+	table: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The table name."
+	}),
+	row: rowsShape
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["update"], { description: "Patch one or more existing rows." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	}),
+	table: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The table name."
+	}),
+	key: keyShape,
+	changes: rowShape
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["remove"], { description: "Delete one or more rows by key." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	}),
+	table: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The table name."
+	}),
+	key: keyShape
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["migrate"], { description: "Replace the table layout in place." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	}),
+	tables: tableSpecShape
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["destroy"], { description: "Drop a database entirely." }),
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	})
+}));
+/** One key value — a string or number; the array form (multiple keys, positional) resolves FIRST per AGENTS §9.2. */
+var relationKeyShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.unionShape)((0, _orkestrel_contract.stringShape)(), (0, _orkestrel_contract.numberShape)()), { description: "Multiple row keys, positional — a miss at an index is undefined there." }), (0, _orkestrel_contract.stringShape)({ description: "One row key." }), (0, _orkestrel_contract.numberShape)({ description: "One row key." }));
+/** A single row key (not an array) — used by `'link'` / `'unlink'` / `'links'`, which address exactly one owning row. */
+var singleKeyShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contract.stringShape)({ description: "The owning row key." }), (0, _orkestrel_contract.numberShape)({ description: "The owning row key." }));
+/** Flat dot-path relation include list, expanded via {@link import('./helpers.js').expandInclude}. */
+var includeShape = (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.stringShape)({ description: "A dot-separated chain of relation names, e.g. \"contacts.account\"." }), { description: "Which relations to attach, as flat dot-paths." }));
+/** Which registered relation manager to address — omitted resolves to the sole registered manager. */
+var managerShape = (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.stringShape)({
+	min: 1,
+	description: "Which registered relation manager to address."
+}));
+/**
+* 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.
+*/
+var relationToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["load"], { description: "Fetch one or more rows by key, with related rows attached." }),
+	manager: managerShape,
+	model: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The model (table) name."
+	}),
+	key: relationKeyShape,
+	include: includeShape
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["find"], { description: "List rows, with related rows attached." }),
+	manager: managerShape,
+	model: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The model (table) name."
+	}),
+	include: includeShape,
+	limit: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.integerShape)({
+		min: 0,
+		description: "Max rows to return."
+	})),
+	offset: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.integerShape)({
+		min: 0,
+		description: "Rows to skip before returning."
+	})),
+	sort: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The column to sort by."
+	})),
+	direction: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.literalShape)(["ascending", "descending"], { description: "The sort direction." }))
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["link"], { description: "Connect two rows through a \"through\" relation." }),
+	manager: managerShape,
+	model: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The model (table) name."
+	}),
+	key: singleKeyShape,
+	relation: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The \"through\" relation name."
+	}),
+	target: singleKeyShape
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["unlink"], { description: "Disconnect two rows previously linked through a \"through\" relation." }),
+	manager: managerShape,
+	model: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The model (table) name."
+	}),
+	key: singleKeyShape,
+	relation: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The \"through\" relation name."
+	}),
+	target: singleKeyShape
+}), (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(["links"], { description: "List every key linked to a row through a \"through\" relation." }),
+	manager: managerShape,
+	model: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The model (table) name."
+	}),
+	key: singleKeyShape,
+	relation: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The \"through\" relation name."
+	})
+}));
 //#endregion
 //#region src/core/helpers.ts
 /**
@@ -881,6 +1311,390 @@ function terminalToolCode(error) {
 	if (error.code === "EXPIRE") return "EXPIRE";
 	return "TOOL";
 }
+/** Narrow an unknown value to a {@link ColumnSpec} — a valid {@link import('./types.js').ColumnKind} shorthand, or `{ type, optional }` with a valid `type`. */
+function isColumnSpec(value) {
+	if (isColumnKind(value)) return true;
+	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+	return isColumnKind(value.type) && (value.optional === void 0 || typeof value.optional === "boolean");
+}
+/** Narrow an unknown value to a {@link import('./types.js').ColumnKind}. */
+function isColumnKind(value) {
+	return value === "string" || value === "integer" || value === "number" || value === "boolean";
+}
+/**
+* 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
+*/
+function expandTables(spec) {
+	const tables = {};
+	for (const [table, definition] of Object.entries(spec)) {
+		const columns = {};
+		for (const [column, kind] of Object.entries(definition.columns)) columns[column] = columnShape(kind);
+		tables[table] = columns;
+	}
+	return tables;
+}
+/** Compile one {@link ColumnSpec} into its `@orkestrel/database` column shape — the per-column leaf {@link expandTables} maps over. */
+function columnShape(spec) {
+	const kind = (0, _orkestrel_contract.isString)(spec) ? spec : spec.type;
+	const optional = !(0, _orkestrel_contract.isString)(spec) && spec.optional === true;
+	const shape = kindShape(kind);
+	return optional ? (0, _orkestrel_contract.optionalShape)(shape) : shape;
+}
+/** Map one {@link import('./types.js').ColumnKind} to its primitive `@orkestrel/database` shape — the leaf {@link columnShape} wraps. */
+function kindShape(kind) {
+	if (kind === "string") return (0, _orkestrel_contract.stringShape)();
+	if (kind === "integer") return (0, _orkestrel_contract.integerShape)();
+	if (kind === "number") return (0, _orkestrel_contract.numberShape)();
+	return (0, _orkestrel_contract.booleanShape)();
+}
+/**
+* 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`).
+*/
+function isDatabaseDefinition(value) {
+	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
+	if (!(0, _orkestrel_contract.isNonEmptyString)(value.id) || !(0, _orkestrel_contract.isNonEmptyString)(value.driver)) return false;
+	if (!(0, _orkestrel_contract.isRecord)(value.tables)) return false;
+	for (const table of Object.values(value.tables)) {
+		if (!(0, _orkestrel_contract.isRecord)(table) || !(0, _orkestrel_contract.isRecord)(table.columns)) return false;
+		for (const column of Object.values(table.columns)) if (!isColumnSpec(column)) return false;
+	}
+	if (value.keys !== void 0) {
+		if (!(0, _orkestrel_contract.isRecord)(value.keys)) return false;
+		for (const key of Object.values(value.keys)) if (!(0, _orkestrel_contract.isString)(key)) return false;
+	}
+	return true;
+}
+/**
+* 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`
+*/
+function databaseToolCode(error) {
+	return (0, _orkestrel_database.isDatabaseError)(error) ? error.code : void 0;
+}
+/**
+* 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`
+*/
+function relationToolCode(error) {
+	return (0, _orkestrel_relation.isRelationError)(error) ? error.code : void 0;
+}
+/**
+* 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 } }
+* ```
+*/
+function expandInclude(paths, depth) {
+	function merge(base, segments) {
+		const [head, ...rest] = segments;
+		const existing = base[head];
+		if (rest.length === 0) return {
+			...base,
+			[head]: existing === void 0 ? true : existing
+		};
+		const nextBase = typeof existing === "object" ? existing : {};
+		return {
+			...base,
+			[head]: merge(nextBase, rest)
+		};
+	}
+	let include = {};
+	for (const path of paths ?? []) {
+		const segments = path.split(".");
+		if (segments.length > depth || segments.some((segment) => segment.length === 0)) throw new AgentToolError("TOOL", `malformed include path '${path}'`, {
+			path,
+			depth
+		});
+		include = merge(include, segments);
+	}
+	return include;
+}
+/**
+* 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}
+*/
+function relationManagerOf(managers, name) {
+	if (name !== void 0) {
+		const manager = managers[name];
+		if (manager === void 0) throw new AgentToolError("TOOL", `unknown relation manager '${name}'`, {
+			manager: name,
+			managers: Object.keys(managers)
+		});
+		return manager;
+	}
+	const names = Object.keys(managers);
+	if (names.length === 1) return managers[names[0]];
+	throw new AgentToolError("TOOL", "no relation manager resolved for the call", { managers: names });
+}
+/**
+* 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}
+*/
+function relationModelOf(manager, name) {
+	if (!manager.has(name)) throw new AgentToolError("TOOL", `unknown model '${name}'`, {
+		model: name,
+		models: manager.models()
+	});
+	return manager.model(name);
+}
+/**
+* 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`
+*/
+function criteriaOf(criteria) {
+	if (criteria === void 0) return void 0;
+	const conditions = criteria.conditions?.map((condition) => ({
+		...condition,
+		connector: condition.connector ?? "and"
+	}));
+	return {
+		...conditions === void 0 ? {} : { conditions },
+		...criteria.order === void 0 ? {} : { order: criteria.order },
+		...criteria.limit === void 0 ? {} : { limit: criteria.limit },
+		...criteria.offset === void 0 ? {} : { offset: criteria.offset }
+	};
+}
+/**
+* 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`
+*/
+function clampCriteria(criteria, cap) {
+	const limit = Math.max(0, Math.min(criteria?.limit ?? cap, cap));
+	return {
+		criteria: {
+			...criteria,
+			limit: limit + 1
+		},
+		limit
+	};
+}
+/** Map a column NAME + its live `@orkestrel/database` `ContractShape` to a {@link ColumnSchema} — the leaf {@link tableSchema} maps over. */
+function columnSchema(name, shape) {
+	return {
+		name,
+		type: (0, _orkestrel_database.shapeToColumnType)(shape),
+		nullable: shape.type === "optional" || shape.type === "nullable"
+	};
+}
+/**
+* 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)
+*/
+function tableSchema(name, table) {
+	return {
+		name,
+		primary: table.key,
+		columns: Object.entries(table.columns).map(([column, shape]) => columnSchema(column, shape)),
+		indexes: []
+	};
+}
+//#endregion
+//#region src/core/stores/MemoryDefinitionStore.ts
+/**
+* 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')
+* ```
+*/
+var MemoryDefinitionStore = class {
+	#definitions = /* @__PURE__ */ new Map();
+	get(id) {
+		return Promise.resolve(this.#definitions.get(id));
+	}
+	set(definition) {
+		this.#definitions.set(definition.id, definition);
+		return Promise.resolve();
+	}
+	delete(id) {
+		this.#definitions.delete(id);
+		return Promise.resolve();
+	}
+};
+//#endregion
+//#region src/core/stores/DatabaseDefinitionStore.ts
+/**
+* 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')
+* ```
+*/
+var DatabaseDefinitionStore = class {
+	#table;
+	/**
+	* 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) {
+		this.#table = table;
+	}
+	/** Resolve the persisted definition for `id`, narrowing the opaque JSON column back to a `DatabaseDefinition`. */
+	async get(id) {
+		const row = await this.#table.get(id);
+		if (row === void 0) return void 0;
+		return isDatabaseDefinition(row.definition) ? row.definition : void 0;
+	}
+	/** Insert or replace under the definition's OWN `id` (no separate id param) — the row is `{ id, definition }`. */
+	async set(definition) {
+		await this.#table.set({
+			id: definition.id,
+			definition
+		});
+	}
+	/** Drop a definition by id; an absent id is a no-op (no throw). */
+	async delete(id) {
+		await this.#table.remove(id);
+	}
+};
 //#endregion
 //#region src/core/factories.ts
 /**
@@ -1587,6 +2401,425 @@ function createAnswerTool(options) {
 		}
 	});
 }
+/**
+* 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()
+* ```
+*/
+function createMemoryDefinitionStore() {
+	return new MemoryDefinitionStore();
+}
+/**
+* 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
+* ```
+*/
+function createDatabaseDefinitionStore(driver = (0, _orkestrel_database.createMemoryDriver)()) {
+	return new DatabaseDefinitionStore((0, _orkestrel_database.createDatabase)({
+		driver,
+		tables: { definitions: {
+			id: (0, _orkestrel_contract.stringShape)(),
+			definition: (0, _orkestrel_contract.rawShape)({})
+		} }
+	}).table("definitions"));
+}
+/**
+* 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' } } },
+* })
+* ```
+*/
+function createDatabaseTool(options = {}) {
+	const contract = (0, _orkestrel_contract.createContract)(databaseToolShape);
+	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
+	const handles = new Map(Object.entries(options.databases ?? {}));
+	const definitions = /* @__PURE__ */ new Map();
+	const drivers = options.drivers ?? { memory: () => (0, _orkestrel_database.createMemoryDriver)() };
+	const key = options.key ?? _orkestrel_database.generateUUID;
+	const cap = options.limit ?? 1e3;
+	const store = options.store;
+	async function resolve(id) {
+		const cached = handles.get(id);
+		if (cached !== void 0) return cached;
+		if (store !== void 0) {
+			const definition = await store.get(id);
+			if (definition !== void 0) {
+				const factory = drivers[definition.driver];
+				if (factory === void 0) throw new AgentToolError("TOOL", `unknown driver '${definition.driver}'`, {
+					id,
+					driver: definition.driver
+				});
+				const handle = (0, _orkestrel_database.createDatabase)({
+					driver: factory(),
+					tables: expandTables(definition.tables),
+					...definition.keys === void 0 ? {} : { keys: definition.keys },
+					key
+				});
+				handles.set(id, handle);
+				definitions.set(id, definition);
+				return handle;
+			}
+		}
+		throw new AgentToolError("TOOL", `unknown database '${id}'`, { id });
+	}
+	return (0, _orkestrel_agent.createTool)({
+		name: options.name ?? "database",
+		description: options.description ?? DATABASE_TOOL_DESCRIPTION,
+		summary: DATABASE_TOOL_SUMMARY,
+		parameters,
+		execute: async (args) => {
+			const call = contract.parse(args);
+			if (call === void 0) throw new AgentToolError("TOOL", "malformed database call", { args });
+			if (options.readonly === true && DATABASE_TOOL_MUTATIONS.has(call.operation)) throw new AgentToolError("TOOL", `operation '${call.operation}' is disabled in readonly mode`, { operation: call.operation });
+			const read = options.timeout === void 0 ? void 0 : { signal: AbortSignal.timeout(options.timeout) };
+			try {
+				switch (call.operation) {
+					case "create": {
+						if (handles.has(call.id) || store !== void 0 && await store.get(call.id) !== void 0) throw new AgentToolError("TOOL", `database '${call.id}' already exists`, { id: call.id });
+						const name = call.driver ?? "memory";
+						const factory = drivers[name];
+						if (factory === void 0) throw new AgentToolError("TOOL", `unknown driver '${name}'`, {
+							id: call.id,
+							driver: name
+						});
+						const tables = call.tables;
+						const keys = call.keys;
+						const handle = (0, _orkestrel_database.createDatabase)({
+							driver: factory(),
+							tables: expandTables(tables),
+							...keys === void 0 ? {} : { keys },
+							key
+						});
+						handles.set(call.id, handle);
+						const definition = {
+							id: call.id,
+							driver: name,
+							tables,
+							...keys === void 0 ? {} : { keys }
+						};
+						definitions.set(call.id, definition);
+						if (store !== void 0) await store.set(definition);
+						return {
+							id: call.id,
+							tables: Object.keys(tables)
+						};
+					}
+					case "tables": {
+						const handle = await resolve(call.id);
+						return { tables: Object.keys(handle.export()).map((name) => {
+							const table = handle.table(name);
+							return {
+								name,
+								primary: table.primary,
+								columns: table.contract.schema
+							};
+						}) };
+					}
+					case "get": {
+						const table = (await resolve(call.id)).table(call.table);
+						const many = Array.isArray(call.key);
+						const keys = Array.isArray(call.key) ? call.key : [call.key];
+						const rows = await table.get(keys);
+						return many ? { rows } : { row: rows[0] };
+					}
+					case "records": {
+						const table = (await resolve(call.id)).table(call.table);
+						const { criteria: probe, limit } = clampCriteria(criteriaOf(call.criteria), cap);
+						const rows = await table.records(probe, read);
+						const truncated = rows.length > limit;
+						const sliced = rows.slice(0, limit);
+						return {
+							rows: sliced,
+							count: sliced.length,
+							truncated,
+							limit
+						};
+					}
+					case "count": return { count: await (await resolve(call.id)).table(call.table).count(criteriaOf(call.criteria), read) };
+					case "aggregate": return { value: await (await resolve(call.id)).table(call.table).aggregate(call.function, call.column, criteriaOf(call.criteria), read) };
+					case "add": {
+						const table = (await resolve(call.id)).table(call.table);
+						const many = Array.isArray(call.row);
+						const rows = Array.isArray(call.row) ? call.row : [call.row];
+						const keys = await table.add(rows, read);
+						return many ? { keys } : { key: keys[0] };
+					}
+					case "set": {
+						const table = (await resolve(call.id)).table(call.table);
+						const many = Array.isArray(call.row);
+						const rows = Array.isArray(call.row) ? call.row : [call.row];
+						const keys = await table.set(rows, read);
+						return many ? { keys } : { key: keys[0] };
+					}
+					case "update": {
+						const table = (await resolve(call.id)).table(call.table);
+						const changes = call.changes;
+						const many = Array.isArray(call.key);
+						const keys = Array.isArray(call.key) ? call.key : [call.key];
+						const updated = await table.update(keys, changes, read);
+						return many ? { updated } : { updated: updated[0] };
+					}
+					case "remove": {
+						const table = (await resolve(call.id)).table(call.table);
+						const many = Array.isArray(call.key);
+						const keys = Array.isArray(call.key) ? call.key : [call.key];
+						const removed = await table.remove(keys, read);
+						return many ? { removed } : { removed: removed[0] };
+					}
+					case "migrate": {
+						const handle = await resolve(call.id);
+						const previous = handle.export();
+						const deployed = Object.entries(previous).map(([name, table]) => tableSchema(name, table));
+						const tables = call.tables;
+						const keys = {};
+						for (const name of Object.keys(tables)) {
+							const existing = previous[name];
+							if (existing !== void 0) keys[name] = existing.key;
+						}
+						const declared = expandTables(tables);
+						const migrated = handle.import(declared, Object.keys(keys).length > 0 ? keys : void 0);
+						const migration = await migrated.migrate(deployed, read);
+						handles.set(call.id, migrated);
+						const tracked = definitions.get(call.id);
+						if (tracked !== void 0) {
+							const updated = {
+								id: call.id,
+								driver: tracked.driver,
+								tables,
+								...Object.keys(keys).length > 0 ? { keys } : {}
+							};
+							definitions.set(call.id, updated);
+							if (store !== void 0) await store.set(updated);
+						}
+						return { migration };
+					}
+					case "destroy": {
+						const cached = handles.get(call.id);
+						const persisted = store !== void 0 && cached === void 0 ? await store.get(call.id) !== void 0 : false;
+						if (cached !== void 0) {
+							await cached.close();
+							handles.delete(call.id);
+						}
+						definitions.delete(call.id);
+						if (store !== void 0) await store.delete(call.id);
+						return {
+							id: call.id,
+							destroyed: cached !== void 0 || persisted
+						};
+					}
+				}
+			} catch (error) {
+				if (isAgentToolError(error)) throw error;
+				const code = databaseToolCode(error);
+				if (code === void 0) throw error;
+				throw new AgentToolError("DATABASE", error instanceof Error ? error.message : String(error), {
+					code,
+					operation: call.operation,
+					id: call.id,
+					..."table" in call ? { table: call.table } : {}
+				});
+			}
+		}
+	});
+}
+/**
+* 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'] })
+* ```
+*/
+function createRelationTool(options) {
+	const contract = (0, _orkestrel_contract.createContract)(relationToolShape);
+	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
+	const depth = options.depth ?? 3;
+	const cap = options.limit ?? 1e3;
+	return (0, _orkestrel_agent.createTool)({
+		name: options.name ?? "relation",
+		description: options.description ?? RELATION_TOOL_DESCRIPTION,
+		summary: RELATION_TOOL_SUMMARY,
+		parameters,
+		execute: async (args) => {
+			const call = contract.parse(args);
+			if (call === void 0) throw new AgentToolError("TOOL", "malformed relation call", { args });
+			try {
+				const model = relationModelOf(relationManagerOf(options.managers, call.manager), call.model);
+				switch (call.operation) {
+					case "load": {
+						const include = expandInclude(call.include, depth);
+						if (typeof call.key === "string" || typeof call.key === "number") return { row: await model.load(call.key, include) };
+						return { rows: await model.load(call.key, include) };
+					}
+					case "find": {
+						const include = expandInclude(call.include, depth);
+						const effective = Math.min(call.limit ?? cap, cap);
+						const rows = await model.find(include, {
+							limit: effective + 1,
+							...call.offset === void 0 ? {} : { offset: call.offset },
+							...call.sort === void 0 ? {} : { sort: call.sort },
+							...call.direction === void 0 ? {} : { direction: call.direction }
+						});
+						const truncated = rows.length > effective;
+						const sliced = rows.slice(0, effective);
+						return {
+							rows: sliced,
+							count: sliced.length,
+							truncated,
+							limit: effective
+						};
+					}
+					case "link":
+						await model.link(call.key, call.relation, call.target);
+						return { linked: true };
+					case "unlink":
+						await model.unlink(call.key, call.relation, call.target);
+						return { unlinked: true };
+					case "links": {
+						const keys = await model.links(call.key, call.relation);
+						const truncated = keys.length > cap;
+						const sliced = keys.slice(0, cap);
+						return {
+							keys: sliced,
+							count: sliced.length,
+							truncated,
+							limit: cap
+						};
+					}
+				}
+			} catch (error) {
+				if (isAgentToolError(error)) throw error;
+				const relation = relationToolCode(error);
+				if (relation !== void 0) throw new AgentToolError("RELATION", error instanceof Error ? error.message : String(error), {
+					code: relation,
+					operation: call.operation,
+					model: call.model,
+					..."relation" in call ? { relation: call.relation } : {}
+				});
+				const database = databaseToolCode(error);
+				if (database === void 0) throw error;
+				throw new AgentToolError("DATABASE", error instanceof Error ? error.message : String(error), {
+					code: database,
+					operation: call.operation
+				});
+			}
+		}
+	});
+}
 //#endregion
 exports.AGENT_TOOL_DEPTH = AGENT_TOOL_DEPTH;
 exports.AGENT_TOOL_DESCRIPTION = AGENT_TOOL_DESCRIPTION;
@@ -1596,13 +2829,25 @@ exports.ANSWER_TOOL_DESCRIPTION = ANSWER_TOOL_DESCRIPTION;
 exports.ANSWER_TOOL_NAME = ANSWER_TOOL_NAME;
 exports.ANSWER_TOOL_SUMMARY = ANSWER_TOOL_SUMMARY;
 exports.AgentToolError = AgentToolError;
+exports.DATABASE_TOOL_DESCRIPTION = DATABASE_TOOL_DESCRIPTION;
+exports.DATABASE_TOOL_LIMIT = DATABASE_TOOL_LIMIT;
+exports.DATABASE_TOOL_MUTATIONS = DATABASE_TOOL_MUTATIONS;
+exports.DATABASE_TOOL_NAME = DATABASE_TOOL_NAME;
+exports.DATABASE_TOOL_SUMMARY = DATABASE_TOOL_SUMMARY;
 exports.DESCRIBE_TOOL_DESCRIPTION = DESCRIBE_TOOL_DESCRIPTION;
 exports.DESCRIBE_TOOL_NAME = DESCRIBE_TOOL_NAME;
 exports.DESCRIBE_TOOL_SUMMARY = DESCRIBE_TOOL_SUMMARY;
+exports.DatabaseDefinitionStore = DatabaseDefinitionStore;
 exports.MAX_WORKFLOW_DEPTH = MAX_WORKFLOW_DEPTH;
+exports.MemoryDefinitionStore = MemoryDefinitionStore;
 exports.PROMPT_TOOL_DESCRIPTION = PROMPT_TOOL_DESCRIPTION;
 exports.PROMPT_TOOL_NAME = PROMPT_TOOL_NAME;
 exports.PROMPT_TOOL_SUMMARY = PROMPT_TOOL_SUMMARY;
+exports.RELATION_TOOL_DEPTH = RELATION_TOOL_DEPTH;
+exports.RELATION_TOOL_DESCRIPTION = RELATION_TOOL_DESCRIPTION;
+exports.RELATION_TOOL_LIMIT = RELATION_TOOL_LIMIT;
+exports.RELATION_TOOL_NAME = RELATION_TOOL_NAME;
+exports.RELATION_TOOL_SUMMARY = RELATION_TOOL_SUMMARY;
 exports.WORKFLOW_TOOL_DESCRIPTION = WORKFLOW_TOOL_DESCRIPTION;
 exports.WORKFLOW_TOOL_FLAT_EXAMPLE = WORKFLOW_TOOL_FLAT_EXAMPLE;
 exports.WORKFLOW_TOOL_NAME = WORKFLOW_TOOL_NAME;
@@ -1615,25 +2860,59 @@ exports.WORKSPACE_TOOL_SUMMARY = WORKSPACE_TOOL_SUMMARY;
 exports.agentTag = agentTag;
 exports.agentToolShape = agentToolShape;
 exports.answerToolShape = answerToolShape;
+exports.clampCriteria = clampCriteria;
 exports.coerceAnswer = coerceAnswer;
+exports.columnKindShape = columnKindShape;
+exports.columnSchema = columnSchema;
+exports.columnShape = columnShape;
+exports.columnSpecShape = columnSpecShape;
 exports.completeDraft = completeDraft;
 exports.completePhaseDraft = completePhaseDraft;
 exports.completeTaskDraft = completeTaskDraft;
+exports.conditionShape = conditionShape;
 exports.createAgentFunction = createAgentFunction;
 exports.createAgentTool = createAgentTool;
 exports.createAnswerTool = createAnswerTool;
+exports.createDatabaseDefinitionStore = createDatabaseDefinitionStore;
+exports.createDatabaseTool = createDatabaseTool;
 exports.createDescribeTool = createDescribeTool;
+exports.createMemoryDefinitionStore = createMemoryDefinitionStore;
 exports.createPromptTool = createPromptTool;
+exports.createRelationTool = createRelationTool;
 exports.createToolFunction = createToolFunction;
 exports.createWorkflowDraftContract = createWorkflowDraftContract;
 exports.createWorkflowTool = createWorkflowTool;
 exports.createWorkspaceTool = createWorkspaceTool;
+exports.criteriaOf = criteriaOf;
+exports.criteriaShape = criteriaShape;
+exports.databaseToolCode = databaseToolCode;
+exports.databaseToolShape = databaseToolShape;
 exports.describeToolShape = describeToolShape;
+exports.expandInclude = expandInclude;
 exports.expandSteps = expandSteps;
+exports.expandTables = expandTables;
+exports.includeShape = includeShape;
 exports.isAgentToolError = isAgentToolError;
+exports.isColumnKind = isColumnKind;
+exports.isColumnSpec = isColumnSpec;
+exports.isDatabaseDefinition = isDatabaseDefinition;
+exports.keyShape = keyShape;
+exports.kindShape = kindShape;
+exports.managerShape = managerShape;
+exports.orderShape = orderShape;
 exports.phaseDraftShape = phaseDraftShape;
 exports.promptToolShape = promptToolShape;
+exports.relationKeyShape = relationKeyShape;
+exports.relationManagerOf = relationManagerOf;
+exports.relationModelOf = relationModelOf;
+exports.relationToolCode = relationToolCode;
+exports.relationToolShape = relationToolShape;
+exports.rowShape = rowShape;
+exports.rowsShape = rowsShape;
+exports.singleKeyShape = singleKeyShape;
 exports.stepShape = stepShape;
+exports.tableSchema = tableSchema;
+exports.tableSpecShape = tableSpecShape;
 exports.taskDraftShape = taskDraftShape;
 exports.terminalToolCode = terminalToolCode;
 exports.workflowDraftShape = workflowDraftShape;