@orkestrel/toolbox 0.0.24 → 0.0.25

package/dist/src/core/index.cjs

@@ -5,8 +5,8 @@ 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_workspace = require("@orkestrel/workspace");
 let _orkestrel_tool = require("@orkestrel/tool");
+let _orkestrel_workspace = require("@orkestrel/workspace");
 let _orkestrel_form = require("@orkestrel/form");
 // src/core/constants.ts
 /**
@@ -191,7 +191,7 @@ var WORKSPACE_TOOL_DESCRIPTION = [
 	"All file operations act on the ACTIVE workspace; use \"workspaces\" then \"switch\" to move between workspaces.",
 	"",
 	"Operations (each takes the fields listed):",
-	"- read     { \"operation\": \"read\", \"path\": \"<file>\" } — return the file's text.",
+	"- read     { \"operation\": \"read\", \"path\": \"<file>\" } — return the file's text, or null when the path holds no text.",
 	"- list     { \"operation\": \"list\" } — list every file in the active workspace (path, state, size, lines, kind).",
 	"- has      { \"operation\": \"has\", \"path\": \"<file>\" } — whether the file exists.",
 	"- search   { \"operation\": \"search\", \"query\": \"<text>\", \"regex\"?: bool, \"sensitive\"?: bool, \"limit\"?: int } — find lines matching the query across all files.",
@@ -205,7 +205,7 @@ var WORKSPACE_TOOL_DESCRIPTION = [
 	"- workspaces { \"operation\": \"workspaces\" } — list the workspaces you can switch between (each id, file count, active).",
 	"- switch   { \"operation\": \"switch\", \"id\": \"<id>\" } — make the workspace with that id active (ids come from \"workspaces\").",
 	"",
-	"Notes: lines and columns are 1-based (column 1 is the first character). \"regex\" defaults to false (a literal substring), \"sensitive\" defaults to true (case-sensitive). \"search\"/\"replace\"/\"splice\" act only on text files. Editing with no active workspace auto-creates one.",
+	"Notes: lines and columns are 1-based (column 1 is the first character). \"regex\" defaults to false (a literal substring), \"sensitive\" defaults to true (case-sensitive). \"search\"/\"replace\"/\"splice\" act only on text files. With no active workspace, \"write\", \"prepend\", and \"append\" create one, and \"replace\", \"splice\", \"move\", and \"remove\" refuse.",
 	"",
 	"Example — write a file:",
 	JSON.stringify(WORKSPACE_TOOL_EXAMPLE)
@@ -681,59 +681,77 @@ function isAgentFunction(value) {
 	return inspected.success && inspected.value;
 }
 /**
-* Narrows an unknown value to a {@link ColumnSpec}.
+* Narrows an unknown value to a {@link ColumnPrimitive}.
+*
+* @param value - The value to inspect
+* @returns True if `value` is `'string'`, `'integer'`, `'number'`, or `'boolean'`; false otherwise
+*/
+var isColumnPrimitive = (0, _orkestrel_contract.literalOf)("string", "integer", "number", "boolean");
+/**
+* Narrows an unknown value to a {@link ColumnSpec} — a bare {@link ColumnPrimitive}, or exactly
+* `{ primitive, optional? }`.
+*
+* @param value - The value to inspect
+* @returns True if `value` is a valid shorthand or an exact record with a valid `primitive`; false otherwise
+*/
+var isColumnSpec = (0, _orkestrel_contract.unionOf)(isColumnPrimitive, (0, _orkestrel_contract.recordOf)({
+	primitive: isColumnPrimitive,
+	optional: _orkestrel_contract.isBoolean
+}, ["optional"]));
+/**
+* Narrows an unknown value to a {@link TableSpec} — table name to exactly `{ columns }`, each column
+* a valid {@link ColumnSpec}.
 *
 * @param value - The value to inspect
-* @returns True if `value` is a valid {@link ColumnPrimitive} shorthand or a `{ primitive, optional }` record with a valid `primitive`; false otherwise
+* @returns True if `value` is a table layout; false otherwise
 */
-function isColumnSpec(value) {
-	if (isColumnPrimitive(value)) return true;
-	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
-	return isColumnPrimitive(value.primitive) && (value.optional === void 0 || (0, _orkestrel_contract.isBoolean)(value.optional));
+function isTableSpec(value) {
+	return (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isRecord)(value) && Object.values(value).every((table) => (0, _orkestrel_contract.isRecord)(table) && Object.keys(table).length === 1 && (0, _orkestrel_contract.isRecord)(table.columns) && Object.values(table.columns).every((column) => isColumnSpec(column))));
 }
 /**
-* Narrows an unknown value to a {@link ColumnPrimitive}.
+* Narrows an unknown value to a `PrimaryMap` (`@orkestrel/database`) — table name to a nonempty
+* primary-key column name.
 *
 * @param value - The value to inspect
-* @returns True if `value` is `'string'`, `'integer'`, `'number'`, or `'boolean'`; false otherwise
+* @returns True if every value is a nonempty string; false otherwise
 */
-var isColumnPrimitive = (0, _orkestrel_contract.literalOf)("string", "integer", "number", "boolean");
+function isPrimaryMap(value) {
+	return (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isRecord)(value) && Object.values(value).every((key) => (0, _orkestrel_contract.isNonEmptyString)(key)));
+}
 /**
-* Narrows an unknown value to a {@link DatabaseDefinition} — a non-empty `id` and `driver`, a
-* `tables` record whose every value is `{ columns: record of valid ColumnSpec }`, plus optional
-* `primary`, `indexes`, and finite `version` schema configuration. The boundary guard a
-* {@link import('./types.js').DefinitionStoreInterface} applies to an untrusted persisted blob
-* before trusting it as a definition (never an `as`).
+* Narrows an unknown value to an `IndexMap` (`@orkestrel/database`) — table name to its index
+* groups, each group a nonempty list of nonempty column names.
 *
 * @param value - The value to inspect
-* @returns True if `value` is a complete {@link DatabaseDefinition}; false otherwise
+* @returns True if every value is a list of such groups; false otherwise
 */
-function isDatabaseDefinition(value) {
-	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
-	if ("keys" in 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.primary !== void 0) {
-		if (!(0, _orkestrel_contract.isRecord)(value.primary)) return false;
-		for (const key of Object.values(value.primary)) if (!(0, _orkestrel_contract.isNonEmptyString)(key)) return false;
-	}
-	if (value.indexes !== void 0) {
-		if (!(0, _orkestrel_contract.isRecord)(value.indexes)) return false;
-		for (const groups of Object.values(value.indexes)) {
-			if (!(0, _orkestrel_contract.isArray)(groups)) return false;
-			for (const group of groups) {
-				if (!(0, _orkestrel_contract.isArray)(group) || group.length === 0) return false;
-				for (const column of group) if (!(0, _orkestrel_contract.isNonEmptyString)(column)) return false;
-			}
-		}
-	}
-	if (value.version !== void 0 && !(0, _orkestrel_contract.isFiniteNumber)(value.version)) return false;
-	return true;
+function isIndexMap(value) {
+	return (0, _orkestrel_contract.holds)(() => (0, _orkestrel_contract.isRecord)(value) && Object.values(value).every((groups) => (0, _orkestrel_contract.isArray)(groups) && groups.every((group) => (0, _orkestrel_contract.isArray)(group) && group.length > 0 && group.every((column) => (0, _orkestrel_contract.isNonEmptyString)(column)))));
 }
+/**
+* Narrows an unknown value to exactly a {@link DatabaseDefinition} — a non-empty `id` and `driver`,
+* a {@link TableSpec}, plus optional `primary`, `indexes`, and finite `version` schema configuration,
+* refusing every other key. The boundary guard a {@link import('./types.js').DefinitionStoreInterface}
+* applies to an untrusted persisted blob before trusting it as a definition (never an `as`).
+*
+* @remarks
+* A lockstep test holds this guard to {@link import('./shapers.js').definitionShape}.
+*
+* @param value - The value to inspect
+* @returns True if `value` is a complete {@link DatabaseDefinition}; false otherwise
+*/
+var isDatabaseDefinition = (0, _orkestrel_contract.recordOf)({
+	id: _orkestrel_contract.isNonEmptyString,
+	driver: _orkestrel_contract.isNonEmptyString,
+	tables: isTableSpec,
+	primary: isPrimaryMap,
+	indexes: isIndexMap,
+	version: _orkestrel_contract.isFiniteNumber
+}, [
+	"primary",
+	"indexes",
+	"version"
+]);
 // src/core/shapers.ts
 /**
 * Describes the shape of {@link import('./factories.js').createPromptTool}'s call arguments — `to` names the
@@ -821,9 +839,9 @@ var taskDraftShape = (0, _orkestrel_contract.objectShape)({
 		description: "Extra attempts after the first on failure; overrides the phase default. Omitted means none."
 	})),
 	timeout: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.integerShape)({
-		min: 0,
+		min: 1,
 		max: _orkestrel_workflow.MAX_TIMER_MS,
-		description: "Persisted per-attempt deadline in milliseconds (0 disables it); omitted means no deadline."
+		description: "Per-attempt deadline in milliseconds. Omit the key for no deadline."
 	}))
 });
 /**
@@ -843,6 +861,7 @@ var phaseDraftShape = (0, _orkestrel_contract.objectShape)({
 	tasks: (0, _orkestrel_contract.arrayShape)(taskDraftShape, { description: "The phase tasks; they run CONCURRENTLY." }),
 	concurrency: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.integerShape)({
 		min: 1,
+		max: Number.MAX_SAFE_INTEGER,
 		description: "Max tasks in flight at once (a resource throttle); omitted means unbounded."
 	})),
 	bail: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.literalShape)([true, false], { description: "Per-phase failure-policy override; omitted inherits the workflow bail." }))
@@ -925,13 +944,22 @@ var workflowStepsShape = (0, _orkestrel_contract.objectShape)({
 */
 var workspaceToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(["read"], { description: "Read a whole text file's text by path." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the file to read." })
+	path: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The path of the file to read."
+	})
 }), (0, _orkestrel_contract.objectShape)({ operation: (0, _orkestrel_contract.literalShape)(["list"], { description: "List every file in the workspace." }) }), (0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(["has"], { description: "Check whether a file exists at the path." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path to check for." })
+	path: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The path to check for."
+	})
 }), (0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(["search"], { description: "Search every text file for a query, returning each hit." }),
-	query: (0, _orkestrel_contract.stringShape)({ description: "The text (or regular-expression source) to search for." }),
+	query: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The text (or regular-expression source) to search for."
+	}),
 	regex: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Treat the query as a regular expression. Defaults to false (a literal substring)." })),
 	sensitive: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
 	limit: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.integerShape)({
@@ -940,7 +968,10 @@ var workspaceToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_cont
 	}))
 }), (0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(["replace"], { description: "Replace a query with a replacement across every text file." }),
-	query: (0, _orkestrel_contract.stringShape)({ description: "The text (or regular-expression source) to replace." }),
+	query: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The text (or regular-expression source) to replace."
+	}),
 	replacement: (0, _orkestrel_contract.stringShape)({ description: "The text to substitute for each match." }),
 	regex: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Treat the query as a regular expression. Defaults to false (a literal substring)." })),
 	sensitive: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
@@ -950,11 +981,17 @@ var workspaceToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_cont
 	}))
 }), (0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(["write"], { description: "Create or overwrite a whole file with content." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the file to write." }),
+	path: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The path of the file to write."
+	}),
 	content: (0, _orkestrel_contract.stringShape)({ description: "The full new contents of the file." })
 }), (0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(["splice"], { description: "Replace a 1-based range of an existing text file (from inclusive, to exclusive) with content." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the text file to edit." }),
+	path: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The path of the text file to edit."
+	}),
 	content: (0, _orkestrel_contract.stringShape)({ description: "The text to splice in place of the range." }),
 	fromLine: (0, _orkestrel_contract.integerShape)({
 		min: 1,
@@ -974,19 +1011,34 @@ var workspaceToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_cont
 	})
 }), (0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(["prepend"], { description: "Add content to the start of a file (creating it when absent)." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the file to prepend to." }),
+	path: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The path of the file to prepend to."
+	}),
 	content: (0, _orkestrel_contract.stringShape)({ description: "The text to add at the start of the file." })
 }), (0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(["append"], { description: "Add content to the end of a file (creating it when absent)." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the file to append to." }),
+	path: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The path of the file to append to."
+	}),
 	content: (0, _orkestrel_contract.stringShape)({ description: "The text to add at the end of the file." })
 }), (0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(["move"], { description: "Rename or move a file (overwriting an occupied target)." }),
-	from: (0, _orkestrel_contract.stringShape)({ description: "The current path of the file." }),
-	to: (0, _orkestrel_contract.stringShape)({ description: "The new path for the file." })
+	from: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The current path of the file."
+	}),
+	to: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The new path for the file."
+	})
 }), (0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(["remove"], { description: "Delete a file from the workspace." }),
-	path: (0, _orkestrel_contract.stringShape)({ description: "The path of the file to remove." })
+	path: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The path of the file to remove."
+	})
 }), (0, _orkestrel_contract.objectShape)({ operation: (0, _orkestrel_contract.literalShape)(["workspaces"], { description: "List the workspaces you can move between (each id, file count, and whether it is active), so you can pick an id to switch to." }) }), (0, _orkestrel_contract.objectShape)({
 	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)." })
@@ -1005,12 +1057,41 @@ var columnSpecShape = (0, _orkestrel_contract.unionShape)(columnPrimitiveShape,
 }));
 /** Describes 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 primitive or its { primitive, optional } spec." }) }), { description: "Table name to its column layout." });
+/** Describes a {@link import('./types.js').DatabaseDefinition}'s `primary` map — table name to its primary-key column. */
+var primaryShape = (0, _orkestrel_contract.recordShape)((0, _orkestrel_contract.stringShape)({ min: 1 }), { description: "Table name to its primary-key column." });
+/** Describes a {@link import('./types.js').DatabaseDefinition}'s `indexes` map — table name to its index column groups. */
+var indexesShape = (0, _orkestrel_contract.recordShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.stringShape)({ min: 1 }), {
+	min: 1,
+	description: "One nonempty index group of column names."
+}), { description: "Zero or more index groups declared for the table." }), { description: "Table name to its index column groups." });
+/**
+* Describes a stored {@link import('./types.js').DatabaseDefinition} exactly: the owned record
+* {@link import('./stores/DatabaseDefinitionStore.js').DatabaseDefinitionStore} reads and writes.
+*
+* @remarks
+* {@link import('./validators.js').isDatabaseDefinition} is the guard the store runs, and a lockstep
+* test holds it to this shape. The compiled contract fills a refusal's faults.
+*/
+var definitionShape = (0, _orkestrel_contract.objectShape)({
+	id: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The database id."
+	}),
+	driver: (0, _orkestrel_contract.stringShape)({
+		min: 1,
+		description: "The registered driver key."
+	}),
+	tables: tableSpecShape,
+	primary: (0, _orkestrel_contract.optionalShape)(primaryShape),
+	indexes: (0, _orkestrel_contract.optionalShape)(indexesShape),
+	version: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.numberShape)({ description: "The schema version for open-time reconciliation." }))
+});
 /**
 * Describes one key value for the database tool and the relation tool — a string or number; the
 * array form (multiple keys, positional) resolves first, so an array argument is read as many keys
 * rather than one.
 */
-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." }));
+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 null there." }), (0, _orkestrel_contract.stringShape)({ description: "One row key." }), (0, _orkestrel_contract.numberShape)({ description: "One row key." }));
 /** Describes a loose row — a flat object of column name to JSON value. */
 var rowShape = (0, _orkestrel_contract.recordShape)((0, _orkestrel_contract.jsonShape)(), { description: "A row as a flat object of column name to value." });
 /**
@@ -1087,11 +1168,8 @@ var databaseToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contr
 		min: 1,
 		description: "The registered driver key. Defaults to \"memory\"."
 	})),
-	primary: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.recordShape)((0, _orkestrel_contract.stringShape)({ min: 1 }), { description: "Table name to its primary-key column." })),
-	indexes: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.recordShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.stringShape)({ min: 1 }), {
-		min: 1,
-		description: "One nonempty index group of column names."
-	}), { description: "Zero or more index groups declared for the table." }), { description: "Table name to its index column groups." })),
+	primary: (0, _orkestrel_contract.optionalShape)(primaryShape),
+	indexes: (0, _orkestrel_contract.optionalShape)(indexesShape),
 	version: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.numberShape)({ description: "The schema version for open-time reconciliation." }))
 }), (0, _orkestrel_contract.objectShape)({
 	operation: (0, _orkestrel_contract.literalShape)(["tables"], { description: "List a database's table names." }),
@@ -1300,8 +1378,8 @@ var relationToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contr
 * optional `candidates` array to check against the inferred schema.
 *
 * @remarks
-* `samples` requires at least one element (`min: 1`) — an empty array parses to `undefined`,
-* surfaced by the handler as a typed `TOOL` {@link import('./errors.js').ToolboxError}. When
+* `samples` requires at least one element (`min: 1`) — the Tool door refuses an empty array with
+* a `ToolError` carrying code `ARGUMENTS` (`@orkestrel/tool`). When
 * `candidates` is present (any array, including empty), the handler compiles a contract from the
 * freshly inferred schema and checks each candidate against it with a strict guard (`.is`, no
 * coercion) — the opposite of {@link import('./factories.js').createEndpointTool}'s normalizing
@@ -1316,6 +1394,20 @@ var inferToolShape = (0, _orkestrel_contract.objectShape)({
 	enum: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Infer enum constraints from repeated literal values. Defaults to false." })),
 	candidates: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.jsonShape)(), { description: "Optional values to check against the freshly inferred schema. When present, the tool returns a per-candidate verdict (strict — no coercion) alongside the inferred parameters." }))
 });
+// src/core/contracts.ts
+/**
+* Holds the compiled {@link import('./shapers.js').definitionShape}, whose `audit` fills the faults a
+* refused stored definition carries.
+*
+* @example
+* ```ts
+* import { definitionContract } from '@orkestrel/toolbox'
+*
+* definitionContract.audit({ id: 'shop', driver: 'memory', tables: {}, keys: {} })
+* // [{ reason: 'extra', path: ['keys'] }]
+* ```
+*/
+var definitionContract = (0, _orkestrel_contract.createContract)(definitionShape);
 // src/core/helpers.ts
 /**
 * Returns the ancestry identifier of a workflow in a run chain — `workflow:<id>`.
@@ -1564,7 +1656,7 @@ function inferRelationCode(error) {
 function expandInclude(paths, depth) {
 	return Iterator.from(paths ?? []).reduce((include, path) => {
 		const segments = path.split(".");
-		if (segments.length > depth || segments.some((segment) => segment.length === 0)) throw new ToolboxError("TOOL", `malformed include path '${path}'`, {
+		if (segments.length > depth || segments.some((segment) => segment.length === 0)) throw new ToolboxError("TOOL", `malformed include path ${(0, _orkestrel_contract.preview)(path)}; send dot-separated relation names with no empty segment and at most ${String(depth)} segments`, {
 			path,
 			depth
 		});
@@ -1620,7 +1712,7 @@ function expandInclude(paths, depth) {
 function resolveRelationManager(managers, name) {
 	if (name !== void 0) {
 		const manager = managers[name];
-		if (manager === void 0) throw new ToolboxError("TOOL", `unknown relation manager '${name}'`, {
+		if (manager === void 0) throw new ToolboxError("TOOL", `unknown relation manager ${(0, _orkestrel_contract.preview)(name)}; send manager as one of ${renderCandidates(Object.keys(managers))}`, {
 			manager: name,
 			managers: Object.keys(managers)
 		});
@@ -1632,7 +1724,7 @@ function resolveRelationManager(managers, name) {
 		const manager = managers[single];
 		if (manager !== void 0) return manager;
 	}
-	throw new ToolboxError("TOOL", "no relation manager resolved for the call", { managers: names });
+	throw new ToolboxError("TOOL", `no relation manager resolved for the call; send manager as one of ${renderCandidates(names)}`, { managers: names });
 }
 /**
 * Resolves a `model` name against a live {@link RelationManagerInterface} — the pure model-lookup
@@ -1644,7 +1736,7 @@ function resolveRelationManager(managers, name) {
 * @returns The model's {@link ModelInterface}
 */
 function resolveRelationModel(manager, name) {
-	if (!manager.has(name)) throw new ToolboxError("TOOL", `unknown model '${name}'`, {
+	if (!manager.has(name)) throw new ToolboxError("TOOL", `unknown model ${(0, _orkestrel_contract.preview)(name)}; send model as one of ${renderCandidates(manager.names())}`, {
 		model: name,
 		models: manager.names()
 	});
@@ -1738,7 +1830,21 @@ function clampQuery(query, cap) {
 	};
 }
 /**
-* Resolves an owned workflow input through the supplied flat or draft contracts.
+* Resolves an owned workflow input through the supplied flat or draft contracts, or refuses it with
+* what to send.
+*
+* @remarks
+* Empty input is the wrapped definition. A `phases` key with no `steps` key takes the draft form,
+* and everything else takes the advertised flat form, so a blob carrying both keys refuses `phases`
+* as undeclared rather than ignoring it, and a blob carrying neither is told to send `steps`.
+*
+* @param owned - The call's owned JSON arguments
+* @param definition - The wrapped definition empty input runs
+* @param steps - The compiled flat form
+* @param draft - The compiled draft form
+* @returns The definition the input resolves to
+* @throws {import('@orkestrel/tool').ToolError} Thrown with code `ARGUMENTS` when the chosen form refuses the input, carrying `context.faults`
+*
 * @example
 * ```ts
 * import { createContract } from '@orkestrel/contract'
@@ -1751,12 +1857,196 @@ function clampQuery(query, cap) {
 */
 function resolveWorkflowTarget(owned, definition, steps, draft) {
 	if (Object.keys(owned).length === 0) return definition;
-	if ((0, _orkestrel_contract.isArray)(owned.steps)) {
-		const flat = steps.parse(owned);
-		return flat === void 0 ? void 0 : expandSteps(flat);
+	return Object.hasOwn(owned, "phases") && !Object.hasOwn(owned, "steps") ? completeDraft(requireToolCall(draft, owned)) : expandSteps(requireToolCall(steps, owned));
+}
+/**
+* Renders the candidates a refusal offers, each encoded and length-capped and at most
+* `REFUSAL_LIST_LIMIT` of them named, so a long or multiline name cannot fake or balloon the message.
+*
+* @param names - The candidates to offer
+* @returns The encoded candidates joined with `, `, empty when there are none
+*
+* @example
+* ```ts
+* import { renderCandidates } from '@src/core'
+*
+* renderCandidates(['read', 'list']) // '"read", "list"'
+* ```
+*/
+function renderCandidates(names) {
+	return (0, _orkestrel_contract.renderList)(names.map((name) => (0, _orkestrel_contract.preview)(name)));
+}
+/**
+* Caps the complete text of a refusal at `FAULT_TEXT_LIMIT` characters, saying where it stopped.
+*
+* @remarks
+* A refusal goes back to a model whose context window can be small. Use this where a message joins
+* parts this package cannot bound one by one: a head beside a report, or an upstream error's text.
+*
+* @param text - The refusal text
+* @returns The text unchanged when it fits, otherwise cut to the limit and well formed
+*
+* @example
+* ```ts
+* import { limitRefusal } from '@src/core'
+*
+* limitRefusal('send steps') // 'send steps'
+* limitRefusal('x'.repeat(5000)).length // 2048
+* ```
+*/
+function limitRefusal(text) {
+	if (text.length <= _orkestrel_contract.FAULT_TEXT_LIMIT) return text;
+	return `${text.slice(0, _orkestrel_contract.FAULT_TEXT_LIMIT - 62).toWellFormed()}… the message stops here; correct what it names and call again`;
+}
+/**
+* Reads a call's arguments through a compiled contract, or refuses them with what to send.
+*
+* @remarks
+* Uses the contract admission door and translates refusals to tool errors.
+* Tools with object and union roots enforce `createTool`'s `contract` and use this helper to type
+* the parsed arguments. The workflow tool uses this door under `strict: false` because it accepts
+* several authoring forms while advertising the flat form.
+*
+* @param contract - The compiled contract of the arguments
+* @param value - The arguments the call sent
+* @returns The admitted value, which may retain input identity under a union
+* @throws {import('@orkestrel/tool').ToolError} Thrown with code `ARGUMENTS`, carrying `context.faults` when the arguments could be read
+*
+* @example
+* ```ts
+* import { createContract, numberShape, objectShape } from '@orkestrel/contract'
+* import { requireToolCall } from '@src/core'
+*
+* const contract = createContract(objectShape({ amount: numberShape() }))
+* requireToolCall(contract, { amount: '3' }) // { amount: 3 }
+* requireToolCall(contract, { amount: 3, extra: 1 }) // throws ToolError ('ARGUMENTS')
+* ```
+*/
+function requireToolCall(contract, value) {
+	const read = (0, _orkestrel_contract.admitValue)(contract, value);
+	if (!read.success) {
+		if (read.error.cause === void 0) throw buildArgumentRefusal(contract.schema, value, read.error.faults);
+		throw new _orkestrel_tool.ToolError("ARGUMENTS", "Arguments could not be read; send one JSON object of plain values", void 0, { cause: read.error.cause });
 	}
-	const parsed = draft.parse(owned);
-	return parsed === void 0 ? void 0 : completeDraft(parsed);
+	return read.value.value;
+}
+/**
+* Builds an argument refusal from the supplied faults, auditing the schema when no faults were supplied.
+*
+* @remarks
+* Uses the contract's union reporting: a selected arm names its own faults, and a value selecting
+* no arm receives a bounded summary of alternatives. Supplied faults remain unchanged.
+*
+* @param schema - The compiled schema the arguments are held to
+* @param value - The arguments the call sent
+* @param faults - The faults admission reported
+* @returns The `ToolError` to throw, with code `ARGUMENTS` and the faults in `context.faults`
+*
+* @example
+* ```ts
+* import { createContract, literalShape, objectShape, stringShape, unionShape } from '@orkestrel/contract'
+* import { buildArgumentRefusal } from '@src/core'
+*
+* const { schema } = createContract(
+* 	unionShape(
+* 		objectShape({ operation: literalShape(['read']), path: stringShape() }),
+* 		objectShape({ operation: literalShape(['list']) }),
+* 	),
+* )
+* buildArgumentRefusal(schema, { operation: 'read' }, []).message
+* // 'path: missing; expected string'
+* ```
+*/
+function buildArgumentRefusal(schema, value, faults) {
+	const listed = faults.length === 0 ? (0, _orkestrel_contract.createContract)((0, _orkestrel_contract.schemaToShape)(schema)).audit(value) : faults;
+	return new _orkestrel_tool.ToolError("ARGUMENTS", (0, _orkestrel_contract.describeFaults)(listed, schema), { faults: listed });
+}
+/**
+* Picks the effective value of a positive numeric tool option: the configured value when it is a
+* positive safe integer, and the fallback when it is omitted.
+*
+* @param value - The configured option, or `undefined`
+* @param fallback - The default an omitted option takes
+* @param subject - The name the refusal gives the option
+* @returns The effective value
+* @throws {ToolboxError} Thrown with code `TOOL` when `value` is present and is anything else, because `NaN` as a bound passes every comparison
+*
+* @example
+* ```ts
+* import { resolveBound } from '@src/core'
+*
+* resolveBound(undefined, 100, 'database limit') // 100
+* resolveBound(25, 100, 'database limit') // 25
+* resolveBound(0, 100, 'database limit') // throws ToolboxError ('TOOL')
+* ```
+*/
+function resolveBound(value, fallback, subject) {
+	if (value === void 0) return fallback;
+	if ((0, _orkestrel_agent.isPositiveSafeInteger)(value)) return value;
+	throw new ToolboxError("TOOL", `${subject} must be a positive safe integer; received ${(0, _orkestrel_contract.preview)(value)}; omit it for the default ${String(fallback)}`, { received: (0, _orkestrel_contract.preview)(value) });
+}
+/**
+* Reads the active workspace for an operation that edits a file that must already exist, or refuses.
+*
+* @param manager - The manager the workspace tool drives
+* @param operation - The operation that needs an active workspace
+* @returns The active workspace
+* @throws {ToolboxError} Thrown with code `TOOL` when no workspace is active, and creates none
+*
+* @example
+* ```ts
+* import { createWorkspaceManager } from '@orkestrel/workspace'
+* import { requireActiveWorkspace } from '@src/core'
+*
+* const manager = createWorkspaceManager()
+* const workspace = manager.add()
+* requireActiveWorkspace(manager, 'remove') === workspace // true
+* ```
+*/
+function requireActiveWorkspace(manager, operation) {
+	const active = manager.active;
+	if (active !== void 0) return active;
+	throw new ToolboxError("TOOL", `operation ${(0, _orkestrel_contract.preview)(operation)} needs an active workspace and none is; call "write" to create one, or "workspaces" then "switch"`, { operation });
+}
+/**
+* Describes a stored definition that names another id, naming the id it holds and the id it must hold.
+*
+* @param id - The database id the row is stored under
+* @param held - The id the stored definition names
+* @returns The refusal message
+*
+* @example
+* ```ts
+* import { describeDefinitionMismatch } from '@src/core'
+*
+* describeDefinitionMismatch('shop', 'other')
+* // 'database "shop" holds a definition that names id "other"; its id must be "shop"; ...'
+* ```
+*/
+function describeDefinitionMismatch(id, held) {
+	const required = (0, _orkestrel_contract.preview)(id);
+	return `database ${required} holds a definition that names id ${(0, _orkestrel_contract.preview)(held)}; its id must be ${required}; read the row through your own table and set its id to ${required}, or delete it with store.delete(${required})`;
+}
+/**
+* Describes a stored definition this package refuses to read, naming its first fault and the remedy.
+*
+* @param id - The database id the row is stored under
+* @param faults - The refused definition's faults
+* @returns The refusal message
+*
+* @example
+* ```ts
+* import { describeDefinitionRefusal } from '@src/core'
+*
+* describeDefinitionRefusal('shop', [{ reason: 'extra', path: ['keys'] }])
+* // 'database "shop" holds a definition this version refuses (extra key "keys" at the root; ...'
+* ```
+*/
+function describeDefinitionRefusal(id, faults) {
+	const [first] = faults;
+	const path = first === void 0 ? [] : (0, _orkestrel_contract.extractPath)(first);
+	const held = (0, _orkestrel_contract.preview)(id);
+	return `database ${held} holds a definition this version refuses (${first?.reason === "extra" ? `extra key ${(0, _orkestrel_contract.preview)(path.at(-1))} at ${path.length === 1 ? "the root" : (0, _orkestrel_contract.preview)(path.slice(0, -1).join("."))}` : first === void 0 ? "a value its shape cannot name" : `${first.reason} at ${path.length === 0 ? "the root" : (0, _orkestrel_contract.preview)(path.join("."))}`}; a definition written before this change can carry it); read the row through your own table and ${first?.reason === "extra" ? "rewrite it without the key" : "rewrite it to the declared shape"}, or delete it with store.delete(${held})`;
 }
 // src/core/compilers.ts
 /**
@@ -1810,8 +2100,8 @@ function compileColumnPrimitive(primitive) {
 * {@link import('../factories.js').createMemoryDefinitionStore} builds. It implements the same
 * {@link DefinitionStoreInterface} contract as
 * {@link import('./DatabaseDefinitionStore.js').DatabaseDefinitionStore}: this store copies on
-* write and on read; the table-backed store narrows an untrusted stored blob and reports
-* `undefined` for a malformed one.
+* write and on read; the table-backed store narrows an untrusted stored blob and refuses a malformed
+* one.
 *
 * @remarks
 * A plain `Map<string, DatabaseDefinition>` (the definition is already pure,
@@ -1895,12 +2185,15 @@ var MemoryDefinitionStore = class {
 * and keeps the row type flat (`definition` reads back as `unknown`).
 *
 * - **`set(definition)` upserts under the definition's own `id`** (no separate id param) — it
-*   writes the row `{ id: definition.id, definition }`.
+*   writes the row `{ id: definition.id, definition }`, and first refuses what `get` would refuse,
+*   so no row is written that `get` cannot read.
 * - **`get(id)` resolves the stored definition for an id**, narrowing the opaque JSON column back
 *   to a {@link DatabaseDefinition} ({@link import('../validators.js').isDatabaseDefinition} — the
-*   boundary narrow for an untrusted storage read), or `undefined` if none is stored
-*   or the stored blob is malformed.
-* - **`delete(id)` drops a definition by id**; an absent id is a no-op (no throw).
+*   boundary narrow for an untrusted storage read), or `undefined` if no row is stored. A present
+*   row whose blob is malformed or names another id throws, because reading it as absent would let
+*   a later `set` overwrite it.
+* - **`delete(id)` drops a definition by id** without reading it, the remedy for a refused row; an
+*   absent id is a no-op (no throw).
 *
 * The public surface is exactly `get` / `set` / `delete` — no extra members (the method
 * bijection with {@link DefinitionStoreInterface}).
@@ -1931,21 +2224,47 @@ var DatabaseDefinitionStore = class {
 	* {@link DatabaseDefinition}.
 	*
 	* @param id - The database id to read
-	* @returns The stored {@link DatabaseDefinition}, or `undefined` when none is stored or the
-	*   stored blob is malformed
+	* @returns The stored {@link DatabaseDefinition}, or `undefined` when no row is stored
+	* @throws {ToolboxError} Thrown with code `DATABASE` when the row's blob is malformed or names another id, with the faults under `context.faults`
 	*/
 	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;
+		const definition = row.definition;
+		if (!isDatabaseDefinition(definition)) {
+			const faults = definitionContract.audit(definition);
+			throw new ToolboxError("DATABASE", describeDefinitionRefusal(id, faults), {
+				id,
+				faults
+			});
+		}
+		if (definition.id !== id) {
+			const faults = [{
+				reason: "type",
+				path: ["id"],
+				expected: "literal",
+				received: (0, _orkestrel_contract.preview)(definition.id)
+			}];
+			throw new ToolboxError("DATABASE", describeDefinitionMismatch(id, definition.id), {
+				id,
+				faults
+			});
+		}
+		return definition;
 	}
 	/**
 	* Inserts or replaces a definition under its own `id` — the written row is `{ id, definition }`.
 	*
 	* @param definition - The config to persist; its own `id` is the row key (no separate id param)
 	* @returns A promise settling after the row is written
+	* @throws {ToolboxError} Thrown with code `DATABASE` before any write when the definition fails the guard `get` reads, with the faults under `context.faults`
 	*/
 	async set(definition) {
+		if (!isDatabaseDefinition(definition)) {
+			const unchecked = definition;
+			const faults = definitionContract.audit(unchecked);
+			throw new ToolboxError("DATABASE", limitRefusal(`a definition store writes only a complete definition; correct each line and call set again:\n${(0, _orkestrel_contract.describeFaults)(faults, definitionContract.schema)}`), { faults });
+		}
 		await this.#table.set({
 			id: definition.id,
 			definition
@@ -2044,7 +2363,7 @@ var DatabaseResolver = class {
 			const definition = await this.#store.get(id);
 			if (definition !== void 0) {
 				const factory = this.#drivers[definition.driver];
-				if (factory === void 0) throw new ToolboxError("TOOL", `unknown driver '${definition.driver}'`, {
+				if (factory === void 0) throw new ToolboxError("TOOL", `database ${(0, _orkestrel_contract.preview)(id)} names unknown driver ${(0, _orkestrel_contract.preview)(definition.driver)}; register it in the tool's drivers, one of ${renderCandidates(Object.keys(this.#drivers))}`, {
 					id,
 					driver: definition.driver
 				});
@@ -2061,7 +2380,7 @@ var DatabaseResolver = class {
 				return handle;
 			}
 		}
-		throw new ToolboxError("TOOL", `unknown database '${id}'`, { id });
+		throw new ToolboxError("TOOL", `unknown database ${(0, _orkestrel_contract.preview)(id)}; define it first with { "operation": "create", "id", "tables" }`, { id });
 	}
 };
 // src/core/factories.ts
@@ -2118,7 +2437,8 @@ function createToolFunction(tools, name) {
 * targets deeper than {@link import('./constants.js').MAX_WORKFLOW_CHAIN} are rejected before
 * agent or runner activity. When {@link import('./types.js').AgentFunctionOptions.runner} is
 * supplied, the adapter binds a recursion-safe {@link createWorkflowTool} onto the agent's
-* `context.tools`, propagating opaque leaves, raw agents, lineage, and the native store. The
+* `context.tools`, propagating opaque leaves, raw agents, lineage, and the native store. The agent
+* needs an `authority` of its own to run that tool, because an agent with none denies every call. The
 * task's cancellation propagates through the Agent's native per-run signal seam:
 * `agent.generate({ signal: controller.signal })` resolves a partial `AgentResult` on a cancel
 * (never rejects), projected onto its exact JSON fields.
@@ -2264,7 +2584,12 @@ function createWorkflowDraftContract() {
 * It is also the propagation carrier
 * {@link createAgentFunction} binds onto a wrapped agent's `context.tools`: because a tool
 * handler receives only the model-supplied `args`, the immutable lineage is closed over at bind
-* time. The authored target is appended and its zero-based depth derived from workflow tags.
+* time. The authored target is appended and its zero-based depth derived from workflow tags. That
+* bound tool wraps the containing workflow's id over no phases, and its empty-args call always
+* refuses as a cycle before the runner, so the wrapper never runs.
+*
+* `parameters` advertises the flat form alone, so the tool is built `strict: false` and its handler
+* runs the door ({@link import('./helpers.js').requireToolCall}) on the form the arguments take.
 *
 * **Widened authoring surface (additive — the canonical contract and runner stay strict and
 * unchanged).** A 2B model reliably calls the tool but cannot reliably emit the full nested
@@ -2279,9 +2604,11 @@ function createWorkflowDraftContract() {
 *   super-set.
 *
 * The universal tool-handler contract: returns the plain run summary
-* (`{ status, count, durable?, fault? }`) on success, throws a typed `ToolboxError` on Toolbox
-* boundary failures — malformed authored args (`TOOL`), or an over-deep / cyclic nested run
-* (`DEPTH`) — and preserves genuine runner `WorkflowError`s. The `ToolManagerInterface` isolates every throw into the canonical tool result's
+* (`{ status, count, durable?, fault? }`) on success. Malformed authored args throw a `ToolError`
+* with code `ARGUMENTS` (`@orkestrel/tool`) whose text lists what to correct, carrying
+* `context.faults`; a wrapped definition the strict contract refuses throws `TOOL`, and an over-deep
+* or cyclic nested run throws `DEPTH`. Genuine runner `WorkflowError`s are preserved, including
+* `SCHEDULE` for a target with no task. The `ToolManagerInterface` isolates every throw into the canonical tool result's
 * top-level `error`, so nothing escapes the run. `options.lineage` is the propagation carrier
 * across a workflow → agent → workflow chain. Opaque `functions` remain host leaves; raw `agents`
 * are contextually adapted through {@link createWorkflowFunctions}; native checkpoint persistence
@@ -2349,20 +2676,26 @@ function createWorkflowTool(definition, runner, options) {
 		description: WORKFLOW_TOOL_DESCRIPTION,
 		summary: WORKFLOW_TOOL_SUMMARY,
 		...parameters === void 0 ? {} : { parameters },
+		strict: false,
 		async execute(args) {
 			const cloned = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.cloneJSONRecord)(args));
-			if (!cloned.success) throw new ToolboxError("TOOL", "malformed workflow definition", { workflow: definition.id });
-			const owned = cloned.value;
-			const target = resolveWorkflowTarget(owned, definition, steps, draft);
-			if (target === void 0 || !strict.is(target)) throw new ToolboxError("TOOL", "malformed workflow definition", { workflow: definition.id });
+			if (!cloned.success) throw new _orkestrel_tool.ToolError("ARGUMENTS", `Arguments could not be read; send one JSON object such as ${JSON.stringify(WORKFLOW_TOOL_FLAT_EXAMPLE)}`, void 0, { cause: cloned.error });
+			const target = resolveWorkflowTarget(cloned.value, definition, steps, draft);
+			if (!strict.is(target)) {
+				const faults = strict.audit(target);
+				throw new ToolboxError("TOOL", limitRefusal(`workflow ${(0, _orkestrel_contract.preview)(definition.id)} cannot run; send steps to author another one, or correct it:\n${(0, _orkestrel_contract.describeFaults)(faults, strict.schema)}`), {
+					workflow: definition.id,
+					faults
+				});
+			}
 			const tag = tagWorkflow(target.id);
-			if (lineage.includes(tag)) throw new ToolboxError("DEPTH", `workflow '${target.id}' is already an ancestor (cycle)`, {
+			if (lineage.includes(tag)) throw new ToolboxError("DEPTH", `workflow ${(0, _orkestrel_contract.preview)(target.id)} is already an ancestor (cycle); send steps with a new name, or phases with a new id`, {
 				workflow: target.id,
 				lineage: [...lineage]
 			});
 			const targetLineage = extendLineage(lineage, tag);
 			const depth = deriveWorkflowDepth(targetLineage);
-			if (depth > 8) throw new ToolboxError("DEPTH", `nested workflow exceeds max depth 8`, {
+			if (depth > 8) throw new ToolboxError("DEPTH", `nested workflow exceeds max depth 8; finish this task without nesting another workflow`, {
 				workflow: target.id,
 				depth,
 				max: 8
@@ -2395,17 +2728,20 @@ function createWorkflowTool(definition, runner, options) {
 * active workspace by id (lenient — an unknown id is a no-op reporting `switched: false`, never a
 * throw).
 *
-* No-active rule (the ergonomic seam): a writing op (write / splice / prepend / append / move /
-* remove / replace) run when `manager.active` is `undefined` auto-creates and activates a default
-* workspace (`manager.add()`) so the model can start writing; a pure-read op (read / list /
-* has / search) against no active workspace returns the empty result (`undefined` / `[]` /
-* `false`), never creating one and never throwing.
-*
-* The handler conforms to the universal tool-handler contract: it `contract.parse`s
-* the args, throws a `TOOL` `ToolboxError` when no operation arm matched (a malformed / unknown
-* operation), else `switch`es on `op.operation` and returns the plain result — letting a
-* `WorkspaceError` raised by the live workspace (`MISSING` / `MODALITY` / `PATTERN` / `RANGE`)
-* propagate uncaught. The range edit is the flat `'splice'` op: its flat caret integers are
+* No-active rule (the ergonomic seam): an op that can create the file it names (write / prepend /
+* append) run when `manager.active` is `undefined` auto-creates and activates a default workspace
+* (`manager.add()`) so the model can start writing; an op that edits a file that must already exist
+* (splice / move / remove / replace) refuses with a `TOOL` `ToolboxError` and creates none; a
+* pure-read op (read / list / has / search) against no active workspace returns the empty result
+* (`null` / `[]` / `false`), never creating one and never throwing.
+*
+* The Tool door enforces the operation union through `contract`, repairing lossless scalar leaves
+* and refusing malformed args with a `ToolError` carrying code `ARGUMENTS`. A selected operation
+* reports its own faults; an unknown operation reports a bounded summary of alternatives.
+* The handler then `switch`es on `op.operation` and returns the plain result
+* — letting a `WorkspaceError` raised by the live workspace (`MISSING` / `MODALITY` / `PATTERN` /
+* `RANGE`) propagate uncaught. `read` returns `null` for a path that holds no text, because JSON
+* tells that from an empty file. The range edit is the flat `'splice'` op: its flat caret integers are
 * reassembled into a `Range` (`@orkestrel/workspace`) by `rangeOf` and fed to the workspace's
 * ranged `write`.
 *
@@ -2426,15 +2762,13 @@ function createWorkflowTool(definition, runner, options) {
 function createWorkspaceTool(options) {
 	const manager = options?.manager ?? (0, _orkestrel_workspace.createWorkspaceManager)(options?.store === void 0 ? void 0 : { store: options.store });
 	const contract = (0, _orkestrel_contract.createContract)(workspaceToolShape);
-	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
 	return (0, _orkestrel_tool.createTool)({
 		name: options?.name ?? "workspace",
 		description: options?.description ?? WORKSPACE_TOOL_DESCRIPTION,
 		summary: WORKSPACE_TOOL_SUMMARY,
-		...parameters === void 0 ? {} : { parameters },
+		contract: workspaceToolShape,
 		execute(args) {
-			const op = contract.parse(args);
-			if (op === void 0) throw new ToolboxError("TOOL", "unknown or malformed operation", { args });
+			const op = requireToolCall(contract, args);
 			if (op.operation === "workspaces") {
 				const activeId = manager.active?.id;
 				return manager.workspaces().map((workspace) => ({
@@ -2456,7 +2790,7 @@ function createWorkspaceTool(options) {
 			}
 			const active = manager.active;
 			switch (op.operation) {
-				case "read": return active?.read(op.path);
+				case "read": return active?.read(op.path) ?? null;
 				case "list": return (active?.files() ?? []).map((file) => ({
 					path: file.path,
 					state: file.state,
@@ -2470,7 +2804,7 @@ function createWorkspaceTool(options) {
 					...op.sensitive === void 0 ? {} : { sensitive: op.sensitive },
 					...op.limit === void 0 ? {} : { limit: op.limit }
 				}) ?? [];
-				case "replace": return (active ?? manager.add()).replace(op.query, op.replacement, {
+				case "replace": return requireActiveWorkspace(manager, op.operation).replace(op.query, op.replacement, {
 					...op.regex === void 0 ? {} : { regex: op.regex },
 					...op.sensitive === void 0 ? {} : { sensitive: op.sensitive },
 					...op.limit === void 0 ? {} : { limit: op.limit }
@@ -2484,7 +2818,7 @@ function createWorkspaceTool(options) {
 					};
 				}
 				case "splice": {
-					const workspace = active ?? manager.add();
+					const workspace = requireActiveWorkspace(manager, op.operation);
 					workspace.write(op.path, op.content, (0, _orkestrel_workspace.rangeOf)(op.fromLine, op.fromColumn, op.toLine, op.toColumn));
 					return {
 						path: op.path,
@@ -2508,7 +2842,7 @@ function createWorkspaceTool(options) {
 					};
 				}
 				case "move": {
-					const workspace = active ?? manager.add();
+					const workspace = requireActiveWorkspace(manager, op.operation);
 					return {
 						from: op.from,
 						to: op.to,
@@ -2516,7 +2850,7 @@ function createWorkspaceTool(options) {
 					};
 				}
 				case "remove": {
-					const workspace = active ?? manager.add();
+					const workspace = requireActiveWorkspace(manager, op.operation);
 					return {
 						path: op.path,
 						removed: workspace.remove(op.path)
@@ -2531,16 +2865,20 @@ function createWorkspaceTool(options) {
 * from `registry` and runs it to completion for one delegated `task`.
 *
 * @remarks
-* The universal tool-handler contract: validates the call args against
-* {@link import('./shapers.js').agentToolShape}, assembles an `AgentJobInput` (`task` seeds the
+* The universal tool-handler contract: the Tool door holds the call args to
+* {@link import('./shapers.js').agentToolShape}, refusing a malformed call with a `ToolError`
+* carrying code `ARGUMENTS`. The handler assembles an `AgentJobInput` (`task` seeds the
 * sub-agent's conversation as a single `user` message; `provider` / `tools` / `system` fall
-* back to the tool's own {@link import('./types.js').AgentToolOptions} defaults), rehydrates the sub-agent through
+* back to the tool's own {@link import('./types.js').AgentToolOptions} defaults, and `authority` is
+* the tool's own, never the call's), rehydrates the sub-agent through
 * `registry.build`, runs it with `agent.generate()`, and returns the settled
-* `AgentResult.content` string (the sub-agent's final text). A missing / unresolvable `provider`, or a malformed call, throws a typed `TOOL`
+* `AgentResult.content` string (the sub-agent's final text). A missing / unresolvable `provider`, or
+* tools with no configured `authority`, throws a typed `TOOL`
 * {@link import('./errors.js').ToolboxError}; a delegation that would exceed
 * {@link import('./constants.js').AGENT_TOOL_DEPTH}, or re-enter an already-delegated agent (a
 * cycle), throws a typed `DEPTH` {@link import('./errors.js').ToolboxError}, each isolated
-* by the `ToolManagerInterface` into the canonical tool result's top-level `error`.
+* by the `ToolManagerInterface` into the canonical tool result's top-level `error`. A `depth` that
+* is not a nonnegative safe integer throws `TOOL` at construction.
 *
 * `AgentInterface` (`@orkestrel/agent`) exposes no teardown method — a bound sub-agent's
 * lifetime is the single `generate()` call this handler awaits; there is nothing to release
@@ -2567,30 +2905,33 @@ function createWorkspaceTool(options) {
 */
 function createAgentTool(registry, options) {
 	const contract = (0, _orkestrel_contract.createContract)(agentToolShape);
-	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
 	const depth = options?.depth ?? 0;
+	if (!(0, _orkestrel_contract.isNonNegativeInteger)(depth) || !Number.isSafeInteger(depth)) throw new ToolboxError("TOOL", `agent tool depth must be a nonnegative safe integer; received ${(0, _orkestrel_contract.preview)(depth)}; omit it for a direct root`, { received: (0, _orkestrel_contract.preview)(depth) });
 	const ancestry = options?.ancestry ?? [];
 	return (0, _orkestrel_tool.createTool)({
 		name: options?.name ?? "agent",
 		description: options?.description ?? AGENT_TOOL_DESCRIPTION,
 		summary: AGENT_TOOL_SUMMARY,
-		...parameters === void 0 ? {} : { parameters },
+		contract: agentToolShape,
 		async execute(args) {
-			const call = contract.parse(args);
-			if (call === void 0) throw new ToolboxError("TOOL", "malformed agent-delegation call", { args });
+			const call = requireToolCall(contract, args);
 			const provider = call.provider ?? options?.provider;
-			if (provider === void 0) throw new ToolboxError("TOOL", "no provider resolved for the delegated agent", { task: call.task });
-			if (depth + 1 > 8) throw new ToolboxError("DEPTH", `delegation exceeds max agent depth 8`, {
+			if (provider === void 0) throw new ToolboxError("TOOL", "no provider resolved for the delegated agent; send provider as a registered provider key", { task: call.task });
+			if (depth + 1 > 8) throw new ToolboxError("DEPTH", `delegation exceeds max agent depth 8; carry out this task without delegating`, {
 				provider,
 				depth,
 				max: 8
 			});
 			const tag = tagAgent(provider);
-			if (ancestry.includes(tag)) throw new ToolboxError("DEPTH", `agent '${provider}' is already an ancestor (cycle)`, {
+			if (ancestry.includes(tag)) throw new ToolboxError("DEPTH", `agent ${(0, _orkestrel_contract.preview)(provider)} is already an ancestor (cycle); send another provider, or carry out this task without delegating`, {
 				provider,
 				ancestry: [...ancestry]
 			});
 			const tools = call.tools ?? options?.tools;
+			if (tools !== void 0 && tools.length > 0 && options?.authority === void 0) throw new ToolboxError("TOOL", "this agent tool has no authority to decide tool calls, so its sub-agent can load no tools; send tools: [] to delegate with none, or have the host set authority on this tool", {
+				provider,
+				tools: [...tools]
+			});
 			const system = call.system ?? options?.system;
 			const agent = registry.build({
 				provider,
@@ -2599,7 +2940,8 @@ function createAgentTool(registry, options) {
 					content: call.task
 				}],
 				...system === void 0 ? {} : { system },
-				...tools === void 0 ? {} : { tools }
+				...tools === void 0 ? {} : { tools },
+				...options?.authority === void 0 ? {} : { authority: options.authority }
 			});
 			const result = await agent.generate();
 			if (options?.store !== void 0) {
@@ -2620,12 +2962,13 @@ function createAgentTool(registry, options) {
 * description when `summary` is set, keeping the advertised tool list compact for a small model.
 * This tool is the on-demand expansion seam: given a registered tool's `name`, it looks the tool
 * up through `tools.tool(name)` and returns its full `description` (falling back to `summary` when a
-* tool has no `description` of its own, then a placeholder when it has neither).
+* tool has no `description` of its own, then an explicit `null` when it has neither).
 *
-* The universal tool-handler contract: validates the call args against
-* {@link import('./shapers.js').describeToolShape}, returns the plain description string on
-* success, throws a typed `TOOL` {@link import('./errors.js').ToolboxError} on a malformed call
-* or an unknown tool name.
+* The universal tool-handler contract: the Tool door holds the call args to
+* {@link import('./shapers.js').describeToolShape}, refusing a malformed call with a `ToolError`
+* carrying code `ARGUMENTS`. The handler returns the plain description on success, and throws a typed
+* `TOOL` {@link import('./errors.js').ToolboxError} that lists the registered names on an unknown
+* tool name.
 *
 * @param tools - The `ToolManagerInterface` (`@orkestrel/tool`) whose registered tools this
 *   tool can describe
@@ -2645,18 +2988,22 @@ function createAgentTool(registry, options) {
 */
 function createDescribeTool(tools) {
 	const contract = (0, _orkestrel_contract.createContract)(describeToolShape);
-	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
 	return (0, _orkestrel_tool.createTool)({
 		name: DESCRIBE_TOOL_NAME,
 		description: DESCRIBE_TOOL_DESCRIPTION,
 		summary: DESCRIBE_TOOL_SUMMARY,
-		...parameters === void 0 ? {} : { parameters },
+		contract: describeToolShape,
 		async execute(args) {
-			const call = contract.parse(args);
-			if (call === void 0) throw new ToolboxError("TOOL", "malformed describe call", { args });
+			const call = requireToolCall(contract, args);
 			const tool = tools.tool(call.name);
-			if (tool === void 0) throw new ToolboxError("TOOL", `unknown tool '${call.name}'`, { name: call.name });
-			return tool.description ?? tool.summary ?? "<no description>";
+			if (tool === void 0) {
+				const names = tools.tools().map((registered) => registered.name);
+				throw new ToolboxError("TOOL", `unknown tool ${(0, _orkestrel_contract.preview)(call.name)}; send name as one of ${renderCandidates(names)}`, {
+					name: call.name,
+					names
+				});
+			}
+			return tool.description ?? tool.summary ?? null;
 		}
 	});
 }
@@ -2665,8 +3012,9 @@ function createDescribeTool(tools) {
 * and blocks until the addressed terminal answers, returning the resolved values record.
 *
 * @remarks
-* The universal tool-handler contract: validates the call args against
-* {@link import('./shapers.js').promptToolShape}, parses the call's schema through
+* The universal tool-handler contract: the Tool door holds the call args to
+* {@link import('./shapers.js').promptToolShape}, refusing a malformed call with a `ToolError`
+* carrying code `ARGUMENTS`. The handler parses the call's schema through
 * `@orkestrel/form`, constructs the live form, and passes it to `TerminalManagerInterface.ask`.
 * `from` is fixed at construction
 * ({@link import('./types.js').PromptToolOptions.from}) — never read from the model-supplied
@@ -2674,7 +3022,7 @@ function createDescribeTool(tools) {
 * `TerminalError('DEADLOCK')`, re-surfaced as a typed `DEADLOCK`
 * {@link import('./errors.js').ToolboxError}; an expired form re-surfaces as `EXPIRE`; an
 * unknown `to` (or any other `TerminalError`) re-surfaces as `TOOL`, naming the unknown terminal
-* and how many brokers the manager holds (`manager.count`). A schema `parseForm` refuses — an
+* and the mounted terminals the manager's refusal lists, encoded and bounded. A schema `parseForm` refuses — an
 * unknown control, a duplicate field name, a `'select'` or `'checkbox'` field without usable
 * `choices` — throws a typed `TOOL` error up front, so a malformed schema never parks as a form
 * nobody can answer.
@@ -2699,37 +3047,40 @@ function createDescribeTool(tools) {
 */
 function createPromptTool(options) {
 	const contract = (0, _orkestrel_contract.createContract)(promptToolShape);
-	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
 	return (0, _orkestrel_tool.createTool)({
 		name: options.name ?? "ask",
 		description: options.description ?? PROMPT_TOOL_DESCRIPTION,
 		summary: PROMPT_TOOL_SUMMARY,
-		...parameters === void 0 ? {} : { parameters },
+		contract: promptToolShape,
 		async execute(args) {
-			const call = contract.parse(args);
-			if (call === void 0) throw new ToolboxError("TOOL", "malformed ask call", { args });
+			const call = requireToolCall(contract, args);
 			const schema = (0, _orkestrel_form.parseForm)(call.schema);
-			if (schema === void 0) throw new ToolboxError("TOOL", "malformed form schema", { schema: call.schema });
-			for (const field of schema.fields) if ((field.control === "select" || field.control === "checkbox") && !field.choices.some((choice) => choice.disabled !== true)) throw new ToolboxError("TOOL", `${field.control} field '${field.name}' has no enabled choices`, {
+			if (schema === void 0) throw new ToolboxError("TOOL", `malformed form schema; send { "fields": [{ "control", "name" }] } with unique names, where control is one of ${_orkestrel_form.FIELD_CONTROLS.join(", ")}, and select or checkbox carries choices of { "label", "value" }`, { schema: call.schema });
+			for (const field of schema.fields) if ((field.control === "select" || field.control === "checkbox") && !field.choices.some((choice) => choice.disabled !== true)) throw new ToolboxError("TOOL", `${field.control} field ${(0, _orkestrel_contract.preview)(field.name)} has no enabled choices; add a choice that is not disabled`, {
 				control: field.control,
 				field: field.name
 			});
 			try {
 				return await options.manager.ask(options.from, call.to, (0, _orkestrel_form.createForm)(schema));
 			} catch (error) {
-				if ((0, _orkestrel_form.isFormError)(error) && error.code === "ABANDONED") throw new ToolboxError("EXPIRE", `form to '${call.to}' expired before it was answered`, { to: call.to });
+				if ((0, _orkestrel_form.isFormError)(error) && error.code === "ABANDONED") throw new ToolboxError("EXPIRE", `form to ${(0, _orkestrel_contract.preview)(call.to)} expired before it was answered; ask again to give it more time`, { to: call.to });
 				const code = inferTerminalCode(error);
 				if (code === void 0) throw error;
-				if (code === "DEADLOCK") throw new ToolboxError("DEADLOCK", `asking '${call.to}' would create a form cycle`, (0, _orkestrel_terminal.isTerminalError)(error) ? error.context : {
+				if (code === "DEADLOCK") throw new ToolboxError("DEADLOCK", `asking ${(0, _orkestrel_contract.preview)(call.to)} would create a form cycle; answer the form addressed to you first`, (0, _orkestrel_terminal.isTerminalError)(error) ? error.context : {
 					from: options.from,
 					to: call.to
 				});
-				if (code === "EXPIRE") throw new ToolboxError("EXPIRE", `form to '${call.to}' expired before it was answered`, { to: call.to });
-				if ((0, _orkestrel_terminal.isTerminalError)(error) && error.code === "TARGET") throw new ToolboxError("TOOL", `unknown terminal '${call.to}'`, {
-					to: call.to,
-					count: options.manager.count
-				});
-				throw new ToolboxError("TOOL", `asking '${call.to}' failed`, { to: call.to });
+				if (code === "EXPIRE") throw new ToolboxError("EXPIRE", `form to ${(0, _orkestrel_contract.preview)(call.to)} expired before it was answered; ask again to give it more time`, { to: call.to });
+				if ((0, _orkestrel_terminal.isTerminalError)(error) && error.code === "TARGET") {
+					const listed = error.context?.known;
+					const known = (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)(listed) ? listed : [];
+					throw new ToolboxError("TOOL", `unknown terminal ${(0, _orkestrel_contract.preview)(call.to)}; ${known.length === 0 ? "no mounted terminal name is available" : `send to as one of ${renderCandidates(known)}`}`, {
+						to: call.to,
+						known,
+						count: options.manager.count
+					});
+				}
+				throw new ToolboxError("TOOL", `asking ${(0, _orkestrel_contract.preview)(call.to)} failed; ask again`, { to: call.to });
 			}
 		}
 	});
@@ -2739,8 +3090,9 @@ function createPromptTool(options) {
 * addressed to {@link import('./types.js').AnswerToolOptions.to}, or answers one of them by id.
 *
 * @remarks
-* The universal tool-handler contract: validates the call args against
-* {@link import('./shapers.js').answerToolShape} (discriminated by `operation`). `'pending'`
+* The universal tool-handler contract: the Tool door holds the call args to
+* {@link import('./shapers.js').answerToolShape} (discriminated by `operation`), refusing malformed
+* args with a `ToolError` carrying code `ARGUMENTS`. `'pending'`
 * returns a compact list (`{ id, from, schema }`) of every form addressed to `to`.
 * `'answer'` looks the form up by `id`, narrows the supplied `values` through `@orkestrel/form`,
 * and applies it through
@@ -2771,31 +3123,32 @@ function createPromptTool(options) {
 */
 function createAnswerTool(options) {
 	const contract = (0, _orkestrel_contract.createContract)(answerToolShape);
-	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
 	return (0, _orkestrel_tool.createTool)({
 		name: options.name ?? "answer",
 		description: options.description ?? ANSWER_TOOL_DESCRIPTION,
 		summary: ANSWER_TOOL_SUMMARY,
-		...parameters === void 0 ? {} : { parameters },
+		contract: answerToolShape,
 		async execute(args) {
-			const call = contract.parse(args);
-			if (call === void 0) throw new ToolboxError("TOOL", "malformed answer call", { args });
+			const call = requireToolCall(contract, args);
 			if (call.operation === "pending") return options.manager.pending(options.to).map((form) => ({
 				id: form.id,
 				from: form.from,
 				schema: form.schema
 			}));
-			if (options.manager.pending(options.to).find((entry) => entry.id === call.id) === void 0) throw new ToolboxError("ANSWER", `unknown form '${call.id}'`, {
+			if (options.manager.pending(options.to).find((entry) => entry.id === call.id) === void 0) throw new ToolboxError("ANSWER", `unknown form ${(0, _orkestrel_contract.preview)(call.id)}; call { "operation": "pending" } for the ids you can answer`, {
 				id: call.id,
 				reason: "unknown"
 			});
-			if (!(0, _orkestrel_form.isFormValues)(call.values)) throw new ToolboxError("TOOL", "malformed form values", { values: call.values });
+			if (!(0, _orkestrel_form.isFormValues)(call.values)) throw new ToolboxError("TOOL", "malformed form values; send values as a record of each field name to a string, a finite number, a boolean, or a list of strings", { values: call.values });
 			const result = options.manager.answer(options.to, call.id, call.values);
-			if (!result.success) throw new ToolboxError("ANSWER", `failed to answer form '${call.id}': ${result.error.reason}`, {
-				id: call.id,
-				reason: result.error.reason,
-				...result.error.reason === "rejected" ? { errors: result.error.errors } : {}
-			});
+			if (!result.success) {
+				const detail = result.error.reason === "rejected" ? `; correct these fields and answer again: ${(0, _orkestrel_contract.renderList)(result.error.errors.map((fault) => `${(0, _orkestrel_contract.preview)(fault.field)}: ${(0, _orkestrel_contract.preview)(fault.message)}`))}` : "; call { \"operation\": \"pending\" } for the ids you can answer";
+				throw new ToolboxError("ANSWER", `failed to answer form ${(0, _orkestrel_contract.preview)(call.id)}: ${result.error.reason}${detail}`, {
+					id: call.id,
+					reason: result.error.reason,
+					...result.error.reason === "rejected" ? { errors: result.error.errors } : {}
+				});
+			}
 			return { answered: call.id };
 		}
 	});
@@ -2848,9 +3201,11 @@ function createDatabaseDefinitionStore(driver = (0, _orkestrel_database.createMe
 * {@link createWorkspaceTool}'s single-tool-many-operations shape).
 *
 * @remarks
-* The universal tool-handler contract: validates the call args against
-* {@link import('./shapers.js').databaseToolShape}, dispatches to the matching operation, and
-* returns a plain result on success. A database is resolved lazily and cached for the tool's
+* The universal tool-handler contract: the Tool door holds the call args to
+* {@link import('./shapers.js').databaseToolShape}, refusing malformed args with a `ToolError`
+* carrying code `ARGUMENTS`. The handler dispatches to the matching operation and
+* returns a plain result on success. A row a `'get'` misses is an explicit `null`. A `limit` that is
+* not a positive safe integer throws `TOOL` at construction. A database is resolved lazily and cached for the tool's
 * lifetime — `'create'` mints one from `tables` ({@link import('./compilers.js').expandTables}) and
 * a registered `driver` key ({@link import('./types.js').DatabaseToolOptions.drivers}, default
 * `{ memory: () => createMemoryDriver() }`); any other operation addressing an uncached id falls
@@ -2908,30 +3263,28 @@ function createDatabaseDefinitionStore(driver = (0, _orkestrel_database.createMe
 function createDatabaseTool(options = {}) {
 	if (options.timeout !== void 0 && (options.timeout < 0 || !(0, _orkestrel_contract.isNumber)(options.timeout) || !Number.isSafeInteger(options.timeout))) throw new ToolboxError("TOOL", "database timeout must be a nonnegative safe integer", { timeout: options.timeout });
 	const contract = (0, _orkestrel_contract.createContract)(databaseToolShape);
-	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
 	const handles = new Map(Object.entries(options.databases ?? {}));
 	const drivers = options.drivers ?? { memory: _orkestrel_database.createMemoryDriver };
 	const generator = options.generator;
-	const cap = options.limit ?? 1e3;
+	const cap = resolveBound(options.limit, DATABASE_TOOL_LIMIT, "database limit");
 	const store = options.store;
 	const resolver = store === void 0 ? new DatabaseResolver(handles, drivers, generator) : new DatabaseResolver(handles, drivers, generator, store);
 	return (0, _orkestrel_tool.createTool)({
 		name: options.name ?? "database",
 		description: options.description ?? DATABASE_TOOL_DESCRIPTION,
 		summary: DATABASE_TOOL_SUMMARY,
-		...parameters === void 0 ? {} : { parameters },
+		contract: databaseToolShape,
 		async execute(args) {
-			const call = contract.parse(args);
-			if (call === void 0) throw new ToolboxError("TOOL", "malformed database call", { args });
-			if (options.readonly === true && DATABASE_TOOL_MUTATIONS.includes(call.operation)) throw new ToolboxError("TOOL", `operation '${call.operation}' is disabled in readonly mode`, { operation: call.operation });
+			const call = requireToolCall(contract, args);
+			if (options.readonly === true && DATABASE_TOOL_MUTATIONS.includes(call.operation)) throw new ToolboxError("TOOL", `operation '${call.operation}' is disabled in readonly mode; call tables, get, records, count, or aggregate`, { operation: call.operation });
 			const read = options.timeout === void 0 ? void 0 : { signal: AbortSignal.timeout(options.timeout) };
 			try {
 				switch (call.operation) {
 					case "create": {
-						if (resolver.has(call.id) || store !== void 0 && await store.get(call.id) !== void 0) throw new ToolboxError("TOOL", `database '${call.id}' already exists`, { id: call.id });
+						if (resolver.has(call.id) || store !== void 0 && await store.get(call.id) !== void 0) throw new ToolboxError("TOOL", `database ${(0, _orkestrel_contract.preview)(call.id)} already exists; use it, destroy it first, or send another id`, { id: call.id });
 						const name = call.driver ?? "memory";
 						const factory = drivers[name];
-						if (factory === void 0) throw new ToolboxError("TOOL", `unknown driver '${name}'`, {
+						if (factory === void 0) throw new ToolboxError("TOOL", `unknown driver ${(0, _orkestrel_contract.preview)(name)}; send driver as one of ${renderCandidates(Object.keys(drivers))}`, {
 							id: call.id,
 							driver: name
 						});
@@ -2978,7 +3331,7 @@ function createDatabaseTool(options = {}) {
 						const table = (await resolver.resolve(call.id)).table(call.table);
 						const many = (0, _orkestrel_contract.isArray)(call.key);
 						const keys = (0, _orkestrel_contract.isArray)(call.key) ? call.key : [call.key];
-						const rows = await table.get(keys);
+						const rows = (await table.get(keys)).map((row) => row ?? null);
 						return many ? { rows } : { row: rows[0] };
 					}
 					case "records": {
@@ -3043,7 +3396,7 @@ function createDatabaseTool(options = {}) {
 				if (isToolboxError(error)) throw error;
 				const code = inferDatabaseCode(error);
 				if (code === void 0) throw error;
-				throw new ToolboxError("DATABASE", (0, _orkestrel_contract.isError)(error) ? error.message : String(error), {
+				throw new ToolboxError("DATABASE", limitRefusal((0, _orkestrel_contract.isError)(error) ? error.message : String(error)), {
 					code,
 					operation: call.operation,
 					id: call.id,
@@ -3059,8 +3412,10 @@ function createDatabaseTool(options = {}) {
 * single-tool-many-operations shape).
 *
 * @remarks
-* The universal tool-handler contract: validates the call args against
-* {@link import('./shapers.js').relationToolShape}, resolves the addressed
+* The universal tool-handler contract: the Tool door holds the call args to
+* {@link import('./shapers.js').relationToolShape}, refusing malformed args with a `ToolError`
+* carrying code `ARGUMENTS`. A `limit` or `depth` that is not a positive safe integer throws `TOOL` at
+* construction, and a row `'load'` misses is an explicit `null`. The handler resolves the addressed
 * {@link import('@orkestrel/relation').RelationManagerInterface} — an explicit `manager` field
 * must match a key of {@link import('./types.js').RelationToolOptions.managers}, an omitted one
 * resolves to the sole registered manager, either miss throwing a typed `TOOL`
@@ -3106,24 +3461,22 @@ function createDatabaseTool(options = {}) {
 */
 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;
+	const depth = resolveBound(options.depth, 3, "relation depth");
+	const cap = resolveBound(options.limit, RELATION_TOOL_LIMIT, "relation limit");
 	return (0, _orkestrel_tool.createTool)({
 		name: options.name ?? "relation",
 		description: options.description ?? RELATION_TOOL_DESCRIPTION,
 		summary: RELATION_TOOL_SUMMARY,
-		...parameters === void 0 ? {} : { parameters },
+		contract: relationToolShape,
 		async execute(args) {
-			const call = contract.parse(args);
-			if (call === void 0) throw new ToolboxError("TOOL", "malformed relation call", { args });
+			const call = requireToolCall(contract, args);
 			try {
 				const model = resolveRelationModel(resolveRelationManager(options.managers, call.manager), call.model);
 				switch (call.operation) {
 					case "load": {
 						const include = expandInclude(call.include, depth);
-						if ((0, _orkestrel_contract.isString)(call.key) || (0, _orkestrel_contract.isNumber)(call.key)) return { row: await model.load(call.key, include) };
-						return { rows: await model.load(call.key, include) };
+						if ((0, _orkestrel_contract.isString)(call.key) || (0, _orkestrel_contract.isNumber)(call.key)) return { row: await model.load(call.key, include) ?? null };
+						return { rows: (await model.load(call.key, include)).map((row) => row ?? null) };
 					}
 					case "find": {
 						const include = expandInclude(call.include, depth);
@@ -3165,7 +3518,7 @@ function createRelationTool(options) {
 			} catch (error) {
 				if (isToolboxError(error)) throw error;
 				const relation = inferRelationCode(error);
-				if (relation !== void 0) throw new ToolboxError("RELATION", (0, _orkestrel_contract.isError)(error) ? error.message : String(error), {
+				if (relation !== void 0) throw new ToolboxError("RELATION", limitRefusal((0, _orkestrel_contract.isError)(error) ? error.message : String(error)), {
 					code: relation,
 					operation: call.operation,
 					model: call.model,
@@ -3173,7 +3526,7 @@ function createRelationTool(options) {
 				});
 				const database = inferDatabaseCode(error);
 				if (database === void 0) throw error;
-				throw new ToolboxError("DATABASE", (0, _orkestrel_contract.isError)(error) ? error.message : String(error), {
+				throw new ToolboxError("DATABASE", limitRefusal((0, _orkestrel_contract.isError)(error) ? error.message : String(error)), {
 					code: database,
 					operation: call.operation
 				});
@@ -3187,14 +3540,13 @@ function createRelationTool(options) {
 * {@link createEndpointTool}, wraps one concrete endpoint).
 *
 * @remarks
-* The universal tool-handler contract: validates the call args against
+* The universal tool-handler contract: the Tool door holds the call args to
 * {@link import('./shapers.js').inferToolShape} (`samples` non-empty, `format` / `enum` optional
-* booleans, `candidates` an optional array), infers a schema through `@orkestrel/contract`'s
+* booleans, `candidates` an optional array), refusing malformed args with a `ToolError` carrying code
+* `ARGUMENTS`. The handler infers a schema through `@orkestrel/contract`'s
 * `samplesToSchema`, wraps a non-object root as `{ value: <schema> }` through `schemaToObject` (mirrors
 * the tool-parameters convention every other `create*Tool` factory advertises), and returns the
-* resulting parameters record. An empty `samples` array fails `inferToolShape`'s `min: 1` bound —
-* `contract.parse` returns `undefined` and the handler throws a typed `TOOL`
-* {@link import('./errors.js').ToolboxError}.
+* resulting parameters record.
 *
 * When `candidates` is absent, the return is the bare parameters record — unchanged from before
 * this array existed. When `candidates` is present (any array, including empty), the handler
@@ -3209,18 +3561,14 @@ function createRelationTool(options) {
 * normalizing parse accept this value", that is would {@link createEndpointTool}'s default enforcement
 * admit it (`checker.parse(candidate) !== undefined`) — computed for every candidate regardless of
 * `valid`; by the house parse/guard round-trip, a `valid: true` entry is
-* always also `coercible: true`. `@orkestrel/contract`'s `explain` mirrors the normalizing
-* `parse`'s leniency, not `is`'s strictness — so a strictly-invalid but coercible candidate (`7`
-* against a string slot) yields `{ valid: false, coercible: true, faults: [] }`: empty faults, because
-* the mismatch the normalizing parse would silently fix is not one `explain` reports. `faults`
-* therefore only ever populates for a non-coercible mismatch — a wrong type the parse can't coerce
-* (a boolean in a string slot), a missing required key, or an out-of-enum value — where
-* `coercible: false`. `checker.is` / `.parse` / `.explain` are all total over JSON-safe input — a
-* JSON-safe hostile candidate (a `__proto__`-carrying object, deeply nested data) reaches each of them
+* always also `coercible: true`. `faults` is `checker.audit(candidate)`, which reports against `is`'s
+* strictness: a strictly-invalid but coercible candidate (`7` against a string slot) yields
+* `{ valid: false, coercible: true, faults: [{ reason: 'type', ... }] }`, so every invalid candidate
+* names why, an undeclared key included. `checker.is` / `.parse` / `.audit` are all total over
+* JSON-safe input — a JSON-safe hostile candidate (a `__proto__`-carrying object, deeply nested data) reaches each of them
 * and yields a bounded, non-throwing per-candidate verdict; a non-JSON-safe candidate (for example a
-* throwing-getter `Proxy`) never reaches the checker at all — it fails the outer `args` parse
-* against {@link import('./shapers.js').inferToolShape} and rejects the whole call with the same
-* `TOOL` {@link import('./errors.js').ToolboxError} a malformed `samples`/`format`/`enum` throws,
+* throwing-getter `Proxy`) never reaches the checker at all — the Tool door refuses the whole call
+* with the same `ToolError` a malformed `samples`/`format`/`enum` throws,
 * with no per-candidate verdict produced.
 *
 * @param options - Advertised `name` / `description` overrides (see
@@ -3260,21 +3608,19 @@ function createRelationTool(options) {
 */
 function createInferTool(options) {
 	const contract = (0, _orkestrel_contract.createContract)(inferToolShape);
-	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
 	return (0, _orkestrel_tool.createTool)({
 		name: options?.name ?? "infer",
 		description: options?.description ?? INFER_TOOL_DESCRIPTION,
 		summary: INFER_TOOL_SUMMARY,
-		...parameters === void 0 ? {} : { parameters },
+		contract: inferToolShape,
 		async execute(args) {
-			const parsed = contract.parse(args);
-			if (parsed === void 0) throw new ToolboxError("TOOL", "malformed infer arguments", { args });
+			const parsed = requireToolCall(contract, args);
 			const schema = (0, _orkestrel_contract.samplesToSchema)(parsed.samples, {
 				format: parsed.format ?? false,
 				enum: parsed.enum ?? false
 			});
 			const result = (0, _orkestrel_contract.schemaToParameters)((0, _orkestrel_contract.schemaToObject)(schema));
-			if (result === void 0) throw new ToolboxError("TOOL", "could not infer a schema", { args });
+			if (result === void 0) throw new ToolboxError("TOOL", "could not infer a schema; send samples that are JSON values of one shape", { args });
 			if (parsed.candidates === void 0) return result;
 			const checker = (0, _orkestrel_contract.createContract)((0, _orkestrel_contract.schemaToShape)(schema));
 			return {
@@ -3290,7 +3636,7 @@ function createInferTool(options) {
 						index,
 						valid,
 						coercible,
-						faults: checker.explain(candidate)
+						faults: checker.audit(candidate)
 					};
 				})
 			};
@@ -3307,20 +3653,19 @@ function createInferTool(options) {
 * `@orkestrel/contract`'s `samplesToSchema` (tuned by {@link import('./types.js').EndpointToolOptions}'s
 * `format` / `enum`), wrapping a non-object root as `{ value: <schema> }` through `schemaToObject` —
 * the same object-rooted schema is both the advertised `parameters` and, by default
-* ({@link import('./types.js').EndpointToolOptions.validate} `true`), the enforced contract:
-* `@orkestrel/contract`'s `schemaToShape` compiles it once (through `createContract`) into a
-* `ContractInterface` whose `.parse` runs on every call's `args` before `definition.execute` — a
+* ({@link import('./types.js').EndpointToolOptions.strict} `true`), the enforced contract: the Tool
+* door converts it through `@orkestrel/contract`'s lenient `schemaToShape` and compiles it on the
+* first call, then runs on every call's `args` before `definition.execute` — a
 * normalizing parse, not a strict type check: a scalar is coerced to its inferred type where the
 * house parsers coerce (a number to/from a numeric string, a boolean from `'1'`/`'0'`/`'true'`/
 * `'false'`/`1`/`0`), so `definition.execute` receives the coerced value (for example `7` sent for a
-* string slot arrives as `'7'`), not the raw call value. A call whose `args` fails to parse into
-* a record — a required key missing, or a value not coercible to its slot's type — throws a
-* typed `TOOL` {@link import('./errors.js').ToolboxError} carrying the compiled contract's
-* structured `explain` faults, and `definition.execute` is never called. `format` annotations are
-* never asserted, and a key outside the closed inferred schema is silently dropped rather than
-* rejected (see {@link import('./types.js').EndpointToolOptions.validate}). With
-* `validate: false`, the tool's `execute` passes through the model-supplied `args` to
-* `definition.execute` without re-validation — the raw-passthrough opt-out. The execution context
+* string slot arrives as `'7'`), not the raw call value. A call whose `args` carries a key outside
+* the closed inferred schema, misses a required key, or holds a value not coercible to its slot's
+* type throws a `ToolError` with code `ARGUMENTS` (`@orkestrel/tool`) carrying `context.faults`, and
+* `definition.execute` is never called. `format` annotations are never asserted (see
+* {@link import('./types.js').EndpointToolOptions.strict}). With
+* `strict: false`, the tool's `execute` passes through the model-supplied `args` to
+* `definition.execute` without validation — the raw-passthrough opt-out. The execution context
 * the tool's `execute` receives reaches `definition.execute` unchanged whichever way `args` are
 * handled, so a handler that reads `context.signal` observes the caller's cancellation. Either way,
 * the definition's return flows back as the tool call's plain result; a throw propagates uncaught,
@@ -3329,7 +3674,7 @@ function createInferTool(options) {
 *
 * @param definition - The endpoint's identity, non-empty samples, and local handler (see
 *   {@link import('./types.js').EndpointDefinition})
-* @param options - Construction-time inference tuning and the validate opt-out (see
+* @param options - Construction-time inference tuning and the strict opt-out (see
 *   {@link import('./types.js').EndpointToolOptions})
 * @returns A `ToolInterface` named `definition.name`
 *
@@ -3362,7 +3707,7 @@ function createInferTool(options) {
 * 	name: 'lookupUser',
 * 	arguments: { id: true, name: 'Ada' },
 * })
-* // rejected.error -> the TOOL ToolboxError message
+* // rejected.error -> the ARGUMENTS ToolError message, which names `id`
 * ```
 */
 function createEndpointTool(definition, options) {
@@ -3372,26 +3717,13 @@ function createEndpointTool(definition, options) {
 		enum: options?.enum ?? false
 	}));
 	const parameters = (0, _orkestrel_contract.schemaToParameters)(objectSchema);
-	if (!(options?.validate ?? true)) return (0, _orkestrel_tool.createTool)({
-		name: definition.name,
-		description: definition.description,
-		...parameters === void 0 ? {} : { parameters },
-		execute(args, context) {
-			return definition.execute(args, context);
-		}
-	});
-	const contract = (0, _orkestrel_contract.createContract)((0, _orkestrel_contract.schemaToShape)(objectSchema));
 	return (0, _orkestrel_tool.createTool)({
 		name: definition.name,
 		description: definition.description,
 		...parameters === void 0 ? {} : { parameters },
+		...options?.strict === void 0 ? {} : { strict: options.strict },
 		execute(args, context) {
-			const parsed = contract.parse(args);
-			if (parsed === void 0 || !(0, _orkestrel_contract.isRecord)(parsed)) throw new ToolboxError("TOOL", "malformed endpoint call arguments", {
-				name: definition.name,
-				faults: contract.explain(args)
-			});
-			return definition.execute(parsed, context);
+			return definition.execute(args, context);
 		}
 	});
 }
@@ -3437,6 +3769,7 @@ exports.WORKSPACE_TOOL_NAME = WORKSPACE_TOOL_NAME;
 exports.WORKSPACE_TOOL_SUMMARY = WORKSPACE_TOOL_SUMMARY;
 exports.agentToolShape = agentToolShape;
 exports.answerToolShape = answerToolShape;
+exports.buildArgumentRefusal = buildArgumentRefusal;
 exports.clampQuery = clampQuery;
 exports.columnPrimitiveShape = columnPrimitiveShape;
 exports.columnSpecShape = columnSpecShape;
@@ -3463,13 +3796,18 @@ exports.createWorkflowFunctions = createWorkflowFunctions;
 exports.createWorkflowTool = createWorkflowTool;
 exports.createWorkspaceTool = createWorkspaceTool;
 exports.databaseToolShape = databaseToolShape;
+exports.definitionContract = definitionContract;
+exports.definitionShape = definitionShape;
 exports.deriveWorkflowDepth = deriveWorkflowDepth;
+exports.describeDefinitionMismatch = describeDefinitionMismatch;
+exports.describeDefinitionRefusal = describeDefinitionRefusal;
 exports.describeToolShape = describeToolShape;
 exports.expandInclude = expandInclude;
 exports.expandSteps = expandSteps;
 exports.expandTables = expandTables;
 exports.extendLineage = extendLineage;
 exports.includeShape = includeShape;
+exports.indexesShape = indexesShape;
 exports.inferDatabaseCode = inferDatabaseCode;
 exports.inferRelationCode = inferRelationCode;
 exports.inferTerminalCode = inferTerminalCode;
@@ -3478,17 +3816,26 @@ exports.isAgentFunction = isAgentFunction;
 exports.isColumnPrimitive = isColumnPrimitive;
 exports.isColumnSpec = isColumnSpec;
 exports.isDatabaseDefinition = isDatabaseDefinition;
+exports.isIndexMap = isIndexMap;
+exports.isPrimaryMap = isPrimaryMap;
+exports.isTableSpec = isTableSpec;
 exports.isToolboxError = isToolboxError;
 exports.isWorkflowLineage = isWorkflowLineage;
 exports.keyShape = keyShape;
+exports.limitRefusal = limitRefusal;
 exports.managerShape = managerShape;
 exports.normalizeLineage = normalizeLineage;
 exports.normalizeQuery = normalizeQuery;
 exports.orderShape = orderShape;
 exports.phaseDraftShape = phaseDraftShape;
+exports.primaryShape = primaryShape;
 exports.promptToolShape = promptToolShape;
 exports.queryShape = queryShape;
 exports.relationToolShape = relationToolShape;
+exports.renderCandidates = renderCandidates;
+exports.requireActiveWorkspace = requireActiveWorkspace;
+exports.requireToolCall = requireToolCall;
+exports.resolveBound = resolveBound;
 exports.resolveLimit = resolveLimit;
 exports.resolveRelationManager = resolveRelationManager;
 exports.resolveRelationModel = resolveRelationModel;