@nhtio/adk 1.20260921.0 → 1.20260925.0

package/{spooled_artifact-BpcesRBv.js → spooled_artifact-CFjf6ULg.cjs}

@@ -1,532 +1,538 @@
-const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_exceptions = require("./exceptions-DrHnAGQz.js");
-const require_guards = require("./guards-05Uq3J4M.js");
-const require_tokenizable = require("./tokenizable-BMZuGWRd.js");
+const require_chunk = require("./chunk-Cek0wNdY.cjs");
+const require_exceptions = require("./exceptions-DrHnAGQz.cjs");
+const require_guards = require("./guards-5-XmJgD2.cjs");
+const require_tokenizable = require("./tokenizable-DDIdXbJN.cjs");
 let _nhtio_validation = require("@nhtio/validation");
+let luxon = require("luxon");
+let js_sha256 = require("js-sha256");
 let dset = require("dset");
 let klona = require("klona");
 let dlv = require("dlv");
 dlv = require_chunk.__toESM(dlv);
-let luxon = require("luxon");
-let js_sha256 = require("js-sha256");
-//#region src/lib/classes/registry.ts
+//#region src/lib/classes/tool_registry.ts
 /**
-* A controlled-mutation key-value store with dot-path access and deep-clone isolation.
+* A mutable, turn-scoped collection of {@link @nhtio/adk!Tool} instances.
 *
 * @remarks
-* The registry enforces a safe read/write contract: callers never hold a live reference into
-* the internal store. Every value that enters (`set`) or leaves (`get`, `all`) is deep-cloned
-* via `klona`, so mutations to a retrieved value cannot affect stored state and vice versa.
+* Each `TurnRunner.run()` call constructs a fresh `ToolRegistry` from the runner's configured
+* baseline tools, so middleware edits are isolated to the current turn and cannot bleed across
+* concurrent or subsequent turns.
 *
-* Keys are dot-delimited paths (e.g. `"user.profile.name"`), resolved via `dlv` for reads and
-* `dset` for writes; intermediate objects are created automatically on write.
+* `Tool` instances are immutable, so `all()` returns a fresh array without deep-cloning.
+*
+* `register()` throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} if a tool with the same name is already
+* present — pass `overwrite: true` to replace it explicitly.
+*
+* Tools can be **hidden** — registered and callable, but excluded from the default tool list
+* rendered to the model. This is useful for discovery patterns where an agent has a tool that
+* enumerates available tools, and the model picks one to call by name in a subsequent iteration.
+* Hidden state is a property of the registry, not the tool: the same tool can be visible in one
+* registry and hidden in another. See {@link hide}, {@link visible}, {@link hidden}.
 */
-var Registry = class Registry {
-	#store;
+var ToolRegistry = class ToolRegistry {
+	#tools;
+	#hidden;
 	/**
-	* @param initial - Optional plain object to seed the registry. Deep-cloned on construction.
-	* @throws {@link @nhtio/adk!E_INVALID_INITIAL_REGISTRY_VALUE} when `initial` is defined but not a plain object.
+	* Returns `true` if `value` is a {@link ToolRegistry} instance.
+	*
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link ToolRegistry} instance.
 	*/
-	constructor(initial) {
-		if ("undefined" !== typeof initial && !require_guards.isObject(initial)) throw new require_tokenizable.E_INVALID_INITIAL_REGISTRY_VALUE();
-		this.#store = initial ? (0, klona.klona)(initial) : {};
+	static isToolRegistry(value) {
+		return require_guards.isInstanceOf(value, "ToolRegistry", ToolRegistry);
 	}
 	/**
-	* Returns `true` if `value` is a {@link Registry} instance.
+	* @param tools - Optional initial tools. Insertion order is preserved. Duplicate names throw
+	*   {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} — ensure each tool has a unique name.
+	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when two tools in `tools` share a name.
+	*/
+	constructor(tools) {
+		this.#tools = /* @__PURE__ */ new Map();
+		this.#hidden = /* @__PURE__ */ new Set();
+		for (const tool of tools ?? []) this.register(tool);
+	}
+	/**
+	* Adds a tool to the registry.
+	*
+	* @param tool - The tool to register.
+	* @param overwrite - When `true`, silently replaces an existing tool with the same name.
+	*   Defaults to `false`.
+	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when a tool with the same name is already registered
+	*   and `overwrite` is not `true`.
+	*/
+	register(tool, overwrite) {
+		if (this.#tools.has(tool.name) && !overwrite) throw new require_tokenizable.E_TOOL_ALREADY_REGISTERED();
+		this.#tools.set(tool.name, tool);
+	}
+	/**
+	* Removes the tool with the given name from the registry.
 	*
 	* @remarks
-	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
+	* Also removes the name from the hidden set if present. No-ops if no tool with that name is
+	* registered.
 	*
-	* @param value - The value to test.
-	* @returns `true` when `value` is a {@link Registry} instance.
+	* @param name - The name of the tool to remove.
 	*/
-	static isRegistry(value) {
-		return require_guards.isInstanceOf(value, "Registry", Registry);
+	unregister(name) {
+		this.#tools.delete(name);
+		this.#hidden.delete(name);
 	}
 	/**
-	* Retrieves the value at `key`, returning `defaultValue` if the path is absent.
+	* Returns the tool registered under `name`, or `undefined` if not present.
 	*
-	* @remarks
-	* The returned value is a deep clone — mutating it will not affect the stored state.
+	* @param name - The tool name to look up.
+	*/
+	get(name) {
+		return this.#tools.get(name);
+	}
+	/**
+	* Returns `true` if a tool with the given name is registered.
 	*
-	* @typeParam T - Expected type of the value at `key`.
-	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
-	* @param defaultValue - Fallback returned when the path resolves to `undefined`.
-	* @returns A deep clone of the stored value cast to `T`, or `defaultValue` when the path is absent.
+	* @param name - The tool name to test.
 	*/
-	get(key, defaultValue) {
-		const value = (0, dlv.default)((0, klona.klona)(this.#store), key);
-		return "undefined" === typeof value ? defaultValue : value;
+	has(name) {
+		return this.#tools.has(name);
 	}
 	/**
-	* Sets the value at `key`, creating intermediate objects as needed.
+	* Returns a fresh array of all registered tools in insertion order.
 	*
 	* @remarks
-	* The stored value is isolated from the caller — mutating `value` after this call will not
-	* affect what is held in the registry.
+	* Includes both visible and hidden tools. Use {@link visible} to get only non-hidden tools, or
+	* {@link hidden} to get only hidden tools.
 	*
-	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
-	* @param value - Value to store at the path.
+	* Since {@link @nhtio/adk!Tool} instances are immutable, no deep-cloning is needed.
 	*/
-	set(key, value) {
-		(0, dset.dset)(this.#store, key, value);
+	all() {
+		return Array.from(this.#tools.values());
 	}
 	/**
-	* Returns `true` if the registry has a value at `key`, `false` otherwise.
+	* Returns a fresh array of registered tools that are **not** hidden, in insertion order.
 	*
 	* @remarks
-	* A key resolving to `undefined` is treated as absent — same convention as {@link Registry.get}'s
-	* `defaultValue` fallback. No clone is performed; this is a pure existence check.
+	* This is the accessor LLM batteries should use when building the tool list for the model.
+	* Hidden tools are still callable (they resolve via {@link get}) but are excluded from the
+	* rendered tool definitions.
+	*/
+	visible() {
+		return this.all().filter((t) => !this.#hidden.has(t.name));
+	}
+	/**
+	* Returns a fresh array of registered tools that **are** hidden, in insertion order.
 	*
-	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
-	* @returns `true` when the path resolves to a value other than `undefined`.
+	* @remarks
+	* The converse of {@link visible}. Useful for discovery tools that enumerate all available
+	* tools, and for propagating hidden state across {@link merge}.
 	*/
-	has(key) {
-		return "undefined" !== typeof (0, dlv.default)(this.#store, key);
+	hidden() {
+		return this.all().filter((t) => this.#hidden.has(t.name));
 	}
 	/**
-	* Returns all leaf dot-paths present in the registry.
+	* Marks one or more registered tools as hidden.
 	*
 	* @remarks
-	* The store is deep-cloned before traversal. Plain objects are walked recursively with path
-	* segments joined by dots; arrays, primitives, `null`, and class instances are treated as leaves.
+	* Hidden tools remain registered and callable via {@link get}, but are excluded from
+	* {@link visible} (and therefore from the LLM tool list). No-ops for any name that is not
+	* currently registered — the end result (the tool is not visible) matches the intent.
 	*
-	* @returns A string array of dot-delimited paths to leaf values in the store.
+	* @param names - One or more tool names to hide.
 	*/
-	keys() {
-		const store = (0, klona.klona)(this.#store);
-		const keys = [];
-		const isPlainRecord = (value) => {
-			if (!require_guards.isObject(value)) return false;
-			const prototype = Object.getPrototypeOf(value);
-			return prototype === Object.prototype || prototype === null;
-		};
-		const walk = (value, segments) => {
-			if (!isPlainRecord(value)) {
-				if (segments.length > 0) keys.push(segments.join("."));
-				return;
-			}
-			for (const [segment, child] of Object.entries(value)) walk(child, [...segments, segment]);
-		};
-		walk(store, []);
-		return keys;
+	hide(...names) {
+		for (const name of names) this.#hidden.add(name);
 	}
 	/**
-	* Returns a deep clone of the entire store contents.
+	* Unmarks one or more tools as hidden, making them visible again.
 	*
-	* @returns A plain object snapshot of all stored key-value pairs.
+	* @remarks
+	* No-ops for any name that is not currently hidden.
+	*
+	* @param names - One or more tool names to unhide.
 	*/
-	all() {
-		return (0, klona.klona)(this.#store);
+	unhide(...names) {
+		for (const name of names) this.#hidden.delete(name);
 	}
 	/**
-	* Serialise this Registry into an `@nhtio/encoder` snapshot.
+	* Replaces the entire hidden set with the given tool names.
 	*
 	* @remarks
-	* The snapshot is a deep clone of the store ({@link Registry.all}). Leaf values that are themselves
-	* registered encodable instances round-trip; anything the encoder cannot serialise throws at encode
-	* time (standard encoder behaviour). Round-trips via {@link Registry.[DECODE_METHOD]}.
+	* Any previously hidden tool not in `names` becomes visible. Names that are not registered are
+	* silently ignored — they are added to the set but have no effect until a tool with that name
+	* is registered.
 	*
-	* @returns A deep-cloned plain-object snapshot of the store.
+	* @param names - The complete set of tool names to hide.
 	*/
-	[require_tokenizable.ENCODE_METHOD]() {
-		return this.all();
+	setHidden(...names) {
+		this.#hidden = new Set(names);
 	}
 	/**
-	* Reconstruct a {@link Registry} from a {@link Registry.[ENCODE_METHOD]} snapshot.
+	* Unhides every tool in the registry.
+	*/
+	clearHidden() {
+		this.#hidden.clear();
+	}
+	/**
+	* Removes every tool whose {@link @nhtio/adk!Tool.ephemeral} flag is `true`.
 	*
-	* @param data - The store snapshot produced by {@link Registry.[ENCODE_METHOD]}.
-	* @returns A fresh {@link Registry} seeded with the snapshot.
+	* @remarks
+	* Also removes pruned tool names from the hidden set. Synchronous and idempotent — calling it
+	* twice in a row is a no-op the second time. The canonical caller is
+	* {@link ToolRegistry.bindContext}, which schedules this method to run at
+	* {@link @nhtio/adk!DispatchContext.ack}. Non-ephemeral tools are left untouched.
 	*/
-	static [require_tokenizable.DECODE_METHOD](data) {
-		return new Registry(data);
+	pruneEphemeral() {
+		for (const [name, tool] of this.#tools) if (tool.ephemeral) {
+			this.#tools.delete(name);
+			this.#hidden.delete(name);
+		}
 	}
-};
-//#endregion
-//#region src/lib/utils/canonical_json.ts
-/**
-* Canonical `JSON.stringify` that sorts object keys recursively so that semantically-equal
-* objects produce identical strings.
-*
-* @remarks
-* Used wherever the ADK derives a stable identity from a structured value — for example,
-* `Tool.executor` computing the `callId` for `ToolExecutionStart`/`End` events, and the
-* `reportToolCall` executor helper computing the `checksum` field on `TurnToolCallContent`.
-* Both code paths hash `canonicalStringify({ tool, args })` so that argument key order does not
-* affect the resulting identifier.
-*
-* Arrays are serialised in their declared order (order is meaningful for an array). Object keys
-* are sorted with `Array.prototype.sort()`'s default lexicographic comparator.
-*
-* @param value - The value to serialise.
-* @returns A canonical JSON string representation of `value`.
-*/
-function canonicalStringify(value) {
-	if (value === null || typeof value !== "object") return JSON.stringify(value);
-	if (Array.isArray(value)) return "[" + value.map((v) => canonicalStringify(v)).join(",") + "]";
-	const obj = value;
-	return "{" + Object.keys(obj).sort().map((k) => JSON.stringify(k) + ":" + canonicalStringify(obj[k])).join(",") + "}";
-}
-//#endregion
-//#region src/lib/contracts/spooled_artifact_constructor.ts
-var ARTIFACT_METHODS = [
-	"head",
-	"tail",
-	"grep",
-	"cat",
-	"byteLength",
-	"lineCount",
-	"estimateTokens"
-];
-/**
-* Validator schema used to validate a {@link SpooledArtifactConstructorLike} value.
-*
-* @remarks
-* Because the validator is invoked at validate-time (not at module-load), it is safe to inspect
-* the constructor's prototype here. The check is duck-typed: the value must be a function whose
-* `prototype` carries every canonical artifact instance method (`head`, `tail`, `grep`, `cat`,
-* `byteLength`, `lineCount`, `estimateTokens`). This mirrors {@link spoolReaderSchema}'s
-* cross-realm-safe duck-type pattern — `instanceof SpooledArtifact` would be tighter but would
-* force a value-import of the class and reopen the module cycle.
-*/
-var spooledArtifactConstructorSchema = _nhtio_validation.validator.any().required().custom((value, helpers) => {
-	if (typeof value !== "function") return helpers.error("any.invalid");
-	const proto = value.prototype;
-	if (proto === void 0 || proto === null) return helpers.error("any.invalid");
-	if (ARTIFACT_METHODS.every((m) => typeof proto[m] === "function")) return value;
-	return helpers.error("any.invalid");
-});
+	/**
+	* Binds this registry to a {@link @nhtio/adk!DispatchContext} so that {@link pruneEphemeral} runs
+	* automatically when the context is acked.
+	*
+	* @remarks
+	* The handler does NOT fire on {@link @nhtio/adk!DispatchContext.nack} — failed executor runs leave
+	* any forged tools in place so the consumer can inspect what was registered when debugging the
+	* failure. Subscriptions are short-lived and die with the context regardless.
+	*
+	* ARTIFACT READERS ARE FORGED BY THE CORE. As of the core-forge change, the `DispatchRunner` forges
+	* artifact-reader tools from prior-turn `SpooledArtifact` results into `ctx.tools` (and calls
+	* `ctx.tools.bindContext(ctx)`) once per iteration, BEFORE the input pipeline — so a battery executor no
+	* longer forges or binds; it reads the already-forged `ctx.tools` for both representation (rendering the
+	* tool declarations) and resolution (looking up an incoming call by name). The lifecycle is unchanged:
+	* ephemeral readers are still pruned on `ack`, and the core re-forges each iteration (prune-then-forge) so
+	* the `callId` enum never goes stale.
+	*
+	* `bindContext` remains the public seam for a CUSTOM consumer that forges its own ephemeral tools outside
+	* the core path. If you forge into a long-lived registry yourself, bind it (or prune manually) or the
+	* ephemeral tools accumulate and later `forgeTools(ctx)` calls see a stale `callId` enum. The pattern for a
+	* hand-rolled forge is:
+	*
+	* ```ts
+	* // Custom forge (the core already does this for artifact readers on ctx.tools):
+	* const forged = SpooledArtifact.forgeTools(ctx)
+	* for (const tool of forged.all()) ctx.tools.register(tool, true)
+	* ctx.tools.bindContext(ctx) // prune the ephemeral readers when the dispatch acks
+	* ```
+	*
+	* @param ctx - The execution context whose `ack` event should trigger pruning.
+	* @returns An unsubscribe function — calling it before `ctx.ack()` prevents pruning. Rarely
+	*   useful outside of tests.
+	*
+	* @see {@link @nhtio/adk!SpooledArtifact.forgeTools}
+	* @see {@link @nhtio/adk!DispatchContext.onAck}
+	*/
+	bindContext(ctx) {
+		return ctx.onAck(() => this.pruneEphemeral());
+	}
+	/**
+	* Combines multiple {@link ToolRegistry} instances into a fresh registry without mutating any
+	* input.
+	*
+	* @remarks
+	* Iteration is left-to-right across `registries` and then in each registry's insertion order.
+	* Collisions are resolved by consulting the **incoming** tool's {@link @nhtio/adk!Tool.onCollision} first:
+	*
+	* - `'replace'` (per-tool): the incoming tool wins, replacing the existing entry.
+	* - `'keep'` (per-tool): the existing entry wins; the incoming tool is dropped.
+	* - `'throw'` (per-tool, the default): fall back to the merge-level `options.onCollision`.
+	*
+	* The merge-level `options.onCollision` defaults to `'throw'`, which mirrors {@link register}.
+	*
+	* The result is a brand-new registry; no input is mutated and no event subscription is
+	* propagated. Each `Tool`'s `ephemeral` flag carries through unchanged — the flag lives on the
+	* tool, not the registry, so `bindContext(ctx)` on the merged registry will prune the forged
+	* tools as expected.
+	*
+	* Hidden state is also propagated: a tool that is hidden in any source registry remains hidden
+	* in the merged result, provided it survives collision resolution.
+	*
+	* @param registries - Registries to merge, in priority order (left-to-right insertion).
+	* @param options - Merge-level collision policy. Defaults to `{ onCollision: 'throw' }`.
+	* @returns A fresh {@link ToolRegistry} containing the resolved union of all inputs.
+	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when the resolved collision policy is `'throw'`
+	*   and a collision occurs.
+	*/
+	static merge(registries, options) {
+		const policy = options?.onCollision ?? "throw";
+		const merged = new ToolRegistry();
+		for (const registry of registries) {
+			for (const tool of registry.all()) {
+				if (!merged.get(tool.name)) {
+					merged.register(tool);
+					continue;
+				}
+				const incomingPolicy = tool.onCollision;
+				if (incomingPolicy === "replace") {
+					merged.register(tool, true);
+					continue;
+				}
+				if (incomingPolicy === "keep") continue;
+				if (policy === "replace") {
+					merged.register(tool, true);
+					continue;
+				}
+				if (policy === "keep") continue;
+				throw new require_tokenizable.E_TOOL_ALREADY_REGISTERED();
+			}
+			for (const tool of registry.hidden()) if (merged.has(tool.name)) merged.hide(tool.name);
+		}
+		return merged;
+	}
+	/**
+	* Serialise this ToolRegistry into an `@nhtio/encoder` snapshot.
+	*
+	* @remarks
+	* Emits the live {@link @nhtio/adk!Tool} instances (the encoder recurses into each — so every tool's
+	* handler-closure caveat from {@link Tool.[ENCODE_METHOD]} applies) plus the hidden-set names. Both
+	* {@link @nhtio/adk!Tool} and {@link @nhtio/adk!ArtifactTool} entries round-trip to their correct
+	* subtype. Round-trips via {@link ToolRegistry.[DECODE_METHOD]}.
+	*
+	* @returns A `{ tools, hidden }` snapshot.
+	*/
+	[require_tokenizable.ENCODE_METHOD]() {
+		return {
+			tools: this.all(),
+			hidden: this.hidden().map((tool) => tool.name)
+		};
+	}
+	/**
+	* Reconstruct a {@link ToolRegistry} from a {@link ToolRegistry.[ENCODE_METHOD]} snapshot.
+	*
+	* @param data - The snapshot produced by {@link ToolRegistry.[ENCODE_METHOD]}.
+	* @returns A fresh {@link ToolRegistry} with the same tools and hidden set.
+	*/
+	static [require_tokenizable.DECODE_METHOD](data) {
+		const snapshot = data;
+		const registry = new ToolRegistry(snapshot.tools);
+		registry.setHidden(...snapshot.hidden);
+		return registry;
+	}
+};
+//#endregion
+//#region src/lib/utils/canonical_json.ts
 /**
-* Returns `true` if `value` is a constructor whose prototype carries every canonical
-* {@link @nhtio/adk!SpooledArtifact} instance method.
+* Canonical `JSON.stringify` that sorts object keys recursively so that semantically-equal
+* objects produce identical strings.
 *
 * @remarks
-* Duck-typed; does not use `instanceof SpooledArtifact`. Used by the `Tool.artifactConstructor`
-* resolver validator and any other site that needs to recognise a `SpooledArtifact`-like
-* constructor without pulling the class into its module-load graph.
+* Used wherever the ADK derives a stable identity from a structured value — for example,
+* `Tool.executor` computing the `callId` for `ToolExecutionStart`/`End` events, and the
+* `reportToolCall` executor helper computing the `checksum` field on `TurnToolCallContent`.
+* Both code paths hash `canonicalStringify({ tool, args })` so that argument key order does not
+* affect the resulting identifier.
 *
-* @param value - The value to test.
-* @returns `true` when `value` is a `SpooledArtifact`-shaped constructor.
-*/
-var implementsSpooledArtifactConstructor = (value) => {
-	return require_exceptions.passesSchema(spooledArtifactConstructorSchema, value);
-};
-/**
-* Creates the validator fragment for a resolver returning a spooled-artifact constructor.
+* Arrays are serialised in their declared order (order is meaningful for an array). Object keys
+* are sorted with `Array.prototype.sort()`'s default lexicographic comparator.
 *
-* The resolver is invoked during validation, then its result is checked with the canonical
-* cross-realm-safe constructor guard. Keeping this fragment here makes `Tool` and `Retrievable`
-* share exactly the same validation behaviour.
+* @param value - The value to serialise.
+* @returns A canonical JSON string representation of `value`.
 */
-var artifactConstructorResolverSchema = () => _nhtio_validation.validator.any().custom((value, helpers) => {
-	if (typeof value !== "function") return helpers.error("any.invalid");
-	let resolved;
-	try {
-		resolved = value();
-	} catch {
-		return helpers.error("any.invalid");
-	}
-	return implementsSpooledArtifactConstructor(resolved) ? value : helpers.error("any.invalid");
-});
+function canonicalStringify(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return "[" + value.map((v) => canonicalStringify(v)).join(",") + "]";
+	const obj = value;
+	return "{" + Object.keys(obj).sort().map((k) => JSON.stringify(k) + ":" + canonicalStringify(obj[k])).join(",") + "}";
+}
 //#endregion
-//#region src/lib/classes/tool.ts
-/**
-* Validator schema for a {@link RawTool}.
-*/
-var rawToolSchema = _nhtio_validation.validator.object({
-	name: _nhtio_validation.validator.string().required(),
-	description: _nhtio_validation.validator.string().required(),
-	inputSchema: _nhtio_validation.validator.any().custom((value, helpers) => {
-		if (_nhtio_validation.validator.isSchema(value) && value.type === "object") return value;
-		return helpers.error("any.invalid");
-	}).required(),
-	handler: _nhtio_validation.validator.function().required(),
-	artifactConstructor: artifactConstructorResolverSchema().optional(),
-	meta: _nhtio_validation.validator.object().pattern(_nhtio_validation.validator.string(), _nhtio_validation.validator.any()).default({}),
-	ephemeral: _nhtio_validation.validator.boolean().default(false),
-	trusted: _nhtio_validation.validator.boolean().default(false),
-	onCollision: _nhtio_validation.validator.string().valid("throw", "replace", "keep").default("throw")
-});
+//#region src/lib/classes/registry.ts
 /**
-* A tool definition that serves as the single source of truth for a callable tool: its name,
-* description, input schema, execution handler, and the {@link @nhtio/adk!SpooledArtifact} subclass that
-* wraps its serialised output.
-*
-* @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype this tool's results should be wrapped in.
-*   Defaults to {@link @nhtio/adk!SpooledArtifact}.
+* A controlled-mutation key-value store with dot-path access and deep-clone isolation.
 *
 * @remarks
-* The `inputSchema` is a `@nhtio/validation` schema. It is used at runtime to validate incoming
-* arguments before the handler is called, and its `.describe()` output provides all the metadata
-* needed to build a provider-specific LLM tool definition — annotate the schema with
-* `.description()`, `.note()`, `.example()` etc. once, and that information is available in both
-* contexts without duplication.
-*
-* The handler is private — invoke it only through `executor(ctx)` which validates args, fires
-* observability events (with a stable `callId` derived from the tool name and arguments), and
-* wraps handler errors in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR}. The handler returns serialised bytes
-* (`string | Uint8Array`); persistence is the consumer's responsibility.
+* The registry enforces a safe read/write contract: callers never hold a live reference into
+* the internal store. Every value that enters (`set`) or leaves (`get`, `all`) is deep-cloned
+* via `klona`, so mutations to a retrieved value cannot affect stored state and vice versa.
 *
-* `artifactConstructor` is the {@link @nhtio/adk!SpooledArtifact} subclass the consumer should use when
-* wrapping the handler's output into a `ToolCall.results` field. The author declares it once
-* on the tool instance; the consumer reads it when assembling persisted records.
+* Keys are dot-delimited paths (e.g. `"user.profile.name"`), resolved via `dlv` for reads and
+* `dset` for writes; intermediate objects are created automatically on write.
 */
-var Tool = class Tool {
+var Registry = class Registry {
+	#store;
 	/**
-	* Validator schema that accepts a {@link RawTool} object.
-	*
-	* @remarks
-	* Reusable fragment for any schema that needs to validate or nest a tool entry
-	* (e.g. `TurnRunnerConfig.tools`).
+	* @param initial - Optional plain object to seed the registry. Deep-cloned on construction.
+	* @throws {@link @nhtio/adk!E_INVALID_INITIAL_REGISTRY_VALUE} when `initial` is defined but not a plain object.
 	*/
-	static schema = rawToolSchema;
+	constructor(initial) {
+		if ("undefined" !== typeof initial && !require_guards.isObject(initial)) throw new require_tokenizable.E_INVALID_INITIAL_REGISTRY_VALUE();
+		this.#store = initial ? (0, klona.klona)(initial) : {};
+	}
 	/**
-	* Returns `true` if `value` is a {@link Tool} instance.
+	* Returns `true` if `value` is a {@link Registry} instance.
+	*
+	* @remarks
+	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.
 	*
 	* @param value - The value to test.
-	* @returns `true` when `value` is a {@link Tool} instance.
+	* @returns `true` when `value` is a {@link Registry} instance.
 	*/
-	static isTool(value) {
-		return require_guards.isInstanceOf(value, "Tool", Tool);
+	static isRegistry(value) {
+		return require_guards.isInstanceOf(value, "Registry", Registry);
 	}
-	#name;
-	#description;
-	#inputSchema;
-	#handler;
-	#artifactConstructor;
-	#meta;
-	#ephemeral;
-	#trusted;
-	#onCollision;
 	/**
-	* @param raw - The raw tool input validated against `rawToolSchema`.
-	* @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy the schema.
+	* Retrieves the value at `key`, returning `defaultValue` if the path is absent.
+	*
+	* @remarks
+	* The returned value is a deep clone — mutating it will not affect the stored state.
+	*
+	* @typeParam T - Expected type of the value at `key`.
+	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
+	* @param defaultValue - Fallback returned when the path resolves to `undefined`.
+	* @returns A deep clone of the stored value cast to `T`, or `defaultValue` when the path is absent.
 	*/
-	constructor(raw) {
-		let resolved;
-		try {
-			resolved = require_exceptions.validateOrThrow(rawToolSchema, raw, true);
-		} catch (err) {
-			throw new require_tokenizable.E_INVALID_INITIAL_TOOL_VALUE({ cause: require_guards.isError(err) ? err : void 0 });
-		}
-		this.#name = resolved.name;
-		this.#description = resolved.description;
-		this.#inputSchema = resolved.inputSchema;
-		this.#handler = resolved.handler;
-		this.#artifactConstructor = resolved.artifactConstructor;
-		this.#meta = new Registry(resolved.meta);
-		this.#ephemeral = resolved.ephemeral;
-		this.#trusted = resolved.trusted;
-		this.#onCollision = resolved.onCollision;
-		Object.defineProperties(this, {
-			name: {
-				get: () => this.#name,
-				enumerable: true,
-				configurable: false
-			},
-			description: {
-				get: () => this.#description,
-				enumerable: true,
-				configurable: false
-			},
-			inputSchema: {
-				get: () => this.#inputSchema,
-				enumerable: true,
-				configurable: false
-			},
-			artifactConstructor: {
-				get: () => this.#artifactConstructor,
-				enumerable: true,
-				configurable: false
-			},
-			meta: {
-				get: () => this.#meta,
-				enumerable: true,
-				configurable: false
-			},
-			ephemeral: {
-				get: () => this.#ephemeral,
-				enumerable: true,
-				configurable: false
-			},
-			trusted: {
-				get: () => this.#trusted,
-				enumerable: true,
-				configurable: false
-			},
-			onCollision: {
-				get: () => this.#onCollision,
-				enumerable: true,
-				configurable: false
-			}
-		});
+	get(key, defaultValue) {
+		const value = (0, dlv.default)((0, klona.klona)(this.#store), key);
+		return "undefined" === typeof value ? defaultValue : value;
 	}
 	/**
-	* Validates `args` against the tool's input schema asynchronously.
+	* Sets the value at `key`, creating intermediate objects as needed.
 	*
 	* @remarks
-	* Async to support schemas with external validators (e.g. database lookups, API calls).
-	* A validation failure throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} — this indicates a programming error
-	* in the tool call loop, not a downstream failure.
+	* The stored value is isolated from the caller — mutating `value` after this call will not
+	* affect what is held in the registry.
 	*
-	* @param args - The arguments to validate.
-	* @returns The validated (and coerced) arguments.
-	* @throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} when `args` does not satisfy the input schema.
+	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
+	* @param value - Value to store at the path.
 	*/
-	async validate(args) {
-		try {
-			return await require_exceptions.asyncValidateOrThrow(this.#inputSchema, args);
-		} catch (err) {
-			if (require_guards.isInstanceOf(err, "ValidationException", require_exceptions.ValidationException)) throw new require_tokenizable.E_INVALID_TOOL_ARGS({ cause: err });
-			throw err;
-		}
+	set(key, value) {
+		(0, dset.dset)(this.#store, key, value);
 	}
 	/**
-	* Returns a bound executor function for this tool against the given turn context.
+	* Returns `true` if the registry has a value at `key`, `false` otherwise.
 	*
 	* @remarks
-	* The executor: (1) computes a stable `callId` as `sha256(canonicalStringify({tool, args}))`
-	* over the **raw, pre-validation args**, (2) validates `args` via {@link Tool.validate},
-	* (3) emits `toolExecutionStart` on the context (with the computed `callId`), (4) calls the
-	* handler, (5) emits `toolExecutionEnd` (with the same `callId`), (6) wraps any handler error
-	* in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR} before re-throwing.
+	* A key resolving to `undefined` is treated as absent — same convention as {@link Registry.get}'s
+	* `defaultValue` fallback. No clone is performed; this is a pure existence check.
 	*
-	* The handler usually returns serialised bytes (`string | Uint8Array`) — persistence is then the
-	* consumer's concern, and {@link Tool.artifactConstructor} is the class a wrap-site uses when
-	* wrapping those bytes into a `ToolCall.results` field. **A handler may instead return a
-	* {@link @nhtio/adk!SpooledArtifact} it built itself** (streaming into storage and wrapping the
-	* reader), in which case wrap-sites pass it through untouched and `artifactConstructor` does not
-	* apply — the returned instance's own class is what artifact-tool forging reads.
+	* @param key - Dot-delimited path into the store (e.g. `"user.name"`).
+	* @returns `true` when the path resolves to a value other than `undefined`.
+	*/
+	has(key) {
+		return "undefined" !== typeof (0, dlv.default)(this.#store, key);
+	}
+	/**
+	* Returns all leaf dot-paths present in the registry.
 	*
-	* Pattern mirrors `Middleware.runner()` — call once per turn, reuse the returned function.
+	* @remarks
+	* The store is deep-cloned before traversal. Plain objects are walked recursively with path
+	* segments joined by dots; arrays, primitives, `null`, and class instances are treated as leaves.
 	*
-	* @param ctx - The active turn context. Provides emit functions and turn ID.
-	* @returns An async function `(args) => Promise<string | Uint8Array | SpooledArtifact | Media | Media[]>`.
-	*   A `SpooledArtifact` is a result the HANDLER built (streamed to storage and wrapped itself); a
-	*   wrap-site passes it through unwrapped rather than re-spooling it. `string`/`Uint8Array` are the
-	*   opposite case — bytes the consumer must still store and wrap.
+	* @returns A string array of dot-delimited paths to leaf values in the store.
 	*/
-	executor(ctx) {
-		return async (args) => {
-			const callId = (0, js_sha256.sha256)(canonicalStringify({
-				tool: this.#name,
-				args
-			}));
-			const validatedArgs = await this.validate(args);
-			const startedAt = luxon.DateTime.now();
-			ctx.emitToolExecutionStart({
-				toolName: this.#name,
-				turnId: ctx.id,
-				callId,
-				args: validatedArgs,
-				startedAt
-			});
-			try {
-				const result = await this.#handler(validatedArgs, ctx, this.#meta);
-				const endedAt = luxon.DateTime.now();
-				ctx.emitToolExecutionEnd({
-					toolName: this.#name,
-					turnId: ctx.id,
-					callId,
-					startedAt,
-					endedAt,
-					durationMs: endedAt.diff(startedAt).milliseconds,
-					isError: false
-				});
-				return result;
-			} catch (err) {
-				const endedAt = luxon.DateTime.now();
-				ctx.emitToolExecutionEnd({
-					toolName: this.#name,
-					turnId: ctx.id,
-					callId,
-					startedAt,
-					endedAt,
-					durationMs: endedAt.diff(startedAt).milliseconds,
-					isError: true
-				});
-				throw new require_tokenizable.E_TOOL_DOWNSTREAM_ERROR({ cause: require_guards.isError(err) ? err : void 0 });
+	keys() {
+		const store = (0, klona.klona)(this.#store);
+		const keys = [];
+		const isPlainRecord = (value) => {
+			if (!require_guards.isObject(value)) return false;
+			const prototype = Object.getPrototypeOf(value);
+			return prototype === Object.prototype || prototype === null;
+		};
+		const walk = (value, segments) => {
+			if (!isPlainRecord(value)) {
+				if (segments.length > 0) keys.push(segments.join("."));
+				return;
 			}
+			for (const [segment, child] of Object.entries(value)) walk(child, [...segments, segment]);
 		};
+		walk(store, []);
+		return keys;
 	}
 	/**
-	* Returns a fully serialisable snapshot of this tool's definition.
-	*
-	* @remarks
-	* The `inputSchema` property is the result of calling `.describe()` on the raw schema — a plain
-	* object carrying all the annotation metadata (descriptions, notes, examples, types) without any
-	* validator functions. Use this to build provider-specific LLM tool definitions.
+	* Returns a deep clone of the entire store contents.
 	*
-	* @returns `{ name, description, inputSchema }` where `inputSchema` is the schema description.
+	* @returns A plain object snapshot of all stored key-value pairs.
 	*/
-	describe() {
-		return {
-			name: this.#name,
-			description: this.#description,
-			inputSchema: this.#inputSchema.describe()
-		};
+	all() {
+		return (0, klona.klona)(this.#store);
 	}
 	/**
-	* Serialise this Tool into an `@nhtio/encoder` snapshot.
+	* Serialise this Registry into an `@nhtio/encoder` snapshot.
 	*
 	* @remarks
-	* Three halves with different serialisation strategies:
-	*
-	* - **Plain config** (`name`, `description`, `meta`, flags) — emitted verbatim.
-	* - **`inputSchema`** — delegated to `@nhtio/validation`'s `encode()`, which captures the full schema
-	*   description plus its library version into a compact string; decode rebuilds the live `Schema`.
-	* - **`handler` / `artifactConstructor`** — emitted as **functions**. The encoder's `FunctionSerializer`
-	*   serialises them by **source text** (`fn.toString()`). This is the sharp edge: a handler that
-	*   closes over `ctx`, service clients, or config loses those bindings on decode — only the source
-	*   survives, and the captured variables read back as `undefined`. A `.bind()`-ed or native handler
-	*   cannot be serialised at all and the encoder throws. Tools are rarely serialised in practice; when
-	*   they are, write handlers that reconstruct their dependencies inside the body rather than closing
-	*   over them.
+	* The snapshot is a deep clone of the store ({@link Registry.all}). Leaf values that are themselves
+	* registered encodable instances round-trip; anything the encoder cannot serialise throws at encode
+	* time (standard encoder behaviour). Round-trips via {@link Registry.[DECODE_METHOD]}.
 	*
-	* @returns A {@link RawTool}-shaped snapshot (with `inputSchema` as an encoded string).
+	* @returns A deep-cloned plain-object snapshot of the store.
 	*/
 	[require_tokenizable.ENCODE_METHOD]() {
-		return {
-			name: this.#name,
-			description: this.#description,
-			inputSchema: (0, _nhtio_validation.encode)(this.#inputSchema),
-			handler: this.#handler,
-			artifactConstructor: this.#artifactConstructor,
-			meta: this.#meta.all(),
-			ephemeral: this.#ephemeral,
-			trusted: this.#trusted,
-			onCollision: this.#onCollision
-		};
+		return this.all();
 	}
 	/**
-	* Reconstruct a {@link Tool} from a {@link Tool.[ENCODE_METHOD]} snapshot.
-	*
-	* @remarks
-	* Rebuilds the live `Schema` via `@nhtio/validation`'s `decode()`, then re-validates through the
-	* constructor. The rehydrated `handler` carries only its source text — see
-	* {@link Tool.[ENCODE_METHOD]} for the closure caveat.
+	* Reconstruct a {@link Registry} from a {@link Registry.[ENCODE_METHOD]} snapshot.
 	*
-	* @param data - The snapshot produced by {@link Tool.[ENCODE_METHOD]}.
-	* @returns A fully-validated {@link Tool}.
+	* @param data - The store snapshot produced by {@link Registry.[ENCODE_METHOD]}.
+	* @returns A fresh {@link Registry} seeded with the snapshot.
 	*/
 	static [require_tokenizable.DECODE_METHOD](data) {
-		const snapshot = data;
-		return new Tool({
-			...snapshot,
-			inputSchema: (0, _nhtio_validation.decode)(snapshot.inputSchema)
-		});
+		return new Registry(data);
 	}
 };
 //#endregion
-//#region src/lib/classes/artifact_tool.ts
+//#region src/lib/contracts/spooled_artifact_constructor.ts
+var ARTIFACT_METHODS = [
+	"head",
+	"tail",
+	"grep",
+	"cat",
+	"byteLength",
+	"lineCount",
+	"estimateTokens"
+];
 /**
-* Validator schema for a {@link RawArtifactTool}.
+* Validator schema used to validate a {@link SpooledArtifactConstructorLike} value.
 *
 * @remarks
-* Mirrors the base tool schema but explicitly forbids `artifactConstructor` — the entire
-* point of `ArtifactTool` is to opt out of `SpooledArtifact` wrapping.
+* Because the validator is invoked at validate-time (not at module-load), it is safe to inspect
+* the constructor's prototype here. The check is duck-typed: the value must be a function whose
+* `prototype` carries every canonical artifact instance method (`head`, `tail`, `grep`, `cat`,
+* `byteLength`, `lineCount`, `estimateTokens`). This mirrors {@link spoolReaderSchema}'s
+* cross-realm-safe duck-type pattern — `instanceof SpooledArtifact` would be tighter but would
+* force a value-import of the class and reopen the module cycle.
 */
-var rawArtifactToolSchema = _nhtio_validation.validator.object({
+var spooledArtifactConstructorSchema = _nhtio_validation.validator.any().required().custom((value, helpers) => {
+	if (typeof value !== "function") return helpers.error("any.invalid");
+	const proto = value.prototype;
+	if (proto === void 0 || proto === null) return helpers.error("any.invalid");
+	if (ARTIFACT_METHODS.every((m) => typeof proto[m] === "function")) return value;
+	return helpers.error("any.invalid");
+});
+/**
+* Returns `true` if `value` is a constructor whose prototype carries every canonical
+* {@link @nhtio/adk!SpooledArtifact} instance method.
+*
+* @remarks
+* Duck-typed; does not use `instanceof SpooledArtifact`. Used by the `Tool.artifactConstructor`
+* resolver validator and any other site that needs to recognise a `SpooledArtifact`-like
+* constructor without pulling the class into its module-load graph.
+*
+* @param value - The value to test.
+* @returns `true` when `value` is a `SpooledArtifact`-shaped constructor.
+*/
+var implementsSpooledArtifactConstructor = (value) => {
+	return require_exceptions.passesSchema(spooledArtifactConstructorSchema, value);
+};
+/**
+* Creates the validator fragment for a resolver returning a spooled-artifact constructor.
+*
+* The resolver is invoked during validation, then its result is checked with the canonical
+* cross-realm-safe constructor guard. Keeping this fragment here makes `Tool` and `Retrievable`
+* share exactly the same validation behaviour.
+*/
+var artifactConstructorResolverSchema = () => _nhtio_validation.validator.any().custom((value, helpers) => {
+	if (typeof value !== "function") return helpers.error("any.invalid");
+	let resolved;
+	try {
+		resolved = value();
+	} catch {
+		return helpers.error("any.invalid");
+	}
+	return implementsSpooledArtifactConstructor(resolved) ? value : helpers.error("any.invalid");
+});
+//#endregion
+//#region src/lib/classes/tool.ts
+/**
+* Validator schema for a {@link RawTool}.
+*/
+var rawToolSchema = _nhtio_validation.validator.object({
 	name: _nhtio_validation.validator.string().required(),
 	description: _nhtio_validation.validator.string().required(),
 	inputSchema: _nhtio_validation.validator.any().custom((value, helpers) => {
@@ -534,404 +540,398 @@ var rawArtifactToolSchema = _nhtio_validation.validator.object({
 		return helpers.error("any.invalid");
 	}).required(),
 	handler: _nhtio_validation.validator.function().required(),
+	artifactConstructor: artifactConstructorResolverSchema().optional(),
 	meta: _nhtio_validation.validator.object().pattern(_nhtio_validation.validator.string(), _nhtio_validation.validator.any()).default({}),
 	ephemeral: _nhtio_validation.validator.boolean().default(false),
 	trusted: _nhtio_validation.validator.boolean().default(false),
-	onCollision: _nhtio_validation.validator.string().valid("throw", "replace", "keep").default("throw"),
-	artifactConstructor: _nhtio_validation.validator.any().forbidden()
+	onCollision: _nhtio_validation.validator.string().valid("throw", "replace", "keep").default("throw")
 });
 /**
-* A {@link @nhtio/adk!Tool} subclass whose handler return value is wrapped directly in a
-* {@link @nhtio/adk!Tokenizable} (not a {@link @nhtio/adk!SpooledArtifact}) when it
-* lands on `ToolCall.results`.
-*
-* @remarks
-* `ArtifactTool` is the canonical producer for **forged artifact-query tools** — the tools
-* `SpooledArtifact.forgeTools(ctx)` emits so the model can `head`, `tail`, `grep`, `json_get`,
-* `md_headings` (etc.) an artifact that is already in `ctx.turnToolCalls`.
-*
-* The difference from {@link @nhtio/adk!Tool} is structural, not stylistic:
-*
-* - A normal `Tool`'s handler returns bytes the ADK wraps in a fresh `SpooledArtifact`.
-*   The artifact lands in `ToolCall.results`, joins `ctx.turnToolCalls`, and is itself a
-*   first-class queryable artifact in the turn.
-* - An `ArtifactTool`'s handler returns a string that is **already the model-visible answer**
-*   to a query against an existing artifact. The ADK wraps it in a `Tokenizable` rather
-*   than a `SpooledArtifact`; nothing new is queryable on its own. Subsequent
-*   `forgeTools(ctx)` calls exclude `ToolCall`s produced by an `ArtifactTool` from the
-*   `callId` enum (via the `ToolCall.fromArtifactTool` marker) — this is the structural fix
-*   that breaks the otherwise-recursive grep-on-the-grep-result loop.
+* A tool definition that serves as the single source of truth for a callable tool: its name,
+* description, input schema, execution handler, and the {@link @nhtio/adk!SpooledArtifact} subclass that
+* wraps its serialised output.
 *
-* Consumers who want to build their own artifact-query tools (e.g. for a domain-specific
-* spooled subclass not shipped by the ADK) should extend or instantiate this class.
-*/
-var ArtifactTool = class ArtifactTool extends Tool {
-	/**
-	* Validator schema that accepts a {@link RawArtifactTool} object.
-	*
-	* @remarks
-	* Differs from {@link @nhtio/adk!Tool.schema} by forbidding `artifactConstructor` — wrapping is
-	* exactly the thing this class opts out of. Typed identically to {@link @nhtio/adk!Tool.schema} so the
-	* subclass relationship `class ArtifactTool extends Tool` remains structurally sound; the
-	* runtime validation rules still differ as declared by `rawArtifactToolSchema`.
-	*/
-	static schema = rawArtifactToolSchema;
-	/**
-	* Returns `true` if `value` is an {@link ArtifactTool} instance.
-	*
-	* @remarks
-	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances
-	* created in a different module copy or VM context.
-	*
-	* @param value - The value to test.
-	* @returns `true` when `value` is an {@link ArtifactTool} instance.
-	*/
-	static isArtifactTool(value) {
-		return require_guards.isInstanceOf(value, "ArtifactTool", ArtifactTool);
-	}
-	/**
-	* @param raw - Raw tool input validated against {@link ArtifactTool.schema}.
-	*
-	* @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy
-	*   {@link ArtifactTool.schema} (most commonly, when `artifactConstructor` is supplied — it is
-	*   explicitly forbidden on this class) or when the base {@link @nhtio/adk!Tool} constructor rejects the
-	*   input for any reason.
-	*/
-	constructor(raw) {
-		try {
-			require_exceptions.validateOrThrow(rawArtifactToolSchema, raw, true);
-		} catch (err) {
-			if (require_guards.isInstanceOf(err, "ValidationException", require_exceptions.ValidationException)) throw new require_tokenizable.E_INVALID_INITIAL_TOOL_VALUE({ cause: err });
-			throw err;
-		}
-		super(raw);
-	}
-	/**
-	* Serialise this ArtifactTool into an `@nhtio/encoder` snapshot.
-	*
-	* @remarks
-	* Reuses the base {@link Tool.[ENCODE_METHOD]} (function-serialised `handler`, validation-encoded
-	* `inputSchema`, plain config) and strips `artifactConstructor` — which {@link ArtifactTool.schema}
-	* forbids. The handler's closure caveat from {@link Tool.[ENCODE_METHOD]} applies here too.
-	*
-	* @returns A {@link RawArtifactTool}-shaped snapshot (with `inputSchema` as an encoded string).
-	*/
-	[require_tokenizable.ENCODE_METHOD]() {
-		const base = super[require_tokenizable.ENCODE_METHOD]();
-		delete base.artifactConstructor;
-		return base;
-	}
-	/**
-	* Reconstruct an {@link ArtifactTool} from an {@link ArtifactTool.[ENCODE_METHOD]} snapshot.
-	*
-	* @param data - The snapshot produced by {@link ArtifactTool.[ENCODE_METHOD]}.
-	* @returns A fully-validated {@link ArtifactTool}.
-	*/
-	static [require_tokenizable.DECODE_METHOD](data) {
-		const snapshot = data;
-		return new ArtifactTool({
-			...snapshot,
-			inputSchema: (0, _nhtio_validation.decode)(snapshot.inputSchema)
-		});
-	}
-};
-//#endregion
-//#region src/lib/classes/tool_registry.ts
-/**
-* A mutable, turn-scoped collection of {@link @nhtio/adk!Tool} instances.
+* @typeParam A - The {@link @nhtio/adk!SpooledArtifact} subtype this tool's results should be wrapped in.
+*   Defaults to {@link @nhtio/adk!SpooledArtifact}.
 *
 * @remarks
-* Each `TurnRunner.run()` call constructs a fresh `ToolRegistry` from the runner's configured
-* baseline tools, so middleware edits are isolated to the current turn and cannot bleed across
-* concurrent or subsequent turns.
-*
-* `Tool` instances are immutable, so `all()` returns a fresh array without deep-cloning.
+* The `inputSchema` is a `@nhtio/validation` schema. It is used at runtime to validate incoming
+* arguments before the handler is called, and its `.describe()` output provides all the metadata
+* needed to build a provider-specific LLM tool definition — annotate the schema with
+* `.description()`, `.note()`, `.example()` etc. once, and that information is available in both
+* contexts without duplication.
 *
-* `register()` throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} if a tool with the same name is already
-* present — pass `overwrite: true` to replace it explicitly.
+* The handler is private — invoke it only through `executor(ctx)` which validates args, fires
+* observability events (with a stable `callId` derived from the tool name and arguments), and
+* wraps handler errors in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR}. The handler returns serialised bytes
+* (`string | Uint8Array`); persistence is the consumer's responsibility.
 *
-* Tools can be **hidden** — registered and callable, but excluded from the default tool list
-* rendered to the model. This is useful for discovery patterns where an agent has a tool that
-* enumerates available tools, and the model picks one to call by name in a subsequent iteration.
-* Hidden state is a property of the registry, not the tool: the same tool can be visible in one
-* registry and hidden in another. See {@link hide}, {@link visible}, {@link hidden}.
+* `artifactConstructor` is the {@link @nhtio/adk!SpooledArtifact} subclass the consumer should use when
+* wrapping the handler's output into a `ToolCall.results` field. The author declares it once
+* on the tool instance; the consumer reads it when assembling persisted records.
 */
-var ToolRegistry = class ToolRegistry {
-	#tools;
-	#hidden;
-	/**
-	* Returns `true` if `value` is a {@link ToolRegistry} instance.
-	*
-	* @param value - The value to test.
-	* @returns `true` when `value` is a {@link ToolRegistry} instance.
-	*/
-	static isToolRegistry(value) {
-		return require_guards.isInstanceOf(value, "ToolRegistry", ToolRegistry);
-	}
-	/**
-	* @param tools - Optional initial tools. Insertion order is preserved. Duplicate names throw
-	*   {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} — ensure each tool has a unique name.
-	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when two tools in `tools` share a name.
-	*/
-	constructor(tools) {
-		this.#tools = /* @__PURE__ */ new Map();
-		this.#hidden = /* @__PURE__ */ new Set();
-		for (const tool of tools ?? []) this.register(tool);
-	}
-	/**
-	* Adds a tool to the registry.
-	*
-	* @param tool - The tool to register.
-	* @param overwrite - When `true`, silently replaces an existing tool with the same name.
-	*   Defaults to `false`.
-	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when a tool with the same name is already registered
-	*   and `overwrite` is not `true`.
-	*/
-	register(tool, overwrite) {
-		if (this.#tools.has(tool.name) && !overwrite) throw new require_tokenizable.E_TOOL_ALREADY_REGISTERED();
-		this.#tools.set(tool.name, tool);
-	}
+var Tool = class Tool {
 	/**
-	* Removes the tool with the given name from the registry.
+	* Validator schema that accepts a {@link RawTool} object.
 	*
 	* @remarks
-	* Also removes the name from the hidden set if present. No-ops if no tool with that name is
-	* registered.
-	*
-	* @param name - The name of the tool to remove.
+	* Reusable fragment for any schema that needs to validate or nest a tool entry
+	* (e.g. `TurnRunnerConfig.tools`).
 	*/
-	unregister(name) {
-		this.#tools.delete(name);
-		this.#hidden.delete(name);
-	}
+	static schema = rawToolSchema;
 	/**
-	* Returns the tool registered under `name`, or `undefined` if not present.
+	* Returns `true` if `value` is a {@link Tool} instance.
 	*
-	* @param name - The tool name to look up.
+	* @param value - The value to test.
+	* @returns `true` when `value` is a {@link Tool} instance.
 	*/
-	get(name) {
-		return this.#tools.get(name);
+	static isTool(value) {
+		return require_guards.isInstanceOf(value, "Tool", Tool);
 	}
+	#name;
+	#description;
+	#inputSchema;
+	#handler;
+	#artifactConstructor;
+	#meta;
+	#ephemeral;
+	#trusted;
+	#onCollision;
 	/**
-	* Returns `true` if a tool with the given name is registered.
-	*
-	* @param name - The tool name to test.
+	* @param raw - The raw tool input validated against `rawToolSchema`.
+	* @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy the schema.
 	*/
-	has(name) {
-		return this.#tools.has(name);
+	constructor(raw) {
+		let resolved;
+		try {
+			resolved = require_exceptions.validateOrThrow(rawToolSchema, raw, true);
+		} catch (err) {
+			throw new require_tokenizable.E_INVALID_INITIAL_TOOL_VALUE({ cause: require_guards.isError(err) ? err : void 0 });
+		}
+		this.#name = resolved.name;
+		this.#description = resolved.description;
+		this.#inputSchema = resolved.inputSchema;
+		this.#handler = resolved.handler;
+		this.#artifactConstructor = resolved.artifactConstructor;
+		this.#meta = new Registry(resolved.meta);
+		this.#ephemeral = resolved.ephemeral;
+		this.#trusted = resolved.trusted;
+		this.#onCollision = resolved.onCollision;
+		Object.defineProperties(this, {
+			name: {
+				get: () => this.#name,
+				enumerable: true,
+				configurable: false
+			},
+			description: {
+				get: () => this.#description,
+				enumerable: true,
+				configurable: false
+			},
+			inputSchema: {
+				get: () => this.#inputSchema,
+				enumerable: true,
+				configurable: false
+			},
+			artifactConstructor: {
+				get: () => this.#artifactConstructor,
+				enumerable: true,
+				configurable: false
+			},
+			meta: {
+				get: () => this.#meta,
+				enumerable: true,
+				configurable: false
+			},
+			ephemeral: {
+				get: () => this.#ephemeral,
+				enumerable: true,
+				configurable: false
+			},
+			trusted: {
+				get: () => this.#trusted,
+				enumerable: true,
+				configurable: false
+			},
+			onCollision: {
+				get: () => this.#onCollision,
+				enumerable: true,
+				configurable: false
+			}
+		});
 	}
 	/**
-	* Returns a fresh array of all registered tools in insertion order.
+	* Validates `args` against the tool's input schema asynchronously.
 	*
 	* @remarks
-	* Includes both visible and hidden tools. Use {@link visible} to get only non-hidden tools, or
-	* {@link hidden} to get only hidden tools.
+	* Async to support schemas with external validators (e.g. database lookups, API calls).
+	* A validation failure throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} — this indicates a programming error
+	* in the tool call loop, not a downstream failure.
 	*
-	* Since {@link @nhtio/adk!Tool} instances are immutable, no deep-cloning is needed.
+	* @param args - The arguments to validate.
+	* @returns The validated (and coerced) arguments.
+	* @throws {@link @nhtio/adk!E_INVALID_TOOL_ARGS} when `args` does not satisfy the input schema.
 	*/
-	all() {
-		return Array.from(this.#tools.values());
+	async validate(args) {
+		try {
+			return await require_exceptions.asyncValidateOrThrow(this.#inputSchema, args);
+		} catch (err) {
+			if (require_guards.isInstanceOf(err, "ValidationException", require_exceptions.ValidationException)) throw new require_tokenizable.E_INVALID_TOOL_ARGS({ cause: err });
+			throw err;
+		}
 	}
 	/**
-	* Returns a fresh array of registered tools that are **not** hidden, in insertion order.
+	* Returns a bound executor function for this tool against the given turn context.
 	*
 	* @remarks
-	* This is the accessor LLM batteries should use when building the tool list for the model.
-	* Hidden tools are still callable (they resolve via {@link get}) but are excluded from the
-	* rendered tool definitions.
-	*/
-	visible() {
-		return this.all().filter((t) => !this.#hidden.has(t.name));
-	}
-	/**
-	* Returns a fresh array of registered tools that **are** hidden, in insertion order.
+	* The executor: (1) computes a stable `callId` as `sha256(canonicalStringify({tool, args}))`
+	* over the **raw, pre-validation args**, (2) validates `args` via {@link Tool.validate},
+	* (3) emits `toolExecutionStart` on the context (with the computed `callId`), (4) calls the
+	* handler, (5) emits `toolExecutionEnd` (with the same `callId`), (6) wraps any handler error
+	* in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR} before re-throwing.
 	*
-	* @remarks
-	* The converse of {@link visible}. Useful for discovery tools that enumerate all available
-	* tools, and for propagating hidden state across {@link merge}.
+	* The handler usually returns serialised bytes (`string | Uint8Array`) — persistence is then the
+	* consumer's concern, and {@link Tool.artifactConstructor} is the class a wrap-site uses when
+	* wrapping those bytes into a `ToolCall.results` field. **A handler may instead return a
+	* {@link @nhtio/adk!SpooledArtifact} it built itself** (streaming into storage and wrapping the
+	* reader), in which case wrap-sites pass it through untouched and `artifactConstructor` does not
+	* apply — the returned instance's own class is what artifact-tool forging reads.
+	*
+	* Pattern mirrors `Middleware.runner()` — call once per turn, reuse the returned function.
+	*
+	* @param ctx - The active turn context. Provides emit functions and turn ID.
+	* @returns An async function `(args) => Promise<string | Uint8Array | SpooledArtifact | Media | Media[]>`.
+	*   A `SpooledArtifact` is a result the HANDLER built (streamed to storage and wrapped itself); a
+	*   wrap-site passes it through unwrapped rather than re-spooling it. `string`/`Uint8Array` are the
+	*   opposite case — bytes the consumer must still store and wrap.
 	*/
-	hidden() {
-		return this.all().filter((t) => this.#hidden.has(t.name));
+	executor(ctx) {
+		return async (args) => {
+			const callId = (0, js_sha256.sha256)(canonicalStringify({
+				tool: this.#name,
+				args
+			}));
+			const validatedArgs = await this.validate(args);
+			const startedAt = luxon.DateTime.now();
+			ctx.emitToolExecutionStart({
+				toolName: this.#name,
+				turnId: ctx.id,
+				callId,
+				args: validatedArgs,
+				startedAt
+			});
+			try {
+				const result = await this.#handler(validatedArgs, ctx, this.#meta);
+				const endedAt = luxon.DateTime.now();
+				ctx.emitToolExecutionEnd({
+					toolName: this.#name,
+					turnId: ctx.id,
+					callId,
+					startedAt,
+					endedAt,
+					durationMs: endedAt.diff(startedAt).milliseconds,
+					isError: false
+				});
+				return result;
+			} catch (err) {
+				const endedAt = luxon.DateTime.now();
+				ctx.emitToolExecutionEnd({
+					toolName: this.#name,
+					turnId: ctx.id,
+					callId,
+					startedAt,
+					endedAt,
+					durationMs: endedAt.diff(startedAt).milliseconds,
+					isError: true
+				});
+				throw new require_tokenizable.E_TOOL_DOWNSTREAM_ERROR({ cause: require_guards.isError(err) ? err : void 0 });
+			}
+		};
 	}
 	/**
-	* Marks one or more registered tools as hidden.
+	* Returns a fully serialisable snapshot of this tool's definition.
 	*
 	* @remarks
-	* Hidden tools remain registered and callable via {@link get}, but are excluded from
-	* {@link visible} (and therefore from the LLM tool list). No-ops for any name that is not
-	* currently registered — the end result (the tool is not visible) matches the intent.
+	* The `inputSchema` property is the result of calling `.describe()` on the raw schema — a plain
+	* object carrying all the annotation metadata (descriptions, notes, examples, types) without any
+	* validator functions. Use this to build provider-specific LLM tool definitions.
 	*
-	* @param names - One or more tool names to hide.
+	* @returns `{ name, description, inputSchema }` where `inputSchema` is the schema description.
 	*/
-	hide(...names) {
-		for (const name of names) this.#hidden.add(name);
+	describe() {
+		return {
+			name: this.#name,
+			description: this.#description,
+			inputSchema: this.#inputSchema.describe()
+		};
 	}
 	/**
-	* Unmarks one or more tools as hidden, making them visible again.
+	* Serialise this Tool into an `@nhtio/encoder` snapshot.
 	*
 	* @remarks
-	* No-ops for any name that is not currently hidden.
+	* Three halves with different serialisation strategies:
 	*
-	* @param names - One or more tool names to unhide.
+	* - **Plain config** (`name`, `description`, `meta`, flags) — emitted verbatim.
+	* - **`inputSchema`** — delegated to `@nhtio/validation`'s `encode()`, which captures the full schema
+	*   description plus its library version into a compact string; decode rebuilds the live `Schema`.
+	* - **`handler` / `artifactConstructor`** — emitted as **functions**. The encoder's `FunctionSerializer`
+	*   serialises them by **source text** (`fn.toString()`). This is the sharp edge: a handler that
+	*   closes over `ctx`, service clients, or config loses those bindings on decode — only the source
+	*   survives, and the captured variables read back as `undefined`. A `.bind()`-ed or native handler
+	*   cannot be serialised at all and the encoder throws. Tools are rarely serialised in practice; when
+	*   they are, write handlers that reconstruct their dependencies inside the body rather than closing
+	*   over them.
+	*
+	* @returns A {@link RawTool}-shaped snapshot (with `inputSchema` as an encoded string).
 	*/
-	unhide(...names) {
-		for (const name of names) this.#hidden.delete(name);
+	[require_tokenizable.ENCODE_METHOD]() {
+		return {
+			name: this.#name,
+			description: this.#description,
+			inputSchema: (0, _nhtio_validation.encode)(this.#inputSchema),
+			handler: this.#handler,
+			artifactConstructor: this.#artifactConstructor,
+			meta: this.#meta.all(),
+			ephemeral: this.#ephemeral,
+			trusted: this.#trusted,
+			onCollision: this.#onCollision
+		};
 	}
 	/**
-	* Replaces the entire hidden set with the given tool names.
+	* Reconstruct a {@link Tool} from a {@link Tool.[ENCODE_METHOD]} snapshot.
 	*
 	* @remarks
-	* Any previously hidden tool not in `names` becomes visible. Names that are not registered are
-	* silently ignored — they are added to the set but have no effect until a tool with that name
-	* is registered.
+	* Rebuilds the live `Schema` via `@nhtio/validation`'s `decode()`, then re-validates through the
+	* constructor. The rehydrated `handler` carries only its source text — see
+	* {@link Tool.[ENCODE_METHOD]} for the closure caveat.
 	*
-	* @param names - The complete set of tool names to hide.
-	*/
-	setHidden(...names) {
-		this.#hidden = new Set(names);
-	}
-	/**
-	* Unhides every tool in the registry.
+	* @param data - The snapshot produced by {@link Tool.[ENCODE_METHOD]}.
+	* @returns A fully-validated {@link Tool}.
 	*/
-	clearHidden() {
-		this.#hidden.clear();
+	static [require_tokenizable.DECODE_METHOD](data) {
+		const snapshot = data;
+		return new Tool({
+			...snapshot,
+			inputSchema: (0, _nhtio_validation.decode)(snapshot.inputSchema)
+		});
 	}
+};
+//#endregion
+//#region src/lib/classes/artifact_tool.ts
+/**
+* Validator schema for a {@link RawArtifactTool}.
+*
+* @remarks
+* Mirrors the base tool schema but explicitly forbids `artifactConstructor` — the entire
+* point of `ArtifactTool` is to opt out of `SpooledArtifact` wrapping.
+*/
+var rawArtifactToolSchema = _nhtio_validation.validator.object({
+	name: _nhtio_validation.validator.string().required(),
+	description: _nhtio_validation.validator.string().required(),
+	inputSchema: _nhtio_validation.validator.any().custom((value, helpers) => {
+		if (_nhtio_validation.validator.isSchema(value) && value.type === "object") return value;
+		return helpers.error("any.invalid");
+	}).required(),
+	handler: _nhtio_validation.validator.function().required(),
+	meta: _nhtio_validation.validator.object().pattern(_nhtio_validation.validator.string(), _nhtio_validation.validator.any()).default({}),
+	ephemeral: _nhtio_validation.validator.boolean().default(false),
+	trusted: _nhtio_validation.validator.boolean().default(false),
+	onCollision: _nhtio_validation.validator.string().valid("throw", "replace", "keep").default("throw"),
+	artifactConstructor: _nhtio_validation.validator.any().forbidden()
+});
+/**
+* A {@link @nhtio/adk!Tool} subclass whose handler return value is wrapped directly in a
+* {@link @nhtio/adk!Tokenizable} (not a {@link @nhtio/adk!SpooledArtifact}) when it
+* lands on `ToolCall.results`.
+*
+* @remarks
+* `ArtifactTool` is the canonical producer for **forged artifact-query tools** — the tools
+* `SpooledArtifact.forgeTools(ctx)` emits so the model can `head`, `tail`, `grep`, `json_get`,
+* `md_headings` (etc.) an artifact that is already in `ctx.turnToolCalls`.
+*
+* The difference from {@link @nhtio/adk!Tool} is structural, not stylistic:
+*
+* - A normal `Tool`'s handler returns bytes the ADK wraps in a fresh `SpooledArtifact`.
+*   The artifact lands in `ToolCall.results`, joins `ctx.turnToolCalls`, and is itself a
+*   first-class queryable artifact in the turn.
+* - An `ArtifactTool`'s handler returns a string that is **already the model-visible answer**
+*   to a query against an existing artifact. The ADK wraps it in a `Tokenizable` rather
+*   than a `SpooledArtifact`; nothing new is queryable on its own. Subsequent
+*   `forgeTools(ctx)` calls exclude `ToolCall`s produced by an `ArtifactTool` from the
+*   `callId` enum (via the `ToolCall.fromArtifactTool` marker) — this is the structural fix
+*   that breaks the otherwise-recursive grep-on-the-grep-result loop.
+*
+* Consumers who want to build their own artifact-query tools (e.g. for a domain-specific
+* spooled subclass not shipped by the ADK) should extend or instantiate this class.
+*/
+var ArtifactTool = class ArtifactTool extends Tool {
 	/**
-	* Removes every tool whose {@link @nhtio/adk!Tool.ephemeral} flag is `true`.
+	* Validator schema that accepts a {@link RawArtifactTool} object.
 	*
 	* @remarks
-	* Also removes pruned tool names from the hidden set. Synchronous and idempotent — calling it
-	* twice in a row is a no-op the second time. The canonical caller is
-	* {@link ToolRegistry.bindContext}, which schedules this method to run at
-	* {@link @nhtio/adk!DispatchContext.ack}. Non-ephemeral tools are left untouched.
+	* Differs from {@link @nhtio/adk!Tool.schema} by forbidding `artifactConstructor` — wrapping is
+	* exactly the thing this class opts out of. Typed identically to {@link @nhtio/adk!Tool.schema} so the
+	* subclass relationship `class ArtifactTool extends Tool` remains structurally sound; the
+	* runtime validation rules still differ as declared by `rawArtifactToolSchema`.
 	*/
-	pruneEphemeral() {
-		for (const [name, tool] of this.#tools) if (tool.ephemeral) {
-			this.#tools.delete(name);
-			this.#hidden.delete(name);
-		}
-	}
+	static schema = rawArtifactToolSchema;
 	/**
-	* Binds this registry to a {@link @nhtio/adk!DispatchContext} so that {@link pruneEphemeral} runs
-	* automatically when the context is acked.
+	* Returns `true` if `value` is an {@link ArtifactTool} instance.
 	*
 	* @remarks
-	* The handler does NOT fire on {@link @nhtio/adk!DispatchContext.nack} — failed executor runs leave
-	* any forged tools in place so the consumer can inspect what was registered when debugging the
-	* failure. Subscriptions are short-lived and die with the context regardless.
-	*
-	* ARTIFACT READERS ARE FORGED BY THE CORE. As of the core-forge change, the `DispatchRunner` forges
-	* artifact-reader tools from prior-turn `SpooledArtifact` results into `ctx.tools` (and calls
-	* `ctx.tools.bindContext(ctx)`) once per iteration, BEFORE the input pipeline — so a battery executor no
-	* longer forges or binds; it reads the already-forged `ctx.tools` for both representation (rendering the
-	* tool declarations) and resolution (looking up an incoming call by name). The lifecycle is unchanged:
-	* ephemeral readers are still pruned on `ack`, and the core re-forges each iteration (prune-then-forge) so
-	* the `callId` enum never goes stale.
-	*
-	* `bindContext` remains the public seam for a CUSTOM consumer that forges its own ephemeral tools outside
-	* the core path. If you forge into a long-lived registry yourself, bind it (or prune manually) or the
-	* ephemeral tools accumulate and later `forgeTools(ctx)` calls see a stale `callId` enum. The pattern for a
-	* hand-rolled forge is:
-	*
-	* ```ts
-	* // Custom forge (the core already does this for artifact readers on ctx.tools):
-	* const forged = SpooledArtifact.forgeTools(ctx)
-	* for (const tool of forged.all()) ctx.tools.register(tool, true)
-	* ctx.tools.bindContext(ctx) // prune the ephemeral readers when the dispatch acks
-	* ```
-	*
-	* @param ctx - The execution context whose `ack` event should trigger pruning.
-	* @returns An unsubscribe function — calling it before `ctx.ack()` prevents pruning. Rarely
-	*   useful outside of tests.
+	* Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety — `instanceof` would fail for instances
+	* created in a different module copy or VM context.
 	*
-	* @see {@link @nhtio/adk!SpooledArtifact.forgeTools}
-	* @see {@link @nhtio/adk!DispatchContext.onAck}
+	* @param value - The value to test.
+	* @returns `true` when `value` is an {@link ArtifactTool} instance.
 	*/
-	bindContext(ctx) {
-		return ctx.onAck(() => this.pruneEphemeral());
+	static isArtifactTool(value) {
+		return require_guards.isInstanceOf(value, "ArtifactTool", ArtifactTool);
 	}
 	/**
-	* Combines multiple {@link ToolRegistry} instances into a fresh registry without mutating any
-	* input.
-	*
-	* @remarks
-	* Iteration is left-to-right across `registries` and then in each registry's insertion order.
-	* Collisions are resolved by consulting the **incoming** tool's {@link @nhtio/adk!Tool.onCollision} first:
-	*
-	* - `'replace'` (per-tool): the incoming tool wins, replacing the existing entry.
-	* - `'keep'` (per-tool): the existing entry wins; the incoming tool is dropped.
-	* - `'throw'` (per-tool, the default): fall back to the merge-level `options.onCollision`.
-	*
-	* The merge-level `options.onCollision` defaults to `'throw'`, which mirrors {@link register}.
-	*
-	* The result is a brand-new registry; no input is mutated and no event subscription is
-	* propagated. Each `Tool`'s `ephemeral` flag carries through unchanged — the flag lives on the
-	* tool, not the registry, so `bindContext(ctx)` on the merged registry will prune the forged
-	* tools as expected.
-	*
-	* Hidden state is also propagated: a tool that is hidden in any source registry remains hidden
-	* in the merged result, provided it survives collision resolution.
+	* @param raw - Raw tool input validated against {@link ArtifactTool.schema}.
 	*
-	* @param registries - Registries to merge, in priority order (left-to-right insertion).
-	* @param options - Merge-level collision policy. Defaults to `{ onCollision: 'throw' }`.
-	* @returns A fresh {@link ToolRegistry} containing the resolved union of all inputs.
-	* @throws {@link @nhtio/adk!E_TOOL_ALREADY_REGISTERED} when the resolved collision policy is `'throw'`
-	*   and a collision occurs.
+	* @throws {@link @nhtio/adk!E_INVALID_INITIAL_TOOL_VALUE} when `raw` does not satisfy
+	*   {@link ArtifactTool.schema} (most commonly, when `artifactConstructor` is supplied — it is
+	*   explicitly forbidden on this class) or when the base {@link @nhtio/adk!Tool} constructor rejects the
+	*   input for any reason.
 	*/
-	static merge(registries, options) {
-		const policy = options?.onCollision ?? "throw";
-		const merged = new ToolRegistry();
-		for (const registry of registries) {
-			for (const tool of registry.all()) {
-				if (!merged.get(tool.name)) {
-					merged.register(tool);
-					continue;
-				}
-				const incomingPolicy = tool.onCollision;
-				if (incomingPolicy === "replace") {
-					merged.register(tool, true);
-					continue;
-				}
-				if (incomingPolicy === "keep") continue;
-				if (policy === "replace") {
-					merged.register(tool, true);
-					continue;
-				}
-				if (policy === "keep") continue;
-				throw new require_tokenizable.E_TOOL_ALREADY_REGISTERED();
-			}
-			for (const tool of registry.hidden()) if (merged.has(tool.name)) merged.hide(tool.name);
+	constructor(raw) {
+		try {
+			require_exceptions.validateOrThrow(rawArtifactToolSchema, raw, true);
+		} catch (err) {
+			if (require_guards.isInstanceOf(err, "ValidationException", require_exceptions.ValidationException)) throw new require_tokenizable.E_INVALID_INITIAL_TOOL_VALUE({ cause: err });
+			throw err;
 		}
-		return merged;
+		super(raw);
 	}
 	/**
-	* Serialise this ToolRegistry into an `@nhtio/encoder` snapshot.
+	* Serialise this ArtifactTool into an `@nhtio/encoder` snapshot.
 	*
 	* @remarks
-	* Emits the live {@link @nhtio/adk!Tool} instances (the encoder recurses into each — so every tool's
-	* handler-closure caveat from {@link Tool.[ENCODE_METHOD]} applies) plus the hidden-set names. Both
-	* {@link @nhtio/adk!Tool} and {@link @nhtio/adk!ArtifactTool} entries round-trip to their correct
-	* subtype. Round-trips via {@link ToolRegistry.[DECODE_METHOD]}.
+	* Reuses the base {@link Tool.[ENCODE_METHOD]} (function-serialised `handler`, validation-encoded
+	* `inputSchema`, plain config) and strips `artifactConstructor` — which {@link ArtifactTool.schema}
+	* forbids. The handler's closure caveat from {@link Tool.[ENCODE_METHOD]} applies here too.
 	*
-	* @returns A `{ tools, hidden }` snapshot.
+	* @returns A {@link RawArtifactTool}-shaped snapshot (with `inputSchema` as an encoded string).
 	*/
 	[require_tokenizable.ENCODE_METHOD]() {
-		return {
-			tools: this.all(),
-			hidden: this.hidden().map((tool) => tool.name)
-		};
+		const base = super[require_tokenizable.ENCODE_METHOD]();
+		delete base.artifactConstructor;
+		return base;
 	}
 	/**
-	* Reconstruct a {@link ToolRegistry} from a {@link ToolRegistry.[ENCODE_METHOD]} snapshot.
+	* Reconstruct an {@link ArtifactTool} from an {@link ArtifactTool.[ENCODE_METHOD]} snapshot.
 	*
-	* @param data - The snapshot produced by {@link ToolRegistry.[ENCODE_METHOD]}.
-	* @returns A fresh {@link ToolRegistry} with the same tools and hidden set.
+	* @param data - The snapshot produced by {@link ArtifactTool.[ENCODE_METHOD]}.
+	* @returns A fully-validated {@link ArtifactTool}.
 	*/
 	static [require_tokenizable.DECODE_METHOD](data) {
 		const snapshot = data;
-		const registry = new ToolRegistry(snapshot.tools);
-		registry.setHidden(...snapshot.hidden);
-		return registry;
+		return new ArtifactTool({
+			...snapshot,
+			inputSchema: (0, _nhtio_validation.decode)(snapshot.inputSchema)
+		});
 	}
 };
 //#endregion
@@ -1727,4 +1727,4 @@ Object.defineProperty(exports, "resolveSpoolReader", {
 	}
 });
 
-//# sourceMappingURL=spooled_artifact-BpcesRBv.js.map
+//# sourceMappingURL=spooled_artifact-CFjf6ULg.cjs.map