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

package/dist/constructs.cjs

@@ -712,9 +712,33 @@ 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) {
+					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
+					if (activeBranchLocked && activeState[0] === i) {
+						provisionalConsuming = {
+							index: i,
+							parser,
+							result
+						};
+						continue;
+					}
+					if (activeBranchLocked && provisionalConsuming != null && provisionalConsuming.index === activeState[0]) continue;
+					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 +836,66 @@ function or(...args) {
 				consumed: []
 			};
 		}
+		if (provisionalConsuming !== null) {
+			const activeIsLockedDifferent = activeState != null && activeState[1].success && activeState[1].consumed.length > 0 && activeState[0] !== provisionalConsuming.index;
+			if (!activeIsLockedDifferent) {
+				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
+				};
+			}
+			if (activeState != null && activeState[1].success) {
+				const previouslyConsumed = activeState[1].consumed;
+				const checkResult = provisionalConsuming.parser.parse({
+					...withChildContext(context, provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
+					buffer: previouslyConsumed
+				});
+				const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
+				if (canConsumeShared && checkResult.success) {
+					const replayExec = mergeChildExec(context.exec, checkResult.next.exec);
+					const replayedResult = provisionalConsuming.parser.parse(withChildContext({
+						...context,
+						...replayExec != null ? {
+							exec: replayExec,
+							dependencyRegistry: replayExec.dependencyRegistry
+						} : {}
+					}, provisionalConsuming.index, checkResult.next.state, provisionalConsuming.parser));
+					if (replayedResult.success) {
+						const mergedExec = mergeChildExec(replayExec, replayedResult.next.exec);
+						return {
+							success: true,
+							provisional: true,
+							next: {
+								...context,
+								buffer: replayedResult.next.buffer,
+								optionsTerminated: replayedResult.next.optionsTerminated,
+								state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
+									...replayedResult,
+									consumed: [...previouslyConsumed, ...replayedResult.consumed]
+								}),
+								...mergedExec != null ? {
+									exec: mergedExec,
+									dependencyRegistry: mergedExec.dependencyRegistry
+								} : {}
+							},
+							consumed: replayedResult.consumed
+						};
+					}
+				}
+			}
+		}
 		return {
 			...error,
 			success: false
@@ -824,10 +908,34 @@ 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) {
+					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
+					if (activeBranchLocked && activeState[0] === i) {
+						provisionalConsuming = {
+							index: i,
+							parser,
+							result
+						};
+						continue;
+					}
+					if (activeBranchLocked && provisionalConsuming != null && provisionalConsuming.index === activeState[0]) continue;
+					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 +1035,66 @@ function or(...args) {
 				consumed: []
 			};
 		}
+		if (provisionalConsuming !== null) {
+			const activeIsLockedDifferent = activeState != null && activeState[1].success && activeState[1].consumed.length > 0 && activeState[0] !== provisionalConsuming.index;
+			if (!activeIsLockedDifferent) {
+				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
+				};
+			}
+			if (activeState != null && activeState[1].success) {
+				const previouslyConsumed = activeState[1].consumed;
+				const checkResult = await provisionalConsuming.parser.parse({
+					...withChildContext(context, provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
+					buffer: previouslyConsumed
+				});
+				const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
+				if (canConsumeShared && checkResult.success) {
+					const replayExec = mergeChildExec(context.exec, checkResult.next.exec);
+					const replayedResult = await provisionalConsuming.parser.parse(withChildContext({
+						...context,
+						...replayExec != null ? {
+							exec: replayExec,
+							dependencyRegistry: replayExec.dependencyRegistry
+						} : {}
+					}, provisionalConsuming.index, checkResult.next.state, provisionalConsuming.parser));
+					if (replayedResult.success) {
+						const mergedExec = mergeChildExec(replayExec, replayedResult.next.exec);
+						return {
+							success: true,
+							provisional: true,
+							next: {
+								...context,
+								buffer: replayedResult.next.buffer,
+								optionsTerminated: replayedResult.next.optionsTerminated,
+								state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
+									...replayedResult,
+									consumed: [...previouslyConsumed, ...replayedResult.consumed]
+								}),
+								...mergedExec != null ? {
+									exec: mergedExec,
+									dependencyRegistry: mergedExec.dependencyRegistry
+								} : {}
+							},
+							consumed: replayedResult.consumed
+						};
+					}
+				}
+			}
+		}
 		return {
 			...error,
 			success: false
@@ -1020,7 +1188,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 +1229,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 +3826,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,13 +4067,87 @@ 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);
+				const speculationContext = {
+					...context,
+					buffer: discriminatorResult.next.buffer,
+					optionsTerminated: discriminatorResult.next.optionsTerminated,
+					...discriminatorExec != null ? {
+						exec: discriminatorExec,
+						dependencyRegistry: discriminatorExec.dependencyRegistry
+					} : {}
+				};
+				let speculativeHit;
+				let provisionalHit;
+				let provisionalAmbiguous = false;
+				let speculativeError;
+				let ambiguous = false;
+				for (const [key, bp] of branchParsers) {
+					const branchResult = await bp.parse(withChildContext(speculationContext, "_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));
+					const defaultResult = await defaultBranch.parse(withChildContext(speculationContext, "_branch", state.branchState ?? defaultBranch.initialState, defaultBranch, defaultBranch.usage));
 					if (defaultResult.success && defaultResult.consumed.length > 0) {
-						const defaultExec = mergeChildExec(context.exec, defaultResult.next.exec);
+						const defaultExec = mergeChildExec(discriminatorExec ?? context.exec, defaultResult.next.exec);
 						return {
 							success: true,
+							...defaultResult.provisional ? { provisional: true } : {},
 							next: {
 								...defaultResult.next,
 								state: {
@@ -3903,10 +4164,10 @@ 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 (defaultResult.success && defaultResult.consumed.length === 0 && speculationContext.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 +4178,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 +4402,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 +4498,30 @@ 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) {
+			const speculativeKey = state.selectedBranch.key;
+			const resolvedKey = discriminatorValue ?? "";
+			return {
+				success: false,
+				error: options?.errors?.branchMismatch ? options.errors.branchMismatch(resolvedKey, speculativeKey) : require_message.message`Branch mismatch: tokens for ${speculativeKey} were consumed, but the discriminator resolved to ${resolvedKey}.`
+			};
+		}
+		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.
@@ -1331,6 +1332,20 @@ interface ConditionalErrorOptions {
    * Custom error message for no matching input.
    */
   noMatch?: Message | ((context: NoMatchContext) => Message);
+  /**
+   * Custom error message when speculative branch parsing committed
+   * to one branch but the resolved discriminator value names a
+   * different branch.  This is the contradictory-input case: tokens
+   * specific to one branch were consumed during the parse phase,
+   * but the discriminator (e.g., from `prompt()` or a deferred
+   * config source) ultimately resolved to a different key.
+   *
+   * Receives both the discriminator value the parser actually
+   * resolved to (`discriminatorValue`) and the speculative key the
+   * branch tokens were committed to (`speculativeKey`).
+   * @since 0.10.1
+   */
+  branchMismatch?: (discriminatorValue: string, speculativeKey: string) => Message;
 }
 /**
  * Options for customizing the {@link conditional} combinator behavior.

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.
@@ -1331,6 +1332,20 @@ interface ConditionalErrorOptions {
    * Custom error message for no matching input.
    */
   noMatch?: Message | ((context: NoMatchContext) => Message);
+  /**
+   * Custom error message when speculative branch parsing committed
+   * to one branch but the resolved discriminator value names a
+   * different branch.  This is the contradictory-input case: tokens
+   * specific to one branch were consumed during the parse phase,
+   * but the discriminator (e.g., from `prompt()` or a deferred
+   * config source) ultimately resolved to a different key.
+   *
+   * Receives both the discriminator value the parser actually
+   * resolved to (`discriminatorValue`) and the speculative key the
+   * branch tokens were committed to (`speculativeKey`).
+   * @since 0.10.1
+   */
+  branchMismatch?: (discriminatorValue: string, speculativeKey: string) => Message;
 }
 /**
  * Options for customizing the {@link conditional} combinator behavior.

package/dist/constructs.js

@@ -712,9 +712,33 @@ 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) {
+					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
+					if (activeBranchLocked && activeState[0] === i) {
+						provisionalConsuming = {
+							index: i,
+							parser,
+							result
+						};
+						continue;
+					}
+					if (activeBranchLocked && provisionalConsuming != null && provisionalConsuming.index === activeState[0]) continue;
+					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 +836,66 @@ function or(...args) {
 				consumed: []
 			};
 		}
+		if (provisionalConsuming !== null) {
+			const activeIsLockedDifferent = activeState != null && activeState[1].success && activeState[1].consumed.length > 0 && activeState[0] !== provisionalConsuming.index;
+			if (!activeIsLockedDifferent) {
+				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
+				};
+			}
+			if (activeState != null && activeState[1].success) {
+				const previouslyConsumed = activeState[1].consumed;
+				const checkResult = provisionalConsuming.parser.parse({
+					...withChildContext(context, provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
+					buffer: previouslyConsumed
+				});
+				const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
+				if (canConsumeShared && checkResult.success) {
+					const replayExec = mergeChildExec(context.exec, checkResult.next.exec);
+					const replayedResult = provisionalConsuming.parser.parse(withChildContext({
+						...context,
+						...replayExec != null ? {
+							exec: replayExec,
+							dependencyRegistry: replayExec.dependencyRegistry
+						} : {}
+					}, provisionalConsuming.index, checkResult.next.state, provisionalConsuming.parser));
+					if (replayedResult.success) {
+						const mergedExec = mergeChildExec(replayExec, replayedResult.next.exec);
+						return {
+							success: true,
+							provisional: true,
+							next: {
+								...context,
+								buffer: replayedResult.next.buffer,
+								optionsTerminated: replayedResult.next.optionsTerminated,
+								state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
+									...replayedResult,
+									consumed: [...previouslyConsumed, ...replayedResult.consumed]
+								}),
+								...mergedExec != null ? {
+									exec: mergedExec,
+									dependencyRegistry: mergedExec.dependencyRegistry
+								} : {}
+							},
+							consumed: replayedResult.consumed
+						};
+					}
+				}
+			}
+		}
 		return {
 			...error,
 			success: false
@@ -824,10 +908,34 @@ 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) {
+					const activeBranchLocked = activeState != null && activeState[1].success && activeState[1].consumed.length > 0;
+					if (activeBranchLocked && activeState[0] === i) {
+						provisionalConsuming = {
+							index: i,
+							parser,
+							result
+						};
+						continue;
+					}
+					if (activeBranchLocked && provisionalConsuming != null && provisionalConsuming.index === activeState[0]) continue;
+					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 +1035,66 @@ function or(...args) {
 				consumed: []
 			};
 		}
+		if (provisionalConsuming !== null) {
+			const activeIsLockedDifferent = activeState != null && activeState[1].success && activeState[1].consumed.length > 0 && activeState[0] !== provisionalConsuming.index;
+			if (!activeIsLockedDifferent) {
+				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
+				};
+			}
+			if (activeState != null && activeState[1].success) {
+				const previouslyConsumed = activeState[1].consumed;
+				const checkResult = await provisionalConsuming.parser.parse({
+					...withChildContext(context, provisionalConsuming.index, provisionalConsuming.parser.initialState, provisionalConsuming.parser),
+					buffer: previouslyConsumed
+				});
+				const canConsumeShared = checkResult.success && checkResult.consumed.length === previouslyConsumed.length && checkResult.consumed.every((c, idx) => c === previouslyConsumed[idx]);
+				if (canConsumeShared && checkResult.success) {
+					const replayExec = mergeChildExec(context.exec, checkResult.next.exec);
+					const replayedResult = await provisionalConsuming.parser.parse(withChildContext({
+						...context,
+						...replayExec != null ? {
+							exec: replayExec,
+							dependencyRegistry: replayExec.dependencyRegistry
+						} : {}
+					}, provisionalConsuming.index, checkResult.next.state, provisionalConsuming.parser));
+					if (replayedResult.success) {
+						const mergedExec = mergeChildExec(replayExec, replayedResult.next.exec);
+						return {
+							success: true,
+							provisional: true,
+							next: {
+								...context,
+								buffer: replayedResult.next.buffer,
+								optionsTerminated: replayedResult.next.optionsTerminated,
+								state: createExclusiveState(context.state, provisionalConsuming.index, provisionalConsuming.parser, {
+									...replayedResult,
+									consumed: [...previouslyConsumed, ...replayedResult.consumed]
+								}),
+								...mergedExec != null ? {
+									exec: mergedExec,
+									dependencyRegistry: mergedExec.dependencyRegistry
+								} : {}
+							},
+							consumed: replayedResult.consumed
+						};
+					}
+				}
+			}
+		}
 		return {
 			...error,
 			success: false
@@ -1020,7 +1188,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 +1229,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 +3826,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,13 +4067,87 @@ 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);
+				const speculationContext = {
+					...context,
+					buffer: discriminatorResult.next.buffer,
+					optionsTerminated: discriminatorResult.next.optionsTerminated,
+					...discriminatorExec != null ? {
+						exec: discriminatorExec,
+						dependencyRegistry: discriminatorExec.dependencyRegistry
+					} : {}
+				};
+				let speculativeHit;
+				let provisionalHit;
+				let provisionalAmbiguous = false;
+				let speculativeError;
+				let ambiguous = false;
+				for (const [key, bp] of branchParsers) {
+					const branchResult = await bp.parse(withChildContext(speculationContext, "_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));
+					const defaultResult = await defaultBranch.parse(withChildContext(speculationContext, "_branch", state.branchState ?? defaultBranch.initialState, defaultBranch, defaultBranch.usage));
 					if (defaultResult.success && defaultResult.consumed.length > 0) {
-						const defaultExec = mergeChildExec(context.exec, defaultResult.next.exec);
+						const defaultExec = mergeChildExec(discriminatorExec ?? context.exec, defaultResult.next.exec);
 						return {
 							success: true,
+							...defaultResult.provisional ? { provisional: true } : {},
 							next: {
 								...defaultResult.next,
 								state: {
@@ -3903,10 +4164,10 @@ 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 (defaultResult.success && defaultResult.consumed.length === 0 && speculationContext.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 +4178,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 +4402,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 +4498,30 @@ 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) {
+			const speculativeKey = state.selectedBranch.key;
+			const resolvedKey = discriminatorValue ?? "";
+			return {
+				success: false,
+				error: options?.errors?.branchMismatch ? options.errors.branchMismatch(resolvedKey, speculativeKey) : message`Branch mismatch: tokens for ${speculativeKey} were consumed, but the discriminator resolved to ${resolvedKey}.`
+			};
+		}
+		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.1714+ef964285",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",