@optique/core 1.4.0-dev.2661 → 1.4.0-dev.2664

package/dist/constructs.js

@@ -11,7 +11,7 @@ import { annotationViewTargets, getWrappedChildParseState, getWrappedChildState,
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { collectLeadingCandidates } from "./usage-internals.js";
 import { adoptOptionScope, combinedOptionScope, conditionalOptionScope, forkOptionScope, restoreOptionScope, scopeParser, selectableOptionScope, withOptionScope, withParserOptionScope } from "./short-option.js";
-import { combineOptionMatches, combinePassThroughPriorities, defineOptionMatch, definePassThroughPriority, delegateKnownCompletion, getKnownCompletion, getOptionMatch, getPassThroughFailureHint, getPassThroughPriority, hasPassThroughUsage, matchesOptionToken, retainConsumingFailure, retainConsumingFailureHint, withPassThroughFailure } from "./internal/passthrough.js";
+import { defineReachableChildren, delegateKnownCompletion, getKnownCompletion, getOptionMatch, getPassThroughFailureHint, getPassThroughPriority, hasPassThroughUsage, matchesOptionToken, retainConsumingFailure, retainConsumingFailureHint, withPassThroughFailure, withReturnedConsumingFailure } from "./internal/passthrough.js";
 import { allowDuplicateLeadingCommandNamesKey } from "./internal/command-alias.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
 import { fluent } from "./modifiers.js";
@@ -1028,12 +1028,16 @@ function analyzeNoMatchContext(parsers) {
 * construction. This is a programmer error, not a user error.
 */
 var DuplicateOptionError = class extends Error {
+	/** The option name shared by multiple fields. */
+	optionName;
+	/** The fields declaring the option. */
+	sources;
 	constructor(optionName$1, sources) {
 		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
 		super(`Duplicate option name "${optionName$1}" found in fields: ${sourceNames.join(", ")}. Each option name must be unique within a parser combinator.`);
+		this.name = "DuplicateOptionError";
 		this.optionName = optionName$1;
 		this.sources = sources;
-		this.name = "DuplicateOptionError";
 	}
 };
 /**
@@ -1041,6 +1045,8 @@ var DuplicateOptionError = class extends Error {
 * during parser construction. This is a programmer error, not a user error.
 */
 var DuplicateCommandNameError = class extends TypeError {
+	commandName;
+	sources;
 	constructor(commandName, sources) {
 		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
 		super(`Duplicate command name "${commandName}" found in parsers: ${sourceNames.join(", ")}. Each command name or alias must be unique within active parser alternatives.`);
@@ -1134,6 +1140,16 @@ function generateNoMatchError(context) {
 	else if (hasOptions && hasCommands && hasArguments) return message`No matching option, command, or argument found.`;
 	else return message`No value provided.`;
 }
+/** Potential alternatives; only parsing decides whether replay can switch. */
+function selectExclusiveChildren(parsers, state, activeFirst = false) {
+	const active = normalizeExclusiveState(state);
+	const children = parsers.map((parser, index) => ({
+		parser,
+		index,
+		state: getWrappedChildParseState(state, active?.[0] === index && active[1].success ? active[1].next.state : parser.initialState, parser)
+	}));
+	return activeFirst ? children.sort((a, b) => active?.[0] === a.index ? -1 : active?.[0] === b.index ? 1 : a.index - b.index) : children;
+}
 function normalizeExclusiveState(state) {
 	if (!Array.isArray(state) || state.length !== 2 || typeof state[0] !== "number") return void 0;
 	return state;
@@ -1463,15 +1479,19 @@ function or(...args) {
 	const parseSync = (context) => {
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
-		const orderedParsers = syncParsers.map((p, i) => [p, i]);
-		orderedParsers.sort(([_, a], [__, b]) => activeState?.[0] === a ? -1 : activeState?.[0] === b ? 1 : a - b);
+		const orderedParsers = selectExclusiveChildren(syncParsers, context.state, true);
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
 		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
-		for (const [parser, i] of orderedParsers) {
-			const result = parser.parse(withChildContext$1(forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+		for (const { parser, index: i, state: childState } of orderedParsers) {
+			const childContext = withChildContext$1(forkOptionScope(context), i, childState, parser);
+			const result = parser.parse(childContext);
+			if (result.success && result.consumed.length === 0) {
+				const own = retainConsumingFailureHint(void 0, childContext, result.next);
+				if (own != null && error.consumed < own.failure.consumed) error = own.failure;
+			}
 			if (isOptionsTerminatorOnlyResult(context, result)) {
 				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
 				optionsTerminatorResult ??= result;
@@ -1671,16 +1691,20 @@ function or(...args) {
 	const parseAsync = async (context) => {
 		let error = getInitialError(context);
 		const activeState = normalizeExclusiveState(context.state);
-		const orderedParsers = parsers.map((p, i) => [p, i]);
-		orderedParsers.sort(([_, a], [__, b]) => activeState?.[0] === a ? -1 : activeState?.[0] === b ? 1 : a - b);
+		const orderedParsers = selectExclusiveChildren(parsers, context.state, true);
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
 		let provisionalConsuming = null;
 		let optionsTerminatorResult = null;
 		let provisionalAmbiguous = false;
-		for (const [parser, i] of orderedParsers) {
-			const resultOrPromise = parser.parse(withChildContext$1(forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
+		for (const { parser, index: i, state: childState } of orderedParsers) {
+			const childContext = withChildContext$1(forkOptionScope(context), i, childState, parser);
+			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
+			if (result.success && result.consumed.length === 0) {
+				const own = retainConsumingFailureHint(void 0, childContext, result.next);
+				if (own != null && error.consumed < own.failure.consumed) error = own.failure;
+			}
 			if (isOptionsTerminatorOnlyResult(context, result)) {
 				if (activeState?.[0] === i && activeState[1].success && activeState[1].consumed.length > 0 && result.next.buffer.length < 1) return preserveExclusiveStateAfterOptionsTerminator(context, result);
 				optionsTerminatorResult ??= result;
@@ -1948,14 +1972,7 @@ function or(...args) {
 	if (singleDependencyMetadata != null) singleResult.dependencyMetadata = singleDependencyMetadata;
 	defineExclusiveSchedulingNodes(singleResult, parsers);
 	defineInheritedAnnotationParser(singleResult);
-	defineOptionMatch(singleResult, (state, token) => combineOptionMatches(parsers.map((parser, index) => {
-		const active = normalizeExclusiveState(state);
-		return getOptionMatch(parser, active?.[0] === index && active[1].success ? active[1].next.state : parser.initialState, token);
-	})));
-	definePassThroughPriority(singleResult, parsers, (state, token) => {
-		const active = normalizeExclusiveState(state);
-		return combinePassThroughPriorities(parsers.map((parser, index) => getPassThroughPriority(parser, active?.[0] === index && active[1].success ? active[1].next.state : parser.initialState, token)));
-	});
+	defineReachableChildren(singleResult, parsers, (state) => selectExclusiveChildren(parsers, state, true));
 	return fluent(scopeParser(singleResult, combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 /**
@@ -2001,7 +2018,7 @@ function createLongestMatch(...args) {
 			},
 			consumed: [...optionsTerminatorResult.consumed, ...match.result.consumed]
 		};
-		const next = selectedResult.consumed.length === 0 ? withPassThroughFailure(selectedResult.next, consumingFailure) : selectedResult.next;
+		const next = selectedResult.consumed.length === 0 ? withReturnedConsumingFailure(selectedResult.next, consumingFailure) : selectedResult.next;
 		const parser = parsers[match.index];
 		const mergedExec = mergeChildExec(context.exec, next.exec);
 		return {
@@ -2046,10 +2063,8 @@ function createLongestMatch(...args) {
 		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
 		let consumingFailure;
-		const activeState = normalizeExclusiveState(context.state);
-		for (let i = 0; i < syncParsers.length; i++) {
-			const parser = syncParsers[i];
-			const childContext = withChildContext$1(forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+		for (const { parser, index: i, state: childState } of selectExclusiveChildren(syncParsers, context.state)) {
+			const childContext = withChildContext$1(forkOptionScope(context), i, childState, parser);
 			const result = parser.parse(childContext);
 			if (isOptionsTerminatorOnlyResult(context, result)) {
 				optionsTerminatorMatches.push({
@@ -2062,6 +2077,7 @@ function createLongestMatch(...args) {
 			}
 			if (result.success) {
 				consumingFailure = retainConsumingFailureHint(consumingFailure, context, result.next);
+				if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
@@ -2088,10 +2104,8 @@ function createLongestMatch(...args) {
 		const optionsTerminatorMatches = [];
 		let error = getInitialError(context);
 		let consumingFailure;
-		const activeState = normalizeExclusiveState(context.state);
-		for (let i = 0; i < parsers.length; i++) {
-			const parser = parsers[i];
-			const childContext = withChildContext$1(forkOptionScope(context), i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser);
+		for (const { parser, index: i, state: childState } of selectExclusiveChildren(parsers, context.state)) {
+			const childContext = withChildContext$1(forkOptionScope(context), i, childState, parser);
 			const resultOrPromise = parser.parse(childContext);
 			const result = await resultOrPromise;
 			if (isOptionsTerminatorOnlyResult(context, result)) {
@@ -2105,6 +2119,7 @@ function createLongestMatch(...args) {
 			}
 			if (result.success) {
 				consumingFailure = retainConsumingFailureHint(consumingFailure, context, result.next);
+				if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
 				const consumed = context.buffer.length - result.next.buffer.length;
 				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
 				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
@@ -2193,14 +2208,7 @@ function createLongestMatch(...args) {
 	if (multiDependencyMetadata != null) multiResult.dependencyMetadata = multiDependencyMetadata;
 	defineExclusiveSchedulingNodes(multiResult, parsers);
 	defineInheritedAnnotationParser(multiResult);
-	defineOptionMatch(multiResult, (state, token) => combineOptionMatches(parsers.map((parser, index) => {
-		const active = normalizeExclusiveState(state);
-		return getOptionMatch(parser, active?.[0] === index && active[1].success ? active[1].next.state : parser.initialState, token);
-	})));
-	definePassThroughPriority(multiResult, parsers, (state, token) => {
-		const active = normalizeExclusiveState(state);
-		return combinePassThroughPriorities(parsers.map((parser, index) => getPassThroughPriority(parser, active?.[0] === index && active[1].success ? active[1].next.state : parser.initialState, token)));
-	});
+	defineReachableChildren(multiResult, parsers, (state) => selectExclusiveChildren(parsers, state, false));
 	return fluent(scopeParser(multiResult, combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 /**
@@ -2642,7 +2650,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		if (!result.success) return result;
 		if (result.consumed.length === 0 && result.next.state === fieldState) return {
 			success: true,
-			next: context,
+			next: {
+				...context,
+				...getPassThroughFailureHint(result.next)
+			},
 			consumed: []
 		};
 		adoptOptionScope(context, result.next);
@@ -2723,8 +2734,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					madeProgress = true;
 					consumedFields.add(field);
 					break;
-				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
-				else {
+				} else if (result.success) {
+					consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
 					const match = getOptionMatch(parser, getFieldState(field, parser), currentContext.buffer[0]);
 					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
 					if (error.consumed < result.consumed) error = result;
@@ -2759,7 +2772,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		if (anySuccess) return {
 			success: true,
-			next: withPassThroughFailure(currentContext, consumingFailure),
+			next: withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 		if (currentContext.buffer.length === 0) {
@@ -2840,8 +2853,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					madeProgress = true;
 					consumedFields.add(field);
 					break;
-				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
-				else {
+				} else if (result.success) {
+					consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
 					const match = getOptionMatch(parser, getFieldState(field, parser), currentContext.buffer[0]);
 					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
 					if (error.consumed < result.consumed) error = result;
@@ -2876,7 +2891,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		if (anySuccess) return {
 			success: true,
-			next: withPassThroughFailure(currentContext, consumingFailure),
+			next: withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 		if (currentContext.buffer.length === 0) {
@@ -3246,8 +3261,13 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	});
 	defineParseLanes(objectParser, objectParseLanes);
 	defineInheritedAnnotationParser(objectParser);
-	defineOptionMatch(objectParser, (state, token) => combineOptionMatches(parserPairs.map(([field, parser]) => getOptionMatch(parser, getAnnotatedFieldState(state, typeof field === "number" ? String(field) : field, parser), token))));
-	definePassThroughPriority(objectParser, parserPairs.map(([, parser]) => parser), (state, token) => combinePassThroughPriorities(parserPairs.map(([field, parser]) => getPassThroughPriority(parser, getAnnotatedFieldState(state, typeof field === "number" ? String(field) : field, parser), token))));
+	defineReachableChildren(objectParser, parserPairs.map(([, parser]) => parser), (state) => {
+		const getFieldState = createFieldStateGetter(state, getObjectParseChildState);
+		return parserPairs.map(([field, parser]) => ({
+			parser,
+			state: getWrappedChildParseState(state, getFieldState(field, parser), parser)
+		}));
+	});
 	return fluent(scopeParser(objectParser, combinedOptionScope(parserPairs.map(([, p]) => p), parserPairs.map(([field]) => field)), void 0, true));
 }
 function isParserLike(value) {
@@ -3908,8 +3928,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
-				else {
+				} else if (result.success) {
+					consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
 					const match = getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
 					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
 					if (error.consumed < result.consumed) error = result;
@@ -3945,7 +3967,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		return {
 			success: true,
-			next: withPassThroughFailure(currentContext, consumingFailure),
+			next: withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -3984,8 +4006,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
-				else {
+				} else if (result.success) {
+					consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
 					const match = getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
 					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
 					if (error.consumed < result.consumed) error = result;
@@ -4022,7 +4046,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		return {
 			success: true,
-			next: withPassThroughFailure(currentContext, consumingFailure),
+			next: withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -4295,8 +4319,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		enumerable: false
 	});
 	defineInheritedAnnotationParser(tupleParser);
-	defineOptionMatch(tupleParser, (state, token) => combineOptionMatches(parsers.map((parser, index) => getOptionMatch(parser, getWrappedChildState(state, state[index], parser), token))));
-	definePassThroughPriority(tupleParser, parsers, (state, token) => combinePassThroughPriorities(parsers.map((parser, index) => getPassThroughPriority(parser, getWrappedChildState(state, state[index], parser), token))));
+	defineReachableChildren(tupleParser, parsers, (state) => parsers.map((parser, index) => ({
+		parser,
+		state: getWrappedChildParseState(state, state[index], parser)
+	})));
 	return fluent(scopeParser(tupleParser, combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 function seq(...rawArgs) {
@@ -5028,7 +5054,8 @@ function merge(...args) {
 					if (!canTryPositionalLaneAfterFailure(lane, currentContext)) continue;
 				}
 				attemptedLane = true;
-				const result = lane.parse(currentContext);
+				const childContext = withPassThroughFailure(currentContext, consumingFailure);
+				const result = lane.parse(childContext);
 				laneResults.set(lane, result);
 				if (result.success && result.consumed.length > 0) {
 					currentContext = result.next;
@@ -5038,6 +5065,13 @@ function merge(...args) {
 					madeProgress = true;
 					break;
 				}
+				if (result.success) {
+					const own = retainConsumingFailureHint(void 0, childContext, result.next);
+					if (own != null) {
+						consumingFailure = retainConsumingFailure(consumingFailure, own.failure, own.priority);
+						if (error.consumed < own.failure.consumed) error = own.failure;
+					}
+				}
 				if (!result.success) {
 					if (result.consumed > 0 && matchesOptionToken({
 						leadingNames: lane.leadingNames,
@@ -5074,7 +5108,7 @@ function merge(...args) {
 		}
 		return {
 			success: true,
-			next: withPassThroughFailure(currentContext, consumingFailure),
+			next: withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -5097,7 +5131,8 @@ function merge(...args) {
 					if (!canTryPositionalLaneAfterFailure(lane, currentContext)) continue;
 				}
 				attemptedLane = true;
-				const result = await lane.parse(currentContext);
+				const childContext = withPassThroughFailure(currentContext, consumingFailure);
+				const result = await lane.parse(childContext);
 				laneResults.set(lane, result);
 				if (result.success && result.consumed.length > 0) {
 					currentContext = result.next;
@@ -5107,6 +5142,13 @@ function merge(...args) {
 					madeProgress = true;
 					break;
 				}
+				if (result.success) {
+					const own = retainConsumingFailureHint(void 0, childContext, result.next);
+					if (own != null) {
+						consumingFailure = retainConsumingFailure(consumingFailure, own.failure, own.priority);
+						if (error.consumed < own.failure.consumed) error = own.failure;
+					}
+				}
 				if (!result.success) {
 					if (result.consumed > 0 && matchesOptionToken({
 						leadingNames: lane.leadingNames,
@@ -5143,7 +5185,7 @@ function merge(...args) {
 		}
 		return {
 			success: true,
-			next: withPassThroughFailure(currentContext, consumingFailure),
+			next: withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -5686,8 +5728,10 @@ function merge(...args) {
 	};
 	defineParseLanes(mergeParser, mergeParseLanes);
 	defineInheritedAnnotationParser(mergeParser);
-	defineOptionMatch(mergeParser, (state, token) => combineOptionMatches(sorted.map(([parser], index) => getOptionMatch(parser, extractParserStateFromState(parser, state, index), token))));
-	definePassThroughPriority(mergeParser, parsers, (state, token) => combinePassThroughPriorities(sorted.map(([parser], index) => getPassThroughPriority(parser, extractParserStateFromState(parser, state, index), token))));
+	defineReachableChildren(mergeParser, parsers, (state) => sorted.map(([parser], index) => ({
+		parser,
+		state: getWrappedChildParseState(state, extractParserStateFromState(parser, state, index), parser)
+	})));
 	return fluent(scopeParser(mergeParser, combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 /**
@@ -5961,8 +6005,10 @@ function concat(...parsers) {
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
-				else {
+				} else if (result.success) {
+					consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
 					const match = getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
 					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
 					if (error.consumed < result.consumed) error = result;
@@ -5998,7 +6044,7 @@ function concat(...parsers) {
 		}
 		return {
 			success: true,
-			next: withPassThroughFailure(currentContext, consumingFailure),
+			next: withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -6036,8 +6082,10 @@ function concat(...parsers) {
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
-				else {
+				} else if (result.success) {
+					consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+					if (consumingFailure != null && error.consumed < consumingFailure.failure.consumed) error = consumingFailure.failure;
+				} else {
 					const match = getOptionMatch(parser, stateArray[index], currentContext.buffer[0]);
 					if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
 					if (error.consumed < result.consumed) error = result;
@@ -6073,7 +6121,7 @@ function concat(...parsers) {
 		}
 		return {
 			success: true,
-			next: withPassThroughFailure(currentContext, consumingFailure),
+			next: withReturnedConsumingFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -6344,8 +6392,10 @@ function concat(...parsers) {
 		}
 	};
 	defineInheritedAnnotationParser(concatParser);
-	defineOptionMatch(concatParser, (state, token) => combineOptionMatches(parsers.map((parser, index) => getOptionMatch(parser, getWrappedChildState(state, state[index], parser), token))));
-	definePassThroughPriority(concatParser, parsers, (state, token) => combinePassThroughPriorities(parsers.map((parser, index) => getPassThroughPriority(parser, getWrappedChildState(state, state[index], parser), token))));
+	defineReachableChildren(concatParser, parsers, (state) => parsers.map((parser, index) => ({
+		parser,
+		state: getWrappedChildParseState(state, state[index], parser)
+	})));
 	return fluent(scopeParser(concatParser, combinedOptionScope(parsers, parsers.map((_, index) => index))));
 }
 function group(label, parser, options = {}) {
@@ -6465,8 +6515,10 @@ function group(label, parser, options = {}) {
 		enumerable: false
 	});
 	delegateKnownCompletion(groupParser, parser);
-	defineOptionMatch(groupParser, (state, token) => getOptionMatch(parser, state, token));
-	definePassThroughPriority(groupParser, [parser], (state, token) => getPassThroughPriority(parser, state, token));
+	defineReachableChildren(groupParser, [parser], (state) => [{
+		parser,
+		state
+	}]);
 	return fluent(scopeParser(groupParser, combinedOptionScope([parser])));
 }
 /**
@@ -6577,13 +6629,14 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		return options?.errors?.noMatch ? typeof options.errors.noMatch === "function" ? options.errors.noMatch(noMatchContext) : options.errors.noMatch : generateNoMatchError(noMatchContext);
 	};
 	const optionScope = conditionalOptionScope(discriminator, defaultBranch, branchParsers.map(([, p]) => p));
+	const selectBranch = (selected, table, fallback) => selected.kind === "default" ? fallback : table[selected.key];
 	const parseSync = (context) => {
 		const state = context.state ?? initialState;
 		const syncDiscriminator = discriminator;
 		const syncBranches = branches;
 		const syncDefaultBranch = defaultBranch;
 		if (state.selectedBranch !== void 0) {
-			const branchParser = state.selectedBranch.kind === "default" ? syncDefaultBranch : syncBranches[state.selectedBranch.key];
+			const branchParser = selectBranch(state.selectedBranch, syncBranches, syncDefaultBranch);
 			const branchResult = branchParser.parse(withChildContext$1(context, "_branch", state.branchState, branchParser, branchParser.usage));
 			if (branchResult.success) {
 				const mergedExec = mergeChildExec(context.exec, branchResult.next.exec);
@@ -6724,7 +6777,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 	const parseAsync = async (context) => {
 		const state = context.state ?? initialState;
 		if (state.selectedBranch !== void 0) {
-			const branchParser = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+			const branchParser = selectBranch(state.selectedBranch, branches, defaultBranch);
 			const branchResult = await branchParser.parse(withChildContext$1(context, "_branch", state.branchState, branchParser, branchParser.usage));
 			if (branchResult.success) {
 				const mergedExec = mergeChildExec(context.exec, branchResult.next.exec);
@@ -7842,7 +7895,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 	});
 	const reachableBranches = (state) => {
 		if (state.selectedBranch != null) {
-			const branch = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+			const branch = selectBranch(state.selectedBranch, branches, defaultBranch);
 			return branch == null ? [] : [{
 				branch,
 				state: state.branchState
@@ -7862,18 +7915,17 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			state: branch.initialState
 		}));
 	};
-	definePassThroughPriority(conditionalParser, [discriminator, ...allBranchParsers], (state, token) => combinePassThroughPriorities([...state.selectedBranch == null ? [getPassThroughPriority(discriminator, state.discriminatorState, token)] : [], ...reachableBranches(state).map(({ branch, state: state$1 }) => getPassThroughPriority(branch, state$1, token))]));
-	defineOptionMatch(conditionalParser, (state, token) => {
-		if (state.selectedBranch != null) {
-			const branch = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
-			return branch == null ? void 0 : getOptionMatch(branch, state.branchState, token);
-		}
-		return combineOptionMatches([getOptionMatch(discriminator, state.discriminatorState, token), ...reachableBranches(state).map(({ branch, state: state$1 }) => getOptionMatch(branch, state$1, token))]);
-	});
+	defineReachableChildren(conditionalParser, [discriminator, ...allBranchParsers], (state) => [...state.selectedBranch == null ? [{
+		parser: discriminator,
+		state: getWrappedChildParseState(state, state.discriminatorState, discriminator)
+	}] : [], ...reachableBranches(state).map(({ branch, state: childState }) => ({
+		parser: branch,
+		state: getWrappedChildParseState(state, childState, branch)
+	}))]);
 	return fluent(scopeParser(conditionalParser, optionScope.source, (context) => {
 		const selected = context.state?.selectedBranch;
 		if (selected != null) {
-			const branch = selected.kind === "default" ? defaultBranch : branches[selected.key];
+			const branch = selectBranch(selected, branches, defaultBranch);
 			if (branch != null) optionScope.select(context, branch);
 		}
 	}));

package/dist/extension.cjs

@@ -99,8 +99,10 @@ function mapSourceMetadata(parser, mapSource) {
 * @since 1.0.11
 */
 function delegateOptionParsing(wrapper, inner, getInnerState) {
-	require_passthrough.defineOptionMatch(wrapper, (state, token) => require_passthrough.getOptionMatch(inner, getInnerState(state), token));
-	require_passthrough.definePassThroughPriority(wrapper, [inner], (state, token) => require_passthrough.getPassThroughPriority(inner, getInnerState(state), token));
+	require_passthrough.defineReachableChildren(wrapper, [inner], (state) => [{
+		parser: inner,
+		state: getInnerState(state)
+	}]);
 }
 
 //#endregion

package/dist/extension.js

@@ -3,7 +3,7 @@ import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispa
 import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, defineInheritedAnnotationParser, getDelegatingSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { withAnnotationView } from "./annotation-state.js";
 import { inheritOptionScope } from "./short-option.js";
-import { defineOptionMatch, definePassThroughPriority, getOptionMatch, getPassThroughPriority } from "./internal/passthrough.js";
+import { defineReachableChildren } from "./internal/passthrough.js";
 import { extractPhase2SeedKey } from "./phase2-seed.js";
 
 //#region src/extension.ts
@@ -99,8 +99,10 @@ function mapSourceMetadata(parser, mapSource) {
 * @since 1.0.11
 */
 function delegateOptionParsing(wrapper, inner, getInnerState) {
-	defineOptionMatch(wrapper, (state, token) => getOptionMatch(inner, getInnerState(state), token));
-	definePassThroughPriority(wrapper, [inner], (state, token) => getPassThroughPriority(inner, getInnerState(state), token));
+	defineReachableChildren(wrapper, [inner], (state) => [{
+		parser: inner,
+		state: getInnerState(state)
+	}]);
 }
 
 //#endregion

package/dist/internal/passthrough.cjs

@@ -29,6 +29,15 @@ function getPassThroughFailure(context, capturePriority$1 = -Infinity) {
 * @internal
 */
 function withPassThroughFailure(context, failure, capturePriority$1 = -Infinity) {
+	const incoming = context;
+	if (incoming[passThroughFailure]?.own != null) {
+		const { own: _own,...hint } = incoming[passThroughFailure];
+		const stripped = {
+			...context,
+			[passThroughFailure]: hint
+		};
+		context = stripped;
+	}
 	const token = context.buffer[0];
 	const existing = getPassThroughFailure(context);
 	if (existing != null && existing.priority < capturePriority$1) {
@@ -49,11 +58,39 @@ function withPassThroughFailure(context, failure, capturePriority$1 = -Infinity)
 	};
 	return hinted;
 }
-/** Retains a child's rejected option failure only at the parent's cursor. @internal */
+/** Reads locally originated diagnostics at the same cursor. @internal */
+function getOwnConsumingFailure(context) {
+	const hinted = context;
+	const hint = hinted[passThroughFailure];
+	return hint?.buffer === context.buffer && hint.optionsTerminated === context.optionsTerminated ? hint.own : void 0;
+}
+/**
+* Returns a successful child's local diagnostic to its parent without merging
+* its provenance with an inherited sibling diagnostic. Both share a cursor.
+* @internal
+*/
+function withReturnedConsumingFailure(context, failure) {
+	const next = withPassThroughFailure(context, failure);
+	if (failure == null || getPassThroughFailure(next) == null) return next;
+	const token = next.buffer[0];
+	if (next.optionsTerminated || token == null || token === "--" || !/^[-/+]/.test(token) || failure.failure.consumed < 1) return next;
+	const hinted = next;
+	const hint = hinted[passThroughFailure];
+	if (hint == null) return next;
+	const returned = {
+		...next,
+		[passThroughFailure]: {
+			...hint,
+			own: failure
+		}
+	};
+	return returned;
+}
+/** Retains a child's own rejected option failure at the parent's cursor. @internal */
 function retainConsumingFailureHint(current, context, next) {
 	if (next.buffer !== context.buffer || next.optionsTerminated !== context.optionsTerminated) return current;
-	const hint = getPassThroughFailure(next);
-	return hint == null ? current : retainConsumingFailure(current, hint.failure, hint.priority);
+	const own = getOwnConsumingFailure(next);
+	return own == null || own === getOwnConsumingFailure(context) ? current : retainConsumingFailure(current, own.failure, own.priority);
 }
 const capturePriority = Symbol("capturePriority");
 /** Checks for capture through usage-preserving wrappers. @internal */
@@ -209,14 +246,30 @@ function delegateKnownCompletion(wrapper, inner) {
 		enumerable: true
 	});
 }
+/**
+* Installs option and capture inspection from one pure child-state selector.
+* Static children retain capture metadata even when no child is selected yet.
+* Selection must not execute parsing, completion, or user callbacks. Potential
+* alternatives remain candidates until parse-time replay or canSkip resolves
+* them; inspection cannot safely predict opaque custom parser callbacks.
+* @internal
+*/
+function defineReachableChildren(parser, children, select) {
+	defineOptionMatch(parser, (state, token) => combineOptionMatches(select(state).map((child) => {
+		const match = getOptionMatch(child.parser, child.state, token);
+		return match == null || !child.continuesCommand ? match : {
+			...match,
+			continuesCommand: true
+		};
+	})));
+	definePassThroughPriority(parser, children, (state, token) => combinePassThroughPriorities(select(state).map((child) => getPassThroughPriority(child.parser, child.state, token))));
+}
 
 //#endregion
-exports.combineOptionMatches = combineOptionMatches;
-exports.combinePassThroughPriorities = combinePassThroughPriorities;
 exports.defineKnownCompletion = defineKnownCompletion;
 exports.defineKnownCompletionLookup = defineKnownCompletionLookup;
-exports.defineOptionMatch = defineOptionMatch;
 exports.definePassThroughPriority = definePassThroughPriority;
+exports.defineReachableChildren = defineReachableChildren;
 exports.delegateKnownCompletion = delegateKnownCompletion;
 exports.getKnownCompletion = getKnownCompletion;
 exports.getOptionMatch = getOptionMatch;
@@ -227,4 +280,5 @@ exports.hasPassThroughUsage = hasPassThroughUsage;
 exports.matchesOptionToken = matchesOptionToken;
 exports.retainConsumingFailure = retainConsumingFailure;
 exports.retainConsumingFailureHint = retainConsumingFailureHint;
-exports.withPassThroughFailure = withPassThroughFailure;
+exports.withPassThroughFailure = withPassThroughFailure;
+exports.withReturnedConsumingFailure = withReturnedConsumingFailure;