@optique/core 1.0.0-dev.1724 → 1.0.0-dev.1728

package/dist/constructs.cjs

@@ -872,27 +872,27 @@ function or(...args) {
 							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
-						};
-					}
+					if (!replayedResult.success) return replayedResult;
+					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,
+								provisional: true,
+								consumed: [...previouslyConsumed, ...replayedResult.consumed]
+							}),
+							...mergedExec != null ? {
+								exec: mergedExec,
+								dependencyRegistry: mergedExec.dependencyRegistry
+							} : {}
+						},
+						consumed: replayedResult.consumed
+					};
 				}
 			}
 		}
@@ -1071,27 +1071,27 @@ function or(...args) {
 							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
-						};
-					}
+					if (!replayedResult.success) return replayedResult;
+					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,
+								provisional: true,
+								consumed: [...previouslyConsumed, ...replayedResult.consumed]
+							}),
+							...mergedExec != null ? {
+								exec: mergedExec,
+								dependencyRegistry: mergedExec.dependencyRegistry
+							} : {}
+						},
+						consumed: replayedResult.consumed
+					};
 				}
 			}
 		}
@@ -4044,6 +4044,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				const mergedExec = mergeChildExec(context.exec, branchResult.next.exec);
 				return {
 					success: true,
+					...state.speculative || branchResult.provisional ? { provisional: true } : {},
 					next: {
 						...branchResult.next,
 						state: {
@@ -4449,6 +4450,10 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					};
 				} else if (defaultBranch === void 0) return deferredDiscriminatorResult;
 			}
+			if (defaultBranch !== void 0 && (exec?.phase === "parse" || exec?.phase === "suggest")) return {
+				success: true,
+				value: [void 0, void 0]
+			};
 			if (defaultBranch !== void 0) {
 				const branchState = getAnnotatedChildState(state, state.branchState ?? defaultBranch.initialState, defaultBranch);
 				const defaultResult = unwrapCompleteResult(await defaultBranch.complete(branchState, withChildExecPath(exec, "_branch")));

package/dist/constructs.d.cts

@@ -1343,7 +1343,7 @@ interface ConditionalErrorOptions {
    * 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
+   * @since 1.0.1
    */
   readonly branchMismatch?: (discriminatorValue: string, speculativeKey: string) => Message;
 }

package/dist/constructs.d.ts

@@ -1343,7 +1343,7 @@ interface ConditionalErrorOptions {
    * 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
+   * @since 1.0.1
    */
   readonly branchMismatch?: (discriminatorValue: string, speculativeKey: string) => Message;
 }

package/dist/constructs.js

@@ -872,27 +872,27 @@ function or(...args) {
 							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
-						};
-					}
+					if (!replayedResult.success) return replayedResult;
+					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,
+								provisional: true,
+								consumed: [...previouslyConsumed, ...replayedResult.consumed]
+							}),
+							...mergedExec != null ? {
+								exec: mergedExec,
+								dependencyRegistry: mergedExec.dependencyRegistry
+							} : {}
+						},
+						consumed: replayedResult.consumed
+					};
 				}
 			}
 		}
@@ -1071,27 +1071,27 @@ function or(...args) {
 							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
-						};
-					}
+					if (!replayedResult.success) return replayedResult;
+					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,
+								provisional: true,
+								consumed: [...previouslyConsumed, ...replayedResult.consumed]
+							}),
+							...mergedExec != null ? {
+								exec: mergedExec,
+								dependencyRegistry: mergedExec.dependencyRegistry
+							} : {}
+						},
+						consumed: replayedResult.consumed
+					};
 				}
 			}
 		}
@@ -4044,6 +4044,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				const mergedExec = mergeChildExec(context.exec, branchResult.next.exec);
 				return {
 					success: true,
+					...state.speculative || branchResult.provisional ? { provisional: true } : {},
 					next: {
 						...branchResult.next,
 						state: {
@@ -4449,6 +4450,10 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					};
 				} else if (defaultBranch === void 0) return deferredDiscriminatorResult;
 			}
+			if (defaultBranch !== void 0 && (exec?.phase === "parse" || exec?.phase === "suggest")) return {
+				success: true,
+				value: [void 0, void 0]
+			};
 			if (defaultBranch !== void 0) {
 				const branchState = getAnnotatedChildState(state, state.branchState ?? defaultBranch.initialState, defaultBranch);
 				const defaultResult = unwrapCompleteResult(await defaultBranch.complete(branchState, withChildExecPath(exec, "_branch")));

package/dist/parser.d.cts

@@ -559,11 +559,23 @@ type ParserResult<TState> = {
    */
   readonly consumed: readonly string[];
   /**
-   * When `true`, indicates that this success is tentative: the parser
-   * matched something (e.g., a zero-consuming discriminator resolved to
-   * a branch key) but the selected sub-parser has not consumed any input
-   * yet.  Outer combinators like {@link or} should not treat provisional
-   * successes as definitive zero-consumed fallback candidates.
+   * When `true`, indicates that this success is tentative or
+   * speculative: the parser matched something but the match has not
+   * been confirmed yet.  This covers two cases:
+   *
+   * - A zero-consuming discriminator resolved to a branch key, but
+   *   the selected sub-parser has not consumed any input yet.
+   * - A {@link conditional} parser speculatively committed to a
+   *   named branch that consumed tokens, before the discriminator
+   *   has had a chance to confirm the choice.  In this case the
+   *   marker stays set across subsequent parse calls until
+   *   `complete()` verifies the speculative selection.
+   *
+   * Outer combinators like {@link or} and {@link longestMatch} should
+   * not treat provisional successes as definitive — a definitive
+   * branch must be allowed to take priority, and a definitive
+   * zero-consuming fallback must not be displaced by a provisional
+   * consuming hit.
    *
    * @since 1.0.0
    */

package/dist/parser.d.ts

@@ -559,11 +559,23 @@ type ParserResult<TState> = {
    */
   readonly consumed: readonly string[];
   /**
-   * When `true`, indicates that this success is tentative: the parser
-   * matched something (e.g., a zero-consuming discriminator resolved to
-   * a branch key) but the selected sub-parser has not consumed any input
-   * yet.  Outer combinators like {@link or} should not treat provisional
-   * successes as definitive zero-consumed fallback candidates.
+   * When `true`, indicates that this success is tentative or
+   * speculative: the parser matched something but the match has not
+   * been confirmed yet.  This covers two cases:
+   *
+   * - A zero-consuming discriminator resolved to a branch key, but
+   *   the selected sub-parser has not consumed any input yet.
+   * - A {@link conditional} parser speculatively committed to a
+   *   named branch that consumed tokens, before the discriminator
+   *   has had a chance to confirm the choice.  In this case the
+   *   marker stays set across subsequent parse calls until
+   *   `complete()` verifies the speculative selection.
+   *
+   * Outer combinators like {@link or} and {@link longestMatch} should
+   * not treat provisional successes as definitive — a definitive
+   * branch must be allowed to take priority, and a definitive
+   * zero-consuming fallback must not be displaced by a provisional
+   * consuming hit.
    *
    * @since 1.0.0
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1724+3460ea70",
+  "version": "1.0.0-dev.1728+5206d2c9",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",