@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/primitives.cjs

@@ -1,42 +1,121 @@
-const require_annotations = require('./annotations.cjs');
+const require_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
-const require_dependency = require('./dependency.cjs');
-const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
+const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
+const require_dependency = require('./internal/dependency.cjs');
+const require_dependency_runtime = require('./dependency-runtime.cjs');
+const require_annotation_state = require('./annotation-state.cjs');
+const require_execution_context = require('./execution-context.cjs');
+const require_phase2_seed = require('./phase2-seed.cjs');
 const require_suggestion = require('./suggestion.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
+const require_dependency_metadata = require('./dependency-metadata.cjs');
 const require_valueparser = require('./valueparser.cjs');
 
 //#region src/primitives.ts
+/**
+* A shared empty set used as the `leadingNames` value for parsers that
+* do not match any specific name at the first buffer position.
+*/
+const EMPTY_LEADING_NAMES = /* @__PURE__ */ new Set();
 function hasParsedOptionValue(state, valueParser) {
-	if (valueParser != null) return require_dependency.isDeferredParseState(state) || require_dependency.isDependencySourceState(state) || state != null && "success" in state && state.success;
+	if (valueParser != null) return state != null && typeof state === "object" && "success" in state && typeof state.success === "boolean";
 	return state != null && "success" in state && state.success && state.value === true;
 }
 /**
-* Helper function to create the appropriate state for an option value.
-* - If the value parser is a DerivedValueParser, wraps the result in a DeferredParseState
-*   to allow later resolution with actual dependency values.
-* - If the value parser is a DependencySource, wraps the result in a DependencySourceState
-*   so that it can be matched with DeferredParseState during resolution.
+* Helper function to create the stored state for an option or argument value.
+*
+* Primitive parsers now keep only the plain parse result as their local state.
+* Any dependency-aware replay information is recorded separately in the
+* execution trace.
 * @internal
 */
-function createOptionParseState(rawInput, valueParser, parseResult) {
-	if (require_dependency.isDerivedValueParser(valueParser)) return require_dependency.createDeferredParseState(rawInput, valueParser, parseResult);
-	if (require_dependency.isDependencySource(valueParser)) return require_dependency.createDependencySourceState(parseResult, valueParser[require_dependency.dependencyId]);
+function createOptionParseState(parseResult) {
 	return parseResult;
 }
+function buildTraceEntry(kind, rawInput, consumed, valueParser, parseResult, optionNames$1) {
+	const entry = {
+		kind,
+		rawInput,
+		consumed,
+		preliminaryResult: parseResult,
+		...optionNames$1 != null ? { optionNames: optionNames$1 } : {},
+		metavar: valueParser.metavar
+	};
+	if (require_dependency.isDerivedValueParser(valueParser)) {
+		const defaults = require_dependency.getSnapshottedDefaultDependencyValues(parseResult);
+		if (defaults != null) return {
+			...entry,
+			defaultDependencyValues: defaults
+		};
+	}
+	return entry;
+}
+function recordTrace(context, entry) {
+	if (context.exec?.trace == null) return context;
+	const trace = context.exec.trace.set(context.exec.path, entry);
+	return {
+		...context,
+		trace,
+		exec: {
+			...context.exec,
+			trace
+		}
+	};
+}
+function resolveDerivedCompletionSync(derivedMetadata, state, exec) {
+	if (derivedMetadata?.derived == null || exec?.dependencyRuntime == null) return state;
+	const traceEntry = exec.trace?.get(exec.path);
+	if (traceEntry?.rawInput == null) return traceEntry?.preliminaryResult ?? state;
+	if (traceEntry.preliminaryResult != null) {
+		const resolution = exec.dependencyRuntime.resolveDependencies({
+			dependencyIds: derivedMetadata.derived.dependencyIds,
+			defaultValues: traceEntry.defaultDependencyValues
+		});
+		if (resolution.kind === "resolved" && resolution.usedDefaults.length > 0 && resolution.usedDefaults.every((used) => used)) return traceEntry.preliminaryResult;
+	}
+	const replayed = require_dependency_runtime.replayDerivedParser({
+		path: exec.path,
+		parser: { dependencyMetadata: { derived: derivedMetadata.derived } },
+		state,
+		defaultDependencyValues: traceEntry.defaultDependencyValues
+	}, traceEntry.rawInput, exec.dependencyRuntime);
+	return replayed ?? traceEntry.preliminaryResult ?? state;
+}
+async function resolveDerivedCompletionAsync(derivedMetadata, state, exec) {
+	if (derivedMetadata?.derived == null || exec?.dependencyRuntime == null) return state;
+	const traceEntry = exec.trace?.get(exec.path);
+	if (traceEntry?.rawInput == null) return traceEntry?.preliminaryResult ?? state;
+	if (traceEntry.preliminaryResult != null) {
+		const resolution = exec.dependencyRuntime.resolveDependencies({
+			dependencyIds: derivedMetadata.derived.dependencyIds,
+			defaultValues: traceEntry.defaultDependencyValues
+		});
+		if (resolution.kind === "resolved" && resolution.usedDefaults.length > 0 && resolution.usedDefaults.every((used) => used)) return traceEntry.preliminaryResult;
+	}
+	const replayed = await require_dependency_runtime.replayDerivedParserAsync({
+		path: exec.path,
+		parser: { dependencyMetadata: { derived: derivedMetadata.derived } },
+		state,
+		defaultDependencyValues: traceEntry.defaultDependencyValues
+	}, traceEntry.rawInput, exec.dependencyRuntime);
+	return replayed ?? traceEntry.preliminaryResult ?? state;
+}
 /**
 * Creates a parser that always succeeds without consuming any input and
 * produces a constant value of the type {@link T}.
 * @template T The type of the constant value produced by the parser.
 */
 function constant(value) {
-	return {
+	const result = {
 		$valueType: [],
 		$stateType: [],
-		$mode: "sync",
+		mode: "sync",
 		priority: 0,
 		usage: [],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: value,
 		parse(context) {
 			return {
@@ -45,7 +124,7 @@ function constant(value) {
 				consumed: []
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			return {
 				success: true,
 				value: state
@@ -58,6 +137,13 @@ function constant(value) {
 			return { fragments: [] };
 		}
 	};
+	Object.defineProperty(result, "placeholder", {
+		value,
+		configurable: true,
+		enumerable: false,
+		writable: false
+	});
+	return result;
 }
 /**
 * Creates a parser that always fails without consuming any input.
@@ -82,9 +168,11 @@ function fail() {
 	return {
 		$valueType: [],
 		$stateType: [],
-		$mode: "sync",
+		mode: "sync",
 		priority: 0,
 		usage: [],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: void 0,
 		parse(_context) {
 			return {
@@ -93,7 +181,7 @@ function fail() {
 				error: require_message.message`No value provided.`
 			};
 		},
-		complete(_state) {
+		complete(_state, _exec) {
 			return {
 				success: false,
 				error: require_message.message`No value provided.`
@@ -112,12 +200,13 @@ function fail() {
 * if the parser is a derived parser and dependency values are available.
 * @internal
 */
-function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry) {
+function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry, exec) {
 	if (!valueParser.suggest) return;
 	if (require_dependency.isDerivedValueParser(valueParser) && require_dependency.suggestWithDependency in valueParser) {
 		const derived = valueParser;
 		const suggestWithDep = derived[require_dependency.suggestWithDependency];
 		if (suggestWithDep && dependencyRegistry) {
+			const dependencyRuntime = exec?.dependencyRuntime;
 			const depIds = require_dependency.getDependencyIds(derived);
 			const defaultsFn = require_dependency.getDefaultValuesFunction(derived);
 			const defaults = defaultsFn?.();
@@ -128,7 +217,8 @@ function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry)
 				if (dependencyRegistry.has(depId)) {
 					dependencyValues.push(dependencyRegistry.get(depId));
 					hasAnyValue = true;
-				} else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
+				} else if (dependencyRuntime?.isSourceFailed(depId)) return;
+				else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
 				else {
 					yield* valueParser.suggest(prefix);
 					return;
@@ -155,7 +245,7 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 		const valuePart = prefix.slice(equalsIndex + 1);
 		if (optionNames$1.includes(optionPart)) {
 			if (valueParser && valueParser.suggest) {
-				const valueSuggestions = getSuggestionsWithDependency(valueParser, valuePart, context.dependencyRegistry);
+				const valueSuggestions = getSuggestionsWithDependency(valueParser, valuePart, context.dependencyRegistry, context.exec);
 				for (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
 					kind: "literal",
 					text: `${optionPart}=${suggestion.text}`,
@@ -184,8 +274,8 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 			if (context.buffer.length > 0) {
 				const lastToken = context.buffer[context.buffer.length - 1];
 				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
-			} else if (context.state === void 0 && context.buffer.length === 0) shouldSuggestValues = true;
-			if (shouldSuggestValues) yield* getSuggestionsWithDependency(valueParser, prefix, context.dependencyRegistry);
+			} else if (require_annotation_state.isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			if (shouldSuggestValues) yield* getSuggestionsWithDependency(valueParser, prefix, context.dependencyRegistry, context.exec);
 		}
 	}
 }
@@ -194,12 +284,13 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 * if the parser is a derived parser and dependency values are available.
 * @internal
 */
-async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependencyRegistry) {
+async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependencyRegistry, exec) {
 	if (!valueParser.suggest) return;
 	if (require_dependency.isDerivedValueParser(valueParser) && require_dependency.suggestWithDependency in valueParser) {
 		const derived = valueParser;
 		const suggestWithDep = derived[require_dependency.suggestWithDependency];
 		if (suggestWithDep && dependencyRegistry) {
+			const dependencyRuntime = exec?.dependencyRuntime;
 			const depIds = require_dependency.getDependencyIds(derived);
 			const defaultsFn = require_dependency.getDefaultValuesFunction(derived);
 			const defaults = defaultsFn?.();
@@ -210,7 +301,8 @@ async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependenc
 				if (dependencyRegistry.has(depId)) {
 					dependencyValues.push(dependencyRegistry.get(depId));
 					hasAnyValue = true;
-				} else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
+				} else if (dependencyRuntime?.isSourceFailed(depId)) return;
+				else if (defaults && i < defaults.length) dependencyValues.push(defaults[i]);
 				else {
 					for await (const suggestion of valueParser.suggest(prefix)) yield suggestion;
 					return;
@@ -237,7 +329,7 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 		const valuePart = prefix.slice(equalsIndex + 1);
 		if (optionNames$1.includes(optionPart)) {
 			if (valueParser && valueParser.suggest) {
-				const valueSuggestions = getSuggestionsWithDependencyAsync(valueParser, valuePart, context.dependencyRegistry);
+				const valueSuggestions = getSuggestionsWithDependencyAsync(valueParser, valuePart, context.dependencyRegistry, context.exec);
 				for await (const suggestion of valueSuggestions) if (suggestion.kind === "literal") yield {
 					kind: "literal",
 					text: `${optionPart}=${suggestion.text}`,
@@ -266,8 +358,8 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 			if (context.buffer.length > 0) {
 				const lastToken = context.buffer[context.buffer.length - 1];
 				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
-			} else if (context.state === void 0 && context.buffer.length === 0) shouldSuggestValues = true;
-			if (shouldSuggestValues) for await (const suggestion of getSuggestionsWithDependencyAsync(valueParser, prefix, context.dependencyRegistry)) yield suggestion;
+			} else if (require_annotation_state.isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			if (shouldSuggestValues) for await (const suggestion of getSuggestionsWithDependencyAsync(valueParser, prefix, context.dependencyRegistry, context.exec)) yield suggestion;
 		}
 	}
 }
@@ -275,17 +367,17 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 * Internal sync helper for argument suggest functionality.
 * @internal
 */
-function* suggestArgumentSync(valueParser, hidden, prefix, dependencyRegistry) {
+function* suggestArgumentSync(valueParser, hidden, prefix, dependencyRegistry, exec) {
 	if (hidden) return;
-	if (valueParser.suggest) yield* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry);
+	if (valueParser.suggest) yield* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry, exec);
 }
 /**
 * Internal async helper for argument suggest functionality.
 * @internal
 */
-async function* suggestArgumentAsync(valueParser, hidden, prefix, dependencyRegistry) {
+async function* suggestArgumentAsync(valueParser, hidden, prefix, dependencyRegistry, exec) {
 	if (hidden) return;
-	if (valueParser.suggest) yield* getSuggestionsWithDependencyAsync(valueParser, prefix, dependencyRegistry);
+	if (valueParser.suggest) yield* getSuggestionsWithDependencyAsync(valueParser, prefix, dependencyRegistry, exec);
 }
 function option(...args) {
 	const lastArg = args.at(-1);
@@ -309,10 +401,14 @@ function option(...args) {
 		optionNames$1 = args;
 		valueParser = void 0;
 	}
-	const mode = valueParser?.$mode ?? "sync";
+	require_validate.validateOptionNames(optionNames$1, "Option");
+	const mode = valueParser?.mode ?? "sync";
 	const isAsync = mode === "async";
+	const syncValueParser = valueParser;
+	const dependencyMetadata = valueParser != null ? require_dependency_metadata.extractDependencyMetadata(valueParser) : void 0;
+	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : require_message.message`${require_message.optionNames(optionNames$1)}: ${error}`;
 	const result = {
-		$mode: mode,
+		mode,
 		$valueType: [],
 		$stateType: [],
 		priority: 10,
@@ -329,13 +425,12 @@ function option(...args) {
 			metavar: valueParser.metavar,
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: new Set(optionNames$1),
+		acceptingAnyToken: false,
 		initialState: valueParser == null ? {
 			success: true,
 			value: false
-		} : require_dependency.isDependencySource(valueParser) ? require_dependency.createPendingDependencySourceState(valueParser[require_dependency.dependencyId]) : {
-			success: false,
-			error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : require_message.message`Missing option ${require_message.optionNames(optionNames$1)}.`
-		},
+		} : void 0,
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -378,28 +473,34 @@ function option(...args) {
 				if (context.buffer.length < 2) return {
 					success: false,
 					consumed: 1,
-					error: require_message.message`Option ${require_message.optionName(context.buffer[0])} requires a value, but got no value.`
+					error: options.errors?.endOfInput ?? require_message.message`${require_message.optionName(context.buffer[0])} requires ${require_message.metavar(valueParser.metavar)}.`
 				};
 				const rawInput = context.buffer[1];
-				const parseResultOrPromise = valueParser.parse(rawInput);
-				if (isAsync) return parseResultOrPromise.then((parseResult) => ({
-					success: true,
-					next: {
-						...context,
-						state: createOptionParseState(rawInput, valueParser, parseResult),
-						buffer: context.buffer.slice(2)
-					},
-					consumed: context.buffer.slice(0, 2)
-				}));
-				return {
-					success: true,
-					next: {
-						...context,
-						state: createOptionParseState(rawInput, valueParser, parseResultOrPromise),
-						buffer: context.buffer.slice(2)
-					},
-					consumed: context.buffer.slice(0, 2)
-				};
+				return require_mode_dispatch.dispatchByMode(mode, () => {
+					const parseResult = syncValueParser.parse(rawInput);
+					const next = recordTrace(context, buildTraceEntry("option-value", rawInput, context.buffer.slice(0, 2), syncValueParser, parseResult, optionNames$1));
+					return {
+						success: true,
+						next: {
+							...next,
+							state: createOptionParseState(parseResult),
+							buffer: context.buffer.slice(2)
+						},
+						consumed: context.buffer.slice(0, 2)
+					};
+				}, async () => {
+					const parseResult = await valueParser.parse(rawInput);
+					const next = recordTrace(context, buildTraceEntry("option-value", rawInput, context.buffer.slice(0, 2), valueParser, parseResult, optionNames$1));
+					return {
+						success: true,
+						next: {
+							...next,
+							state: createOptionParseState(parseResult),
+							buffer: context.buffer.slice(2)
+						},
+						consumed: context.buffer.slice(0, 2)
+					};
+				});
 			}
 			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/") || name.startsWith("-") && name.length > 2).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
 			for (const prefix of prefixes) {
@@ -418,25 +519,31 @@ function option(...args) {
 					consumed: 1,
 					error: options.errors?.unexpectedValue ? typeof options.errors.unexpectedValue === "function" ? options.errors.unexpectedValue(rawInput) : options.errors.unexpectedValue : require_message.message`Option ${require_message.optionName(prefix)} is a Boolean flag, but got a value: ${rawInput}.`
 				};
-				const parseResultOrPromise = valueParser.parse(rawInput);
-				if (isAsync) return parseResultOrPromise.then((parseResult) => ({
-					success: true,
-					next: {
-						...context,
-						state: createOptionParseState(rawInput, valueParser, parseResult),
-						buffer: context.buffer.slice(1)
-					},
-					consumed: context.buffer.slice(0, 1)
-				}));
-				return {
-					success: true,
-					next: {
-						...context,
-						state: createOptionParseState(rawInput, valueParser, parseResultOrPromise),
-						buffer: context.buffer.slice(1)
-					},
-					consumed: context.buffer.slice(0, 1)
-				};
+				return require_mode_dispatch.dispatchByMode(mode, () => {
+					const parseResult = syncValueParser.parse(rawInput);
+					const next = recordTrace(context, buildTraceEntry("option-value", rawInput, context.buffer.slice(0, 1), syncValueParser, parseResult, optionNames$1));
+					return {
+						success: true,
+						next: {
+							...next,
+							state: createOptionParseState(parseResult),
+							buffer: context.buffer.slice(1)
+						},
+						consumed: context.buffer.slice(0, 1)
+					};
+				}, async () => {
+					const parseResult = await valueParser.parse(rawInput);
+					const next = recordTrace(context, buildTraceEntry("option-value", rawInput, context.buffer.slice(0, 1), valueParser, parseResult, optionNames$1));
+					return {
+						success: true,
+						next: {
+							...next,
+							state: createOptionParseState(parseResult),
+							buffer: context.buffer.slice(1)
+						},
+						consumed: context.buffer.slice(0, 1)
+					};
+				});
 			}
 			if (valueParser == null) {
 				const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/));
@@ -480,39 +587,32 @@ function option(...args) {
 				error: require_suggestion.createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
 			};
 		},
-		complete(state) {
-			if (state == null) return valueParser == null ? {
+		complete(state, exec) {
+			const missing = valueParser == null ? {
 				success: true,
 				value: false
 			} : {
 				success: false,
 				error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : require_message.message`Missing option ${require_message.optionNames(optionNames$1)}.`
 			};
-			if (require_dependency.isPendingDependencySourceState(state)) return {
-				success: false,
-				error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : require_message.message`Missing option ${require_message.optionNames(optionNames$1)}.`
-			};
-			if (require_dependency.isDeferredParseState(state)) {
-				const preliminaryResult = state.preliminaryResult;
-				if (preliminaryResult.success) return preliminaryResult;
-				return {
+			const completeSync = () => {
+				if (state == null) return missing;
+				const resolvedState = valueParser != null && dependencyMetadata?.derived != null ? resolveDerivedCompletionSync(dependencyMetadata, state, exec) : state;
+				return resolvedState.success ? resolvedState : {
 					success: false,
-					error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(preliminaryResult.error) : options.errors.invalidValue : require_message.message`${require_message.optionNames(optionNames$1)}: ${preliminaryResult.error}`
+					error: formatInvalidValueError(resolvedState.error)
 				};
-			}
-			if (require_dependency.isDependencySourceState(state)) {
-				const result$1 = state.result;
-				if (result$1.success) return result$1;
-				return {
+			};
+			const completeAsync = async () => {
+				if (state == null) return missing;
+				if (valueParser == null || dependencyMetadata?.derived == null) return completeSync();
+				const resolved = await resolveDerivedCompletionAsync(dependencyMetadata, state, exec);
+				return resolved.success ? resolved : {
 					success: false,
-					error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(result$1.error) : options.errors.invalidValue : require_message.message`${require_message.optionNames(optionNames$1)}: ${result$1.error}`
+					error: formatInvalidValueError(resolved.error)
 				};
-			}
-			if (state.success) return state;
-			return {
-				success: false,
-				error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(state.error) : options.errors.invalidValue : require_message.message`${require_message.optionNames(optionNames$1)}: ${state.error}`
 			};
+			return require_mode_dispatch.dispatchByMode(mode, completeSync, completeAsync);
 		},
 		suggest(context, prefix) {
 			if (isAsync) return suggestOptionAsync(optionNames$1, valueParser, require_usage.isSuggestionHidden(options.hidden), context, prefix);
@@ -523,7 +623,10 @@ function option(...args) {
 				fragments: [],
 				description: options.description
 			};
-			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), { type: "unit" }) : void 0;
+			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
+				fallback: "",
+				type: "unit"
+			}) : void 0;
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -544,6 +647,86 @@ function option(...args) {
 			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
 		}
 	};
+	if (valueParser != null && typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	if (valueParser == null) Object.defineProperty(result, "validateValue", {
+		value(v) {
+			if (typeof v !== "boolean") {
+				const actualType = v === null ? "null" : typeof v;
+				return require_mode_dispatch.wrapForMode(mode, {
+					success: false,
+					error: formatInvalidValueError(require_message.message`Expected a boolean value, but received ${actualType}.`)
+				});
+			}
+			return require_mode_dispatch.wrapForMode(mode, {
+				success: true,
+				value: v
+			});
+		},
+		configurable: true,
+		enumerable: false
+	});
+	else if (!require_dependency.isDerivedValueParser(valueParser)) {
+		const vp = valueParser;
+		const wrapParseResult = (parsed) => parsed.success ? parsed : {
+			success: false,
+			error: formatInvalidValueError(parsed.error)
+		};
+		Object.defineProperty(result, "validateValue", {
+			value(v) {
+				let stringified;
+				try {
+					stringified = vp.format(v);
+				} catch {
+					return require_mode_dispatch.wrapForMode(mode, {
+						success: true,
+						value: v
+					});
+				}
+				if (typeof stringified !== "string") return require_mode_dispatch.wrapForMode(mode, {
+					success: true,
+					value: v
+				});
+				return require_mode_dispatch.dispatchByMode(mode, () => wrapParseResult(vp.parse(stringified)), async () => wrapParseResult(await vp.parse(stringified)));
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	if (valueParser != null) Object.defineProperty(result, "placeholder", {
+		get() {
+			try {
+				return valueParser.placeholder;
+			} catch {
+				return void 0;
+			}
+		},
+		configurable: true,
+		enumerable: false
+	});
+	else Object.defineProperty(result, "placeholder", {
+		value: false,
+		configurable: true,
+		enumerable: false,
+		writable: false
+	});
+	if (dependencyMetadata != null) Object.defineProperty(result, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**
@@ -585,16 +768,19 @@ function flag(...args) {
 		options = lastArg;
 		optionNames$1 = args.slice(0, -1);
 	} else optionNames$1 = args;
-	return {
+	require_validate.validateOptionNames(optionNames$1, "Flag");
+	const result = {
 		$valueType: [],
 		$stateType: [],
-		$mode: "sync",
+		mode: "sync",
 		priority: 10,
 		usage: [{
 			type: "option",
 			names: optionNames$1,
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: new Set(optionNames$1),
+		acceptingAnyToken: false,
 		initialState: void 0,
 		parse(context) {
 			if (context.optionsTerminated) return {
@@ -685,7 +871,7 @@ function flag(...args) {
 				error: require_suggestion.createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			if (state == null) return {
 				success: false,
 				error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : require_message.message`Required flag ${require_message.optionNames(optionNames$1)} is missing.`
@@ -735,6 +921,13 @@ function flag(...args) {
 			return `flag(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
 		}
 	};
+	Object.defineProperty(result, "placeholder", {
+		value: true,
+		configurable: true,
+		enumerable: false,
+		writable: false
+	});
+	return result;
 }
 /**
 * Creates a parser that expects a single argument value.
@@ -750,7 +943,10 @@ function flag(...args) {
 *          the parsed value of type {@link T}.
 */
 function argument(valueParser, options = {}) {
-	const isAsync = valueParser.$mode === "async";
+	const isAsync = valueParser.mode === "async";
+	const syncValueParser = valueParser;
+	const dependencyMetadata = require_dependency_metadata.extractDependencyMetadata(valueParser);
+	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : require_message.message`${require_message.metavar(valueParser.metavar)}: ${error}`;
 	const optionPattern = /^--?[a-z0-9-]+$/i;
 	const term = {
 		type: "argument",
@@ -758,13 +954,16 @@ function argument(valueParser, options = {}) {
 		...options.hidden != null && { hidden: options.hidden }
 	};
 	const result = {
-		$mode: valueParser.$mode,
+		mode: valueParser.mode,
 		$valueType: [],
 		$stateType: [],
 		priority: 5,
 		usage: [term],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: true,
 		initialState: void 0,
 		parse(context) {
+			const localState = require_annotation_state.normalizeInjectedAnnotationState(context.state);
 			if (context.buffer.length < 1) return {
 				success: false,
 				consumed: 0,
@@ -787,72 +986,78 @@ function argument(valueParser, options = {}) {
 				consumed: i,
 				error: require_message.message`Expected an argument, but got end of input.`
 			};
-			if (context.state != null) return {
+			if (localState != null) return {
 				success: false,
 				consumed: i,
 				error: options.errors?.multiple ? typeof options.errors.multiple === "function" ? options.errors.multiple(valueParser.metavar) : options.errors.multiple : require_message.message`The argument ${require_message.metavar(valueParser.metavar)} cannot be used multiple times.`
 			};
 			const rawInput = context.buffer[i];
-			const parseResultOrPromise = valueParser.parse(rawInput);
-			if (isAsync) return parseResultOrPromise.then((parseResult) => ({
-				success: true,
-				next: {
-					...context,
-					buffer: context.buffer.slice(i + 1),
-					state: createOptionParseState(rawInput, valueParser, parseResult),
-					optionsTerminated
-				},
-				consumed: context.buffer.slice(0, i + 1)
-			}));
-			return {
-				success: true,
-				next: {
-					...context,
-					buffer: context.buffer.slice(i + 1),
-					state: createOptionParseState(rawInput, valueParser, parseResultOrPromise),
-					optionsTerminated
-				},
-				consumed: context.buffer.slice(0, i + 1)
-			};
+			return require_mode_dispatch.dispatchByMode(valueParser.mode, () => {
+				const parseResult = syncValueParser.parse(rawInput);
+				const next = recordTrace(context, buildTraceEntry("argument-value", rawInput, context.buffer.slice(0, i + 1), syncValueParser, parseResult));
+				return {
+					success: true,
+					next: {
+						...next,
+						buffer: context.buffer.slice(i + 1),
+						state: createOptionParseState(parseResult),
+						optionsTerminated
+					},
+					consumed: context.buffer.slice(0, i + 1)
+				};
+			}, async () => {
+				const parseResult = await valueParser.parse(rawInput);
+				const next = recordTrace(context, buildTraceEntry("argument-value", rawInput, context.buffer.slice(0, i + 1), valueParser, parseResult));
+				return {
+					success: true,
+					next: {
+						...next,
+						buffer: context.buffer.slice(i + 1),
+						state: createOptionParseState(parseResult),
+						optionsTerminated
+					},
+					consumed: context.buffer.slice(0, i + 1)
+				};
+			});
 		},
-		complete(state) {
-			if (state == null) return {
+		complete(state, exec) {
+			const missing = {
 				success: false,
 				error: options.errors?.endOfInput ?? require_message.message`Expected a ${require_message.metavar(valueParser.metavar)}, but too few arguments.`
 			};
-			if (require_dependency.isDeferredParseState(state)) {
-				const preliminaryResult = state.preliminaryResult;
-				if (preliminaryResult.success) return preliminaryResult;
-				return {
+			const completeSync = () => {
+				if (state == null) return missing;
+				const resolvedState = dependencyMetadata?.derived != null ? resolveDerivedCompletionSync(dependencyMetadata, state, exec) : state;
+				return resolvedState.success ? resolvedState : {
 					success: false,
-					error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(preliminaryResult.error) : options.errors.invalidValue : require_message.message`${require_message.metavar(valueParser.metavar)}: ${preliminaryResult.error}`
+					error: formatInvalidValueError(resolvedState.error)
 				};
-			}
-			if (require_dependency.isDependencySourceState(state)) {
-				const result$1 = state.result;
-				if (result$1.success) return result$1;
-				return {
+			};
+			const completeAsync = async () => {
+				if (state == null) return missing;
+				if (dependencyMetadata?.derived == null) return completeSync();
+				const resolved = await resolveDerivedCompletionAsync(dependencyMetadata, state, exec);
+				return resolved.success ? resolved : {
 					success: false,
-					error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(result$1.error) : options.errors.invalidValue : require_message.message`${require_message.metavar(valueParser.metavar)}: ${result$1.error}`
+					error: formatInvalidValueError(resolved.error)
 				};
-			}
-			if (state.success) return state;
-			return {
-				success: false,
-				error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(state.error) : options.errors.invalidValue : require_message.message`${require_message.metavar(valueParser.metavar)}: ${state.error}`
 			};
+			return require_mode_dispatch.dispatchByMode(valueParser.mode, completeSync, completeAsync);
 		},
 		suggest(context, prefix) {
-			if (context.state != null) return require_mode_dispatch.dispatchIterableByMode(valueParser.$mode, function* () {}, async function* () {});
-			if (isAsync) return suggestArgumentAsync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry);
-			return suggestArgumentSync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry);
+			if (require_annotation_state.normalizeInjectedAnnotationState(context.state) != null) return require_mode_dispatch.dispatchIterableByMode(valueParser.mode, function* () {}, async function* () {});
+			if (isAsync) return suggestArgumentAsync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
+			return suggestArgumentSync(valueParser, require_usage.isSuggestionHidden(options.hidden), prefix, context.dependencyRegistry, context.exec);
 		},
 		getDocFragments(_state, defaultValue) {
 			if (require_usage.isDocHidden(options.hidden)) return {
 				fragments: [],
 				description: options.description
 			};
-			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), { type: "unit" }) : void 0;
+			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), {
+				fallback: "",
+				type: "unit"
+			}) : void 0;
 			const fragments = [{
 				type: "entry",
 				term,
@@ -869,44 +1074,111 @@ function argument(valueParser, options = {}) {
 			return `argument()`;
 		}
 	};
+	if (typeof valueParser.normalize === "function") {
+		const normalize = valueParser.normalize.bind(valueParser);
+		Object.defineProperty(result, "normalizeValue", {
+			value(v) {
+				try {
+					return normalize(v);
+				} catch {
+					return v;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	if (!require_dependency.isDerivedValueParser(valueParser)) {
+		const vp = valueParser;
+		const vpMode = valueParser.mode;
+		const wrapParseResult = (parsed) => parsed.success ? parsed : {
+			success: false,
+			error: formatInvalidValueError(parsed.error)
+		};
+		Object.defineProperty(result, "validateValue", {
+			value(v) {
+				let stringified;
+				try {
+					stringified = vp.format(v);
+				} catch {
+					return require_mode_dispatch.wrapForMode(vpMode, {
+						success: true,
+						value: v
+					});
+				}
+				if (typeof stringified !== "string") return require_mode_dispatch.wrapForMode(vpMode, {
+					success: true,
+					value: v
+				});
+				return require_mode_dispatch.dispatchByMode(vpMode, () => wrapParseResult(syncValueParser.parse(stringified)), async () => wrapParseResult(await vp.parse(stringified)));
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
+	Object.defineProperty(result, "placeholder", {
+		get() {
+			try {
+				return valueParser.placeholder;
+			} catch {
+				return void 0;
+			}
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (dependencyMetadata != null) Object.defineProperty(result, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
+function normalizeCommandState(state) {
+	return require_annotation_state.normalizeInjectedAnnotationState(state);
+}
+function getCommandParseChildState(commandState, childState, parser) {
+	return require_annotation_state.getWrappedChildParseState(commandState, childState, parser);
+}
+function getCommandChildState(commandState, childState, parser) {
+	return require_annotation_state.getWrappedChildState(commandState, childState, parser);
+}
+function createCommandState(sourceState, state) {
+	return require_annotations.annotateFreshArray(sourceState, state);
+}
+function appendCommandPath(exec, name) {
+	if (exec == null) return void 0;
+	return {
+		...exec,
+		commandPath: [...exec.commandPath ?? [], name]
+	};
+}
 function* suggestCommandSync(context, prefix, name, parser, options) {
 	if (require_usage.isSuggestionHidden(options.hidden)) return;
-	if (context.state === void 0) {
+	const state = normalizeCommandState(context.state);
+	if (state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
 			text: name,
 			...options.description && { description: options.description }
 		};
-	} else if (context.state[0] === "matched") yield* parser.suggest({
-		...context,
-		state: parser.initialState
-	}, prefix);
-	else if (context.state[0] === "parsing") yield* parser.suggest({
-		...context,
-		state: context.state[1]
-	}, prefix);
+	} else if (state[0] === "matched") yield* parser.suggest(require_execution_context.withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
+	else if (state[0] === "parsing") yield* parser.suggest(require_execution_context.withChildContext(context, name, getCommandChildState(context.state, state[1], parser), parser.usage), prefix);
 }
 async function* suggestCommandAsync(context, prefix, name, parser, options) {
 	if (require_usage.isSuggestionHidden(options.hidden)) return;
-	if (context.state === void 0) {
+	const state = normalizeCommandState(context.state);
+	if (state === void 0) {
 		if (name.startsWith(prefix)) yield {
 			kind: "literal",
 			text: name,
 			...options.description && { description: options.description }
 		};
-	} else if (context.state[0] === "matched") {
-		const suggestions = parser.suggest({
-			...context,
-			state: parser.initialState
-		}, prefix);
+	} else if (state[0] === "matched") {
+		const suggestions = parser.suggest(require_execution_context.withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
 		for await (const s of suggestions) yield s;
-	} else if (context.state[0] === "parsing") {
-		const suggestions = parser.suggest({
-			...context,
-			state: context.state[1]
-		}, prefix);
+	} else if (state[0] === "parsing") {
+		const suggestions = parser.suggest(require_execution_context.withChildContext(context, name, getCommandChildState(context.state, state[1], parser), parser.usage), prefix);
 		for await (const s of suggestions) yield s;
 	}
 }
@@ -923,11 +1195,17 @@ async function* suggestCommandAsync(context, prefix, name, parser, options) {
 *                a description for documentation.
 * @returns A {@link Parser} that matches the command name and delegates
 *          to the inner parser for the remaining arguments.
+* @throws {TypeError} If `name` is empty, whitespace-only, contains
+*         embedded whitespace, or contains control characters.
 */
 function command(name, parser, options = {}) {
-	const isAsync = parser.$mode === "async";
+	require_validate.validateCommandNames([name], "Command");
+	const isAsync = parser.mode === "async";
+	const syncInnerParser = parser;
+	const asyncInnerParser = parser;
 	const result = {
-		$mode: parser.$mode,
+		[Symbol.for("@optique/core/commandParser")]: true,
+		mode: parser.mode,
 		$valueType: [],
 		$stateType: [],
 		priority: 15,
@@ -937,9 +1215,23 @@ function command(name, parser, options = {}) {
 			...options.usageLine != null && { usageLine: options.usageLine },
 			...options.hidden != null && { hidden: options.hidden }
 		}, ...parser.usage],
+		leadingNames: new Set([name]),
+		acceptingAnyToken: false,
 		initialState: void 0,
+		getSuggestRuntimeNodes(state, path) {
+			const normalizedState = normalizeCommandState(state);
+			if (normalizedState === void 0) return [];
+			const childState = normalizedState[0] === "matched" ? getCommandChildState(state, parser.initialState, parser) : getCommandChildState(state, normalizedState[1], parser);
+			const childPath = [...path, name];
+			return parser.getSuggestRuntimeNodes?.(childState, childPath) ?? (parser.dependencyMetadata?.source != null ? [{
+				path: childPath,
+				parser,
+				state: childState
+			}] : []);
+		},
 		parse(context) {
-			if (context.state === void 0) {
+			const state = normalizeCommandState(context.state);
+			if (state === void 0) {
 				if (context.buffer.length < 1 || context.buffer[0] !== name) {
 					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
 					const leadingCmds = require_usage_internals.extractLeadingCommandNames(context.usage);
@@ -974,29 +1266,32 @@ function command(name, parser, options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: ["matched", name]
+						state: createCommandState(context.state, ["matched", name]),
+						...context.exec != null ? { exec: appendCommandPath(context.exec, name) } : {}
 					},
 					consumed: context.buffer.slice(0, 1)
 				};
-			} else if (context.state[0] === "matched" || context.state[0] === "parsing") {
-				const innerState = context.state[0] === "matched" ? parser.initialState : context.state[1];
-				const parseResultOrPromise = parser.parse({
-					...context,
-					state: innerState
-				});
+			} else if (state[0] === "matched" || state[0] === "parsing") {
+				const innerState = state[0] === "matched" ? getCommandParseChildState(context.state, parser.initialState, parser) : getCommandParseChildState(context.state, state[1], parser);
 				const wrapState = (parseResult) => {
-					if (parseResult.success) return {
-						success: true,
-						next: {
-							...parseResult.next,
-							state: ["parsing", parseResult.next.state]
-						},
-						consumed: parseResult.consumed
-					};
+					if (parseResult.success) {
+						const mergedExec = require_execution_context.mergeChildExec(context.exec, parseResult.next.exec);
+						return {
+							success: true,
+							next: {
+								...parseResult.next,
+								state: createCommandState(context.state, ["parsing", parseResult.next.state]),
+								...mergedExec != null ? {
+									exec: mergedExec,
+									dependencyRegistry: mergedExec.dependencyRegistry
+								} : {}
+							},
+							consumed: parseResult.consumed
+						};
+					}
 					return parseResult;
 				};
-				if (isAsync) return parseResultOrPromise.then(wrapState);
-				return wrapState(parseResultOrPromise);
+				return require_mode_dispatch.dispatchByMode(parser.mode, () => wrapState(syncInnerParser.parse(require_execution_context.withChildContext(context, name, innerState, parser.usage))), async () => wrapState(await parser.parse(require_execution_context.withChildContext(context, name, innerState, parser.usage))));
 			}
 			return {
 				success: false,
@@ -1004,37 +1299,79 @@ function command(name, parser, options = {}) {
 				error: options.errors?.invalidState ?? require_message.message`Invalid command state.`
 			};
 		},
-		complete(state) {
-			if (typeof state === "undefined") return {
+		complete(state, exec) {
+			const normalizedState = normalizeCommandState(state);
+			if (typeof normalizedState === "undefined") return {
 				success: false,
 				error: options.errors?.notFound ?? require_message.message`Command ${require_message.optionName(name)} was not matched.`
 			};
-			else if (state[0] === "matched") {
-				const parseResultOrPromise = parser.parse({
+			else if (normalizedState[0] === "matched") {
+				const childExec = require_execution_context.withChildExecPath(exec, name);
+				const childContext = {
 					buffer: [],
 					optionsTerminated: false,
-					usage: [],
-					state: parser.initialState
-				});
-				if (isAsync) return parseResultOrPromise.then((parseResult$1) => {
-					if (parseResult$1.success) return parser.complete(parseResult$1.next.state);
-					return parser.complete(parser.initialState);
+					usage: parser.usage,
+					state: getCommandParseChildState(state, parser.initialState, parser),
+					...childExec != null ? {
+						exec: childExec,
+						trace: childExec.trace,
+						dependencyRegistry: childExec.dependencyRegistry
+					} : {}
+				};
+				return require_mode_dispatch.dispatchByMode(parser.mode, () => {
+					const parseResult = syncInnerParser.parse(childContext);
+					const nextExec = parseResult.success ? require_execution_context.mergeChildExec(childExec, parseResult.next.exec) : childExec;
+					return syncInnerParser.complete(parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, syncInnerParser.initialState, parser), nextExec);
+				}, async () => {
+					const parseResult = await asyncInnerParser.parse(childContext);
+					const nextExec = parseResult.success ? require_execution_context.mergeChildExec(childExec, parseResult.next.exec) : childExec;
+					return asyncInnerParser.complete(parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, parser.initialState, parser), nextExec);
 				});
-				const parseResult = parseResultOrPromise;
-				if (parseResult.success) return parser.complete(parseResult.next.state);
-				return parser.complete(parser.initialState);
-			} else if (state[0] === "parsing") return parser.complete(state[1]);
+			} else if (normalizedState[0] === "parsing") {
+				const childExec = require_execution_context.withChildExecPath(exec, name);
+				return require_mode_dispatch.dispatchByMode(parser.mode, () => syncInnerParser.complete(getCommandChildState(state, normalizedState[1], parser), childExec), async () => await asyncInnerParser.complete(getCommandChildState(state, normalizedState[1], parser), childExec));
+			}
 			return {
 				success: false,
 				error: options.errors?.invalidState ?? require_message.message`Invalid command state during completion.`
 			};
 		},
+		[require_phase2_seed.extractPhase2SeedKey](state, exec) {
+			const normalizedState = normalizeCommandState(state);
+			if (typeof normalizedState === "undefined") return require_mode_dispatch.wrapForMode(parser.mode, null);
+			if (normalizedState[0] === "matched") {
+				const childExec = require_execution_context.withChildExecPath(exec, name);
+				const childContext = {
+					buffer: [],
+					optionsTerminated: false,
+					usage: parser.usage,
+					state: getCommandParseChildState(state, parser.initialState, parser),
+					...childExec != null ? {
+						exec: childExec,
+						trace: childExec.trace,
+						dependencyRegistry: childExec.dependencyRegistry
+					} : {}
+				};
+				return require_mode_dispatch.dispatchByMode(parser.mode, () => {
+					const parseResult = syncInnerParser.parse(childContext);
+					const nextExec = parseResult.success ? require_execution_context.mergeChildExec(childExec, parseResult.next.exec) : childExec;
+					return require_phase2_seed.completeOrExtractPhase2Seed(syncInnerParser, parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, syncInnerParser.initialState, parser), nextExec);
+				}, async () => {
+					const parseResult = await asyncInnerParser.parse(childContext);
+					const nextExec = parseResult.success ? require_execution_context.mergeChildExec(childExec, parseResult.next.exec) : childExec;
+					return await require_phase2_seed.completeOrExtractPhase2Seed(asyncInnerParser, parseResult.success ? getCommandChildState(state, parseResult.next.state, parser) : getCommandChildState(state, parser.initialState, parser), nextExec);
+				});
+			}
+			if (normalizedState[0] === "parsing") return require_phase2_seed.completeOrExtractPhase2Seed(parser, getCommandChildState(state, normalizedState[1], parser), require_execution_context.withChildExecPath(exec, name));
+			return require_mode_dispatch.wrapForMode(parser.mode, null);
+		},
 		suggest(context, prefix) {
 			if (isAsync) return suggestCommandAsync(context, prefix, name, parser, options);
 			return suggestCommandSync(context, prefix, name, parser, options);
 		},
 		getDocFragments(state, defaultValue) {
-			if (state.kind === "unavailable" || typeof state.state === "undefined") {
+			const commandState = state.kind === "available" ? normalizeCommandState(state.state) : void 0;
+			if (state.kind === "unavailable" || typeof commandState === "undefined") {
 				if (require_usage.isDocHidden(options.hidden)) return {
 					fragments: [],
 					description: options.description
@@ -1051,12 +1388,12 @@ function command(name, parser, options = {}) {
 					}]
 				};
 			}
-			const innerState = state.state[0] === "parsing" ? {
+			const innerState = commandState[0] === "parsing" ? {
 				kind: "available",
-				state: state.state[1]
+				state: getCommandChildState(state.state, commandState[1], parser)
 			} : {
 				kind: "available",
-				state: parser.initialState
+				state: getCommandChildState(state.state, parser.initialState, parser)
 			};
 			const innerFragments = parser.getDocFragments(innerState, defaultValue);
 			return {
@@ -1070,6 +1407,16 @@ function command(name, parser, options = {}) {
 			return `command(${JSON.stringify(name)})`;
 		}
 	};
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(result, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(result, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**
@@ -1125,12 +1472,14 @@ function passThrough(options = {}) {
 	return {
 		$valueType: [],
 		$stateType: [],
-		$mode: "sync",
+		mode: "sync",
 		priority: -10,
 		usage: [{
 			type: "passthrough",
 			...options.hidden != null && { hidden: options.hidden }
 		}],
+		leadingNames: EMPTY_LEADING_NAMES,
+		acceptingAnyToken: false,
 		initialState: [],
 		parse(context) {
 			if (context.buffer.length < 1) return {
@@ -1217,7 +1566,7 @@ function passThrough(options = {}) {
 				error: require_message.message`Unknown passThrough format: ${format}.`
 			};
 		},
-		complete(state) {
+		complete(state, _exec) {
 			if (require_annotations.getAnnotations(state) == null) return {
 				success: true,
 				value: state