@optique/core 1.0.0-dev.1758 → 1.0.0-dev.1772

package/dist/annotations.cjs

@@ -131,6 +131,21 @@ function inheritAnnotations(source, target) {
 	return cloned;
 }
 /**
+* Returns whether an annotations record carries at least one own symbol key.
+*
+* An annotations object with no own symbol keys is treated as a no-op by the
+* injection pipeline: it should behave identically to omitting the
+* `annotations` option entirely.  `null` and `undefined` are accepted for
+* call-site convenience and always return `false`.
+*
+* @param annotations The annotations record to check.
+* @returns `true` when the record has at least one own symbol key.
+* @internal
+*/
+function hasMeaningfulAnnotations(annotations) {
+	return annotations != null && Object.getOwnPropertySymbols(annotations).length > 0;
+}
+/**
 * Injects annotations into parser state while preserving state shape.
 *
 * - Primitive, null, and undefined states are wrapped with internal metadata.
@@ -138,6 +153,8 @@ function inheritAnnotations(source, target) {
 * - Plain object states are shallow-cloned with annotations attached.
 * - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
 * - Other non-plain object states are cloned via prototype/descriptors.
+* - If the `annotations` record has no own symbol keys, the state is
+*   returned unchanged; an empty annotations object is a no-op.
 *
 * @param state The parser state to annotate.
 * @param annotations The annotations to inject.
@@ -145,6 +162,7 @@ function inheritAnnotations(source, target) {
 * @internal
 */
 function injectAnnotations(state, annotations) {
+	if (!hasMeaningfulAnnotations(annotations)) return state;
 	if (state == null || typeof state !== "object") {
 		const wrapper = {};
 		Object.defineProperties(wrapper, {
@@ -243,6 +261,7 @@ exports.annotationStateValueKey = annotationStateValueKey;
 exports.annotationWrapperKey = annotationWrapperKey;
 exports.firstPassAnnotationKey = firstPassAnnotationKey;
 exports.getAnnotations = getAnnotations;
+exports.hasMeaningfulAnnotations = hasMeaningfulAnnotations;
 exports.inheritAnnotations = inheritAnnotations;
 exports.injectAnnotations = injectAnnotations;
 exports.isInjectedAnnotationWrapper = isInjectedAnnotationWrapper;

package/dist/annotations.d.cts

@@ -100,6 +100,19 @@ declare function annotateFreshArray<T>(source: unknown, target: readonly T[]): r
  * @internal
  */
 declare function inheritAnnotations<T>(source: unknown, target: T): T;
+/**
+ * Returns whether an annotations record carries at least one own symbol key.
+ *
+ * An annotations object with no own symbol keys is treated as a no-op by the
+ * injection pipeline: it should behave identically to omitting the
+ * `annotations` option entirely.  `null` and `undefined` are accepted for
+ * call-site convenience and always return `false`.
+ *
+ * @param annotations The annotations record to check.
+ * @returns `true` when the record has at least one own symbol key.
+ * @internal
+ */
+declare function hasMeaningfulAnnotations(annotations: Annotations | null | undefined): annotations is Annotations;
 /**
  * Injects annotations into parser state while preserving state shape.
  *
@@ -108,6 +121,8 @@ declare function inheritAnnotations<T>(source: unknown, target: T): T;
  * - Plain object states are shallow-cloned with annotations attached.
  * - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
  * - Other non-plain object states are cloned via prototype/descriptors.
+ * - If the `annotations` record has no own symbol keys, the state is
+ *   returned unchanged; an empty annotations object is a no-op.
  *
  * @param state The parser state to annotate.
  * @param annotations The annotations to inject.
@@ -134,4 +149,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.d.ts

@@ -100,6 +100,19 @@ declare function annotateFreshArray<T>(source: unknown, target: readonly T[]): r
  * @internal
  */
 declare function inheritAnnotations<T>(source: unknown, target: T): T;
+/**
+ * Returns whether an annotations record carries at least one own symbol key.
+ *
+ * An annotations object with no own symbol keys is treated as a no-op by the
+ * injection pipeline: it should behave identically to omitting the
+ * `annotations` option entirely.  `null` and `undefined` are accepted for
+ * call-site convenience and always return `false`.
+ *
+ * @param annotations The annotations record to check.
+ * @returns `true` when the record has at least one own symbol key.
+ * @internal
+ */
+declare function hasMeaningfulAnnotations(annotations: Annotations | null | undefined): annotations is Annotations;
 /**
  * Injects annotations into parser state while preserving state shape.
  *
@@ -108,6 +121,8 @@ declare function inheritAnnotations<T>(source: unknown, target: T): T;
  * - Plain object states are shallow-cloned with annotations attached.
  * - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
  * - Other non-plain object states are cloned via prototype/descriptors.
+ * - If the `annotations` record has no own symbol keys, the state is
+ *   returned unchanged; an empty annotations object is a no-op.
  *
  * @param state The parser state to annotate.
  * @param annotations The annotations to inject.
@@ -134,4 +149,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.js

@@ -130,6 +130,21 @@ function inheritAnnotations(source, target) {
 	return cloned;
 }
 /**
+* Returns whether an annotations record carries at least one own symbol key.
+*
+* An annotations object with no own symbol keys is treated as a no-op by the
+* injection pipeline: it should behave identically to omitting the
+* `annotations` option entirely.  `null` and `undefined` are accepted for
+* call-site convenience and always return `false`.
+*
+* @param annotations The annotations record to check.
+* @returns `true` when the record has at least one own symbol key.
+* @internal
+*/
+function hasMeaningfulAnnotations(annotations) {
+	return annotations != null && Object.getOwnPropertySymbols(annotations).length > 0;
+}
+/**
 * Injects annotations into parser state while preserving state shape.
 *
 * - Primitive, null, and undefined states are wrapped with internal metadata.
@@ -137,6 +152,8 @@ function inheritAnnotations(source, target) {
 * - Plain object states are shallow-cloned with annotations attached.
 * - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
 * - Other non-plain object states are cloned via prototype/descriptors.
+* - If the `annotations` record has no own symbol keys, the state is
+*   returned unchanged; an empty annotations object is a no-op.
 *
 * @param state The parser state to annotate.
 * @param annotations The annotations to inject.
@@ -144,6 +161,7 @@ function inheritAnnotations(source, target) {
 * @internal
 */
 function injectAnnotations(state, annotations) {
+	if (!hasMeaningfulAnnotations(annotations)) return state;
 	if (state == null || typeof state !== "object") {
 		const wrapper = {};
 		Object.defineProperties(wrapper, {
@@ -236,4 +254,4 @@ function isInjectedAnnotationWrapper(value) {
 }
 
 //#endregion
-export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/constructs.cjs

@@ -3795,6 +3795,11 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(groupParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return groupParser;
 }
 /**

package/dist/constructs.js

@@ -3795,6 +3795,11 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(groupParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return groupParser;
 }
 /**

package/dist/modifiers.cjs

@@ -306,6 +306,20 @@ function optional(parser) {
 			enumerable: false
 		});
 	}
+	if (typeof parser.validateValue === "function") {
+		const innerValidate = parser.validateValue.bind(parser);
+		Object.defineProperty(optionalParser, "validateValue", {
+			value(v) {
+				if (v === void 0) return require_mode_dispatch.wrapForMode(parser.$mode, {
+					success: true,
+					value: v
+				});
+				return innerValidate(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata != null) {
 		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
@@ -504,6 +518,16 @@ function withDefault(parser, defaultValue, options) {
 			enumerable: false
 		});
 	}
+	if (typeof parser.validateValue === "function") {
+		const innerValidate = parser.validateValue.bind(parser);
+		Object.defineProperty(withDefaultParser, "validateValue", {
+			value(v) {
+				return innerValidate(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata != null) {
 		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "withDefault", { defaultValue: () => {
 			let v;
@@ -649,6 +673,7 @@ function map(parser, transform) {
 		}
 	};
 	delete mappedParser.normalizeValue;
+	delete mappedParser.validateValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
 		get() {
 			try {
@@ -1152,6 +1177,72 @@ function multiple(parser, options = {}) {
 			enumerable: false
 		});
 	}
+	{
+		const innerValidate = typeof parser.validateValue === "function" ? parser.validateValue.bind(parser) : void 0;
+		const validateArity = (values) => {
+			if (values.length < min) {
+				const customMessage = options.errors?.tooFew;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(min, values.length) : customMessage : require_message.message`Expected at least ${require_message.text(min.toLocaleString("en"))} values, but got only ${require_message.text(values.length.toLocaleString("en"))}.`
+				};
+			}
+			if (values.length > max) {
+				const customMessage = options.errors?.tooMany;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(max, values.length) : customMessage : require_message.message`Expected at most ${require_message.text(max.toLocaleString("en"))} values, but got ${require_message.text(values.length.toLocaleString("en"))}.`
+				};
+			}
+			return {
+				success: true,
+				value: values
+			};
+		};
+		Object.defineProperty(resultParser, "validateValue", {
+			value(values) {
+				if (!Array.isArray(values)) {
+					const actualType = values === null ? "null" : typeof values;
+					return require_mode_dispatch.wrapForMode(parser.$mode, {
+						success: false,
+						error: require_message.message`Expected an array of values, but received ${actualType}.`
+					});
+				}
+				const arity = validateArity(values);
+				if (!arity.success) return require_mode_dispatch.wrapForMode(parser.$mode, arity);
+				if (innerValidate == null) return require_mode_dispatch.wrapForMode(parser.$mode, arity);
+				return require_mode_dispatch.dispatchByMode(parser.$mode, () => {
+					let changed = false;
+					const normalized = [];
+					for (const v of values) {
+						const r = innerValidate(v);
+						if (!r.success) return r;
+						normalized.push(r.value);
+						if (r.value !== v) changed = true;
+					}
+					return {
+						success: true,
+						value: changed ? normalized : values
+					};
+				}, async () => {
+					let changed = false;
+					const normalized = [];
+					for (const v of values) {
+						const r = await innerValidate(v);
+						if (!r.success) return r;
+						normalized.push(r.value);
+						if (r.value !== v) changed = true;
+					}
+					return {
+						success: true,
+						value: changed ? normalized : values
+					};
+				});
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata?.source != null) {
 		const innerSource = parser.dependencyMetadata.source;
 		Object.defineProperty(resultParser, "dependencyMetadata", {
@@ -1279,6 +1370,11 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(nonEmptyParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return nonEmptyParser;
 }
 

package/dist/modifiers.js

@@ -1,6 +1,6 @@
 import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { formatMessage, message, text } from "./message.js";
-import { dispatchByMode, dispatchIterableByMode, mapModeValue } from "./mode-dispatch.js";
+import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./mode-dispatch.js";
 import { composeDependencyMetadata } from "./dependency-metadata.js";
 import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
 
@@ -306,6 +306,20 @@ function optional(parser) {
 			enumerable: false
 		});
 	}
+	if (typeof parser.validateValue === "function") {
+		const innerValidate = parser.validateValue.bind(parser);
+		Object.defineProperty(optionalParser, "validateValue", {
+			value(v) {
+				if (v === void 0) return wrapForMode(parser.$mode, {
+					success: true,
+					value: v
+				});
+				return innerValidate(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata != null) {
 		const composed = composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
@@ -504,6 +518,16 @@ function withDefault(parser, defaultValue, options) {
 			enumerable: false
 		});
 	}
+	if (typeof parser.validateValue === "function") {
+		const innerValidate = parser.validateValue.bind(parser);
+		Object.defineProperty(withDefaultParser, "validateValue", {
+			value(v) {
+				return innerValidate(v);
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata != null) {
 		const composed = composeDependencyMetadata(parser.dependencyMetadata, "withDefault", { defaultValue: () => {
 			let v;
@@ -649,6 +673,7 @@ function map(parser, transform) {
 		}
 	};
 	delete mappedParser.normalizeValue;
+	delete mappedParser.validateValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
 		get() {
 			try {
@@ -1152,6 +1177,72 @@ function multiple(parser, options = {}) {
 			enumerable: false
 		});
 	}
+	{
+		const innerValidate = typeof parser.validateValue === "function" ? parser.validateValue.bind(parser) : void 0;
+		const validateArity = (values) => {
+			if (values.length < min) {
+				const customMessage = options.errors?.tooFew;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(min, values.length) : customMessage : message`Expected at least ${text(min.toLocaleString("en"))} values, but got only ${text(values.length.toLocaleString("en"))}.`
+				};
+			}
+			if (values.length > max) {
+				const customMessage = options.errors?.tooMany;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(max, values.length) : customMessage : message`Expected at most ${text(max.toLocaleString("en"))} values, but got ${text(values.length.toLocaleString("en"))}.`
+				};
+			}
+			return {
+				success: true,
+				value: values
+			};
+		};
+		Object.defineProperty(resultParser, "validateValue", {
+			value(values) {
+				if (!Array.isArray(values)) {
+					const actualType = values === null ? "null" : typeof values;
+					return wrapForMode(parser.$mode, {
+						success: false,
+						error: message`Expected an array of values, but received ${actualType}.`
+					});
+				}
+				const arity = validateArity(values);
+				if (!arity.success) return wrapForMode(parser.$mode, arity);
+				if (innerValidate == null) return wrapForMode(parser.$mode, arity);
+				return dispatchByMode(parser.$mode, () => {
+					let changed = false;
+					const normalized = [];
+					for (const v of values) {
+						const r = innerValidate(v);
+						if (!r.success) return r;
+						normalized.push(r.value);
+						if (r.value !== v) changed = true;
+					}
+					return {
+						success: true,
+						value: changed ? normalized : values
+					};
+				}, async () => {
+					let changed = false;
+					const normalized = [];
+					for (const v of values) {
+						const r = await innerValidate(v);
+						if (!r.success) return r;
+						normalized.push(r.value);
+						if (r.value !== v) changed = true;
+					}
+					return {
+						success: true,
+						value: changed ? normalized : values
+					};
+				});
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (parser.dependencyMetadata?.source != null) {
 		const innerSource = parser.dependencyMetadata.source;
 		Object.defineProperty(resultParser, "dependencyMetadata", {
@@ -1279,6 +1370,11 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(nonEmptyParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return nonEmptyParser;
 }
 

package/dist/parser.cjs

@@ -68,7 +68,7 @@ function createParserContext(frame, exec) {
 }
 function injectAnnotationsIntoState(state, options) {
 	const annotations = options?.annotations;
-	if (annotations == null) return state;
+	if (!require_annotations.hasMeaningfulAnnotations(annotations)) return state;
 	return require_annotations.injectAnnotations(state, annotations);
 }
 /**
@@ -97,7 +97,7 @@ function injectAnnotationsIntoState(state, options) {
 */
 function parseSync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_annotations.hasMeaningfulAnnotations(options?.annotations) || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
@@ -169,7 +169,7 @@ function isBufferUnchanged(previous, current) {
 */
 async function parseAsync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_annotations.hasMeaningfulAnnotations(options?.annotations) || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",

package/dist/parser.d.cts

@@ -262,6 +262,50 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   normalizeValue?(value: TValue): TValue;
+  /**
+   * Optionally re-validates a value as if it had been parsed from CLI
+   * input, surfacing any constraint violations from the underlying value
+   * parser (e.g., regex patterns, numeric bounds, `choice()` values).
+   *
+   * Wrappers like `bindEnv()` and `bindConfig()` call this on fallback
+   * values — environment variables parsed by a looser env parser,
+   * configured defaults, and values loaded from config files — so that
+   * those values obey the same validation semantics as CLI input.
+   * Without it, parser constraints can be silently bypassed through
+   * fallback paths.
+   *
+   * Built-in primitive parsers ({@link option}, {@link argument})
+   * implement this method by round-tripping the value through the inner
+   * {@link ValueParser.format} and {@link ValueParser.parse} calls: the
+   * value is serialized back to a string and re-parsed, which re-runs
+   * every constraint check.  Combinator wrappers ({@link optional},
+   * {@link withDefault}) forward this method from their inner parser.
+   * {@link map} intentionally does *not* forward it because the mapping
+   * function is one-way: the mapped output type no longer corresponds
+   * to the inner parser's constraints.  Exclusive combinators
+   * ({@link or}, `longestMatch()`) and multi-source combinators
+   * (`merge()`, `concat()`) intentionally do not implement this method
+   * because the active branch or key ownership is unknown at validation
+   * time.
+   *
+   * Implementations must wrap any *exception* thrown by `format()` in
+   * `try`/`catch` and return the original value as a successful
+   * {@link ValueParserResult}.  This specifically protects
+   * dependency-derived parsers whose factory cannot run without the
+   * current dependency value, and custom value parsers whose `format()`
+   * intentionally throws for unsupported inputs.  Values that
+   * `format()` successfully serializes to a string are always re-parsed,
+   * and any resulting parse failure is propagated — they represent the
+   * bug class this method exists to surface.
+   *
+   * @param value The candidate value to validate.
+   * @returns A {@link ValueParserResult} indicating success (with the
+   *          possibly-canonicalized value) or failure (with an error
+   *          message).  In async mode, returns a `Promise` resolving to
+   *          the result.
+   * @since 1.0.0
+   */
+  validateValue?(value: TValue): ModeValue<M, ValueParserResult<TValue>>;
   /**
    * Internal dependency metadata describing this parser's dependency
    * capabilities.  Used by the dependency runtime to resolve dependencies

package/dist/parser.d.ts

@@ -262,6 +262,50 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * @since 1.0.0
    */
   normalizeValue?(value: TValue): TValue;
+  /**
+   * Optionally re-validates a value as if it had been parsed from CLI
+   * input, surfacing any constraint violations from the underlying value
+   * parser (e.g., regex patterns, numeric bounds, `choice()` values).
+   *
+   * Wrappers like `bindEnv()` and `bindConfig()` call this on fallback
+   * values — environment variables parsed by a looser env parser,
+   * configured defaults, and values loaded from config files — so that
+   * those values obey the same validation semantics as CLI input.
+   * Without it, parser constraints can be silently bypassed through
+   * fallback paths.
+   *
+   * Built-in primitive parsers ({@link option}, {@link argument})
+   * implement this method by round-tripping the value through the inner
+   * {@link ValueParser.format} and {@link ValueParser.parse} calls: the
+   * value is serialized back to a string and re-parsed, which re-runs
+   * every constraint check.  Combinator wrappers ({@link optional},
+   * {@link withDefault}) forward this method from their inner parser.
+   * {@link map} intentionally does *not* forward it because the mapping
+   * function is one-way: the mapped output type no longer corresponds
+   * to the inner parser's constraints.  Exclusive combinators
+   * ({@link or}, `longestMatch()`) and multi-source combinators
+   * (`merge()`, `concat()`) intentionally do not implement this method
+   * because the active branch or key ownership is unknown at validation
+   * time.
+   *
+   * Implementations must wrap any *exception* thrown by `format()` in
+   * `try`/`catch` and return the original value as a successful
+   * {@link ValueParserResult}.  This specifically protects
+   * dependency-derived parsers whose factory cannot run without the
+   * current dependency value, and custom value parsers whose `format()`
+   * intentionally throws for unsupported inputs.  Values that
+   * `format()` successfully serializes to a string are always re-parsed,
+   * and any resulting parse failure is propagated — they represent the
+   * bug class this method exists to surface.
+   *
+   * @param value The candidate value to validate.
+   * @returns A {@link ValueParserResult} indicating success (with the
+   *          possibly-canonicalized value) or failure (with an error
+   *          message).  In async mode, returns a `Promise` resolving to
+   *          the result.
+   * @since 1.0.0
+   */
+  validateValue?(value: TValue): ModeValue<M, ValueParserResult<TValue>>;
   /**
    * Internal dependency metadata describing this parser's dependency
    * capabilities.  Used by the dependency runtime to resolve dependencies

package/dist/parser.js

@@ -1,4 +1,4 @@
-import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { hasMeaningfulAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { cloneMessage, message } from "./message.js";
 import { cloneUsage, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, isDocEntryHidden } from "./doc.js";
@@ -68,7 +68,7 @@ function createParserContext(frame, exec) {
 }
 function injectAnnotationsIntoState(state, options) {
 	const annotations = options?.annotations;
-	if (annotations == null) return state;
+	if (!hasMeaningfulAnnotations(annotations)) return state;
 	return injectAnnotations(state, annotations);
 }
 /**
@@ -97,7 +97,7 @@ function injectAnnotationsIntoState(state, options) {
 */
 function parseSync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = options?.annotations != null || isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = hasMeaningfulAnnotations(options?.annotations) || isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
@@ -169,7 +169,7 @@ function isBufferUnchanged(previous, current) {
 */
 async function parseAsync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = options?.annotations != null || isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = hasMeaningfulAnnotations(options?.annotations) || isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",

package/dist/primitives.cjs

@@ -438,6 +438,7 @@ function option(...args) {
 	const isAsync = mode === "async";
 	const syncValueParser = valueParser;
 	const dependencyMetadata = valueParser != null ? require_dependency_metadata.extractDependencyMetadata(valueParser) : void 0;
+	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : require_message.message`${require_message.optionNames(optionNames$1)}: ${error}`;
 	const result = {
 		$mode: mode,
 		$valueType: [],
@@ -619,7 +620,6 @@ function option(...args) {
 			};
 		},
 		complete(state, exec) {
-			const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : require_message.message`${require_message.optionNames(optionNames$1)}: ${error}`;
 			const missing = valueParser == null ? {
 				success: true,
 				value: false
@@ -693,6 +693,50 @@ function option(...args) {
 			enumerable: false
 		});
 	}
+	if (valueParser == null) Object.defineProperty(result, "validateValue", {
+		value(v) {
+			if (typeof v !== "boolean") {
+				const actualType = v === null ? "null" : typeof v;
+				return require_mode_dispatch.wrapForMode(mode, {
+					success: false,
+					error: formatInvalidValueError(require_message.message`Expected a boolean value, but received ${actualType}.`)
+				});
+			}
+			return require_mode_dispatch.wrapForMode(mode, {
+				success: true,
+				value: v
+			});
+		},
+		configurable: true,
+		enumerable: false
+	});
+	else if (!require_dependency.isDerivedValueParser(valueParser)) {
+		const vp = valueParser;
+		const wrapParseResult = (parsed) => parsed.success ? parsed : {
+			success: false,
+			error: formatInvalidValueError(parsed.error)
+		};
+		Object.defineProperty(result, "validateValue", {
+			value(v) {
+				let stringified;
+				try {
+					stringified = vp.format(v);
+				} catch {
+					return require_mode_dispatch.wrapForMode(mode, {
+						success: true,
+						value: v
+					});
+				}
+				if (typeof stringified !== "string") return require_mode_dispatch.wrapForMode(mode, {
+					success: true,
+					value: v
+				});
+				return require_mode_dispatch.dispatchByMode(mode, () => wrapParseResult(vp.parse(stringified)), async () => wrapParseResult(await vp.parse(stringified)));
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (valueParser != null) Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -934,6 +978,7 @@ function argument(valueParser, options = {}) {
 	const isAsync = valueParser.$mode === "async";
 	const syncValueParser = valueParser;
 	const dependencyMetadata = require_dependency_metadata.extractDependencyMetadata(valueParser);
+	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : require_message.message`${require_message.metavar(valueParser.metavar)}: ${error}`;
 	const optionPattern = /^--?[a-z0-9-]+$/i;
 	const term = {
 		type: "argument",
@@ -1007,7 +1052,6 @@ function argument(valueParser, options = {}) {
 			});
 		},
 		complete(state, exec) {
-			const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : require_message.message`${require_message.metavar(valueParser.metavar)}: ${error}`;
 			const missing = {
 				success: false,
 				error: options.errors?.endOfInput ?? require_message.message`Expected a ${require_message.metavar(valueParser.metavar)}, but too few arguments.`
@@ -1075,6 +1119,34 @@ function argument(valueParser, options = {}) {
 			enumerable: false
 		});
 	}
+	if (!require_dependency.isDerivedValueParser(valueParser)) {
+		const vp = valueParser;
+		const vpMode = valueParser.$mode;
+		const wrapParseResult = (parsed) => parsed.success ? parsed : {
+			success: false,
+			error: formatInvalidValueError(parsed.error)
+		};
+		Object.defineProperty(result, "validateValue", {
+			value(v) {
+				let stringified;
+				try {
+					stringified = vp.format(v);
+				} catch {
+					return require_mode_dispatch.wrapForMode(vpMode, {
+						success: true,
+						value: v
+					});
+				}
+				if (typeof stringified !== "string") return require_mode_dispatch.wrapForMode(vpMode, {
+					success: true,
+					value: v
+				});
+				return require_mode_dispatch.dispatchByMode(vpMode, () => wrapParseResult(syncValueParser.parse(stringified)), async () => wrapParseResult(await vp.parse(stringified)));
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -1316,6 +1388,11 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(result, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**

package/dist/primitives.js

@@ -3,7 +3,7 @@ import { message, metavar, optionName, optionNames, text, valueSet } from "./mes
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./dependency.js";
 import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
-import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
+import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./mode-dispatch.js";
 import { extractDependencyMetadata } from "./dependency-metadata.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, findSimilar } from "./suggestion.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
@@ -438,6 +438,7 @@ function option(...args) {
 	const isAsync = mode === "async";
 	const syncValueParser = valueParser;
 	const dependencyMetadata = valueParser != null ? extractDependencyMetadata(valueParser) : void 0;
+	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : message`${optionNames(optionNames$1)}: ${error}`;
 	const result = {
 		$mode: mode,
 		$valueType: [],
@@ -619,7 +620,6 @@ function option(...args) {
 			};
 		},
 		complete(state, exec) {
-			const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : message`${optionNames(optionNames$1)}: ${error}`;
 			const missing = valueParser == null ? {
 				success: true,
 				value: false
@@ -693,6 +693,50 @@ function option(...args) {
 			enumerable: false
 		});
 	}
+	if (valueParser == null) Object.defineProperty(result, "validateValue", {
+		value(v) {
+			if (typeof v !== "boolean") {
+				const actualType = v === null ? "null" : typeof v;
+				return wrapForMode(mode, {
+					success: false,
+					error: formatInvalidValueError(message`Expected a boolean value, but received ${actualType}.`)
+				});
+			}
+			return wrapForMode(mode, {
+				success: true,
+				value: v
+			});
+		},
+		configurable: true,
+		enumerable: false
+	});
+	else if (!isDerivedValueParser(valueParser)) {
+		const vp = valueParser;
+		const wrapParseResult = (parsed) => parsed.success ? parsed : {
+			success: false,
+			error: formatInvalidValueError(parsed.error)
+		};
+		Object.defineProperty(result, "validateValue", {
+			value(v) {
+				let stringified;
+				try {
+					stringified = vp.format(v);
+				} catch {
+					return wrapForMode(mode, {
+						success: true,
+						value: v
+					});
+				}
+				if (typeof stringified !== "string") return wrapForMode(mode, {
+					success: true,
+					value: v
+				});
+				return dispatchByMode(mode, () => wrapParseResult(vp.parse(stringified)), async () => wrapParseResult(await vp.parse(stringified)));
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	if (valueParser != null) Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -934,6 +978,7 @@ function argument(valueParser, options = {}) {
 	const isAsync = valueParser.$mode === "async";
 	const syncValueParser = valueParser;
 	const dependencyMetadata = extractDependencyMetadata(valueParser);
+	const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : message`${metavar(valueParser.metavar)}: ${error}`;
 	const optionPattern = /^--?[a-z0-9-]+$/i;
 	const term = {
 		type: "argument",
@@ -1007,7 +1052,6 @@ function argument(valueParser, options = {}) {
 			});
 		},
 		complete(state, exec) {
-			const formatInvalidValueError = (error) => options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(error) : options.errors.invalidValue : message`${metavar(valueParser.metavar)}: ${error}`;
 			const missing = {
 				success: false,
 				error: options.errors?.endOfInput ?? message`Expected a ${metavar(valueParser.metavar)}, but too few arguments.`
@@ -1075,6 +1119,34 @@ function argument(valueParser, options = {}) {
 			enumerable: false
 		});
 	}
+	if (!isDerivedValueParser(valueParser)) {
+		const vp = valueParser;
+		const vpMode = valueParser.$mode;
+		const wrapParseResult = (parsed) => parsed.success ? parsed : {
+			success: false,
+			error: formatInvalidValueError(parsed.error)
+		};
+		Object.defineProperty(result, "validateValue", {
+			value(v) {
+				let stringified;
+				try {
+					stringified = vp.format(v);
+				} catch {
+					return wrapForMode(vpMode, {
+						success: true,
+						value: v
+					});
+				}
+				if (typeof stringified !== "string") return wrapForMode(vpMode, {
+					success: true,
+					value: v
+				});
+				return dispatchByMode(vpMode, () => wrapParseResult(syncValueParser.parse(stringified)), async () => wrapParseResult(await vp.parse(stringified)));
+			},
+			configurable: true,
+			enumerable: false
+		});
+	}
 	Object.defineProperty(result, "placeholder", {
 		get() {
 			try {
@@ -1316,6 +1388,11 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(result, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
 	return result;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1758+0d05b449",
+  "version": "1.0.0-dev.1772+a1288062",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",