@optique/core 1.2.8 → 1.2.9

package/dist/constructs.js

@@ -8,6 +8,7 @@ import { createDependencySourceState, dependencyId, isDependencySourceState, isP
 import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyRuntimeContext, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync } from "./dependency-runtime.js";
 import { defineInheritedAnnotationParser, defineParseLanes, getOwnParseLanes, getParserSuggestRuntimeNodes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { annotationViewTargets, getWrappedChildParseState, getWrappedChildState, reconcileObjectChildState, unwrapAnnotationView } from "./annotation-state.js";
+import { combineOptionMatches, combinePassThroughPriorities, defineOptionMatch, definePassThroughPriority, delegateKnownCompletion, getKnownCompletion, getOptionMatch, getPassThroughFailureHint, getPassThroughPriority, hasPassThroughUsage, matchesOptionToken, retainConsumingFailure, retainConsumingFailureHint, withPassThroughFailure } from "./internal/passthrough.js";
 import { allowDuplicateLeadingCommandNamesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
@@ -98,6 +99,63 @@ function sharedBufferLeadingNames(parsers) {
 	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
 }
 /**
+* Defers capture until a known option at an equal or higher lane priority
+* has been tried.
+* Other siblings retain their relative order, and explicit priorities win.
+*/
+function orderBeforePassThrough(pairs, context, getParser, getState, passThroughParsers) {
+	const token = context.buffer[0];
+	if (passThroughParsers.size === 0 || context.optionsTerminated || token == null || token === "--" || !/^[-/+]/.test(token)) return pairs;
+	const matches = new Map(pairs.map((pair) => [pair, getOptionMatch(getParser(pair), getState(pair), token)]));
+	const normalizedOptions = /* @__PURE__ */ new Map();
+	const captures = new Map(pairs.flatMap((pair) => {
+		if (!passThroughParsers.has(getParser(pair))) return [];
+		const priority = getPassThroughPriority(getParser(pair), getState(pair), token);
+		const match = matches.get(pair);
+		if (match != null && (priority == null || match.priority >= priority)) {
+			const unfiltered = getPassThroughPriority(getParser(pair), getState(pair));
+			if (priority == null || unfiltered != null && unfiltered > match.priority) normalizedOptions.set(pair, match.priority);
+			return [];
+		}
+		return priority == null ? [] : [[pair, priority]];
+	}));
+	const matching = pairs.filter((pair) => !captures.has(pair)).flatMap((pair) => {
+		const match = matches.get(pair);
+		return match == null ? [] : [match];
+	});
+	const orderedCaptures = [...captures].sort((a, b) => b[1] - a[1]);
+	if (matching.length === 0) {
+		let captureIndex = 0;
+		return pairs.map((pair) => captures.has(pair) ? orderedCaptures[captureIndex++][0] : pair);
+	}
+	const matchingPriority = Math.max(...matching.map((match) => match.priority));
+	const ordinary = pairs.filter((pair) => !captures.has(pair) && !normalizedOptions.has(pair));
+	const positions = new Map(pairs.map((pair, index) => [pair, index]));
+	for (const [pair, priority] of [...normalizedOptions].sort((a, b) => b[1] - a[1])) {
+		let insertion = ordinary.findIndex((candidate) => {
+			const match = matches.get(candidate);
+			return match != null && (match.priority < priority || match.priority === priority && positions.get(pair) < positions.get(candidate));
+		});
+		if (insertion < 0) {
+			const lastMatch = ordinary.findLastIndex((candidate) => matches.get(candidate) != null);
+			insertion = lastMatch >= 0 ? lastMatch + 1 : ordinary.findIndex((candidate) => positions.get(candidate) > positions.get(pair));
+			if (insertion < 0) insertion = ordinary.length;
+		}
+		ordinary.splice(insertion, 0, pair);
+	}
+	const first = ordinary.findIndex((pair) => matches.get(pair) != null);
+	const last = ordinary.findLastIndex((pair) => matches.get(pair) != null);
+	const before = orderedCaptures.filter(([, priority]) => priority > matchingPriority).map(([pair]) => pair);
+	const after = orderedCaptures.filter(([, priority]) => priority <= matchingPriority).map(([pair]) => pair);
+	return [
+		...ordinary.slice(0, first),
+		...before,
+		...ordinary.slice(first, last + 1),
+		...after,
+		...ordinary.slice(last + 1)
+	];
+}
+/**
 * Internal symbol for exposing field-level parser pairs from `object()`
 * and `merge()` parsers.  This allows `merge()` to pre-complete dependency
 * source fields from child parsers before resolving deferred states.
@@ -599,6 +657,7 @@ function preserveExclusiveStateAfterOptionsTerminator(context, result) {
 		success: true,
 		next: {
 			...context,
+			...getPassThroughFailureHint(result.next),
 			buffer: result.next.buffer,
 			optionsTerminated: true,
 			state: context.state,
@@ -887,6 +946,7 @@ function or(...args) {
 							success: true,
 							next: {
 								...context,
+								...getPassThroughFailureHint(result.next),
 								buffer: result.next.buffer,
 								optionsTerminated: result.next.optionsTerminated,
 								state: createExclusiveState(context.state, i, parser, result),
@@ -923,6 +983,7 @@ function or(...args) {
 						success: true,
 						next: {
 							...context,
+							...getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, i, parser, {
@@ -942,6 +1003,7 @@ function or(...args) {
 					success: true,
 					next: {
 						...context,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: createExclusiveState(context.state, i, parser, result),
@@ -986,6 +1048,7 @@ function or(...args) {
 					provisional: true,
 					next: {
 						...context,
+						...getPassThroughFailureHint(provisionalConsuming.result.next),
 						buffer: provisionalConsuming.result.next.buffer,
 						optionsTerminated: provisionalConsuming.result.next.optionsTerminated,
 						state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, provisionalConsuming.result),
@@ -1020,6 +1083,7 @@ function or(...args) {
 						provisional: true,
 						next: {
 							...context,
+							...getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
@@ -1091,6 +1155,7 @@ function or(...args) {
 							success: true,
 							next: {
 								...context,
+								...getPassThroughFailureHint(result.next),
 								buffer: result.next.buffer,
 								optionsTerminated: result.next.optionsTerminated,
 								state: createExclusiveState(context.state, i, parser, result),
@@ -1129,6 +1194,7 @@ function or(...args) {
 						success: true,
 						next: {
 							...context,
+							...getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, i, parser, {
@@ -1148,6 +1214,7 @@ function or(...args) {
 					success: true,
 					next: {
 						...context,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: createExclusiveState(context.state, i, parser, result),
@@ -1192,6 +1259,7 @@ function or(...args) {
 					provisional: true,
 					next: {
 						...context,
+						...getPassThroughFailureHint(provisionalConsuming.result.next),
 						buffer: provisionalConsuming.result.next.buffer,
 						optionsTerminated: provisionalConsuming.result.next.optionsTerminated,
 						state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, provisionalConsuming.result),
@@ -1226,6 +1294,7 @@ function or(...args) {
 						provisional: true,
 						next: {
 							...context,
+							...getPassThroughFailureHint(replayedResult.next),
 							buffer: replayedResult.next.buffer,
 							optionsTerminated: replayedResult.next.optionsTerminated,
 							state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
@@ -1311,6 +1380,14 @@ function or(...args) {
 	const singleDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
 	if (singleDependencyMetadata != null) singleResult.dependencyMetadata = singleDependencyMetadata;
 	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)));
+	});
 	return fluent(singleResult);
 }
 /**
@@ -1345,24 +1422,27 @@ function createLongestMatch(...args) {
 			return createUnexpectedInputErrorWithScopedSuggestions(defaultMsg, token, parsers, options?.errors?.suggestions);
 		})()
 	});
-	const commitLongestMatch = (context, match, optionsTerminatorResult) => {
+	const commitLongestMatch = (context, match, optionsTerminatorResult, consumingFailure) => {
 		const selectedResult = optionsTerminatorResult == null ? match.result : {
 			...match.result,
 			next: {
 				...match.result.next,
+				...getPassThroughFailureHint(optionsTerminatorResult.next),
 				buffer: optionsTerminatorResult.next.buffer,
 				optionsTerminated: true
 			},
 			consumed: [...optionsTerminatorResult.consumed, ...match.result.consumed]
 		};
+		const next = selectedResult.consumed.length === 0 ? withPassThroughFailure(selectedResult.next, consumingFailure) : selectedResult.next;
 		const parser = parsers[match.index];
-		const mergedExec = mergeChildExec(context.exec, selectedResult.next.exec);
+		const mergedExec = mergeChildExec(context.exec, next.exec);
 		return {
 			success: true,
 			next: {
 				...context,
-				buffer: selectedResult.next.buffer,
-				optionsTerminated: selectedResult.next.optionsTerminated,
+				...getPassThroughFailureHint(next),
+				buffer: next.buffer,
+				optionsTerminated: next.optionsTerminated,
 				state: createExclusiveState(context.state, match.index, parser, selectedResult),
 				...mergedExec != null ? {
 					exec: mergedExec,
@@ -1397,6 +1477,7 @@ function createLongestMatch(...args) {
 		let bestMatch = null;
 		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];
@@ -1412,6 +1493,7 @@ function createLongestMatch(...args) {
 				continue;
 			}
 			if (result.success) {
+				consumingFailure = retainConsumingFailureHint(consumingFailure, context, result.next);
 				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 = {
@@ -1419,11 +1501,15 @@ function createLongestMatch(...args) {
 					result,
 					consumed
 				};
-			} else if (error.consumed < result.consumed) error = result;
+			} else {
+				const match = getOptionMatch(parser, childContext.state, context.buffer[0]);
+				if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
+				if (error.consumed < result.consumed) error = result;
+			}
 		}
 		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
 		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
-		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch, void 0, consumingFailure);
 		return {
 			...error,
 			success: false
@@ -1433,6 +1519,7 @@ function createLongestMatch(...args) {
 		let bestMatch = null;
 		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];
@@ -1449,6 +1536,7 @@ function createLongestMatch(...args) {
 				continue;
 			}
 			if (result.success) {
+				consumingFailure = retainConsumingFailureHint(consumingFailure, context, result.next);
 				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 = {
@@ -1456,11 +1544,15 @@ function createLongestMatch(...args) {
 					result,
 					consumed
 				};
-			} else if (error.consumed < result.consumed) error = result;
+			} else {
+				const match = getOptionMatch(parser, childContext.state, context.buffer[0]);
+				if (result.consumed > 0 && match != null) consumingFailure = retainConsumingFailure(consumingFailure, result, match.priority);
+				if (error.consumed < result.consumed) error = result;
+			}
 		}
 		const optionsTerminatorResolution = resolveLongestMatchOptionsTerminator(context, bestMatch, optionsTerminatorMatches);
 		if (optionsTerminatorResolution != null) return optionsTerminatorResolution;
-		if (bestMatch != null) return commitLongestMatch(context, bestMatch);
+		if (bestMatch != null) return commitLongestMatch(context, bestMatch, void 0, consumingFailure);
 		return {
 			...error,
 			success: false
@@ -1526,6 +1618,14 @@ function createLongestMatch(...args) {
 	const multiDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
 	if (multiDependencyMetadata != null) multiResult.dependencyMetadata = multiDependencyMetadata;
 	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)));
+	});
 	return fluent(multiResult);
 }
 /**
@@ -1916,6 +2016,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const parserKeys = Reflect.ownKeys(parsers);
 	const parserPairs = parserKeys.map((k) => [k, parsers[k]]);
 	parserPairs.sort(([_, parserA], [__, parserB]) => parserB.priority - parserA.priority);
+	const passThroughParsers = new Set(parserPairs.map(([, parser]) => parser).filter((parser) => hasPassThroughUsage(parser.usage)));
 	const createInitialState = () => {
 		const state = {};
 		for (const key of parserKeys) state[key] = parsers[key].initialState;
@@ -1965,6 +2066,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			success: true,
 			next: {
 				...context,
+				...getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: nextState,
@@ -2001,16 +2103,19 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let anySuccess = false;
 		const allConsumed = [];
 		const consumedFields = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			consumingFailure = void 0;
 			const getFieldState = createFieldStateGetter(currentContext.state, getObjectParseChildState);
-			for (const [field, parser] of parserPairs) {
-				const result = parser.parse(withChildContext$1(currentContext, field, getFieldState(field, parser), parser));
+			for (const [field, parser] of orderBeforePassThrough(parserPairs, currentContext, ([, parser$1]) => parser$1, ([field$1, parser$1]) => getFieldState(field$1, parser$1), passThroughParsers)) {
+				const result = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, field, getFieldState(field, parser), parser), consumingFailure, getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: {
@@ -2028,7 +2133,12 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					madeProgress = true;
 					consumedFields.add(field);
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				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;
+				}
 			}
 		}
 		{
@@ -2038,7 +2148,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				const typedParser = parser;
 				if (parser.leadingNames.size > 0 || typedParser.acceptingAnyToken) continue;
 				const fieldState = getFieldState(field, parser);
-				const result = typedParser.parse(withChildContext$1(currentContext, field, fieldState, parser));
+				const result = typedParser.parse(withPassThroughFailure(withChildContext$1(currentContext, field, fieldState, parser), consumingFailure, getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				if (result.success && result.consumed.length === 0 && result.next.state !== fieldState) {
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
@@ -2058,7 +2168,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		if (anySuccess) return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 		if (currentContext.buffer.length === 0) {
@@ -2107,17 +2217,20 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let anySuccess = false;
 		const allConsumed = [];
 		const consumedFields = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			consumingFailure = void 0;
 			const getFieldState = createFieldStateGetter(currentContext.state, getObjectParseChildState);
-			for (const [field, parser] of parserPairs) {
-				const resultOrPromise = parser.parse(withChildContext$1(currentContext, field, getFieldState(field, parser), parser));
+			for (const [field, parser] of orderBeforePassThrough(parserPairs, currentContext, ([, parser$1]) => parser$1, ([field$1, parser$1]) => getFieldState(field$1, parser$1), passThroughParsers)) {
+				const resultOrPromise = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, field, getFieldState(field, parser), parser), consumingFailure, getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: {
@@ -2135,7 +2248,12 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					madeProgress = true;
 					consumedFields.add(field);
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				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;
+				}
 			}
 		}
 		{
@@ -2144,7 +2262,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				if (consumedFields.has(field)) continue;
 				if (parser.leadingNames.size > 0 || parser.acceptingAnyToken) continue;
 				const fieldState = getFieldState(field, parser);
-				const resultOrPromise = parser.parse(withChildContext$1(currentContext, field, fieldState, parser));
+				const resultOrPromise = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, field, fieldState, parser), consumingFailure, getPassThroughPriority(parser, getFieldState(field, parser), currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length === 0 && result.next.state !== fieldState) {
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
@@ -2165,7 +2283,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		if (anySuccess) return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 		if (currentContext.buffer.length === 0) {
@@ -2515,6 +2633,8 @@ 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))));
 	return fluent(objectParser);
 }
 function isParserLike(value) {
@@ -2965,6 +3085,7 @@ function advanceTupleSuggestContextSync(context, parsers) {
 				const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
+					...getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newStateArray,
@@ -3031,6 +3152,7 @@ async function advanceTupleSuggestContextAsync(context, parsers) {
 				const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 				currentContext = {
 					...currentContext,
+					...getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newStateArray,
@@ -3130,10 +3252,12 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const combinedMode = parsers.some((p) => p.mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parsers.map((parser, index) => [String(index), parser.usage]));
+	const passThroughParsers = new Set(parsers.filter((parser) => hasPassThroughUsage(parser.usage)));
 	const parseSync = (context) => {
 		let currentContext = context;
 		const allConsumed = [];
 		const matchedParsers = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		while (matchedParsers.size < syncParsers.length) {
 			let foundMatch = false;
 			let error = {
@@ -3141,14 +3265,15 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				error: message`No remaining parsers could match the input.`
 			};
 			const stateArray = currentContext.state;
-			const remainingParsers = syncParsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
+			const remainingParsers = orderBeforePassThrough(syncParsers.map((parser, index) => [parser, index]).filter(([parser, index]) => !matchedParsers.has(index) || getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && getOptionMatch(parser, stateArray[index], currentContext.buffer[0]) != null).sort(([parserA], [parserB]) => parserB.priority - parserA.priority), currentContext, ([parser]) => parser, ([, index]) => stateArray[index], passThroughParsers);
 			for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				const result = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -3157,14 +3282,21 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							dependencyRegistry: mergedExec.dependencyRegistry
 						} : {}
 					};
+					consumingFailure = void 0;
 					allConsumed.push(...result.consumed);
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				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;
+				}
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				if (matchedParsers.has(index)) continue;
+				const result = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length < 1) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
@@ -3192,7 +3324,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -3200,6 +3332,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let currentContext = context;
 		const allConsumed = [];
 		const matchedParsers = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		while (matchedParsers.size < parsers.length) {
 			let foundMatch = false;
 			let error = {
@@ -3207,15 +3340,16 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				error: message`No remaining parsers could match the input.`
 			};
 			const stateArray = currentContext.state;
-			const remainingParsers = parsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
+			const remainingParsers = orderBeforePassThrough(parsers.map((parser, index) => [parser, index]).filter(([parser, index]) => !matchedParsers.has(index) || getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && getOptionMatch(parser, stateArray[index], currentContext.buffer[0]) != null).sort(([parserA], [parserB]) => parserB.priority - parserA.priority), currentContext, ([parser]) => parser, ([, index]) => stateArray[index], passThroughParsers);
 			for (const [parser, index] of remainingParsers) {
-				const resultOrPromise = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				const resultOrPromise = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -3224,14 +3358,21 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 							dependencyRegistry: mergedExec.dependencyRegistry
 						} : {}
 					};
+					consumingFailure = void 0;
 					allConsumed.push(...result.consumed);
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				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;
+				}
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const resultOrPromise = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				if (matchedParsers.has(index)) continue;
+				const resultOrPromise = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length < 1) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
@@ -3260,7 +3401,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -3513,6 +3654,8 @@ 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))));
 	return fluent(tupleParser);
 }
 function seq(...rawArgs) {
@@ -3926,6 +4069,7 @@ function merge(...args) {
 			success: true,
 			next: {
 				...context,
+				...getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: newState,
@@ -4031,6 +4175,7 @@ function merge(...args) {
 			const mergedExec = mergeChildExec(settledContext.exec, result.next.exec);
 			settledContext = {
 				...settledContext,
+				...getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: nextState,
@@ -4063,6 +4208,7 @@ function merge(...args) {
 				const newState = mergeResultState(parser, currentContext, parserState, result, i);
 				const newContext = {
 					...currentContext,
+					...getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newState,
@@ -4108,6 +4254,7 @@ function merge(...args) {
 				const newState = mergeResultState(parser, currentContext, parserState, result, i);
 				const newContext = {
 					...currentContext,
+					...getPassThroughFailureHint(result.next),
 					buffer: result.next.buffer,
 					optionsTerminated: result.next.optionsTerminated,
 					state: newState,
@@ -4147,10 +4294,12 @@ function merge(...args) {
 		const consumedLanes = /* @__PURE__ */ new Set();
 		const consumedGroups = /* @__PURE__ */ new Set();
 		const laneResults = /* @__PURE__ */ new Map();
+		let consumingFailure;
 		let attemptedLane = false;
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			consumingFailure = void 0;
 			let consumingError = null;
 			for (const lane of mergeParseLanes) {
 				if (consumingError != null && lane.priority < consumingError.priority) {
@@ -4168,6 +4317,10 @@ function merge(...args) {
 					break;
 				}
 				if (!result.success) {
+					if (result.consumed > 0 && matchesOptionToken({
+						leadingNames: lane.leadingNames,
+						usage: parsers.flatMap((parser) => parser.usage)
+					}, currentContext.buffer[0])) consumingFailure = retainConsumingFailure(consumingFailure, result, lane.priority);
 					if (result.consumed > 0 && consumingError == null) consumingError = {
 						priority: lane.priority,
 						result
@@ -4199,7 +4352,7 @@ function merge(...args) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -4210,10 +4363,12 @@ function merge(...args) {
 		const consumedLanes = /* @__PURE__ */ new Set();
 		const consumedGroups = /* @__PURE__ */ new Set();
 		const laneResults = /* @__PURE__ */ new Map();
+		let consumingFailure;
 		let attemptedLane = false;
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
+			consumingFailure = void 0;
 			let consumingError = null;
 			for (const lane of mergeParseLanes) {
 				if (consumingError != null && lane.priority < consumingError.priority) {
@@ -4231,6 +4386,10 @@ function merge(...args) {
 					break;
 				}
 				if (!result.success) {
+					if (result.consumed > 0 && matchesOptionToken({
+						leadingNames: lane.leadingNames,
+						usage: parsers.flatMap((parser) => parser.usage)
+					}, currentContext.buffer[0])) consumingFailure = retainConsumingFailure(consumingFailure, result, lane.priority);
 					if (result.consumed > 0 && consumingError == null) consumingError = {
 						priority: lane.priority,
 						result
@@ -4262,7 +4421,7 @@ function merge(...args) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -4751,6 +4910,8 @@ 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))));
 	return fluent(mergeParser);
 }
 /**
@@ -4941,6 +5102,7 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 					const mergedExec = mergeChildExec(context.exec, result$1.next.exec);
 					return preParseSuggestLoop({
 						...context,
+						...getPassThroughFailureHint(result$1.next),
 						buffer: result$1.next.buffer,
 						optionsTerminated: result$1.next.optionsTerminated,
 						state: stateArray,
@@ -4968,6 +5130,7 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 			const mergedExec = mergeChildExec(context.exec, result.next.exec);
 			return {
 				...context,
+				...getPassThroughFailureHint(result.next),
 				buffer: result.next.buffer,
 				optionsTerminated: result.next.optionsTerminated,
 				state: stateArray,
@@ -4987,10 +5150,12 @@ function concat(...parsers) {
 	const isAsync = combinedMode === "async";
 	const syncParsers = parsers;
 	const initialState = parsers.map((parser) => parser.initialState);
+	const passThroughParsers = new Set(parsers.filter((parser) => hasPassThroughUsage(parser.usage)));
 	const parseSync = (context) => {
 		let currentContext = context;
 		const allConsumed = [];
 		const matchedParsers = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		while (matchedParsers.size < syncParsers.length) {
 			let foundMatch = false;
 			let error = {
@@ -4998,14 +5163,15 @@ function concat(...parsers) {
 				error: message`No remaining parsers could match the input.`
 			};
 			const stateArray = currentContext.state;
-			const remainingParsers = syncParsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
+			const remainingParsers = orderBeforePassThrough(syncParsers.map((parser, index) => [parser, index]).filter(([parser, index]) => !matchedParsers.has(index) || getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && getOptionMatch(parser, stateArray[index], currentContext.buffer[0]) != null).sort(([parserA], [parserB]) => parserB.priority - parserA.priority), currentContext, ([parser]) => parser, ([, index]) => stateArray[index], passThroughParsers);
 			for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				const result = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -5014,14 +5180,21 @@ function concat(...parsers) {
 							dependencyRegistry: mergedExec.dependencyRegistry
 						} : {}
 					};
+					consumingFailure = void 0;
 					allConsumed.push(...result.consumed);
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				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;
+				}
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				if (matchedParsers.has(index)) continue;
+				const result = parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length < 1) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
@@ -5049,7 +5222,7 @@ function concat(...parsers) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -5057,6 +5230,7 @@ function concat(...parsers) {
 		let currentContext = context;
 		const allConsumed = [];
 		const matchedParsers = /* @__PURE__ */ new Set();
+		let consumingFailure;
 		while (matchedParsers.size < parsers.length) {
 			let foundMatch = false;
 			let error = {
@@ -5064,14 +5238,15 @@ function concat(...parsers) {
 				error: message`No remaining parsers could match the input.`
 			};
 			const stateArray = currentContext.state;
-			const remainingParsers = parsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
+			const remainingParsers = orderBeforePassThrough(parsers.map((parser, index) => [parser, index]).filter(([parser, index]) => !matchedParsers.has(index) || getOptionMatch(parser, stateArray[index], currentContext.buffer[0])?.continuesCommand === true || passThroughParsers.size > 0 && !currentContext.optionsTerminated && getOptionMatch(parser, stateArray[index], currentContext.buffer[0]) != null).sort(([parserA], [parserB]) => parserB.priority - parserA.priority), currentContext, ([parser]) => parser, ([, index]) => stateArray[index], passThroughParsers);
 			for (const [parser, index] of remainingParsers) {
-				const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				const result = await parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length > 0) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
+						...getPassThroughFailureHint(result.next),
 						buffer: result.next.buffer,
 						optionsTerminated: result.next.optionsTerminated,
 						state: newStateArray,
@@ -5080,14 +5255,21 @@ function concat(...parsers) {
 							dependencyRegistry: mergedExec.dependencyRegistry
 						} : {}
 					};
+					consumingFailure = void 0;
 					allConsumed.push(...result.consumed);
 					matchedParsers.add(index);
 					foundMatch = true;
 					break;
-				} else if (!result.success && error.consumed < result.consumed) error = result;
+				} else if (result.success) consumingFailure = retainConsumingFailureHint(consumingFailure, currentContext, result.next);
+				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;
+				}
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const result = await parser.parse(withChildContext$1(currentContext, index, stateArray[index], parser));
+				if (matchedParsers.has(index)) continue;
+				const result = await parser.parse(withPassThroughFailure(withChildContext$1(currentContext, index, stateArray[index], parser), consumingFailure, getPassThroughPriority(parser, stateArray[index], currentContext.buffer[0])));
 				if (result.success && result.consumed.length < 1) {
 					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getWrappedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
@@ -5115,7 +5297,7 @@ function concat(...parsers) {
 		}
 		return {
 			success: true,
-			next: currentContext,
+			next: withPassThroughFailure(currentContext, consumingFailure),
 			consumed: allConsumed
 		};
 	};
@@ -5365,6 +5547,8 @@ 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))));
 	return fluent(concatParser);
 }
 function group(label, parser, options = {}) {
@@ -5457,6 +5641,9 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	delegateKnownCompletion(groupParser, parser);
+	defineOptionMatch(groupParser, (state, token) => getOptionMatch(parser, state, token));
+	definePassThroughPriority(groupParser, [parser], (state, token) => getPassThroughPriority(parser, state, token));
 	return fluent(groupParser);
 }
 /**
@@ -5611,6 +5798,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 								dependencyRegistry: discriminatorExec.dependencyRegistry
 							} : {}
 						}, "_branch", branchParser.initialState, branchParser, branchParser.usage),
+						...getPassThroughFailureHint(discriminatorResult.next),
 						buffer: discriminatorResult.next.buffer,
 						optionsTerminated: discriminatorResult.next.optionsTerminated
 					});
@@ -5732,6 +5920,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				const discriminatorExec = mergeChildExec(context.exec, discriminatorResult.next.exec);
 				const speculationContext = {
 					...context,
+					...getPassThroughFailureHint(discriminatorResult.next),
 					buffer: discriminatorResult.next.buffer,
 					optionsTerminated: discriminatorResult.next.optionsTerminated,
 					...discriminatorExec != null ? {
@@ -5859,6 +6048,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 								dependencyRegistry: discriminatorExec.dependencyRegistry
 							} : {}
 						}, "_branch", branchParser.initialState, branchParser, branchParser.usage),
+						...getPassThroughFailureHint(discriminatorResult.next),
 						buffer: discriminatorResult.next.buffer,
 						optionsTerminated: discriminatorResult.next.optionsTerminated
 					});
@@ -6426,6 +6616,36 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		}
 	};
 	defineInheritedAnnotationParser(conditionalParser);
+	const reachableBranches = (state) => {
+		if (state.selectedBranch != null) {
+			const branch = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+			return branch == null ? [] : [{
+				branch,
+				state: state.branchState
+			}];
+		}
+		const known = getKnownCompletion(discriminator, state.discriminatorState);
+		if (known != null) {
+			const branch = typeof known.value === "string" ? branches[known.value] : void 0;
+			const reachable = branch ?? defaultBranch;
+			return reachable == null ? [] : [{
+				branch: reachable,
+				state: reachable.initialState
+			}];
+		}
+		return allBranchParsers.map((branch) => ({
+			branch,
+			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))]);
+	});
 	return fluent(conditionalParser);
 }