@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/constructs.d.cts

@@ -1,6 +1,6 @@
 import { Message } from "./message.cjs";
 import { HiddenVisibility } from "./usage.cjs";
-import { CombineModes, InferValue, Mode, Parser, ParserResult } from "./parser.cjs";
+import { CombineModes, InferValue, Mode, Parser, ParserResult } from "./internal/parser.cjs";
 
 //#region src/constructs.d.ts
 
@@ -730,6 +730,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, MD extend
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, options: OrOptions): Parser<CombineModes<readonly [MA, MB]>, TA | TB, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>]>;
@@ -751,6 +752,7 @@ declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, TC, TStateA, TStateB, TStateC>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, c: Parser<MC, TC, TStateC>, options: OrOptions): Parser<CombineModes<readonly [MA, MB, MC]>, TA | TB | TC, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>]>;
@@ -760,6 +762,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, T
  * @param rest Parsers to try, followed by {@link OrOptions} for error
  *             customization.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: OrTailOptions] & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -767,6 +770,7 @@ declare function or<const TParsers extends readonly Parser<Mode, unknown, unknow
  * Creates a parser that tries each parser in sequence until one succeeds.
  * @param parsers Parsers to try in order.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...parsers: TParsers & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -860,6 +864,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @param rest Parsers to compare, followed by error customization options.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<"sync", unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<"sync", InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -870,6 +875,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @param rest Parsers to compare, followed by error customization options.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -919,7 +925,8 @@ interface ObjectOptions {
   readonly errors?: ObjectErrorOptions;
   /**
    * When `true`, allows duplicate option names across different fields.
-   * By default (`false`), duplicate option names will cause a parse error.
+   * By default (`false`), duplicate option names cause a construction-time
+   * error.
    *
    * @default `false`
    * @since 0.7.0
@@ -1017,6 +1024,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function object<T extends {
   readonly [key: string | symbol]: Parser<Mode, unknown, unknown>;
@@ -1034,6 +1043,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.5.0
  */
 declare function object<T extends {
@@ -1046,7 +1057,8 @@ declare function object<T extends {
 interface TupleOptions {
   /**
    * When `true`, allows duplicate option names across different parsers.
-   * By default (`false`), duplicate option names will cause a parse error.
+   * By default (`false`), duplicate option names cause a construction-time
+   * error.
    *
    * @default `false`
    * @since 0.7.0
@@ -1078,6 +1090,8 @@ declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]
  * @returns A {@link Parser} that produces a readonly tuple with the same length
  *          as the input array, where each element is the result of the
  *          corresponding parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, parsers: T, options?: TupleOptions): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
 /**
@@ -1097,7 +1111,8 @@ type ExtractObjectTypes<P> = P extends Parser<Mode, infer V, unknown> ? [AllObje
 interface MergeOptions {
   /**
    * When `true`, allows duplicate option names across merged parsers.
-   * By default (`false`), duplicate option names will cause a parse error.
+   * By default (`false`), duplicate option names cause a construction-time
+   * error.
    *
    * @default `false`
    * @since 0.7.0
@@ -1131,6 +1146,7 @@ type MergeReturnType<TParsers extends MergeParsers> = Parser<CombineModes<{ read
  * @param rest Parsers to merge, followed by merge options.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1144,6 +1160,9 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1157,6 +1176,9 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
  * @param rest Parsers to merge, followed by merge options.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1169,6 +1191,7 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...re
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.1.0
  */
 declare function merge<const TParsers extends MergeParsers>(...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1216,6 +1239,7 @@ type ConcatValues<TParsers extends ConcatParsers> = IsTuple<TParsers> extends tr
  * @param parsers Tuple parsers to concatenate.
  * @returns A parser with flattened tuple values from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.2.0
  */
 declare function concat<const TParsers extends ConcatParsers>(...parsers: TParsers & ConcatArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, ConcatValues<TParsers>, ConcatStates<TParsers>>;
@@ -1260,6 +1284,8 @@ declare function concat<const TParsers extends ConcatParsers>(...parsers: TParse
  * @param options Optional visibility controls for the wrapped parser terms.
  * @returns A new parser that behaves identically to the input parser
  *          but generates documentation within a labeled section.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 /**
@@ -1293,6 +1319,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.
@@ -1303,11 +1330,25 @@ interface ConditionalErrorOptions {
    * Custom error message when branch parser fails.
    * Receives the discriminator value for context.
    */
-  branchError?: (discriminatorValue: string | undefined, error: Message) => Message;
+  readonly branchError?: (discriminatorValue: string | undefined, error: Message) => Message;
   /**
    * Custom error message for no matching input.
    */
-  noMatch?: Message | ((context: NoMatchContext) => Message);
+  readonly 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 1.0.1
+   */
+  readonly branchMismatch?: (discriminatorValue: string, speculativeKey: string) => Message;
 }
 /**
  * Options for customizing the {@link conditional} combinator behavior.
@@ -1317,7 +1358,7 @@ interface ConditionalOptions {
   /**
    * Custom error messages.
    */
-  errors?: ConditionalErrorOptions;
+  readonly errors?: ConditionalErrorOptions;
 }
 /**
  * Helper type to infer result type without default branch.

package/dist/constructs.d.ts

@@ -1,6 +1,6 @@
 import { Message } from "./message.js";
 import { HiddenVisibility } from "./usage.js";
-import { CombineModes, InferValue, Mode, Parser, ParserResult } from "./parser.js";
+import { CombineModes, InferValue, Mode, Parser, ParserResult } from "./internal/parser.js";
 
 //#region src/constructs.d.ts
 
@@ -730,6 +730,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, MD extend
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, options: OrOptions): Parser<CombineModes<readonly [MA, MB]>, TA | TB, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>]>;
@@ -751,6 +752,7 @@ declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, TC, TStateA, TStateB, TStateC>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, c: Parser<MC, TC, TStateC>, options: OrOptions): Parser<CombineModes<readonly [MA, MB, MC]>, TA | TB | TC, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>]>;
@@ -760,6 +762,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, T
  * @param rest Parsers to try, followed by {@link OrOptions} for error
  *             customization.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: OrTailOptions] & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -767,6 +770,7 @@ declare function or<const TParsers extends readonly Parser<Mode, unknown, unknow
  * Creates a parser that tries each parser in sequence until one succeeds.
  * @param parsers Parsers to try in order.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...parsers: TParsers & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -860,6 +864,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @param rest Parsers to compare, followed by error customization options.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<"sync", unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<"sync", InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -870,6 +875,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @param rest Parsers to compare, followed by error customization options.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -919,7 +925,8 @@ interface ObjectOptions {
   readonly errors?: ObjectErrorOptions;
   /**
    * When `true`, allows duplicate option names across different fields.
-   * By default (`false`), duplicate option names will cause a parse error.
+   * By default (`false`), duplicate option names cause a construction-time
+   * error.
    *
    * @default `false`
    * @since 0.7.0
@@ -1017,6 +1024,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function object<T extends {
   readonly [key: string | symbol]: Parser<Mode, unknown, unknown>;
@@ -1034,6 +1043,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.5.0
  */
 declare function object<T extends {
@@ -1046,7 +1057,8 @@ declare function object<T extends {
 interface TupleOptions {
   /**
    * When `true`, allows duplicate option names across different parsers.
-   * By default (`false`), duplicate option names will cause a parse error.
+   * By default (`false`), duplicate option names cause a construction-time
+   * error.
    *
    * @default `false`
    * @since 0.7.0
@@ -1078,6 +1090,8 @@ declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]
  * @returns A {@link Parser} that produces a readonly tuple with the same length
  *          as the input array, where each element is the result of the
  *          corresponding parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, parsers: T, options?: TupleOptions): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
 /**
@@ -1097,7 +1111,8 @@ type ExtractObjectTypes<P> = P extends Parser<Mode, infer V, unknown> ? [AllObje
 interface MergeOptions {
   /**
    * When `true`, allows duplicate option names across merged parsers.
-   * By default (`false`), duplicate option names will cause a parse error.
+   * By default (`false`), duplicate option names cause a construction-time
+   * error.
    *
    * @default `false`
    * @since 0.7.0
@@ -1131,6 +1146,7 @@ type MergeReturnType<TParsers extends MergeParsers> = Parser<CombineModes<{ read
  * @param rest Parsers to merge, followed by merge options.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1144,6 +1160,9 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1157,6 +1176,9 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
  * @param rest Parsers to merge, followed by merge options.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1169,6 +1191,7 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...re
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.1.0
  */
 declare function merge<const TParsers extends MergeParsers>(...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1216,6 +1239,7 @@ type ConcatValues<TParsers extends ConcatParsers> = IsTuple<TParsers> extends tr
  * @param parsers Tuple parsers to concatenate.
  * @returns A parser with flattened tuple values from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.2.0
  */
 declare function concat<const TParsers extends ConcatParsers>(...parsers: TParsers & ConcatArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, ConcatValues<TParsers>, ConcatStates<TParsers>>;
@@ -1260,6 +1284,8 @@ declare function concat<const TParsers extends ConcatParsers>(...parsers: TParse
  * @param options Optional visibility controls for the wrapped parser terms.
  * @returns A new parser that behaves identically to the input parser
  *          but generates documentation within a labeled section.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 /**
@@ -1293,6 +1319,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.
@@ -1303,11 +1330,25 @@ interface ConditionalErrorOptions {
    * Custom error message when branch parser fails.
    * Receives the discriminator value for context.
    */
-  branchError?: (discriminatorValue: string | undefined, error: Message) => Message;
+  readonly branchError?: (discriminatorValue: string | undefined, error: Message) => Message;
   /**
    * Custom error message for no matching input.
    */
-  noMatch?: Message | ((context: NoMatchContext) => Message);
+  readonly 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 1.0.1
+   */
+  readonly branchMismatch?: (discriminatorValue: string, speculativeKey: string) => Message;
 }
 /**
  * Options for customizing the {@link conditional} combinator behavior.
@@ -1317,7 +1358,7 @@ interface ConditionalOptions {
   /**
    * Custom error messages.
    */
-  errors?: ConditionalErrorOptions;
+  readonly errors?: ConditionalErrorOptions;
 }
 /**
  * Helper type to infer result type without default branch.