@styx-api/core 0.7.0 → 0.8.0

package/dist/index.mjs

@@ -205,10 +205,7 @@ var ArgdumpParser = class {
 			if (nargs.__argparse__ === "REMAINDER") return {
 				kind: "repeat",
 				attrs: {
-					node: {
-						kind: "str",
-						attrs: {}
-					},
+					node,
 					countMin: 0
 				}
 			};
@@ -579,25 +576,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;
@@ -657,23 +653,19 @@ var ArgdumpParser = class {
 		};
 		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);
-			}
+			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(actionsByDest, mutexGroups, allNodes, nodesByDest);
+		if (isArray$3(mutexGroups) && mutexGroups.length > 0) allNodes = this.applyMutualExclusion(mutexGroups, allNodes, nodesByDest);
 		return {
 			kind: "sequence",
 			attrs: { nodes: allNodes }
@@ -863,6 +855,18 @@ function lex(source) {
 					});
 				}
 			}
+			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;
 		}
@@ -1022,7 +1026,44 @@ function findColon(s) {
 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;
@@ -1235,6 +1276,37 @@ const KNOWN_METHODS = new Set([
 	"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;
@@ -1361,38 +1433,41 @@ var Parser = class {
 		return {
 			kind: "comb",
 			op: "alt",
-			children: alts
+			children: alts,
+			...first.span && { span: first.span }
 		};
 	}
 	parseChain() {
 		const node = this.parsePrimary();
-		let chained = false;
 		while (this.at("dot")) {
 			this.next();
 			this.applyMethod(node);
-			chained = true;
 		}
 		if (this.at("eq")) {
-			const eqTok = this.next();
-			const value = this.parseValue();
-			if (node.kind === "terminal" && !chained) node.default = value;
-			else this.error("`= value` default is only allowed on a bare terminal; use `.default(...)` after a method chain", eqTok);
+			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
+				value: tok.value,
+				span
 			};
 		}
 		if (tok.kind === "lparen") return {
 			kind: "comb",
 			op: "seq",
-			children: this.parseParenList()
+			children: this.parseParenList(),
+			span
 		};
 		if (tok.kind === "ident") {
 			if (COMBINATORS.has(tok.value) && this.peek(1).kind === "lparen") {
@@ -1401,27 +1476,31 @@ var Parser = class {
 				return {
 					kind: "comb",
 					op: tok.value,
-					children
+					children,
+					span
 				};
 			}
 			if (TERMINALS.has(tok.value)) {
 				this.next();
 				return {
 					kind: "terminal",
-					terminal: tok.value
+					terminal: tok.value,
+					span
 				};
 			}
 			this.next();
 			return {
 				kind: "ref",
-				refName: tok.value
+				refName: tok.value,
+				span
 			};
 		}
 		this.error(`Unexpected token '${tok.value || tok.kind}' in expression`, tok);
 		this.next();
 		return {
 			kind: "literal",
-			value: ""
+			value: "",
+			span
 		};
 	}
 	/** Parse `( elem, elem, ... )` with optional leading docs and trailing comma. */
@@ -1449,7 +1528,8 @@ var Parser = class {
 		}
 		if (!KNOWN_METHODS.has(method)) {
 			this.skipBalancedArgs();
-			this.warn(`Ignoring unsupported method '.${method}()'`, nameTok);
+			const hint = suggestMethod(method, [...KNOWN_METHODS, "output"]);
+			this.warn(`Ignoring unsupported method '.${method}()'` + (hint ? ` (did you mean '.${hint}()'?)` : ""), nameTok);
 			return;
 		}
 		const args = this.parseScalarArgs();
@@ -1569,7 +1649,8 @@ var Parser = class {
 				else out.description = arg;
 			} else {
 				this.skipBalancedArgs();
-				this.warn(`Ignoring unsupported output-template method '.${m.value}()'`, m);
+				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;
@@ -1731,6 +1812,13 @@ function effectiveOutputName(output, index) {
 *   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 = {
@@ -1742,16 +1830,27 @@ function docFrom(node) {
 var Lowerer = class {
 	errors = [];
 	warnings = [];
-	/** Extensions whose annotations the document actually uses, collected during
-	* lowering so `lowerDocument` can flag any used-but-undeclared in frontmatter. */
-	usedExtensions = /* @__PURE__ */ new Set();
 	aliases = /* @__PURE__ */ new Map();
 	constructor(aliases) {
 		for (const a of aliases) {
-			if (this.aliases.has(a.name)) this.warnings.push(`Duplicate alias '${a.name}'; last definition wins`);
+			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);
@@ -1777,17 +1876,19 @@ var Lowerer = class {
 		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.warnings.push("`.join()` is only supported on seq/set/rep/opt; ignored here");
+		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.warnings.push("`.min()`/`.max()` is only supported on int/float terminals; ignored here");
-		if ((node.countMin !== void 0 || node.countMax !== void 0) && !isRep) this.warnings.push("`.count()`/`.countMin()`/`.countMax()` is only supported on rep; ignored here");
-		if ((node.mutable || node.resolveParent) && !isPath) this.warnings.push("`.mutable()`/`.resolveParent()` is only supported on path; ignored here");
-		if (node.mediaTypes?.length && !isPath) this.warnings.push("`.mediaType()` is only supported on path; ignored here");
-		if (node.outputs?.length) this.usedExtensions.add("outputs");
-		if (node.mediaTypes?.length && isPath) this.usedExtensions.add("mediatypes");
-		if ((node.mutable || node.resolveParent) && isPath) this.usedExtensions.add("paths");
+		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) {
@@ -1799,7 +1900,7 @@ var Lowerer = class {
 			case "terminal": return this.lowerTerminal(node);
 			case "comb": return this.lowerComb(node, expanding, name, sink);
 			default:
-				this.errors.push(`Unknown AST node kind '${node.kind}'`);
+				this.err(`Unknown AST node kind '${node.kind}'`, node);
 				return seq();
 		}
 	}
@@ -1807,14 +1908,15 @@ var Lowerer = class {
 		const target = node.refName;
 		const aliasExpr = this.aliases.get(target);
 		if (!aliasExpr) {
-			this.errors.push(`Unknown alias '${target}'`);
+			this.err(`Unknown alias '${target}'`, node);
 			return seq();
 		}
 		if (expanding.has(target)) {
-			this.errors.push(`Recursive alias '${target}' is not allowed`);
+			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;
@@ -1836,7 +1938,7 @@ var Lowerer = class {
 		switch (node.terminal) {
 			case "int": {
 				const e = int();
-				this.checkBounds(node.min, node.max, "value", "min", "max");
+				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);
@@ -1844,7 +1946,7 @@ var Lowerer = class {
 			}
 			case "float": {
 				const e = float();
-				this.checkBounds(node.min, node.max, "value", "min", "max");
+				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);
@@ -1864,7 +1966,7 @@ var Lowerer = class {
 				return e;
 			}
 			default:
-				this.errors.push(`Unknown terminal '${String(node.terminal)}'`);
+				this.err(`Unknown terminal '${String(node.terminal)}'`, node);
 				return str();
 		}
 	}
@@ -1877,7 +1979,7 @@ var Lowerer = class {
 				const selfOutputs = [];
 				for (const o of node.outputs ?? []) selfOutputs.push(this.toOutput(o, name));
 				const lowered = lowerChildren(selfOutputs);
-				this.dedupeSiblingNames(lowered);
+				this.dedupeSiblingNames(lowered, node);
 				const e = seq(...lowered);
 				if (node.join !== void 0) e.attrs.join = node.join;
 				this.applyMeta(e, node);
@@ -1889,14 +1991,14 @@ var Lowerer = class {
 			}
 			case "alt": {
 				const arms = lowerChildren(sink);
-				this.dedupeSiblingNames(arms);
+				this.dedupeSiblingNames(arms, node);
 				const e = alt(...arms);
 				this.applyMeta(e, node);
 				return e;
 			}
 			case "any": {
 				if (children.length === 0) {
-					this.errors.push("`any(...)` requires at least one branch");
+					this.err("`any(...)` requires at least one branch", node);
 					return seq();
 				}
 				const e = this.lowerNode(children[0], expanding, name, sink);
@@ -1927,21 +2029,21 @@ var Lowerer = class {
 			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");
+				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.errors.push(`Unknown combinator '${String(node.op)}'`);
+				this.err(`Unknown combinator '${String(node.op)}'`, node);
 				return seq();
 		}
 	}
 	/** 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) {
-		if (min !== void 0 && max !== void 0 && min > max) this.warnings.push(`Inverted ${what} bounds: ${minLabel} (${min}) > ${maxLabel} (${max})`);
+	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
@@ -1955,7 +2057,7 @@ var Lowerer = class {
 	* explicit labels; it does not detect collisions between solver-derived names
 	* of otherwise-unnamed children, which the solver also does not guard.)
 	*/
-	dedupeSiblingNames(children) {
+	dedupeSiblingNames(children, parent) {
 		const used = /* @__PURE__ */ new Set();
 		for (const child of children) {
 			const nm = child.meta?.name;
@@ -1972,7 +2074,7 @@ var Lowerer = class {
 				...child.meta,
 				name: renamed
 			};
-			this.warnings.push(`Duplicate sibling name '${nm}'; renamed one occurrence to '${renamed}'`);
+			this.warn(`Duplicate sibling name '${nm}'; renamed one occurrence to '${renamed}'`, parent);
 		}
 	}
 	/** `opt`/`rep` with multiple children implicitly wrap them in a sequence,
@@ -2011,15 +2113,15 @@ var Lowerer = class {
 			}
 			const targetName = t.name ?? selfName;
 			if (!targetName) {
-				this.warnings.push("Output self-reference '{}' has no named node to resolve to; emitting empty");
+				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.warnings.push("Output ref op 'strip_prefix' is not supported by the IR; ignored");
-			if (t.basename) this.warnings.push("Output ref op 'basename' is not supported by the IR; ignored");
+			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),
@@ -2027,7 +2129,7 @@ var Lowerer = class {
 				...t.or !== void 0 && { fallback: t.or }
 			});
 		}
-		if (o.fallback !== void 0) this.warnings.push("Output-level '.or(...)' fallback is not supported by the IR; ignored");
+		if (o.fallback !== void 0) this.warn("Output-level '.or(...)' fallback is not supported by the IR; ignored");
 		const doc = docFrom(o);
 		return {
 			...o.name && { name: o.name },
@@ -2056,6 +2158,17 @@ function buildAppMeta(fm, rootDoc, rootName) {
 	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 },
@@ -2105,28 +2218,18 @@ function isRecord$1(x) {
 	return typeof x === "object" && x !== null && !Array.isArray(x);
 }
 function lowerDocument(doc) {
-	const lowerer = new Lowerer(doc.aliases);
-	const result = lowerer.lower(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);
-	const extWarnings = [];
-	if (doc.frontmatter) {
-		const declared = new Set(Array.isArray(doc.frontmatter.extensions) ? doc.frontmatter.extensions.filter((e) => typeof e === "string") : []);
-		for (const used of lowerer.usedExtensions) if (!declared.has(used)) extWarnings.push(`Uses the '${used}' extension but does not declare it in frontmatter (add it to 'extensions:')`);
-	}
 	return {
 		...meta && { meta },
 		expr: result.expr,
 		errors: result.errors,
-		warnings: [
-			...result.warnings,
-			...warnings,
-			...extWarnings
-		]
+		warnings: [...result.warnings, ...warnings.map((message) => ({ message }))]
 	};
 }
 
@@ -2173,8 +2276,14 @@ var ArgtypeParser = class {
 			warnings
 		};
 		const lowered = lowerDocument(doc);
-		warnings.push(...lowered.warnings.map((message) => ({ message })));
-		errors.push(...lowered.errors.map((message) => ({ message })));
+		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,
@@ -2204,20 +2313,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 (!didSplit) destructed.push(x);
+		if (best === null) {
+			destructed.push(x);
+			continue;
+		}
+		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;
 }
@@ -2545,14 +2660,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;
 			}
@@ -2602,7 +2711,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: {
@@ -2701,13 +2813,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;
@@ -3785,25 +3900,6 @@ function syntheticWrap(root) {
 		...meta?.outputs && { outputs: meta.outputs }
 	};
 }
-function hasOutputs(expr) {
-	return walkSome(expr, (n) => (n.meta?.outputs?.length ?? 0) > 0);
-}
-function hasMediaTypes(expr) {
-	return walkSome(expr, (n) => n.kind === "path" && (n.attrs.mediaTypes?.length ?? 0) > 0);
-}
-function hasPaths(expr) {
-	return walkSome(expr, (n) => n.kind === "path" && (!!n.attrs.mutable || !!n.attrs.resolveParent));
-}
-function walkSome(node, pred) {
-	if (pred(node)) return true;
-	switch (node.kind) {
-		case "sequence": return node.attrs.nodes.some((n) => walkSome(n, pred));
-		case "alternative": return node.attrs.alts.some((n) => walkSome(n, pred));
-		case "optional": return walkSome(node.attrs.node, pred);
-		case "repeat": return walkSome(node.attrs.node, pred);
-		default: return false;
-	}
-}
 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
@@ -3900,7 +3996,7 @@ var ArgtypeEmitter = class {
 			};
 			if (raw.meta) root.meta = raw.meta;
 		}
-		const frontmatter = this.emitFrontmatter(app, exe, hasOutputs(root), hasMediaTypes(root), hasPaths(root));
+		const frontmatter = this.emitFrontmatter(app, exe);
 		if (frontmatter) lines.push(frontmatter, "");
 		const synthetic = syntheticWrap(root);
 		const defNode = synthetic ? synthetic.child : root;
@@ -4100,7 +4196,7 @@ var ArgtypeEmitter = class {
 	fmScalar(value) {
 		return quote(value);
 	}
-	emitFrontmatter(app, exe, outputs, mediaTypes, paths) {
+	emitFrontmatter(app, exe) {
 		const lines = [];
 		if (exe !== void 0) lines.push(`exe: ${this.fmScalar(exe)}`);
 		if (app) {
@@ -4129,14 +4225,6 @@ var ArgtypeEmitter = class {
 			if (app.stderr) this.emitStream(lines, "stderr", app.stderr);
 			if (app.doc?.comment) this.warn("AppMeta.doc.comment has no argtype surface; ignored");
 		}
-		const extensions = [];
-		if (outputs) extensions.push("outputs");
-		if (mediaTypes) extensions.push("mediatypes");
-		if (paths) extensions.push("paths");
-		if (extensions.length > 0) {
-			lines.push("extensions:");
-			for (const e of extensions) lines.push(`  - ${e}`);
-		}
 		if (lines.length === 0) return void 0;
 		return [
 			"---",
@@ -4278,6 +4366,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) {
@@ -4483,53 +4572,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/boutiques/boutiques.ts
 var BoutiquesEmitter = class {
@@ -4745,14 +4787,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);
@@ -4845,6 +4885,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"];
@@ -4871,6 +4912,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,
@@ -4894,6 +4944,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;
@@ -4982,8 +5034,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 = {};
@@ -4994,22 +5045,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;
@@ -5108,7 +5144,8 @@ var BoutiquesEmitter = class {
 				inputs: []
 			},
 			list: true,
-			minListEntries: countMin
+			minListEntries: countMin,
+			...countMin === 0 && { optional: true }
 		};
 	}
 };
@@ -5314,9 +5351,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
@@ -5454,10 +5547,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
@@ -5468,7 +5557,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 } : {});
 }
 /**
@@ -5488,21 +5577,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;
 /**
@@ -5518,7 +5592,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) {
@@ -5678,8 +5752,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;
 	}
@@ -5687,20 +5761,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";
@@ -6202,9 +6274,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
 			]);
 		}
@@ -6684,7 +6757,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":
@@ -6971,10 +7044,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);
@@ -6993,26 +7065,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") {
@@ -7023,7 +7075,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);
@@ -7079,7 +7137,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) {
@@ -7142,7 +7200,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();
@@ -7179,11 +7237,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;
 }
@@ -7369,13 +7432,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();
@@ -7400,7 +7472,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);
@@ -7408,10 +7481,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,
@@ -7422,7 +7495,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`.
@@ -7434,22 +7516,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
@@ -7486,10 +7552,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)");
 	});
@@ -7498,11 +7565,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: []
@@ -8496,6 +8563,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 {
@@ -8515,7 +8586,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);
@@ -8677,10 +8748,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
@@ -8689,22 +8756,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.
@@ -8717,7 +8771,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) {
@@ -8872,7 +8926,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("/**");
@@ -8880,15 +8934,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) {
@@ -9232,7 +9285,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;
 		}
@@ -9367,26 +9420,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
@@ -9430,10 +9463,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 {
@@ -9505,7 +9543,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(() => {
@@ -9675,13 +9713,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();
@@ -9702,13 +9749,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`.
@@ -9790,11 +9847,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: []
@@ -10060,6 +10117,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)}`;
@@ -10072,13 +10138,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: {
@@ -10361,11 +10427,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 ? {
@@ -10783,7 +10862,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;
@@ -11032,5 +11111,5 @@ function compile(source, filenameOrOptions) {
 }
 
 //#endregion
-export { ArgtypeBackend, BoutiquesBackend, CodeBuilder, JsonSchemaBackend, NipypeBackend, PYTHON_RUNNER_DEPS, PassStatus, PydraBackend, PythonBackend, STYXDEFS_COMPAT, Scope, TypeScriptBackend, alt, appEntrypoint, atomKey, buildEmitModel, buildSigEntries, buildTypedSpec, camelCase, canonicalize, collectFieldInfo, collectNamedTypes, compactTokens, compile, compose, createContext, createPipeline, createRegistry, defaultNamingStrategy, defaultPipeline, detectFormat, effectiveOutputName, findDoc, findStructNode, fixpoint, flatten, float, format, formatSolveResult, generateArgtype, generateBoutiques, generateNipype, generateOutputsSchema, generatePydra, generatePython, generateSchema, generateTypeScript, int, isGated, isIterated, isStructural, isTerminal, lit, nipypeNames, nodeRef, opt, outputGate, pascalCase, path, planOutput, planScope, pydraNames, removeEmpty, renderPythonCall, renderStructLiteral, renderTypeScriptCall, renderValue, rep, repJoin, resolveFieldBinding, resolveOutputs, resolveTypeName, screamingSnakeCase, seq, seqJoin, simplify, snakeCase, solve, str, structKey, typeKey, unionKey };
+export { ArgtypeBackend, BoutiquesBackend, CodeBuilder, JsonSchemaBackend, NipypeBackend, PYTHON_RUNNER_DEPS, PassStatus, PydraBackend, PythonBackend, STYXDEFS_COMPAT, Scope, TypeScriptBackend, alt, appEntrypoint, atomKey, buildEmitModel, buildSigEntries, buildTypedSpec, camelCase, canonicalize, collectFieldInfo, collectNamedTypes, compile, compose, createContext, createPipeline, createRegistry, defaultNamingStrategy, defaultPipeline, detectFormat, effectiveOutputName, findDoc, findStructNode, fixpoint, flatten, float, format, formatSolveResult, generateArgtype, generateBoutiques, generateNipype, generateOutputsSchema, generatePydra, generatePython, generateSchema, generateTypeScript, int, isStructural, isTerminal, lit, nipypeNames, nodeRef, opt, outputGate, pascalCase, path, pydraNames, removeEmpty, renderPythonCall, renderStructLiteral, renderTypeScriptCall, renderValue, rep, repJoin, resolveFieldBinding, resolveOutputs, resolveTypeName, screamingSnakeCase, seq, seqJoin, simplify, snakeCase, solve, str, structKey, typeKey, unionKey };
 //# sourceMappingURL=index.mjs.map