@optique/core 1.1.4 → 1.1.5

package/dist/constructs.cjs

@@ -78,8 +78,8 @@ function unionLeadingNames(parsers) {
 * Computes `leadingNames` for shared-buffer compositions (`tuple()`,
 * `object()`, `merge()`, `concat()`).
 *
-* Children are processed in descending priority order (matching the
-* round-robin parse loop).  Once a child with `acceptingAnyToken` is
+* Sources are processed in descending priority order (matching the
+* round-robin parse loop).  Once a source with `acceptingAnyToken` is
 * encountered, no lower-priority children can match at position 0, so
 * their names are excluded.
 */
@@ -1948,6 +1948,52 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	const combinedMode = parserKeys.some((k) => parsers[k].mode === "async") ? "async" : "sync";
 	const getInitialError = (context) => createObjectLikeInitialError(context, noMatchContext, options.errors);
+	const adaptFieldLaneResult = (context, field, parser, fieldState, result) => {
+		if (!result.success) return result;
+		if (result.consumed.length === 0 && result.next.state === fieldState) return {
+			success: true,
+			next: context,
+			consumed: []
+		};
+		const mergedExec = require_execution_context.mergeChildExec(context.exec, result.next.exec);
+		const nextState = result.next.state === fieldState ? context.state : {
+			...context.state,
+			[field]: require_annotation_state.getWrappedChildState(context.state, result.next.state, parser)
+		};
+		return {
+			success: true,
+			next: {
+				...context,
+				buffer: result.next.buffer,
+				optionsTerminated: result.next.optionsTerminated,
+				state: nextState,
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: result.consumed
+		};
+	};
+	const objectZeroConsumptionGroup = {};
+	const objectParseLanes = parserPairs.map(([field, parser]) => ({
+		priority: parser.priority,
+		zeroConsumptionGroup: objectZeroConsumptionGroup,
+		settlesZeroConsumption: false,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
+		parse(context) {
+			const fieldState = createFieldStateGetter(context.state, getObjectParseChildState)(field, parser);
+			return require_mode_dispatch.dispatchByMode(combinedMode, () => {
+				const result = parser.parse(withChildContext$1(context, field, fieldState, parser));
+				return adaptFieldLaneResult(context, field, parser, fieldState, result);
+			}, async () => {
+				const result = await parser.parse(withChildContext$1(context, field, fieldState, parser));
+				return adaptFieldLaneResult(context, field, parser, fieldState, result);
+			});
+		}
+	}));
 	const parseSync = (context) => {
 		let error = getInitialError(context);
 		let currentContext = context;
@@ -2466,6 +2512,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		configurable: true,
 		enumerable: false
 	});
+	require_internal_parser.defineParseLanes(objectParser, objectParseLanes);
 	require_internal_parser.defineInheritedAnnotationParser(objectParser);
 	return objectParser;
 }
@@ -3870,7 +3917,140 @@ function merge(...args) {
 			[localObjectStateKey(index)]: result.next.state
 		};
 	};
-	const parseSync = (context) => {
+	const adaptMergeLaneResult = (parser, context, parserState, parsedState, result, index) => {
+		if (!result.success) return result;
+		const mergedExec = require_execution_context.mergeChildExec(context.exec, result.next.exec);
+		const newState = result.next.state === parsedState ? context.state : mergeResultState(parser, context, parserState, result, index);
+		return {
+			success: true,
+			next: {
+				...context,
+				buffer: result.next.buffer,
+				optionsTerminated: result.next.optionsTerminated,
+				state: newState,
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: result.consumed
+		};
+	};
+	const childrenInDeclarationOrder = sorted.map(([parser, originalIndex], sortedIndex) => ({
+		parser,
+		originalIndex,
+		sortedIndex
+	})).toSorted((a, b) => a.originalIndex - b.originalIndex);
+	const mergeParseLanes = childrenInDeclarationOrder.flatMap(({ parser, sortedIndex }) => {
+		const occurrenceConsumptionGroups = /* @__PURE__ */ new WeakMap();
+		const occurrenceZeroConsumptionGroups = /* @__PURE__ */ new WeakMap();
+		const scopeConsumptionGroup = (group$1) => {
+			const existing = occurrenceConsumptionGroups.get(group$1);
+			if (existing != null) return existing;
+			const scoped = {};
+			occurrenceConsumptionGroups.set(group$1, scoped);
+			return scoped;
+		};
+		const childLanes = require_internal_parser.getOwnParseLanes(parser);
+		const lanes = childLanes ?? [{
+			priority: parser.priority,
+			leadingNames: parser.leadingNames,
+			acceptingAnyToken: parser.acceptingAnyToken,
+			parse(context) {
+				return parser.parse(context);
+			}
+		}];
+		return lanes.map((lane) => ({
+			priority: lane.priority,
+			zeroConsumptionGroup: (() => {
+				const group$1 = lane.zeroConsumptionGroup ?? lane;
+				const existing = occurrenceZeroConsumptionGroups.get(group$1);
+				if (existing != null) return existing;
+				const scoped = {};
+				occurrenceZeroConsumptionGroups.set(group$1, scoped);
+				return scoped;
+			})(),
+			settlesZeroConsumption: lane.settlesZeroConsumption,
+			leadingNames: lane.leadingNames,
+			acceptingAnyToken: lane.acceptingAnyToken,
+			requiredConsumptionGroups: lane.requiredConsumptionGroups?.map((group$1) => ({
+				id: scopeConsumptionGroup(group$1.id),
+				...group$1.isActive == null ? {} : { isActive(state) {
+					if (state == null || typeof state !== "object") return false;
+					const parserState = extractParserStateFromState(parser, state, sortedIndex);
+					return group$1.isActive?.(parserState) ?? true;
+				} }
+			})),
+			parse(context) {
+				const parserState = extractParserState(parser, context, sortedIndex);
+				const childContext = withChildContext$1(context, sortedIndex, parserState, parser);
+				return require_mode_dispatch.dispatchByMode(combinedMode, () => {
+					const result = lane.parse(childContext);
+					return adaptMergeLaneResult(parser, context, parserState, childContext.state, result, sortedIndex);
+				}, async () => {
+					const result = await lane.parse(childContext);
+					return adaptMergeLaneResult(parser, context, parserState, childContext.state, result, sortedIndex);
+				});
+			}
+		}));
+	}).toSorted((a, b) => b.priority - a.priority);
+	const settleZeroConsumptionLanes = (context, laneResults) => {
+		const groups = /* @__PURE__ */ new Map();
+		for (const lane of mergeParseLanes) {
+			const group$1 = lane.zeroConsumptionGroup ?? lane;
+			const groupedLanes = groups.get(group$1);
+			if (groupedLanes == null) groups.set(group$1, [lane]);
+			else groupedLanes.push(lane);
+		}
+		const settledGroups = [];
+		for (const groupedLanes of groups.values()) {
+			const groupSucceeded = groupedLanes.every((lane) => {
+				const result = laneResults.get(lane);
+				return lane.settlesZeroConsumption !== false && result?.success === true && result.consumed.length === 0 && (lane.requiredConsumptionGroups?.length ?? 0) === 0;
+			});
+			if (!groupSucceeded) return null;
+			settledGroups.push(groupedLanes);
+		}
+		let settledContext = context;
+		for (const groupedLanes of settledGroups) for (const lane of groupedLanes) {
+			const result = laneResults.get(lane);
+			if (result?.success !== true) continue;
+			const originalState = context.state;
+			const resultState = result.next.state;
+			const nextState = { ...settledContext.state };
+			const stateKeys = new Set([...Reflect.ownKeys(originalState), ...Reflect.ownKeys(resultState)]);
+			for (const key of stateKeys) {
+				const originalHasKey = Object.hasOwn(originalState, key);
+				const resultHasKey = Object.hasOwn(resultState, key);
+				if (originalHasKey === resultHasKey && originalState[key] === resultState[key]) continue;
+				if (resultHasKey) nextState[key] = resultState[key];
+				else delete nextState[key];
+			}
+			const mergedExec = require_execution_context.mergeChildExec(settledContext.exec, result.next.exec);
+			settledContext = {
+				...settledContext,
+				buffer: result.next.buffer,
+				optionsTerminated: result.next.optionsTerminated,
+				state: nextState,
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			};
+		}
+		return {
+			success: true,
+			next: settledContext,
+			consumed: []
+		};
+	};
+	const canTryPositionalLaneAfterFailure = (lane, context) => {
+		const token = context.buffer[0];
+		return token != null && (context.optionsTerminated || !token.startsWith("-")) && (lane.acceptingAnyToken || lane.leadingNames.has(token));
+	};
+	const parseChildrenSync = (context) => {
 		let currentContext = context;
 		let zeroConsumedSuccess = null;
 		for (let i = 0; i < syncParsers.length; i++) {
@@ -3914,7 +4094,7 @@ function merge(...args) {
 			...createObjectLikeInitialError(context, noMatchContext)
 		};
 	};
-	const parseAsync = async (context) => {
+	const parseChildrenAsync = async (context) => {
 		let currentContext = context;
 		let zeroConsumedSuccess = null;
 		for (let i = 0; i < parsers.length; i++) {
@@ -3959,15 +4139,141 @@ function merge(...args) {
 			...createObjectLikeInitialError(context, noMatchContext)
 		};
 	};
+	const parseSync = (context) => {
+		let currentContext = context;
+		let error = createObjectLikeInitialError(context, noMatchContext);
+		const allConsumed = [];
+		const consumedLanes = /* @__PURE__ */ new Set();
+		const consumedGroups = /* @__PURE__ */ new Set();
+		const laneResults = /* @__PURE__ */ new Map();
+		let attemptedLane = false;
+		let madeProgress = true;
+		while (madeProgress && currentContext.buffer.length > 0) {
+			madeProgress = false;
+			let consumingError = null;
+			for (const lane of mergeParseLanes) {
+				if (consumingError != null && lane.priority < consumingError.priority) {
+					if (!canTryPositionalLaneAfterFailure(lane, currentContext)) continue;
+				}
+				attemptedLane = true;
+				const result = lane.parse(currentContext);
+				laneResults.set(lane, result);
+				if (result.success && result.consumed.length > 0) {
+					currentContext = result.next;
+					allConsumed.push(...result.consumed);
+					consumedLanes.add(lane);
+					for (const group$1 of lane.requiredConsumptionGroups ?? []) if (group$1.isActive?.(result.next.state) !== false) consumedGroups.add(group$1.id);
+					madeProgress = true;
+					break;
+				}
+				if (!result.success) {
+					if (result.consumed > 0 && consumingError == null) consumingError = {
+						priority: lane.priority,
+						result
+					};
+					if (error.consumed < result.consumed) error = result;
+				}
+			}
+			if (!madeProgress && consumingError != null && allConsumed.length === 0) return consumingError.result;
+		}
+		if (allConsumed.length === 0) {
+			if (attemptedLane) {
+				const settled = settleZeroConsumptionLanes(context, laneResults);
+				return settled ?? {
+					...error,
+					success: false
+				};
+			}
+			const fallback = parseChildrenSync(context);
+			if (!fallback.success && fallback.consumed < error.consumed) return {
+				...error,
+				success: false
+			};
+			return fallback;
+		}
+		for (const lane of mergeParseLanes) {
+			if (consumedLanes.has(lane) || lane.leadingNames.size > 0 || lane.acceptingAnyToken || lane.requiredConsumptionGroups?.some((group$1) => !consumedGroups.has(group$1.id)) === true) continue;
+			const result = lane.parse(currentContext);
+			if (result.success && result.consumed.length === 0 && result.next.state !== currentContext.state) currentContext = result.next;
+		}
+		return {
+			success: true,
+			next: currentContext,
+			consumed: allConsumed
+		};
+	};
+	const parseAsync = async (context) => {
+		let currentContext = context;
+		let error = createObjectLikeInitialError(context, noMatchContext);
+		const allConsumed = [];
+		const consumedLanes = /* @__PURE__ */ new Set();
+		const consumedGroups = /* @__PURE__ */ new Set();
+		const laneResults = /* @__PURE__ */ new Map();
+		let attemptedLane = false;
+		let madeProgress = true;
+		while (madeProgress && currentContext.buffer.length > 0) {
+			madeProgress = false;
+			let consumingError = null;
+			for (const lane of mergeParseLanes) {
+				if (consumingError != null && lane.priority < consumingError.priority) {
+					if (!canTryPositionalLaneAfterFailure(lane, currentContext)) continue;
+				}
+				attemptedLane = true;
+				const result = await lane.parse(currentContext);
+				laneResults.set(lane, result);
+				if (result.success && result.consumed.length > 0) {
+					currentContext = result.next;
+					allConsumed.push(...result.consumed);
+					consumedLanes.add(lane);
+					for (const group$1 of lane.requiredConsumptionGroups ?? []) if (group$1.isActive?.(result.next.state) !== false) consumedGroups.add(group$1.id);
+					madeProgress = true;
+					break;
+				}
+				if (!result.success) {
+					if (result.consumed > 0 && consumingError == null) consumingError = {
+						priority: lane.priority,
+						result
+					};
+					if (error.consumed < result.consumed) error = result;
+				}
+			}
+			if (!madeProgress && consumingError != null && allConsumed.length === 0) return consumingError.result;
+		}
+		if (allConsumed.length === 0) {
+			if (attemptedLane) {
+				const settled = settleZeroConsumptionLanes(context, laneResults);
+				return settled ?? {
+					...error,
+					success: false
+				};
+			}
+			const fallback = await parseChildrenAsync(context);
+			if (!fallback.success && fallback.consumed < error.consumed) return {
+				...error,
+				success: false
+			};
+			return fallback;
+		}
+		for (const lane of mergeParseLanes) {
+			if (consumedLanes.has(lane) || lane.leadingNames.size > 0 || lane.acceptingAnyToken || lane.requiredConsumptionGroups?.some((group$1) => !consumedGroups.has(group$1.id)) === true) continue;
+			const result = await lane.parse(currentContext);
+			if (result.success && result.consumed.length === 0 && result.next.state !== currentContext.state) currentContext = result.next;
+		}
+		return {
+			success: true,
+			next: currentContext,
+			consumed: allConsumed
+		};
+	};
 	const mergeParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: mergedFieldParsers,
-		priority: Math.max(...parsers.map((p) => p.priority)),
+		priority: Math.max(...mergeParseLanes.map((lane) => lane.priority)),
 		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
-		leadingNames: sharedBufferLeadingNames(parsers),
-		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
+		leadingNames: sharedBufferLeadingNames(mergeParseLanes),
+		acceptingAnyToken: mergeParseLanes.some((lane) => lane.acceptingAnyToken),
 		initialState,
 		canSkip(state, exec) {
 			return parsers.every((parser, index) => {
@@ -4442,6 +4748,7 @@ function merge(...args) {
 			};
 		}
 	};
+	require_internal_parser.defineParseLanes(mergeParser, mergeParseLanes);
 	require_internal_parser.defineInheritedAnnotationParser(mergeParser);
 	return mergeParser;
 }
@@ -5124,6 +5431,7 @@ function group(label, parser, options = {}) {
 			};
 		}
 	};
+	require_internal_parser.defineParseLanes(groupParser, require_internal_parser.getOwnParseLanes(parser));
 	Object.defineProperty(groupParser, require_phase2_seed.extractPhase2SeedKey, {
 		value(state, exec) {
 			return require_phase2_seed.extractPhase2Seed(parser, state, exec);

package/dist/constructs.js

@@ -6,7 +6,7 @@ import { deduplicateDocFragments } from "./doc.js";
 import { dispatchByMode, dispatchIterableByMode } from "./internal/mode-dispatch.js";
 import { createDependencySourceState, dependencyId, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, wrappedDependencySourceMarker } from "./internal/dependency.js";
 import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyRuntimeContext, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync } from "./dependency-runtime.js";
-import { defineInheritedAnnotationParser, getParserSuggestRuntimeNodes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
+import { defineInheritedAnnotationParser, defineParseLanes, getOwnParseLanes, getParserSuggestRuntimeNodes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { annotationViewTargets, getWrappedChildParseState, getWrappedChildState, reconcileObjectChildState, unwrapAnnotationView } from "./annotation-state.js";
 import { allowDuplicateLeadingCommandNamesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
@@ -78,8 +78,8 @@ function unionLeadingNames(parsers) {
 * Computes `leadingNames` for shared-buffer compositions (`tuple()`,
 * `object()`, `merge()`, `concat()`).
 *
-* Children are processed in descending priority order (matching the
-* round-robin parse loop).  Once a child with `acceptingAnyToken` is
+* Sources are processed in descending priority order (matching the
+* round-robin parse loop).  Once a source with `acceptingAnyToken` is
 * encountered, no lower-priority children can match at position 0, so
 * their names are excluded.
 */
@@ -1948,6 +1948,52 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	const combinedMode = parserKeys.some((k) => parsers[k].mode === "async") ? "async" : "sync";
 	const getInitialError = (context) => createObjectLikeInitialError(context, noMatchContext, options.errors);
+	const adaptFieldLaneResult = (context, field, parser, fieldState, result) => {
+		if (!result.success) return result;
+		if (result.consumed.length === 0 && result.next.state === fieldState) return {
+			success: true,
+			next: context,
+			consumed: []
+		};
+		const mergedExec = mergeChildExec(context.exec, result.next.exec);
+		const nextState = result.next.state === fieldState ? context.state : {
+			...context.state,
+			[field]: getWrappedChildState(context.state, result.next.state, parser)
+		};
+		return {
+			success: true,
+			next: {
+				...context,
+				buffer: result.next.buffer,
+				optionsTerminated: result.next.optionsTerminated,
+				state: nextState,
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: result.consumed
+		};
+	};
+	const objectZeroConsumptionGroup = {};
+	const objectParseLanes = parserPairs.map(([field, parser]) => ({
+		priority: parser.priority,
+		zeroConsumptionGroup: objectZeroConsumptionGroup,
+		settlesZeroConsumption: false,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
+		parse(context) {
+			const fieldState = createFieldStateGetter(context.state, getObjectParseChildState)(field, parser);
+			return dispatchByMode(combinedMode, () => {
+				const result = parser.parse(withChildContext$1(context, field, fieldState, parser));
+				return adaptFieldLaneResult(context, field, parser, fieldState, result);
+			}, async () => {
+				const result = await parser.parse(withChildContext$1(context, field, fieldState, parser));
+				return adaptFieldLaneResult(context, field, parser, fieldState, result);
+			});
+		}
+	}));
 	const parseSync = (context) => {
 		let error = getInitialError(context);
 		let currentContext = context;
@@ -2466,6 +2512,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		configurable: true,
 		enumerable: false
 	});
+	defineParseLanes(objectParser, objectParseLanes);
 	defineInheritedAnnotationParser(objectParser);
 	return objectParser;
 }
@@ -3870,7 +3917,140 @@ function merge(...args) {
 			[localObjectStateKey(index)]: result.next.state
 		};
 	};
-	const parseSync = (context) => {
+	const adaptMergeLaneResult = (parser, context, parserState, parsedState, result, index) => {
+		if (!result.success) return result;
+		const mergedExec = mergeChildExec(context.exec, result.next.exec);
+		const newState = result.next.state === parsedState ? context.state : mergeResultState(parser, context, parserState, result, index);
+		return {
+			success: true,
+			next: {
+				...context,
+				buffer: result.next.buffer,
+				optionsTerminated: result.next.optionsTerminated,
+				state: newState,
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			},
+			consumed: result.consumed
+		};
+	};
+	const childrenInDeclarationOrder = sorted.map(([parser, originalIndex], sortedIndex) => ({
+		parser,
+		originalIndex,
+		sortedIndex
+	})).toSorted((a, b) => a.originalIndex - b.originalIndex);
+	const mergeParseLanes = childrenInDeclarationOrder.flatMap(({ parser, sortedIndex }) => {
+		const occurrenceConsumptionGroups = /* @__PURE__ */ new WeakMap();
+		const occurrenceZeroConsumptionGroups = /* @__PURE__ */ new WeakMap();
+		const scopeConsumptionGroup = (group$1) => {
+			const existing = occurrenceConsumptionGroups.get(group$1);
+			if (existing != null) return existing;
+			const scoped = {};
+			occurrenceConsumptionGroups.set(group$1, scoped);
+			return scoped;
+		};
+		const childLanes = getOwnParseLanes(parser);
+		const lanes = childLanes ?? [{
+			priority: parser.priority,
+			leadingNames: parser.leadingNames,
+			acceptingAnyToken: parser.acceptingAnyToken,
+			parse(context) {
+				return parser.parse(context);
+			}
+		}];
+		return lanes.map((lane) => ({
+			priority: lane.priority,
+			zeroConsumptionGroup: (() => {
+				const group$1 = lane.zeroConsumptionGroup ?? lane;
+				const existing = occurrenceZeroConsumptionGroups.get(group$1);
+				if (existing != null) return existing;
+				const scoped = {};
+				occurrenceZeroConsumptionGroups.set(group$1, scoped);
+				return scoped;
+			})(),
+			settlesZeroConsumption: lane.settlesZeroConsumption,
+			leadingNames: lane.leadingNames,
+			acceptingAnyToken: lane.acceptingAnyToken,
+			requiredConsumptionGroups: lane.requiredConsumptionGroups?.map((group$1) => ({
+				id: scopeConsumptionGroup(group$1.id),
+				...group$1.isActive == null ? {} : { isActive(state) {
+					if (state == null || typeof state !== "object") return false;
+					const parserState = extractParserStateFromState(parser, state, sortedIndex);
+					return group$1.isActive?.(parserState) ?? true;
+				} }
+			})),
+			parse(context) {
+				const parserState = extractParserState(parser, context, sortedIndex);
+				const childContext = withChildContext$1(context, sortedIndex, parserState, parser);
+				return dispatchByMode(combinedMode, () => {
+					const result = lane.parse(childContext);
+					return adaptMergeLaneResult(parser, context, parserState, childContext.state, result, sortedIndex);
+				}, async () => {
+					const result = await lane.parse(childContext);
+					return adaptMergeLaneResult(parser, context, parserState, childContext.state, result, sortedIndex);
+				});
+			}
+		}));
+	}).toSorted((a, b) => b.priority - a.priority);
+	const settleZeroConsumptionLanes = (context, laneResults) => {
+		const groups = /* @__PURE__ */ new Map();
+		for (const lane of mergeParseLanes) {
+			const group$1 = lane.zeroConsumptionGroup ?? lane;
+			const groupedLanes = groups.get(group$1);
+			if (groupedLanes == null) groups.set(group$1, [lane]);
+			else groupedLanes.push(lane);
+		}
+		const settledGroups = [];
+		for (const groupedLanes of groups.values()) {
+			const groupSucceeded = groupedLanes.every((lane) => {
+				const result = laneResults.get(lane);
+				return lane.settlesZeroConsumption !== false && result?.success === true && result.consumed.length === 0 && (lane.requiredConsumptionGroups?.length ?? 0) === 0;
+			});
+			if (!groupSucceeded) return null;
+			settledGroups.push(groupedLanes);
+		}
+		let settledContext = context;
+		for (const groupedLanes of settledGroups) for (const lane of groupedLanes) {
+			const result = laneResults.get(lane);
+			if (result?.success !== true) continue;
+			const originalState = context.state;
+			const resultState = result.next.state;
+			const nextState = { ...settledContext.state };
+			const stateKeys = new Set([...Reflect.ownKeys(originalState), ...Reflect.ownKeys(resultState)]);
+			for (const key of stateKeys) {
+				const originalHasKey = Object.hasOwn(originalState, key);
+				const resultHasKey = Object.hasOwn(resultState, key);
+				if (originalHasKey === resultHasKey && originalState[key] === resultState[key]) continue;
+				if (resultHasKey) nextState[key] = resultState[key];
+				else delete nextState[key];
+			}
+			const mergedExec = mergeChildExec(settledContext.exec, result.next.exec);
+			settledContext = {
+				...settledContext,
+				buffer: result.next.buffer,
+				optionsTerminated: result.next.optionsTerminated,
+				state: nextState,
+				...mergedExec != null ? {
+					trace: mergedExec.trace,
+					exec: mergedExec,
+					dependencyRegistry: mergedExec.dependencyRegistry
+				} : {}
+			};
+		}
+		return {
+			success: true,
+			next: settledContext,
+			consumed: []
+		};
+	};
+	const canTryPositionalLaneAfterFailure = (lane, context) => {
+		const token = context.buffer[0];
+		return token != null && (context.optionsTerminated || !token.startsWith("-")) && (lane.acceptingAnyToken || lane.leadingNames.has(token));
+	};
+	const parseChildrenSync = (context) => {
 		let currentContext = context;
 		let zeroConsumedSuccess = null;
 		for (let i = 0; i < syncParsers.length; i++) {
@@ -3914,7 +4094,7 @@ function merge(...args) {
 			...createObjectLikeInitialError(context, noMatchContext)
 		};
 	};
-	const parseAsync = async (context) => {
+	const parseChildrenAsync = async (context) => {
 		let currentContext = context;
 		let zeroConsumedSuccess = null;
 		for (let i = 0; i < parsers.length; i++) {
@@ -3959,15 +4139,141 @@ function merge(...args) {
 			...createObjectLikeInitialError(context, noMatchContext)
 		};
 	};
+	const parseSync = (context) => {
+		let currentContext = context;
+		let error = createObjectLikeInitialError(context, noMatchContext);
+		const allConsumed = [];
+		const consumedLanes = /* @__PURE__ */ new Set();
+		const consumedGroups = /* @__PURE__ */ new Set();
+		const laneResults = /* @__PURE__ */ new Map();
+		let attemptedLane = false;
+		let madeProgress = true;
+		while (madeProgress && currentContext.buffer.length > 0) {
+			madeProgress = false;
+			let consumingError = null;
+			for (const lane of mergeParseLanes) {
+				if (consumingError != null && lane.priority < consumingError.priority) {
+					if (!canTryPositionalLaneAfterFailure(lane, currentContext)) continue;
+				}
+				attemptedLane = true;
+				const result = lane.parse(currentContext);
+				laneResults.set(lane, result);
+				if (result.success && result.consumed.length > 0) {
+					currentContext = result.next;
+					allConsumed.push(...result.consumed);
+					consumedLanes.add(lane);
+					for (const group$1 of lane.requiredConsumptionGroups ?? []) if (group$1.isActive?.(result.next.state) !== false) consumedGroups.add(group$1.id);
+					madeProgress = true;
+					break;
+				}
+				if (!result.success) {
+					if (result.consumed > 0 && consumingError == null) consumingError = {
+						priority: lane.priority,
+						result
+					};
+					if (error.consumed < result.consumed) error = result;
+				}
+			}
+			if (!madeProgress && consumingError != null && allConsumed.length === 0) return consumingError.result;
+		}
+		if (allConsumed.length === 0) {
+			if (attemptedLane) {
+				const settled = settleZeroConsumptionLanes(context, laneResults);
+				return settled ?? {
+					...error,
+					success: false
+				};
+			}
+			const fallback = parseChildrenSync(context);
+			if (!fallback.success && fallback.consumed < error.consumed) return {
+				...error,
+				success: false
+			};
+			return fallback;
+		}
+		for (const lane of mergeParseLanes) {
+			if (consumedLanes.has(lane) || lane.leadingNames.size > 0 || lane.acceptingAnyToken || lane.requiredConsumptionGroups?.some((group$1) => !consumedGroups.has(group$1.id)) === true) continue;
+			const result = lane.parse(currentContext);
+			if (result.success && result.consumed.length === 0 && result.next.state !== currentContext.state) currentContext = result.next;
+		}
+		return {
+			success: true,
+			next: currentContext,
+			consumed: allConsumed
+		};
+	};
+	const parseAsync = async (context) => {
+		let currentContext = context;
+		let error = createObjectLikeInitialError(context, noMatchContext);
+		const allConsumed = [];
+		const consumedLanes = /* @__PURE__ */ new Set();
+		const consumedGroups = /* @__PURE__ */ new Set();
+		const laneResults = /* @__PURE__ */ new Map();
+		let attemptedLane = false;
+		let madeProgress = true;
+		while (madeProgress && currentContext.buffer.length > 0) {
+			madeProgress = false;
+			let consumingError = null;
+			for (const lane of mergeParseLanes) {
+				if (consumingError != null && lane.priority < consumingError.priority) {
+					if (!canTryPositionalLaneAfterFailure(lane, currentContext)) continue;
+				}
+				attemptedLane = true;
+				const result = await lane.parse(currentContext);
+				laneResults.set(lane, result);
+				if (result.success && result.consumed.length > 0) {
+					currentContext = result.next;
+					allConsumed.push(...result.consumed);
+					consumedLanes.add(lane);
+					for (const group$1 of lane.requiredConsumptionGroups ?? []) if (group$1.isActive?.(result.next.state) !== false) consumedGroups.add(group$1.id);
+					madeProgress = true;
+					break;
+				}
+				if (!result.success) {
+					if (result.consumed > 0 && consumingError == null) consumingError = {
+						priority: lane.priority,
+						result
+					};
+					if (error.consumed < result.consumed) error = result;
+				}
+			}
+			if (!madeProgress && consumingError != null && allConsumed.length === 0) return consumingError.result;
+		}
+		if (allConsumed.length === 0) {
+			if (attemptedLane) {
+				const settled = settleZeroConsumptionLanes(context, laneResults);
+				return settled ?? {
+					...error,
+					success: false
+				};
+			}
+			const fallback = await parseChildrenAsync(context);
+			if (!fallback.success && fallback.consumed < error.consumed) return {
+				...error,
+				success: false
+			};
+			return fallback;
+		}
+		for (const lane of mergeParseLanes) {
+			if (consumedLanes.has(lane) || lane.leadingNames.size > 0 || lane.acceptingAnyToken || lane.requiredConsumptionGroups?.some((group$1) => !consumedGroups.has(group$1.id)) === true) continue;
+			const result = await lane.parse(currentContext);
+			if (result.success && result.consumed.length === 0 && result.next.state !== currentContext.state) currentContext = result.next;
+		}
+		return {
+			success: true,
+			next: currentContext,
+			consumed: allConsumed
+		};
+	};
 	const mergeParser = {
 		mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: mergedFieldParsers,
-		priority: Math.max(...parsers.map((p) => p.priority)),
+		priority: Math.max(...mergeParseLanes.map((lane) => lane.priority)),
 		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
-		leadingNames: sharedBufferLeadingNames(parsers),
-		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
+		leadingNames: sharedBufferLeadingNames(mergeParseLanes),
+		acceptingAnyToken: mergeParseLanes.some((lane) => lane.acceptingAnyToken),
 		initialState,
 		canSkip(state, exec) {
 			return parsers.every((parser, index) => {
@@ -4442,6 +4748,7 @@ function merge(...args) {
 			};
 		}
 	};
+	defineParseLanes(mergeParser, mergeParseLanes);
 	defineInheritedAnnotationParser(mergeParser);
 	return mergeParser;
 }
@@ -5124,6 +5431,7 @@ function group(label, parser, options = {}) {
 			};
 		}
 	};
+	defineParseLanes(groupParser, getOwnParseLanes(parser));
 	Object.defineProperty(groupParser, extractPhase2SeedKey, {
 		value(state, exec) {
 			return extractPhase2Seed(parser, state, exec);

package/dist/internal/parser.cjs

@@ -8,6 +8,12 @@ const require_input_trace = require('../input-trace.cjs');
 
 //#region src/internal/parser.ts
 /**
+* Internal symbol used by transparent combinators to expose independently
+* competing parse operations to shared-buffer parents.
+* @internal
+*/
+const parseLanesKey = Symbol("parseLanes");
+/**
 * Internal marker for wrappers whose `{ hasCliValue: false }` states should
 * be treated as unmatched dependency-source states during completion-time
 * Phase 1.
@@ -387,6 +393,32 @@ function composeWrappedSourceMetadata(dependencyMetadata, wrapSource) {
 	};
 }
 /**
+* Defines internal parse-lane metadata without exposing it through object
+* spreads used by custom parser wrappers.
+*
+* @internal
+*/
+function defineParseLanes(parser, lanes) {
+	if (lanes == null) return;
+	Object.defineProperty(parser, parseLanesKey, {
+		value: lanes,
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Gets parse-lane metadata defined directly on a parser.
+*
+* Inherited metadata belongs to the parser's prototype and must not bypass an
+* overriding `parse()` implementation on a custom wrapper.
+*
+* @internal
+*/
+function getOwnParseLanes(parser) {
+	if (!Object.hasOwn(parser, parseLanesKey)) return void 0;
+	return parser[parseLanesKey];
+}
+/**
 * Marks a parser as inheriting parent-state annotations through wrapper-state
 * reconstruction.
 *
@@ -797,15 +829,18 @@ exports.annotationWrapperRequiresSourceBindingKey = annotationWrapperRequiresSou
 exports.composeWrappedSourceMetadata = composeWrappedSourceMetadata;
 exports.createParserContext = createParserContext;
 exports.defineInheritedAnnotationParser = defineInheritedAnnotationParser;
+exports.defineParseLanes = defineParseLanes;
 exports.defineSourceBindingOnlyAnnotationCompletionParser = defineSourceBindingOnlyAnnotationCompletionParser;
 exports.getDelegatingSuggestRuntimeNodes = getDelegatingSuggestRuntimeNodes;
 exports.getDocPage = getDocPage;
 exports.getDocPageAsync = getDocPageAsync;
 exports.getDocPageSync = getDocPageSync;
+exports.getOwnParseLanes = getOwnParseLanes;
 exports.getParserSuggestRuntimeNodes = getParserSuggestRuntimeNodes;
 exports.inheritParentAnnotationsKey = inheritParentAnnotationsKey;
 exports.parse = parse;
 exports.parseAsync = parseAsync;
+exports.parseLanesKey = parseLanesKey;
 exports.parseSync = parseSync;
 exports.suggest = suggest;
 exports.suggestAsync = suggestAsync;

package/dist/internal/parser.d.cts

@@ -42,6 +42,51 @@ type ModeValue<M extends Mode, T> = M extends "async" ? Promise<T> : T;
  * @since 0.9.0
  */
 type ModeIterable<M extends Mode, T> = M extends "async" ? AsyncIterable<T> : Iterable<T>;
+/**
+ * Internal symbol used by transparent combinators to expose independently
+ * competing parse operations to shared-buffer parents.
+ * @internal
+ */
+declare const parseLanesKey: unique symbol;
+/**
+ * An owner-consumption requirement for a parse lane.
+ * @internal
+ */
+interface ParseLaneConsumptionGroup {
+  /** Identity shared by lanes belonging to the same owning parser. */
+  readonly id: object;
+  /** Whether the owning parser is active after a consuming lane succeeds. */
+  readonly isActive?: (state: unknown) => boolean;
+}
+/**
+ * A state-preserving parse operation that competes at one exact priority.
+ * @internal
+ */
+interface ParseLane<TState> {
+  /** The exact priority at which this lane competes. */
+  readonly priority: number;
+  /**
+   * Identity shared by lanes that must all succeed before their
+   * zero-consumption state updates can be committed.
+   */
+  readonly zeroConsumptionGroup?: object;
+  /**
+   * Whether a zero-consumption success can settle the owning parser while
+   * input remains.  Defaults to `true`.
+   */
+  readonly settlesZeroConsumption?: boolean;
+  /** Fixed tokens reachable through this lane. */
+  readonly leadingNames: ReadonlySet<string>;
+  /** Whether this lane accepts any positional token. */
+  readonly acceptingAnyToken: boolean;
+  /**
+   * Groups in which a zero-consumption update is valid only after another
+   * lane in every group has consumed input during the same arbitration.
+   */
+  readonly requiredConsumptionGroups?: readonly ParseLaneConsumptionGroup[];
+  /** Parses through the owning parser's state and execution context. */
+  parse(context: ParserContext<TState>): ParserResult<TState> | Promise<ParserResult<TState>>;
+}
 /**
  * Combines multiple modes into a single mode.
  * If any mode is `"async"`, the result is `"async"`; otherwise `"sync"`.
@@ -162,6 +207,13 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * state when parsing starts.
    */
   readonly initialState: TState;
+  /**
+   * Independently competing parse operations exposed by transparent
+   * combinators.  Shared-buffer parents use these to arbitrate below an
+   * aggregate parser boundary without bypassing the owner's state adapters.
+   * @internal
+   */
+  readonly [parseLanesKey]?: readonly ParseLane<TState>[];
   /**
    * Internal marker for wrappers whose `{ hasCliValue: false }` states should
    * be treated as unmatched dependency-source states during completion-time
@@ -851,6 +903,22 @@ declare function getDelegatingSuggestRuntimeNodes<TInnerState>(innerParser: Pars
  * @internal
  */
 declare function composeWrappedSourceMetadata(dependencyMetadata: ParserDependencyMetadata | undefined, wrapSource: (source: NonNullable<ParserDependencyMetadata["source"]>) => NonNullable<ParserDependencyMetadata["source"]>): ParserDependencyMetadata | undefined;
+/**
+ * Defines internal parse-lane metadata without exposing it through object
+ * spreads used by custom parser wrappers.
+ *
+ * @internal
+ */
+declare function defineParseLanes<TState>(parser: object, lanes: readonly ParseLane<TState>[] | undefined): void;
+/**
+ * Gets parse-lane metadata defined directly on a parser.
+ *
+ * Inherited metadata belongs to the parser's prototype and must not bypass an
+ * overriding `parse()` implementation on a custom wrapper.
+ *
+ * @internal
+ */
+declare function getOwnParseLanes<TState>(parser: object): readonly ParseLane<TState>[] | undefined;
 /**
  * Marks a parser as inheriting parent-state annotations through wrapper-state
  * reconstruction.
@@ -999,4 +1067,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };
+export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, ParseLane, ParseLaneConsumptionGroup, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };

package/dist/internal/parser.d.ts

@@ -42,6 +42,51 @@ type ModeValue<M extends Mode, T> = M extends "async" ? Promise<T> : T;
  * @since 0.9.0
  */
 type ModeIterable<M extends Mode, T> = M extends "async" ? AsyncIterable<T> : Iterable<T>;
+/**
+ * Internal symbol used by transparent combinators to expose independently
+ * competing parse operations to shared-buffer parents.
+ * @internal
+ */
+declare const parseLanesKey: unique symbol;
+/**
+ * An owner-consumption requirement for a parse lane.
+ * @internal
+ */
+interface ParseLaneConsumptionGroup {
+  /** Identity shared by lanes belonging to the same owning parser. */
+  readonly id: object;
+  /** Whether the owning parser is active after a consuming lane succeeds. */
+  readonly isActive?: (state: unknown) => boolean;
+}
+/**
+ * A state-preserving parse operation that competes at one exact priority.
+ * @internal
+ */
+interface ParseLane<TState> {
+  /** The exact priority at which this lane competes. */
+  readonly priority: number;
+  /**
+   * Identity shared by lanes that must all succeed before their
+   * zero-consumption state updates can be committed.
+   */
+  readonly zeroConsumptionGroup?: object;
+  /**
+   * Whether a zero-consumption success can settle the owning parser while
+   * input remains.  Defaults to `true`.
+   */
+  readonly settlesZeroConsumption?: boolean;
+  /** Fixed tokens reachable through this lane. */
+  readonly leadingNames: ReadonlySet<string>;
+  /** Whether this lane accepts any positional token. */
+  readonly acceptingAnyToken: boolean;
+  /**
+   * Groups in which a zero-consumption update is valid only after another
+   * lane in every group has consumed input during the same arbitration.
+   */
+  readonly requiredConsumptionGroups?: readonly ParseLaneConsumptionGroup[];
+  /** Parses through the owning parser's state and execution context. */
+  parse(context: ParserContext<TState>): ParserResult<TState> | Promise<ParserResult<TState>>;
+}
 /**
  * Combines multiple modes into a single mode.
  * If any mode is `"async"`, the result is `"async"`; otherwise `"sync"`.
@@ -162,6 +207,13 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * state when parsing starts.
    */
   readonly initialState: TState;
+  /**
+   * Independently competing parse operations exposed by transparent
+   * combinators.  Shared-buffer parents use these to arbitrate below an
+   * aggregate parser boundary without bypassing the owner's state adapters.
+   * @internal
+   */
+  readonly [parseLanesKey]?: readonly ParseLane<TState>[];
   /**
    * Internal marker for wrappers whose `{ hasCliValue: false }` states should
    * be treated as unmatched dependency-source states during completion-time
@@ -851,6 +903,22 @@ declare function getDelegatingSuggestRuntimeNodes<TInnerState>(innerParser: Pars
  * @internal
  */
 declare function composeWrappedSourceMetadata(dependencyMetadata: ParserDependencyMetadata | undefined, wrapSource: (source: NonNullable<ParserDependencyMetadata["source"]>) => NonNullable<ParserDependencyMetadata["source"]>): ParserDependencyMetadata | undefined;
+/**
+ * Defines internal parse-lane metadata without exposing it through object
+ * spreads used by custom parser wrappers.
+ *
+ * @internal
+ */
+declare function defineParseLanes<TState>(parser: object, lanes: readonly ParseLane<TState>[] | undefined): void;
+/**
+ * Gets parse-lane metadata defined directly on a parser.
+ *
+ * Inherited metadata belongs to the parser's prototype and must not bypass an
+ * overriding `parse()` implementation on a custom wrapper.
+ *
+ * @internal
+ */
+declare function getOwnParseLanes<TState>(parser: object): readonly ParseLane<TState>[] | undefined;
 /**
  * Marks a parser as inheriting parent-state annotations through wrapper-state
  * reconstruction.
@@ -999,4 +1067,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };
+export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, ParseLane, ParseLaneConsumptionGroup, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };

package/dist/internal/parser.js

@@ -8,6 +8,12 @@ import { createInputTrace } from "../input-trace.js";
 
 //#region src/internal/parser.ts
 /**
+* Internal symbol used by transparent combinators to expose independently
+* competing parse operations to shared-buffer parents.
+* @internal
+*/
+const parseLanesKey = Symbol("parseLanes");
+/**
 * Internal marker for wrappers whose `{ hasCliValue: false }` states should
 * be treated as unmatched dependency-source states during completion-time
 * Phase 1.
@@ -387,6 +393,32 @@ function composeWrappedSourceMetadata(dependencyMetadata, wrapSource) {
 	};
 }
 /**
+* Defines internal parse-lane metadata without exposing it through object
+* spreads used by custom parser wrappers.
+*
+* @internal
+*/
+function defineParseLanes(parser, lanes) {
+	if (lanes == null) return;
+	Object.defineProperty(parser, parseLanesKey, {
+		value: lanes,
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Gets parse-lane metadata defined directly on a parser.
+*
+* Inherited metadata belongs to the parser's prototype and must not bypass an
+* overriding `parse()` implementation on a custom wrapper.
+*
+* @internal
+*/
+function getOwnParseLanes(parser) {
+	if (!Object.hasOwn(parser, parseLanesKey)) return void 0;
+	return parser[parseLanesKey];
+}
+/**
 * Marks a parser as inheriting parent-state annotations through wrapper-state
 * reconstruction.
 *
@@ -793,4 +825,4 @@ function buildDocPage(parser, context, args, matchedCommandArgIndices) {
 }
 
 //#endregion
-export { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };
+export { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };

package/dist/modifiers.cjs

@@ -231,6 +231,44 @@ function processOptionalStyleResult(result, innerState, context) {
 	};
 	return result;
 }
+function adaptOptionalStyleParseLanes(parser) {
+	const lanes = require_internal_parser.getOwnParseLanes(parser);
+	if (lanes == null) return void 0;
+	const consumptionGroup = {};
+	return lanes.map((lane) => ({
+		priority: lane.priority,
+		zeroConsumptionGroup: lane.zeroConsumptionGroup,
+		settlesZeroConsumption: lane.settlesZeroConsumption,
+		leadingNames: lane.leadingNames,
+		acceptingAnyToken: false,
+		requiredConsumptionGroups: [...lane.requiredConsumptionGroups?.map((group) => ({
+			id: group.id,
+			...group.isActive == null ? {} : { isActive(state) {
+				const innerState = Array.isArray(state) ? state[0] : parser.initialState;
+				return group.isActive?.(innerState) ?? true;
+			} }
+		})) ?? [], {
+			id: consumptionGroup,
+			isActive(state) {
+				return Array.isArray(state);
+			}
+		}],
+		parse(context) {
+			const innerState = deriveOptionalInnerParseState(context.state, parser);
+			const innerContext = {
+				...context,
+				state: innerState
+			};
+			return require_mode_dispatch.dispatchByMode(parser.mode, () => {
+				const result = lane.parse(innerContext);
+				return processOptionalStyleResult(result, innerState, context);
+			}, async () => {
+				const result = await lane.parse(innerContext);
+				return processOptionalStyleResult(result, innerState, context);
+			});
+		}
+	}));
+}
 /**
 * Creates a `shouldDeferCompletion` adapter that unwraps the outer state
 * shape (`[TState] | undefined`) used by {@link optional} and
@@ -420,6 +458,7 @@ function optional(parser) {
 		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
 	}
+	require_internal_parser.defineParseLanes(optionalParser, adaptOptionalStyleParseLanes(parser));
 	require_internal_parser.defineInheritedAnnotationParser(optionalParser);
 	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
 	return optionalParser;
@@ -654,6 +693,7 @@ function withDefault(parser, defaultValue, options) {
 		} });
 		if (composed != null) withDefaultParser.dependencyMetadata = composed;
 	}
+	require_internal_parser.defineParseLanes(withDefaultParser, adaptOptionalStyleParseLanes(parser));
 	require_internal_parser.defineInheritedAnnotationParser(withDefaultParser);
 	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
 	return withDefaultParser;
@@ -793,6 +833,7 @@ function map(parser, transform) {
 			return parser.getDocFragments(state, void 0);
 		}
 	};
+	require_internal_parser.defineParseLanes(mappedParser, require_internal_parser.getOwnParseLanes(parser));
 	delete mappedParser.normalizeValue;
 	delete mappedParser.validateValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
@@ -1509,6 +1550,7 @@ function multiple(parser, options = {}) {
 function nonEmpty(parser) {
 	const syncParser = parser;
 	const initialState = parser.initialState;
+	const consumptionGroup = {};
 	const processNonEmptyResult = (result) => {
 		if (!result.success) return result;
 		if (result.consumed.length === 0) return {
@@ -1561,6 +1603,17 @@ function nonEmpty(parser) {
 			return syncParser.getDocFragments(state, defaultValue);
 		}
 	};
+	require_internal_parser.defineParseLanes(nonEmptyParser, require_internal_parser.getOwnParseLanes(parser)?.map((lane) => ({
+		priority: lane.priority,
+		zeroConsumptionGroup: lane.zeroConsumptionGroup,
+		settlesZeroConsumption: lane.settlesZeroConsumption,
+		leadingNames: lane.leadingNames,
+		acceptingAnyToken: lane.acceptingAnyToken,
+		requiredConsumptionGroups: [...lane.requiredConsumptionGroups ?? [], { id: consumptionGroup }],
+		parse(context) {
+			return lane.parse(context);
+		}
+	})));
 	if ("placeholder" in parser) Object.defineProperty(nonEmptyParser, "placeholder", {
 		get() {
 			return parser.placeholder;

package/dist/modifiers.js

@@ -1,7 +1,7 @@
 import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { formatMessage, message, text } from "./message.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
-import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
+import { defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getOwnParseLanes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
@@ -231,6 +231,44 @@ function processOptionalStyleResult(result, innerState, context) {
 	};
 	return result;
 }
+function adaptOptionalStyleParseLanes(parser) {
+	const lanes = getOwnParseLanes(parser);
+	if (lanes == null) return void 0;
+	const consumptionGroup = {};
+	return lanes.map((lane) => ({
+		priority: lane.priority,
+		zeroConsumptionGroup: lane.zeroConsumptionGroup,
+		settlesZeroConsumption: lane.settlesZeroConsumption,
+		leadingNames: lane.leadingNames,
+		acceptingAnyToken: false,
+		requiredConsumptionGroups: [...lane.requiredConsumptionGroups?.map((group) => ({
+			id: group.id,
+			...group.isActive == null ? {} : { isActive(state) {
+				const innerState = Array.isArray(state) ? state[0] : parser.initialState;
+				return group.isActive?.(innerState) ?? true;
+			} }
+		})) ?? [], {
+			id: consumptionGroup,
+			isActive(state) {
+				return Array.isArray(state);
+			}
+		}],
+		parse(context) {
+			const innerState = deriveOptionalInnerParseState(context.state, parser);
+			const innerContext = {
+				...context,
+				state: innerState
+			};
+			return dispatchByMode(parser.mode, () => {
+				const result = lane.parse(innerContext);
+				return processOptionalStyleResult(result, innerState, context);
+			}, async () => {
+				const result = await lane.parse(innerContext);
+				return processOptionalStyleResult(result, innerState, context);
+			});
+		}
+	}));
+}
 /**
 * Creates a `shouldDeferCompletion` adapter that unwraps the outer state
 * shape (`[TState] | undefined`) used by {@link optional} and
@@ -420,6 +458,7 @@ function optional(parser) {
 		const composed = composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
 	}
+	defineParseLanes(optionalParser, adaptOptionalStyleParseLanes(parser));
 	defineInheritedAnnotationParser(optionalParser);
 	defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
 	return optionalParser;
@@ -654,6 +693,7 @@ function withDefault(parser, defaultValue, options) {
 		} });
 		if (composed != null) withDefaultParser.dependencyMetadata = composed;
 	}
+	defineParseLanes(withDefaultParser, adaptOptionalStyleParseLanes(parser));
 	defineInheritedAnnotationParser(withDefaultParser);
 	defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
 	return withDefaultParser;
@@ -793,6 +833,7 @@ function map(parser, transform) {
 			return parser.getDocFragments(state, void 0);
 		}
 	};
+	defineParseLanes(mappedParser, getOwnParseLanes(parser));
 	delete mappedParser.normalizeValue;
 	delete mappedParser.validateValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
@@ -1509,6 +1550,7 @@ function multiple(parser, options = {}) {
 function nonEmpty(parser) {
 	const syncParser = parser;
 	const initialState = parser.initialState;
+	const consumptionGroup = {};
 	const processNonEmptyResult = (result) => {
 		if (!result.success) return result;
 		if (result.consumed.length === 0) return {
@@ -1561,6 +1603,17 @@ function nonEmpty(parser) {
 			return syncParser.getDocFragments(state, defaultValue);
 		}
 	};
+	defineParseLanes(nonEmptyParser, getOwnParseLanes(parser)?.map((lane) => ({
+		priority: lane.priority,
+		zeroConsumptionGroup: lane.zeroConsumptionGroup,
+		settlesZeroConsumption: lane.settlesZeroConsumption,
+		leadingNames: lane.leadingNames,
+		acceptingAnyToken: lane.acceptingAnyToken,
+		requiredConsumptionGroups: [...lane.requiredConsumptionGroups ?? [], { id: consumptionGroup }],
+		parse(context) {
+			return lane.parse(context);
+		}
+	})));
 	if ("placeholder" in parser) Object.defineProperty(nonEmptyParser, "placeholder", {
 		get() {
 			return parser.placeholder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -196,11 +196,11 @@
   },
   "sideEffects": false,
   "devDependencies": {
+    "@optique/env": "1.1.5",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
-    "typescript": "^5.8.3",
-    "@optique/env": "1.1.4"
+    "typescript": "^5.8.3"
   },
   "scripts": {
     "build": "tsdown",