@nhtio/adk 0.1.0-master-e6c58205 → 0.1.0-master-89b47bec

package/batteries/media.cjs

@@ -1,10 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("../chunk-Cek0wNdY.js");
-const require_tool_registry = require("../tool_registry-BdKlPuHS.js");
+const require_tool_registry = require("../tool_registry-DwZ6pzN4.js");
 require("../guards.cjs");
 const require_batteries_media_contracts = require("./media/contracts.cjs");
 const require_exceptions = require("../exceptions-D79HIKeX.js");
-const require_validate = require("../validate-DgDZkUKs.js");
+const require_validate = require("../validate-gaSa9bsk.js");
+const require_formats = require("../formats-DZVuqZUN.js");
 let _nhtio_validation = require("@nhtio/validation");
 let _nhtio_middleware = require("@nhtio/middleware");
 let moo = require("moo");
@@ -48,7 +49,7 @@ var lexer = moo.default.compile({
 	pipe: "|",
 	eq: "=",
 	comma: ",",
-	ref: /@[A-Za-z0-9_-]+/,
+	ref: /@[A-Za-z0-9:_-]+/,
 	regex: /\/(?:\\.|\[(?:\\.|[^\]\\\n])*\]|[^/\\[\n])+\/[a-z]*/,
 	dstring: /"(?:\\.|[^"\\\n])*"/,
 	sstring: /'(?:\\.|[^'\\\n])*'/,
@@ -87,7 +88,7 @@ var spanOf = (tok, length) => ({
 	length: length ?? tok.text.length
 });
 var unquote = (raw) => raw.slice(1, -1).replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\(["'\\/])/g, "$1");
-var fail$5 = (tok, message, exemplar) => {
+var fail$6 = (tok, message, exemplar) => {
 	throw new require_exceptions.E_MEDIA_PIPE_SYNTAX([`${message}${tok ? ` at line ${tok.line}, col ${tok.col}` : " at end of input"}. Write it like: ${exemplar}`]);
 };
 var Parser = class {
@@ -104,19 +105,19 @@ var Parser = class {
 	}
 	parsePipeline() {
 		const segments = [];
-		if (this.#toks.length === 0) fail$5(void 0, "empty pipe expression", "extract text | chunk by=sentence");
+		if (this.#toks.length === 0) fail$6(void 0, "empty pipe expression", "extract text | chunk by=sentence");
 		segments.push(this.#parseSegment());
 		while (this.#peek()?.type === "pipe") {
 			this.#next();
 			segments.push(this.#parseSegment());
 		}
 		const trailing = this.#peek();
-		if (trailing) fail$5(trailing, `unexpected "${trailing.text}" after a complete segment`, "segment | segment (segments are separated by |)");
+		if (trailing) fail$6(trailing, `unexpected "${trailing.text}" after a complete segment`, "segment | segment (segments are separated by |)");
 		return segments;
 	}
 	#parseSegment() {
 		const first = this.#peek();
-		if (!first || first.type !== "ident") fail$5(first, "expected a verb to start the segment", "convert to=pdf");
+		if (!first || first.type !== "ident") fail$6(first, "expected a verb to start the segment", "convert to=pdf");
 		const head = this.#next();
 		const collected = [head.value];
 		const posAfterWord = [this.#pos];
@@ -139,12 +140,12 @@ var Parser = class {
 		for (;;) {
 			const tok = this.#peek();
 			if (!tok || tok.type === "pipe") break;
-			if (tok.type === "dash") fail$5(tok, "unexpected \"-\" — values containing dashes must be quoted", `${verbText} name="value-with-dashes"`);
-			if (tok.type !== "ident" || this.#peek(1)?.type !== "eq") fail$5(tok, `unexpected "${tok.text}" — args must be name=value`, `${verbText} name=value`);
+			if (tok.type === "dash") fail$6(tok, "unexpected \"-\" — values containing dashes must be quoted", `${verbText} name="value-with-dashes"`);
+			if (tok.type !== "ident" || this.#peek(1)?.type !== "eq") fail$6(tok, `unexpected "${tok.text}" — args must be name=value`, `${verbText} name=value`);
 			const name = this.#next().value;
 			this.#next();
 			const value = this.#parseValue(verbText, name);
-			if (args.has(name)) fail$5(tok, `duplicate arg "${name}"`, `${verbText} ${name}=value (give each arg once)`);
+			if (args.has(name)) fail$6(tok, `duplicate arg "${name}"`, `${verbText} ${name}=value (give each arg once)`);
 			args.set(name, value);
 		}
 		return {
@@ -173,7 +174,7 @@ var Parser = class {
 	}
 	#parseScalar(verbText, argName) {
 		const tok = this.#peek();
-		if (!tok) fail$5(tok, `missing value for "${argName}"`, `${verbText} ${argName}=value`);
+		if (!tok) fail$6(tok, `missing value for "${argName}"`, `${verbText} ${argName}=value`);
 		const t = tok;
 		switch (t.type) {
 			case "int":
@@ -193,7 +194,7 @@ var Parser = class {
 			case "range": {
 				this.#next();
 				const [lo, hi] = t.value.split("-").map(Number);
-				if (lo > hi) fail$5(t, `range ${t.value} is descending (start must be ≤ end)`, `${argName}=${hi}-${lo}`);
+				if (lo > hi) fail$6(t, `range ${t.value} is descending (start must be ≤ end)`, `${argName}=${hi}-${lo}`);
 				const nums = [];
 				for (let n = lo; n <= hi; n++) nums.push(n);
 				return {
@@ -236,7 +237,7 @@ var Parser = class {
 					new RegExp(source, flags);
 				} catch (err) {
 					const detail = require_tool_registry.isError(err) ? err.message : String(err);
-					fail$5(t, `invalid regex ${t.text}: ${detail}`, `${argName}=/pattern/flags`);
+					fail$6(t, `invalid regex ${t.text}: ${detail}`, `${argName}=/pattern/flags`);
 				}
 				return {
 					value: {
@@ -258,9 +259,9 @@ var Parser = class {
 					span: spanOf(t)
 				};
 			case "dash":
-				fail$5(t, "unexpected \"-\" in a bare value", `${argName}="value-with-dashes" (quote values containing dashes)`);
+				fail$6(t, "unexpected \"-\" in a bare value", `${argName}="value-with-dashes" (quote values containing dashes)`);
 				break;
-			default: fail$5(t, `unexpected "${t.text}"`, `${verbText} ${argName}=value`);
+			default: fail$6(t, `unexpected "${t.text}"`, `${verbText} ${argName}=value`);
 		}
 		throw new require_exceptions.E_MEDIA_PIPE_SYNTAX(["internal parser error"]);
 	}
@@ -798,137 +799,255 @@ var materializedName = (filename) => {
 /** Convenience: read a step arg with a typed cast (validation already ran). */
 var argOf = (step, name) => step.args[name];
 //#endregion
-//#region src/batteries/media/formats.ts
-/** Well-known MIME constants used across the battery. */
-var MIME = {
-	DOCX: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-	XLSX: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-	PPTX: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-	ODT: "application/vnd.oasis.opendocument.text",
-	ODS: "application/vnd.oasis.opendocument.spreadsheet",
-	ODP: "application/vnd.oasis.opendocument.presentation",
-	PDF: "application/pdf",
-	DOC: "application/msword",
-	XLS: "application/vnd.ms-excel",
-	PPT: "application/vnd.ms-powerpoint",
-	PAGES: "application/x-iwork-pages-sffpages",
-	NUMBERS: "application/x-iwork-numbers-sffnumbers",
-	KEYNOTE: "application/x-iwork-keynote-sffkey",
-	TXT: "text/plain",
-	MD: "text/markdown",
-	CSV: "text/csv",
-	HTML: "text/html",
-	JSON: "application/json",
-	PNG: "image/png",
-	JPEG: "image/jpeg",
-	WEBP: "image/webp",
-	TIFF: "image/tiff",
-	AVIF: "image/avif",
-	WAV: "audio/wav",
-	MP3: "audio/mpeg"
-};
-/** Legacy Office MIME types (extraction only — mutation is rejected). */
-var LEGACY_OFFICE_MIMES = new Set([
-	MIME.DOC,
-	MIME.XLS,
-	MIME.PPT
-]);
-/** Apple iWork MIME types (extraction only — mutation is rejected). */
-var IWORK_MIMES = new Set([
-	MIME.PAGES,
-	MIME.NUMBERS,
-	MIME.KEYNOTE
-]);
-var SPREADSHEET_MIMES = new Set([
-	MIME.XLSX,
-	MIME.ODS,
-	MIME.XLS,
-	MIME.CSV
-]);
-var PRESENTATION_MIMES = new Set([
-	MIME.PPTX,
-	MIME.ODP,
-	MIME.PPT,
-	MIME.KEYNOTE
-]);
-var DOCUMENT_MIMES = new Set([
-	MIME.PDF,
-	MIME.DOCX,
-	MIME.ODT,
-	MIME.DOC,
-	MIME.PAGES,
-	MIME.TXT,
-	MIME.MD,
-	MIME.HTML,
-	MIME.JSON,
-	"application/rtf",
-	"text/rtf"
-]);
+//#region src/batteries/media/steps/patch.ts
+var PATCH_PREFIX = "*** Begin Patch";
+var PATCH_SUFFIX = "*** End Patch";
+var ADD_FILE_PREFIX = "*** Add File:";
+var DELETE_FILE_PREFIX = "*** Delete File:";
+var UPDATE_FILE_PREFIX = "*** Update File:";
+var MOVE_TO_PREFIX = "*** Move to:";
+/** `true` when `patch` is the structured envelope rather than a unified diff. */
+var isStructuredPatch = (patch) => patch.trimStart().startsWith(PATCH_PREFIX);
+/** Normalize a workspace path: relative, no `.`/`..`/empty segments, forward slashes. */
+var normalizeWorkspacePath = (path) => {
+	const normalized = path.replace(/\\/g, "/").trim();
+	if (!normalized) throw new Error("apply_patch path cannot be empty");
+	if (normalized.startsWith("/") || /^[A-Za-z]:/.test(normalized)) throw new Error(`apply_patch path "${path}" must be relative to the workspace root`);
+	const segments = normalized.split("/");
+	const sanitizedSegments = [];
+	for (const segment of segments) {
+		if (!segment || segment === "." || segment === "..") throw new Error(`apply_patch path "${path}" contains invalid segment "${segment || "(empty)"}"`);
+		sanitizedSegments.push(segment);
+	}
+	return sanitizedSegments.join("/");
+};
 /**
-* Classify a MIME type into the verb table's broad format family.
+* Parse a structured `*** Begin Patch` envelope.
 *
-* @param mimeType - The media MIME type.
-* @returns The family used by verb-applicability checks.
+* @param patch - The raw patch text.
+* @returns The parsed operations.
 */
-var familyOf = (mimeType) => {
-	const mime = mimeType.toLowerCase().split(";")[0].trim();
-	if (SPREADSHEET_MIMES.has(mime)) return "spreadsheet";
-	if (PRESENTATION_MIMES.has(mime)) return "presentation";
-	if (DOCUMENT_MIMES.has(mime)) return "document";
-	if (mime.startsWith("image/")) return "image";
-	if (mime.startsWith("audio/")) return "audio";
-	if (mime.startsWith("text/")) return "document";
-	return "document";
+var parseStructuredPatch = (patch) => {
+	const lines = patch.replace(/\r\n/g, "\n").split("\n");
+	if (lines[0]?.trim() !== PATCH_PREFIX) throw new Error("a structured patch must start with \"*** Begin Patch\"");
+	const lastNonEmptyIndex = [...lines].reverse().findIndex((line) => line.trim() !== "");
+	const endIndex = lastNonEmptyIndex === -1 ? -1 : lines.length - 1 - lastNonEmptyIndex;
+	if (endIndex < 0 || lines[endIndex]?.trim() !== PATCH_SUFFIX) throw new Error("a structured patch must end with \"*** End Patch\"");
+	const body = lines.slice(1, endIndex);
+	const operations = [];
+	let totalAdded = 0;
+	let totalRemoved = 0;
+	let i = 0;
+	while (i < body.length) {
+		const line = body[i] ?? "";
+		if (line.trim() === "" || line.startsWith("*** End of File")) {
+			i += 1;
+			continue;
+		}
+		if (line.startsWith(ADD_FILE_PREFIX)) {
+			const path = normalizeWorkspacePath(line.slice(13).trim());
+			i += 1;
+			const contentLines = [];
+			while (i < body.length) {
+				const next = body[i] ?? "";
+				if (next.startsWith("*** ")) break;
+				if (!next.startsWith("+")) throw new Error(`apply_patch add-file line must start with "+": "${next}"`);
+				contentLines.push(next.slice(1));
+				i += 1;
+			}
+			operations.push({
+				type: "add",
+				path,
+				content: contentLines.join("\n"),
+				added: contentLines.length
+			});
+			totalAdded += contentLines.length;
+			continue;
+		}
+		if (line.startsWith(DELETE_FILE_PREFIX)) {
+			const path = normalizeWorkspacePath(line.slice(16).trim());
+			operations.push({
+				type: "delete",
+				path
+			});
+			i += 1;
+			continue;
+		}
+		if (!line.startsWith(UPDATE_FILE_PREFIX)) throw new Error(`apply_patch invalid structured patch header: "${line}"`);
+		const path = normalizeWorkspacePath(line.slice(16).trim());
+		i += 1;
+		let movePath;
+		if ((body[i] ?? "").startsWith(MOVE_TO_PREFIX)) {
+			movePath = normalizeWorkspacePath((body[i] ?? "").slice(12).trim());
+			i += 1;
+		}
+		const hunks = [];
+		let opAdded = 0;
+		let opRemoved = 0;
+		while (i < body.length && (body[i] ?? "").startsWith("@@")) {
+			i += 1;
+			const hunkLines = [];
+			while (i < body.length) {
+				const next = body[i] ?? "";
+				if (next.startsWith("@@") || next.startsWith("*** ")) break;
+				hunkLines.push(next);
+				i += 1;
+			}
+			if (hunkLines.length === 0) throw new Error("apply_patch contains an empty hunk");
+			const oldLines = [];
+			const newLines = [];
+			let added = 0;
+			let removed = 0;
+			for (const hunkLine of hunkLines) if (hunkLine.startsWith("+")) {
+				newLines.push(hunkLine.slice(1));
+				added += 1;
+			} else if (hunkLine.startsWith("-")) {
+				oldLines.push(hunkLine.slice(1));
+				removed += 1;
+			} else if (hunkLine.startsWith(" ")) {
+				const contextLine = hunkLine.slice(1);
+				oldLines.push(contextLine);
+				newLines.push(contextLine);
+			} else throw new Error(`apply_patch invalid hunk line (must start with +, -, or space): "${hunkLine}"`);
+			if (added === 0 && removed === 0) throw new Error("apply_patch hunk must contain at least one added or removed line");
+			opAdded += added;
+			opRemoved += removed;
+			hunks.push({
+				oldLines,
+				newLines,
+				added,
+				removed
+			});
+		}
+		if (hunks.length === 0) throw new Error(`apply_patch update operation for "${path}" must contain at least one hunk`);
+		operations.push({
+			type: "update",
+			path,
+			movePath,
+			hunks,
+			added: opAdded,
+			removed: opRemoved
+		});
+		totalAdded += opAdded;
+		totalRemoved += opRemoved;
+	}
+	if (operations.length === 0) throw new Error("apply_patch contains no operations");
+	return {
+		operations,
+		added: totalAdded,
+		removed: totalRemoved
+	};
+};
+var countSequenceMatches = (haystack, needle, start) => {
+	if (needle.length === 0) return 0;
+	let matches = 0;
+	let i = start;
+	while (i <= haystack.length - needle.length) {
+		let matched = true;
+		let j = 0;
+		while (j < needle.length) {
+			if (haystack[i + j] !== needle[j]) {
+				matched = false;
+				break;
+			}
+			j += 1;
+		}
+		if (matched) matches += 1;
+		i += 1;
+	}
+	return matches;
+};
+var findExactSequence = (haystack, needle, start) => {
+	if (needle.length === 0) return start;
+	let i = start;
+	while (i <= haystack.length - needle.length) {
+		let matched = true;
+		let j = 0;
+		while (j < needle.length) {
+			if (haystack[i + j] !== needle[j]) {
+				matched = false;
+				break;
+			}
+			j += 1;
+		}
+		if (matched) return i;
+		i += 1;
+	}
+	return -1;
 };
 /**
-* Reason a mutation verb cannot run against this MIME type, or `undefined` when mutation is
-* allowed. Returns a reason string (not a throw) so callers compose model-actionable failures.
+* Apply an update operation's hunks to `inputText`. Context matching is exact and rejects
+* ambiguity: a hunk whose old-lines match more than one location past the cursor fails
+* rather than guessing.
 *
-* @param mimeType - The media MIME type.
-* @returns A human-readable reason, or `undefined` when mutation is supported.
+* @param inputText - The file's current text.
+* @param hunks - The parsed hunks, in order.
+* @returns The patched text.
 */
-var unsupportedForMutationReason = (mimeType) => {
-	const mime = mimeType.toLowerCase().split(";")[0].trim();
-	if (LEGACY_OFFICE_MIMES.has(mime)) return `legacy Office format (${mime}) supports extraction only — convert it first (e.g. convert to=docx)`;
-	if (IWORK_MIMES.has(mime)) return `Apple iWork format (${mime}) supports extraction only`;
-};
-/** A small extension → MIME lookup for filenames produced by transforms. */
-var EXT_TO_MIME = {
-	pdf: MIME.PDF,
-	docx: MIME.DOCX,
-	xlsx: MIME.XLSX,
-	pptx: MIME.PPTX,
-	odt: MIME.ODT,
-	ods: MIME.ODS,
-	odp: MIME.ODP,
-	doc: MIME.DOC,
-	xls: MIME.XLS,
-	ppt: MIME.PPT,
-	txt: MIME.TXT,
-	md: MIME.MD,
-	csv: MIME.CSV,
-	html: MIME.HTML,
-	json: MIME.JSON,
-	rtf: "application/rtf",
-	png: MIME.PNG,
-	jpg: MIME.JPEG,
-	jpeg: MIME.JPEG,
-	webp: MIME.WEBP,
-	tiff: MIME.TIFF,
-	avif: MIME.AVIF,
-	wav: MIME.WAV,
-	mp3: MIME.MP3
+var applyUpdateHunks = (inputText, hunks) => {
+	const lines = inputText.replace(/\r\n/g, "\n").split("\n");
+	let cursor = 0;
+	for (const hunk of hunks) {
+		if (countSequenceMatches(lines, hunk.oldLines, cursor) > 1) throw new Error("patch context is ambiguous and matches multiple locations");
+		const start = findExactSequence(lines, hunk.oldLines, cursor);
+		if (start === -1) throw new Error("the patch could not be applied cleanly to the source text");
+		lines.splice(start, hunk.oldLines.length, ...hunk.newLines);
+		cursor = start + hunk.newLines.length;
+	}
+	return lines.join("\n");
 };
 /**
-* Replace (or add) a filename's extension.
+* Apply a parsed structured patch to a virtual workspace of files keyed by normalized path.
 *
-* @param filename - The original filename.
-* @param ext - The new extension, without the dot.
-* @returns The filename with the new extension.
+* @param files - The workspace (mutated in place).
+* @param patch - The parsed envelope.
+* @returns The workspace and the number of files touched.
 */
-var replaceExtension = (filename, ext) => {
-	const dot = filename.lastIndexOf(".");
-	return `${dot > 0 ? filename.slice(0, dot) : filename}.${ext}`;
+var applyOperations = (files, patch) => {
+	let modifiedFiles = 0;
+	for (const operation of patch.operations) {
+		if (operation.type === "add") {
+			if (files.has(operation.path)) throw new Error(`cannot add file "${operation.path}": the path already exists`);
+			files.set(operation.path, {
+				text: operation.content,
+				mimeType: inferTextMimeFromPath(operation.path)
+			});
+			modifiedFiles += 1;
+			continue;
+		}
+		if (operation.type === "delete") {
+			if (!files.has(operation.path)) throw new Error(`cannot delete file "${operation.path}": the path does not exist`);
+			files.delete(operation.path);
+			modifiedFiles += 1;
+			continue;
+		}
+		const current = files.get(operation.path);
+		if (!current) throw new Error(`cannot update file "${operation.path}": the path does not exist`);
+		const updatedText = applyUpdateHunks(current.text, operation.hunks);
+		const targetPath = operation.movePath ?? operation.path;
+		if (operation.movePath && files.has(targetPath)) throw new Error(`cannot move file "${operation.path}" to "${targetPath}": the target already exists`);
+		files.delete(operation.path);
+		files.set(targetPath, {
+			text: updatedText,
+			mimeType: current.mimeType
+		});
+		modifiedFiles += 1;
+	}
+	return {
+		files,
+		modifiedFiles
+	};
+};
+/** Infer a text MIME from a workspace path's extension (Add File outputs). */
+var inferTextMimeFromPath = (path) => {
+	const dot = path.lastIndexOf(".");
+	const ext = dot > 0 ? path.slice(dot + 1).toLowerCase() : "";
+	if (ext === "json") return "application/json";
+	if (ext === "md" || ext === "markdown") return "text/markdown";
+	if (ext === "csv") return "text/csv";
+	if (ext === "yaml" || ext === "yml") return "application/yaml";
+	if (ext === "html" || ext === "htm") return "text/html";
+	return "text/plain";
 };
 //#endregion
 //#region src/batteries/media/steps/text.ts
@@ -999,20 +1118,20 @@ var splitFixed = (text, chunkSize, overlap) => {
 	}
 	return chunks;
 };
-var decoder = new TextDecoder("utf-8", { fatal: false });
-var encoder = new TextEncoder();
+var decoder$1 = new TextDecoder("utf-8", { fatal: false });
+var encoder$1 = new TextEncoder();
 /** Decode payload bytes as UTF-8 text (UTF-16 BOM aware). */
 var decodeText = (bytes) => {
 	if (bytes.length >= 2) {
 		if (bytes[0] === 255 && bytes[1] === 254) return new TextDecoder("utf-16le").decode(bytes.subarray(2));
 		if (bytes[0] === 254 && bytes[1] === 255) return new TextDecoder("utf-16be").decode(bytes.subarray(2));
 	}
-	return decoder.decode(bytes).replace(/\r\n?/g, "\n");
+	return decoder$1.decode(bytes).replace(/\r\n?/g, "\n");
 };
 var textPayload = (source, text, suffix) => ({
-	bytes: encoder.encode(text),
-	mimeType: MIME.TXT,
-	filename: replaceExtension(source.filename, suffix)
+	bytes: encoder$1.encode(text),
+	mimeType: require_formats.MIME.TXT,
+	filename: require_formats.replaceExtension(source.filename, suffix)
 });
 /** `chunk` — split text content into retrieval chunks (data result). */
 var chunkStep = async (ctx) => {
@@ -1033,9 +1152,9 @@ var chunkStep = async (ctx) => {
 * clear reason.
 */
 var extractTextStep = async (ctx) => {
-	const family = familyOf(ctx.payload.mimeType);
+	const family = require_formats.familyOf(ctx.payload.mimeType);
 	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
-	if (!(mime.startsWith("text/") || mime === MIME.JSON || mime === MIME.MD || mime === MIME.CSV)) throw new require_exceptions.E_MEDIA_STEP_FAILED(["extract.text", `extraction for ${family} media (${mime}) is not yet implemented in this build`]);
+	if (!(mime.startsWith("text/") || mime === require_formats.MIME.JSON || mime === require_formats.MIME.MD || mime === require_formats.MIME.CSV)) throw new require_exceptions.E_MEDIA_STEP_FAILED(["extract.text", `extraction for ${family} media (${mime}) is not yet implemented in this build`]);
 	const text = decodeText(ctx.payload.bytes);
 	return {
 		kind: "data",
@@ -1049,7 +1168,7 @@ var extractMetadataStep = async (ctx) => {
 		filename: ctx.payload.filename,
 		mime_type: ctx.payload.mimeType,
 		size_bytes: ctx.payload.bytes.byteLength,
-		family: familyOf(ctx.payload.mimeType)
+		family: require_formats.familyOf(ctx.payload.mimeType)
 	};
 	return {
 		kind: "data",
@@ -1094,7 +1213,7 @@ var updateTextStep = async (ctx) => {
 		kind: "media",
 		payload: {
 			...ctx.payload,
-			bytes: encoder.encode(updated)
+			bytes: encoder$1.encode(updated)
 		}
 	};
 };
@@ -1124,9 +1243,13 @@ var diffStep = async (ctx) => {
 		asText: patch
 	};
 };
-/** `apply_patch` — apply a unified diff to the media text. */
+/**
+* `apply_patch` — apply a unified diff, or a structured `*** Begin Patch` envelope
+* (multi-file Add/Delete/Update/Move — the GitHub Copilot apply_patch dialect).
+*/
 var applyPatchStep = async (ctx) => {
 	const patch = argOf(ctx.step, "patch");
+	if (isStructuredPatch(patch)) return applyStructuredPatch(ctx, patch);
 	const text = decodeText(ctx.payload.bytes);
 	const result = (await import("diff")).applyPatch(text, patch);
 	if (result === false) throw new require_exceptions.E_MEDIA_STEP_FAILED(["apply_patch", "the patch does not apply to this media content (context mismatch)"]);
@@ -1134,30 +1257,86 @@ var applyPatchStep = async (ctx) => {
 		kind: "media",
 		payload: {
 			...ctx.payload,
-			bytes: encoder.encode(result)
+			bytes: encoder$1.encode(result)
 		}
 	};
 };
+/** The structured-envelope path: primary media + `with=@refs` form a virtual workspace. */
+var applyStructuredPatch = async (ctx, patch) => {
+	const verb = "apply_patch";
+	const fail = (message) => {
+		throw new require_exceptions.E_MEDIA_STEP_FAILED([verb, message]);
+	};
+	const files = /* @__PURE__ */ new Map();
+	const addToWorkspace = (payload) => {
+		let path;
+		try {
+			path = normalizeWorkspacePath(payload.filename);
+		} catch (err) {
+			fail(require_tool_registry.isError(err) ? err.message : String(err));
+			throw err;
+		}
+		if (files.has(path)) fail(`duplicate workspace path in inputs: "${path}"`);
+		files.set(path, {
+			text: decodeText(payload.bytes),
+			mimeType: payload.mimeType
+		});
+	};
+	addToWorkspace(ctx.payload);
+	const raw = ctx.step.args.with;
+	if (raw !== void 0) {
+		const refs = Array.isArray(raw) ? raw : [raw];
+		for (const ref of refs) {
+			if (ref.kind !== "id") fail("builder refs are not yet supported here");
+			addToWorkspace(await ctx.resolveRef(ref.id));
+		}
+	}
+	let parsed;
+	let applied;
+	try {
+		parsed = parseStructuredPatch(patch);
+		applied = applyOperations(files, parsed);
+	} catch (err) {
+		fail(require_tool_registry.isError(err) ? err.message : String(err));
+		throw err;
+	}
+	const payloads = [...applied.files.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([path, file]) => ({
+		bytes: encoder$1.encode(file.text),
+		mimeType: file.mimeType,
+		filename: path
+	}));
+	if (payloads.length === 0) fail("the patch deleted every file in the workspace");
+	if (payloads.length === 1) return {
+		kind: "media",
+		payload: payloads[0]
+	};
+	return {
+		kind: "media-list",
+		payloads
+	};
+};
 //#endregion
 //#region src/batteries/media/steps/doc.ts
 /**
-* Doc-domain step extensions: format-preserving text mutation for DOCX/PPTX, asset
-* extraction from OOXML/ODF archives and PDFs, and format conversion via the convert engine.
+* Doc-domain step extensions: format-preserving text mutation for DOCX/PPTX/ODF, PDF visual
+* redaction, asset extraction from OOXML/ODF archives and PDFs, and format conversion via the
+* convert engine.
 *
 * @remarks
 * Internal sibling of the `@nhtio/adk/batteries/media` entry. Ported from the source server's
 * doc adapters; the format-dispatch contract follows the server's green e2e suite: DOCX and
 * PPTX redact/sanitize/normalize/update_text mutate text in place inside the container
-* (preserving the source format); text-like inputs mutate as text; PDF redact falls back to
-* text extraction (the server's PDF "visual annotation" path is content-stream-preserving and
-* out of scope here — the failure message says exactly that).
+* (preserving the source format); ODT/ODS/ODP redact/update_text mutate `content.xml` the
+* same way; text-like inputs mutate as text. PDF redact is VISUAL (pdf-lib draw-over +
+* metadata strip — content streams keep the text); the result carries that warning verbatim
+* because it is a trust boundary, not a footnote.
 */
 var zipPromise$2;
 var jszip$2 = () => {
 	zipPromise$2 ??= import("jszip").then((m) => "default" in m ? m.default : m);
 	return zipPromise$2;
 };
-var fail$4 = (verb, message) => {
+var fail$5 = (verb, message) => {
 	throw new require_exceptions.E_MEDIA_STEP_FAILED([verb, message]);
 };
 var escapeXml$1 = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
@@ -1203,17 +1382,17 @@ var replaceInOoxml = (xml, paragraphTag, textTag, pattern, replacement) => {
 };
 /** Map text-node mutation over every relevant part of a DOCX or PPTX archive. */
 var mutateOoxmlText = async (ctx, verb, mutateXml) => {
-	const kind = ctx.payload.mimeType.toLowerCase().split(";")[0].trim() === MIME.DOCX ? "docx" : "pptx";
+	const kind = ctx.payload.mimeType.toLowerCase().split(";")[0].trim() === require_formats.MIME.DOCX ? "docx" : "pptx";
 	const JSZip = await jszip$2();
 	let zip;
 	try {
 		zip = await JSZip.loadAsync(ctx.payload.bytes);
 	} catch (err) {
-		fail$4(verb, `could not open the document container: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
+		fail$5(verb, `could not open the document container: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
 		throw err;
 	}
 	const parts = kind === "docx" ? Object.keys(zip.files).filter((n) => /^word\/(document|header\d*|footer\d*)\.xml$/.test(n)) : Object.keys(zip.files).filter((n) => /^ppt\/slides\/slide\d+\.xml$/.test(n));
-	if (parts.length === 0) fail$4(verb, "the container has no text parts to mutate (corrupt file?)");
+	if (parts.length === 0) fail$5(verb, "the container has no text parts to mutate (corrupt file?)");
 	for (const part of parts) {
 		const xml = await zip.file(part).async("text");
 		const next = mutateXml(xml, kind);
@@ -1239,21 +1418,170 @@ var toGlobalRegex = (value) => {
 	const ref = value;
 	return new RegExp(ref.source, ref.flags.includes("g") ? ref.flags : `${ref.flags}g`);
 };
-/** `redact` — format dispatch: text media → text path; DOCX/PPTX → in-place container edit. */
+var ODF_MIMES = new Set([
+	require_formats.MIME.ODT,
+	require_formats.MIME.ODS,
+	require_formats.MIME.ODP
+]);
+/**
+* Replace matches inside the text nodes of ODF `content.xml`, aggregating per paragraph so
+* patterns spanning `<text:span>` formatting splits still match.
+*/
+var replaceTextInContentXml = (xml, pattern, replacement) => {
+	let totalMatches = 0;
+	return {
+		xml: xml.replace(/<text:(?:p|h)\b[^>]*>[\s\S]*?<\/text:(?:p|h)>/g, (paragraphXml) => {
+			const textNodes = [];
+			const textRegex = />([^<]+)</g;
+			let match;
+			while (match = textRegex.exec(paragraphXml)) {
+				const content = unescapeXml(match[1]);
+				if (content.trim() === "") continue;
+				textNodes.push({
+					content,
+					start: match.index,
+					end: match.index + match[0].length
+				});
+			}
+			if (textNodes.length === 0) return paragraphXml;
+			const aggregated = textNodes.map((n) => n.content).join("");
+			const p = new RegExp(pattern.source, pattern.flags);
+			const replaced = aggregated.replace(p, replacement);
+			if (replaced === aggregated) return paragraphXml;
+			const counter = new RegExp(pattern.source, pattern.flags);
+			while (counter.exec(aggregated)) {
+				totalMatches += 1;
+				if (!counter.global) break;
+			}
+			let out = paragraphXml;
+			for (let i = textNodes.length - 1; i >= 0; i--) {
+				const node = textNodes[i];
+				const newContent = i === 0 ? escapeXml$1(replaced) : "";
+				out = out.slice(0, node.start) + `>${newContent}<` + out.slice(node.end);
+			}
+			return out;
+		}),
+		matchCount: totalMatches
+	};
+};
+/** Map a `content.xml` mutation over an ODF container (ODT/ODS/ODP). */
+var mutateOdfText = async (ctx, verb, mutateXml) => {
+	const JSZip = await jszip$2();
+	let zip;
+	try {
+		zip = await JSZip.loadAsync(ctx.payload.bytes);
+	} catch (err) {
+		fail$5(verb, `could not open the document container: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
+		throw err;
+	}
+	const part = zip.file("content.xml");
+	if (!part) fail$5(verb, "the ODF container has no content.xml (corrupt file?)");
+	const xml = await part.async("text");
+	const next = mutateXml(xml);
+	if (next !== xml) zip.file("content.xml", next);
+	const bytes = await zip.generateAsync({
+		type: "uint8array",
+		compression: "DEFLATE"
+	});
+	return {
+		kind: "media",
+		payload: {
+			...ctx.payload,
+			bytes
+		}
+	};
+};
+/** Visual page-level redaction: draw-over banner on matching pages + metadata strip. */
+var redactPdf = async (ctx, verb, patterns) => {
+	const { PDFDocument, PDFName, PDFString, rgb, StandardFonts } = await import("pdf-lib");
+	let doc;
+	try {
+		doc = await PDFDocument.load(ctx.payload.bytes, { ignoreEncryption: true });
+	} catch (err) {
+		fail$5(verb, `could not parse the PDF: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
+		throw err;
+	}
+	let pageTexts = [];
+	try {
+		const { PDFParse } = await import("pdf-parse");
+		pageTexts = (await new PDFParse({ data: ctx.payload.bytes }).getText()).pages.map((p) => p.text ?? "");
+	} catch {
+		pageTexts = [];
+	}
+	const pages = doc.getPages();
+	const font = await doc.embedFont(StandardFonts.Helvetica);
+	let pagesRedacted = 0;
+	for (const [i, page] of pages.entries()) {
+		const pageText = pageTexts[i] ?? "";
+		if (!patterns.some((pattern) => new RegExp(pattern.source, pattern.flags).test(pageText))) continue;
+		const { width } = page.getSize();
+		page.drawRectangle({
+			x: 0,
+			y: 0,
+			width,
+			height: 14,
+			color: rgb(1, 1, .9)
+		});
+		page.drawText(`[Page ${i + 1}: content redacted]`, {
+			x: 4,
+			y: 2,
+			size: 8,
+			font,
+			color: rgb(.5, 0, 0)
+		});
+		pagesRedacted += 1;
+	}
+	for (const field of [
+		"Title",
+		"Author",
+		"Subject",
+		"Keywords",
+		"Creator",
+		"Producer"
+	]) try {
+		const infoDict = doc.context.lookup(doc.context.trailerInfo.Info);
+		if (infoDict && typeof infoDict.get === "function" && typeof infoDict.set === "function") {
+			if (infoDict.get(PDFName.of(field))) infoDict.set(PDFName.of(field), PDFString.of(""));
+		}
+	} catch {}
+	try {
+		const catalog = doc.context.lookup(doc.context.trailerInfo.Root);
+		if (catalog && typeof catalog.get === "function" && typeof catalog.delete === "function") {
+			if (catalog.get(PDFName.of("Metadata"))) catalog.delete(PDFName.of("Metadata"));
+		}
+	} catch {}
+	if (pagesRedacted === 0) fail$5(verb, "no page text matched the redaction pattern(s) — nothing was redacted");
+	const bytes = new Uint8Array(await doc.save());
+	return {
+		kind: "media",
+		payload: {
+			...ctx.payload,
+			bytes
+		}
+	};
+};
+/**
+* `redact` — format dispatch: text media → text path; DOCX/PPTX/ODF → in-place container
+* edit; PDF → visual redaction (draw-over + metadata strip — see {@link PDF_REDACTION_WARNING}).
+*/
 var docRedactStep = async (ctx) => {
 	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
 	if (mime.startsWith("text/")) return redactStep(ctx);
-	if (mime === MIME.DOCX || mime === MIME.PPTX) {
-		const raw = ctx.step.args.match;
-		const patterns = Array.isArray(raw) ? raw : [raw];
-		const replacement = argOf(ctx.step, "replace") ?? "█";
-		return mutateOoxmlText(ctx, "redact", (xml, kind) => {
-			let out = xml;
-			for (const p of patterns) out = replaceInOoxml(out, kind === "docx" ? "w:p" : "a:p", kind === "docx" ? "w:t" : "a:t", toGlobalRegex(p), replacement).xml;
-			return out;
-		});
-	}
-	fail$4("redact", `redaction for ${mime} is not supported in this build (text, DOCX, and PPTX are). For PDF, extract the text first: extract text | redact …`);
+	const raw = ctx.step.args.match;
+	const patterns = Array.isArray(raw) ? raw : [raw];
+	const replacement = argOf(ctx.step, "replace") ?? "█";
+	if (mime === require_formats.MIME.DOCX || mime === require_formats.MIME.PPTX) return mutateOoxmlText(ctx, "redact", (xml, kind) => {
+		let out = xml;
+		for (const p of patterns) out = replaceInOoxml(out, kind === "docx" ? "w:p" : "a:p", kind === "docx" ? "w:t" : "a:t", toGlobalRegex(p), replacement).xml;
+		return out;
+	});
+	if (ODF_MIMES.has(mime)) return mutateOdfText(ctx, "redact", (xml) => {
+		let out = xml;
+		for (const p of patterns) out = replaceTextInContentXml(out, toGlobalRegex(p), replacement).xml;
+		return out;
+	});
+	if (mime === require_formats.MIME.PDF) return redactPdf(ctx, "redact", patterns.map(toGlobalRegex));
+	fail$5("redact", `redaction for ${mime} is not supported in this build (text, DOCX, PPTX, ODT/ODS/ODP, and PDF are).`);
 	throw new Error("unreachable");
 };
 var BLOCKED_CONTROL = (code) => code >= 0 && code <= 8 || code === 11 || code === 12 || code >= 14 && code <= 31 || code === 127;
@@ -1283,8 +1611,8 @@ var docSanitizeStep = async (ctx) => {
 			}
 		};
 	}
-	if (mime === MIME.DOCX || mime === MIME.PPTX) return mutateOoxmlText(ctx, "sanitize", (xml, kind) => sanitizeTextNodes(xml, kind === "docx" ? "w:t" : "a:t"));
-	fail$4("sanitize", `sanitize for ${mime} is not supported in this build (text, DOCX, PPTX are)`);
+	if (mime === require_formats.MIME.DOCX || mime === require_formats.MIME.PPTX) return mutateOoxmlText(ctx, "sanitize", (xml, kind) => sanitizeTextNodes(xml, kind === "docx" ? "w:t" : "a:t"));
+	fail$5("sanitize", `sanitize for ${mime} is not supported in this build (text, DOCX, PPTX are)`);
 	throw new Error("unreachable");
 };
 var normalizeText = (text) => text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/[\t ]+$/gm, "");
@@ -1301,7 +1629,7 @@ var docNormalizeStep = async (ctx) => {
 			}
 		};
 	}
-	if (mime === MIME.DOCX || mime === MIME.PPTX) return mutateOoxmlText(ctx, "normalize", (xml, kind) => {
+	if (mime === require_formats.MIME.DOCX || mime === require_formats.MIME.PPTX) return mutateOoxmlText(ctx, "normalize", (xml, kind) => {
 		const tag = kind === "docx" ? "w:t" : "a:t";
 		return xml.replace(new RegExp(`<${tag}(?:\\s[^>]*)?>([^<]*)</${tag}>`, "g"), (full, content) => {
 			const normalized = normalizeText(unescapeXml(content));
@@ -1309,28 +1637,38 @@ var docNormalizeStep = async (ctx) => {
 			return full.replace(content, escapeXml$1(normalized));
 		});
 	});
-	fail$4("normalize", `normalize for ${mime} is not supported in this build (text, DOCX, PPTX are)`);
+	fail$5("normalize", `normalize for ${mime} is not supported in this build (text, DOCX, PPTX are)`);
 	throw new Error("unreachable");
 };
-/** `update_text` — anchor replacement; DOCX/PPTX in-place, TARGET_NOT_FOUND when absent. */
+/** `update_text` — anchor replacement; DOCX/PPTX/ODF in-place, TARGET_NOT_FOUND when absent. */
 var docUpdateTextStep = async (ctx) => {
 	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
 	if (mime.startsWith("text/")) return updateTextStep(ctx);
-	if (mime === MIME.DOCX || mime === MIME.PPTX) {
-		const anchor = argOf(ctx.step, "anchor");
-		const replace = argOf(ctx.step, "replace") ?? "";
+	const anchor = argOf(ctx.step, "anchor");
+	const replace = argOf(ctx.step, "replace") ?? "";
+	const escapedAnchor = anchor.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	if (mime === require_formats.MIME.DOCX || mime === require_formats.MIME.PPTX) {
 		let found = 0;
 		const result = await mutateOoxmlText(ctx, "update_text", (xml, kind) => {
 			if (found > 0) return xml;
-			const escaped = anchor.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-			const { xml: next, matchCount } = replaceInOoxml(xml, kind === "docx" ? "w:p" : "a:p", kind === "docx" ? "w:t" : "a:t", new RegExp(escaped), replace);
+			const { xml: next, matchCount } = replaceInOoxml(xml, kind === "docx" ? "w:p" : "a:p", kind === "docx" ? "w:t" : "a:t", new RegExp(escapedAnchor), replace);
 			found += matchCount;
 			return next;
 		});
-		if (found === 0) fail$4("update_text", `anchor text not found: "${anchor.slice(0, 80)}"`);
+		if (found === 0) fail$5("update_text", `anchor text not found: "${anchor.slice(0, 80)}"`);
 		return result;
 	}
-	fail$4("update_text", `text update for ${mime} is not supported (text, DOCX, PPTX are; PDF text is not reliably editable)`);
+	if (ODF_MIMES.has(mime)) {
+		let found = 0;
+		const result = await mutateOdfText(ctx, "update_text", (xml) => {
+			const { xml: next, matchCount } = replaceTextInContentXml(xml, new RegExp(escapedAnchor), replace);
+			found += matchCount;
+			return next;
+		});
+		if (found === 0) fail$5("update_text", `anchor text not found: "${anchor.slice(0, 80)}"`);
+		return result;
+	}
+	fail$5("update_text", `text update for ${mime} is not supported (text, DOCX, PPTX, ODT/ODS/ODP are; PDF text is not reliably editable)`);
 	throw new Error("unreachable");
 };
 var ASSET_PATTERNS = {
@@ -1365,9 +1703,9 @@ var extractAssetsStep = async (ctx) => {
 	const requested = ctx.step.args.types ?? ["all"];
 	const wantAll = requested.includes("all");
 	const want = (kind) => wantAll || requested.includes(kind);
-	if (mime === MIME.PDF) {
-		if (!want("image")) fail$4(verb, "PDF asset extraction currently supports images (types=image or all)");
-		if (!ctx.engines.hasConvert(mime, "images")) fail$4(verb, "PDF asset extraction requires an engine that converts application/pdf to \"images\", and none is configured. Do not retry this verb on PDFs in this deployment.");
+	if (mime === require_formats.MIME.PDF) {
+		if (!want("image")) fail$5(verb, "PDF asset extraction currently supports images (types=image or all)");
+		if (!ctx.engines.hasConvert(mime, "images")) fail$5(verb, "PDF asset extraction requires an engine that converts application/pdf to \"images\", and none is configured. Do not retry this verb on PDFs in this deployment.");
 		const format = argOf(ctx.step, "format");
 		const result = await ctx.engines.convert({
 			bytes: ctx.payload.bytes,
@@ -1377,7 +1715,7 @@ var extractAssetsStep = async (ctx) => {
 			options: format ? { format } : void 0,
 			signal: ctx.signal
 		});
-		if (result.outputs.length === 0) fail$4(verb, "no embedded images were found in the PDF");
+		if (result.outputs.length === 0) fail$5(verb, "no embedded images were found in the PDF");
 		const wantedMime = format ? EXT_MIME[format] ?? `image/${format}` : void 0;
 		const payloads = [];
 		for (const [i, img] of result.outputs.entries()) {
@@ -1405,13 +1743,13 @@ var extractAssetsStep = async (ctx) => {
 		};
 	}
 	if (![
-		MIME.DOCX,
-		MIME.XLSX,
-		MIME.PPTX,
-		MIME.ODT,
-		MIME.ODS,
-		MIME.ODP
-	].includes(mime)) fail$4(verb, `asset extraction for ${mime} is not supported (OOXML/ODF archives and PDF are)`);
+		require_formats.MIME.DOCX,
+		require_formats.MIME.XLSX,
+		require_formats.MIME.PPTX,
+		require_formats.MIME.ODT,
+		require_formats.MIME.ODS,
+		require_formats.MIME.ODP
+	].includes(mime)) fail$5(verb, `asset extraction for ${mime} is not supported (OOXML/ODF archives and PDF are)`);
 	const zip = await (await jszip$2()).loadAsync(ctx.payload.bytes);
 	const payloads = [];
 	for (const [name, entry] of Object.entries(zip.files)) {
@@ -1427,7 +1765,7 @@ var extractAssetsStep = async (ctx) => {
 			filename: basename
 		});
 	}
-	if (payloads.length === 0) fail$4(verb, "no embedded assets matched the requested types");
+	if (payloads.length === 0) fail$5(verb, "no embedded assets matched the requested types");
 	return {
 		kind: "media-list",
 		payloads
@@ -1438,7 +1776,7 @@ var convertStep = async (ctx) => {
 	const verb = "convert";
 	const to = argOf(ctx.step, "to");
 	const supported = ctx.engines.convertTargets(ctx.payload.mimeType);
-	if (!supported.includes(to)) fail$4(verb, `no configured engine (or computed path) can produce "${to}" from ${ctx.payload.mimeType}; reachable targets: ${supported.join(", ") || "(none)"}`);
+	if (!supported.includes(to)) fail$5(verb, `no configured engine (or computed path) can produce "${to}" from ${ctx.payload.mimeType}; reachable targets: ${supported.join(", ") || "(none)"}`);
 	const output = (await ctx.engines.convert({
 		bytes: ctx.payload.bytes,
 		mimeType: ctx.payload.mimeType,
@@ -1446,7 +1784,7 @@ var convertStep = async (ctx) => {
 		to,
 		signal: ctx.signal
 	})).outputs[0];
-	if (!output) fail$4(verb, "the conversion produced no output");
+	if (!output) fail$5(verb, "the conversion produced no output");
 	const dot = ctx.payload.filename.lastIndexOf(".");
 	const base = dot > 0 ? ctx.payload.filename.slice(0, dot) : ctx.payload.filename;
 	return {
@@ -1468,32 +1806,222 @@ var DOC_STEPS = [
 	["convert", convertStep]
 ];
 //#endregion
-//#region src/batteries/media/steps/sheet.ts
+//#region src/batteries/media/steps/data.ts
 /**
-* `sheet.*` step implementations: ExcelJS workbook mutations on in-memory bytes.
+* `append` and `data.*` step implementations: deterministic text/data mutations on in-memory
+* bytes — append a line, set/merge/delete at a JSON or YAML path.
 *
 * @remarks
-* Internal sibling of the `@nhtio/adk/batteries/media` entry. Ported from the source server's
-* sheet adapters (its green e2e suite informs the spec coverage). All ten mutations operate on
-* xlsx natively via ExcelJS (optional peer, lazily imported); ODS and legacy-xls inputs are
-* normalized to xlsx first through the configured `sheetNormalize` engine, degrading to a
-* readable failure when none is configured. Output is always xlsx.
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. Pure and cross-env: text ops
+* are string concatenation; structured ops parse (JSON natively, YAML via the `js-yaml`
+* dependency), mutate the value tree, and re-serialize **preserving the source format** —
+* `data.set` on a YAML file yields YAML, on a JSON file yields JSON. These are the verbs
+* that make the lossy text family first-class media: `empty:json | data set path=… value=…`
+* is a create-then-populate chain with no engine requirement at all.
 */
-var excelPromise;
-var excel = () => {
-	excelPromise ??= import("exceljs").then((m) => "default" in m ? m.default : m);
-	return excelPromise;
+var fail$4 = (verb, message) => {
+	throw new require_exceptions.E_MEDIA_STEP_FAILED([verb, message]);
+};
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+/** MIME types the text-shaped verbs operate on. */
+var TEXTUAL = (mime) => mime.startsWith("text/") || mime === require_formats.MIME.JSON || mime === require_formats.MIME.YAML;
+/** `append` — append text to text-family media. */
+var appendStep = async (ctx) => {
+	const verb = "append";
+	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
+	if (!TEXTUAL(mime)) fail$4(verb, `append expects text-family media (txt/md/csv/yaml/json-lines); the media is ${mime}`);
+	const text = argOf(ctx.step, "text");
+	const newline = argOf(ctx.step, "newline") ?? true;
+	const current = decoder.decode(ctx.payload.bytes);
+	const next = current + (newline && current.length > 0 && !current.endsWith("\n") ? "\n" : "") + text + (newline ? "\n" : "");
+	return {
+		kind: "media",
+		payload: {
+			...ctx.payload,
+			bytes: encoder.encode(next)
+		}
+	};
+};
+var parseDoc = async (verb, payload) => {
+	const mime = payload.mimeType.toLowerCase().split(";")[0].trim();
+	const text = decoder.decode(payload.bytes);
+	if (mime === require_formats.MIME.JSON) try {
+		return {
+			value: text.trim() === "" ? null : JSON.parse(text),
+			format: "json"
+		};
+	} catch (err) {
+		fail$4(verb, `the media is not valid JSON: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
+	}
+	if (mime === require_formats.MIME.YAML) try {
+		const { load } = await import("js-yaml");
+		return {
+			value: load(text) ?? null,
+			format: "yaml"
+		};
+	} catch (err) {
+		fail$4(verb, `the media is not valid YAML: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
+	}
+	fail$4(verb, `data operations expect JSON or YAML media; the media is ${mime}`);
+	throw new Error("unreachable");
+};
+var serializeDoc = async (doc, payload) => {
+	if (doc.format === "yaml") {
+		const { dump } = await import("js-yaml");
+		return {
+			...payload,
+			bytes: encoder.encode(dump(doc.value))
+		};
+	}
+	return {
+		...payload,
+		bytes: encoder.encode(JSON.stringify(doc.value, null, 2))
+	};
+};
+/** Parse a dot/bracket path (`a.b[2].c`) into segments. */
+var parsePath = (verb, raw) => {
+	if (typeof raw !== "string" || raw.trim() === "") fail$4(verb, "path must be a non-empty string");
+	const segments = [];
+	const re = /([^.[\]]+)|\[(\d+)\]/g;
+	let match;
+	while (match = re.exec(raw)) if (match[2] !== void 0) segments.push(Number(match[2]));
+	else segments.push(match[1]);
+	if (segments.length === 0) fail$4(verb, `could not parse path "${raw}"`);
+	return segments;
+};
+/** Walk to the parent of the path target, creating containers when `create` is set. */
+var walkToParent = (verb, root, segments, create) => {
+	let node = root;
+	for (let i = 0; i < segments.length - 1; i++) {
+		const seg = segments[i];
+		const isIndex = typeof seg === "number";
+		if (node === null || typeof node !== "object") fail$4(verb, `path segment "${String(seg)}" walks through a non-container value`);
+		const container = node;
+		let next = isIndex ? container[seg] : container[seg];
+		if (next === void 0 || next === null) {
+			if (!create) fail$4(verb, `path segment "${String(seg)}" does not exist`);
+			next = typeof segments[i + 1] === "number" ? [] : {};
+			if (isIndex) container[seg] = next;
+			else container[seg] = next;
+		}
+		node = next;
+	}
+	if (node === null || typeof node !== "object") fail$4(verb, "the path target parent is not an object or array");
+	return {
+		parent: node,
+		key: segments[segments.length - 1]
+	};
+};
+/** `data.set` — set a value at a JSON/YAML path, creating intermediate containers. */
+var dataSetStep = async (ctx) => {
+	const verb = "data set";
+	const path = argOf(ctx.step, "path");
+	const rawValue = argOf(ctx.step, "value");
+	if (rawValue === void 0) fail$4(verb, "value is required (JSON-encoded scalar or structure)");
+	let value;
+	try {
+		value = JSON.parse(String(rawValue));
+	} catch {
+		value = String(rawValue);
+	}
+	const doc = await parseDoc(verb, ctx.payload);
+	const segments = parsePath(verb, path);
+	if (doc.value === null || typeof doc.value !== "object") doc.value = typeof segments[0] === "number" ? [] : {};
+	const { parent, key } = walkToParent(verb, doc.value, segments, true);
+	if (Array.isArray(parent)) parent[Number(key)] = value;
+	else parent[String(key)] = value;
+	return {
+		kind: "media",
+		payload: await serializeDoc(doc, ctx.payload)
+	};
 };
+/** Deep merge `fragment` into `target` (objects merge recursively; everything else replaces). */
+var deepMerge = (target, fragment) => {
+	if (target === null || fragment === null || typeof target !== "object" || typeof fragment !== "object" || Array.isArray(target) !== Array.isArray(fragment) || Array.isArray(fragment)) return fragment;
+	const out = { ...target };
+	for (const [k, v] of Object.entries(fragment)) out[k] = k in out ? deepMerge(out[k], v) : v;
+	return out;
+};
+/** `data.merge` — merge a JSON fragment into the document (deep by default). */
+var dataMergeStep = async (ctx) => {
+	const verb = "data merge";
+	const rawFragment = argOf(ctx.step, "fragment");
+	const strategy = argOf(ctx.step, "strategy") ?? "deep";
+	let fragment;
+	try {
+		fragment = JSON.parse(String(rawFragment));
+	} catch (err) {
+		fail$4(verb, `fragment must be valid JSON: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
+	}
+	if (fragment === null || typeof fragment !== "object" || Array.isArray(fragment)) fail$4(verb, "fragment must be a JSON object");
+	const doc = await parseDoc(verb, ctx.payload);
+	if (doc.value === null || typeof doc.value !== "object" || Array.isArray(doc.value)) fail$4(verb, "merge requires the document root to be an object");
+	doc.value = strategy === "shallow" ? {
+		...doc.value,
+		...fragment
+	} : deepMerge(doc.value, fragment);
+	return {
+		kind: "media",
+		payload: await serializeDoc(doc, ctx.payload)
+	};
+};
+/** `data.delete` — remove a key/index at a JSON/YAML path. */
+var dataDeleteStep = async (ctx) => {
+	const verb = "data delete";
+	const path = argOf(ctx.step, "path");
+	const doc = await parseDoc(verb, ctx.payload);
+	const segments = parsePath(verb, path);
+	if (doc.value === null || typeof doc.value !== "object") fail$4(verb, "the document has no structure to delete from");
+	const { parent, key } = walkToParent(verb, doc.value, segments, false);
+	if (Array.isArray(parent)) {
+		const idx = Number(key);
+		if (idx < 0 || idx >= parent.length) fail$4(verb, `index ${idx} is out of range`);
+		parent.splice(idx, 1);
+	} else {
+		if (!(String(key) in parent)) fail$4(verb, `key "${String(key)}" does not exist at that path`);
+		delete parent[String(key)];
+	}
+	return {
+		kind: "media",
+		payload: await serializeDoc(doc, ctx.payload)
+	};
+};
+/** The data step registry fragment, keyed by canonical verb id. */
+var DATA_STEPS = [
+	["append", appendStep],
+	["data.set", dataSetStep],
+	["data.merge", dataMergeStep],
+	["data.delete", dataDeleteStep]
+];
+//#endregion
+//#region src/batteries/media/steps/sheet.ts
+/**
+* `sheet.*` step implementations: thin dispatchers into the engine registry's edit
+* capability.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. The actual workbook surgery
+* lives in edit-capable engines (`engines/exceljs` preserves styling; `engines/sheetjs`
+* covers the wider read matrix but strips styling — SheetJS CE limitation). Each step here:
+* normalizes non-xlsx spreadsheet inputs to xlsx when the selected edit coverage requires it
+* (any spreadsheet-family MIME with a declared `hasConvert(mime, 'xlsx')` edge qualifies —
+* ODS/XLS via soffice or sheetjs, XLSB/FODS/SYLK/DIF/DBF/NUMBERS via sheetjs), dispatches the
+* op through `ctx.engines.edit`, and degrades to a model-actionable failure when no edit
+* engine is configured.
+*/
 var fail$3 = (verb, message) => {
 	throw new require_exceptions.E_MEDIA_STEP_FAILED([verb, message]);
 };
-/** Acquire xlsx bytes for the step, converting ODS/xls to xlsx via the engine registry. */
-var acquireXlsx = async (ctx, verb) => {
+/** Acquire bytes the edit dispatch can work on, normalizing to xlsx when necessary. */
+var acquireEditable = async (ctx, verb) => {
 	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
-	if (mime === MIME.XLSX) return ctx.payload.bytes;
-	const mutationBlock = unsupportedForMutationReason(mime);
-	if (mime === MIME.ODS || mime === MIME.XLS) {
-		if (!ctx.engines.hasConvert(mime, "xlsx")) fail$3(verb, `this input is ${mime} — an engine that converts it to xlsx is required first, and none is configured. Do not retry this verb on this media in this deployment.`);
+	if (ctx.engines.hasEdit?.(mime)) return {
+		bytes: ctx.payload.bytes,
+		mimeType: mime
+	};
+	if (require_formats.SPREADSHEET_MIMES.has(mime) && mime !== require_formats.MIME.XLSX) {
+		if (!ctx.engines.hasConvert(mime, "xlsx")) fail$3(verb, require_formats.unsupportedForMutationReason(mime) ?? `this input is ${mime} — an engine that converts it to xlsx is required first, and none is configured. Do not retry this verb on this media in this deployment.`);
 		const output = (await ctx.engines.convert({
 			bytes: ctx.payload.bytes,
 			mimeType: mime,
@@ -1502,247 +2030,93 @@ var acquireXlsx = async (ctx, verb) => {
 			signal: ctx.signal
 		})).outputs[0];
 		if (!output) fail$3(verb, "normalizing the workbook to xlsx produced no output");
-		return output.bytes;
+		return {
+			bytes: output.bytes,
+			mimeType: require_formats.MIME.XLSX
+		};
 	}
-	if (mutationBlock) fail$3(verb, mutationBlock);
-	fail$3(verb, `sheet operations expect a spreadsheet; the media is ${mime}`);
-	throw new Error("unreachable");
-};
-/** The shared open → mutate → write-back lifecycle every sheet verb uses. */
-var withWorkbook = async (ctx, verb, mutate) => {
-	const xlsxBytes = await acquireXlsx(ctx, verb);
-	const wb = new (await (excel())).Workbook();
-	try {
-		await wb.xlsx.load(xlsxBytes.buffer.slice(xlsxBytes.byteOffset, xlsxBytes.byteOffset + xlsxBytes.byteLength));
-	} catch (err) {
-		fail$3(verb, `could not open the spreadsheet: ${require_tool_registry.isError(err) ? err.message : String(err)}`);
+	if (mime !== require_formats.MIME.XLSX) {
+		const mutationBlock = require_formats.unsupportedForMutationReason(mime);
+		if (mutationBlock) fail$3(verb, mutationBlock);
+		fail$3(verb, `sheet operations expect a spreadsheet; the media is ${mime}`);
 	}
-	await mutate(wb);
 	return {
-		kind: "media",
-		payload: {
-			bytes: new Uint8Array(await wb.xlsx.writeBuffer()),
-			mimeType: MIME.XLSX,
-			filename: replaceExtension(ctx.payload.filename, "xlsx")
-		}
+		bytes: ctx.payload.bytes,
+		mimeType: require_formats.MIME.XLSX
 	};
 };
-/** Resolve the target worksheet from the frozen `sheet=` rule (bare number=index, string=name). */
-var resolveSheet = (verb, wb, sheetArg) => {
-	if (sheetArg === void 0) {
-		const first = wb.worksheets[0];
-		if (!first) fail$3(verb, "the workbook has no worksheets");
-		return first;
+/** Dispatch one `sheet.*` op through the registry's edit capability. */
+var dispatchEdit = async (ctx, verb, op) => {
+	const { bytes, mimeType } = await acquireEditable(ctx, verb);
+	if (!ctx.engines.hasEdit?.(mimeType, op)) fail$3(verb, `no engine that edits spreadsheets is configured — add engines/exceljs (or engines/sheetjs) to the pipeline's engines array. Do not retry this verb in this deployment.`);
+	try {
+		const result = await ctx.engines.edit({
+			bytes,
+			mimeType,
+			op,
+			args: ctx.step.args,
+			signal: ctx.signal
+		});
+		return {
+			kind: "media",
+			payload: {
+				bytes: result.bytes,
+				mimeType: result.mimeType,
+				filename: require_formats.replaceExtension(ctx.payload.filename, "xlsx")
+			}
+		};
+	} catch (err) {
+		if (require_tool_registry.isError(err) && err.name.startsWith("E_MEDIA_")) throw err;
+		fail$3(verb, require_tool_registry.isError(err) ? err.message : String(err));
+		throw err;
 	}
-	if (typeof sheetArg === "number") {
-		const byIndex = wb.worksheets[sheetArg - 1];
-		if (byIndex) return byIndex;
-		if (wb.getWorksheet(String(sheetArg))) fail$3(verb, `no sheet at index ${sheetArg}, but a sheet NAMED "${sheetArg}" exists — quote it: sheet="${sheetArg}"`);
-		fail$3(verb, `sheet index ${sheetArg} is out of range (1-based; the workbook has ${wb.worksheets.length})`);
-	}
-	const ws = wb.getWorksheet(sheetArg);
-	if (!ws) fail$3(verb, `no sheet named "${sheetArg}". Sheets: ${wb.worksheets.map((w) => `"${w.name}"`).join(", ")}`);
-	return ws;
-};
-var columnLetterToNumber = (col) => {
-	let n = 0;
-	for (const ch of col.toUpperCase()) n = n * 26 + (ch.charCodeAt(0) - 64);
-	return n;
-};
-var asCellValue = (verb, value) => {
-	if (value === null) return null;
-	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
-	fail$3(verb, `cell values must be string, number, boolean, or null; got ${typeof value}`);
-	throw new Error("unreachable");
+};
+/** Pre-dispatch arg validation: keep the historical readable failures for malformed args. */
+var requireJsonArray = (verb, value, message) => {
+	if (!Array.isArray(value) || value.length === 0) fail$3(verb, message);
 };
 /** `sheet.add_rows` — insert rows before/after an index, or append. */
 var sheetAddRowsStep = async (ctx) => {
 	const verb = "sheet add_rows";
 	const rows = ctx.step.args.rows;
 	if (!Array.isArray(rows) || rows.length === 0 || !rows.every(Array.isArray)) fail$3(verb, `rows must be a non-empty JSON array of arrays, e.g. rows='[["a",1]]'`);
-	const before = argOf(ctx.step, "before");
-	const after = argOf(ctx.step, "after");
-	return withWorkbook(ctx, verb, (wb) => {
-		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
-		const insertAt = before !== void 0 ? before : after !== void 0 ? after + 1 : ws.rowCount + 1;
-		const cellRows = rows.map((r) => r.map((v) => asCellValue(verb, v)));
-		ws.spliceRows(insertAt, 0, ...cellRows);
-		return { added: cellRows.length };
-	});
+	return dispatchEdit(ctx, verb, "sheet.add_rows");
 };
 /** `sheet.add_columns` — insert columns with headers or full descriptors. */
 var sheetAddColumnsStep = async (ctx) => {
 	const verb = "sheet add_columns";
 	const headers = ctx.step.args.headers;
-	const columns = ctx.step.args.columns ?? headers?.map((header) => ({ header }));
-	if (!Array.isArray(columns) || columns.length === 0) fail$3(verb, `provide headers=a,b or columns='[{"header":"X","values":[1]}]'`);
-	const before = argOf(ctx.step, "before");
-	const after = argOf(ctx.step, "after");
-	return withWorkbook(ctx, verb, (wb) => {
-		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
-		const insertAt = before !== void 0 ? before : after !== void 0 ? after + 1 : ws.columnCount + 1;
-		for (const [i, col] of columns.entries()) {
-			if (typeof col?.header !== "string") fail$3(verb, "every column needs a string header");
-			ws.spliceColumns(insertAt + i, 0, [col.header, ...(col.values ?? []).map((v) => asCellValue(verb, v))]);
-		}
-		return { added: columns.length };
-	});
+	requireJsonArray(verb, ctx.step.args.columns ?? headers, `provide headers=a,b or columns='[{"header":"X","values":[1]}]'`);
+	return dispatchEdit(ctx, verb, "sheet.add_columns");
 };
 /** `sheet.update_cells` — set cells by A1 address or row/col. Leading `=` writes a formula. */
 var sheetUpdateCellsStep = async (ctx) => {
 	const verb = "sheet update_cells";
-	const updates = ctx.step.args.updates;
-	if (!Array.isArray(updates) || updates.length === 0) fail$3(verb, `updates must be a non-empty JSON array, e.g. updates='[{"address":"B2","value":3}]'`);
-	return withWorkbook(ctx, verb, (wb) => {
-		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
-		let modified = 0;
-		for (const raw of updates) {
-			const address = raw.address;
-			const row = raw.row;
-			const col = raw.col;
-			let cell;
-			if (address) cell = ws.getCell(address);
-			else if (row !== void 0 && col !== void 0) cell = typeof col === "string" ? ws.getCell(row, columnLetterToNumber(col)) : ws.getCell(row, col);
-			else {
-				fail$3(verb, "each update needs address, or both row and col");
-				continue;
-			}
-			const value = raw.value;
-			if (typeof value === "string" && value.startsWith("=")) cell.value = { formula: value.slice(1) };
-			else cell.value = asCellValue(verb, value);
-			modified += 1;
-		}
-		return { modified };
-	});
+	requireJsonArray(verb, ctx.step.args.updates, `updates must be a non-empty JSON array, e.g. updates='[{"address":"B2","value":3}]'`);
+	return dispatchEdit(ctx, verb, "sheet.update_cells");
 };
 /** `sheet.delete_rows` — delete 1-based rows (bottom-up so indices stay valid). */
-var sheetDeleteRowsStep = async (ctx) => {
-	const verb = "sheet delete_rows";
-	const rows = ctx.step.args.rows;
-	return withWorkbook(ctx, verb, (wb) => {
-		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
-		for (const r of [...rows].sort((a, b) => b - a)) ws.spliceRows(r, 1);
-		return { removed: rows.length };
-	});
-};
+var sheetDeleteRowsStep = async (ctx) => dispatchEdit(ctx, "sheet delete_rows", "sheet.delete_rows");
 /** `sheet.delete_columns` — delete 1-based columns. */
-var sheetDeleteColumnsStep = async (ctx) => {
-	const verb = "sheet delete_columns";
-	const columns = ctx.step.args.columns;
-	return withWorkbook(ctx, verb, (wb) => {
-		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
-		for (const c of [...columns].sort((a, b) => b - a)) ws.spliceColumns(c, 1);
-		return { removed: columns.length };
-	});
-};
+var sheetDeleteColumnsStep = async (ctx) => dispatchEdit(ctx, "sheet delete_columns", "sheet.delete_columns");
 /** `sheet.rename_sheet` — rename by NAME (the server contract; index targeting is rejected). */
-var sheetRenameSheetStep = async (ctx) => {
-	const verb = "sheet rename_sheet";
-	const sheet = argOf(ctx.step, "sheet");
-	const to = argOf(ctx.step, "to");
-	return withWorkbook(ctx, verb, (wb) => {
-		const ws = wb.getWorksheet(sheet);
-		if (!ws) fail$3(verb, `rename targets a sheet NAME; no sheet named "${sheet}". Sheets: ${wb.worksheets.map((w) => `"${w.name}"`).join(", ")}`);
-		ws.name = to;
-		return { modified: 1 };
-	});
-};
+var sheetRenameSheetStep = async (ctx) => dispatchEdit(ctx, "sheet rename_sheet", "sheet.rename_sheet");
 /** `sheet.add_sheet` — add a worksheet, optionally at a 1-based position. */
-var sheetAddSheetStep = async (ctx) => {
-	const verb = "sheet add_sheet";
-	const name = argOf(ctx.step, "name");
-	const at = argOf(ctx.step, "at");
-	return withWorkbook(ctx, verb, (wb) => {
-		if (wb.getWorksheet(name)) fail$3(verb, `a sheet named "${name}" already exists`);
-		const ws = wb.addWorksheet(name);
-		if (at !== void 0) {
-			const all = wb.worksheets;
-			const wsIdx = all.indexOf(ws);
-			if (wsIdx !== at - 1) all.forEach((w, i) => {
-				w.orderNo = w === ws ? at : i + 1 >= at && i < wsIdx ? i + 2 : i + 1;
-			});
-		}
-		return { added: 1 };
-	});
-};
+var sheetAddSheetStep = async (ctx) => dispatchEdit(ctx, "sheet add_sheet", "sheet.add_sheet");
 /** `sheet.remove_sheet` — remove by NAME (the server contract). */
-var sheetRemoveSheetStep = async (ctx) => {
-	const verb = "sheet remove_sheet";
-	const sheet = argOf(ctx.step, "sheet");
-	return withWorkbook(ctx, verb, (wb) => {
-		const ws = wb.getWorksheet(sheet);
-		if (!ws) fail$3(verb, `remove targets a sheet NAME; no sheet named "${sheet}". Sheets: ${wb.worksheets.map((w) => `"${w.name}"`).join(", ")}`);
-		wb.removeWorksheet(ws.id);
-		return { removed: 1 };
-	});
-};
+var sheetRemoveSheetStep = async (ctx) => dispatchEdit(ctx, "sheet remove_sheet", "sheet.remove_sheet");
 /** `sheet.reorder_sheets` — every sheet exactly once, by name or 1-based index. */
 var sheetReorderSheetsStep = async (ctx) => {
 	const verb = "sheet reorder_sheets";
-	const order = ctx.step.args.order;
-	if (!Array.isArray(order) || order.length === 0) fail$3(verb, `order must be a JSON array of names/indices, e.g. order='["Summary",2]'`);
-	return withWorkbook(ctx, verb, (wb) => {
-		const refs = order;
-		if (refs.length !== wb.worksheets.length) fail$3(verb, `order must include every worksheet exactly once (the workbook has ${wb.worksheets.length})`);
-		const reordered = [];
-		const seen = /* @__PURE__ */ new Set();
-		for (const ref of refs) {
-			const ws = typeof ref === "number" ? wb.worksheets[ref - 1] : wb.getWorksheet(ref);
-			if (!ws) fail$3(verb, `sheet not found: ${String(ref)}`);
-			if (seen.has(ws.id)) fail$3(verb, `duplicate sheet reference: ${String(ref)}`);
-			seen.add(ws.id);
-			reordered.push(ws);
-		}
-		reordered.forEach((ws, i) => {
-			ws.orderNo = i + 1;
-		});
-		return { modified: reordered.length };
-	});
+	requireJsonArray(verb, ctx.step.args.order, `order must be a JSON array of names/indices, e.g. order='["Summary",2]'`);
+	return dispatchEdit(ctx, verb, "sheet.reorder_sheets");
 };
 /** `sheet.transform_table` — rename/select/drop columns by header name. */
 var sheetTransformTableStep = async (ctx) => {
 	const verb = "sheet transform_table";
-	const headerRow = argOf(ctx.step, "header_row") ?? 1;
-	const rename = ctx.step.args.rename;
-	const select = ctx.step.args.select;
-	const drop = ctx.step.args.drop;
-	return withWorkbook(ctx, verb, (wb) => {
-		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
-		let modified = 0;
-		const headerMap = /* @__PURE__ */ new Map();
-		ws.getRow(headerRow).eachCell({ includeEmpty: false }, (cell, colNumber) => {
-			if (typeof cell.value === "string") headerMap.set(cell.value, colNumber);
-		});
-		if (rename) for (const { from, to } of rename) {
-			const colNum = headerMap.get(from);
-			if (colNum !== void 0) {
-				ws.getRow(headerRow).getCell(colNum).value = to;
-				headerMap.delete(from);
-				headerMap.set(to, colNum);
-				modified += 1;
-			}
-		}
-		if (drop) {
-			const cols = drop.map((name) => headerMap.get(name)).filter((n) => n !== void 0).sort((a, b) => b - a);
-			for (const col of cols) {
-				ws.spliceColumns(col, 1);
-				modified += 1;
-			}
-		}
-		if (select) {
-			const keep = new Set(select);
-			const cols = [];
-			ws.getRow(headerRow).eachCell({ includeEmpty: false }, (cell, colNumber) => {
-				if (typeof cell.value === "string" && !keep.has(cell.value)) cols.push(colNumber);
-			});
-			cols.sort((a, b) => b - a);
-			for (const col of cols) {
-				ws.spliceColumns(col, 1);
-				modified += 1;
-			}
-		}
-		return { modified };
-	});
+	const headerRow = argOf(ctx.step, "header_row");
+	if (headerRow !== void 0 && (!Number.isFinite(headerRow) || headerRow < 1)) fail$3(verb, "header_row must be a 1-based row number");
+	return dispatchEdit(ctx, verb, "sheet.transform_table");
 };
 /** The sheet step registry fragment, keyed by canonical verb id. */
 var SHEET_STEPS = [
@@ -1876,8 +2250,8 @@ var setSlideTitle = (slideXml, title) => {
 /** Acquire pptx bytes, converting ODP to PPTX via the engine registry. */
 var acquirePptx = async (ctx, verb) => {
 	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
-	if (mime === MIME.PPTX) return ctx.payload.bytes;
-	if (mime === MIME.ODP) {
+	if (mime === require_formats.MIME.PPTX) return ctx.payload.bytes;
+	if (mime === require_formats.MIME.ODP) {
 		if (!ctx.engines.hasConvert(mime, "pptx")) fail$2(verb, "this input is ODP — an engine that converts it to PPTX is required first, and none is configured. Do not retry this verb on this media in this deployment.");
 		const output = (await ctx.engines.convert({
 			bytes: ctx.payload.bytes,
@@ -1889,7 +2263,7 @@ var acquirePptx = async (ctx, verb) => {
 		if (!output) fail$2(verb, "normalizing the presentation to PPTX produced no output");
 		return output.bytes;
 	}
-	const reason = unsupportedForMutationReason(mime);
+	const reason = require_formats.unsupportedForMutationReason(mime);
 	if (reason) fail$2(verb, reason);
 	fail$2(verb, `slides operations expect a presentation; the media is ${mime}`);
 	throw new Error("unreachable");
@@ -1913,8 +2287,8 @@ var withPresentation = async (ctx, verb, mutate) => {
 				type: "uint8array",
 				compression: "DEFLATE"
 			}),
-			mimeType: MIME.PPTX,
-			filename: replaceExtension(ctx.payload.filename, "pptx")
+			mimeType: require_formats.MIME.PPTX,
+			filename: require_formats.replaceExtension(ctx.payload.filename, "pptx")
 		}
 	};
 };
@@ -2258,7 +2632,7 @@ var extractTextDeepStep = async (ctx) => {
 	});
 	if (mime.startsWith("image/")) return asData(await runOcr(ctx));
 	if (ocrMode === "force") return asData(await runOcr(ctx));
-	if (mime === MIME.PDF) {
+	if (mime === require_formats.MIME.PDF) {
 		const text = await extractPdfText(ctx);
 		if (text.trim().length === 0 && ocrMode === "auto") {
 			if (!ctx.engines.hasConvert(mime, "txt")) fail$1(VERB, "this PDF has no text layer (scanned?). An engine that converts application/pdf to text (OCR) is required to read it, and none is configured. Do not retry this verb on this media in this deployment.");
@@ -2266,11 +2640,11 @@ var extractTextDeepStep = async (ctx) => {
 		}
 		return asData(text);
 	}
-	if (mime === MIME.DOCX || mime === MIME.DOC) return asData(await extractDocxText(ctx));
-	if (mime === MIME.XLSX) return asData(await extractXlsxText(ctx));
-	if (mime === MIME.ODT || mime === MIME.ODS || mime === MIME.ODP) return asData(await extractOdfText(ctx));
-	if (mime === MIME.PPTX) return asData(await extractPptxText(ctx));
-	if (mime.startsWith("text/") || mime === MIME.JSON) return asData(decodeText(ctx.payload.bytes));
+	if (mime === require_formats.MIME.DOCX || mime === require_formats.MIME.DOC) return asData(await extractDocxText(ctx));
+	if (mime === require_formats.MIME.XLSX) return asData(await extractXlsxText(ctx));
+	if (mime === require_formats.MIME.ODT || mime === require_formats.MIME.ODS || mime === require_formats.MIME.ODP) return asData(await extractOdfText(ctx));
+	if (mime === require_formats.MIME.PPTX) return asData(await extractPptxText(ctx));
+	if (mime.startsWith("text/") || mime === require_formats.MIME.JSON) return asData(decodeText(ctx.payload.bytes));
 	fail$1(VERB, `text extraction for ${mime} is not supported in this build. For PPT/legacy formats: convert to=pptx | extract text (requires a convert engine).`);
 	throw new Error("unreachable");
 };
@@ -2281,16 +2655,16 @@ var extractMetadataDeepStep = async (ctx) => {
 		filename: ctx.payload.filename,
 		mime_type: ctx.payload.mimeType,
 		size_bytes: ctx.payload.bytes.byteLength,
-		family: familyOf(ctx.payload.mimeType)
+		family: require_formats.familyOf(ctx.payload.mimeType)
 	};
 	try {
-		if (mime === MIME.PDF) {
+		if (mime === require_formats.MIME.PDF) {
 			const { PDFDocument } = await import("pdf-lib");
 			const doc = await PDFDocument.load(ctx.payload.bytes, { ignoreEncryption: true });
 			meta.page_count = doc.getPageCount();
 			meta.title = doc.getTitle() ?? void 0;
 			meta.author = doc.getAuthor() ?? void 0;
-		} else if (mime === MIME.XLSX) {
+		} else if (mime === require_formats.MIME.XLSX) {
 			const mod = await import("exceljs");
 			const wb = new ("default" in mod ? mod.default : mod).Workbook();
 			await wb.xlsx.load(ctx.payload.bytes.buffer.slice(ctx.payload.bytes.byteOffset, ctx.payload.bytes.byteOffset + ctx.payload.bytes.byteLength));
@@ -2298,7 +2672,7 @@ var extractMetadataDeepStep = async (ctx) => {
 				name: ws.name,
 				rows: ws.rowCount
 			}));
-		} else if (mime === MIME.PPTX) {
+		} else if (mime === require_formats.MIME.PPTX) {
 			const zip = await (await jszip()).loadAsync(ctx.payload.bytes);
 			meta.slide_count = Object.keys(zip.files).filter((n) => /^ppt\/slides\/slide\d+\.xml$/.test(n)).length;
 		}
@@ -2332,10 +2706,16 @@ var INGEST_STEPS = [["extract.text", extractTextDeepStep], ["extract.metadata",
 /** The maximum number of conversion hops a computed path may take. */
 var MAX_HOPS = 3;
 /**
-* Format tokens that are valid conversion endpoints but never intermediate path nodes.
-* Without this rule the pathfinder would happily route `docx → txt → …` (lossy garbage in,
-* garbage out) or auto-chain `audio → pcm → txt` (skipping the resample the transcription
-* step performs between those legs).
+* The no-lossy-intermediates ROUTING rule — and nothing else. These format tokens are valid
+* conversion endpoints but never intermediate path nodes: without this rule the pathfinder
+* would happily route `docx → txt → …` (lossy garbage in, garbage out) or auto-chain
+* `audio → pcm → txt` (skipping the resample the transcription step performs between those
+* legs).
+*
+* This set does NOT gate mutation, creation, or advertising. A lossy format as the *desired
+* output* is still valid media: `txt` can be created (`empty:txt`), appended to, patched,
+* diffed, and targeted by `convert to=txt` — terminality only forbids silently routing
+* *through* it on the way to somewhere else.
 */
 var TERMINAL_TOKENS = new Set([
 	"txt",
@@ -2403,6 +2783,20 @@ var buildEngineRegistry = (engines, selection = []) => {
 		}
 		return out;
 	};
+	const editCandidates = (mimeType, op) => {
+		const mime = normalizeMime(mimeType);
+		const out = [];
+		for (const engine of engines) for (const capability of engine.edits ?? []) {
+			if (!matchesAny(capability.over, mime)) continue;
+			if (!capability.ops.includes(op)) continue;
+			out.push({
+				engine,
+				capability
+			});
+			break;
+		}
+		return out;
+	};
 	const arbitrate = async (kind, request, candidates) => {
 		if (candidates.length === 0) return void 0;
 		if (selection.length === 0 || candidates.length === 1) return candidates[0];
@@ -2441,7 +2835,7 @@ var buildEngineRegistry = (engines, selection = []) => {
 				if (!matchesAny(capability.from, mime)) continue;
 				for (const to of capability.to) {
 					if (TERMINAL_TOKENS.has(to)) continue;
-					const nextMime = EXT_TO_MIME[to];
+					const nextMime = require_formats.EXT_TO_MIME[to];
 					if (!nextMime || visited.has(nextMime)) continue;
 					visited.add(nextMime);
 					queue.push({
@@ -2478,7 +2872,7 @@ var buildEngineRegistry = (engines, selection = []) => {
 						reachable.push(to);
 					}
 					if (TERMINAL_TOKENS.has(to)) continue;
-					const nextMime = EXT_TO_MIME[to];
+					const nextMime = require_formats.EXT_TO_MIME[to];
 					if (nextMime && !visitedMimes.has(nextMime)) {
 						visitedMimes.add(nextMime);
 						next.push(nextMime);
@@ -2546,13 +2940,38 @@ var buildEngineRegistry = (engines, selection = []) => {
 		if (!chosen) throw new Error(`all engines capable of this mutate (${candidates.map((c) => c.engine.id).join(", ")}) were excluded by selection middleware`);
 		return chosen.capability.mutate(request);
 	};
+	const edit = async (request) => {
+		const candidates = editCandidates(request.mimeType, request.op);
+		if (candidates.length === 0) {
+			const allOps = /* @__PURE__ */ new Set();
+			for (const engine of engines) for (const capability of engine.edits ?? []) for (const op of capability.ops) allOps.add(op);
+			throw new Error(`no configured engine can apply "${request.op}" to ${request.mimeType}; declared edit ops: ${[...allOps].join(", ") || "(none)"} (engines: ${ids()})`);
+		}
+		const chosen = await arbitrate("edit", {
+			mimeType: request.mimeType,
+			filename: "",
+			bytes: request.bytes,
+			ops: [request.op]
+		}, candidates);
+		if (!chosen) throw new Error(`all engines capable of "${request.op}" (${candidates.map((c) => c.engine.id).join(", ")}) were excluded by selection middleware`);
+		return chosen.capability.edit(request);
+	};
 	return {
 		engines,
 		hasConvert,
 		hasMutate: () => engines.some((e) => (e.mutates ?? []).length > 0),
+		hasEdit: (mime, op) => {
+			for (const engine of engines) for (const capability of engine.edits ?? []) {
+				if (mime !== void 0 && !matchesAny(capability.over, normalizeMime(mime))) continue;
+				if (op !== void 0 && !capability.ops.includes(op)) continue;
+				return true;
+			}
+			return false;
+		},
 		convertTargets,
 		convert,
-		mutate
+		mutate,
+		edit
 	};
 };
 //#endregion
@@ -2752,7 +3171,7 @@ var pdfLib = () => {
 	return pdfLibPromise;
 };
 var requirePdf = (verb, payload) => {
-	if (payload.mimeType.toLowerCase().split(";")[0].trim() !== MIME.PDF) throw new require_exceptions.E_MEDIA_STEP_FAILED([verb, `page operations for ${payload.mimeType} are not yet implemented in this build (PDF is supported)`]);
+	if (payload.mimeType.toLowerCase().split(";")[0].trim() !== require_formats.MIME.PDF) throw new require_exceptions.E_MEDIA_STEP_FAILED([verb, `page operations for ${payload.mimeType} are not yet implemented in this build (PDF is supported)`]);
 };
 var loadPdf = async (verb, bytes) => {
 	const { PDFDocument } = await pdfLib();
@@ -2810,8 +3229,8 @@ var splitStep = async (ctx) => {
 		const bytes = new Uint8Array(await out.save());
 		payloads.push({
 			bytes,
-			mimeType: MIME.PDF,
-			filename: replaceExtension(ctx.payload.filename, "").replace(/\.$/, "") + `.part${part}.pdf`
+			mimeType: require_formats.MIME.PDF,
+			filename: require_formats.replaceExtension(ctx.payload.filename, "").replace(/\.$/, "") + `.part${part}.pdf`
 		});
 		part += 1;
 	}
@@ -2930,6 +3349,7 @@ var PURE_STEPS = [
 	["extract.text", extractTextStep],
 	["extract.metadata", extractMetadataStep],
 	["chunk", chunkStep],
+	...DATA_STEPS,
 	...SHEET_STEPS,
 	...SLIDES_STEPS,
 	...DOC_STEPS,
@@ -3007,7 +3427,8 @@ var createMediaPipeline = async (config = {}) => {
 	return callable;
 };
 //#endregion
-exports.EXT_TO_MIME = EXT_TO_MIME;
+exports.EMPTY_MIME = require_batteries_media_contracts.EMPTY_MIME;
+exports.EXT_TO_MIME = require_formats.EXT_TO_MIME;
 exports.E_INVALID_MEDIA_PIPELINE_CONFIG = require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG;
 exports.E_MEDIA_BAD_ARG = require_exceptions.E_MEDIA_BAD_ARG;
 exports.E_MEDIA_ENGINE_REQUIRED = require_exceptions.E_MEDIA_ENGINE_REQUIRED;
@@ -3020,7 +3441,7 @@ exports.E_MEDIA_UNKNOWN_ARG = require_exceptions.E_MEDIA_UNKNOWN_ARG;
 exports.E_MEDIA_UNKNOWN_VERB = require_exceptions.E_MEDIA_UNKNOWN_VERB;
 exports.E_MEDIA_UNSUPPORTED_OP = require_exceptions.E_MEDIA_UNSUPPORTED_OP;
 exports.FOLDED_VERBS = require_validate.FOLDED_VERBS;
-exports.MIME = MIME;
+exports.MIME = require_formats.MIME;
 exports.MediaChain = MediaChain;
 exports.PCM_MIME = require_batteries_media_contracts.PCM_MIME;
 exports.VERBS = require_validate.VERBS;
@@ -3029,7 +3450,7 @@ exports.availableVerbs = require_validate.availableVerbs;
 exports.buildEngineRegistry = buildEngineRegistry;
 exports.bytesToPcm = require_batteries_media_contracts.bytesToPcm;
 exports.createMediaPipeline = createMediaPipeline;
-exports.familyOf = familyOf;
+exports.familyOf = require_formats.familyOf;
 exports.foldVerb = require_validate.foldVerb;
 exports.fromOps = require_validate.fromOps;
 exports.implementsMediaEngine = require_batteries_media_contracts.implementsMediaEngine;
@@ -3038,11 +3459,11 @@ exports.isRegExpRef = require_validate.isRegExpRef;
 exports.lowerSegments = lowerSegments;
 exports.parsePipeRaw = parsePipeRaw;
 exports.pcmToBytes = require_batteries_media_contracts.pcmToBytes;
-exports.replaceExtension = replaceExtension;
+exports.replaceExtension = require_formats.replaceExtension;
 exports.suggestVerbs = require_validate.suggestVerbs;
 exports.toOps = require_validate.toOps;
 exports.toPipe = require_validate.toPipe;
-exports.unsupportedForMutationReason = unsupportedForMutationReason;
+exports.unsupportedForMutationReason = require_formats.unsupportedForMutationReason;
 exports.validateOps = require_validate.validateOps;
 exports.validateSegments = require_validate.validateSegments;