@styx-api/core 0.6.1 → 0.8.0

package/dist/index.cjs

@@ -206,10 +206,7 @@ var ArgdumpParser = class {
 			if (nargs.__argparse__ === "REMAINDER") return {
 				kind: "repeat",
 				attrs: {
-					node: {
-						kind: "str",
-						attrs: {}
-					},
+					node,
 					countMin: 0
 				}
 			};
@@ -580,25 +577,24 @@ var ArgdumpParser = class {
 			this.error(`No valid subparsers for '${action.dest}'`);
 			return null;
 		}
-		if (alts.length === 1) return alts[0];
-		const alt = {
+		const node = alts.length === 1 ? alts[0] : {
 			kind: "alternative",
 			attrs: { alts }
 		};
-		if (!(action.subparsers_required === true || action.required === true)) {
+		const isRequired = action.subparsers_required === true || action.required === true;
+		const meta = this.buildNodeMeta(action);
+		if (!isRequired) {
 			const opt = {
 				kind: "optional",
-				attrs: { node: alt }
+				attrs: { node }
 			};
-			const meta = this.buildNodeMeta(action);
 			if (meta) opt.meta = meta;
 			return opt;
 		}
-		const meta = this.buildNodeMeta(action);
-		if (meta) alt.meta = meta;
-		return alt;
+		if (node.kind === "alternative" && meta) node.meta = meta;
+		return node;
 	}
-	applyMutualExclusion(actionsByDest, groups, nodes, nodesByDest) {
+	applyMutualExclusion(groups, nodes, nodesByDest) {
 		const excluded = /* @__PURE__ */ new Set();
 		for (const group of groups) {
 			if (!isObject$3(group)) continue;
@@ -621,136 +617,1682 @@ var ArgdumpParser = class {
 					...inner.meta,
 					name: inner.meta?.name ?? findDeepName$1(inner) ?? dest
 				};
-				altMembers.push(inner);
-				excluded.add(dest);
+				altMembers.push(inner);
+				excluded.add(dest);
+			}
+			const alt = {
+				kind: "alternative",
+				attrs: { alts: altMembers }
+			};
+			const isRequired = group.required === true;
+			let groupNode;
+			if (isRequired) groupNode = alt;
+			else groupNode = {
+				kind: "optional",
+				attrs: { node: alt }
+			};
+			const groupName = (isString$3(group.title) ? group.title : void 0) ?? (memberDests.length === 2 ? `${memberDests[0]}_or_${memberDests[1]}` : `${memberDests[0]}_choice`);
+			groupNode.meta = {
+				...groupNode.meta,
+				name: groupName
+			};
+			const firstDest = memberDests[0];
+			const firstIdx = nodes.findIndex((n) => n === nodesByDest.get(firstDest));
+			if (firstIdx >= 0) nodes.splice(firstIdx, 0, groupNode);
+			else nodes.push(groupNode);
+		}
+		return nodes.filter((n) => {
+			for (const [dest, node] of nodesByDest) if (node === n && excluded.has(dest)) return false;
+			return true;
+		});
+	}
+	parseParserInfo(descriptor) {
+		const actions = descriptor.actions;
+		if (!isArray$3(actions)) return {
+			kind: "sequence",
+			attrs: { nodes: [] }
+		};
+		const positionals = [];
+		const optionals = [];
+		const nodesByDest = /* @__PURE__ */ new Map();
+		for (const rawAction of actions) {
+			if (!isObject$3(rawAction)) continue;
+			const node = this.buildAction(rawAction);
+			if (!node) continue;
+			const dest = rawAction.dest;
+			if (isString$3(dest)) nodesByDest.set(dest, node);
+			if (this.isPositional(rawAction) && rawAction.action_type !== "parsers") positionals.push(node);
+			else optionals.push(node);
+		}
+		let allNodes = [...positionals, ...optionals];
+		const mutexGroups = descriptor.mutually_exclusive_groups;
+		if (isArray$3(mutexGroups) && mutexGroups.length > 0) allNodes = this.applyMutualExclusion(mutexGroups, allNodes, nodesByDest);
+		return {
+			kind: "sequence",
+			attrs: { nodes: allNodes }
+		};
+	}
+	parse(source, _filename) {
+		this.reset();
+		const descriptor = this.parseJSON(source);
+		if (descriptor === null) return {
+			expr: {
+				kind: "sequence",
+				attrs: { nodes: [] }
+			},
+			errors: this.errors,
+			warnings: this.warnings
+		};
+		const meta = this.buildAppMeta(descriptor);
+		if (!meta) {
+			this.error("Descriptor is missing prog");
+			return {
+				expr: {
+					kind: "sequence",
+					attrs: { nodes: [] }
+				},
+				errors: this.errors,
+				warnings: this.warnings
+			};
+		}
+		const expr = this.parseParserInfo(descriptor);
+		if (expr === null) {
+			this.error("Failed to parse argument structure");
+			return {
+				expr: {
+					kind: "sequence",
+					attrs: { nodes: [] }
+				},
+				errors: this.errors,
+				warnings: this.warnings
+			};
+		}
+		const prog = descriptor.prog;
+		if (isString$3(prog) && prog) expr.attrs.nodes.unshift({
+			kind: "literal",
+			attrs: { str: prog }
+		});
+		if (!expr.meta?.name && meta.id) expr.meta = {
+			...expr.meta,
+			name: meta.id
+		};
+		return {
+			meta,
+			expr,
+			errors: this.errors,
+			warnings: this.warnings
+		};
+	}
+};
+
+//#endregion
+//#region src/frontend/argtype/lexer.ts
+const PUNCT = {
+	":": "colon",
+	"=": "eq",
+	"|": "pipe",
+	".": "dot",
+	",": "comma",
+	"(": "lparen",
+	")": "rparen"
+};
+function isIdentStart(ch) {
+	return /[A-Za-z_]/.test(ch);
+}
+function isIdentPart(ch) {
+	return /[A-Za-z0-9_]/.test(ch);
+}
+function isDigit(ch) {
+	return ch >= "0" && ch <= "9";
+}
+function lex(source) {
+	const tokens = [];
+	const errors = [];
+	let i = 0;
+	let line = 1;
+	let col = 1;
+	const peek = (o = 0) => source[i + o] ?? "";
+	const advance = () => {
+		const ch = source[i++];
+		if (ch === "\n") {
+			line++;
+			col = 1;
+		} else col++;
+		return ch;
+	};
+	const push = (kind, value, l, c) => {
+		tokens.push({
+			kind,
+			value,
+			line: l,
+			column: c
+		});
+	};
+	while (i < source.length) {
+		const ch = peek();
+		const startLine = line;
+		const startCol = col;
+		if (ch === " " || ch === "	" || ch === "\r" || ch === "\n") {
+			advance();
+			continue;
+		}
+		if (ch === "/" && peek(1) === "/") {
+			const isDoc = peek(2) === "/";
+			advance();
+			advance();
+			if (isDoc) advance();
+			let text = "";
+			while (i < source.length && peek() !== "\n") text += advance();
+			if (isDoc) push("doc", text.trim(), startLine, startCol);
+			continue;
+		}
+		if (ch === "\"") {
+			advance();
+			let str = "";
+			let closed = false;
+			while (i < source.length) {
+				const c = advance();
+				if (c === "\\") {
+					const esc = i < source.length ? advance() : "";
+					str += unescape(esc);
+				} else if (c === "\"") {
+					closed = true;
+					break;
+				} else if (c === "\n") break;
+				else str += c;
+			}
+			if (!closed) errors.push({
+				message: "Unterminated string literal",
+				line: startLine,
+				column: startCol
+			});
+			push("string", str, startLine, startCol);
+			continue;
+		}
+		if (ch === "`") {
+			advance();
+			let body = "";
+			let closed = false;
+			while (i < source.length) {
+				const c = advance();
+				if (c === "\\") {
+					body += c;
+					if (i < source.length) body += advance();
+					continue;
+				}
+				if (c === "`") {
+					closed = true;
+					break;
+				}
+				body += c;
+			}
+			if (!closed) errors.push({
+				message: "Unterminated template literal",
+				line: startLine,
+				column: startCol
+			});
+			push("template", body, startLine, startCol);
+			continue;
+		}
+		if (isDigit(ch) || ch === "-" && isDigit(peek(1))) {
+			let num = advance();
+			while (i < source.length && isDigit(peek())) num += advance();
+			if (peek() === "." && isDigit(peek(1))) {
+				num += advance();
+				while (i < source.length && isDigit(peek())) num += advance();
+			}
+			if (peek() === "e" || peek() === "E") {
+				const signed = peek(1) === "+" || peek(1) === "-";
+				if (isDigit(peek(1)) || signed && isDigit(peek(2))) {
+					num += advance();
+					if (peek() === "+" || peek() === "-") num += advance();
+					while (i < source.length && isDigit(peek())) num += advance();
+				} else {
+					num += advance();
+					errors.push({
+						message: `Malformed number '${num}': exponent has no digits`,
+						line: startLine,
+						column: startCol
+					});
+				}
+			}
+			if (/^\d+$/.test(num) && isIdentStart(peek())) {
+				let rest = "";
+				while (i < source.length && isIdentPart(peek())) rest += advance();
+				const full = num + rest;
+				errors.push({
+					message: `Identifier cannot start with a digit; quote it as "${full}"`,
+					line: startLine,
+					column: startCol
+				});
+				push("ident", full, startLine, startCol);
+				continue;
+			}
+			push("number", num, startLine, startCol);
+			continue;
+		}
+		if (isIdentStart(ch)) {
+			let id = advance();
+			while (i < source.length && isIdentPart(peek())) id += advance();
+			push("ident", id, startLine, startCol);
+			continue;
+		}
+		const punct = PUNCT[ch];
+		if (punct) {
+			advance();
+			push(punct, ch, startLine, startCol);
+			continue;
+		}
+		errors.push({
+			message: `Unexpected character '${ch}'`,
+			line: startLine,
+			column: startCol
+		});
+		advance();
+	}
+	push("eof", "", line, col);
+	return {
+		tokens,
+		errors
+	};
+}
+/** Minimal escape handling inside double-quoted strings. */
+function unescape(esc) {
+	switch (esc) {
+		case "n": return "\n";
+		case "t": return "	";
+		case "r": return "\r";
+		case "\"": return "\"";
+		case "\\": return "\\";
+		case "": return "";
+		default: return esc;
+	}
+}
+
+//#endregion
+//#region src/frontend/argtype/frontmatter.ts
+function splitFrontmatter(source) {
+	const lines = source.split("\n");
+	let start = 0;
+	while (start < lines.length && lines[start].trim() === "") start++;
+	if (lines[start]?.trim() !== "---") return {
+		body: source,
+		errors: []
+	};
+	let end = -1;
+	for (let i = start + 1; i < lines.length; i++) if (lines[i].trim() === "---") {
+		end = i;
+		break;
+	}
+	if (end === -1) return {
+		body: source,
+		errors: ["Unterminated frontmatter block (missing closing '---')"]
+	};
+	const { value, errors } = parseYamlish(lines.slice(start + 1, end));
+	return {
+		frontmatter: value,
+		body: lines.map((line, i) => i >= start && i <= end ? "" : line).join("\n"),
+		errors
+	};
+}
+function tokenizeLines(raw) {
+	const out = [];
+	for (const line of raw) {
+		const noComment = stripComment(line);
+		if (noComment.trim() === "") continue;
+		const indent = noComment.length - noComment.trimStart().length;
+		out.push({
+			indent,
+			content: noComment.trim()
+		});
+	}
+	return out;
+}
+/** Strip a trailing `#` comment that is not inside quotes. Following YAML, a
+* `#` only starts a comment at the start of the line or after whitespace, so an
+* unquoted value containing `#` (e.g. a URL fragment `https://x/#frag`) is kept
+* intact. */
+function stripComment(line) {
+	let inQuote = null;
+	for (let i = 0; i < line.length; i++) {
+		const ch = line[i];
+		if (inQuote === "\"" && ch === "\\") {
+			i++;
+			continue;
+		}
+		if (inQuote) {
+			if (ch === inQuote) inQuote = null;
+		} else if (ch === "\"" || ch === "'") inQuote = ch;
+		else if (ch === "#" && (i === 0 || line[i - 1] === " " || line[i - 1] === "	")) return line.slice(0, i);
+	}
+	return line;
+}
+function parseYamlish(raw) {
+	const lines = tokenizeLines(raw);
+	const errors = [];
+	let pos = 0;
+	function parseBlock(minIndent) {
+		if (pos < lines.length && lines[pos].indent >= minIndent && lines[pos].content.startsWith("- ")) {
+			const seq = [];
+			const indent = lines[pos].indent;
+			while (pos < lines.length && lines[pos].indent === indent && lines[pos].content.startsWith("- ")) {
+				seq.push(parseScalar(lines[pos].content.slice(2).trim()));
+				pos++;
+			}
+			return seq;
+		}
+		const map = {};
+		if (pos >= lines.length) return map;
+		const indent = lines[pos].indent;
+		while (pos < lines.length && lines[pos].indent === indent && !lines[pos].content.startsWith("- ")) {
+			const { content } = lines[pos];
+			const colon = findColon(content);
+			if (colon === -1) {
+				errors.push(`Malformed frontmatter line: '${content}'`);
+				pos++;
+				continue;
+			}
+			const key = content.slice(0, colon).trim();
+			const valueText = content.slice(colon + 1).trim();
+			pos++;
+			if (valueText !== "") map[key] = parseScalar(valueText);
+			else if (pos < lines.length && lines[pos].indent > indent) map[key] = parseBlock(lines[pos].indent);
+			else map[key] = null;
+		}
+		return map;
+	}
+	const value = parseBlock(0);
+	return {
+		value: isRecord$2(value) ? value : { _root: value },
+		errors
+	};
+}
+function findColon(s) {
+	let inQuote = null;
+	for (let i = 0; i < s.length; i++) {
+		const ch = s[i];
+		if (inQuote === "\"" && ch === "\\") {
+			i++;
+			continue;
+		}
+		if (inQuote) {
+			if (ch === inQuote) inQuote = null;
+		} else if (ch === "\"" || ch === "'") inQuote = ch;
+		else if (ch === ":") return i;
+	}
+	return -1;
+}
+/** Reverse the backslash escapes an emitter applies to a quoted scalar
+* (`\n`, `\t`, `\r`, `\"`, `\\`), so values with newlines/quotes round-trip. */
+function unescapeScalar(s) {
+	return s.replace(/\\(.)/g, (_, c) => c === "n" ? "\n" : c === "t" ? "	" : c === "r" ? "\r" : c);
+}
+/** Split a flow-sequence body (`a, "b, c", [d, e]`) on top-level commas, keeping
+* commas inside quotes or a nested `[...]` intact. Empty segments (from a leading,
+* trailing, or doubled comma, or an empty `[]` body) are dropped, matching YAML;
+* a quoted empty string keeps its quotes and so survives. */
+function splitFlow(body) {
+	const parts = [];
+	let depth = 0;
+	let inQuote = null;
+	let cur = "";
+	for (let i = 0; i < body.length; i++) {
+		const ch = body[i];
+		if (inQuote === "\"" && ch === "\\") {
+			cur += ch + (body[i + 1] ?? "");
+			i++;
+			continue;
+		}
+		if (inQuote) {
+			if (ch === inQuote) inQuote = null;
+			cur += ch;
+		} else if (ch === "\"" || ch === "'") {
+			inQuote = ch;
+			cur += ch;
+		} else if (ch === "[") {
+			depth++;
+			cur += ch;
+		} else if (ch === "]") {
+			depth--;
+			cur += ch;
+		} else if (ch === "," && depth === 0) {
+			parts.push(cur);
+			cur = "";
+		} else cur += ch;
+	}
+	parts.push(cur);
+	return parts.map((p) => p.trim()).filter((p) => p !== "");
+}
+function parseScalar(text) {
+	if (text.startsWith("[") && text.endsWith("]") && text.length >= 2) return splitFlow(text.slice(1, -1)).map(parseScalar);
+	if (text.startsWith("\"") && text.endsWith("\"") && text.length >= 2) return unescapeScalar(text.slice(1, -1));
+	if (text.startsWith("'") && text.endsWith("'") && text.length >= 2) return text.slice(1, -1);
+	if (text === "true") return true;
+	if (text === "false") return false;
+	if (text === "null" || text === "~") return null;
+	if (/^-?\d+(\.\d+)?$/.test(text)) return Number(text);
+	return text;
+}
+function isRecord$2(x) {
+	return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+
+//#endregion
+//#region src/frontend/argtype/template.ts
+/**
+* Index of the `}` that closes an interpolation opened at `open` (the position
+* just past the `{`), or -1 if unterminated. A naive `indexOf("}")` would stop
+* at the first `}` even when it sits inside a quoted ref name (`{"a}b"}`) or a
+* quoted operation argument (`{a.or("{b}")}`); this scan skips double-quoted
+* spans (honoring `\"`) and balances nested `{}` so those round-trip.
+*/
+function interpolationEnd(body, open) {
+	let depth = 1;
+	let inQuote = false;
+	for (let j = open; j < body.length; j++) {
+		const c = body[j];
+		if (inQuote) {
+			if (c === "\\") j++;
+			else if (c === "\"") inQuote = false;
+			continue;
+		}
+		if (c === "\"") inQuote = true;
+		else if (c === "{") depth++;
+		else if (c === "}" && --depth === 0) return j;
+	}
+	return -1;
+}
+function parseTemplate(body) {
+	const tokens = [];
+	const errors = [];
+	let lit = "";
+	let i = 0;
+	const flushLit = () => {
+		if (lit.length > 0) {
+			tokens.push({
+				kind: "literal",
+				value: lit
+			});
+			lit = "";
+		}
+	};
+	while (i < body.length) {
+		const ch = body[i];
+		if (ch === "\\" && i + 1 < body.length) {
+			const next = body[i + 1];
+			lit += next === "{" || next === "}" || next === "`" || next === "\\" ? next : "\\" + next;
+			i += 2;
+			continue;
+		}
+		if (ch === "{") {
+			const close = interpolationEnd(body, i + 1);
+			if (close === -1) {
+				errors.push("Unterminated '{' in output template");
+				lit += body.slice(i);
+				break;
+			}
+			flushLit();
+			const { token, error } = parseRef(body.slice(i + 1, close).trim());
+			if (error) errors.push(error);
+			tokens.push(token);
+			i = close + 1;
+		} else {
+			lit += ch;
+			i++;
+		}
+	}
+	flushLit();
+	return {
+		tokens,
+		errors
+	};
+}
+/** Parse the inside of `{...}`: an optional name followed by `.op(arg)` calls.
+* The name is a bare identifier, a double-quoted string (for a non-identifier
+* target name, e.g. `{"4d_output"}`), or absent for a self-reference (`{}`). */
+function parseRef(inner) {
+	const token = { kind: "ref" };
+	let rest = inner;
+	const quoted = /^"((?:[^"\\]|\\.)*)"/.exec(inner);
+	if (quoted) {
+		token.name = unescapeArg(quoted[1]);
+		rest = inner.slice(quoted[0].length);
+	} else {
+		const nameMatch = /^[A-Za-z_][A-Za-z0-9_]*/.exec(inner);
+		if (nameMatch) {
+			token.name = nameMatch[0];
+			rest = inner.slice(nameMatch[0].length);
+		}
+	}
+	const opRe = /^\.\s*([A-Za-z_]+)\s*\(\s*(?:"((?:[^"\\]|\\.)*)")?\s*\)/;
+	let error;
+	while (rest.length > 0) {
+		const m = opRe.exec(rest);
+		if (!m) {
+			error = `Unrecognized output-reference operation near '${rest}'`;
+			break;
+		}
+		const op = m[1];
+		const arg = m[2];
+		switch (op) {
+			case "strip_suffix":
+				if (arg !== void 0) (token.stripSuffix ??= []).push(unescapeArg(arg));
+				break;
+			case "strip_prefix":
+				if (arg !== void 0) (token.stripPrefix ??= []).push(unescapeArg(arg));
+				break;
+			case "basename":
+				token.basename = true;
+				break;
+			case "or":
+				if (arg !== void 0) token.or = unescapeArg(arg);
+				break;
+			default: error = `Unknown output-reference operation '${op}'`;
+		}
+		rest = rest.slice(m[0].length).trimStart();
+	}
+	return {
+		token,
+		...error && { error }
+	};
+}
+function unescapeArg(s) {
+	return s.replace(/\\(.)/g, "$1");
+}
+
+//#endregion
+//#region src/frontend/argtype/doc.ts
+/**
+* Reflow a `///` description as Markdown-style prose: a single line break is a
+* soft wrap (the lines join with a space) and a blank line starts a new
+* paragraph (kept as `\n\n`). This lets an author wrap a long description across
+* several `///` lines for readability without forcing hard breaks, while real
+* paragraph structure survives. (It does not preserve Markdown lists or indented
+* code blocks - their single line breaks are joined like ordinary prose.)
+*/
+function reflowProse(text) {
+	return text.split(/\n{2,}/).map((para) => para.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join(" ")).filter((para) => para.length > 0).join("\n\n");
+}
+/**
+* Split a `///` doc block into title + description. A leading Markdown H1
+* (`# Title` on the first line) is the title; everything after it is the
+* description. Without a leading `# `, the whole block is the description (no
+* title). The description is reflowed as prose (see `reflowProse`): single line
+* breaks soft-wrap, blank lines separate paragraphs.
+*/
+function splitDocText(raw) {
+	const newline = raw.indexOf("\n");
+	const firstLine = (newline === -1 ? raw : raw.slice(0, newline)).trim();
+	if (firstLine.startsWith("# ")) {
+		const title = firstLine.slice(2).trim();
+		const description = reflowProse(newline === -1 ? "" : raw.slice(newline + 1));
+		return {
+			...title && { title },
+			...description && { description }
+		};
+	}
+	const description = reflowProse(raw);
+	return description ? { description } : {};
+}
+
+//#endregion
+//#region src/frontend/argtype/parser.ts
+/** Split a `///` block and attach its title/description to a node. Per the spec,
+* the block "is applied first and wins": for each field the block provides it
+* overrides a value a chained `.title()`/`.description()` already set, while a
+* field the block leaves unset keeps whatever the chain supplied. */
+function attachDocText(target, raw) {
+	const { title, description } = splitDocText(raw);
+	if (title !== void 0) target.title = title;
+	if (description !== void 0) target.description = description;
+}
+const COMBINATORS = new Set([
+	"seq",
+	"set",
+	"opt",
+	"rep",
+	"alt",
+	"any"
+]);
+const TERMINALS = new Set([
+	"int",
+	"float",
+	"str",
+	"path"
+]);
+/** Core + supported-extension chaining methods. Anything else is an extension
+* we don't implement and is parsed-and-ignored (the spec's "ignorable" rule). */
+const KNOWN_METHODS = new Set([
+	"name",
+	"title",
+	"description",
+	"default",
+	"min",
+	"max",
+	"join",
+	"count",
+	"countMin",
+	"countMax",
+	"mediaType",
+	"mutable",
+	"resolveParent"
+]);
+/** Levenshtein edit distance between two strings. */
+function editDistance(a, b) {
+	const m = a.length;
+	const n = b.length;
+	let prev = Array.from({ length: n + 1 }, (_, j) => j);
+	for (let i = 1; i <= m; i++) {
+		const cur = [i];
+		for (let j = 1; j <= n; j++) cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+		prev = cur;
+	}
+	return prev[n];
+}
+/** The closest candidate to `name` within a small edit distance, for a "did you
+* mean?" hint on an unknown method. Returns undefined when nothing is close
+* enough, so a deliberate unknown-extension method gets no spurious suggestion.
+* A typo (`reqires`, `mediaTpe`) lands within distance 2 of a real method; an
+* unrelated extension method (`conflicts`) does not. The `bestDist < name.length`
+* clause additionally stops a very short unknown name from matching a longer
+* method by pure insertion (a 1-char `.n()` is not "did you mean `.min()`"). */
+function suggestMethod(name, candidates) {
+	let best;
+	let bestDist = Infinity;
+	for (const c of candidates) {
+		const d = editDistance(name, c);
+		if (d < bestDist) {
+			bestDist = d;
+			best = c;
+		}
+	}
+	return best !== void 0 && bestDist <= 2 && bestDist < name.length ? best : void 0;
+}
+var Parser = class {
+	tokens;
+	pos = 0;
+	errors = [];
+	warnings = [];
+	constructor(tokens) {
+		this.tokens = tokens;
+	}
+	peek(o = 0) {
+		return this.tokens[Math.min(this.pos + o, this.tokens.length - 1)];
+	}
+	at(kind) {
+		return this.peek().kind === kind;
+	}
+	next() {
+		return this.tokens[this.pos++] ?? this.tokens[this.tokens.length - 1];
+	}
+	expect(kind, what) {
+		if (this.at(kind)) return this.next();
+		const tok = this.peek();
+		this.error(`Expected ${what} but found '${tok.value || tok.kind}'`, tok);
+		return tok;
+	}
+	error(message, tok = this.peek()) {
+		this.errors.push({
+			message,
+			line: tok.line,
+			column: tok.column
+		});
+	}
+	warn(message, tok = this.peek()) {
+		this.warnings.push({
+			message,
+			line: tok.line,
+			column: tok.column
+		});
+	}
+	parseDocument(frontmatter) {
+		const aliases = [];
+		let rootName;
+		let root;
+		while (!this.at("eof")) {
+			const docs = this.collectDocs();
+			if (this.at("eof")) break;
+			const labelLike = this.at("ident") || this.at("string");
+			const following = this.peek(1).kind;
+			if (labelLike && following === "eq") {
+				const nameTok = this.next();
+				if (nameTok.kind === "string") this.error("Alias names must be identifiers, not quoted strings", nameTok);
+				this.next();
+				const expr = this.parseElement();
+				if (docs) attachDocText(expr, docs);
+				aliases.push({
+					name: nameTok.value,
+					expr
+				});
+				continue;
+			}
+			if (labelLike && following === "colon") {
+				const nameTok = this.next();
+				this.next();
+				const expr = this.parseElement();
+				if (docs) attachDocText(expr, docs);
+				if (root) this.error(`Multiple root definitions; '${nameTok.value}' ignored (already have '${rootName ?? "<anonymous>"}')`, nameTok);
+				else {
+					rootName = nameTok.value;
+					root = expr;
+					if (!root.name) root.name = nameTok.value;
+				}
+				continue;
+			}
+			if (!this.at("ident") && !this.at("string") && !this.at("lparen")) {
+				this.error("Expected a definition (name: expr), an alias (Name = expr), or a root expression");
+				break;
+			}
+			const expr = this.parseElement();
+			if (docs) attachDocText(expr, docs);
+			if (root) {
+				this.error("Multiple root definitions; a second top-level expression is not allowed");
+				break;
+			}
+			root = expr;
+		}
+		if (!root) {
+			this.error("No root definition (expected `name: expr` or a bare root expression)");
+			return;
+		}
+		return {
+			...frontmatter && { frontmatter },
+			aliases,
+			...rootName !== void 0 && { rootName },
+			root
+		};
+	}
+	/** Collect consecutive `///` doc lines, joined with newlines. */
+	collectDocs() {
+		const lines = [];
+		while (this.at("doc")) lines.push(this.next().value);
+		return lines.length > 0 ? lines.join("\n") : void 0;
+	}
+	/**
+	* An element is the unit inside a comma list: an optionally-named expression.
+	* `label:` is looser than `|`, so a name binds the whole alternative that
+	* follows it.
+	*/
+	parseElement() {
+		if ((this.at("ident") || this.at("string")) && this.peek(1).kind === "colon") {
+			const nameTok = this.next();
+			this.next();
+			const inner = this.parseElement();
+			inner.name = nameTok.value;
+			return inner;
+		}
+		return this.parseAlt();
+	}
+	parseAlt() {
+		const first = this.parseChain();
+		if (!this.at("pipe")) return first;
+		const alts = [first];
+		while (this.at("pipe")) {
+			this.next();
+			alts.push(this.parseChain());
+		}
+		return {
+			kind: "comb",
+			op: "alt",
+			children: alts,
+			...first.span && { span: first.span }
+		};
+	}
+	parseChain() {
+		const node = this.parsePrimary();
+		while (this.at("dot")) {
+			this.next();
+			this.applyMethod(node);
+		}
+		if (this.at("eq")) {
+			this.next();
+			node.default = this.parseValue();
+		}
+		return node;
+	}
+	parsePrimary() {
+		const tok = this.peek();
+		const span = {
+			line: tok.line,
+			column: tok.column
+		};
+		if (tok.kind === "string") {
+			this.next();
+			return {
+				kind: "literal",
+				value: tok.value,
+				span
+			};
+		}
+		if (tok.kind === "lparen") return {
+			kind: "comb",
+			op: "seq",
+			children: this.parseParenList(),
+			span
+		};
+		if (tok.kind === "ident") {
+			if (COMBINATORS.has(tok.value) && this.peek(1).kind === "lparen") {
+				this.next();
+				const children = this.parseParenList();
+				return {
+					kind: "comb",
+					op: tok.value,
+					children,
+					span
+				};
+			}
+			if (TERMINALS.has(tok.value)) {
+				this.next();
+				return {
+					kind: "terminal",
+					terminal: tok.value,
+					span
+				};
+			}
+			this.next();
+			return {
+				kind: "ref",
+				refName: tok.value,
+				span
+			};
+		}
+		this.error(`Unexpected token '${tok.value || tok.kind}' in expression`, tok);
+		this.next();
+		return {
+			kind: "literal",
+			value: "",
+			span
+		};
+	}
+	/** Parse `( elem, elem, ... )` with optional leading docs and trailing comma. */
+	parseParenList() {
+		this.expect("lparen", "'('");
+		const items = [];
+		while (!this.at("rparen") && !this.at("eof")) {
+			const docs = this.collectDocs();
+			if (this.at("rparen")) break;
+			const elem = this.parseElement();
+			if (docs) attachDocText(elem, docs);
+			items.push(elem);
+			if (this.at("comma")) this.next();
+			else break;
+		}
+		this.expect("rparen", "')'");
+		return items;
+	}
+	applyMethod(node) {
+		const nameTok = this.expect("ident", "a method name");
+		const method = nameTok.value;
+		if (method === "output") {
+			node.outputs = [...node.outputs ?? [], ...this.parseOutputArgs()];
+			return;
+		}
+		if (!KNOWN_METHODS.has(method)) {
+			this.skipBalancedArgs();
+			const hint = suggestMethod(method, [...KNOWN_METHODS, "output"]);
+			this.warn(`Ignoring unsupported method '.${method}()'` + (hint ? ` (did you mean '.${hint}()'?)` : ""), nameTok);
+			return;
+		}
+		const args = this.parseScalarArgs();
+		switch (method) {
+			case "name":
+				if (typeof args[0] === "string") node.name = args[0];
+				break;
+			case "title":
+				if (typeof args[0] === "string") node.title = args[0];
+				break;
+			case "description":
+				if (typeof args[0] === "string") node.description = args[0];
+				break;
+			case "default":
+				if (args[0] !== void 0) node.default = args[0];
+				break;
+			case "min":
+				if (typeof args[0] === "number") node.min = args[0];
+				break;
+			case "max":
+				if (typeof args[0] === "number") node.max = args[0];
+				break;
+			case "join":
+				node.join = typeof args[0] === "string" ? args[0] : "";
+				break;
+			case "count":
+				if (typeof args[0] === "number") {
+					node.countMin = args[0];
+					node.countMax = args[0];
+				}
+				break;
+			case "countMin":
+				if (typeof args[0] === "number") node.countMin = args[0];
+				break;
+			case "countMax":
+				if (typeof args[0] === "number") node.countMax = args[0];
+				break;
+			case "mediaType":
+				if (typeof args[0] === "string") (node.mediaTypes ??= []).push(args[0]);
+				break;
+			case "mutable":
+				node.mutable = true;
+				break;
+			case "resolveParent":
+				node.resolveParent = true;
+				break;
+		}
+	}
+	/** Parse a parenthesized list of plain scalar arguments (numbers / strings). */
+	parseScalarArgs() {
+		this.expect("lparen", "'('");
+		const args = [];
+		while (!this.at("rparen") && !this.at("eof")) {
+			args.push(this.parseValue());
+			if (this.at("comma")) this.next();
+			else break;
+		}
+		this.expect("rparen", "')'");
+		return args;
+	}
+	/** Consume a balanced `( ... )` group without interpreting its contents.
+	* Used to skip the arguments of an unsupported extension method. */
+	skipBalancedArgs() {
+		if (!this.at("lparen")) return;
+		let depth = 0;
+		do {
+			const tok = this.next();
+			if (tok.kind === "lparen") depth++;
+			else if (tok.kind === "rparen") depth--;
+			else if (tok.kind === "eof") break;
+		} while (depth > 0);
+	}
+	/** Parse the argument list of `.output(...)`: one or more template expressions. */
+	parseOutputArgs() {
+		this.expect("lparen", "'('");
+		const outputs = [];
+		while (!this.at("rparen") && !this.at("eof")) {
+			const docs = this.collectDocs();
+			if (this.at("rparen")) break;
+			const out = this.parseOutputTemplate();
+			if (docs) attachDocText(out, docs);
+			outputs.push(out);
+			if (this.at("comma")) this.next();
+			else break;
+		}
+		this.expect("rparen", "')'");
+		return outputs;
+	}
+	/** `label: \`tpl\`` or `\`tpl\`` followed by optional `.name(...)` / `.or(...)`. */
+	parseOutputTemplate() {
+		let name;
+		if ((this.at("ident") || this.at("string")) && this.peek(1).kind === "colon") {
+			name = this.next().value;
+			this.next();
+		}
+		const out = { tokens: [] };
+		if (this.at("template")) {
+			const tmplTok = this.next();
+			const { tokens, errors } = parseTemplate(tmplTok.value);
+			out.tokens = tokens;
+			for (const e of errors) this.error(e, tmplTok);
+		} else this.error(`Expected an output template literal`);
+		const CHAIN = new Set([
+			"name",
+			"or",
+			"title",
+			"description"
+		]);
+		while (this.at("dot")) {
+			this.next();
+			const m = this.expect("ident", "a template method");
+			if (CHAIN.has(m.value)) {
+				const arg = this.parseScalarArgs()[0];
+				if (typeof arg === "string") if (m.value === "name") name = arg;
+				else if (m.value === "or") out.fallback = arg;
+				else if (m.value === "title") out.title = arg;
+				else out.description = arg;
+			} else {
+				this.skipBalancedArgs();
+				const hint = suggestMethod(m.value, CHAIN);
+				this.warn(`Ignoring unsupported output-template method '.${m.value}()'` + (hint ? ` (did you mean '.${hint}()'?)` : ""), m);
+			}
+		}
+		if (name !== void 0) out.name = name;
+		return out;
+	}
+	parseValue() {
+		const tok = this.peek();
+		if (tok.kind === "string") {
+			this.next();
+			return tok.value;
+		}
+		if (tok.kind === "number") {
+			this.next();
+			return Number(tok.value);
+		}
+		this.error(`Expected a value (string or number) but found '${tok.value || tok.kind}'`, tok);
+		this.next();
+		return "";
+	}
+};
+function parseArgtype(source) {
+	const { frontmatter, body, errors: fmErrors } = splitFrontmatter(source);
+	const { tokens, errors: lexErrors } = lex(body);
+	const parser = new Parser(tokens);
+	const doc = parser.parseDocument(frontmatter);
+	const errors = [
+		...fmErrors.map((m) => ({ message: m })),
+		...lexErrors.map((e) => ({
+			message: e.message,
+			line: e.line,
+			column: e.column
+		})),
+		...parser.errors
+	];
+	return {
+		...doc && { doc },
+		errors,
+		warnings: parser.warnings
+	};
+}
+
+//#endregion
+//#region src/ir/builders.ts
+function lit(str) {
+	return {
+		kind: "literal",
+		attrs: { str }
+	};
+}
+function str(meta) {
+	return {
+		kind: "str",
+		attrs: {},
+		meta: normalizeMeta(meta)
+	};
+}
+function int(meta) {
+	return {
+		kind: "int",
+		attrs: {},
+		meta: normalizeMeta(meta)
+	};
+}
+function float(meta) {
+	return {
+		kind: "float",
+		attrs: {},
+		meta: normalizeMeta(meta)
+	};
+}
+function path(meta) {
+	return {
+		kind: "path",
+		attrs: {},
+		meta: normalizeMeta(meta)
+	};
+}
+function seq(...nodes) {
+	return {
+		kind: "sequence",
+		attrs: { nodes }
+	};
+}
+function seqJoin(join, ...nodes) {
+	return {
+		kind: "sequence",
+		attrs: {
+			nodes,
+			join
+		}
+	};
+}
+function opt(node, meta) {
+	return {
+		kind: "optional",
+		attrs: { node },
+		meta: normalizeMeta(meta)
+	};
+}
+function rep(node, meta) {
+	return {
+		kind: "repeat",
+		attrs: { node },
+		meta: normalizeMeta(meta)
+	};
+}
+function repJoin(join, node, meta) {
+	return {
+		kind: "repeat",
+		attrs: {
+			node,
+			join
+		},
+		meta: normalizeMeta(meta)
+	};
+}
+function alt(...alts) {
+	return {
+		kind: "alternative",
+		attrs: { alts }
+	};
+}
+function normalizeMeta(meta) {
+	if (meta === void 0) return void 0;
+	if (typeof meta === "string") return { name: meta };
+	return meta;
+}
+
+//#endregion
+//#region src/ir/meta.ts
+/** Construct a NodeRef from a node name. */
+function nodeRef(name) {
+	return {
+		kind: "node-ref",
+		name
+	};
+}
+/**
+* Produce a usable name for an Output. Frontends may leave `Output.name`
+* unset; downstream code (resolver, validator, backends) needs a stable
+* identifier for diagnostics and field naming. Falls back to `output_<index>`
+* keyed by the output's position in tree-walk order.
+*/
+function effectiveOutputName(output, index) {
+	return output.name ?? `output_${index}`;
+}
+
+//#endregion
+//#region src/frontend/argtype/lower.ts
+/**
+* Lower an `AstDocument` to Styx IR (`Expr` + `AppMeta`).
+*
+* Mapping highlights:
+* - Combinators map 1:1 except `set` -> `sequence` (order-not-meaningful is not
+*   modeled in the IR) and `any` -> its first branch (the spec's "emit branch 0"
+*   rule; the interchangeable alternatives are dropped with a warning).
+* - Aliases are resolved by substitution with cycle detection.
+* - `.output(...)` declarations attach to the nearest enclosing sequence scope,
+*   so an output nested in a repeat / subcommand keeps its list / struct shape
+*   (per-output gating is recovered downstream from each ref binding's gate).
+*/
+/** Spread a node's span into a diagnostic (no-op when the node has no span). */
+function at(span) {
+	return span ? {
+		line: span.line,
+		column: span.column
+	} : {};
+}
+/** Build IR `Documentation` from an AST node's already-split title/description. */
+function docFrom(node) {
+	const doc = {
+		...node.title && { title: node.title },
+		...node.description && { description: node.description }
+	};
+	return Object.keys(doc).length > 0 ? doc : void 0;
+}
+var Lowerer = class {
+	errors = [];
+	warnings = [];
+	aliases = /* @__PURE__ */ new Map();
+	constructor(aliases) {
+		for (const a of aliases) {
+			if (this.aliases.has(a.name)) this.warn(`Duplicate alias '${a.name}'; last definition wins`, a.expr);
+			this.aliases.set(a.name, a.expr);
+		}
+	}
+	/** Record an error, located at `node`'s span when one is available. */
+	err(message, node) {
+		this.errors.push({
+			message,
+			...at(node?.span)
+		});
+	}
+	/** Record a warning, located at `node`'s span when one is available. */
+	warn(message, node) {
+		this.warnings.push({
+			message,
+			...at(node?.span)
+		});
+	}
+	lower(doc) {
+		const rootSink = [];
+		const expr = this.lowerNode(doc.root, /* @__PURE__ */ new Set(), void 0, rootSink);
+		const root = expr.kind === "sequence" ? expr : seq(expr);
+		if (root !== expr) root.meta = { ...doc.root.name && { name: doc.root.name } };
+		if (rootSink.length > 0) root.meta = {
+			...root.meta,
+			outputs: [...root.meta?.outputs ?? [], ...rootSink]
+		};
+		return {
+			expr: root,
+			errors: this.errors,
+			warnings: this.warnings
+		};
+	}
+	/**
+	* @param expanding - alias names currently being expanded (cycle guard).
+	* @param selfName - nearest enclosing named node, for `{}` self-references.
+	* @param sink - outputs array of the nearest enclosing sequence; a `.output()`
+	*   on this node attaches here (seq/set nodes instead own their outputs).
+	*/
+	lowerNode(node, expanding, selfName, sink) {
+		if (node.kind === "ref") return this.lowerRef(node, expanding, selfName, sink);
+		const name = node.name ?? selfName;
+		const joinable = node.kind === "comb" && (node.op === "seq" || node.op === "set" || node.op === "rep" || node.op === "opt");
+		if (node.join !== void 0 && !joinable) this.err("`.join()` is only supported on seq/set/rep/opt", node);
+		const isNumericTerminal = node.kind === "terminal" && (node.terminal === "int" || node.terminal === "float");
+		const isRep = node.kind === "comb" && node.op === "rep";
+		const isPath = node.kind === "terminal" && node.terminal === "path";
+		if ((node.min !== void 0 || node.max !== void 0) && !isNumericTerminal) this.err("`.min()`/`.max()` is only supported on int/float terminals", node);
+		if ((node.countMin !== void 0 || node.countMax !== void 0) && !isRep) this.err("`.count()`/`.countMin()`/`.countMax()` is only supported on rep", node);
+		if ((node.mutable || node.resolveParent) && !isPath) this.err("`.mutable()`/`.resolveParent()` is only supported on path", node);
+		if (node.mediaTypes?.length && !isPath) this.err("`.mediaType()` is only supported on path", node);
+		const isStruct = node.kind === "comb" && (node.op === "seq" || node.op === "set");
+		if (node.default !== void 0 && isStruct) {
+			this.warn("`= value` / `.default()` is not supported on a seq/set struct; ignored", node);
+			node.default = void 0;
+		}
+		const isSeqSet = node.kind === "comb" && (node.op === "seq" || node.op === "set");
+		if (node.outputs?.length && !isSeqSet) for (const o of node.outputs) sink.push(this.toOutput(o, name));
+		switch (node.kind) {
+			case "literal": {
+				const e = lit(node.value ?? "");
+				this.applyMeta(e, node);
+				return e;
+			}
+			case "terminal": return this.lowerTerminal(node);
+			case "comb": return this.lowerComb(node, expanding, name, sink);
+			default:
+				this.err(`Unknown AST node kind '${node.kind}'`, node);
+				return seq();
+		}
+	}
+	lowerRef(node, expanding, selfName, sink) {
+		const target = node.refName;
+		const aliasExpr = this.aliases.get(target);
+		if (!aliasExpr) {
+			this.err(`Unknown alias '${target}'`, node);
+			return seq();
+		}
+		if (expanding.has(target)) {
+			this.err(`Recursive alias '${target}' is not allowed`, node);
+			return seq();
+		}
+		const clone = structuredClone(aliasExpr);
+		clone.span = node.span ?? clone.span;
+		clone.name = node.name ?? clone.name;
+		clone.title = node.title ?? clone.title;
+		clone.description = node.description ?? clone.description;
+		if (node.default !== void 0) clone.default = node.default;
+		if (node.min !== void 0) clone.min = node.min;
+		if (node.max !== void 0) clone.max = node.max;
+		if (node.join !== void 0) clone.join = node.join;
+		if (node.countMin !== void 0) clone.countMin = node.countMin;
+		if (node.countMax !== void 0) clone.countMax = node.countMax;
+		if (node.mediaTypes?.length) clone.mediaTypes = [...clone.mediaTypes ?? [], ...node.mediaTypes];
+		if (node.mutable) clone.mutable = true;
+		if (node.resolveParent) clone.resolveParent = true;
+		if (node.outputs?.length) clone.outputs = [...clone.outputs ?? [], ...node.outputs];
+		const next = new Set(expanding);
+		next.add(target);
+		return this.lowerNode(clone, next, selfName, sink);
+	}
+	lowerTerminal(node) {
+		switch (node.terminal) {
+			case "int": {
+				const e = int();
+				this.checkBounds(node.min, node.max, "value", "min", "max", node);
+				if (node.min !== void 0) e.attrs.minValue = node.min;
+				if (node.max !== void 0) e.attrs.maxValue = node.max;
+				this.applyMeta(e, node);
+				return e;
+			}
+			case "float": {
+				const e = float();
+				this.checkBounds(node.min, node.max, "value", "min", "max", node);
+				if (node.min !== void 0) e.attrs.minValue = node.min;
+				if (node.max !== void 0) e.attrs.maxValue = node.max;
+				this.applyMeta(e, node);
+				return e;
+			}
+			case "str": {
+				const e = str();
+				this.applyMeta(e, node);
+				return e;
+			}
+			case "path": {
+				const e = path();
+				if (node.mediaTypes?.length) e.attrs.mediaTypes = node.mediaTypes;
+				if (node.mutable) e.attrs.mutable = true;
+				if (node.resolveParent) e.attrs.resolveParent = true;
+				this.applyMeta(e, node);
+				return e;
+			}
+			default:
+				this.err(`Unknown terminal '${String(node.terminal)}'`, node);
+				return str();
+		}
+	}
+	lowerComb(node, expanding, name, sink) {
+		const children = node.children ?? [];
+		const lowerChildren = (s) => children.map((c) => this.lowerNode(c, expanding, name, s));
+		switch (node.op) {
+			case "seq":
+			case "set": {
+				const selfOutputs = [];
+				for (const o of node.outputs ?? []) selfOutputs.push(this.toOutput(o, name));
+				const lowered = lowerChildren(selfOutputs);
+				this.dedupeSiblingNames(lowered, node);
+				const e = seq(...lowered);
+				if (node.join !== void 0) e.attrs.join = node.join;
+				this.applyMeta(e, node);
+				if (selfOutputs.length > 0) e.meta = {
+					...e.meta,
+					outputs: [...e.meta?.outputs ?? [], ...selfOutputs]
+				};
+				return e;
 			}
-			const alt = {
-				kind: "alternative",
-				attrs: { alts: altMembers }
-			};
-			const isRequired = group.required === true;
-			let groupNode;
-			if (isRequired) groupNode = alt;
-			else groupNode = {
-				kind: "optional",
-				attrs: { node: alt }
-			};
-			const groupName = (isString$3(group.title) ? group.title : void 0) ?? (memberDests.length === 2 ? `${memberDests[0]}_or_${memberDests[1]}` : `${memberDests[0]}_choice`);
-			groupNode.meta = {
-				...groupNode.meta,
-				name: groupName
-			};
-			const firstDest = memberDests[0];
-			const firstIdx = nodes.findIndex((n) => n === nodesByDest.get(firstDest));
-			if (firstIdx >= 0) nodes.splice(firstIdx, 0, groupNode);
-			else nodes.push(groupNode);
+			case "alt": {
+				const arms = lowerChildren(sink);
+				this.dedupeSiblingNames(arms, node);
+				const e = alt(...arms);
+				this.applyMeta(e, node);
+				return e;
+			}
+			case "any": {
+				if (children.length === 0) {
+					this.err("`any(...)` requires at least one branch", node);
+					return seq();
+				}
+				const e = this.lowerNode(children[0], expanding, name, sink);
+				if (node.name) e.meta = {
+					...e.meta,
+					name: node.name
+				};
+				{
+					const d = docFrom(node);
+					if (d) e.meta = {
+						...e.meta,
+						doc: d
+					};
+				}
+				return e;
+			}
+			case "opt": {
+				const inner = this.wrapChildren(children, expanding, name, sink);
+				if (node.join !== void 0 && (inner.kind === "sequence" || inner.kind === "repeat")) inner.attrs.join = node.join;
+				const e = opt(inner);
+				this.applyMeta(e, node);
+				if (inner.kind === "literal") e.meta = {
+					...e.meta,
+					defaultValue: false
+				};
+				return e;
+			}
+			case "rep": {
+				const e = rep(this.wrapChildren(children, expanding, name, sink));
+				if (node.join !== void 0) e.attrs.join = node.join;
+				this.checkBounds(node.countMin, node.countMax, "repetition count", "countMin", "countMax", node);
+				if (node.countMin !== void 0) e.attrs.countMin = node.countMin;
+				if (node.countMax !== void 0) e.attrs.countMax = node.countMax;
+				this.applyMeta(e, node);
+				return e;
+			}
+			default:
+				this.err(`Unknown combinator '${String(node.op)}'`, node);
+				return seq();
 		}
-		return nodes.filter((n) => {
-			for (const [dest, node] of nodesByDest) if (node === n && excluded.has(dest)) return false;
-			return true;
-		});
 	}
-	parseParserInfo(descriptor) {
-		const actions = descriptor.actions;
-		if (!isArray$3(actions)) return {
-			kind: "sequence",
-			attrs: { nodes: [] }
+	/** Warn on an inverted `[min, max]` pair (a lower bound above its upper
+	* bound), which yields an unsatisfiable constraint downstream. */
+	checkBounds(min, max, what, minLabel, maxLabel, node) {
+		if (min !== void 0 && max !== void 0 && min > max) this.warn(`Inverted ${what} bounds: ${minLabel} (${min}) > ${maxLabel} (${max})`, node);
+	}
+	/**
+	* Disambiguate duplicate explicit names among the direct children of a
+	* sequence/set (struct fields) or the arms of an alternative (union
+	* discriminants). The solver turns each named child into a struct field / union
+	* variant keyed by its name; two siblings with the same name would silently
+	* collapse (the second overwrites the first, dropping a parameter). argtype is
+	* hand-authored
+	* and gives no uniqueness guarantee, so - like the mrtrix frontend - we rename
+	* collisions (`name_2`, `name_3`, ...) and warn. (This catches duplicate
+	* explicit labels; it does not detect collisions between solver-derived names
+	* of otherwise-unnamed children, which the solver also does not guard.)
+	*/
+	dedupeSiblingNames(children, parent) {
+		const used = /* @__PURE__ */ new Set();
+		for (const child of children) {
+			const nm = child.meta?.name;
+			if (nm === void 0) continue;
+			if (!used.has(nm)) {
+				used.add(nm);
+				continue;
+			}
+			let n = 2;
+			while (used.has(`${nm}_${n}`)) n++;
+			const renamed = `${nm}_${n}`;
+			used.add(renamed);
+			child.meta = {
+				...child.meta,
+				name: renamed
+			};
+			this.warn(`Duplicate sibling name '${nm}'; renamed one occurrence to '${renamed}'`, parent);
+		}
+	}
+	/** `opt`/`rep` with multiple children implicitly wrap them in a sequence,
+	* which - like any sequence - is the output scope for those children. */
+	wrapChildren(children, expanding, name, sink) {
+		if (children.length === 1) return this.lowerNode(children[0], expanding, name, sink);
+		const selfOutputs = [];
+		const e = seq(...children.map((c) => this.lowerNode(c, expanding, name, selfOutputs)));
+		if (selfOutputs.length > 0) e.meta = {
+			...e.meta,
+			outputs: selfOutputs
 		};
-		const positionals = [];
-		const optionals = [];
-		const actionsByDest = /* @__PURE__ */ new Map();
-		const nodesByDest = /* @__PURE__ */ new Map();
-		for (const rawAction of actions) {
-			if (!isObject$3(rawAction)) continue;
-			const node = this.buildAction(rawAction);
-			if (!node) continue;
-			const dest = rawAction.dest;
-			if (isString$3(dest)) {
-				actionsByDest.set(dest, rawAction);
-				nodesByDest.set(dest, node);
+		return e;
+	}
+	/** Fold an AST node's name/doc/default decorations onto an IR node's meta. */
+	applyMeta(e, node) {
+		const meta = {};
+		if (node.name) meta.name = node.name;
+		const doc = docFrom(node);
+		if (doc) meta.doc = doc;
+		if (node.default !== void 0) meta.defaultValue = node.default;
+		if (Object.keys(meta).length > 0) e.meta = {
+			...e.meta,
+			...meta
+		};
+	}
+	toOutput(o, selfName) {
+		const tokens = [];
+		for (const t of o.tokens) {
+			if (t.kind === "literal") {
+				tokens.push({
+					kind: "literal",
+					value: t.value
+				});
+				continue;
 			}
-			if (this.isPositional(rawAction) && rawAction.action_type !== "parsers") positionals.push(node);
-			else optionals.push(node);
+			const targetName = t.name ?? selfName;
+			if (!targetName) {
+				this.warn("Output self-reference '{}' has no named node to resolve to; emitting empty");
+				tokens.push({
+					kind: "literal",
+					value: ""
+				});
+				continue;
+			}
+			if (t.stripPrefix?.length) this.warn("Output ref op 'strip_prefix' is not supported by the IR; ignored");
+			if (t.basename) this.warn("Output ref op 'basename' is not supported by the IR; ignored");
+			tokens.push({
+				kind: "ref",
+				target: nodeRef(targetName),
+				...t.stripSuffix?.length && { stripExtensions: t.stripSuffix },
+				...t.or !== void 0 && { fallback: t.or }
+			});
 		}
-		let allNodes = [...positionals, ...optionals];
-		const mutexGroups = descriptor.mutually_exclusive_groups;
-		if (isArray$3(mutexGroups) && mutexGroups.length > 0) allNodes = this.applyMutualExclusion(actionsByDest, mutexGroups, allNodes, nodesByDest);
+		if (o.fallback !== void 0) this.warn("Output-level '.or(...)' fallback is not supported by the IR; ignored");
+		const doc = docFrom(o);
 		return {
-			kind: "sequence",
-			attrs: { nodes: allNodes }
+			...o.name && { name: o.name },
+			...doc && { doc },
+			tokens
 		};
 	}
-	parse(source, _filename) {
-		this.reset();
-		const descriptor = this.parseJSON(source);
-		if (descriptor === null) return {
-			expr: {
-				kind: "sequence",
-				attrs: { nodes: [] }
-			},
-			errors: this.errors,
-			warnings: this.warnings
+};
+function buildAppMeta(fm, rootDoc, rootName) {
+	const warnings = [];
+	const rootTitleDesc = docFrom(rootDoc);
+	if (!fm) {
+		const meta = {
+			...rootName && { id: rootName },
+			...rootTitleDesc && { doc: rootTitleDesc }
 		};
-		const meta = this.buildAppMeta(descriptor);
-		if (!meta) {
-			this.error("Descriptor is missing prog");
-			return {
-				expr: {
-					kind: "sequence",
-					attrs: { nodes: [] }
-				},
-				errors: this.errors,
-				warnings: this.warnings
-			};
-		}
-		const expr = this.parseParserInfo(descriptor);
-		if (expr === null) {
-			this.error("Failed to parse argument structure");
-			return {
-				expr: {
-					kind: "sequence",
-					attrs: { nodes: [] }
-				},
-				errors: this.errors,
-				warnings: this.warnings
-			};
-		}
-		const prog = descriptor.prog;
-		if (isString$3(prog) && prog) expr.attrs.nodes.unshift({
-			kind: "literal",
-			attrs: { str: prog }
-		});
-		if (!expr.meta?.name && meta.id) expr.meta = {
-			...expr.meta,
-			name: meta.id
+		return Object.keys(meta).length > 0 ? {
+			meta,
+			warnings
+		} : { warnings };
+	}
+	const asStr = (x) => typeof x === "string" && x.length > 0 ? x : void 0;
+	const id = asStr(rootName) ?? asStr(fm.exe) ?? asStr(fm.id);
+	const version = asStr(fm.version) ?? (typeof fm.version === "number" ? String(fm.version) : void 0);
+	const strList = (x) => Array.isArray(x) ? x.filter((a) => typeof a === "string") : [];
+	const authors = strList(fm.authors);
+	const urls = strList(fm.urls);
+	const references = strList(fm.references);
+	const checkList = (key, v) => {
+		if (v !== void 0 && v !== null && !Array.isArray(v)) warnings.push(`Frontmatter '${key}' should be a list; got a scalar - ignored`);
+	};
+	checkList("authors", fm.authors);
+	checkList("urls", fm.urls);
+	checkList("references", fm.references);
+	if (fm.version !== void 0 && fm.version !== null && version === void 0) warnings.push(`Frontmatter 'version' should be a string or number; ignored`);
+	if (fm.container !== void 0 && fm.container !== null) {
+		if (!isRecord$1(fm.container)) warnings.push(`Frontmatter 'container' should be a mapping with an 'image'; ignored`);
+		else if (!asStr(fm.container.image)) warnings.push(`Frontmatter 'container' is missing an 'image'; ignored`);
+	}
+	const doc = {
+		...rootTitleDesc,
+		...authors.length > 0 && { authors },
+		...urls.length > 0 && { urls },
+		...references.length > 0 && { literature: references }
+	};
+	const meta = {
+		...id && { id },
+		...version && { version },
+		...Object.keys(doc).length > 0 && { doc }
+	};
+	if (isRecord$1(fm.container)) {
+		const image = asStr(fm.container.image);
+		const type = asStr(fm.container.type);
+		if (image) meta.container = {
+			image,
+			...type === "docker" || type === "singularity" ? { type } : {}
 		};
+	}
+	meta.stdout = streamFrom(fm.stdout, warnings, "stdout");
+	meta.stderr = streamFrom(fm.stderr, warnings, "stderr");
+	if (!meta.stdout) delete meta.stdout;
+	if (!meta.stderr) delete meta.stderr;
+	return {
+		meta,
+		warnings
+	};
+}
+function streamFrom(x, warnings, key) {
+	if (x === void 0 || x === null) return void 0;
+	if (isRecord$1(x)) {
+		const name = typeof x.name === "string" ? x.name : void 0;
+		if (!name) {
+			warnings.push(`Frontmatter '${key}' is missing a 'name'; ignored`);
+			return;
+		}
+		const description = typeof x.description === "string" ? x.description : void 0;
 		return {
-			meta,
-			expr,
-			errors: this.errors,
-			warnings: this.warnings
+			name,
+			...description && { doc: { description } }
 		};
 	}
-};
+	if (typeof x === "string") return { name: x };
+	warnings.push(`Frontmatter '${key}' has an unexpected shape; ignored`);
+}
+function isRecord$1(x) {
+	return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+function lowerDocument(doc) {
+	const result = new Lowerer(doc.aliases).lower(doc);
+	const exe = typeof doc.frontmatter?.exe === "string" ? doc.frontmatter.exe : void 0;
+	if (exe) result.expr.attrs.nodes.unshift(lit(exe));
+	const { meta, warnings } = buildAppMeta(doc.frontmatter, {
+		title: doc.root.title,
+		description: doc.root.description
+	}, doc.rootName);
+	return {
+		...meta && { meta },
+		expr: result.expr,
+		errors: result.errors,
+		warnings: [...result.warnings, ...warnings.map((message) => ({ message }))]
+	};
+}
 
 //#endregion
-//#region src/ir/meta.ts
-/** Construct a NodeRef from a node name. */
-function nodeRef(name) {
+//#region src/frontend/argtype/parser-frontend.ts
+/** A fresh empty root sequence for error returns (IR passes mutate in place). */
+function emptyExpr$2() {
 	return {
-		kind: "node-ref",
-		name
+		kind: "sequence",
+		attrs: { nodes: [] }
 	};
 }
 /**
-* Produce a usable name for an Output. Frontends may leave `Output.name`
-* unset; downstream code (resolver, validator, backends) needs a stable
-* identifier for diagnostics and field naming. Falls back to `output_<index>`
-* keyed by the output's position in tree-walk order.
+* Frontend for the argtype sugar DSL - the hand-authored, TypeScript-types-like
+* language for describing CLI argument grammars (see the argtype spec). Parses
+* the text into an AST, then lowers it to Styx IR + AppMeta.
+*
+* Supported today: the argtype core (combinators, terminals, literals, naming,
+* aliases, value constraints, `.join`/`.count`/`.default`, doc comments,
+* frontmatter) plus the `outputs`, `mediatypes`, and `paths` extensions. `set`
+* lowers to a sequence and `any` to its first branch; the `constraints`
+* extension is parsed-and-ignored.
 */
-function effectiveOutputName(output, index) {
-	return output.name ?? `output_${index}`;
-}
+var ArgtypeParser = class {
+	name = "argtype";
+	extensions = ["argtype"];
+	parse(source, _filename) {
+		const { doc, errors: parseErrors, warnings: parseWarnings } = parseArgtype(source);
+		const toLocation = (e) => e.line !== void 0 ? { location: {
+			line: e.line,
+			column: e.column
+		} } : {};
+		const errors = parseErrors.map((e) => ({
+			message: e.message,
+			...toLocation(e)
+		}));
+		const warnings = parseWarnings.map((e) => ({
+			message: e.message,
+			...toLocation(e)
+		}));
+		if (!doc) return {
+			expr: emptyExpr$2(),
+			errors,
+			warnings
+		};
+		const lowered = lowerDocument(doc);
+		warnings.push(...lowered.warnings.map((d) => ({
+			message: d.message,
+			...toLocation(d)
+		})));
+		errors.push(...lowered.errors.map((d) => ({
+			message: d.message,
+			...toLocation(d)
+		})));
+		return {
+			...lowered.meta && { meta: lowered.meta },
+			expr: lowered.expr,
+			errors,
+			warnings
+		};
+	}
+};
 
 //#endregion
 //#region src/frontend/boutiques/destruct-template.ts
@@ -772,20 +2314,26 @@ function destructTemplate(template, lookup) {
 			destructed.push(x);
 			continue;
 		}
-		let didSplit = false;
+		let best = null;
 		for (const [alias, replacement] of Object.entries(lookup)) {
+			if (alias.length === 0) continue;
 			const idx = x.indexOf(alias);
-			if (idx !== -1) {
-				const left = x.slice(0, idx);
-				const right = x.slice(idx + alias.length);
-				if (right.length > 0) stack.unshift(right);
-				stack.unshift(replacement);
-				if (left.length > 0) stack.unshift(left);
-				didSplit = true;
-				break;
-			}
+			if (idx === -1) continue;
+			if (best === null || idx < best.idx || idx === best.idx && alias.length > best.alias.length) best = {
+				idx,
+				alias,
+				replacement
+			};
+		}
+		if (best === null) {
+			destructed.push(x);
+			continue;
 		}
-		if (!didSplit) destructed.push(x);
+		const left = x.slice(0, best.idx);
+		const right = x.slice(best.idx + best.alias.length);
+		if (right.length > 0) stack.unshift(right);
+		stack.unshift(best.replacement);
+		if (left.length > 0) stack.unshift(left);
 	}
 	return destructed;
 }
@@ -1113,14 +2661,8 @@ var BoutiquesParser = class {
 					kind: "int",
 					attrs: {}
 				};
-				if (isNumber$1(btInput.minimum)) {
-					node.attrs.minValue = Math.floor(btInput.minimum);
-					if (btInput["exclusive-minimum"] === true) node.attrs.minValue += 1;
-				}
-				if (isNumber$1(btInput.maximum)) {
-					node.attrs.maxValue = Math.floor(btInput.maximum);
-					if (btInput["exclusive-maximum"] === true) node.attrs.maxValue -= 1;
-				}
+				if (isNumber$1(btInput.minimum)) node.attrs.minValue = btInput["exclusive-minimum"] === true ? Math.floor(btInput.minimum) + 1 : Math.ceil(btInput.minimum);
+				if (isNumber$1(btInput.maximum)) node.attrs.maxValue = btInput["exclusive-maximum"] === true ? Math.ceil(btInput.maximum) - 1 : Math.floor(btInput.maximum);
 				if (meta) node.meta = meta;
 				return node;
 			}
@@ -1170,7 +2712,10 @@ var BoutiquesParser = class {
 					return null;
 				}
 				const node = this.parseDescriptor(nested);
-				if (node && meta) node.meta = meta;
+				if (node && meta) node.meta = {
+					...node.meta,
+					...meta
+				};
 				return node;
 			}
 			case InputTypePrimitive.SubCommandUnion: {
@@ -1269,13 +2814,16 @@ var BoutiquesParser = class {
 		node = this.wrapWithFlag(node, btInput);
 		if (inputType.isOptional) node = this.wrapWithOptional(node);
 		if (node !== inner && inner.meta) {
-			const { name, ...rest } = inner.meta;
+			const { name, outputs, ...rest } = inner.meta;
 			if (Object.keys(rest).length > 0) {
 				node.meta = {
 					...node.meta,
 					...rest
 				};
-				inner.meta = name ? { name } : void 0;
+				const kept = {};
+				if (name) kept.name = name;
+				if (outputs) kept.outputs = outputs;
+				inner.meta = Object.keys(kept).length > 0 ? kept : void 0;
 			}
 		}
 		return node;
@@ -1345,123 +2893,36 @@ var BoutiquesParser = class {
 			return {
 				expr: {
 					kind: "sequence",
-					attrs: { nodes: [] }
-				},
-				errors: this.errors,
-				warnings: this.warnings
-			};
-		}
-		const expr = this.parseDescriptor(bt);
-		if (expr === null) {
-			this.error("Failed to parse command structure");
-			return {
-				expr: {
-					kind: "sequence",
-					attrs: { nodes: [] }
-				},
-				errors: this.errors,
-				warnings: this.warnings
-			};
-		}
-		if (!expr.meta?.name && baseMeta?.id) expr.meta = {
-			...expr.meta,
-			name: baseMeta.id
-		};
-		return {
-			meta: baseMeta,
-			expr,
-			errors: this.errors,
-			warnings: this.warnings
-		};
-	}
-};
-
-//#endregion
-//#region src/ir/builders.ts
-function lit(str) {
-	return {
-		kind: "literal",
-		attrs: { str }
-	};
-}
-function str(meta) {
-	return {
-		kind: "str",
-		attrs: {},
-		meta: normalizeMeta(meta)
-	};
-}
-function int(meta) {
-	return {
-		kind: "int",
-		attrs: {},
-		meta: normalizeMeta(meta)
-	};
-}
-function float(meta) {
-	return {
-		kind: "float",
-		attrs: {},
-		meta: normalizeMeta(meta)
-	};
-}
-function path(meta) {
-	return {
-		kind: "path",
-		attrs: {},
-		meta: normalizeMeta(meta)
-	};
-}
-function seq(...nodes) {
-	return {
-		kind: "sequence",
-		attrs: { nodes }
-	};
-}
-function seqJoin(join, ...nodes) {
-	return {
-		kind: "sequence",
-		attrs: {
-			nodes,
-			join
+					attrs: { nodes: [] }
+				},
+				errors: this.errors,
+				warnings: this.warnings
+			};
 		}
-	};
-}
-function opt(node, meta) {
-	return {
-		kind: "optional",
-		attrs: { node },
-		meta: normalizeMeta(meta)
-	};
-}
-function rep(node, meta) {
-	return {
-		kind: "repeat",
-		attrs: { node },
-		meta: normalizeMeta(meta)
-	};
-}
-function repJoin(join, node, meta) {
-	return {
-		kind: "repeat",
-		attrs: {
-			node,
-			join
-		},
-		meta: normalizeMeta(meta)
-	};
-}
-function alt(...alts) {
-	return {
-		kind: "alternative",
-		attrs: { alts }
-	};
-}
-function normalizeMeta(meta) {
-	if (meta === void 0) return void 0;
-	if (typeof meta === "string") return { name: meta };
-	return meta;
-}
+		const expr = this.parseDescriptor(bt);
+		if (expr === null) {
+			this.error("Failed to parse command structure");
+			return {
+				expr: {
+					kind: "sequence",
+					attrs: { nodes: [] }
+				},
+				errors: this.errors,
+				warnings: this.warnings
+			};
+		}
+		if (!expr.meta?.name && baseMeta?.id) expr.meta = {
+			...expr.meta,
+			name: baseMeta.id
+		};
+		return {
+			meta: baseMeta,
+			expr,
+			errors: this.errors,
+			warnings: this.warnings
+		};
+	}
+};
 
 //#endregion
 //#region src/backend/string-case.ts
@@ -2211,27 +3672,621 @@ function extractVersion(versionInfo) {
 }
 
 //#endregion
-//#region src/frontend/detect-format.ts
+//#region src/frontend/detect-format.ts
+/** The first non-whitespace character of a source ("" if it is all blank). */
+function firstNonBlankChar(source) {
+	const match = source.match(/\S/);
+	return match ? match[0] : "";
+}
+/**
+* Auto-detect the format of a descriptor source string.
+*
+* Every JSON frontend (boutiques, argdump, workbench, mrtrix) is a top-level
+* object, so the first non-blank character being `{` is the signal for "some
+* JSON format"; we then inspect its keys to pick which one. Anything else
+* non-blank is treated as the argtype DSL, whose sources open with a terminal
+* (`int`), a literal (`"hello"`), a combinator (`seq(...)`), a `name: expr`
+* definition, or a `---` frontmatter fence - never with `{`.
+*
+* Deciding on the leading character (rather than trying `JSON.parse` first) is
+* what lets standalone argtype snippets like `"hello"` or `42` be recognized:
+* those are *also* valid JSON scalars, so a parse-first approach would swallow
+* them and then reject them as "not an object".
+*
+* Returns null only when the source is blank, or opens with `{` but matches no
+* known JSON format (ambiguous, or still being typed).
+*/
+function detectFormat(source) {
+	const first = firstNonBlankChar(source);
+	if (first === "") return null;
+	if (first !== "{") return "argtype";
+	let parsed;
+	try {
+		parsed = JSON.parse(source);
+	} catch {
+		return null;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+	const obj = parsed;
+	if (typeof obj.$schema === "string" && obj.$schema.includes("argdump")) return "argdump";
+	if (typeof obj.command === "string" && typeof obj.short_description === "string") return "workbench";
+	if (typeof obj.synopsis === "string" && Array.isArray(obj.option_groups) && Array.isArray(obj.arguments)) return "mrtrix";
+	if ("command-line" in obj || Array.isArray(obj.inputs) && "name" in obj) return "boutiques";
+	if (Array.isArray(obj.actions) && "prog" in obj) return "argdump";
+	return null;
+}
+
+//#endregion
+//#region src/backend/scope.ts
+/** Symbol collision avoidance for code generation. */
+var Scope = class Scope {
+	reserved;
+	used;
+	parent;
+	constructor(reserved = [], parent) {
+		this.reserved = new Set(reserved);
+		this.used = /* @__PURE__ */ new Set();
+		this.parent = parent;
+	}
+	/** Check if a symbol is already taken (in this scope or any parent). */
+	has(symbol) {
+		return this.reserved.has(symbol) || this.used.has(symbol) || (this.parent?.has(symbol) ?? false);
+	}
+	/**
+	* Add a symbol, appending a numeric suffix to avoid collisions. Returns the
+	* safe name.
+	*
+	* When a `recase` transform is given, a disambiguated candidate is routed back
+	* through it so the suffix is absorbed into the identifier's casing - e.g.
+	* `pascalCase` folds `Config_2` into `Config2` - rather than leaving a
+	* mixed-case `Config_2`. Uniqueness is always checked on the final emitted
+	* form, so two hints that case-collide still get distinct names. Defaults to
+	* identity (the bare `<name>_<n>` suffix) for callers that don't case-normalize.
+	*/
+	add(candidate, recase = (s) => s) {
+		if (!this.has(candidate)) {
+			this.used.add(candidate);
+			return candidate;
+		}
+		let suffix = 2;
+		let safe = recase(`${candidate}_${suffix}`);
+		while (this.has(safe)) {
+			suffix++;
+			safe = recase(`${candidate}_${suffix}`);
+		}
+		this.used.add(safe);
+		return safe;
+	}
+	/** Create a child scope that inherits this scope's restrictions. */
+	child(reserved = []) {
+		return new Scope(reserved, this);
+	}
+};
+
+//#endregion
+//#region src/backend/argtype/emit.ts
+const INDENT = "  ";
+/** Target content width (excluding the `/// ` prefix and indentation) for a
+* wrapped `///` description line. */
+const DOC_WIDTH = 80;
+function pad(level) {
+	return INDENT.repeat(level);
+}
+/**
+* Wrap a description into `///`-ready content lines. Paragraphs (separated by a
+* blank line) are word-wrapped to `width`; an empty string marks a paragraph
+* break (the caller emits it as a bare `///`).
+*
+* The argtype frontend reflows a `///` block as prose - a single line break
+* rejoins with a space, a blank line separates paragraphs - so wrapping here is
+* the inverse: it round-trips paragraph text exactly (whitespace within a
+* paragraph is normalized to single spaces, matching the frontend's reflow), and
+* keeps a long description from emitting as one giant physical line.
+*/
+function wrapDoc(text, width) {
+	const lines = [];
+	for (const paragraph of text.split(/\n{2,}/)) {
+		const words = paragraph.split(/\s+/).filter((w) => w.length > 0);
+		if (words.length === 0) continue;
+		if (lines.length > 0) lines.push("");
+		let cur = "";
+		for (const word of words) if (cur === "") cur = word;
+		else if (cur.length + 1 + word.length <= width) cur += ` ${word}`;
+		else {
+			lines.push(cur);
+			cur = word;
+		}
+		if (cur !== "") lines.push(cur);
+	}
+	return lines;
+}
+function num(n) {
+	return String(n);
+}
+/** Escape a string for a double-quoted argtype literal (matches the lexer). */
+function escapeString(s) {
+	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\t/g, "\\t").replace(/\r/g, "\\r");
+}
+function quote(s) {
+	return `"${escapeString(s)}"`;
+}
+/** A value terminal kind whose `meta.defaultValue` argtype can express. */
+function isValueTerminal(node) {
+	return node.kind === "int" || node.kind === "float" || node.kind === "str" || node.kind === "path";
+}
+/**
+* Find the single value terminal a wrapper's default should attach to. Descends
+* through optional/repeat and a sequence with exactly one non-literal child
+* (the flag-value pattern `seq(lit, value)`). Returns undefined when the value
+* slot is ambiguous (multiple non-literal children) or absent (a bare literal
+* flag), in which case the wrapper default has no terminal to sink onto.
+*/
+function findValueTerminal(node) {
+	switch (node.kind) {
+		case "int":
+		case "float":
+		case "str":
+		case "path": return node;
+		case "optional": return findValueTerminal(node.attrs.node);
+		case "repeat": return findValueTerminal(node.attrs.node);
+		case "sequence": {
+			const nonLiteral = node.attrs.nodes.filter((n) => n.kind !== "literal");
+			return nonLiteral.length === 1 ? findValueTerminal(nonLiteral[0]) : void 0;
+		}
+		default: return;
+	}
+}
+/**
+* Push a wrapper's `meta.defaultValue` down onto its inner value terminal so it
+* can be emitted as `int = 5` / `.default(...)`. Boutiques (and argparse) hoist
+* an input's default onto the outermost wrapper (`optional` / `sequence`); the
+* argtype surface only carries `.default()` on a terminal, so we relocate it.
+* Boolean defaults are left in place: those are the `opt(literal)` flag-false
+* convention, which the frontend regenerates for free and which has no terminal.
+*/
+function sinkDefaults(expr) {
+	const clone = structuredClone(expr);
+	const visit = (node) => {
+		switch (node.kind) {
+			case "optional":
+				visit(node.attrs.node);
+				sinkInto(node);
+				break;
+			case "repeat":
+				visit(node.attrs.node);
+				sinkInto(node);
+				break;
+			case "sequence":
+				for (const c of node.attrs.nodes) visit(c);
+				sinkInto(node);
+				break;
+			case "alternative":
+				for (const c of node.attrs.alts) visit(c);
+				break;
+			default: break;
+		}
+	};
+	visit(clone);
+	return clone;
+}
+function sinkInto(wrapper) {
+	const dv = wrapper.meta?.defaultValue;
+	if (dv === void 0 || typeof dv === "boolean") return;
+	const terminal = findValueTerminal(wrapper);
+	if (!terminal || !isValueTerminal(terminal) || terminal.meta?.defaultValue !== void 0) return;
+	terminal.meta = {
+		...terminal.meta,
+		defaultValue: dv
+	};
+	const meta = { ...wrapper.meta };
+	delete meta.defaultValue;
+	wrapper.meta = Object.keys(meta).length > 0 ? meta : void 0;
+}
+/**
+* Detect the synthetic single-child sequence the frontend wraps a non-sequence
+* root in. Such a wrapper carries only `name` (matching the child's name) plus
+* any collected `outputs`; the doc/default live on the inner node. Returns the
+* inner node and the wrapper's outputs so the caller can emit the inner node as
+* the definition body (the frontend re-wraps it identically on re-parse).
+*/
+function syntheticWrap(root) {
+	if (root.kind !== "sequence" || root.attrs.nodes.length !== 1 || root.attrs.join !== void 0) return;
+	const meta = root.meta;
+	if (meta?.doc || meta?.defaultValue !== void 0 || meta?.variantTag !== void 0) return;
+	const child = root.attrs.nodes[0];
+	if (child.kind === "sequence") return void 0;
+	if ((child.meta?.name ?? void 0) !== (meta?.name ?? void 0)) return void 0;
+	return {
+		child,
+		...meta?.outputs && { outputs: meta.outputs }
+	};
+}
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A name rendered where an identifier is expected: bare when it is a valid
+* identifier, otherwise a double-quoted form preserving it exactly. Used for
+* both `label:` prefixes and output-template `{ref}` targets (templates accept a
+* quoted name, `{"4d_output"}`), so the two always agree and no lossy
+* sanitization is needed. */
+function identOrQuoted(name) {
+	return IDENT_RE.test(name) ? name : quote(name);
+}
+var ArgtypeEmitter = class {
+	warnings = [];
+	warn(message) {
+		this.warnings.push({ message });
+	}
+	/** Render a name as it appears before a `:` label (bare identifier or quoted
+	* label, e.g. `"1deval":`, `"1D":`). */
+	labelFor(name) {
+		return identOrQuoted(name);
+	}
+	/**
+	* `///` doc lines for a `Documentation`. A title is written as a leading
+	* Markdown H1 (`# Title`); the description follows after a blank `///` line.
+	* Either alone emits just that part.
+	*/
+	docLines(doc) {
+		if (!doc) return [];
+		const out = [];
+		if (doc.title) out.push(`/// # ${doc.title}`);
+		if (doc.title && doc.description) out.push("///");
+		if (doc.description) for (const line of wrapDoc(doc.description, DOC_WIDTH)) out.push(line === "" ? "///" : `/// ${line}`);
+		return out;
+	}
+	/**
+	* Whether a `///` block would not round-trip, so the doc must instead be
+	* emitted as `.title()` / `.description()` chaining (which sets the fields
+	* verbatim). Three cases:
+	* - a multi-line title (only its first line would survive `splitDocText`);
+	* - a description with a lone line break (a single `\n`, not a blank-line
+	*   paragraph break), which a `///` block reflows to a space - chaining keeps
+	*   the hard break intact;
+	* - a title-less description whose first line looks like an H1 heading
+	*   (`# ...`), which would be promoted to a spurious title.
+	* A blank-line paragraph break is safe: the frontend reflows a `///` block back
+	* into the same paragraphs, and a description under a title is safe too
+	* (`splitDocText` consumes only the very first line as the title).
+	*/
+	docNeedsChain(doc) {
+		if (!doc) return false;
+		if (doc.title?.includes("\n")) return true;
+		const desc = doc.description;
+		if (desc) {
+			if (desc.split(/\n{2,}/).some((para) => para.includes("\n"))) return true;
+			if (!doc.title && (desc.split("\n")[0] ?? "").trim().startsWith("# ")) return true;
+		}
+		return false;
+	}
+	/** `.title(...)` / `.description(...)` chaining for a doc that cannot round-trip
+	* as a `///` block (see `docNeedsChain`). */
+	docChain(doc) {
+		if (!doc) return "";
+		let chain = "";
+		if (doc.title) chain += `.title(${quote(doc.title)})`;
+		if (doc.description) chain += `.description(${quote(doc.description)})`;
+		return chain;
+	}
+	/**
+	* Warn for `Documentation` fields a node's `///` comment cannot carry. `title`
+	* and `description` are emitted (see `docLines`); literature / comment /
+	* authors / urls attached to an inner node have no surface, so surface them
+	* rather than dropping silently.
+	*/
+	warnUnrepresentableDoc(doc, where) {
+		if (!doc) return;
+		const lost = [];
+		if (doc.literature?.length) lost.push("literature");
+		if (doc.comment) lost.push("comment");
+		if (doc.authors?.length) lost.push("authors");
+		if (doc.urls?.length) lost.push("urls");
+		if (lost.length > 0) this.warn(`Documentation ${lost.join("/")} on ${where} has no argtype node surface; ignored`);
+	}
+	emit(expr, app) {
+		const raw = sinkDefaults(expr);
+		const lines = [];
+		let exe;
+		let root = raw;
+		if (raw.kind === "sequence" && raw.attrs.nodes[0]?.kind === "literal") {
+			exe = raw.attrs.nodes[0].attrs.str;
+			root = {
+				kind: "sequence",
+				attrs: {
+					...raw.attrs,
+					nodes: raw.attrs.nodes.slice(1)
+				}
+			};
+			if (raw.meta) root.meta = raw.meta;
+		}
+		const frontmatter = this.emitFrontmatter(app, exe);
+		if (frontmatter) lines.push(frontmatter, "");
+		const synthetic = syntheticWrap(root);
+		const defNode = synthetic ? synthetic.child : root;
+		const wrapperOutputs = synthetic ? synthetic.outputs : void 0;
+		const rootDoc = defNode.meta?.doc ?? app?.doc;
+		const rootChain = this.docNeedsChain(rootDoc);
+		if (!rootChain) lines.push(...this.docLines(rootDoc));
+		this.warnUnrepresentableDoc(defNode.meta?.doc, "the root node");
+		const rootName = this.labelFor(defNode.meta?.name || app?.id || "tool");
+		let body = this.emitNode(defNode, 0);
+		if (rootChain) body += this.docChain(rootDoc);
+		if (wrapperOutputs?.length) body += this.emitOutputs(wrapperOutputs, 0);
+		lines.push(`${rootName}: ${body}`);
+		return lines.join("\n") + "\n";
+	}
+	/**
+	* Emit a node's core expression plus its node-local chains (value
+	* constraints, default, join, count, media types) and any `.output(...)`.
+	* The first line is not indented (the caller places it after a label or pad);
+	* continuation lines are indented relative to `level`.
+	*/
+	emitNode(expr, level) {
+		let core;
+		switch (expr.kind) {
+			case "literal":
+				core = quote(expr.attrs.str);
+				break;
+			case "str":
+				core = "str" + this.defaultSuffix(expr, false);
+				break;
+			case "int":
+			case "float": {
+				core = expr.kind;
+				let chained = false;
+				const min = this.finiteNum(expr.attrs.minValue, "min");
+				if (min !== void 0) {
+					core += `.min(${min})`;
+					chained = true;
+				}
+				const max = this.finiteNum(expr.attrs.maxValue, "max");
+				if (max !== void 0) {
+					core += `.max(${max})`;
+					chained = true;
+				}
+				core += this.defaultSuffix(expr, chained);
+				break;
+			}
+			case "path": {
+				core = "path";
+				const media = expr.attrs.mediaTypes ?? [];
+				for (const m of media) core += `.mediaType(${quote(m)})`;
+				if (expr.attrs.mutable) core += ".mutable()";
+				if (expr.attrs.resolveParent) core += ".resolveParent()";
+				const chained = media.length > 0 || !!expr.attrs.mutable || !!expr.attrs.resolveParent;
+				core += this.defaultSuffix(expr, chained);
+				break;
+			}
+			case "sequence":
+				core = this.emitCombinator("seq", expr.attrs.nodes, level, expr.attrs.join);
+				core += this.structuralDefaultSuffix(expr);
+				break;
+			case "optional":
+				core = this.emitOptional(expr, level) + this.structuralDefaultSuffix(expr);
+				break;
+			case "repeat":
+				core = this.emitRepeat(expr, level) + this.structuralDefaultSuffix(expr);
+				break;
+			case "alternative":
+				for (const arm of expr.attrs.alts) {
+					const tag = arm.meta?.variantTag;
+					if (tag !== void 0 && tag !== arm.meta?.name) this.warn(`Union arm discriminator '${tag}' has no argtype surface and will be re-derived from the arm name '${arm.meta?.name ?? "<unnamed>"}' on re-parse`);
+				}
+				core = this.emitCombinator("alt", expr.attrs.alts, level) + this.structuralDefaultSuffix(expr);
+				break;
+			default: core = "";
+		}
+		if (expr.meta?.outputs?.length) core += this.emitOutputs(expr.meta.outputs, level);
+		return core;
+	}
+	/** `String(n)` when `n` is finite; otherwise undefined with a warning, since
+	* `Infinity`/`NaN` have no argtype number literal (emitting them would produce
+	* an identifier that fails to re-parse). */
+	finiteNum(n, where) {
+		if (n === void 0) return void 0;
+		if (!Number.isFinite(n)) {
+			this.warn(`Non-finite number (${String(n)}) on ${where} has no argtype literal; ignored`);
+			return;
+		}
+		return num(n);
+	}
+	/** `= value` on a bare terminal, else `.default(value)` once a chain started. */
+	defaultSuffix(expr, chained) {
+		const dv = expr.meta?.defaultValue;
+		if (dv === void 0 || typeof dv === "boolean") return "";
+		let value;
+		if (typeof dv === "number") {
+			const n = this.finiteNum(dv, "default");
+			if (n === void 0) return "";
+			value = n;
+		} else value = quote(dv);
+		return chained ? `.default(${value})` : ` = ${value}`;
+	}
+	/**
+	* A `.default(value)` chained onto a structural node (e.g. an enum
+	* `alternative`, or a wrapper whose default could not sink onto an inner
+	* terminal). Booleans have no argtype value literal: the only legitimate one
+	* is the `opt(literal)` flag-false convention, which the frontend regenerates,
+	* so it is silently dropped; any other boolean default is warned and dropped.
+	*/
+	structuralDefaultSuffix(expr) {
+		const dv = expr.meta?.defaultValue;
+		if (dv === void 0) return "";
+		if (typeof dv === "boolean") {
+			if (!(expr.kind === "optional" && expr.attrs.node.kind === "literal" && dv === false)) this.warn(`Boolean default on a ${expr.kind} cannot be expressed in argtype; ignored`);
+			return "";
+		}
+		if (typeof dv === "number") {
+			const n = this.finiteNum(dv, "default");
+			return n === void 0 ? "" : `.default(${n})`;
+		}
+		return `.default(${quote(dv)})`;
+	}
+	emitOptional(expr, level) {
+		const inner = expr.attrs.node;
+		if (inner.kind === "sequence" && !inner.meta && inner.attrs.join === void 0) return this.emitCombinator("opt", inner.attrs.nodes, level);
+		return this.emitCombinator("opt", [inner], level);
+	}
+	emitRepeat(expr, level) {
+		const node = expr.attrs.node;
+		let core;
+		if (node.kind === "sequence" && !node.meta && node.attrs.join === void 0) core = this.emitCombinator("rep", node.attrs.nodes, level);
+		else core = this.emitCombinator("rep", [node], level);
+		if (expr.attrs.join !== void 0) core += `.join(${expr.attrs.join === "" ? "" : quote(expr.attrs.join)})`;
+		const { countMin, countMax } = expr.attrs;
+		if (countMin !== void 0 && countMin === countMax) core += `.count(${countMin})`;
+		else {
+			if (countMin !== void 0) core += `.countMin(${countMin})`;
+			if (countMax !== void 0) core += `.countMax(${countMax})`;
+		}
+		return core;
+	}
+	emitCombinator(keyword, children, level, join) {
+		let core;
+		if (children.length === 0) core = `${keyword}()`;
+		else {
+			const items = children.map((c) => this.emitDecorated(c, level + 1));
+			const inline = `${keyword}(${items.join(", ")})`;
+			if (!items.some((i) => i.includes("\n")) && inline.length + level * 2 <= 80) core = inline;
+			else core = `${keyword}(\n${items.map((i) => pad(level + 1) + i).join(",\n")},\n${pad(level)})`;
+		}
+		if (join !== void 0) core += `.join(${join === "" ? "" : quote(join)})`;
+		return core;
+	}
+	/**
+	* A list item: leading `///` doc lines, an optional `label:` prefix, then the
+	* node. The first line is unindented (the caller pads it); continuation lines
+	* are indented to `level`.
+	*/
+	emitDecorated(expr, level) {
+		const doc = expr.meta?.doc;
+		const useChain = this.docNeedsChain(doc);
+		const parts = useChain ? [] : [...this.docLines(doc)];
+		this.warnUnrepresentableDoc(doc, `node '${expr.meta?.name ?? expr.kind}'`);
+		const label = expr.meta?.name ? `${this.labelFor(expr.meta.name)}: ` : "";
+		let node = this.emitNode(expr, level);
+		if (useChain) node += this.docChain(doc);
+		parts.push(label + node);
+		return parts.join("\n" + pad(level));
+	}
+	emitOutputs(outputs, level) {
+		return `.output(\n${outputs.map((o) => {
+			const useChain = this.docNeedsChain(o.doc);
+			const docs = useChain ? [] : this.docLines(o.doc).map((l) => pad(level + 1) + l);
+			let template = pad(level + 1) + this.emitOutputTemplate(o);
+			if (useChain) template += this.docChain(o.doc);
+			return [...docs, template].join("\n");
+		}).join(",\n")},\n${pad(level)})`;
+	}
+	emitOutputTemplate(output) {
+		if (output.mediaTypes?.length) this.warn(`Output '${output.name ?? "<anon>"}' has media types, which have no argtype surface; ignored`);
+		const label = output.name ? `${this.labelFor(output.name)}: ` : "";
+		let body = "";
+		for (const token of output.tokens) {
+			if (token.kind === "literal") {
+				body += token.value.replace(/[\\{}`]/g, (c) => `\\${c}`);
+				continue;
+			}
+			let ref = identOrQuoted(token.target.name);
+			for (const ext of token.stripExtensions ?? []) ref += `.strip_suffix(${quote(ext)})`;
+			if (token.fallback !== void 0) ref += `.or(${quote(token.fallback)})`;
+			body += `{${ref}}`;
+		}
+		return `${label}\`${body}\``;
+	}
+	/** Quote a frontmatter scalar (double-quoted, backslash-escaped). The
+	* frontmatter parser unescapes symmetrically, so quotes/newlines round-trip. */
+	fmScalar(value) {
+		return quote(value);
+	}
+	emitFrontmatter(app, exe) {
+		const lines = [];
+		if (exe !== void 0) lines.push(`exe: ${this.fmScalar(exe)}`);
+		if (app) {
+			if (app.version) lines.push(`version: ${this.fmScalar(app.version)}`);
+			const authors = app.doc?.authors ?? [];
+			if (authors.length > 0) {
+				lines.push("authors:");
+				for (const a of authors) lines.push(`  - ${this.fmScalar(a)}`);
+			}
+			const urls = app.doc?.urls ?? [];
+			if (urls.length > 0) {
+				lines.push("urls:");
+				for (const u of urls) lines.push(`  - ${this.fmScalar(u)}`);
+			}
+			const references = app.doc?.literature ?? [];
+			if (references.length > 0) {
+				lines.push("references:");
+				for (const rf of references) lines.push(`  - ${this.fmScalar(rf)}`);
+			}
+			if (app.container) {
+				lines.push("container:");
+				lines.push(`  image: ${this.fmScalar(app.container.image)}`);
+				if (app.container.type) lines.push(`  type: ${this.fmScalar(app.container.type)}`);
+			}
+			if (app.stdout) this.emitStream(lines, "stdout", app.stdout);
+			if (app.stderr) this.emitStream(lines, "stderr", app.stderr);
+			if (app.doc?.comment) this.warn("AppMeta.doc.comment has no argtype surface; ignored");
+		}
+		if (lines.length === 0) return void 0;
+		return [
+			"---",
+			...lines,
+			"---"
+		].join("\n");
+	}
+	emitStream(lines, key, stream) {
+		lines.push(`${key}:`);
+		lines.push(`  name: ${this.fmScalar(stream.name)}`);
+		if (stream.doc?.description) lines.push(`  description: ${this.fmScalar(stream.doc.description)}`);
+		if (stream.doc?.title) this.warn(`${key} stream title has no argtype surface; ignored`);
+	}
+};
+/** Emit argtype sugar-DSL source from an IR expression tree and optional `AppMeta`. */
+function generateArgtype(expr, app) {
+	const emitter = new ArgtypeEmitter();
+	return {
+		source: emitter.emit(expr, app),
+		warnings: emitter.warnings
+	};
+}
+
+//#endregion
+//#region src/backend/argtype/argtype.ts
 /**
-* Auto-detect the format of a JSON descriptor source string.
-* Returns null if the format cannot be determined.
+* A per-tool file stem, so co-located tools in a catalog build don't clobber one
+* another's `descriptor.argtype`. Standalone single-tool builds (no scope) keep
+* the bare name. Mirrors the JSON Schema backend's `schemaStem`.
 */
-function detectFormat(source) {
-	let parsed;
-	try {
-		parsed = JSON.parse(source);
-	} catch {
-		return null;
-	}
-	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
-	const obj = parsed;
-	if (typeof obj.$schema === "string" && obj.$schema.includes("argdump")) return "argdump";
-	if (typeof obj.command === "string" && typeof obj.short_description === "string") return "workbench";
-	if (typeof obj.synopsis === "string" && Array.isArray(obj.option_groups) && Array.isArray(obj.arguments)) return "mrtrix";
-	if ("command-line" in obj || Array.isArray(obj.inputs) && "name" in obj) return "boutiques";
-	if (Array.isArray(obj.actions) && "prog" in obj) return "argdump";
-	return null;
+function argtypeStem(ctx, scope) {
+	const id = ctx.app?.id;
+	if (!id || !scope) return void 0;
+	return scope.add(snakeCase(id) || "descriptor");
 }
+/**
+* Serialization backend: emit argtype sugar-DSL source from the IR + `AppMeta`.
+*
+* The dogfooding / round-trip counterpart to the argtype frontend. Like the
+* Boutiques backend it only needs the IR (`ctx.expr`) and app metadata
+* (`ctx.app`), never the solved bindings, so it ignores the rest of the context.
+*/
+var ArgtypeBackend = class {
+	name = "argtype";
+	target = "argtype";
+	/** One scope per package so per-tool file stems stay unique in the suite dir. */
+	newPackageScope() {
+		return new Scope();
+	}
+	emitApp(ctx, scope) {
+		const { source, warnings } = generateArgtype(ctx.expr, ctx.app);
+		const stem = argtypeStem(ctx, scope);
+		const filename = stem ? `${stem}.argtype` : "descriptor.argtype";
+		return {
+			meta: ctx.app,
+			files: new Map([[filename, source]]),
+			errors: [],
+			warnings
+		};
+	}
+};
 
 //#endregion
 //#region src/backend/find-doc.ts
@@ -2312,6 +4367,7 @@ function resolveFieldBinding(node, ctx, structType, outermost) {
 * sequence is the actual struct owner (e.g. `seq(lit("--flag"), seq(field1, field2))`).
 */
 function findStructNode(node, ctx, structType) {
+	if (node.kind === "sequence" && Object.keys(structType.fields).length === 0) return node;
 	switch (node.kind) {
 		case "sequence":
 			for (const child of node.attrs.nodes) {
@@ -2517,100 +4573,6 @@ function formatType(type, indent = 0) {
 	}
 }
 
-//#endregion
-//#region src/backend/resolve-output-tokens.ts
-/**
-* Compact consecutive literal tokens. Backends that emit string concatenation
-* benefit from a shorter token stream; backends that template each token
-* individually can ignore this and use `output.tokens` directly.
-*/
-function compactTokens(tokens) {
-	const out = [];
-	for (const tok of tokens) {
-		const last = out[out.length - 1];
-		if (tok.kind === "literal" && last && last.kind === "literal") out[out.length - 1] = {
-			kind: "literal",
-			value: last.value + tok.value
-		};
-		else out.push(tok);
-	}
-	return out;
-}
-function planOutput(scopeGate, output, bindings) {
-	return {
-		name: output.name,
-		gate: outputGate(scopeGate, output, bindings),
-		tokens: compactTokens(output.tokens),
-		resolved: output
-	};
-}
-/**
-* Does the output have any conditional wrapper? Equivalent to "is at least one
-* atom a `present` or `variant`?". `iter` alone means the output emits a list
-* and is not conditionally absent.
-*/
-function isGated(plan) {
-	return plan.gate.some((a) => a.kind === "present" || a.kind === "variant");
-}
-/** Does the output iterate (emit zero-or-more values)? */
-function isIterated(plan) {
-	return plan.gate.some((a) => a.kind === "iter");
-}
-/**
-* Convenience for backends emitting all outputs of a scope at once. The caller
-* provides the scope's gate (typically `bindings.get(scope.scope)?.gate ?? []`).
-*/
-function planScope(scope, scopeGate, bindings) {
-	return scope.outputs.map((output) => planOutput(scopeGate, output, bindings));
-}
-
-//#endregion
-//#region src/backend/scope.ts
-/** Symbol collision avoidance for code generation. */
-var Scope = class Scope {
-	reserved;
-	used;
-	parent;
-	constructor(reserved = [], parent) {
-		this.reserved = new Set(reserved);
-		this.used = /* @__PURE__ */ new Set();
-		this.parent = parent;
-	}
-	/** Check if a symbol is already taken (in this scope or any parent). */
-	has(symbol) {
-		return this.reserved.has(symbol) || this.used.has(symbol) || (this.parent?.has(symbol) ?? false);
-	}
-	/**
-	* Add a symbol, appending a numeric suffix to avoid collisions. Returns the
-	* safe name.
-	*
-	* When a `recase` transform is given, a disambiguated candidate is routed back
-	* through it so the suffix is absorbed into the identifier's casing - e.g.
-	* `pascalCase` folds `Config_2` into `Config2` - rather than leaving a
-	* mixed-case `Config_2`. Uniqueness is always checked on the final emitted
-	* form, so two hints that case-collide still get distinct names. Defaults to
-	* identity (the bare `<name>_<n>` suffix) for callers that don't case-normalize.
-	*/
-	add(candidate, recase = (s) => s) {
-		if (!this.has(candidate)) {
-			this.used.add(candidate);
-			return candidate;
-		}
-		let suffix = 2;
-		let safe = recase(`${candidate}_${suffix}`);
-		while (this.has(safe)) {
-			suffix++;
-			safe = recase(`${candidate}_${suffix}`);
-		}
-		this.used.add(safe);
-		return safe;
-	}
-	/** Create a child scope that inherits this scope's restrictions. */
-	child(reserved = []) {
-		return new Scope(reserved, this);
-	}
-};
-
 //#endregion
 //#region src/backend/boutiques/boutiques.ts
 var BoutiquesEmitter = class {
@@ -2826,14 +4788,12 @@ var BoutiquesEmitter = class {
 				if (flagStr) peeled.flag = flagStr;
 			}
 			const input = this.buildInput(binding, id, fieldType, valueKeyStr, peeled, fieldInfo, wrapperNode);
-			if (peeled.flag) if (fieldType.kind === "bool" || fieldType.kind === "optional" && this.isBool(fieldType)) commandParts.push(valueKeyStr);
-			else commandParts.push(valueKeyStr);
-			else commandParts.push(valueKeyStr);
+			commandParts.push(valueKeyStr);
 			inputs.push(input);
 		}
 		bt["command-line"] = commandParts.join(" ");
 		bt.inputs = inputs;
-		this.emitOutputFiles(bt, expr, valueKeyByBinding, idScope);
+		this.emitOutputFiles(bt, structNode, valueKeyByBinding, idScope);
 	}
 	emitOutputFiles(bt, scopeNode, valueKeys, idScope) {
 		const scopeBinding = this.ctx.resolve(scopeNode);
@@ -2926,6 +4886,7 @@ var BoutiquesEmitter = class {
 	}
 	finalizeInput(input) {
 		if (input.name === void 0) input.name = input.id;
+		this.finalizeSubDescriptors(input);
 		if (input.type === "String" && typeof input["default-value"] === "boolean" && input["value-choices"] === void 0) input.type = "Flag";
 		if (input.type === "Flag") {
 			delete input["default-value"];
@@ -2952,6 +4913,15 @@ var BoutiquesEmitter = class {
 		if (Array.isArray(choices) && dv !== void 0 && !choices.some((c) => c === dv)) delete input["default-value"];
 		this.mergeDefaultIntoDescription(input);
 	}
+	finalizeSubDescriptors(input) {
+		const type = input.type;
+		if (Array.isArray(type)) type.forEach((sub, i) => this.ensureSubDescriptorId(sub, `${input.id}_${i + 1}`));
+		else if (typeof type === "object" && type !== null) this.ensureSubDescriptorId(type, input.id);
+	}
+	ensureSubDescriptorId(sub, fallback) {
+		if (sub.id === void 0) sub.id = this.sanitizeId(fallback);
+		if (sub.name === void 0) sub.name = sub.id;
+	}
 	peelNode(node, type) {
 		const result = {
 			isOptional: false,
@@ -2975,6 +4945,8 @@ var BoutiquesEmitter = class {
 				this.peelNodeInner(node.attrs.node, type.kind === "list" ? type.item : type, result);
 				break;
 			case "sequence": {
+				const structType = this.unwrapType(type);
+				if (structType.kind === "struct" && findStructNode(node, this.ctx, structType) === node) break;
 				const nodes = node.attrs.nodes;
 				if (nodes.length === 2 && nodes[0].kind === "literal") {
 					const flagLit = nodes[0].attrs.str;
@@ -3063,8 +5035,7 @@ var BoutiquesEmitter = class {
 			type: "String",
 			valueChoices: type.variants.map((v) => v.type.kind === "literal" ? v.type.value : "")
 		};
-		if (type.variants.every((v) => v.type.kind === "struct")) return { type: this.buildSubCommandUnion(type, node) };
-		return { type: this.buildMixedUnionAsSubCommands(type, node) };
+		return { type: this.buildUnionSubCommands(type, node) };
 	}
 	buildSubCommand(type, node) {
 		const bt = {};
@@ -3075,22 +5046,7 @@ var BoutiquesEmitter = class {
 		}
 		return bt;
 	}
-	buildSubCommandUnion(type, node) {
-		const alts = node.kind === "alternative" ? node.attrs.alts : [node];
-		return type.variants.map((variant, i) => {
-			const altNode = alts[i] ?? node;
-			if (variant.type.kind === "struct") {
-				const bt = this.buildSubCommand(variant.type, altNode);
-				if (variant.name) {
-					bt.name = variant.name;
-					bt.id = this.sanitizeId(variant.name);
-				}
-				return bt;
-			}
-			return this.wrapAsDescriptor(variant, altNode);
-		});
-	}
-	buildMixedUnionAsSubCommands(type, node) {
+	buildUnionSubCommands(type, node) {
 		const alts = node.kind === "alternative" ? node.attrs.alts : [node];
 		return type.variants.map((variant, i) => {
 			const altNode = alts[i] ?? node;
@@ -3189,7 +5145,8 @@ var BoutiquesEmitter = class {
 				inputs: []
 			},
 			list: true,
-			minListEntries: countMin
+			minListEntries: countMin,
+			...countMin === 0 && { optional: true }
 		};
 	}
 };
@@ -3395,9 +5352,65 @@ function resolveTypeName(namedTypes) {
 	};
 }
 
+//#endregion
+//#region src/backend/field-defaults.ts
+/**
+* Build the field-name -> rendered-default map for a struct root (else empty).
+* Includes only non-optional defaulted fields (optional fields are
+* presence-guarded; their default comes from the factory's kwarg signature).
+*
+* `rootType` defaults to the resolved root type; callers that already have it
+* (the arg-builders) pass it to avoid re-resolving.
+*/
+function collectDefaults(ctx, renderLiteral, rootType = ctx.resolve(ctx.expr)?.type) {
+	const out = /* @__PURE__ */ new Map();
+	if (rootType?.kind !== "struct") return out;
+	for (const [name, fi] of collectFieldInfo(ctx, rootType)) {
+		if (fi.defaultValue === void 0) continue;
+		if (rootType.fields[name]?.kind === "optional") continue;
+		out.set(name, renderLiteral(fi.defaultValue));
+	}
+	return out;
+}
+/** The rendered default for a binding iff it is a root-level defaulted field. */
+function rootFieldDefault(binding, defaults) {
+	if (!binding) return void 0;
+	const a = binding.access;
+	if (a.length === 1 && a[0]?.kind === "field") return defaults.get(binding.name);
+}
+
 //#endregion
 //#region src/backend/union-variants.ts
 /**
+* Whether a union is "mixed": it has at least one non-struct (bare-literal) arm
+* alongside its struct variants (e.g. ants `n4_correction = Literal[0] | N4On`).
+*
+* The `@type` discriminator only exists on the struct arms, so indexing
+* `value["@type"]` on the union value is unsound (a type error, and a runtime
+* KeyError if the literal arm is ever hit) until the value is narrowed to a
+* struct at runtime. Backends that dispatch on `@type` must first emit a shape
+* guard (Python `isinstance(value, dict)`, TS `typeof value === "object"`) when
+* this is true; a pure-struct union (every arm a struct) needs no guard.
+*/
+function unionIsMixed(unionType) {
+	return unionType.variants.some((v) => v.type.kind !== "struct");
+}
+/**
+* The union type bound by a `variant` gate atom, if the atom's binding resolves
+* to a union - used by the outputs emitters to decide whether the variant gate
+* needs a mixed-union shape guard before its `@type` check. Returns `undefined`
+* for a well-formed non-union (defensive; a variant atom should always name a
+* union binding).
+*/
+function variantAtomUnion(atom, bindings) {
+	return resolveUnion(bindings.get(atom.binding)?.type);
+}
+function resolveUnion(type) {
+	if (!type) return void 0;
+	if (type.kind === "optional") return resolveUnion(type.inner);
+	if (type.kind === "union") return type;
+}
+/**
 * The struct variants of a union, each with its index into `variants`.
 *
 * A discriminated union dispatches on a unique `@type`, so two struct variants
@@ -3535,10 +5548,6 @@ function pathArg$1(node, expr) {
 * carrying a Boutiques default. Restricted to single-segment (root) field access
 * so a nested field can never accidentally pick up a same-named root default.
 */
-function rootFieldDefault$3(binding, defaults) {
-	const a = binding.access;
-	if (a.length === 1 && a[0]?.kind === "field") return defaults.get(binding.name);
-}
 /**
 * Render a binding's access for an UNCONDITIONAL value read (terminal, repeat
 * loop, alternative dispatch): substitutes the field's default via
@@ -3549,7 +5558,7 @@ function rootFieldDefault$3(binding, defaults) {
 * via `.get()`).
 */
 function readAccess$1(binding, arg) {
-	const def = rootFieldDefault$3(binding, arg.defaults);
+	const def = rootFieldDefault(binding, arg.defaults);
 	return accessOf$1(binding, arg, def !== void 0 ? { finalDefault: def } : {});
 }
 /**
@@ -3569,21 +5578,6 @@ function accessOf$1(binding, arg, opts = {}) {
 		subst: arg.valueSubst
 	});
 }
-/**
-* Build the field-name -> rendered-default map for a struct root (else empty).
-* Includes only non-optional defaulted fields (optional fields are
-* presence-guarded; their default comes from the factory's kwarg signature).
-*/
-function collectDefaults$3(ctx, rootType) {
-	const out = /* @__PURE__ */ new Map();
-	if (rootType?.kind !== "struct") return out;
-	for (const [name, fi] of collectFieldInfo(ctx, rootType)) {
-		if (fi.defaultValue === void 0) continue;
-		if (rootType.fields[name]?.kind === "optional") continue;
-		out.set(name, renderPyLiteral(fi.defaultValue));
-	}
-	return out;
-}
 let loopVarCounter$1 = 0;
 let optVarCounter = 0;
 /**
@@ -3599,7 +5593,7 @@ function buildArgs$1(rootExpr, ctx, rootType) {
 		joinDepth: 0,
 		loopVars: /* @__PURE__ */ new Map(),
 		valueSubst: /* @__PURE__ */ new Map(),
-		defaults: collectDefaults$3(ctx, rootType)
+		defaults: collectDefaults(ctx, renderPyLiteral, rootType)
 	});
 }
 function walk$2(node, ctx, arg) {
@@ -3759,8 +5753,8 @@ function walkAlternative$1(node, ctx, arg) {
 */
 function emitDocstring(cb, text) {
 	if (!text) return;
-	const lines = text.split("\n");
-	if (lines.length === 1 && !lines[0].includes("\"")) {
+	const lines = text.replace(/"""/g, "\\\"\\\"\\\"").split("\n");
+	if (lines.length === 1 && !lines[0].includes("\"") && !lines[0].endsWith("\\")) {
 		cb.line(`"""${lines[0]}"""`);
 		return;
 	}
@@ -3768,20 +5762,18 @@ function emitDocstring(cb, text) {
 	for (const line of lines) cb.line(line);
 	cb.line(`"""`);
 }
-function emitImports$1(cb, emitOutputs) {
-	cb.line("import dataclasses");
+function emitImports$1(cb) {
 	cb.line("import pathlib");
 	cb.line("import typing");
 	cb.blank();
-	const fromStyxdefs = [
+	cb.line(`from styxdefs import ${[
 		"Execution",
 		"InputPathType",
 		"Metadata",
 		"Runner",
-		"StyxValidationError"
-	];
-	if (emitOutputs) fromStyxdefs.push("OutputPathType");
-	cb.line(`from styxdefs import ${fromStyxdefs.join(", ")}, get_global_runner`);
+		"StyxValidationError",
+		"OutputPathType"
+	].join(", ")}, get_global_runner`);
 }
 function emitMetadata$1(ctx, metaConst, cb) {
 	const id = ctx.app?.id ?? "unknown";
@@ -4283,9 +6275,10 @@ function renderInputTrait(p) {
 		case "str": return call("traits.Str", [...hasDef ? [renderPyLiteral(def), "usedefault=True"] : [], ...tail]);
 		case "enum": {
 			const choices = p.choices ?? [];
+			const defChoice = hasDef && def !== void 0 && typeof def !== "boolean" && choices.includes(def) ? def : void 0;
 			return call("traits.Enum", [
-				...(hasDef ? [def, ...choices.filter((c) => c !== def)] : choices).map((c) => renderPyLiteral(c)),
-				...hasDef ? ["usedefault=True"] : [],
+				...(defChoice !== void 0 ? [defChoice, ...choices.filter((c) => c !== defChoice)] : choices).map((c) => renderPyLiteral(c)),
+				...defChoice !== void 0 ? ["usedefault=True"] : [],
 				...tail
 			]);
 		}
@@ -4765,7 +6758,7 @@ function emitValue$1(e, type, node, wireKey, valueExpr, expected) {
 			const itemNode = findRepeatNode(node)?.attrs.node;
 			const elem = e.scope.add("e");
 			e.cb.line(`for ${elem} in ${valueExpr}:`);
-			e.cb.indent(() => emitValue$1(e, type.item, itemNode, wireKey, elem, expected));
+			e.cb.indent(() => emitValue$1(e, type.item, itemNode, wireKey, elem, expectedType$1(e, type.item)));
 			return;
 		}
 		case "struct":
@@ -5052,10 +7045,9 @@ function streamFieldIds$1(ctx) {
 	if (ctx.app?.stderr) res.stderr = fields[idx++].id;
 	return res;
 }
-/** Emit `@dataclasses.dataclass\nclass <outputsType>:` declaration. */
+/** Emit `class <outputsType>(typing.NamedTuple):` declaration. */
 function emitOutputsClass(ctx, outputsType, cb) {
-	cb.line("@dataclasses.dataclass");
-	cb.line(`class ${outputsType}:`);
+	cb.line(`class ${outputsType}(typing.NamedTuple):`);
 	cb.indent(() => {
 		emitDocstring(cb, "Output paths produced by the tool.");
 		const fields = collectOutputFields(ctx, pyId);
@@ -5074,26 +7066,6 @@ function emitOutputsClass(ctx, outputsType, cb) {
 		}
 	});
 }
-/** The rendered default for a binding iff it is a root-level defaulted field. */
-function rootFieldDefault$2(binding, defaults) {
-	if (!binding) return void 0;
-	const a = binding.access;
-	if (a.length === 1 && a[0]?.kind === "field") return defaults.get(binding.name);
-}
-/** Build the field-name -> rendered-default map for the struct root (else empty).
-* Includes only non-optional defaulted fields (optional fields are
-* presence-guarded; their default comes from the factory's kwarg signature). */
-function collectDefaults$2(ctx) {
-	const out = /* @__PURE__ */ new Map();
-	const rootType = ctx.resolve(ctx.expr)?.type;
-	if (rootType?.kind !== "struct") return out;
-	for (const [name, fi] of collectFieldInfo(ctx, rootType)) {
-		if (fi.defaultValue === void 0) continue;
-		if (rootType.fields[name]?.kind === "optional") continue;
-		out.set(name, renderPyLiteral(fi.defaultValue));
-	}
-	return out;
-}
 let loopCounter$1 = 0;
 function renderWrapperOpen$1(atom, ec) {
 	if (atom.kind === "iter") {
@@ -5104,7 +7076,13 @@ function renderWrapperOpen$1(atom, ec) {
 			loopVar: v
 		};
 	}
-	if (atom.kind === "variant") return { open: `if ${bindingAccess$1(atom.binding, ec)}["@type"] == ${pyStr(atom.variant)}:` };
+	if (atom.kind === "variant") {
+		const access = bindingAccess$1(atom.binding, ec);
+		const check = `${access}["@type"] == ${pyStr(atom.variant)}`;
+		const union = variantAtomUnion(atom, ec.ctx.bindings);
+		if (union && unionIsMixed(union)) return { open: `if isinstance(${access}, dict) and ${check}:` };
+		return { open: `if ${check}:` };
+	}
 	const binding = ec.ctx.bindings.get(atom.binding);
 	if (binding?.type.kind === "optional") {
 		const subscriptAccess = bindingAccess$1(atom.binding, ec);
@@ -5160,7 +7138,7 @@ function renderToken$1(tok, ec) {
 	return renderRefValue$1(tok, ec);
 }
 function renderRefValue$1(tok, ec) {
-	const def = rootFieldDefault$2(ec.ctx.bindings.get(tok.binding), ec.defaults);
+	const def = rootFieldDefault(ec.ctx.bindings.get(tok.binding), ec.defaults);
 	let expr = def !== void 0 && !ec.iter.has(tok.binding) ? bindingAccess$1(tok.binding, ec, false, def) : bindingAccess$1(tok.binding, ec);
 	if (tok.fallback !== void 0) expr = `(${expr} if ${expr} is not None else ${pyStr(tok.fallback)})`;
 	if (tok.stripExtensions && tok.stripExtensions.length > 0) {
@@ -5223,7 +7201,7 @@ function emitBuildOutputs$1(ctx, paramsType, outputsType, funcName, cb) {
 			ctx,
 			iter: /* @__PURE__ */ new Map(),
 			subst: /* @__PURE__ */ new Map(),
-			defaults: collectDefaults$2(ctx)
+			defaults: collectDefaults(ctx, renderPyLiteral)
 		};
 		const fields = collectOutputFields(ctx, pyId);
 		const localVarOf = /* @__PURE__ */ new Map();
@@ -5260,11 +7238,16 @@ function emitBuildOutputs$1(ctx, paramsType, outputsType, funcName, cb) {
 		}
 	});
 }
-/** Sanitize an output name to a valid Python identifier. */
+/**
+* Sanitize an output name to a valid Python identifier. Uses a *letter*-leading
+* prefix (`v_`) for digit-leading / empty names, never a leading underscore:
+* the Outputs type is a `typing.NamedTuple`, which raises `ValueError` at import
+* time for a field whose name starts with `_`. Matches styx1 and `pyScrubIdent`.
+* (A trailing underscore for keywords is fine - only leading underscores fail.)
+*/
 function pyId(name) {
 	let s = name.replace(/[^a-zA-Z0-9_]/g, "_");
-	if (/^\d/.test(s)) s = "_" + s;
-	if (s === "") s = "_";
+	if (/^\d/.test(s) || s === "") s = "v_" + s;
 	if (PY_KEYWORDS.has(s)) s = s + "_";
 	return s;
 }
@@ -5450,13 +7433,22 @@ function buildEmitModel(ctx, scope = new Scope(PY_RESERVED)) {
 	};
 }
 function generatePython(ctx, packageScope) {
+	return generatePythonModule(ctx, packageScope).code;
+}
+/**
+* Emit the module and, alongside it, the dispatch entrypoint carrying the
+* *scope-registered* execute-function name. Computing the entrypoint here (not
+* via the scope-blind `appEntrypoint`) keeps the suite dispatcher in sync with
+* the actual emitted symbol when a shared package scope suffix-bumps a collision.
+*/
+function generatePythonModule(ctx, packageScope) {
 	const cb = new CodeBuilder("    ");
 	const scope = packageScope ?? new Scope(PY_RESERVED);
 	const { names, rootType, rootIsStruct, namedTypes, typeDecls, rootTypeTag, paramsType, sigEntries, nestedFactories } = buildEmitModel(ctx, scope);
 	cb.comment("This file was auto generated by Styx.", "# ");
 	cb.comment("Do not edit this file directly.", "# ");
 	cb.blank();
-	emitImports$1(cb, true);
+	emitImports$1(cb);
 	cb.blank();
 	emitMetadata$1(ctx, names.metadata, cb);
 	cb.blank();
@@ -5481,7 +7473,8 @@ function generatePython(ctx, packageScope) {
 	cb.blank();
 	emitBuildOutputs$1(ctx, paramsType, names.outputs, names.outputsFn, cb);
 	cb.blank();
-	emitWrapperFunction$1(ctx, paramsType, rootIsStruct ? names.execute : names.wrapper, names.metadata, names.cargs, names.outputsFn, names.outputs, names.validate, streamFieldIds$1(ctx), cb);
+	const executeName = rootIsStruct ? names.execute : names.wrapper;
+	emitWrapperFunction$1(ctx, paramsType, executeName, names.metadata, names.cargs, names.outputsFn, names.outputs, names.validate, streamFieldIds$1(ctx), cb);
 	cb.blank();
 	if (rootIsStruct) {
 		emitKwargWrapper$1(ctx, sigEntries, names.wrapper, names.paramsFn, names.execute, names.outputs, cb);
@@ -5489,10 +7482,10 @@ function generatePython(ctx, packageScope) {
 	}
 	const publicSymbols = [
 		names.params,
-		...[names.outputs],
+		names.outputs,
 		names.metadata,
 		names.cargs,
-		...[names.outputsFn],
+		names.outputsFn,
 		...rootIsStruct ? [names.paramsFn, names.execute] : [],
 		...nestedFactories.map((nf) => nf.funcName),
 		names.validate,
@@ -5503,7 +7496,16 @@ function generatePython(ctx, packageScope) {
 		for (const sym of publicSymbols) cb.line(`"${sym}",`);
 	});
 	cb.line("]");
-	return cb.toString();
+	const appId = ctx.app?.id;
+	const pkg = ctx.package?.name;
+	const entrypoint = appId && pkg ? {
+		type: `${pkg}/${appId}`,
+		executeFn: executeName
+	} : void 0;
+	return {
+		code: cb.toString(),
+		entrypoint
+	};
 }
 /**
 * Module name (file stem) for an app: snake_case of app.id, fallback `output`.
@@ -5515,22 +7517,6 @@ function appModuleName$1(meta) {
 	return pyScrubIdent(snakeCase(meta.id), PY_RESERVED);
 }
 /**
-* The dispatch entrypoint for one app: its root `@type` (`<package>/<app>`) and
-* the dict-style execute function name. Returns undefined when the id or package
-* is unknown (no stable `@type`), so the app is left out of the suite dispatcher.
-*/
-function appEntrypoint$1(ctx) {
-	const appId = ctx.app?.id;
-	const pkg = ctx.package?.name;
-	if (!appId || !pkg) return void 0;
-	const publicNames = computePublicNames$1(appId);
-	const executeFn = pyScrubIdent(ctx.resolve(ctx.expr)?.type.kind === "struct" ? publicNames.execute : publicNames.wrapper, PY_RESERVED);
-	return {
-		type: `${pkg}/${appId}`,
-		executeFn
-	};
-}
-/**
 * Generate the suite-level `__init__.py` re-export for a package containing
 * multiple tool modules. Each tool module's public symbols are surfaced via
 * `from .bet import *` (each tool file defines `__all__`). When apps carry a
@@ -5567,10 +7553,11 @@ function emitPackageDispatch$1(cb, dispatch) {
 			for (const e of dispatch) cb.line(`${JSON.stringify(e.type)}: ${e.executeFn},`);
 		});
 		cb.line("}");
-		cb.line("_fn = _dispatch.get(params[\"@type\"])");
+		cb.line("_type = params.get(\"@type\")");
+		cb.line("_fn = _dispatch.get(_type) if _type is not None else None");
 		cb.line("if _fn is None:");
 		cb.indent(() => {
-			cb.line(`raise ValueError(f"No tool registered for @type {params['@type']!r}")`);
+			cb.line(`raise ValueError(f"No tool registered for @type {_type!r}")`);
 		});
 		cb.line("return _fn(params, runner)");
 	});
@@ -5579,11 +7566,11 @@ var PythonBackend = class {
 	name = "python";
 	target = "python";
 	emitApp(ctx, scope) {
-		const code = generatePython(ctx, scope);
+		const { code, entrypoint } = generatePythonModule(ctx, scope);
 		const fileName = `${appModuleName$1(ctx.app)}.py`;
 		return {
 			meta: ctx.app,
-			entrypoint: appEntrypoint$1(ctx),
+			entrypoint,
 			files: new Map([[fileName, code]]),
 			errors: [],
 			warnings: []
@@ -6577,6 +8564,10 @@ var JsonSchemaBackend = class {
 
 //#endregion
 //#region src/backend/typescript/typemap.ts
+const TS_IDENT_RE$1 = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function objKey(key) {
+	return TS_IDENT_RE$1.test(key) ? key : JSON.stringify(key);
+}
 function mapType(type, resolve) {
 	switch (type.kind) {
 		case "scalar": return {
@@ -6596,7 +8587,7 @@ function mapType(type, resolve) {
 		case "struct": {
 			const name = resolve(type);
 			if (name) return name;
-			return `{ ${Object.entries(type.fields).filter(([, v]) => v.kind !== "literal").map(([k, v]) => `${k}: ${mapType(v, resolve)}`).join("; ")} }`;
+			return `{ ${Object.entries(type.fields).filter(([, v]) => v.kind !== "literal").map(([k, v]) => `${objKey(k)}: ${mapType(v, resolve)}`).join("; ")} }`;
 		}
 		case "union": {
 			const name = resolve(type);
@@ -6758,10 +8749,6 @@ function accessOf(binding, arg) {
 * carrying a Boutiques default. Restricted to single-segment (root) field access
 * so a nested field can never accidentally pick up a same-named root default.
 */
-function rootFieldDefault$1(binding, defaults) {
-	const a = binding.access;
-	if (a.length === 1 && a[0]?.kind === "field") return defaults.get(binding.name);
-}
 /**
 * Render a binding's access for an UNCONDITIONAL value read (terminal, repeat
 * loop, alternative dispatch): substitutes the field's default via
@@ -6770,22 +8757,9 @@ function rootFieldDefault$1(binding, defaults) {
 * emitted code is byte-identical to before for the common case.
 */
 function readAccess(binding, arg) {
-	const def = rootFieldDefault$1(binding, arg.defaults);
+	const def = rootFieldDefault(binding, arg.defaults);
 	return def !== void 0 ? `(${accessOf(binding, arg)} ?? ${def})` : accessOf(binding, arg);
 }
-/** Build the field-name -> rendered-default map for a struct root (else empty).
-* Includes only non-optional defaulted fields (optional fields are
-* presence-guarded; their default comes from the factory's kwarg signature). */
-function collectDefaults$1(ctx, rootType) {
-	const out = /* @__PURE__ */ new Map();
-	if (rootType?.kind !== "struct") return out;
-	for (const [name, fi] of collectFieldInfo(ctx, rootType)) {
-		if (fi.defaultValue === void 0) continue;
-		if (rootType.fields[name]?.kind === "optional") continue;
-		out.set(name, renderTsLiteral(fi.defaultValue));
-	}
-	return out;
-}
 let loopVarCounter = 0;
 /**
 * Build arg-building code for an IR tree via recursive descent.
@@ -6798,7 +8772,7 @@ function buildArgs(rootExpr, ctx, rootType) {
 	return walk$1(rootExpr, ctx, {
 		joinDepth: 0,
 		loopVars: /* @__PURE__ */ new Map(),
-		defaults: collectDefaults$1(ctx, rootType)
+		defaults: collectDefaults(ctx, renderTsLiteral, rootType)
 	});
 }
 function walk$1(node, ctx, arg) {
@@ -6953,7 +8927,7 @@ function walkAlternative(node, ctx, arg) {
 //#region src/backend/typescript/emit.ts
 function emitJsDoc(cb, description) {
 	if (!description) return;
-	const lines = description.split("\n");
+	const lines = description.replace(/\*\//g, "*\\/").split("\n");
 	if (lines.length === 1) cb.line(`/** ${lines[0]} */`);
 	else {
 		cb.line("/**");
@@ -6961,15 +8935,14 @@ function emitJsDoc(cb, description) {
 		cb.line(" */");
 	}
 }
-function emitImports(cb, emitOutputs) {
-	const inputs = [
+function emitImports(cb) {
+	cb.line(`import type { ${[
 		"Runner",
 		"Execution",
 		"Metadata",
-		"InputPathType"
-	];
-	if (emitOutputs) inputs.push("OutputPathType");
-	cb.line(`import type { ${inputs.join(", ")} } from "styxdefs";`);
+		"InputPathType",
+		"OutputPathType"
+	].join(", ")} } from "styxdefs";`);
 	cb.line("import { getGlobalRunner, StyxValidationError } from \"styxdefs\";");
 }
 function emitMetadata(ctx, metaConst, cb) {
@@ -7313,7 +9286,7 @@ function emitValue(e, type, node, wireKey, access, expected) {
 			const itemNode = findRepeatNode(node)?.attrs.node;
 			const elem = e.scope.add("el");
 			e.cb.line(`for (const ${elem} of ${access}) {`);
-			e.cb.indent(() => emitValue(e, type.item, itemNode, wireKey, elem, expected));
+			e.cb.indent(() => emitValue(e, type.item, itemNode, wireKey, elem, expectedType(e, type.item)));
 			e.cb.line("}");
 			return;
 		}
@@ -7448,26 +9421,6 @@ function emitOutputsInterface(ctx, outputsType, cb) {
 	});
 	cb.line(`}`);
 }
-/** The rendered default for a binding iff it is a root-level defaulted field. */
-function rootFieldDefault(binding, defaults) {
-	if (!binding) return void 0;
-	const a = binding.access;
-	if (a.length === 1 && a[0]?.kind === "field") return defaults.get(binding.name);
-}
-/** Build the field-name -> rendered-default map for the struct root (else empty).
-* Includes only non-optional defaulted fields (optional fields are
-* presence-guarded; their default comes from the factory's kwarg signature). */
-function collectDefaults(ctx) {
-	const out = /* @__PURE__ */ new Map();
-	const rootType = ctx.resolve(ctx.expr)?.type;
-	if (rootType?.kind !== "struct") return out;
-	for (const [name, fi] of collectFieldInfo(ctx, rootType)) {
-		if (fi.defaultValue === void 0) continue;
-		if (rootType.fields[name]?.kind === "optional") continue;
-		out.set(name, renderTsLiteral(fi.defaultValue));
-	}
-	return out;
-}
 /**
 * Render one output's wrapper stack and emit the assignment inside the
 * innermost wrapper. Nesting is done via recursive callbacks so the
@@ -7511,10 +9464,15 @@ function renderWrapperOpen(atom, ec) {
 			loopVar: v
 		};
 	}
-	if (atom.kind === "variant") return {
-		open: `if (${bindingAccess(atom.binding, ec)}["@type"] === ${JSON.stringify(atom.variant)}) {`,
-		close: `}`
-	};
+	if (atom.kind === "variant") {
+		const access = bindingAccess(atom.binding, ec);
+		const check = `${access}["@type"] === ${JSON.stringify(atom.variant)}`;
+		const union = variantAtomUnion(atom, ec.ctx.bindings);
+		return {
+			open: `if (${union && unionIsMixed(union) ? `typeof ${access} === "object" && ${access} !== null && ${check}` : check}) {`,
+			close: `}`
+		};
+	}
 	const binding = ec.ctx.bindings.get(atom.binding);
 	const access = bindingAccess(atom.binding, ec);
 	return {
@@ -7586,7 +9544,7 @@ function emitBuildOutputs(ctx, paramsType, outputsType, funcName, cb) {
 			ctx,
 			iter: /* @__PURE__ */ new Map(),
 			fieldShapes: new Map(fields.map((f) => [f.id, f.shape])),
-			defaults: collectDefaults(ctx)
+			defaults: collectDefaults(ctx, renderTsLiteral)
 		};
 		cb.line(`const outputs: ${outputsType} = {`);
 		cb.indent(() => {
@@ -7756,13 +9714,22 @@ function buildEmitModel$1(ctx, scope = new Scope(TS_RESERVED)) {
 	};
 }
 function generateTypeScript(ctx, packageScope) {
+	return generateTypeScriptModule(ctx, packageScope).code;
+}
+/**
+* Emit the module and, alongside it, the dispatch entrypoint carrying the
+* *scope-registered* execute-function name. Computing the entrypoint here (not
+* via the scope-blind `appEntrypoint`) keeps the suite dispatcher in sync with
+* the actual emitted symbol when a shared package scope suffix-bumps a collision.
+*/
+function generateTypeScriptModule(ctx, packageScope) {
 	const cb = new CodeBuilder("  ");
 	const scope = packageScope ?? new Scope(TS_RESERVED);
 	const { appId, pkg, names, rootType, rootIsStruct, namedTypes, typeDecls, rootTypeTag, paramsType, sigEntries } = buildEmitModel$1(ctx, scope);
 	cb.comment("This file was auto generated by Styx.");
 	cb.comment("Do not edit this file directly.");
 	cb.blank();
-	emitImports(cb, true);
+	emitImports(cb);
 	cb.blank();
 	emitMetadata(ctx, names.metadata, cb);
 	cb.blank();
@@ -7783,13 +9750,23 @@ function generateTypeScript(ctx, packageScope) {
 	cb.blank();
 	emitBuildOutputs(ctx, paramsType, names.outputs, names.outputsFn, cb);
 	cb.blank();
-	emitWrapperFunction(ctx, paramsType, rootIsStruct ? names.execute : names.wrapper, names.metadata, names.cargs, names.outputsFn, names.outputs, names.validate, streamFieldIds(ctx), cb);
+	const executeName = rootIsStruct ? names.execute : names.wrapper;
+	emitWrapperFunction(ctx, paramsType, executeName, names.metadata, names.cargs, names.outputsFn, names.outputs, names.validate, streamFieldIds(ctx), cb);
 	cb.blank();
 	if (rootIsStruct) {
 		emitKwargWrapper(ctx, sigEntries, names.wrapper, names.paramsFn, names.execute, names.outputs, cb);
 		cb.blank();
 	}
-	return cb.toString();
+	const entryAppId = ctx.app?.id;
+	const entryPkg = ctx.package?.name;
+	const entrypoint = entryAppId && entryPkg ? {
+		type: `${entryPkg}/${entryAppId}`,
+		executeFn: executeName
+	} : void 0;
+	return {
+		code: cb.toString(),
+		entrypoint
+	};
 }
 /**
 * Module name (file stem) for an app: snake_case of app.id, fallback `output`.
@@ -7871,11 +9848,11 @@ var TypeScriptBackend = class {
 	name = "typescript";
 	target = "typescript";
 	emitApp(ctx, scope) {
-		const code = generateTypeScript(ctx, scope);
+		const { code, entrypoint } = generateTypeScriptModule(ctx, scope);
 		const fileName = `${appModuleName(ctx.app)}.ts`;
 		return {
 			meta: ctx.app,
-			entrypoint: appEntrypoint(ctx),
+			entrypoint,
 			files: new Map([[fileName, code]]),
 			errors: [],
 			warnings: []
@@ -8141,6 +10118,15 @@ const canonicalize = {
 				default: return "";
 			}
 		}
+		function identityKey(node) {
+			const m = node.meta;
+			const metaKey = m ? [
+				m.name ?? "",
+				m.variantTag ?? "",
+				m.outputs ? JSON.stringify(m.outputs) : ""
+			].join("|") : "";
+			return `${structuralHash(node)}#${metaKey}`;
+		}
 		function sortKey(node) {
 			const name = node.meta?.name ?? "";
 			return `${node.kind}:${name}:${structuralHash(node)}`;
@@ -8153,13 +10139,13 @@ const canonicalize = {
 					const seen = /* @__PURE__ */ new Set();
 					const alts = [];
 					for (const child of sorted) {
-						const hash = structuralHash(child);
-						if (!seen.has(hash)) {
-							seen.add(hash);
+						const key = identityKey(child);
+						if (!seen.has(key)) {
+							seen.add(key);
 							alts.push(child);
 						} else changed = true;
 					}
-					if (alts.length !== children.length || alts.some((alt, i) => structuralHash(alt) !== structuralHash(children[i]))) changed = true;
+					if (alts.length !== children.length || alts.some((alt, i) => identityKey(alt) !== identityKey(children[i]))) changed = true;
 					return {
 						...node,
 						attrs: {
@@ -8442,11 +10428,24 @@ const simplify = {
 						const prev = nodes[nodes.length - 1];
 						if (prev?.kind === "literal" && child.kind === "literal" && !prev.meta && !child.meta && node.attrs.join === "") {
 							changed = true;
-							prev.attrs.str += child.attrs.str;
+							nodes[nodes.length - 1] = {
+								...prev,
+								attrs: {
+									...prev.attrs,
+									str: prev.attrs.str + child.attrs.str
+								}
+							};
 						} else nodes.push(child);
 					}
 					if (nodes.length === 1) {
 						const child = nodes[0];
+						if (node.meta?.outputs?.length && child.kind === "literal") return {
+							...node,
+							attrs: {
+								...node.attrs,
+								nodes
+							}
+						};
 						changed = true;
 						const mergedMeta = mergeMeta(node.meta, child.meta);
 						return mergedMeta ? {
@@ -8864,7 +10863,7 @@ function defaultNamingStrategy() {
 function isBooleanLiteralPair(variants) {
 	if (variants.length !== 2 || !variants.every((v) => v.type.kind === "literal")) return false;
 	const [a, b] = variants.map((v) => v.type.kind === "literal" ? v.type.value : null);
-	return a === 0 && b === 1 || a === 1 && b === 0 || a === "0" && b === "1" || a === "1" && b === "0" || a === "false" && b === "true" || a === "true" && b === "false";
+	return a === 0 && b === 1 || a === 1 && b === 0 || a === "false" && b === "true" || a === "true" && b === "false";
 }
 function literalFromNode(node) {
 	const str = node.attrs.str;
@@ -9090,7 +11089,8 @@ function solve(expr, options) {
 //#region src/index.ts
 function compile(source, filenameOrOptions) {
 	const options = typeof filenameOrOptions === "string" ? { filename: filenameOrOptions } : filenameOrOptions ?? {};
-	const format = options.format ?? detectFormat(source);
+	const byExtension = options.filename?.endsWith(".argtype") ? "argtype" : void 0;
+	const format = options.format ?? byExtension ?? detectFormat(source);
 	if (!format) return {
 		expr: {
 			kind: "sequence",
@@ -9099,10 +11099,20 @@ function compile(source, filenameOrOptions) {
 		errors: [{ message: "Could not detect input format. Specify format explicitly." }],
 		warnings: []
 	};
-	return (format === "argdump" ? new ArgdumpParser() : format === "workbench" ? new WorkbenchParser() : format === "mrtrix" ? new MrtrixParser() : new BoutiquesParser()).parse(source, options.filename);
+	return (() => {
+		switch (format) {
+			case "argdump": return new ArgdumpParser();
+			case "argtype": return new ArgtypeParser();
+			case "workbench": return new WorkbenchParser();
+			case "mrtrix": return new MrtrixParser();
+			case "boutiques": return new BoutiquesParser();
+			default: return new BoutiquesParser();
+		}
+	})().parse(source, options.filename);
 }
 
 //#endregion
+exports.ArgtypeBackend = ArgtypeBackend;
 exports.BoutiquesBackend = BoutiquesBackend;
 exports.CodeBuilder = CodeBuilder;
 exports.JsonSchemaBackend = JsonSchemaBackend;
@@ -9124,7 +11134,6 @@ exports.camelCase = camelCase;
 exports.canonicalize = canonicalize;
 exports.collectFieldInfo = collectFieldInfo;
 exports.collectNamedTypes = collectNamedTypes;
-exports.compactTokens = compactTokens;
 exports.compile = compile;
 exports.compose = compose;
 exports.createContext = createContext;
@@ -9141,6 +11150,7 @@ exports.flatten = flatten;
 exports.float = float;
 exports.format = format;
 exports.formatSolveResult = formatSolveResult;
+exports.generateArgtype = generateArgtype;
 exports.generateBoutiques = generateBoutiques;
 exports.generateNipype = generateNipype;
 exports.generateOutputsSchema = generateOutputsSchema;
@@ -9149,8 +11159,6 @@ exports.generatePython = generatePython;
 exports.generateSchema = generateSchema;
 exports.generateTypeScript = generateTypeScript;
 exports.int = int;
-exports.isGated = isGated;
-exports.isIterated = isIterated;
 exports.isStructural = isStructural;
 exports.isTerminal = isTerminal;
 exports.lit = lit;
@@ -9160,8 +11168,6 @@ exports.opt = opt;
 exports.outputGate = outputGate;
 exports.pascalCase = pascalCase;
 exports.path = path;
-exports.planOutput = planOutput;
-exports.planScope = planScope;
 exports.pydraNames = pydraNames;
 exports.removeEmpty = removeEmpty;
 exports.renderPythonCall = renderPythonCall;