@orkestrel/toolbox 0.0.1 → 0.0.2

package/dist/src/core/index.js

@@ -1,10 +1,11 @@
-import { arrayShape, booleanShape, createContract, integerShape, isNonEmptyString, isRecord, isString, jsonShape, literalShape, numberShape, objectShape, optionalShape, rawShape, recordShape, samplesToSchema, schemaToObject, schemaToParameters, schemaToShape, stringShape, unionShape } from "@orkestrel/contract";
+import { arrayShape, attempt, booleanShape, cloneJSONRecord, createContract, integerShape, isFiniteNumber, isNonEmptyString, isRecord, isString, jsonShape, literalShape, numberShape, objectShape, optionalShape, parseJSONValue, rawShape, recordShape, samplesToSchema, schemaToObject, schemaToParameters, schemaToShape, stringShape, unionShape } from "@orkestrel/contract";
+import { MAX_TIMER_MS, createWorkflowContract } from "@orkestrel/workflow";
 import { isTerminalError } from "@orkestrel/terminal";
-import { createDatabase, createMemoryDriver, generateUUID, isDatabaseError, shapeToColumnType } from "@orkestrel/database";
+import { createDatabase, createMemoryDriver, isDatabaseError } from "@orkestrel/database";
 import { isRelationError } from "@orkestrel/relation";
-import { WorkspaceError, createWorkspaceManager, isText, rangeOf } from "@orkestrel/agent";
+import { agentResultToJSON } from "@orkestrel/agent";
+import { createWorkspaceManager, isText, rangeOf } from "@orkestrel/workspace";
 import { createTool } from "@orkestrel/tool";
-import { WorkflowError, createWorkflowContract } from "@orkestrel/workflow";
 //#region src/core/constants.ts
 /**
 * The name {@link import('./factories.js').createAgentTool} advertises by default — the key a
@@ -25,15 +26,6 @@ var AGENT_TOOL_NAME = "agent";
 */
 var AGENT_TOOL_DEPTH = 8;
 /**
-* The DESCRIPTION {@link import('./factories.js').createAgentTool} advertises — a short guide
-* that teaches a model how to delegate a task to a sub-agent.
-*
-* @remarks
-* Mirrors {@link WORKFLOW_TOOL_DESCRIPTION} / `WORKSPACE_TOOL_DESCRIPTION`'s teaching style: names
-* the required `task` field, and documents the optional per-call `provider` / `tools` /
-* `system` overrides.
-*/
-/**
 * The lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createAgentTool}
 * advertises in place of {@link AGENT_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
 * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
@@ -41,6 +33,10 @@ var AGENT_TOOL_DEPTH = 8;
 * {@link import('./factories.js').createDescribeTool}.
 */
 var AGENT_TOOL_SUMMARY = "Delegate a task to a sub-agent and return its result; each call runs one sub-agent turn to completion. Call describe('agent') for the optional provider/tools/system overrides.";
+/**
+* The description {@link import('./factories.js').createAgentTool} advertises — a short guide
+* covering the required task and optional provider, tools, and system overrides.
+*/
 var AGENT_TOOL_DESCRIPTION = [
 	"Delegate a task to a sub-agent and return its result. Every call runs ONE sub-agent turn to completion.",
 	"",
@@ -59,11 +55,9 @@ var AGENT_TOOL_DESCRIPTION = [
 * {@link import('./factories.js').createWorkflowTool}'s depth/cycle guards enforce.
 *
 * @remarks
-* OWNED here now (ported from `@orkestrel/workflow`, whose engine no longer uses it — only the
-* tool-authoring guards this package now owns consume it). The limit lives in ONE place: an
-* agent-function-wrapped agent running at this depth can no longer author + run a NESTED
-* workflow through its bound workflow tool (that would be depth `MAX_WORKFLOW_DEPTH + 1`), so
-* the over-deep invocation is REJECTED (a typed `DEPTH` `WorkflowError` throw, `@orkestrel/workflow`).
+* Depth is zero-based and counts workflow tags after the root: the root plus eight nested
+* workflows is allowed, while a ninth nested workflow is rejected with this package's typed
+* `DEPTH` `ToolboxError`.
 */
 var MAX_WORKFLOW_DEPTH = 8;
 /**
@@ -73,7 +67,7 @@ var MAX_WORKFLOW_DEPTH = 8;
 * under onto a wrapped agent's `context.tools`.
 *
 * @remarks
-* OWNED here now (ported from `@orkestrel/workflow`). The propagation seam's well-known key: when
+* The propagation seam's well-known key: when
 * `createAgentFunction`'s `runner` option is supplied, it adds a `createWorkflowTool`-built tool
 * under this name to the agent's `context.tools`, so it can author + run a NESTED workflow
 * (bounded by {@link MAX_WORKFLOW_DEPTH}).
@@ -84,7 +78,7 @@ var WORKFLOW_TOOL_NAME = "workflow";
 * {@link import('./factories.js').createWorkflowTool}: `{ name, steps: [{ name }] }`.
 *
 * @remarks
-* OWNED here now (ported from `@orkestrel/workflow`). Each step becomes a one-task phase, in
+* Each step becomes a one-task phase, in
 * order; a step's `name` is a REGISTERED behavior name (not a label) — the registry key its
 * task's `run` resolves against. The tool expands this
 * ({@link import('./helpers.js').expandSteps}) into a valid `WorkflowDefinition`
@@ -99,7 +93,7 @@ var WORKFLOW_TOOL_FLAT_EXAMPLE = Object.freeze({
 * the flat shape: a full `WorkflowDefinition` (`@orkestrel/workflow`).
 *
 * @remarks
-* OWNED here now (ported from `@orkestrel/workflow`). The full four-level form, documented in
+* The full four-level form, documented in
 * {@link WORKFLOW_TOOL_DESCRIPTION} as the advanced alternative. It is embedded VERBATIM.
 */
 var WORKFLOW_TOOL_NESTED_EXAMPLE = Object.freeze({
@@ -116,19 +110,6 @@ var WORKFLOW_TOOL_NESTED_EXAMPLE = Object.freeze({
 	})])
 });
 /**
-* The DESCRIPTION {@link import('./factories.js').createWorkflowTool} advertises — a multi-line
-* guide that teaches a small model how to author a complete workflow tree.
-*
-* @remarks
-* OWNED here now (ported from `@orkestrel/workflow`). Presents the SIMPLE flat shape
-* (`{ name, steps: [{ name }] }`) as the PRIMARY way with one complete worked example
-* ({@link WORKFLOW_TOOL_FLAT_EXAMPLE}), names that a step's `name` is a REGISTERED name (not a
-* human label), and documents the full nested `WorkflowDefinition` as the ADVANCED form with a
-* minimal example ({@link WORKFLOW_TOOL_NESTED_EXAMPLE}). The `parameters` the tool advertises
-* are the FLAT shape's schema; the nested form is the documented escape-hatch (the tool accepts
-* both).
-*/
-/**
 * The lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createWorkflowTool}
 * advertises in place of {@link WORKFLOW_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
 * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
@@ -136,26 +117,28 @@ var WORKFLOW_TOOL_NESTED_EXAMPLE = Object.freeze({
 * {@link import('./factories.js').createDescribeTool}.
 */
 var WORKFLOW_TOOL_SUMMARY = "Author and run a multi-phase workflow in one call — phases run in sequence, tasks within a phase run concurrently. Call describe('workflow') for the full authoring schema and examples.";
+/**
+* The description {@link import('./factories.js').createWorkflowTool} advertises — the flat
+* authoring form, its worked example, and the advanced nested definition form.
+*/
 var WORKFLOW_TOOL_DESCRIPTION = [
 	"Author and run a workflow (phases run sequentially, the tasks within a phase run concurrently) in one call.",
 	"",
 	"SIMPLEST way — a flat list of steps. Each step runs one registered behavior; steps run one after another:",
 	"  { \"name\": \"<workflow name>\", \"steps\": [ { \"name\": \"<registered name>\" }, ... ] }",
 	"- a step's \"name\" is a REGISTERED behavior name (a registry key), NOT a human label.",
-	"- the top-level \"name\" (the workflow name) is optional. Ids are filled in for you.",
+	"- every step name must exist in the host-supplied functions registry; an unknown name is rejected.",
+	"- the top-level \"name\" is optional; when present it is also the workflow persistence id. Other ids are filled in for you.",
 	"Example:",
 	JSON.stringify(WORKFLOW_TOOL_FLAT_EXAMPLE),
 	"",
-	"ADVANCED — the full nested form, for multi-task phases or explicit ids. A workflow has phases; a phase has tasks; a task has a \"run\" (a registered behavior name):",
+	"ADVANCED — the full nested form, for multi-task phases or explicit ids. A workflow has phases; a phase has tasks; a task may have a \"run\" (a registered behavior name); omitting it creates a JSON-null no-op:",
 	JSON.stringify(WORKFLOW_TOOL_NESTED_EXAMPLE),
 	"In the nested form you may omit any \"id\"/\"name\" and they are filled in positionally; a provided one is kept."
 ].join("\n");
 /**
 * The name {@link import('./factories.js').createWorkspaceTool} advertises by default — the key a
 * model calls and the `ToolManagerInterface` (`@orkestrel/tool`) registers under.
-*
-* @remarks
-* OWNED here now (ported from `@orkestrel/agent`).
 */
 var WORKSPACE_TOOL_NAME = "workspace";
 /**
@@ -163,7 +146,7 @@ var WORKSPACE_TOOL_NAME = "workspace";
 * VERBATIM in {@link WORKSPACE_TOOL_DESCRIPTION}.
 *
 * @remarks
-* OWNED here now (ported from `@orkestrel/agent`). A `'write'` op (the most common authoring
+* A `'write'` op (the most common authoring
 * action): create or overwrite `notes.txt` with `hello`. Frozen so it cannot be mutated in
 * place.
 */
@@ -173,17 +156,6 @@ var WORKSPACE_TOOL_EXAMPLE = Object.freeze({
 	content: "hello"
 });
 /**
-* The DESCRIPTION {@link import('./factories.js').createWorkspaceTool} advertises — a multi-line
-* guide that teaches a small model how to drive a workspace through the single
-* `operation`-keyed tool.
-*
-* @remarks
-* OWNED here now (ported from `@orkestrel/agent`). Mirrors {@link WORKFLOW_TOOL_DESCRIPTION}'s
-* teaching style: names the `operation` discriminant field, enumerates all 13 operations with
-* their FLAT fields, gives a worked example for the common ones, and embeds
-* {@link WORKSPACE_TOOL_EXAMPLE} verbatim.
-*/
-/**
 * The lean {@link import('@orkestrel/tool').ToolInterface.summary} {@link import('./factories.js').createWorkspaceTool}
 * advertises in place of {@link WORKSPACE_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
 * (`@orkestrel/tool`) advertises `summary ?? description`, so this one-sentence text stands in
@@ -191,6 +163,14 @@ var WORKSPACE_TOOL_EXAMPLE = Object.freeze({
 * {@link import('./factories.js').createDescribeTool}.
 */
 var WORKSPACE_TOOL_SUMMARY = "Read and edit files in a workspace — one operation per call (read, write, list, search, replace, splice, move, remove, plus workspace switching), chosen by the 'operation' field. Call describe('workspace') for the full operation list and fields.";
+/**
+* The description {@link import('./factories.js').createWorkspaceTool} advertises — the
+* operation-keyed workspace protocol, all supported operations, and worked examples.
+*
+* @remarks
+* Mirrors {@link WORKFLOW_TOOL_DESCRIPTION}'s teaching style and embeds
+* {@link WORKSPACE_TOOL_EXAMPLE} verbatim.
+*/
 var WORKSPACE_TOOL_DESCRIPTION = [
 	"Read and edit files in a workspace. Every call is ONE operation, chosen by the \"operation\" field.",
 	"All file operations act on the ACTIVE workspace; use \"workspaces\" then \"switch\" to move between workspaces.",
@@ -199,8 +179,8 @@ var WORKSPACE_TOOL_DESCRIPTION = [
 	"- read     { \"operation\": \"read\", \"path\": \"<file>\" } — return the file's 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, \"exact\"?: bool, \"limit\"?: int } — find lines matching the query across all files.",
-	"- replace  { \"operation\": \"replace\", \"query\": \"<text>\", \"replacement\": \"<text>\", \"regex\"?: bool, \"exact\"?: bool, \"limit\"?: int } — replace matches across all files.",
+	"- search   { \"operation\": \"search\", \"query\": \"<text>\", \"regex\"?: bool, \"sensitive\"?: bool, \"limit\"?: int } — find lines matching the query across all files.",
+	"- replace  { \"operation\": \"replace\", \"query\": \"<text>\", \"replacement\": \"<text>\", \"regex\"?: bool, \"sensitive\"?: bool, \"limit\"?: int } — replace matches across all files.",
 	"- write    { \"operation\": \"write\", \"path\": \"<file>\", \"content\": \"<text>\" } — create or overwrite the whole file.",
 	"- splice   { \"operation\": \"splice\", \"path\": \"<file>\", \"content\": \"<text>\", \"fromLine\": int, \"fromColumn\": int, \"toLine\": int, \"toColumn\": int } — replace a 1-based range (from inclusive, to exclusive) with content.",
 	"- prepend  { \"operation\": \"prepend\", \"path\": \"<file>\", \"content\": \"<text>\" } — add content to the start of the file.",
@@ -210,7 +190,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), \"exact\" 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. Editing with no active workspace auto-creates one.",
 	"",
 	"Example — write a file:",
 	JSON.stringify(WORKSPACE_TOOL_EXAMPLE)
@@ -253,6 +233,7 @@ var PROMPT_TOOL_NAME = "ask";
 * {@link import('./factories.js').createDescribeTool}.
 */
 var PROMPT_TOOL_SUMMARY = "Ask another terminal a question and BLOCK until it answers; the call resolves with the answered value. Call describe('ask') for the required fields.";
+/** The full prompt protocol {@link import('./factories.js').createPromptTool} advertises. */
 var PROMPT_TOOL_DESCRIPTION = [
 	"Ask another terminal a question and block until it answers. This call does not return until the addressed terminal answers, or the prompt fails.",
 	"",
@@ -283,6 +264,7 @@ var ANSWER_TOOL_NAME = "answer";
 * {@link import('./factories.js').createDescribeTool}.
 */
 var ANSWER_TOOL_SUMMARY = "List prompts addressed to this terminal, or answer one by id. Call describe('answer') for the required fields.";
+/** The pending/answer protocol {@link import('./factories.js').createAnswerTool} advertises. */
 var ANSWER_TOOL_DESCRIPTION = [
 	"List the prompts currently addressed to this terminal, or answer one of them by id. Every call is ONE operation, chosen by the \"operation\" field.",
 	"",
@@ -312,14 +294,14 @@ var DATABASE_TOOL_NAME = "database";
 * The lean {@link import('@orkestrel/tool').ToolInterface.summary} the upcoming database tool
 * will advertise in place of {@link DATABASE_TOOL_DESCRIPTION}.
 */
-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.";
+var DATABASE_TOOL_SUMMARY = "Create and query a database — one operation per call (create, tables, get, records, count, aggregate, add, set, update, remove, destroy), chosen by the 'operation' field. Call describe('database') for the full operation list, the query form, and the column DSL.";
 /**
 * 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}
+* small model the operation list, the SERIALIZED query 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
+* The query 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.
@@ -328,25 +310,25 @@ 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.",
+	"- create    { \"operation\": \"create\", \"id\": \"<database id>\", \"tables\": { \"<table>\": { \"columns\": { \"<column>\": \"string\" | \"integer\" | \"number\" | \"boolean\" | { \"type\": \"string\", \"optional\": true } } } }, \"primary\"?: { \"<table>\": \"<column>\" }, \"indexes\"?: { \"<table>\": [[\"<column>\"]] }, \"version\"?: <number> } — 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.",
+	"- records   { \"operation\": \"records\", \"id\": \"<database id>\", \"table\": \"<table>\", \"query\"?: <Query> } — list rows matching a query.",
+	"- count     { \"operation\": \"count\", \"id\": \"<database id>\", \"table\": \"<table>\", \"query\"?: <Query> } — count rows matching a query.",
+	"- aggregate { \"operation\": \"aggregate\", \"id\": \"<database id>\", \"table\": \"<table>\", \"column\": \"<column>\", \"function\": \"count\" | \"sum\" | \"average\" | \"minimum\" | \"maximum\", \"query\"?: <Query> } — 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.",
+	"- update    { \"operation\": \"update\", \"id\": \"<database id>\", \"table\": \"<table>\", \"key\": \"<row key>\", \"changes\": { ... } } — 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:",
+	"Query 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.",
+	"Column DSL (used by \"create\" \"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.",
+	"Schema configuration is creation-time only. Evolve a schema by opening a newly configured target-version database over a versioned persistent driver; reconciliation requires paired metadata/stamp capabilities.",
 	"Example — create a database:",
 	JSON.stringify({
 		operation: "create",
@@ -360,28 +342,27 @@ var DATABASE_TOOL_DESCRIPTION = [
 			}
 		} } }
 	}),
-	"Example — query with criteria:",
+	"Example — query records:",
 	JSON.stringify({
 		operation: "records",
 		id: "shop",
 		table: "products",
-		criteria: { conditions: [{
+		query: { 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. */
+/** The default cap on rows a `records` call returns when the caller omits `query.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([
+/** The runtime-frozen database-tool mutation names disabled by `DatabaseToolOptions.readonly`. */
+var DATABASE_TOOL_MUTATIONS = Object.freeze([
 	"create",
 	"add",
 	"set",
 	"update",
 	"remove",
-	"migrate",
 	"destroy"
 ]);
 /**
@@ -438,6 +419,7 @@ var INFER_TOOL_NAME = "infer";
 * {@link import('./factories.js').createDescribeTool}.
 */
 var INFER_TOOL_SUMMARY = "Infer a JSON Schema (as advertised tool parameters) from one or more example values. Call describe('infer') for the required fields.";
+/** The schema-inference protocol {@link import('./factories.js').createInferTool} advertises. */
 var INFER_TOOL_DESCRIPTION = [
 	"Infer a JSON Schema from example values, returned in the same shape a tool advertises its parameters.",
 	"",
@@ -530,13 +512,9 @@ var INFER_TOOL_DESCRIPTION = [
 //#endregion
 //#region src/core/errors.ts
 /**
-* Thrown by {@link import('./factories.js').createAgentTool}'s and
-* {@link import('./factories.js').createDescribeTool}'s handlers on every failure path — a
-* malformed / unresolvable call or an unknown tool name (`TOOL`), a delegation that would
-* exceed the configured depth bound or re-enter an ancestor (`DEPTH`), a prompt cycle
-* (`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}.
+* A package-owned tool-call failure: malformed input or unresolved configuration (`TOOL`),
+* delegation depth/cycle rejection (`DEPTH`), prompt failure (`DEADLOCK` / `EXPIRE` / `ANSWER`),
+* or a translated upstream database/relation failure (`DATABASE` / `RELATION`).
 *
 * @remarks
 * Carries a machine-readable `code` (see {@link import('./types.js').ToolboxErrorCode}) and
@@ -734,7 +712,7 @@ var taskDraftShape = objectShape({
 	description: optionalShape(stringShape({ description: "Optional task description." })),
 	run: optionalShape(stringShape({
 		min: 1,
-		description: "The registered behavior name to invoke (a registry key, not a label); omitted has no handler."
+		description: "The registered behavior name to invoke (a registry key, not a label); omitted completes with JSON null."
 	})),
 	retries: optionalShape(integerShape({
 		min: 0,
@@ -742,7 +720,8 @@ var taskDraftShape = objectShape({
 	})),
 	timeout: optionalShape(integerShape({
 		min: 0,
-		description: "Per-attempt deadline in milliseconds; overrides the phase default. Omitted means no deadline."
+		max: MAX_TIMER_MS,
+		description: "Persisted per-attempt deadline in milliseconds (0 disables it); omitted means no deadline."
 	}))
 });
 /**
@@ -773,7 +752,8 @@ var phaseDraftShape = objectShape({
 *
 * @remarks
 * The lenient counterpart {@link import('./factories.js').createWorkflowDraftContract} compiles.
-* `run` stays required on the strict form; a provided `id` / `name` still has `minLength: 1` (so
+* `run` stays optional like the strict form; omission is the deliberate JSON `null` no-op. A
+* provided `id` / `name` still has `minLength: 1` (so
 * an explicitly-empty `id: ''` is REJECTED, not auto-filled). After
 * {@link import('./helpers.js').completeDraft} fills the missing ids/names, the result is
 * validated against the STRICT `createWorkflowContract` (`@orkestrel/workflow`) gate before
@@ -834,10 +814,10 @@ var workflowStepsShape = objectShape({
 * The union compiles to an `anyOf` JSON Schema + a `unionOf` guard + a first-match parser
 * automatically ({@link import('./factories.js').createWorkspaceTool} types the result to the
 * hand-written {@link import('./types.js').WorkspaceOperation}). `limit` and the four `'splice'`
-* caret components are POSITIVE integers (`integerShape({ min: 1 })`); `regex` / `exact` are
-* `optionalShape(booleanShape(...))`. The two REGISTRY arms — `workspaces` (list the workspaces
-* the model can move between) and `switch` (re-point the active one by `id`) — let a model
-* DISCOVER then CHOOSE which workspace the edit / read arms target.
+* caret components are POSITIVE integers (`integerShape({ min: 1 })`); `regex` / `sensitive`
+* are `optionalShape(booleanShape(...))`. The two REGISTRY arms — `workspaces` (list the
+* workspaces the model can move between) and `switch` (re-point the active one by `id`) — let a
+* model DISCOVER then CHOOSE which workspace the edit / read arms target.
 */
 var workspaceToolShape = unionShape(objectShape({
 	operation: literalShape(["read"], { description: "Read a whole text file's text by path." }),
@@ -849,7 +829,7 @@ var workspaceToolShape = unionShape(objectShape({
 	operation: literalShape(["search"], { description: "Search every text file for a query, returning each hit." }),
 	query: stringShape({ description: "The text (or regular-expression source) to search for." }),
 	regex: optionalShape(booleanShape({ description: "Treat the query as a regular expression. Defaults to false (a literal substring)." })),
-	exact: optionalShape(booleanShape({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
+	sensitive: optionalShape(booleanShape({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
 	limit: optionalShape(integerShape({
 		min: 1,
 		description: "Stop after this many matches across all files. Omitted means unlimited."
@@ -859,7 +839,7 @@ var workspaceToolShape = unionShape(objectShape({
 	query: stringShape({ description: "The text (or regular-expression source) to replace." }),
 	replacement: stringShape({ description: "The text to substitute for each match." }),
 	regex: optionalShape(booleanShape({ description: "Treat the query as a regular expression. Defaults to false (a literal substring)." })),
-	exact: optionalShape(booleanShape({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
+	sensitive: optionalShape(booleanShape({ description: "Match case-sensitively. Defaults to true (set false for case-insensitive)." })),
 	limit: optionalShape(integerShape({
 		min: 1,
 		description: "Stop after this many replacements across all files. Omitted means unlimited."
@@ -955,8 +935,8 @@ var orderShape = objectShape({
 	column: stringShape({ description: "The column to sort by." }),
 	direction: literalShape(["ascending", "descending"], { description: "The sort direction." })
 });
-/** The SERIALIZED criteria form — conditions, order, and pagination. */
-var criteriaShape = objectShape({
+/** The SERIALIZED query form — conditions, order, and pagination. */
+var queryShape = objectShape({
 	conditions: optionalShape(arrayShape(conditionShape, { description: "The WHERE conditions, folded left to right." })),
 	order: optionalShape(arrayShape(orderShape, { description: "The sort terms, applied in order." })),
 	limit: optionalShape(integerShape({
@@ -970,17 +950,17 @@ var criteriaShape = objectShape({
 });
 /**
 * The shape of {@link import('./factories.js').createDatabaseTool}'s call arguments —
-* discriminated by `operation` into the 12 database operations (`'create'` / `'tables'` /
+* discriminated by `operation` into the 11 database operations (`'create'` / `'tables'` /
 * `'get'` / `'records'` / `'count'` / `'aggregate'` / `'add'` / `'set'` / `'update'` /
-* `'remove'` / `'migrate'` / `'destroy'`).
+* `'remove'` / `'destroy'`).
 *
 * @remarks
-* Every arm carries `id` (the database id). `'create'` / `'migrate'` carry `tables` (the
+* Every arm carries `id` (the database id). `'create'` carries `tables` (the
 * {@link import('./types.js').TableSpec} column DSL, compiled via
 * {@link import('./helpers.js').expandTables}); `'get'` / `'update'` / `'remove'` carry `key`
 * (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,
+* `'aggregate'` carry an optional `query` (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 = unionShape(objectShape({
@@ -994,7 +974,12 @@ var databaseToolShape = unionShape(objectShape({
 		min: 1,
 		description: "The registered driver key. Defaults to \"memory\"."
 	})),
-	keys: optionalShape(recordShape(stringShape(), { description: "Table name to its primary-key column." }))
+	primary: optionalShape(recordShape(stringShape({ min: 1 }), { description: "Table name to its primary-key column." })),
+	indexes: optionalShape(recordShape(arrayShape(arrayShape(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." })),
+	version: optionalShape(numberShape({ description: "The schema version for open-time reconciliation." }))
 }), objectShape({
 	operation: literalShape(["tables"], { description: "List a database's table names." }),
 	id: stringShape({
@@ -1013,7 +998,7 @@ var databaseToolShape = unionShape(objectShape({
 	}),
 	key: keyShape
 }), objectShape({
-	operation: literalShape(["records"], { description: "List rows matching criteria." }),
+	operation: literalShape(["records"], { description: "List rows matching a query." }),
 	id: stringShape({
 		min: 1,
 		description: "The database id."
@@ -1022,9 +1007,9 @@ var databaseToolShape = unionShape(objectShape({
 		min: 1,
 		description: "The table name."
 	}),
-	criteria: optionalShape(criteriaShape)
+	query: optionalShape(queryShape)
 }), objectShape({
-	operation: literalShape(["count"], { description: "Count rows matching criteria." }),
+	operation: literalShape(["count"], { description: "Count rows matching a query." }),
 	id: stringShape({
 		min: 1,
 		description: "The database id."
@@ -1033,7 +1018,7 @@ var databaseToolShape = unionShape(objectShape({
 		min: 1,
 		description: "The table name."
 	}),
-	criteria: optionalShape(criteriaShape)
+	query: optionalShape(queryShape)
 }), objectShape({
 	operation: literalShape(["aggregate"], { description: "Compute an aggregate over a column." }),
 	id: stringShape({
@@ -1055,7 +1040,7 @@ var databaseToolShape = unionShape(objectShape({
 		min: 1,
 		description: "The column to aggregate."
 	}),
-	criteria: optionalShape(criteriaShape)
+	query: optionalShape(queryShape)
 }), objectShape({
 	operation: literalShape(["add"], { description: "Insert one or more rows (fails on a duplicate key)." }),
 	id: stringShape({
@@ -1101,13 +1086,6 @@ var databaseToolShape = unionShape(objectShape({
 		description: "The table name."
 	}),
 	key: keyShape
-}), objectShape({
-	operation: literalShape(["migrate"], { description: "Replace the table layout in place." }),
-	id: stringShape({
-		min: 1,
-		description: "The database id."
-	}),
-	tables: tableSpecShape
 }), objectShape({
 	operation: literalShape(["destroy"], { description: "Drop a database entirely." }),
 	id: stringShape({
@@ -1249,7 +1227,7 @@ function workflowTag(id) {
 * @remarks
 * The agent counterpart of {@link workflowTag}: {@link import('./factories.js').createAgentFunction}
 * / {@link import('./factories.js').createWorkflowTool} guard against re-entering an agent or
-* workflow already in the chain (a typed `DEPTH` `WorkflowError`, `@orkestrel/workflow`). The
+* workflow already in the chain (this package's typed `DEPTH` `ToolboxError`). The
 * `agent:` namespace keeps it distinct from a same-string workflow id.
 *
 * @param name - The agent's identifier / registry name
@@ -1259,23 +1237,89 @@ function agentTag(name) {
 	return `agent:${name}`;
 }
 /**
+* Narrow an unknown value to a valid alternating workflow lineage.
+*
+* @param value - The value to inspect
+* @returns Whether `value` is a unique, nonempty-tagged workflow/agent chain
+*/
+function isWorkflowLineage(value) {
+	const inspected = attempt(() => {
+		if (!Array.isArray(value)) return false;
+		const seen = /* @__PURE__ */ new Set();
+		for (const [index, tag] of value.entries()) {
+			if (!isString(tag)) return false;
+			const prefix = index % 2 === 0 ? "workflow:" : "agent:";
+			if (!tag.startsWith(prefix) || tag.length === prefix.length || seen.has(tag)) return false;
+			seen.add(tag);
+		}
+		return true;
+	});
+	return inspected.success && inspected.value;
+}
+/**
+* Build a validated, copied, and frozen workflow lineage value.
+*
+* @param lineage - The configured chain; omitted means a direct root
+* @returns An immutable caller-isolated lineage
+*/
+function lineageOf(lineage = []) {
+	if (!isWorkflowLineage(lineage)) throw new ToolboxError("TOOL", "workflow lineage must alternate unique workflow and agent tags");
+	return Object.freeze([...lineage]);
+}
+/**
+* Append one tag to a workflow lineage and return a frozen copy.
+*
+* @param lineage - The valid chain to extend
+* @param tag - The workflow or agent tag to append
+* @returns The validated immutable extension
+*/
+function extendLineage(lineage, tag) {
+	return lineageOf([...lineage, tag]);
+}
+/**
+* Derive the zero-based workflow nesting depth from a valid lineage.
+*
+* @param lineage - The workflow/agent chain
+* @returns Zero for an empty/root lineage, then one per nested workflow
+*/
+function deriveWorkflowDepth(lineage) {
+	const workflows = lineageOf(lineage).filter((tag) => tag.startsWith("workflow:")).length;
+	return Math.max(0, workflows - 1);
+}
+/**
+* Narrow an unknown callable to Toolbox's frozen contextual agent adapter metadata.
+*
+* @param value - The value to inspect
+* @returns Whether it is a frozen {@link AgentFunction} with a frozen valid lineage
+*/
+function isAgentFunction(value) {
+	const inspected = attempt(() => {
+		if (typeof value !== "function" || !Object.isFrozen(value)) return false;
+		const category = Reflect.getOwnPropertyDescriptor(value, "category");
+		const lineage = Reflect.getOwnPropertyDescriptor(value, "lineage");
+		return category?.value === "agent" && lineage !== void 0 && "value" in lineage && Object.isFrozen(lineage.value) && isWorkflowLineage(lineage.value);
+	});
+	return inspected.success && inspected.value;
+}
+/**
 * Build the plain success summary {@link import('./factories.js').createWorkflowTool} returns on
 * a completed run — the universal tool-handler contract (AGENTS §14): return a plain value on
 * success, appearing identically over BOTH the agent loop and MCP.
 *
 * @remarks
-* The summary is LEAN: the workflow's terminal `status` and the COUNT of settled task results —
-* enough for a caller / model to react without serializing the whole live tree. (It carries no
-* synthetic `id` / `name`: a tool handler has no call id; the `ToolManagerInterface`
-* (`@orkestrel/tool`) supplies the canonical envelope's identity.)
+* The summary is LEAN: the workflow's terminal `status`, settled-task count, and exact optional
+* native persistence outcome. It carries no synthetic `id` / `name`: a tool handler has no call
+* id; the `ToolManagerInterface` (`@orkestrel/tool`) supplies the canonical envelope's identity.
 *
 * @param result - The terminal `WorkflowResult` (`@orkestrel/workflow`) the run produced
-* @returns The plain success summary — `{ status, count }`
+* @returns The plain success summary — `{ status, count, durable?, fault? }`
 */
 function workflowToolSummary(result) {
 	return {
 		status: result.status,
-		count: result.results.length
+		count: result.results.length,
+		...result.durable === void 0 ? {} : { durable: result.durable },
+		...result.fault === void 0 ? {} : { fault: result.fault }
 	};
 }
 /**
@@ -1356,16 +1400,20 @@ function completeTaskDraft(task, phaseId, index) {
 * `name` becomes the task's `run` (the behavior-registry key). Ids/names are auto-filled
 * positionally — it builds an ids-omitted {@link WorkflowDraft} and delegates to
 * {@link completeDraft}, so the two lenient surfaces share ONE synthesis path (step `i` → phase
-* `phase-<i>`, its task `phase-<i>-task-0`). The optional `name` becomes the workflow's `name`.
-* The result is a complete definition the caller validates against the STRICT contract before
-* running.
+* `phase-<i>`, its task `phase-<i>-task-0`). The optional `name` becomes both the workflow's
+* deterministic id and its name, so named flat workflows retain distinct persistence keys;
+* omission keeps the shared draft fallback `wf`. The result is a complete definition the caller
+* validates against the STRICT contract before running.
 *
 * @param flat - The flat steps blob (`{ name?, steps: [{ name }] }`)
 * @returns A complete {@link WorkflowDefinition} (one one-task phase per step)
 */
 function expandSteps(flat) {
 	return completeDraft({
-		...flat.name === void 0 ? {} : { name: flat.name },
+		...flat.name === void 0 ? {} : {
+			id: flat.name,
+			name: flat.name
+		},
 		phases: flat.steps.map((step) => ({ tasks: [{ run: step.name }] }))
 	});
 }
@@ -1443,13 +1491,13 @@ function isColumnKind(value) {
 	return value === "string" || value === "integer" || value === "number" || value === "boolean";
 }
 /**
-* Compile a {@link TableSpec} into the `@orkestrel/database` {@link TablesShape} it configures —
+* Compile a {@link TableSpec} into the `@orkestrel/database` {@link TableMap} it configures —
 * each {@link ColumnSpec} maps to the matching primitive shaper (`'string'` → `stringShape()`,
 * `'integer'` → `integerShape()`, `'number'` → `numberShape()`, `'boolean'` → `booleanShape()`),
 * wrapped in `optionalShape` when the column declares `optional: true`. Total, pure.
 *
 * @param spec - The small-model-facing table layout
-* @returns The compiled `TablesShape` a `@orkestrel/database` `createDatabase` call accepts
+* @returns The compiled `TableMap` a `@orkestrel/database` `createDatabase` call accepts
 */
 function expandTables(spec) {
 	const tables = {};
@@ -1476,22 +1524,35 @@ function kindShape(kind) {
 }
 /**
 * 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`).
+* `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`).
 */
 function isDatabaseDefinition(value) {
 	if (!isRecord(value)) return false;
+	if ("keys" in value) return false;
 	if (!isNonEmptyString(value.id) || !isNonEmptyString(value.driver)) return false;
 	if (!isRecord(value.tables)) return false;
 	for (const table of Object.values(value.tables)) {
 		if (!isRecord(table) || !isRecord(table.columns)) return false;
 		for (const column of Object.values(table.columns)) if (!isColumnSpec(column)) return false;
 	}
-	if (value.keys !== void 0) {
-		if (!isRecord(value.keys)) return false;
-		for (const key of Object.values(value.keys)) if (!isString(key)) return false;
+	if (value.primary !== void 0) {
+		if (!isRecord(value.primary)) return false;
+		for (const key of Object.values(value.primary)) if (!isNonEmptyString(key)) return false;
 	}
+	if (value.indexes !== void 0) {
+		if (!isRecord(value.indexes)) return false;
+		for (const groups of Object.values(value.indexes)) {
+			if (!Array.isArray(groups)) return false;
+			for (const group of groups) {
+				if (!Array.isArray(group) || group.length === 0) return false;
+				for (const column of group) if (!isNonEmptyString(column)) return false;
+			}
+		}
+	}
+	if (value.version !== void 0 && !isFiniteNumber(value.version)) return false;
 	return true;
 }
 /**
@@ -1635,8 +1696,8 @@ function relationModelOf(manager, name) {
 	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'`.
+* Normalize the database tool's parsed SERIALIZED query into a live `@orkestrel/database`
+* {@link QueryInput} — default each condition's OMITTED `connector` to `'and'`.
 *
 * @remarks
 * The wire form ({@link import('./shapers.js').databaseToolShape}) lets a caller drop `connector`
@@ -1644,84 +1705,58 @@ function relationModelOf(manager, name) {
 * `@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`
+* @param query - The parsed query (or `undefined`)
+* @returns The equivalent live `QueryInput`, or `undefined` when `query` is `undefined`
 */
-function criteriaOf(criteria) {
-	if (criteria === void 0) return void 0;
-	const conditions = criteria.conditions?.map((condition) => ({
+function queryOf(query) {
+	if (query === void 0) return void 0;
+	const conditions = query.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 }
+		...query.order === void 0 ? {} : { order: query.order },
+		...query.limit === void 0 ? {} : { limit: query.limit },
+		...query.offset === void 0 ? {} : { offset: query.offset }
 	};
 }
 /**
-* Clamp a `'records'` call's criteria to a row cap, and build the PROBE criteria the caller reads
+* Clamp a `'records'` call's query to a row cap, and build the PROBE query the caller reads
 * with — the pure leaf {@link import('./factories.js').createDatabaseTool}'s `'records'` operation
 * uses to detect truncation without a separate `count` round trip.
 *
 * @remarks
-* The effective limit is `min(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
+* The effective limit is `min(query?.limit ?? cap, cap)`, floored at `0` (so a caller can never
+* exceed the configured cap by supplying a larger `query.limit`). The returned probe query
 * 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'
+* import { clampQuery } 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 { query, limit } = clampQuery(undefined, 100)
+* // limit === 100, query.limit === 101 — a probe fetching one extra row
+* const rows = await table.records(query)
 * const truncated = rows.length > limit // true when storage had more than `limit` rows
 * ```
 *
-* @param criteria - The live criteria to clamp (or `undefined`)
+* @param query - The live query to clamp (or `undefined`)
 * @param cap - The row-count ceiling
-* @returns The PROBE criteria (`limit` bumped by one) and the effective `limit`
+* @returns The PROBE query (`limit` bumped by one) and the effective `limit`
 */
-function clampCriteria(criteria, cap) {
-	const limit = Math.max(0, Math.min(criteria?.limit ?? cap, cap));
+function clampQuery(query, cap) {
+	const limit = Math.max(0, Math.min(query?.limit ?? cap, cap));
 	return {
-		criteria: {
-			...criteria,
+		query: {
+			...query,
 			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: 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
 /**
@@ -1732,7 +1767,8 @@ function tableSchema(name, table) {
 *
 * @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
+* self-contained CONFIG-only JSON, so no encoding is needed for the memory tier). Values are
+* structured-cloned on both write and read, keeping caller mutation outside the store. There is NO
 * idle-TTL and NO eviction: a persisted definition lives until an explicit `delete`. A durable
 * backend (JSON / SQLite / IndexedDB) swaps in through the SAME interface without touching a
 * consumer — its driver-pluggable twin is
@@ -1759,10 +1795,11 @@ function tableSchema(name, table) {
 var MemoryDefinitionStore = class {
 	#definitions = /* @__PURE__ */ new Map();
 	get(id) {
-		return Promise.resolve(this.#definitions.get(id));
+		const definition = this.#definitions.get(id);
+		return Promise.resolve(definition === void 0 ? void 0 : structuredClone(definition));
 	}
 	set(definition) {
-		this.#definitions.set(definition.id, definition);
+		this.#definitions.set(definition.id, structuredClone(definition));
 		return Promise.resolve();
 	}
 	delete(id) {
@@ -1851,27 +1888,27 @@ var DatabaseDefinitionStore = class {
 * ```ts
 * import { DatabaseResolver } from '@orkestrel/toolbox'
 *
-* const resolver = new DatabaseResolver(handles, drivers, key, store)
+* const resolver = new DatabaseResolver(handles, drivers, generator, store)
 * const database = await resolver.resolve('shop')
 * ```
 */
 var DatabaseResolver = class {
 	#handles;
 	#drivers;
-	#key;
+	#generator;
 	#store;
 	/**
 	* Create a database resolver over the tool's live state and optional definition store.
 	*
 	* @param handles - Initial live database handles cached by id
 	* @param drivers - Driver factories keyed by definition driver name
-	* @param key - Key generator supplied to newly created databases
+	* @param generator - Optional key generator supplied to newly created databases
 	* @param store - Optional persistent definition store
 	*/
-	constructor(handles, drivers, key, store) {
+	constructor(handles, drivers, generator, store) {
 		this.#handles = new Map(handles);
 		this.#drivers = drivers;
-		this.#key = key;
+		this.#generator = generator;
 		this.#store = store;
 	}
 	/**
@@ -1931,8 +1968,11 @@ var DatabaseResolver = class {
 				const handle = createDatabase({
 					driver: factory(),
 					tables: expandTables(definition.tables),
-					...definition.keys === void 0 ? {} : { keys: definition.keys },
-					key: this.#key
+					name: id,
+					...definition.primary === void 0 ? {} : { primary: definition.primary },
+					...definition.indexes === void 0 ? {} : { indexes: definition.indexes },
+					...definition.version === void 0 ? {} : { version: definition.version },
+					...this.#generator === void 0 ? {} : { generator: this.#generator }
 				});
 				this.set(id, handle);
 				return handle;
@@ -1948,17 +1988,13 @@ var DatabaseResolver = class {
 * adapter that lets a `function`-form task run a `@orkestrel/tool` tool BY NAME.
 *
 * @remarks
-* OWNED here now (ported from `@orkestrel/workflow`). Composes into a caller's
-* `WorkflowOptions.functions` registry like any other behavior
+* Composes into a caller's `WorkflowOptions.functions` registry like any other behavior
 * (`{ publish: createToolFunction(tools, 'publish') }`); the pure workflow runner has no
 * knowledge of tools itself. The returned function executes `name` against `tools` with the
-* task's `controller.input` as the call arguments, id-correlated to the task's own id. A
-* `ToolManagerInterface.execute` (`@orkestrel/tool`) NEVER throws (a handler throw is isolated
-* into `result.error`), so a failing tool is surfaced here as a THROWN `Error` carrying the
-* original message as `cause` — the leaf `fail`s, honouring `bail`. An UNREGISTERED tool name is
-* a programmer error (an explicit binding to a name that doesn't exist) — unlike the engine's
-* own silent auto-complete of an unresolved task handler, this THROWS a typed `TOOL`
-* `WorkflowError` (`@orkestrel/workflow`).
+* task's `controller.input` as the call arguments. The adapter resolves the live tool, calls its
+* `execute` method directly, and deep-gates the returned unknown through `parseJSONValue`.
+* Genuine execution throws retain identity. An unregistered name or non-JSON return throws this
+* package's typed `TOOL` `ToolboxError`.
 *
 * @param tools - The `ToolManagerInterface` (`@orkestrel/tool`) the named tool is registered on
 * @param name - The registered tool's name
@@ -1977,47 +2013,40 @@ var DatabaseResolver = class {
 * ```
 */
 function createToolFunction(tools, name) {
+	if (name === "workflow") throw new ToolboxError("TOOL", `tool '${WORKFLOW_TOOL_NAME}' is reserved for live workflows`, { tool: name });
 	return async (controller) => {
-		if (tools.tool(name) === void 0) throw new WorkflowError("TOOL", `tool '${name}' is not registered`, { tool: name });
-		const result = await tools.execute({
-			id: controller.task.id,
-			name,
-			arguments: controller.input
-		});
-		if (result.error !== void 0) throw new Error(result.error, { cause: result.error });
-		return result.value;
+		const tool = tools.tool(name);
+		if (tool === void 0) throw new ToolboxError("TOOL", `tool '${name}' is not registered`, { tool: name });
+		const result = parseJSONValue(await tool.execute(controller.input));
+		if (result === void 0) throw new ToolboxError("TOOL", `tool '${name}' returned a non-JSON value`, { tool: name });
+		return result;
 	};
 }
 /**
 * Wrap a live `AgentInterface` (`@orkestrel/agent`) as a {@link WorkflowFunction}
-* (`@orkestrel/workflow`) — the OPT-IN adapter that runs the agent to a settled result, folding
-* a nested workflow-authoring depth / cycle guard into its own closure.
+* (`@orkestrel/workflow`) — the opt-in adapter that runs the agent to a settled result and carries
+* immutable lineage metadata for contextual Toolbox composition.
 *
 * @remarks
-* OWNED here now (ported from `@orkestrel/workflow`). Composes into a caller's
-* `WorkflowOptions.functions` registry like any other behavior; the pure workflow runner has no
-* knowledge of agents itself. Before running the agent, the depth/cycle guard REJECTS the call
-* (a THROWN typed `DEPTH` `WorkflowError`, which the leaf `fail`s) when running it would push a
-* nested chain past {@link import('./constants.js').MAX_WORKFLOW_DEPTH}, OR when this agent is
-* already an ancestor (a cycle). When {@link import('./types.js').AgentFunctionOptions.runner}
-* is supplied, the adapter BINDS a depth/cycle-aware {@link createWorkflowTool} onto the agent's
-* `context.tools` (the propagation seam) — closed over `depth` and the extended ancestry (the
-* tool itself computes `depth + 1` internally) — so the agent can author + run a NESTED workflow
-* through it; the wrapped default is the CURRENT task's own workflow id (used only on a no-args
-* tool call). The task's cancellation folds into the agent run: an already-aborted
-* `controller.signal` cancels the agent up front; otherwise a one-shot listener fires
-* `agent.abort(reason)` when the task cancels, removed in `finally`. `agent.generate()` resolves
-* a partial `AgentResult` on a cancel (never rejects), returned as the task's completed value.
-*
-* A bound agent is effectively SINGLE-RUN: `context.tools.add` binds one `ToolInterface` under
-* the fixed {@link import('./constants.js').WORKFLOW_TOOL_NAME}, and `agent.generate()` /
-* `agent.abort()` are per-agent state. Two CONCURRENT tasks sharing the SAME `agent` instance
-* race on that one tool binding (last-write-wins) and on generate/abort — give each concurrent
-* task its OWN agent instance.
+* Composes into a caller's registry like any other behavior; the pure workflow runner has no
+* knowledge of agents itself. A root adapter derives its workflow lineage from the controller,
+* while a contextual adapter requires an exact match. Repeated agents, repeated workflows, and
+* targets deeper than {@link import('./constants.js').MAX_WORKFLOW_DEPTH} are rejected before
+* 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
+* 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.
+*
+* A bound agent is single-run. A concurrent branch sharing the same real agent is rejected before
+* its fixed {@link import('./constants.js').WORKFLOW_TOOL_NAME} binding can be replaced. Toolbox
+* cannot serialize opaque external wrappers that hide or bypass the raw agent registry; hosts
+* must give such concurrent work distinct agents.
 *
 * @param agent - The live `AgentInterface` to run
-* @param options - The nested-workflow binding + depth/cycle bookkeeping (see {@link import('./types.js').AgentFunctionOptions})
-* @returns A {@link WorkflowFunction} that runs `agent` to its settled result
+* @param options - The nested-workflow composition and lineage options
+* @returns A frozen {@link AgentFunction} that runs `agent` to its settled result
 *
 * @example
 * ```ts
@@ -2030,21 +2059,32 @@ function createToolFunction(tools, name) {
 * ```
 */
 function createAgentFunction(agent, options) {
-	return async (controller) => {
-		const depth = options?.depth ?? 0;
-		const ancestry = options?.ancestry ?? [];
-		if (depth + 1 > 8) throw new WorkflowError("DEPTH", `agent '${agent.id}' exceeds max workflow depth`, {
+	const lineage = lineageOf(options?.lineage);
+	if (lineage.length > 0 && !lineage.at(-1)?.startsWith("workflow:")) throw new ToolboxError("TOOL", "agent function lineage must end with a workflow tag");
+	const functions = options?.functions === void 0 ? void 0 : Object.freeze({ ...options.functions });
+	const agents = options?.agents === void 0 ? void 0 : Object.freeze({ ...options.agents });
+	return Object.freeze(Object.assign(async (controller) => {
+		const workflow = workflowTag(controller.task.phase.workflow.id);
+		const current = lineage.length === 0 ? extendLineage(lineage, workflow) : lineage;
+		if (current.at(-1) !== workflow) throw new ToolboxError("DEPTH", "agent function workflow does not match its lineage", {
+			workflow,
+			lineage: [...current]
+		});
+		const depth = deriveWorkflowDepth(current);
+		if (depth > 8) throw new ToolboxError("DEPTH", `agent '${agent.id}' exceeds max workflow depth`, {
 			agent: agent.id,
 			depth,
 			max: 8
 		});
 		const tag = agentTag(agent.id);
-		if (ancestry.includes(tag)) throw new WorkflowError("DEPTH", `agent '${agent.id}' is already an ancestor (cycle)`, {
+		if (current.includes(tag)) throw new ToolboxError("DEPTH", `agent '${agent.id}' is already an ancestor (cycle)`, {
 			agent: agent.id,
-			ancestry: [...ancestry]
+			lineage: [...current]
 		});
+		const nested = extendLineage(current, tag);
 		const runner = options?.runner;
 		if (runner !== void 0) {
+			if (agent.status === "running") throw new ToolboxError("TOOL", `agent '${agent.id}' is already running`, { agent: agent.id });
 			const workflowId = controller.task.phase.workflow.id;
 			const wrapped = {
 				id: workflowId,
@@ -2052,50 +2092,77 @@ function createAgentFunction(agent, options) {
 				phases: []
 			};
 			agent.context.tools.add(createWorkflowTool(wrapped, runner, {
-				depth,
-				ancestry: [...ancestry, tag]
+				lineage: nested,
+				...functions === void 0 ? {} : { functions },
+				...agents === void 0 ? {} : { agents },
+				...options?.store === void 0 ? {} : { store: options.store }
 			}));
 		}
-		const signal = controller.signal;
-		const onAbort = { handleEvent() {
-			agent.abort(signal.reason);
-		} };
-		if (signal.aborted) agent.abort(signal.reason);
-		else signal.addEventListener("abort", onAbort, { once: true });
-		try {
-			return await agent.generate();
-		} finally {
-			signal.removeEventListener("abort", onAbort);
-		}
-	};
+		const generated = agent.generate({ signal: controller.signal });
+		const result = agentResultToJSON(await generated);
+		if (result === void 0) throw new ToolboxError("TOOL", `agent '${agent.id}' returned a non-JSON result`, { agent: agent.id });
+		return result;
+	}, {
+		category: "agent",
+		lineage
+	}));
 }
 /**
-* Compile the LENIENT workflow DRAFT contract — identical to `createWorkflowContract`
-* (`@orkestrel/workflow`) EXCEPT `id` and `name` are OPTIONAL at all three levels (workflow /
-* phase / task), so a small model can omit the six identity strings.
+* Compose opaque host functions and raw agents into one immutable workflow registry.
 *
 * @remarks
-* The widened authoring surface {@link createWorkflowTool} parses an authored blob through
-* before {@link import('./helpers.js').completeDraft} fills the missing ids/names. It does NOT
-* relax the canonical contract — `createWorkflowContract` (`@orkestrel/workflow`) stays
-* byte-for-byte unchanged and STRICT, and the completed draft is re-validated against THAT
-* strict gate before running (soundness preserved). A PROVIDED `id` / `name` still carries
-* `minLength: 1`, so an explicitly-empty `id: ''` is REJECTED (parses to `undefined`), never
-* auto-filled — keeping "garbage" distinct from "omitted". `run` stays optional (a plain name
-* string).
+* This is the target-aware composition boundary used by direct runner consumers and
+* {@link createWorkflowTool}. Opaque leaves are copied unchanged, marked agent adapters are
+* rejected from that channel, raw agents are rebound to the supplied lineage, collisions fail
+* closed, and the returned null-prototype record prevents inherited names from becoming phantom
+* Workflow handlers.
 *
-* @returns The compiled {@link import('./types.js').WorkflowDraft} contract
+* @param runner - The native runner propagated into contextual agent adapters
+* @param options - Target lineage, opaque functions, raw agents, and native store
+* @returns A frozen null-prototype snapshot of the target workflow's callable registry
 *
 * @example
 * ```ts
-* import { createWorkflowDraftContract, completeDraft } from '@src/core'
+* import { createWorkflowFunctions } from '@src/core'
+* import { createWorkflowRunner } from '@orkestrel/workflow'
 *
-* const draft = createWorkflowDraftContract()
-* const parsed = draft.parse({ phases: [{ tasks: [{ run: 'compile' }] }] })
-* const definition = parsed && completeDraft(parsed) // ids/names filled positionally
-* draft.parse({ id: '', phases: [] }) // undefined — an explicit empty id is rejected
+* const runner = createWorkflowRunner()
+* const functions = createWorkflowFunctions(runner, {
+* 	functions: { publish: async () => 'published' },
+* 	agents: { review: reviewAgent },
+* })
+* await runner.execute(definition, { functions })
 * ```
 */
+function createWorkflowFunctions(runner, options) {
+	const lineage = lineageOf(options?.lineage);
+	if (lineage.length > 0 && !lineage.at(-1)?.startsWith("workflow:")) throw new ToolboxError("TOOL", "workflow functions lineage must end with a workflow tag");
+	const functions = options?.functions === void 0 ? Object.freeze({}) : Object.freeze({ ...options.functions });
+	const agents = options?.agents === void 0 ? Object.freeze({}) : Object.freeze({ ...options.agents });
+	const composed = {};
+	Object.setPrototypeOf(composed, null);
+	for (const [name, fn] of Object.entries(functions)) {
+		if (typeof fn !== "function") throw new ToolboxError("TOOL", `workflow function '${name}' is not callable`, { function: name });
+		if (isAgentFunction(fn)) throw new ToolboxError("TOOL", `agent function '${name}' must be supplied through agents`, { function: name });
+		composed[name] = fn;
+	}
+	for (const [name, agent] of Object.entries(agents)) {
+		if (Object.hasOwn(composed, name)) throw new ToolboxError("TOOL", `workflow function '${name}' collides with an agent`, { function: name });
+		composed[name] = createAgentFunction(agent, {
+			runner,
+			lineage,
+			functions,
+			agents,
+			...options?.store === void 0 ? {} : { store: options.store }
+		});
+	}
+	return Object.freeze(composed);
+}
+/**
+* Compile the lenient workflow draft contract used by {@link createWorkflowTool}.
+*
+* @returns The compiled {@link import('./types.js').WorkflowDraft} contract
+*/
 function createWorkflowDraftContract() {
 	return createContract(workflowDraftShape);
 }
@@ -2103,19 +2170,16 @@ function createWorkflowDraftContract() {
 * Wrap a {@link WorkflowDefinition} as an LLM-callable tool — it ADVERTISES the SIMPLE flat
 * authoring shape (`{ name?, steps: [{ name }] }`) as its `parameters` so even a small model can
 * author a complete tree, and its handler EXPANDS / COMPLETES the authored blob, validates it
-* against the STRICT contract, runs it through `runner`, and, when
-* {@link import('./types.js').WorkflowToolOptions.store} is supplied, PERSISTS each executed
-* workflow's final snapshot after the run settles.
+* against the STRICT contract, and runs it through `runner`, forwarding the caller's optional
+* named functions and native checkpoint store.
 *
 * @remarks
 * A plain `ToolManagerInterface`-compatible tool (`@orkestrel/tool`), reproducing
-* `@orkestrel/workflow`'s former call contract exactly (flat / draft / full authoring forms, the
-* strict soundness gate, the depth/cycle guard). It is ALSO the propagation carrier
+* Toolbox's flat / draft / full authoring contract, strict soundness gate, and lineage guard.
+* 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` (no ambient context, no signal), the run's
-* depth + ancestry are CLOSED OVER at bind time via {@link import('./types.js').WorkflowToolOptions},
-* and the handler enforces the SAME depth / cycle guard itself before running the nested
-* workflow at `depth + 1` with the extended ancestry.
+* 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.
 *
 * **Widened authoring surface (additive — the canonical contract + runner stay STRICT and
 * unchanged).** A 2B model reliably CALLS the tool but cannot reliably emit the full four-level
@@ -2130,17 +2194,17 @@ function createWorkflowDraftContract() {
 *   super-set.
 *
 * The universal tool-handler contract (AGENTS §14): returns the plain run summary
-* (`{ status, count }`) on success, THROWS a typed `WorkflowError` (`@orkestrel/workflow`) on
-* every failure path — malformed authored args (`TOOL`), or an over-deep / cyclic nested run
-* (`DEPTH`). The `ToolManagerInterface` isolates every throw into the canonical tool result's
-* top-level `error`, so nothing escapes the run. `options.depth` / `options.ancestry` are the
-* propagation carrier across a workflow → agent → workflow chain; `options.store` is this
-* package's ADDITION — the persisted snapshot is retrievable via the store afterwards (a caller
-* restores it through `@orkestrel/workflow`'s own `Workflow.restore` / store-backed factories).
+* (`{ 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
+* 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
+* makes the final snapshot retrievable without a second Toolbox write.
 *
 * @param definition - The workflow the tool runs when called with no authored args
 * @param runner - The `WorkflowRunnerInterface` (`@orkestrel/workflow`) that executes the (nested) workflow
-* @param options - Depth/ancestry bookkeeping plus the optional durable store (see {@link import('./types.js').WorkflowToolOptions})
+* @param options - Lineage-aware functions, agents, and optional native store
 * @returns A `ToolInterface` (named {@link import('./constants.js').WORKFLOW_TOOL_NAME}) whose
 *   `parameters` advertise the flat authoring schema
 *
@@ -2154,15 +2218,17 @@ function createWorkflowDraftContract() {
 * const store = createMemoryWorkflowStore()
 * const tool = createWorkflowTool(definition, runner, { store })
 * const tools = createToolManager()
-* tools.add(tool) // authored runs are now persisted to `store` on settle
+* tools.add(tool) // authored runs now use native checkpoints through `store`
 * ```
 */
 function createWorkflowTool(definition, runner, options) {
 	const strict = createWorkflowContract();
 	const draft = createWorkflowDraftContract();
 	const steps = createContract(workflowStepsShape);
-	const depth = options?.depth ?? 0;
-	const ancestry = options?.ancestry ?? [];
+	const lineage = lineageOf(options?.lineage);
+	if (lineage.length > 0 && !lineage.at(-1)?.startsWith("agent:")) throw new ToolboxError("TOOL", "workflow tool lineage must end with an agent tag");
+	const functions = options?.functions === void 0 ? void 0 : Object.freeze({ ...options.functions });
+	const agents = options?.agents === void 0 ? void 0 : Object.freeze({ ...options.agents });
 	const store = options?.store;
 	const parameters = schemaToParameters(steps.schema);
 	return createTool({
@@ -2171,29 +2237,41 @@ function createWorkflowTool(definition, runner, options) {
 		summary: WORKFLOW_TOOL_SUMMARY,
 		...parameters === void 0 ? {} : { parameters },
 		async execute(args) {
+			const cloned = attempt(() => cloneJSONRecord(args));
+			if (!cloned.success) throw new ToolboxError("TOOL", "malformed workflow definition", { workflow: definition.id });
+			const owned = cloned.value;
 			let target;
-			if (Object.keys(args).length === 0) target = definition;
-			else if (Array.isArray(args.steps)) {
-				const flat = steps.parse(args);
+			if (Object.keys(owned).length === 0) target = definition;
+			else if (Array.isArray(owned.steps)) {
+				const flat = steps.parse(owned);
 				target = flat === void 0 ? void 0 : expandSteps(flat);
 			} else {
-				const parsed = draft.parse(args);
+				const parsed = draft.parse(owned);
 				target = parsed === void 0 ? void 0 : completeDraft(parsed);
 			}
-			if (target === void 0 || !strict.is(target)) throw new WorkflowError("TOOL", "malformed workflow definition", { workflow: definition.id });
-			if (depth + 1 > 8) throw new WorkflowError("DEPTH", `nested workflow exceeds max depth 8`, {
+			if (target === void 0 || !strict.is(target)) throw new ToolboxError("TOOL", "malformed workflow definition", { workflow: definition.id });
+			const tag = workflowTag(target.id);
+			if (lineage.includes(tag)) throw new ToolboxError("DEPTH", `workflow '${target.id}' is already an ancestor (cycle)`, {
+				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`, {
 				workflow: target.id,
 				depth,
 				max: 8
 			});
-			const tag = workflowTag(target.id);
-			if (ancestry.includes(tag)) throw new WorkflowError("DEPTH", `workflow '${target.id}' is already an ancestor (cycle)`, {
-				workflow: target.id,
-				ancestry: [...ancestry]
+			const registry = functions === void 0 && agents === void 0 ? void 0 : createWorkflowFunctions(runner, {
+				lineage: targetLineage,
+				...functions === void 0 ? {} : { functions },
+				...agents === void 0 ? {} : { agents },
+				...store === void 0 ? {} : { store }
 			});
-			const result = await runner.execute(target);
-			if (store !== void 0) await store.set(result.workflow.snapshot());
-			return workflowToolSummary(result);
+			return workflowToolSummary(await runner.execute(target, {
+				...registry === void 0 ? {} : { functions: registry },
+				...store === void 0 ? {} : { store }
+			}));
 		}
 	});
 }
@@ -2202,12 +2280,13 @@ function createWorkflowTool(definition, runner, options) {
 * 13-op union ({@link import('./shapers.js').workspaceToolShape}) as its `parameters`, and its
 * handler PARSES the model-supplied args against that contract and DISPATCHES the matched
 * operation against the manager's ACTIVE workspace (the registry ops drive the manager itself),
-* returning the plain result (throwing a typed `WorkspaceError`, `@orkestrel/agent`, on
-* failure). EITHER drives a caller-supplied {@link WorkspaceToolOptions.manager} directly, OR
-* constructs a fresh `WorkspaceManagerInterface` (`@orkestrel/agent`) over
-* {@link import('./types.js').WorkspaceToolOptions.store} (via `@orkestrel/agent`'s
-* `createWorkspaceManager`); neither given constructs a manager backed by `@orkestrel/agent`'s
-* in-memory store default.
+* returning the plain result. A malformed operation throws this package's `ToolboxError`; a
+* genuine workspace-domain failure propagates `@orkestrel/workspace`'s typed `WorkspaceError`.
+* EITHER drives a caller-supplied {@link WorkspaceToolOptions.manager} directly, OR
+* constructs a fresh `WorkspaceManagerInterface` (`@orkestrel/workspace`) over
+* {@link import('./types.js').WorkspaceToolOptions.store} (via `@orkestrel/workspace`'s
+* `createWorkspaceManager`); neither given constructs a manager backed by
+* `@orkestrel/workspace`'s in-memory store default.
 *
 * @remarks
 * MANAGER-DRIVEN: every edit / read op (read / list / has / search / replace / write / splice /
@@ -2225,12 +2304,12 @@ function createWorkflowTool(definition, runner, options) {
 * `false`), never creating one and never throwing.
 *
 * The handler conforms to the universal tool-handler contract (AGENTS §14): it `contract.parse`s
-* the args, THROWS a `TOOL` `WorkspaceError` when no operation arm matched (a malformed / unknown
+* the args, THROWS a `TOOL` `ToolboxError` when no operation arm matched (a malformed / unknown
 * operation), else `switch`es on `op.operation` and RETURNS the plain result — letting a
 * `WorkspaceError` raised by the live workspace (`MODALITY` / `PATTERN` / `RANGE`) PROPAGATE
 * uncaught. The range edit is the FLAT `'splice'` op: its four flat caret integers are
-* reassembled into a `Range` (`@orkestrel/agent`) by `rangeOf` and fed to the workspace's ranged
-* `write`.
+* reassembled into a `Range` (`@orkestrel/workspace`) by `rangeOf` and fed to the workspace's
+* ranged `write`.
 *
 * @param options - `manager` (drive directly) OR `store` (build a manager over it); neither ⇒
 *   an in-memory-backed manager (see {@link import('./types.js').WorkspaceToolOptions})
@@ -2257,7 +2336,7 @@ function createWorkspaceTool(options) {
 		...parameters === void 0 ? {} : { parameters },
 		execute(args) {
 			const op = contract.parse(args);
-			if (op === void 0) throw new WorkspaceError("TOOL", `unknown or malformed operation`, { args });
+			if (op === void 0) throw new ToolboxError("TOOL", "unknown or malformed operation", { args });
 			if (op.operation === "workspaces") {
 				const activeId = manager.active?.id;
 				return manager.workspaces().map((workspace) => ({
@@ -2290,12 +2369,12 @@ function createWorkspaceTool(options) {
 				case "has": return active?.has(op.path) ?? false;
 				case "search": return active?.search(op.query, {
 					...op.regex === void 0 ? {} : { regex: op.regex },
-					...op.exact === void 0 ? {} : { exact: op.exact },
+					...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, {
 					...op.regex === void 0 ? {} : { regex: op.regex },
-					...op.exact === void 0 ? {} : { exact: op.exact },
+					...op.sensitive === void 0 ? {} : { sensitive: op.sensitive },
 					...op.limit === void 0 ? {} : { limit: op.limit }
 				});
 				case "write": {
@@ -2712,20 +2791,18 @@ function createDatabaseDefinitionStore(driver = createMemoryDriver()) {
 * `TOOL` {@link import('./errors.js').ToolboxError}). 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
+* `'records'` clamps its `query` 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'`).
+* {@link import('./helpers.js').clampQuery}, reporting `truncated` when storage held more rows
+* than the cap. Every operation's `query` is normalized via
+* {@link import('./helpers.js').queryOf} (defaults an omitted condition `connector` to `'and'`).
 * When {@link import('./types.js').DatabaseToolOptions.readonly} is `true`, every mutating
-* operation throws a typed `TOOL` `ToolboxError` 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`
+* operation throws a typed `TOOL` `ToolboxError` before doing anything. A configured
+* {@link import('./types.js').DatabaseToolOptions.timeout} is passed as a fresh
+* `AbortSignal.timeout(timeout)` only to table operations whose current database API accepts
+* operation options (`records`, `count`, `aggregate`, `add`, `set`, `update`, and `remove`). It is
+* not an outer deadline for resolution, construction, schema inspection, `get`, or `close`. A typed `@orkestrel/database`
 * failure (`DatabaseError`) re-surfaces as a typed `DATABASE` `ToolboxError` carrying the
 * original {@link import('@orkestrel/database').DatabaseErrorCode} in `context.code`
 * ({@link import('./helpers.js').databaseToolCode}); an `ToolboxError` thrown by this tool's own
@@ -2759,15 +2836,15 @@ function createDatabaseDefinitionStore(driver = createMemoryDriver()) {
 * ```
 */
 function createDatabaseTool(options = {}) {
+	if (options.timeout !== void 0 && (options.timeout < 0 || !Number.isSafeInteger(options.timeout))) throw new ToolboxError("TOOL", "database timeout must be a nonnegative safe integer", { timeout: options.timeout });
 	const contract = createContract(databaseToolShape);
 	const parameters = schemaToParameters(contract.schema);
 	const handles = new Map(Object.entries(options.databases ?? {}));
-	const definitions = /* @__PURE__ */ new Map();
 	const drivers = options.drivers ?? { memory: createMemoryDriver };
-	const key = options.key ?? generateUUID;
+	const generator = options.generator;
 	const cap = options.limit ?? 1e3;
 	const store = options.store;
-	const resolver = store === void 0 ? new DatabaseResolver(handles, drivers, key) : new DatabaseResolver(handles, drivers, key, store);
+	const resolver = store === void 0 ? new DatabaseResolver(handles, drivers, generator) : new DatabaseResolver(handles, drivers, generator, store);
 	return createTool({
 		name: options.name ?? "database",
 		description: options.description ?? DATABASE_TOOL_DESCRIPTION,
@@ -2776,7 +2853,7 @@ function createDatabaseTool(options = {}) {
 		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.has(call.operation)) throw new ToolboxError("TOOL", `operation '${call.operation}' is disabled in readonly mode`, { operation: call.operation });
+			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 read = options.timeout === void 0 ? void 0 : { signal: AbortSignal.timeout(options.timeout) };
 			try {
 				switch (call.operation) {
@@ -2789,22 +2866,28 @@ function createDatabaseTool(options = {}) {
 							driver: name
 						});
 						const tables = call.tables;
-						const keys = call.keys;
+						const primary = call.primary;
+						const indexes = call.indexes;
+						const version = call.version;
 						const handle = createDatabase({
 							driver: factory(),
 							tables: expandTables(tables),
-							...keys === void 0 ? {} : { keys },
-							key
+							name: call.id,
+							...primary === void 0 ? {} : { primary },
+							...indexes === void 0 ? {} : { indexes },
+							...version === void 0 ? {} : { version },
+							...generator === void 0 ? {} : { generator }
 						});
-						resolver.set(call.id, handle);
 						const definition = {
 							id: call.id,
 							driver: name,
 							tables,
-							...keys === void 0 ? {} : { keys }
+							...primary === void 0 ? {} : { primary },
+							...indexes === void 0 ? {} : { indexes },
+							...version === void 0 ? {} : { version }
 						};
-						definitions.set(call.id, definition);
 						if (store !== void 0) await store.set(definition);
+						resolver.set(call.id, handle);
 						return {
 							id: call.id,
 							tables: Object.keys(tables)
@@ -2830,7 +2913,7 @@ function createDatabaseTool(options = {}) {
 					}
 					case "records": {
 						const table = (await resolver.resolve(call.id)).table(call.table);
-						const { criteria: probe, limit } = clampCriteria(criteriaOf(call.criteria), cap);
+						const { query: probe, limit } = clampQuery(queryOf(call.query), cap);
 						const rows = await table.records(probe, read);
 						const truncated = rows.length > limit;
 						const sliced = rows.slice(0, limit);
@@ -2841,8 +2924,8 @@ function createDatabaseTool(options = {}) {
 							limit
 						};
 					}
-					case "count": return { count: await (await resolver.resolve(call.id)).table(call.table).count(criteriaOf(call.criteria), read) };
-					case "aggregate": return { value: await (await resolver.resolve(call.id)).table(call.table).aggregate(call.function, call.column, criteriaOf(call.criteria), read) };
+					case "count": return { count: await (await resolver.resolve(call.id)).table(call.table).count(queryOf(call.query), read) };
+					case "aggregate": return { value: await (await resolver.resolve(call.id)).table(call.table).aggregate(call.function, call.column, queryOf(call.query), read) };
 					case "add": {
 						const table = (await resolver.resolve(call.id)).table(call.table);
 						const many = Array.isArray(call.row);
@@ -2872,33 +2955,6 @@ function createDatabaseTool(options = {}) {
 						const removed = await table.remove(keys, read);
 						return many ? { removed } : { removed: removed[0] };
 					}
-					case "migrate": {
-						const handle = await resolver.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);
-						resolver.set(call.id, migrated);
-						const tracked = definitions.get(call.id) ?? (store === void 0 ? void 0 : await store.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 = resolver.get(call.id);
 						const persisted = store !== void 0 && cached === void 0 ? await store.get(call.id) !== void 0 : false;
@@ -2906,7 +2962,6 @@ function createDatabaseTool(options = {}) {
 							await cached.close();
 							resolver.delete(call.id);
 						}
-						definitions.delete(call.id);
 						if (store !== void 0) await store.delete(call.id);
 						return {
 							id: call.id,
@@ -2952,7 +3007,7 @@ function createDatabaseTool(options = {}) {
 * (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
+* effective limit (mirroring {@link import('./helpers.js').clampQuery}'s idiom) to report
 * `truncated`; `'links'` (which has no upstream pagination) fetches the FULL linked-key list and
 * slices/truncates it the same way. `'link'` / `'unlink'` write / remove one `through` junction
 * row.
@@ -3264,6 +3319,6 @@ function createEndpointTool(definition, options) {
 	});
 }
 //#endregion
-export { AGENT_TOOL_DEPTH, AGENT_TOOL_DESCRIPTION, AGENT_TOOL_NAME, AGENT_TOOL_SUMMARY, ANSWER_TOOL_DESCRIPTION, ANSWER_TOOL_NAME, ANSWER_TOOL_SUMMARY, DATABASE_TOOL_DESCRIPTION, DATABASE_TOOL_LIMIT, DATABASE_TOOL_MUTATIONS, DATABASE_TOOL_NAME, DATABASE_TOOL_SUMMARY, DESCRIBE_TOOL_DESCRIPTION, DESCRIBE_TOOL_NAME, DESCRIBE_TOOL_SUMMARY, DatabaseDefinitionStore, DatabaseResolver, INFER_TOOL_DESCRIPTION, INFER_TOOL_NAME, INFER_TOOL_SUMMARY, MAX_WORKFLOW_DEPTH, MemoryDefinitionStore, PROMPT_TOOL_DESCRIPTION, PROMPT_TOOL_NAME, PROMPT_TOOL_SUMMARY, RELATION_TOOL_DEPTH, RELATION_TOOL_DESCRIPTION, RELATION_TOOL_LIMIT, RELATION_TOOL_NAME, RELATION_TOOL_SUMMARY, ToolboxError, WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_TOOL_FLAT_EXAMPLE, WORKFLOW_TOOL_NAME, WORKFLOW_TOOL_NESTED_EXAMPLE, WORKFLOW_TOOL_SUMMARY, WORKSPACE_TOOL_DESCRIPTION, WORKSPACE_TOOL_EXAMPLE, WORKSPACE_TOOL_NAME, WORKSPACE_TOOL_SUMMARY, agentTag, agentToolShape, answerToolShape, clampCriteria, coerceAnswer, columnKindShape, columnSchema, columnShape, columnSpecShape, completeDraft, completePhaseDraft, completeTaskDraft, conditionShape, createAgentFunction, createAgentTool, createAnswerTool, createDatabaseDefinitionStore, createDatabaseTool, createDescribeTool, createEndpointTool, createInferTool, createMemoryDefinitionStore, createPromptTool, createRelationTool, createToolFunction, createWorkflowDraftContract, createWorkflowTool, createWorkspaceTool, criteriaOf, criteriaShape, databaseToolCode, databaseToolShape, describeToolShape, expandInclude, expandSteps, expandTables, includeShape, inferToolShape, isColumnKind, isColumnSpec, isDatabaseDefinition, isToolboxError, keyShape, kindShape, managerShape, orderShape, phaseDraftShape, promptToolShape, relationKeyShape, relationManagerOf, relationModelOf, relationToolCode, relationToolShape, rowShape, rowsShape, singleKeyShape, stepShape, tableSchema, tableSpecShape, taskDraftShape, terminalToolCode, workflowDraftShape, workflowStepsShape, workflowTag, workflowToolSummary, workspaceToolShape };
+export { AGENT_TOOL_DEPTH, AGENT_TOOL_DESCRIPTION, AGENT_TOOL_NAME, AGENT_TOOL_SUMMARY, ANSWER_TOOL_DESCRIPTION, ANSWER_TOOL_NAME, ANSWER_TOOL_SUMMARY, DATABASE_TOOL_DESCRIPTION, DATABASE_TOOL_LIMIT, DATABASE_TOOL_MUTATIONS, DATABASE_TOOL_NAME, DATABASE_TOOL_SUMMARY, DESCRIBE_TOOL_DESCRIPTION, DESCRIBE_TOOL_NAME, DESCRIBE_TOOL_SUMMARY, DatabaseDefinitionStore, DatabaseResolver, INFER_TOOL_DESCRIPTION, INFER_TOOL_NAME, INFER_TOOL_SUMMARY, MAX_WORKFLOW_DEPTH, MemoryDefinitionStore, PROMPT_TOOL_DESCRIPTION, PROMPT_TOOL_NAME, PROMPT_TOOL_SUMMARY, RELATION_TOOL_DEPTH, RELATION_TOOL_DESCRIPTION, RELATION_TOOL_LIMIT, RELATION_TOOL_NAME, RELATION_TOOL_SUMMARY, ToolboxError, WORKFLOW_TOOL_DESCRIPTION, WORKFLOW_TOOL_FLAT_EXAMPLE, WORKFLOW_TOOL_NAME, WORKFLOW_TOOL_NESTED_EXAMPLE, WORKFLOW_TOOL_SUMMARY, WORKSPACE_TOOL_DESCRIPTION, WORKSPACE_TOOL_EXAMPLE, WORKSPACE_TOOL_NAME, WORKSPACE_TOOL_SUMMARY, agentTag, agentToolShape, answerToolShape, clampQuery, coerceAnswer, columnKindShape, columnShape, columnSpecShape, completeDraft, completePhaseDraft, completeTaskDraft, conditionShape, createAgentFunction, createAgentTool, createAnswerTool, createDatabaseDefinitionStore, createDatabaseTool, createDescribeTool, createEndpointTool, createInferTool, createMemoryDefinitionStore, createPromptTool, createRelationTool, createToolFunction, createWorkflowDraftContract, createWorkflowFunctions, createWorkflowTool, createWorkspaceTool, databaseToolCode, databaseToolShape, deriveWorkflowDepth, describeToolShape, expandInclude, expandSteps, expandTables, extendLineage, includeShape, inferToolShape, isAgentFunction, isColumnKind, isColumnSpec, isDatabaseDefinition, isToolboxError, isWorkflowLineage, keyShape, kindShape, lineageOf, managerShape, orderShape, phaseDraftShape, promptToolShape, queryOf, queryShape, relationKeyShape, relationManagerOf, relationModelOf, relationToolCode, relationToolShape, rowShape, rowsShape, singleKeyShape, stepShape, tableSpecShape, taskDraftShape, terminalToolCode, workflowDraftShape, workflowStepsShape, workflowTag, workflowToolSummary, workspaceToolShape };
 
 //# sourceMappingURL=index.js.map