@nhtio/adk 1.20260609.0 → 1.20260610.0

package/validate-DSZ3wicB.mjs

@@ -0,0 +1,1215 @@
+import { c as isObject, o as isError } from "./tool_registry-791Vrjtf.mjs";
+import "./guards.mjs";
+import { PCM_MIME } from "./batteries/media/contracts.mjs";
+import { a as E_MEDIA_NOT_PIPE_EXPRESSIBLE, i as E_MEDIA_MISSING_ARG, l as E_MEDIA_UNKNOWN_ARG, n as E_MEDIA_BAD_ARG, r as E_MEDIA_ENGINE_REQUIRED, u as E_MEDIA_UNKNOWN_VERB } from "./exceptions-C7FSHEnV.mjs";
+//#region src/batteries/media/plan.ts
+/**
+* The neutral `MediaPlan` intermediate representation and its canonical serializers.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. All three front-ends — the
+* chainable builder, the pipe-string parser, and the JSON ops array — compile to this one IR,
+* and the step runtime consumes only this IR. Invariants (frozen design, section 0.7):
+*
+* - **Serializable.** No live `RegExp`, `Media`, or function values — regexes are
+*   `{ source, flags }`, media refs are typed handles. A plan can be logged, content-hashed,
+*   and embedded in a tool result.
+* - **Round-trip is fixed-point.** `parsePipe(toPipe(plan))` produces an equal plan and
+*   `toPipe` is idempotent. `toPipe(parsePipe(s)) === s` is NOT promised (e.g. `2,3,4,5`
+*   renders as `2-5`).
+* - **Engine-agnostic.** Steps name verbs, never engines.
+*/
+/** `true` when `value` is a {@link RegExpRef}. */
+var isRegExpRef = (value) => {
+	if (!isObject(value)) return false;
+	const v = value;
+	return typeof v.source === "string" && typeof v.flags === "string" && Object.keys(v).length === 2;
+};
+/** `true` when `value` is a {@link MediaRef}. */
+var isMediaRef = (value) => {
+	if (!isObject(value)) return false;
+	const v = value;
+	if (v.kind === "id") return typeof v.id === "string";
+	if (v.kind === "builder") return isObject(v.plan);
+	return false;
+};
+/** Characters legal in an unquoted bareword value. */
+var BAREWORD = /^[A-Za-z0-9_]+$/;
+/** Strings that would lex as a non-ident token and therefore must be quoted. */
+var LEXES_AS_OTHER = /^(?:\d+(?:-\d+)?|\d+\.\d+|true|false|@.*)$/;
+/**
+* The frozen quoting predicate: quote any string that is empty, would lex as a number, range,
+* boolean, or `@id` token, starts with `/`, or contains a character outside `[A-Za-z0-9_]`.
+*/
+var renderString = (s) => {
+	if (s.length === 0 || !BAREWORD.test(s) || LEXES_AS_OTHER.test(s) || s.startsWith("/")) return `"${s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n")}"`;
+	return s;
+};
+/** Canonicalize regex flags: validate against JS flags and sort. */
+var canonicalFlags = (flags) => Array.from(flags).sort().join("");
+/** Render a {@link RegExpRef} back to a pipe regex literal, re-escaping bare slashes. */
+var renderRegExp = (ref) => {
+	const source = ref.source.length === 0 ? "(?:)" : ref.source;
+	let out = "";
+	let inClass = false;
+	for (let i = 0; i < source.length; i++) {
+		const ch = source[i];
+		if (ch === "\\") {
+			out += ch + (source[i + 1] ?? "");
+			i++;
+			continue;
+		}
+		if (ch === "[") inClass = true;
+		else if (ch === "]") inClass = false;
+		if (ch === "/" && !inClass) {
+			out += "\\/";
+			continue;
+		}
+		out += ch;
+	}
+	return `/${out}/${canonicalFlags(ref.flags)}`;
+};
+/**
+* Compress maximal ascending consecutive runs in a number list to `a-b` range tokens.
+* Order-preserving and lossless on the array; never sorts or dedupes.
+*/
+var renderNumberList = (nums) => {
+	const parts = [];
+	let i = 0;
+	while (i < nums.length) {
+		let j = i;
+		while (j + 1 < nums.length && Number.isInteger(nums[j]) && nums[j + 1] === nums[j] + 1) j++;
+		if (j - i >= 1 && Number.isInteger(nums[i])) parts.push(`${nums[i]}-${nums[j]}`);
+		else {
+			parts.push(String(nums[i]));
+			j = i;
+		}
+		i = j + 1;
+	}
+	return parts.join(",");
+};
+var renderScalar = (value) => {
+	if (typeof value === "number") return String(value);
+	if (typeof value === "boolean") return String(value);
+	if (typeof value === "string") return renderString(value);
+	if (isRegExpRef(value)) return renderRegExp(value);
+	if (value.kind === "id") return `@${value.id}`;
+	throw new E_MEDIA_NOT_PIPE_EXPRESSIBLE(["nested builder refs have no pipe form; use toOps()"]);
+};
+var isScalar = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean" || isRegExpRef(value) || isMediaRef(value);
+var renderValue = (value) => {
+	if (value === null) throw new E_MEDIA_NOT_PIPE_EXPRESSIBLE(["null is not a flat pipe value; use toOps()"]);
+	if (Array.isArray(value)) {
+		const arr = value;
+		if (arr.length > 0 && arr.every((v) => typeof v === "number")) return renderNumberList(arr);
+		if (arr.every(isScalar)) return arr.map(renderScalar).join(",");
+		return `'${JSON.stringify(value)}'`;
+	}
+	if (isScalar(value)) return renderScalar(value);
+	return `'${JSON.stringify(value)}'`;
+};
+/**
+* Render a {@link MediaPlan} to its canonical pipe string.
+*
+* @remarks
+* Total for every plan except those containing builder-variant media refs, which throw
+* {@link E_MEDIA_NOT_PIPE_EXPRESSIBLE}. Structured args render as quoted JSON. The output is
+* canonical: dot-namespaced verbs render as space-separated words, number runs compress to
+* ranges, strings quote per the frozen predicate.
+*
+* @param plan - The plan to render.
+* @returns The canonical pipe expression.
+*/
+var toPipe = (plan) => plan.steps.map((step) => {
+	const verb = step.verb.replace(/\./g, " ");
+	const args = Object.entries(step.args).map(([k, v]) => `${k}=${renderValue(v)}`).join(" ");
+	return args.length > 0 ? `${verb} ${args}` : verb;
+}).join(" | ");
+/**
+* Render a {@link MediaPlan} to its JSON ops array. Total — every plan has an ops form.
+*
+* @param plan - The plan to render.
+* @returns The ops array (spans stripped).
+*/
+var toOps = (plan) => plan.steps.map((step) => ({
+	verb: step.verb,
+	args: step.args
+}));
+/**
+* Build a {@link MediaPlan} from a JSON ops array. The inverse of {@link toOps}.
+*
+* @remarks
+* Performs structural normalization only (verb-id folding via the caller's verb table happens
+* in validation, not here). Steps carry no spans.
+*
+* @param ops - The ops array.
+* @returns The equivalent plan.
+*/
+var fromOps = (ops) => ({ steps: ops.map((op) => ({
+	verb: op.verb,
+	args: op.args
+})) });
+//#endregion
+//#region src/batteries/media/verbs.ts
+/**
+* The canonical verb table: every verb the media DSL knows, with arg schemas, engine
+* requirements, format-family applicability, and output kinds.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. This table is the single source
+* of truth consumed by:
+*
+* - the pipe parser's semantic validator (unknown-verb/arg detection, did-you-mean),
+* - the plan compiler (arg coercion + constraint checks),
+* - the engine-narrowing pass (which verbs a deployment advertises),
+* - the forge (generating the `media_query` tool description and few-shot examples),
+* - the builder (typed front-end methods map 1:1 onto entries here).
+*
+* Frozen design decisions (design doc section 0): canonical verb ids are dot-namespaced
+* snake_case; verb matching is separator-insensitive (space/`_`/`.` fold); args are named-only;
+* indices are 1-based everywhere; arg names follow one-meaning-one-name (`to`, `with`, `match`,
+* `replace`, `order`, `pages`, `at`).
+*/
+/** Conversion targets supported by `convert` (matches the server's enum exactly). */
+var CONVERT_TARGETS = [
+	"pdf",
+	"html",
+	"txt",
+	"md",
+	"csv",
+	"json",
+	"docx",
+	"doc",
+	"rtf",
+	"odt",
+	"xlsx",
+	"xls",
+	"ods",
+	"pptx",
+	"ppt",
+	"odp"
+];
+/** Image output formats supported by `image.format`. */
+var IMAGE_FORMATS = [
+	"png",
+	"jpg",
+	"jpeg",
+	"webp",
+	"tiff",
+	"avif"
+];
+/** The canonical verb table. Order is presentation order in generated grammar text. */
+var VERBS = [
+	{
+		id: "convert",
+		description: "Convert the media to another format.",
+		args: { to: {
+			type: "enum",
+			required: true,
+			values: CONVERT_TARGETS,
+			description: "Target format."
+		} },
+		requires: { capability: "convert" },
+		appliesTo: [
+			"document",
+			"spreadsheet",
+			"presentation"
+		],
+		output: "media"
+	},
+	{
+		id: "select",
+		description: "Keep only the listed pages/slides/sections (1-based), producing one file.",
+		args: { pages: {
+			type: "number-list",
+			required: true,
+			min: 1,
+			description: "Pages (or slides/sections) to keep, 1-based. Ranges allowed: 2-5,8."
+		} },
+		appliesTo: ["document", "presentation"],
+		output: "media"
+	},
+	{
+		id: "split",
+		description: "Split the media into multiple files by page or section.",
+		args: {
+			by: {
+				type: "enum",
+				values: ["page", "section"],
+				description: "Split unit. Default: page."
+			},
+			ranges: {
+				type: "json",
+				description: "Explicit grouping as a JSON array of [start,end] pairs (1-based), e.g. '[[1,3],[5,7]]'."
+			}
+		},
+		appliesTo: ["document", "presentation"],
+		output: "media-list"
+	},
+	{
+		id: "merge",
+		description: "Merge other media into this one, in order.",
+		args: { with: {
+			type: "media-ref-list",
+			required: true,
+			description: "Other media to append, as @id refs: with=@<media id>,@<media id>."
+		} },
+		appliesTo: ["document", "presentation"],
+		output: "media"
+	},
+	{
+		id: "reorder",
+		description: "Reorder pages/slides/sections by the given 1-based index order.",
+		args: { order: {
+			type: "number-list",
+			required: true,
+			min: 1,
+			description: "New order of existing 1-based indices."
+		} },
+		appliesTo: ["document", "presentation"],
+		output: "media"
+	},
+	{
+		id: "redact",
+		description: "Redact matching text. Prefer literal strings; /regex/ is supported.",
+		args: {
+			match: {
+				type: "regex-or-string-list",
+				required: true,
+				description: "Literal string(s) or a /regex/ to redact."
+			},
+			replace: {
+				type: "string",
+				description: "Replacement text. Default: blackout/removal."
+			}
+		},
+		appliesTo: [
+			"document",
+			"spreadsheet",
+			"presentation"
+		],
+		output: "media"
+	},
+	{
+		id: "sanitize",
+		description: "Remove potentially unsafe embedded content from the media.",
+		args: {},
+		appliesTo: [
+			"document",
+			"spreadsheet",
+			"presentation"
+		],
+		output: "media"
+	},
+	{
+		id: "normalize",
+		description: "Normalize the media structure/encoding for downstream consistency.",
+		args: {},
+		appliesTo: [
+			"document",
+			"spreadsheet",
+			"presentation"
+		],
+		output: "media"
+	},
+	{
+		id: "update_text",
+		description: "Replace the first occurrence of an anchor text.",
+		args: {
+			anchor: {
+				type: "string",
+				required: true,
+				description: "Existing text to find."
+			},
+			replace: {
+				type: "string",
+				required: true,
+				description: "Replacement text (empty string deletes)."
+			}
+		},
+		appliesTo: ["document", "presentation"],
+		output: "media"
+	},
+	{
+		id: "diff",
+		description: "Compare this media against another; returns a structured diff.",
+		args: { with: {
+			type: "media-ref",
+			required: true,
+			description: "The media to compare against, as an @id ref."
+		} },
+		appliesTo: [
+			"document",
+			"spreadsheet",
+			"presentation"
+		],
+		output: "json"
+	},
+	{
+		id: "apply_patch",
+		description: "Apply a unified-diff patch to the media text.",
+		args: {
+			patch: {
+				type: "string",
+				required: true,
+				description: "The unified diff content."
+			},
+			with: {
+				type: "media-ref-list",
+				description: "Optional additional context media, as @id refs."
+			}
+		},
+		appliesTo: ["document"],
+		output: "media"
+	},
+	{
+		id: "extract.text",
+		description: "Extract text from any supported media (document, spreadsheet, image). To limit pages: select pages=… | extract text.",
+		args: {
+			ocr: {
+				type: "enum",
+				values: [
+					"off",
+					"auto",
+					"force"
+				],
+				description: "OCR behavior. Default auto (OCR only when there is no text layer)."
+			},
+			ocr_out: {
+				type: "enum",
+				values: [
+					"txt",
+					"hocr",
+					"json"
+				],
+				description: "OCR output structure when OCR runs. Default txt."
+			},
+			lang: {
+				type: "string-list",
+				description: "OCR language hint(s), e.g. lang=eng,deu. Quote tags with dashes."
+			}
+		},
+		appliesTo: [
+			"document",
+			"spreadsheet",
+			"presentation",
+			"image"
+		],
+		output: "text"
+	},
+	{
+		id: "extract.metadata",
+		description: "Extract document metadata (author, dates, page count) as JSON.",
+		args: {},
+		appliesTo: [
+			"document",
+			"spreadsheet",
+			"presentation",
+			"image",
+			"audio"
+		],
+		output: "json"
+	},
+	{
+		id: "extract.assets",
+		description: "Extract embedded assets (images, fonts, attachments) as separate media.",
+		args: {
+			types: {
+				type: "string-list",
+				values: [
+					"image",
+					"font",
+					"attachment",
+					"all"
+				],
+				description: "Asset kinds to extract. Default all."
+			},
+			format: {
+				type: "enum",
+				values: IMAGE_FORMATS,
+				description: "Re-encode extracted images to this format. Default: native encoding as stored."
+			}
+		},
+		appliesTo: [
+			"document",
+			"presentation",
+			"spreadsheet"
+		],
+		output: "media-list"
+	},
+	{
+		id: "chunk",
+		description: "Split extracted text into chunks for retrieval/indexing.",
+		args: {
+			by: {
+				type: "enum",
+				values: [
+					"sentence",
+					"paragraph",
+					"fixed"
+				],
+				description: "Chunking strategy. Default paragraph."
+			},
+			size: {
+				type: "number",
+				min: 1,
+				description: "Chunk size for fixed strategy / max size otherwise."
+			},
+			overlap: {
+				type: "number",
+				min: 0,
+				description: "Overlap between consecutive chunks."
+			}
+		},
+		appliesTo: ["document", "any"],
+		output: "json"
+	},
+	{
+		id: "sheet.add_rows",
+		description: "Insert rows into a worksheet.",
+		args: {
+			sheet: {
+				type: "name-or-index",
+				description: "Target worksheet: bare number = 1-based index, quoted string = name."
+			},
+			rows: {
+				type: "json",
+				required: true,
+				description: "Rows as a JSON array of arrays of cell values, e.g. '[[\"a\",1],[\"b\",2]]'."
+			},
+			before: {
+				type: "number",
+				min: 1,
+				description: "Insert before this 1-based row."
+			},
+			after: {
+				type: "number",
+				min: 1,
+				description: "Insert after this 1-based row."
+			}
+		},
+		appliesTo: ["spreadsheet"],
+		output: "media"
+	},
+	{
+		id: "sheet.add_columns",
+		description: "Insert columns into a worksheet.",
+		args: {
+			sheet: {
+				type: "name-or-index",
+				description: "Target worksheet (index or quoted name)."
+			},
+			headers: {
+				type: "string-list",
+				description: "Header names for the new columns (values empty)."
+			},
+			columns: {
+				type: "json",
+				description: "Full column descriptors as JSON: '[{\"header\":\"X\",\"values\":[1,2]}]'."
+			},
+			before: {
+				type: "number",
+				min: 1,
+				description: "Insert before this 1-based column."
+			},
+			after: {
+				type: "number",
+				min: 1,
+				description: "Insert after this 1-based column."
+			}
+		},
+		appliesTo: ["spreadsheet"],
+		output: "media"
+	},
+	{
+		id: "sheet.update_cells",
+		description: "Update specific cells.",
+		args: {
+			sheet: {
+				type: "name-or-index",
+				description: "Target worksheet (index or quoted name)."
+			},
+			updates: {
+				type: "json",
+				required: true,
+				description: "JSON array of updates: '[{\"address\":\"B2\",\"value\":42}]' or '[{\"row\":2,\"col\":3,\"value\":\"x\"}]'."
+			}
+		},
+		appliesTo: ["spreadsheet"],
+		output: "media"
+	},
+	{
+		id: "sheet.delete_rows",
+		description: "Delete rows by 1-based index.",
+		args: {
+			sheet: {
+				type: "name-or-index",
+				description: "Target worksheet (index or quoted name)."
+			},
+			rows: {
+				type: "number-list",
+				required: true,
+				min: 1,
+				description: "1-based row indices to delete."
+			}
+		},
+		appliesTo: ["spreadsheet"],
+		output: "media"
+	},
+	{
+		id: "sheet.delete_columns",
+		description: "Delete columns by 1-based index.",
+		args: {
+			sheet: {
+				type: "name-or-index",
+				description: "Target worksheet (index or quoted name)."
+			},
+			columns: {
+				type: "number-list",
+				required: true,
+				min: 1,
+				description: "1-based column indices to delete."
+			}
+		},
+		appliesTo: ["spreadsheet"],
+		output: "media"
+	},
+	{
+		id: "sheet.rename_sheet",
+		description: "Rename a worksheet. The target must be a sheet NAME (quote it).",
+		args: {
+			sheet: {
+				type: "string",
+				required: true,
+				description: "Current sheet name (names only for rename; quote it)."
+			},
+			to: {
+				type: "string",
+				required: true,
+				description: "New sheet name."
+			}
+		},
+		appliesTo: ["spreadsheet"],
+		output: "media"
+	},
+	{
+		id: "sheet.add_sheet",
+		description: "Add a new worksheet.",
+		args: {
+			name: {
+				type: "string",
+				required: true,
+				description: "Name for the new worksheet."
+			},
+			at: {
+				type: "number",
+				min: 1,
+				description: "Insert at this 1-based position."
+			}
+		},
+		appliesTo: ["spreadsheet"],
+		output: "media"
+	},
+	{
+		id: "sheet.remove_sheet",
+		description: "Remove a worksheet. The target must be a sheet NAME (quote it).",
+		args: { sheet: {
+			type: "string",
+			required: true,
+			description: "Sheet name to remove (names only; quote it)."
+		} },
+		appliesTo: ["spreadsheet"],
+		output: "media"
+	},
+	{
+		id: "sheet.reorder_sheets",
+		description: "Reorder worksheets.",
+		args: { order: {
+			type: "json",
+			required: true,
+			description: "JSON array of sheet names and/or 1-based indices in the new order: '[\"Summary\",2,3]'."
+		} },
+		appliesTo: ["spreadsheet"],
+		output: "media"
+	},
+	{
+		id: "sheet.transform_table",
+		description: "Rename/select/drop table columns by header name.",
+		args: {
+			sheet: {
+				type: "name-or-index",
+				description: "Target worksheet (index or quoted name)."
+			},
+			header_row: {
+				type: "number",
+				min: 1,
+				description: "1-based header row. Default 1."
+			},
+			select: {
+				type: "string-list",
+				description: "Column headers to keep."
+			},
+			drop: {
+				type: "string-list",
+				description: "Column headers to drop."
+			},
+			rename: {
+				type: "json",
+				description: "JSON array of renames: '[{\"from\":\"Old\",\"to\":\"New\"}]'."
+			}
+		},
+		appliesTo: ["spreadsheet"],
+		output: "media"
+	},
+	{
+		id: "slides.add",
+		description: "Add a new slide.",
+		args: {
+			at: {
+				type: "number",
+				min: 1,
+				description: "Insert at this 1-based position."
+			},
+			title: {
+				type: "string",
+				description: "Title text for the new slide."
+			},
+			layout: {
+				type: "string",
+				description: "Layout name (template-dependent)."
+			}
+		},
+		appliesTo: ["presentation"],
+		output: "media"
+	},
+	{
+		id: "slides.update_text",
+		description: "Update text on a slide.",
+		args: {
+			slide: {
+				type: "name-or-index",
+				description: "Target slide: bare number = 1-based index, quoted string = title."
+			},
+			placeholder: {
+				type: "string",
+				description: "Placeholder/shape to target."
+			},
+			text: {
+				type: "string",
+				required: true,
+				description: "Replacement text."
+			}
+		},
+		appliesTo: ["presentation"],
+		output: "media"
+	},
+	{
+		id: "slides.update_table",
+		description: "Update table cells on a slide.",
+		args: {
+			slide: {
+				type: "name-or-index",
+				description: "Target slide (index or quoted title)."
+			},
+			updates: {
+				type: "json",
+				required: true,
+				description: "JSON array: '[{\"row\":1,\"col\":2,\"value\":\"x\"}]' (1-based)."
+			}
+		},
+		appliesTo: ["presentation"],
+		output: "media"
+	},
+	{
+		id: "slides.update_image",
+		description: "Replace an image on a slide with another media.",
+		args: {
+			slide: {
+				type: "name-or-index",
+				description: "Target slide (index or quoted title)."
+			},
+			placeholder: {
+				type: "string",
+				description: "Placeholder/shape to target."
+			},
+			with: {
+				type: "media-ref",
+				required: true,
+				description: "The replacement image, as an @id ref."
+			}
+		},
+		appliesTo: ["presentation"],
+		output: "media"
+	},
+	{
+		id: "slides.update_chart",
+		description: "Update chart data on a slide.",
+		args: {
+			slide: {
+				type: "name-or-index",
+				description: "Target slide (index or quoted title)."
+			},
+			data: {
+				type: "json",
+				description: "JSON array-of-arrays of chart data: '[[\"Q1\",10],[\"Q2\",20]]'."
+			}
+		},
+		appliesTo: ["presentation"],
+		output: "media"
+	},
+	{
+		id: "slides.delete",
+		description: "Delete slides by 1-based index.",
+		args: { slides: {
+			type: "number-list",
+			required: true,
+			min: 1,
+			description: "1-based slide indices to delete."
+		} },
+		appliesTo: ["presentation"],
+		output: "media"
+	},
+	{
+		id: "slides.reorder",
+		description: "Reorder slides.",
+		args: { order: {
+			type: "number-list",
+			required: true,
+			min: 1,
+			description: "New order of existing 1-based slide indices."
+		} },
+		appliesTo: ["presentation"],
+		output: "media"
+	},
+	{
+		id: "slides.duplicate",
+		description: "Duplicate a slide.",
+		args: {
+			slide: {
+				type: "number",
+				required: true,
+				min: 1,
+				description: "1-based slide to copy."
+			},
+			at: {
+				type: "number",
+				min: 1,
+				description: "Insert the copy at this position."
+			}
+		},
+		appliesTo: ["presentation"],
+		output: "media"
+	},
+	{
+		id: "image.resize",
+		description: "Resize the image.",
+		args: {
+			width: {
+				type: "number",
+				min: 1,
+				max: 16384,
+				description: "Target width in px."
+			},
+			height: {
+				type: "number",
+				min: 1,
+				max: 16384,
+				description: "Target height in px."
+			},
+			fit: {
+				type: "enum",
+				values: [
+					"cover",
+					"contain",
+					"fill",
+					"inside",
+					"outside"
+				],
+				description: "Resize fit mode. Default cover."
+			}
+		},
+		requires: { capability: "mutate" },
+		appliesTo: ["image"],
+		output: "media"
+	},
+	{
+		id: "image.format",
+		description: "Re-encode the image to another format.",
+		args: {
+			to: {
+				type: "enum",
+				required: true,
+				values: IMAGE_FORMATS,
+				description: "Target image format."
+			},
+			quality: {
+				type: "number",
+				min: 1,
+				max: 100,
+				description: "Quality for lossy formats."
+			},
+			strip_metadata: {
+				type: "boolean",
+				description: "Remove EXIF/ICC metadata from the output."
+			}
+		},
+		requires: { capability: "mutate" },
+		appliesTo: ["image"],
+		output: "media"
+	},
+	{
+		id: "image.rotate",
+		description: "Rotate the image.",
+		args: { deg: {
+			type: "enum",
+			required: true,
+			values: [
+				"90",
+				"180",
+				"270"
+			],
+			description: "Rotation in degrees (clockwise)."
+		} },
+		requires: { capability: "mutate" },
+		appliesTo: ["image"],
+		output: "media"
+	},
+	{
+		id: "image.flip",
+		description: "Flip the image.",
+		args: { axis: {
+			type: "enum",
+			required: true,
+			values: [
+				"horizontal",
+				"vertical",
+				"both"
+			],
+			description: "Flip axis."
+		} },
+		requires: { capability: "mutate" },
+		appliesTo: ["image"],
+		output: "media"
+	},
+	{
+		id: "image.strip_metadata",
+		description: "Remove EXIF/ICC metadata from the image without other changes.",
+		args: {},
+		requires: { capability: "mutate" },
+		appliesTo: ["image"],
+		output: "media"
+	},
+	{
+		id: "audio.transcribe",
+		description: "Transcribe speech to text.",
+		args: {
+			lang: {
+				type: "string",
+				description: "Language hint, e.g. lang=en. Quote tags with dashes: lang=\"en-US\"."
+			},
+			out: {
+				type: "enum",
+				values: [
+					"txt",
+					"srt",
+					"vtt",
+					"json"
+				],
+				description: "Output format. Default txt. srt/vtt produce subtitles."
+			},
+			translate: {
+				type: "boolean",
+				description: "Translate the transcription to English."
+			}
+		},
+		requires: {
+			capability: "convert",
+			from: PCM_MIME
+		},
+		appliesTo: ["audio"],
+		output: "text"
+	}
+];
+/** Map of canonical verb id → spec, for direct lookup. */
+var VERB_INDEX = new Map(VERBS.map((v) => [v.id, v]));
+/**
+* Fold a verb token sequence to canonical form: lowercase, separators (space/`_`/`.`)
+* normalized so `extract_text` ≡ `extract text` ≡ `extract.text` all match `extract.text`.
+*
+* @param words - The verb word tokens as written (1 or 2 words, possibly containing `_`/`.`).
+* @returns The canonical verb id when a fold-match exists, otherwise `undefined`.
+*/
+var foldVerb = (words) => {
+	const flat = words.join(" ").toLowerCase().replace(/[._\s]+/g, " ").trim();
+	return FOLDED_INDEX.get(flat);
+};
+/** Internal: folded "word word" form → canonical id. */
+var FOLDED_INDEX = (() => {
+	const map = /* @__PURE__ */ new Map();
+	for (const v of VERBS) {
+		const folded = v.id.replace(/[._]+/g, " ");
+		if (map.has(folded)) throw new Error(`verb table invariant violated: "${folded}" folds to multiple verbs`);
+		map.set(folded, v.id);
+	}
+	return map;
+})();
+/**
+* All folded verb word-sequences, for the parser's longest-match verb recognition and for
+* generated grammar text.
+*/
+var FOLDED_VERBS = Array.from(FOLDED_INDEX.keys());
+/**
+* Suggest the nearest verbs to an unknown input, for did-you-mean errors. Matches whole folded
+* forms AND suffix words (`resize` suggests `image resize`), per the frozen error model.
+*
+* @param input - The unknown verb text as written.
+* @param candidates - The folded verb forms to search (pass the narrowed set to avoid
+*   suggesting unconfigured verbs).
+* @returns Up to three suggestions, best first.
+*/
+var suggestVerbs = (input, candidates) => {
+	const folded = input.toLowerCase().replace(/[._\s]+/g, " ").trim();
+	const scored = [];
+	for (const cand of candidates) {
+		const direct = levenshtein(folded, cand);
+		const words = cand.split(" ");
+		const suffix = words.length > 1 ? levenshtein(folded, words[words.length - 1]) : Infinity;
+		const score = Math.min(direct, suffix);
+		if (score <= Math.max(2, Math.floor(folded.length / 3))) scored.push({
+			name: cand,
+			score
+		});
+	}
+	scored.sort((a, b) => a.score - b.score);
+	return scored.slice(0, 3).map((s) => s.name);
+};
+/** Classic two-row Levenshtein distance. */
+var levenshtein = (a, b) => {
+	if (a === b) return 0;
+	if (a.length === 0) return b.length;
+	if (b.length === 0) return a.length;
+	let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+	let curr = new Array(b.length + 1);
+	for (let i = 1; i <= a.length; i++) {
+		curr[0] = i;
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+		}
+		[prev, curr] = [curr, prev];
+	}
+	return prev[b.length];
+};
+//#endregion
+//#region src/batteries/media/validate.ts
+/**
+* The semantic validator: checks raw parsed segments (or ops) against the verb table and the
+* deployment's configured engines, producing the validated {@link MediaPlan} or a
+* model-actionable error.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. This is the layer no parser
+* toolkit could supply — every error names what was wrong, suggests the nearest valid form,
+* and shows a corrective exemplar (frozen design 0.14). Engine narrowing happens HERE, never
+* at parse time (frozen 0.3): the same string parses identically in every deployment; only
+* validation differs.
+*/
+/** `true` when the deployment satisfies a verb's capability requirement. */
+var satisfies = (capabilities, requires) => requires.capability === "mutate" ? capabilities.hasMutate() : capabilities.hasConvert(requires.from, requires.to);
+/** A human phrase for an unmet requirement, for the do-not-retry error. */
+var requirementText = (requires) => {
+	if (requires.capability === "mutate") return "an engine that can mutate this media";
+	return `an engine that can convert${requires.from ? ` from ${requires.from}` : ""}${requires.to ? ` to ${requires.to}` : ""}`;
+};
+/** The folded verb forms available under a given capability configuration. */
+var availableVerbs = (capabilities) => {
+	const out = [];
+	for (const [id, spec] of VERB_INDEX) {
+		if (spec.requires && !satisfies(capabilities, spec.requires)) continue;
+		out.push(id.replace(/[._]+/g, " "));
+	}
+	return out;
+};
+var levSuggest = (verbText, capabilities) => {
+	const suggestions = suggestVerbs(verbText, availableVerbs(capabilities));
+	return suggestions.length > 0 ? ` did you mean "${suggestions[0]}"?` : "";
+};
+var verbList = (capabilities) => availableVerbs(capabilities).join(", ");
+var resolveVerb = (verbText, capabilities, position) => {
+	const canonical = foldVerb(verbText.split(" ")) ?? verbText;
+	const spec = VERB_INDEX.get(canonical);
+	if (!spec) throw new E_MEDIA_UNKNOWN_VERB([`unknown verb "${verbText}" at segment ${position}.${levSuggest(verbText, capabilities)} Available verbs: ${verbList(capabilities)}`]);
+	if (spec.requires && !satisfies(capabilities, spec.requires)) throw new E_MEDIA_ENGINE_REQUIRED([`verb "${verbText}" requires ${requirementText(spec.requires)}, and none is configured in this deployment. Do not retry this verb here. Available verbs: ${verbList(capabilities)}`]);
+	return spec;
+};
+var suggestArg = (name, spec) => {
+	const ranked = suggestVerbs(name, Object.keys(spec.args));
+	return ranked.length > 0 ? ` did you mean "${ranked[0]}"?` : "";
+};
+var argList = (spec) => {
+	const names = Object.keys(spec.args);
+	return names.length > 0 ? names.join(", ") : "(none)";
+};
+var exemplar = (spec) => {
+	const parts = [spec.id.replace(/\./g, " ")];
+	for (const [name, arg] of Object.entries(spec.args)) {
+		if (!arg.required) continue;
+		parts.push(`${name}=${exampleValue(arg)}`);
+	}
+	return parts.join(" ");
+};
+var exampleValue = (arg) => {
+	switch (arg.type) {
+		case "enum": return arg.values?.[0] ?? "value";
+		case "number": return String(arg.min ?? 1);
+		case "number-list": return "1-3,5";
+		case "string-list": return "a,b";
+		case "boolean": return "true";
+		case "regex-or-string-list": return "\"literal text\"";
+		case "media-ref": return "@<media id>";
+		case "media-ref-list": return "@<media id>";
+		case "json": return `'[…]'`;
+		default: return "\"value\"";
+	}
+};
+/** Coerce + check one arg value against its spec. Returns the IR-final value. */
+var checkArg = (verb, name, raw) => {
+	const spec = verb.args[name];
+	const where = `arg "${name}" on "${verb.id.replace(/\./g, " ")}"`;
+	const bad = (msg) => {
+		throw new E_MEDIA_BAD_ARG([`${where}: ${msg}. Write it like: ${exemplar(verb)}`]);
+	};
+	const v = raw.value;
+	switch (spec.type) {
+		case "name-or-index":
+			if (typeof v === "number") {
+				if (!Number.isInteger(v) || v < 1) bad("indices are 1-based integers");
+				return v;
+			}
+			if (typeof v !== "string") bad("expected a 1-based index or a quoted name");
+			return v;
+		case "string":
+			if (typeof v === "number" && !raw.quoted) return String(v);
+			if (typeof v !== "string") bad(`expected text${typeof v === "object" ? ", got a structured value" : ""}`);
+			return v;
+		case "number": {
+			if (typeof v !== "number") bad("expected a number");
+			const n = v;
+			if (spec.min !== void 0 && n < spec.min) bad(`must be ≥ ${spec.min} (indices are 1-based)`);
+			if (spec.max !== void 0 && n > spec.max) bad(`must be ≤ ${spec.max}`);
+			return n;
+		}
+		case "boolean":
+			if (typeof v !== "boolean") bad("expected true or false");
+			return v;
+		case "enum": {
+			const s = typeof v === "number" ? String(v) : v;
+			if (typeof s !== "string" || !spec.values?.includes(s)) bad(`"${String(v)}" is not valid; valid values: ${spec.values?.join(", ")}`);
+			return s;
+		}
+		case "number-list": {
+			const arr = Array.isArray(v) ? v : [v];
+			if (!arr.every((x) => typeof x === "number")) bad("expected numbers (e.g. 1-3,5)");
+			const nums = arr;
+			if (spec.min !== void 0 && nums.some((n) => n < spec.min)) bad(`values must be ≥ ${spec.min} (indices are 1-based)`);
+			return nums;
+		}
+		case "string-list": {
+			const arr = Array.isArray(v) ? v : [v];
+			if (!arr.every((x) => typeof x === "string")) bad("expected names (quote values with special characters)");
+			const strs = arr;
+			if (spec.values && !strs.every((s) => spec.values?.includes(s))) bad(`valid values: ${spec.values.join(", ")}`);
+			return strs;
+		}
+		case "regex-or-string-list": {
+			if (isRegExpRef(v)) return v;
+			const arr = Array.isArray(v) ? v : [v];
+			if (arr.every((x) => typeof x === "string" || isRegExpRef(x))) return arr;
+			bad("expected literal text, a list of literals, or a /regex/");
+			break;
+		}
+		case "media-ref":
+			if (isMediaRef(v)) return v;
+			bad("expected a media reference: with=@<media id> (get ids from list_media)");
+			break;
+		case "media-ref-list": {
+			const arr = Array.isArray(v) ? v : [v];
+			if (arr.every(isMediaRef)) return arr;
+			bad("expected media references: with=@<id>,@<id> (get ids from list_media)");
+			break;
+		}
+		case "json":
+			if (typeof v === "string") {
+				if (!raw.quoted) bad(`expected a quoted JSON value, e.g. ${name}='[…]'`);
+				try {
+					return JSON.parse(v);
+				} catch (err) {
+					bad(`the quoted value is not valid JSON (${isError(err) ? err.message : String(err)})`);
+				}
+			}
+			if (isObject(v) || Array.isArray(v)) return v;
+			bad(`expected a JSON value, e.g. ${name}='[…]'`);
+			break;
+	}
+	throw new E_MEDIA_BAD_ARG([`${where}: invalid value`]);
+};
+var checkStep = (spec, args) => {
+	const verbText = spec.id.replace(/\./g, " ");
+	const finalArgs = {};
+	for (const [name, raw] of args) {
+		if (!(name in spec.args)) throw new E_MEDIA_UNKNOWN_ARG([`verb "${verbText}" has no arg "${name}".${suggestArg(name, spec)} Args: ${argList(spec)}. Write it like: ${exemplar(spec)}`]);
+		finalArgs[name] = checkArg(spec, name, raw);
+	}
+	for (const [name, argSpec] of Object.entries(spec.args)) if (argSpec.required && !(name in finalArgs)) throw new E_MEDIA_MISSING_ARG([`verb "${verbText}" requires arg "${name}" (${argSpec.description}). Write it like: ${exemplar(spec)}`]);
+	return {
+		verb: spec.id,
+		args: finalArgs
+	};
+};
+/**
+* Validate raw pipe segments into a {@link MediaPlan}.
+*
+* @param segments - Output of `parsePipeRaw`.
+* @param options - The deployment's capability probe.
+* @returns The validated plan, spans preserved.
+*/
+var validateSegments = (segments, options) => {
+	const steps = [];
+	segments.forEach((seg, i) => {
+		const step = checkStep(resolveVerb(seg.verb.replace(/\./g, " "), options.capabilities, i + 1), seg.args);
+		step.span = seg.span;
+		steps.push(step);
+	});
+	return { steps };
+};
+/**
+* Validate a JSON ops array into a {@link MediaPlan}. The same checks as the pipe path —
+* verbs fold the same way, args validate against the same specs — so the two front-ends
+* produce identical plans for equivalent statements.
+*
+* @param ops - The ops array.
+* @param options - The deployment's capability probe.
+* @returns The validated plan (no spans).
+*/
+var validateOps = (ops, options) => {
+	const steps = [];
+	ops.forEach((op, i) => {
+		const spec = resolveVerb(op.verb.replace(/[._]+/g, " "), options.capabilities, i + 1);
+		const args = new Map(Object.entries(op.args).map(([k, v]) => [k, {
+			value: v,
+			quoted: typeof v === "string",
+			span: {
+				offset: 0,
+				line: 1,
+				col: 1,
+				length: 0
+			}
+		}]));
+		steps.push(checkStep(spec, args));
+	});
+	return { steps };
+};
+//#endregion
+export { VERBS as a, suggestVerbs as c, isMediaRef as d, isRegExpRef as f, FOLDED_VERBS as i, canonicalFlags as l, toPipe as m, validateOps as n, VERB_INDEX as o, toOps as p, validateSegments as r, foldVerb as s, availableVerbs as t, fromOps as u };
+
+//# sourceMappingURL=validate-DSZ3wicB.mjs.map