@optique/core 1.0.0-dev.1711 → 1.0.0-dev.1712

package/dist/constructs.cjs

@@ -712,9 +712,23 @@ function or(...args) {
 		orderedParsers.sort(([_, a], [__, b]) => activeState?.[0] === a ? -1 : activeState?.[0] === b ? 1 : a - b);
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
+		let provisionalConsuming = null;
+		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const result = parser.parse(withChildContext(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			if (result.success && result.consumed.length > 0) {
+				if (result.provisional) {
+					if (provisionalConsuming == null && !provisionalAmbiguous) provisionalConsuming = {
+						index: i,
+						parser,
+						result
+					};
+					else {
+						provisionalConsuming = null;
+						provisionalAmbiguous = true;
+					}
+					continue;
+				}
 				if (activeState?.[0] !== i && activeState?.[1].success) {
 					if (activeState[1].consumed.length === 0) {
 						const mergedExec$2 = mergeChildExec(context.exec, result.next.exec);
@@ -812,6 +826,24 @@ function or(...args) {
 				consumed: []
 			};
 		}
+		if (provisionalConsuming !== null && !(activeState != null && activeState[1].success && activeState[1].consumed.length > 0 && activeState[0] !== provisionalConsuming.index)) {
+			const mergedExec = mergeChildExec(context.exec, provisionalConsuming.result.next.exec);
+			return {
+				success: true,
+				provisional: true,
+				next: {
+					...context,
+					buffer: provisionalConsuming.result.next.buffer,
+					optionsTerminated: provisionalConsuming.result.next.optionsTerminated,
+					state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, provisionalConsuming.result),
+					...mergedExec != null ? {
+						exec: mergedExec,
+						dependencyRegistry: mergedExec.dependencyRegistry
+					} : {}
+				},
+				consumed: provisionalConsuming.result.consumed
+			};
+		}
 		return {
 			...error,
 			success: false
@@ -824,10 +856,24 @@ function or(...args) {
 		orderedParsers.sort(([_, a], [__, b]) => activeState?.[0] === a ? -1 : activeState?.[0] === b ? 1 : a - b);
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
+		let provisionalConsuming = null;
+		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const resultOrPromise = parser.parse(withChildContext(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			const result = await resultOrPromise;
 			if (result.success && result.consumed.length > 0) {
+				if (result.provisional) {
+					if (provisionalConsuming == null && !provisionalAmbiguous) provisionalConsuming = {
+						index: i,
+						parser,
+						result
+					};
+					else {
+						provisionalConsuming = null;
+						provisionalAmbiguous = true;
+					}
+					continue;
+				}
 				if (activeState?.[0] !== i && activeState?.[1].success) {
 					if (activeState[1].consumed.length === 0) {
 						const mergedExec$2 = mergeChildExec(context.exec, result.next.exec);
@@ -927,6 +973,24 @@ function or(...args) {
 				consumed: []
 			};
 		}
+		if (provisionalConsuming !== null && !(activeState != null && activeState[1].success && activeState[1].consumed.length > 0 && activeState[0] !== provisionalConsuming.index)) {
+			const mergedExec = mergeChildExec(context.exec, provisionalConsuming.result.next.exec);
+			return {
+				success: true,
+				provisional: true,
+				next: {
+					...context,
+					buffer: provisionalConsuming.result.next.buffer,
+					optionsTerminated: provisionalConsuming.result.next.optionsTerminated,
+					state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, provisionalConsuming.result),
+					...mergedExec != null ? {
+						exec: mergedExec,
+						dependencyRegistry: mergedExec.dependencyRegistry
+					} : {}
+				},
+				consumed: provisionalConsuming.result.consumed
+			};
+		}
 		return {
 			...error,
 			success: false
@@ -1020,7 +1084,8 @@ function longestMatch(...args) {
 			const result = parser.parse(withChildContext(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
-				if (bestMatch === null || consumed > bestMatch.consumed) bestMatch = {
+				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
+				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
 					parser,
 					result,
@@ -1060,7 +1125,8 @@ function longestMatch(...args) {
 			const result = await resultOrPromise;
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
-				if (bestMatch === null || consumed > bestMatch.consumed) bestMatch = {
+				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
+				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
 					parser,
 					result,
@@ -3656,18 +3722,35 @@ function group(label, parser, options = {}) {
 * // defaultResult.value = [undefined, {}]
 * ```
 *
-* ### Async discriminator limitation
+* ### Speculative branch parsing
 *
 * When the discriminator is an async parser that succeeds without consuming
 * input (e.g., `prompt(option(...))` with no CLI input), branch selection
-* is deferred to the complete phase.  If the selected branch needs to
-* consume remaining tokens, those tokens cannot be consumed because the
-* branch is not known during parse.  In practice, this means
-* `conditional(prompt(option(...)), { key: option(...) })` cannot parse
-* branch-specific tokens when the discriminator requires interactive
-* resolution.  Provide a default branch or ensure the discriminator
-* can resolve synchronously (e.g., via `bindEnv()` or `withDefault()`)
-* to avoid this limitation.
+* is normally deferred to the complete phase.  To allow branch-specific
+* tokens to be consumed, `conditional()` speculatively tries all named
+* branches during parse.  If exactly one branch can consume tokens, it is
+* tentatively selected and verified against the resolved discriminator
+* during the complete phase.
+*
+* If the discriminator resolves to a different branch than the one that
+* consumed tokens (contradictory input), the parse fails.  When multiple
+* branches can consume the same tokens (ambiguous), speculation is skipped
+* entirely to keep branch selection order-independent.
+*
+* #### Known limitations
+*
+* - When a default branch accepts the same tokens as a named branch,
+*   speculation prefers the named branch.  If the discriminator later
+*   resolves to a value not in the named branches, the parse fails
+*   instead of falling back to the default branch.  To avoid this,
+*   ensure named branch options are distinct from the default branch.
+* - Within `longestMatch()`, a longer speculative match can beat a
+*   shorter definitive one.  If the speculative match fails during
+*   completion, the tokens consumed by it are not recoverable.
+* - The dependency runtime seeds both discriminator and branch sources
+*   before verifying the speculative selection.  A discriminator that
+*   depends on branch-local dependency sources could be circularly
+*   confirmed by the speculative branch.
 *
 * @since 0.8.0
 */
@@ -3880,6 +3963,76 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		const discriminatorResult = await discriminator.parse({ ...withChildContext(context, "_discriminator", state.discriminatorState, discriminator) });
 		if (discriminatorResult.success) {
 			if (discriminatorResult.consumed.length === 0 && discriminator.$mode === "async") {
+				const discriminatorExec = mergeChildExec(context.exec, discriminatorResult.next.exec);
+				let speculativeHit;
+				let provisionalHit;
+				let provisionalAmbiguous = false;
+				let speculativeError;
+				let ambiguous = false;
+				for (const [key, bp] of branchParsers) {
+					const branchResult = await bp.parse(withChildContext({
+						...context,
+						...discriminatorExec != null ? {
+							exec: discriminatorExec,
+							dependencyRegistry: discriminatorExec.dependencyRegistry
+						} : {}
+					}, "_branch", bp.initialState, bp, bp.usage));
+					if (branchResult.success && branchResult.consumed.length > 0) {
+						if (branchResult.provisional) {
+							if (provisionalHit == null && !provisionalAmbiguous) provisionalHit = {
+								key,
+								bp,
+								result: branchResult
+							};
+							else {
+								provisionalHit = void 0;
+								provisionalAmbiguous = true;
+							}
+							continue;
+						}
+						if (speculativeHit != null) {
+							ambiguous = true;
+							break;
+						}
+						speculativeHit = {
+							key,
+							bp,
+							result: branchResult
+						};
+					}
+					if (!branchResult.success && branchResult.consumed > 0 && (speculativeError == null || speculativeError.consumed < branchResult.consumed)) speculativeError = branchResult;
+				}
+				if (speculativeHit != null && (provisionalHit != null || provisionalAmbiguous)) ambiguous = true;
+				if (speculativeHit == null && !ambiguous && !provisionalAmbiguous && provisionalHit != null) speculativeHit = provisionalHit;
+				if (speculativeHit != null && !ambiguous) {
+					const { key, bp, result: branchResult } = speculativeHit;
+					if (branchResult.success) {
+						const annotatedDiscriminatorState$2 = getAnnotatedChildState(state, discriminatorResult.next.state, discriminator);
+						const mergedExec = mergeChildExec(discriminatorExec, branchResult.next.exec);
+						return {
+							success: true,
+							provisional: true,
+							next: {
+								...branchResult.next,
+								state: {
+									...state,
+									discriminatorState: annotatedDiscriminatorState$2,
+									selectedBranch: {
+										kind: "branch",
+										key
+									},
+									branchState: getAnnotatedChildState(state, branchResult.next.state, bp),
+									speculative: true
+								},
+								...mergedExec != null ? {
+									exec: mergedExec,
+									dependencyRegistry: mergedExec.dependencyRegistry
+								} : {}
+							},
+							consumed: branchResult.consumed
+						};
+					}
+				}
 				let deferredBranchState = state.branchState;
 				if (defaultBranch !== void 0) {
 					const defaultResult = await defaultBranch.parse(withChildContext(context, "_branch", state.branchState ?? defaultBranch.initialState, defaultBranch, defaultBranch.usage));
@@ -3887,6 +4040,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 						const defaultExec = mergeChildExec(context.exec, defaultResult.next.exec);
 						return {
 							success: true,
+							...defaultResult.provisional ? { provisional: true } : {},
 							next: {
 								...defaultResult.next,
 								state: {
@@ -3905,8 +4059,8 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					if (!defaultResult.success && defaultResult.consumed > 0) return defaultResult;
 					if (defaultResult.success && defaultResult.consumed.length === 0 && context.buffer.length === 0) deferredBranchState = getAnnotatedChildState(state, defaultResult.next.state, defaultBranch);
 				}
+				if (speculativeError != null && !ambiguous) return speculativeError;
 				const annotatedDiscriminatorState$1 = getAnnotatedChildState(state, discriminatorResult.next.state, discriminator);
-				const mergedExec = mergeChildExec(context.exec, discriminatorResult.next.exec);
 				return {
 					success: true,
 					provisional: true,
@@ -3917,9 +4071,9 @@ function conditional(discriminator, branches, defaultBranch, options) {
 							discriminatorState: annotatedDiscriminatorState$1,
 							branchState: deferredBranchState
 						},
-						...mergedExec != null ? {
-							exec: mergedExec,
-							dependencyRegistry: mergedExec.dependencyRegistry
+						...discriminatorExec != null ? {
+							exec: discriminatorExec,
+							dependencyRegistry: discriminatorExec.dependencyRegistry
 						} : {}
 					},
 					consumed: []
@@ -4141,6 +4295,18 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		};
 	};
 	const completeAsync = async (state, exec) => {
+		let wasSpeculative = false;
+		if (state.speculative && state.selectedBranch?.kind === "branch") if (exec?.phase !== "parse" && exec?.phase !== "suggest") {
+			wasSpeculative = true;
+			state = {
+				...state,
+				speculative: void 0
+			};
+		} else state = {
+			...state,
+			discriminatorValue: state.selectedBranch.key,
+			speculative: void 0
+		};
 		if (state.selectedBranch === void 0) {
 			if (exec?.phase !== "parse" && exec?.phase !== "suggest") {
 				const annotatedDiscriminatorStateForDeferred = getAnnotatedChildState(state, state.discriminatorState, discriminator);
@@ -4225,20 +4391,26 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		};
 		const needsDiscriminatorCompletion = state.selectedBranch.kind !== "default" && !(state.discriminatorValue != null && state.discriminatorValue === state.selectedBranch.key);
 		const discriminatorCompleteResult = needsDiscriminatorCompletion ? await discriminator.complete(annotatedDiscriminatorState, withChildExecPath(completionExec, "_discriminator")) : void 0;
-		const branchResult = unwrapCompleteResult(await branchParser.complete(resolvedBranchState, withChildExecPath(completionExec, "_branch")));
-		if (!branchResult.success) {
-			if (state.discriminatorValue !== void 0 && options?.errors?.branchError) return {
-				success: false,
-				error: options.errors.branchError(state.discriminatorValue, branchResult.error)
-			};
-			return branchResult;
-		}
 		let discriminatorValue;
 		if (state.selectedBranch.kind === "default") discriminatorValue = void 0;
 		else if (state.discriminatorValue != null && state.discriminatorValue === state.selectedBranch.key) discriminatorValue = state.discriminatorValue;
 		else {
 			const completedDiscriminator = unwrapCompleteResult(discriminatorCompleteResult);
-			discriminatorValue = completedDiscriminator.success ? completedDiscriminator.value : state.selectedBranch.key;
+			if (completedDiscriminator.success) discriminatorValue = completedDiscriminator.value;
+			else if (wasSpeculative) return completedDiscriminator;
+			else discriminatorValue = state.selectedBranch.key;
+		}
+		if (wasSpeculative && state.selectedBranch.kind === "branch" && discriminatorValue !== state.selectedBranch.key) return {
+			success: false,
+			error: getNoMatchError$1()
+		};
+		const branchResult = unwrapCompleteResult(await branchParser.complete(resolvedBranchState, withChildExecPath(completionExec, "_branch")));
+		if (!branchResult.success) {
+			if (discriminatorValue !== void 0 && options?.errors?.branchError) return {
+				success: false,
+				error: options.errors.branchError(discriminatorValue, branchResult.error)
+			};
+			return branchResult;
 		}
 		return {
 			success: true,

package/dist/constructs.d.cts

@@ -1316,6 +1316,7 @@ interface ConditionalState<TDiscriminator extends string> {
   readonly discriminatorValue: TDiscriminator | undefined;
   readonly selectedBranch: SelectedBranch<TDiscriminator> | undefined;
   readonly branchState: unknown;
+  readonly speculative?: true;
 }
 /**
  * Options for customizing error messages in the {@link conditional} combinator.

package/dist/constructs.d.ts

@@ -1316,6 +1316,7 @@ interface ConditionalState<TDiscriminator extends string> {
   readonly discriminatorValue: TDiscriminator | undefined;
   readonly selectedBranch: SelectedBranch<TDiscriminator> | undefined;
   readonly branchState: unknown;
+  readonly speculative?: true;
 }
 /**
  * Options for customizing error messages in the {@link conditional} combinator.

package/dist/constructs.js

@@ -712,9 +712,23 @@ function or(...args) {
 		orderedParsers.sort(([_, a], [__, b]) => activeState?.[0] === a ? -1 : activeState?.[0] === b ? 1 : a - b);
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
+		let provisionalConsuming = null;
+		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const result = parser.parse(withChildContext(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			if (result.success && result.consumed.length > 0) {
+				if (result.provisional) {
+					if (provisionalConsuming == null && !provisionalAmbiguous) provisionalConsuming = {
+						index: i,
+						parser,
+						result
+					};
+					else {
+						provisionalConsuming = null;
+						provisionalAmbiguous = true;
+					}
+					continue;
+				}
 				if (activeState?.[0] !== i && activeState?.[1].success) {
 					if (activeState[1].consumed.length === 0) {
 						const mergedExec$2 = mergeChildExec(context.exec, result.next.exec);
@@ -812,6 +826,24 @@ function or(...args) {
 				consumed: []
 			};
 		}
+		if (provisionalConsuming !== null && !(activeState != null && activeState[1].success && activeState[1].consumed.length > 0 && activeState[0] !== provisionalConsuming.index)) {
+			const mergedExec = mergeChildExec(context.exec, provisionalConsuming.result.next.exec);
+			return {
+				success: true,
+				provisional: true,
+				next: {
+					...context,
+					buffer: provisionalConsuming.result.next.buffer,
+					optionsTerminated: provisionalConsuming.result.next.optionsTerminated,
+					state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, provisionalConsuming.result),
+					...mergedExec != null ? {
+						exec: mergedExec,
+						dependencyRegistry: mergedExec.dependencyRegistry
+					} : {}
+				},
+				consumed: provisionalConsuming.result.consumed
+			};
+		}
 		return {
 			...error,
 			success: false
@@ -824,10 +856,24 @@ function or(...args) {
 		orderedParsers.sort(([_, a], [__, b]) => activeState?.[0] === a ? -1 : activeState?.[0] === b ? 1 : a - b);
 		let zeroConsumedBranch = null;
 		let zeroConsumedCount = 0;
+		let provisionalConsuming = null;
+		let provisionalAmbiguous = false;
 		for (const [parser, i] of orderedParsers) {
 			const resultOrPromise = parser.parse(withChildContext(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			const result = await resultOrPromise;
 			if (result.success && result.consumed.length > 0) {
+				if (result.provisional) {
+					if (provisionalConsuming == null && !provisionalAmbiguous) provisionalConsuming = {
+						index: i,
+						parser,
+						result
+					};
+					else {
+						provisionalConsuming = null;
+						provisionalAmbiguous = true;
+					}
+					continue;
+				}
 				if (activeState?.[0] !== i && activeState?.[1].success) {
 					if (activeState[1].consumed.length === 0) {
 						const mergedExec$2 = mergeChildExec(context.exec, result.next.exec);
@@ -927,6 +973,24 @@ function or(...args) {
 				consumed: []
 			};
 		}
+		if (provisionalConsuming !== null && !(activeState != null && activeState[1].success && activeState[1].consumed.length > 0 && activeState[0] !== provisionalConsuming.index)) {
+			const mergedExec = mergeChildExec(context.exec, provisionalConsuming.result.next.exec);
+			return {
+				success: true,
+				provisional: true,
+				next: {
+					...context,
+					buffer: provisionalConsuming.result.next.buffer,
+					optionsTerminated: provisionalConsuming.result.next.optionsTerminated,
+					state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, provisionalConsuming.result),
+					...mergedExec != null ? {
+						exec: mergedExec,
+						dependencyRegistry: mergedExec.dependencyRegistry
+					} : {}
+				},
+				consumed: provisionalConsuming.result.consumed
+			};
+		}
 		return {
 			...error,
 			success: false
@@ -1020,7 +1084,8 @@ function longestMatch(...args) {
 			const result = parser.parse(withChildContext(context, i, activeState == null || activeState[0] !== i || !activeState[1].success ? parser.initialState : activeState[1].next.state, parser));
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
-				if (bestMatch === null || consumed > bestMatch.consumed) bestMatch = {
+				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
+				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
 					parser,
 					result,
@@ -1060,7 +1125,8 @@ function longestMatch(...args) {
 			const result = await resultOrPromise;
 			if (result.success) {
 				const consumed = context.buffer.length - result.next.buffer.length;
-				if (bestMatch === null || consumed > bestMatch.consumed) bestMatch = {
+				const bestIsProvisional = bestMatch != null && bestMatch.result.success && !!bestMatch.result.provisional;
+				if (bestMatch === null || consumed > bestMatch.consumed || consumed === bestMatch.consumed && bestIsProvisional && !result.provisional) bestMatch = {
 					index: i,
 					parser,
 					result,
@@ -3656,18 +3722,35 @@ function group(label, parser, options = {}) {
 * // defaultResult.value = [undefined, {}]
 * ```
 *
-* ### Async discriminator limitation
+* ### Speculative branch parsing
 *
 * When the discriminator is an async parser that succeeds without consuming
 * input (e.g., `prompt(option(...))` with no CLI input), branch selection
-* is deferred to the complete phase.  If the selected branch needs to
-* consume remaining tokens, those tokens cannot be consumed because the
-* branch is not known during parse.  In practice, this means
-* `conditional(prompt(option(...)), { key: option(...) })` cannot parse
-* branch-specific tokens when the discriminator requires interactive
-* resolution.  Provide a default branch or ensure the discriminator
-* can resolve synchronously (e.g., via `bindEnv()` or `withDefault()`)
-* to avoid this limitation.
+* is normally deferred to the complete phase.  To allow branch-specific
+* tokens to be consumed, `conditional()` speculatively tries all named
+* branches during parse.  If exactly one branch can consume tokens, it is
+* tentatively selected and verified against the resolved discriminator
+* during the complete phase.
+*
+* If the discriminator resolves to a different branch than the one that
+* consumed tokens (contradictory input), the parse fails.  When multiple
+* branches can consume the same tokens (ambiguous), speculation is skipped
+* entirely to keep branch selection order-independent.
+*
+* #### Known limitations
+*
+* - When a default branch accepts the same tokens as a named branch,
+*   speculation prefers the named branch.  If the discriminator later
+*   resolves to a value not in the named branches, the parse fails
+*   instead of falling back to the default branch.  To avoid this,
+*   ensure named branch options are distinct from the default branch.
+* - Within `longestMatch()`, a longer speculative match can beat a
+*   shorter definitive one.  If the speculative match fails during
+*   completion, the tokens consumed by it are not recoverable.
+* - The dependency runtime seeds both discriminator and branch sources
+*   before verifying the speculative selection.  A discriminator that
+*   depends on branch-local dependency sources could be circularly
+*   confirmed by the speculative branch.
 *
 * @since 0.8.0
 */
@@ -3880,6 +3963,76 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		const discriminatorResult = await discriminator.parse({ ...withChildContext(context, "_discriminator", state.discriminatorState, discriminator) });
 		if (discriminatorResult.success) {
 			if (discriminatorResult.consumed.length === 0 && discriminator.$mode === "async") {
+				const discriminatorExec = mergeChildExec(context.exec, discriminatorResult.next.exec);
+				let speculativeHit;
+				let provisionalHit;
+				let provisionalAmbiguous = false;
+				let speculativeError;
+				let ambiguous = false;
+				for (const [key, bp] of branchParsers) {
+					const branchResult = await bp.parse(withChildContext({
+						...context,
+						...discriminatorExec != null ? {
+							exec: discriminatorExec,
+							dependencyRegistry: discriminatorExec.dependencyRegistry
+						} : {}
+					}, "_branch", bp.initialState, bp, bp.usage));
+					if (branchResult.success && branchResult.consumed.length > 0) {
+						if (branchResult.provisional) {
+							if (provisionalHit == null && !provisionalAmbiguous) provisionalHit = {
+								key,
+								bp,
+								result: branchResult
+							};
+							else {
+								provisionalHit = void 0;
+								provisionalAmbiguous = true;
+							}
+							continue;
+						}
+						if (speculativeHit != null) {
+							ambiguous = true;
+							break;
+						}
+						speculativeHit = {
+							key,
+							bp,
+							result: branchResult
+						};
+					}
+					if (!branchResult.success && branchResult.consumed > 0 && (speculativeError == null || speculativeError.consumed < branchResult.consumed)) speculativeError = branchResult;
+				}
+				if (speculativeHit != null && (provisionalHit != null || provisionalAmbiguous)) ambiguous = true;
+				if (speculativeHit == null && !ambiguous && !provisionalAmbiguous && provisionalHit != null) speculativeHit = provisionalHit;
+				if (speculativeHit != null && !ambiguous) {
+					const { key, bp, result: branchResult } = speculativeHit;
+					if (branchResult.success) {
+						const annotatedDiscriminatorState$2 = getAnnotatedChildState(state, discriminatorResult.next.state, discriminator);
+						const mergedExec = mergeChildExec(discriminatorExec, branchResult.next.exec);
+						return {
+							success: true,
+							provisional: true,
+							next: {
+								...branchResult.next,
+								state: {
+									...state,
+									discriminatorState: annotatedDiscriminatorState$2,
+									selectedBranch: {
+										kind: "branch",
+										key
+									},
+									branchState: getAnnotatedChildState(state, branchResult.next.state, bp),
+									speculative: true
+								},
+								...mergedExec != null ? {
+									exec: mergedExec,
+									dependencyRegistry: mergedExec.dependencyRegistry
+								} : {}
+							},
+							consumed: branchResult.consumed
+						};
+					}
+				}
 				let deferredBranchState = state.branchState;
 				if (defaultBranch !== void 0) {
 					const defaultResult = await defaultBranch.parse(withChildContext(context, "_branch", state.branchState ?? defaultBranch.initialState, defaultBranch, defaultBranch.usage));
@@ -3887,6 +4040,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 						const defaultExec = mergeChildExec(context.exec, defaultResult.next.exec);
 						return {
 							success: true,
+							...defaultResult.provisional ? { provisional: true } : {},
 							next: {
 								...defaultResult.next,
 								state: {
@@ -3905,8 +4059,8 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					if (!defaultResult.success && defaultResult.consumed > 0) return defaultResult;
 					if (defaultResult.success && defaultResult.consumed.length === 0 && context.buffer.length === 0) deferredBranchState = getAnnotatedChildState(state, defaultResult.next.state, defaultBranch);
 				}
+				if (speculativeError != null && !ambiguous) return speculativeError;
 				const annotatedDiscriminatorState$1 = getAnnotatedChildState(state, discriminatorResult.next.state, discriminator);
-				const mergedExec = mergeChildExec(context.exec, discriminatorResult.next.exec);
 				return {
 					success: true,
 					provisional: true,
@@ -3917,9 +4071,9 @@ function conditional(discriminator, branches, defaultBranch, options) {
 							discriminatorState: annotatedDiscriminatorState$1,
 							branchState: deferredBranchState
 						},
-						...mergedExec != null ? {
-							exec: mergedExec,
-							dependencyRegistry: mergedExec.dependencyRegistry
+						...discriminatorExec != null ? {
+							exec: discriminatorExec,
+							dependencyRegistry: discriminatorExec.dependencyRegistry
 						} : {}
 					},
 					consumed: []
@@ -4141,6 +4295,18 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		};
 	};
 	const completeAsync = async (state, exec) => {
+		let wasSpeculative = false;
+		if (state.speculative && state.selectedBranch?.kind === "branch") if (exec?.phase !== "parse" && exec?.phase !== "suggest") {
+			wasSpeculative = true;
+			state = {
+				...state,
+				speculative: void 0
+			};
+		} else state = {
+			...state,
+			discriminatorValue: state.selectedBranch.key,
+			speculative: void 0
+		};
 		if (state.selectedBranch === void 0) {
 			if (exec?.phase !== "parse" && exec?.phase !== "suggest") {
 				const annotatedDiscriminatorStateForDeferred = getAnnotatedChildState(state, state.discriminatorState, discriminator);
@@ -4225,20 +4391,26 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		};
 		const needsDiscriminatorCompletion = state.selectedBranch.kind !== "default" && !(state.discriminatorValue != null && state.discriminatorValue === state.selectedBranch.key);
 		const discriminatorCompleteResult = needsDiscriminatorCompletion ? await discriminator.complete(annotatedDiscriminatorState, withChildExecPath(completionExec, "_discriminator")) : void 0;
-		const branchResult = unwrapCompleteResult(await branchParser.complete(resolvedBranchState, withChildExecPath(completionExec, "_branch")));
-		if (!branchResult.success) {
-			if (state.discriminatorValue !== void 0 && options?.errors?.branchError) return {
-				success: false,
-				error: options.errors.branchError(state.discriminatorValue, branchResult.error)
-			};
-			return branchResult;
-		}
 		let discriminatorValue;
 		if (state.selectedBranch.kind === "default") discriminatorValue = void 0;
 		else if (state.discriminatorValue != null && state.discriminatorValue === state.selectedBranch.key) discriminatorValue = state.discriminatorValue;
 		else {
 			const completedDiscriminator = unwrapCompleteResult(discriminatorCompleteResult);
-			discriminatorValue = completedDiscriminator.success ? completedDiscriminator.value : state.selectedBranch.key;
+			if (completedDiscriminator.success) discriminatorValue = completedDiscriminator.value;
+			else if (wasSpeculative) return completedDiscriminator;
+			else discriminatorValue = state.selectedBranch.key;
+		}
+		if (wasSpeculative && state.selectedBranch.kind === "branch" && discriminatorValue !== state.selectedBranch.key) return {
+			success: false,
+			error: getNoMatchError$1()
+		};
+		const branchResult = unwrapCompleteResult(await branchParser.complete(resolvedBranchState, withChildExecPath(completionExec, "_branch")));
+		if (!branchResult.success) {
+			if (discriminatorValue !== void 0 && options?.errors?.branchError) return {
+				success: false,
+				error: options.errors.branchError(discriminatorValue, branchResult.error)
+			};
+			return branchResult;
 		}
 		return {
 			success: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1711+3514d59b",
+  "version": "1.0.0-dev.1712+ea879e28",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",