@optique/config 1.0.0-dev.908 → 1.0.0

package/dist/index.js

@@ -1,305 +1,46 @@
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { annotationKey, getAnnotations } from "@optique/core/annotations";
+import { getAnnotations } from "@optique/core/annotations";
+import { defineTraits, delegateSuggestNodes, inheritAnnotations, injectAnnotations, mapModeValue, mapSourceMetadata, wrapForMode } from "@optique/core/extension";
 import { message } from "@optique/core/message";
-import { mapModeValue, wrapForMode } from "@optique/core/mode-dispatch";
 
 //#region src/index.ts
-const deferPromptUntilConfigResolvesKey = Symbol.for("@optique/config/deferPromptUntilResolved");
-const phase1ConfigAnnotationsKey = Symbol.for("@optique/config/phase1PromptAnnotations");
-const phase2UndefinedParsedValueKey = Symbol.for("@optique/config/phase2UndefinedParsedValue");
-const deferredPromptValueKey = Symbol.for("@optique/inquirer/deferredPromptValue");
-/**
-* Internal registry for active config data during config context execution.
-* This is a workaround for the limitation that object() doesn't propagate
-* annotations to child field parsers.
-* @internal
-*/
-const activeConfigRegistry = /* @__PURE__ */ new Map();
-/**
-* Internal registry for active config metadata during config context execution.
-* @internal
-*/
-const activeConfigMetaRegistry = /* @__PURE__ */ new Map();
 const phase1ConfigAnnotationMarker = Symbol("@optique/config/phase1Annotation");
-function isDeferredPromptValue(value) {
-	return value != null && typeof value === "object" && deferredPromptValueKey in value;
-}
-function isPhase2UndefinedParsedValue(value) {
-	return value != null && typeof value === "object" && phase2UndefinedParsedValueKey in value;
-}
-function isPlainObject(value) {
-	const proto = Object.getPrototypeOf(value);
-	return proto === Object.prototype || proto === null;
+function getTypeName(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "array";
+	return typeof value;
 }
-function shouldSkipCollectionOwnKey(value, key) {
-	if (Array.isArray(value)) return key === "length" || typeof key === "string" && Number.isInteger(Number(key)) && String(Number(key)) === key;
-	return false;
-}
-function containsDeferredPromptValuesInOwnProperties(value, seen) {
-	for (const key of Reflect.ownKeys(value)) {
-		if (shouldSkipCollectionOwnKey(value, key)) continue;
-		const descriptor = Object.getOwnPropertyDescriptor(value, key);
-		if (descriptor != null && "value" in descriptor && containsDeferredPromptValues(descriptor.value, seen)) return true;
-	}
-	return false;
-}
-function copySanitizedOwnProperties(source, target, seen) {
-	for (const key of Reflect.ownKeys(source)) {
-		if (shouldSkipCollectionOwnKey(source, key)) continue;
-		const descriptor = Object.getOwnPropertyDescriptor(source, key);
-		if (descriptor == null) continue;
-		if ("value" in descriptor) descriptor.value = stripDeferredPromptValues(descriptor.value, seen);
-		Object.defineProperty(target, key, descriptor);
-	}
-}
-function containsDeferredPromptValues(value, seen = /* @__PURE__ */ new WeakSet()) {
-	if (isDeferredPromptValue(value)) return true;
-	if (value == null || typeof value !== "object") return false;
-	if (seen.has(value)) return false;
-	seen.add(value);
-	if (Array.isArray(value)) {
-		if (value.some((item) => containsDeferredPromptValues(item, seen))) return true;
-		return containsDeferredPromptValuesInOwnProperties(value, seen);
-	}
-	if (value instanceof Set) {
-		for (const entryValue of value) if (containsDeferredPromptValues(entryValue, seen)) return true;
-		return containsDeferredPromptValuesInOwnProperties(value, seen);
-	}
-	if (value instanceof Map) {
-		for (const [key, entryValue] of value) if (containsDeferredPromptValues(key, seen) || containsDeferredPromptValues(entryValue, seen)) return true;
-		return containsDeferredPromptValuesInOwnProperties(value, seen);
-	}
-	return containsDeferredPromptValuesInOwnProperties(value, seen);
-}
-const SANITIZE_FAILED = Symbol("sanitizeFailed");
-const activeSanitizations = /* @__PURE__ */ new WeakMap();
-function callWithSanitizedOwnProperties(target, fn, args, strip, seen) {
-	let active = activeSanitizations.get(target);
-	if (active != null) active.count++;
-	else {
-		const saved = /* @__PURE__ */ new Map();
-		const sanitizedValues = /* @__PURE__ */ new Map();
-		for (const key of Reflect.ownKeys(target)) {
-			const desc = Object.getOwnPropertyDescriptor(target, key);
-			if (desc != null && "value" in desc) {
-				let stripped;
-				try {
-					stripped = strip(desc.value, seen);
-				} catch {
-					for (const [k, d] of saved) try {
-						Object.defineProperty(target, k, d);
-					} catch {}
-					return SANITIZE_FAILED;
-				}
-				if (stripped !== desc.value) try {
-					Object.defineProperty(target, key, {
-						...desc,
-						value: stripped
-					});
-					saved.set(key, desc);
-					sanitizedValues.set(key, stripped);
-				} catch {
-					for (const [k, d] of saved) try {
-						Object.defineProperty(target, k, d);
-					} catch {}
-					return SANITIZE_FAILED;
-				}
-			}
-		}
-		active = {
-			saved,
-			sanitizedValues,
-			count: 1
-		};
-		activeSanitizations.set(target, active);
-	}
-	function release() {
-		active.count--;
-		if (active.count === 0) {
-			activeSanitizations.delete(target);
-			for (const [key, desc] of active.saved) try {
-				const current = Object.getOwnPropertyDescriptor(target, key);
-				if (current == null) continue;
-				if ("value" in current && current.value !== active.sanitizedValues.get(key)) continue;
-				Object.defineProperty(target, key, desc);
-			} catch {}
-		}
-	}
-	let result;
-	try {
-		result = fn.apply(target, args);
-	} catch (e) {
-		release();
-		throw e;
-	}
-	if (result instanceof Promise) return result.then((v) => {
-		release();
-		return strip(v, seen);
-	}, (e) => {
-		release();
-		throw e;
-	});
-	release();
-	return strip(result, seen);
-}
-function callMethodOnSanitizedTarget(fn, proxy, target, args, strip, seen) {
-	const result = callWithSanitizedOwnProperties(target, fn, args, strip, seen);
-	if (result !== SANITIZE_FAILED) return result;
-	const fallback = fn.apply(proxy, args);
-	if (fallback instanceof Promise) return fallback.then((v) => strip(v, seen));
-	return strip(fallback, seen);
-}
-function createSanitizedNonPlainView(value, seen) {
-	const methodCache = /* @__PURE__ */ new Map();
-	const proxy = new Proxy(value, {
-		get(target, key, receiver) {
-			const descriptor = Object.getOwnPropertyDescriptor(target, key);
-			if (descriptor != null && "value" in descriptor) {
-				if (!descriptor.configurable && !descriptor.writable) return descriptor.value;
-				const val = stripDeferredPromptValues(descriptor.value, seen);
-				if (typeof val === "function") {
-					if (!descriptor.configurable && !descriptor.writable || /^class[\s{]/.test(Function.prototype.toString.call(val))) return val;
-					const cached = methodCache.get(key);
-					if (cached != null && cached.fn === val) return cached.wrapper;
-					const wrapper = function(...args) {
-						if (this !== proxy) return stripDeferredPromptValues(val.apply(this, args), seen);
-						return callMethodOnSanitizedTarget(val, proxy, target, args, stripDeferredPromptValues, seen);
-					};
-					methodCache.set(key, {
-						fn: val,
-						wrapper
-					});
-					return wrapper;
-				}
-				return val;
-			}
-			let isAccessor = false;
-			for (let proto = target; proto != null; proto = Object.getPrototypeOf(proto)) {
-				const d = Object.getOwnPropertyDescriptor(proto, key);
-				if (d != null) {
-					isAccessor = "get" in d;
-					break;
-				}
-			}
-			const result = Reflect.get(target, key, receiver);
-			if (typeof result === "function") {
-				if (/^class[\s{]/.test(Function.prototype.toString.call(result))) return result;
-				if (!isAccessor) {
-					const cached = methodCache.get(key);
-					if (cached != null && cached.fn === result) return cached.wrapper;
-					const wrapper = function(...args) {
-						if (this !== proxy) return stripDeferredPromptValues(result.apply(this, args), seen);
-						return callMethodOnSanitizedTarget(result, proxy, target, args, stripDeferredPromptValues, seen);
-					};
-					methodCache.set(key, {
-						fn: result,
-						wrapper
-					});
-					return wrapper;
-				}
-				return function(...args) {
-					if (this !== proxy) return stripDeferredPromptValues(result.apply(this, args), seen);
-					return callMethodOnSanitizedTarget(result, proxy, target, args, stripDeferredPromptValues, seen);
-				};
-			}
-			return stripDeferredPromptValues(result, seen);
-		},
-		getOwnPropertyDescriptor(target, key) {
-			const descriptor = Object.getOwnPropertyDescriptor(target, key);
-			if (descriptor == null || !("value" in descriptor)) return descriptor;
-			if (!descriptor.configurable && !descriptor.writable) return descriptor;
-			return {
-				...descriptor,
-				value: stripDeferredPromptValues(descriptor.value, seen)
-			};
-		}
-	});
-	seen.set(value, proxy);
-	return proxy;
-}
-function stripDeferredPromptValues(value, seen = /* @__PURE__ */ new WeakMap()) {
-	if (isDeferredPromptValue(value)) return void 0;
-	if (value == null || typeof value !== "object") return value;
-	const cached = seen.get(value);
-	if (cached !== void 0) return cached;
-	if (Array.isArray(value)) {
-		if (!containsDeferredPromptValues(value)) return value;
-		const clone$1 = new Array(value.length);
-		seen.set(value, clone$1);
-		for (let i = 0; i < value.length; i++) clone$1[i] = stripDeferredPromptValues(value[i], seen);
-		copySanitizedOwnProperties(value, clone$1, seen);
-		return clone$1;
-	}
-	if (value instanceof Set) {
-		if (!containsDeferredPromptValues(value)) return value;
-		const clone$1 = /* @__PURE__ */ new Set();
-		seen.set(value, clone$1);
-		for (const entryValue of value) clone$1.add(stripDeferredPromptValues(entryValue, seen));
-		copySanitizedOwnProperties(value, clone$1, seen);
-		return clone$1;
-	}
-	if (value instanceof Map) {
-		if (!containsDeferredPromptValues(value)) return value;
-		const clone$1 = /* @__PURE__ */ new Map();
-		seen.set(value, clone$1);
-		for (const [key, entryValue] of value) clone$1.set(stripDeferredPromptValues(key, seen), stripDeferredPromptValues(entryValue, seen));
-		copySanitizedOwnProperties(value, clone$1, seen);
-		return clone$1;
-	}
-	if (!isPlainObject(value)) return containsDeferredPromptValues(value) ? createSanitizedNonPlainView(value, seen) : value;
-	if (!containsDeferredPromptValues(value)) return value;
-	const clone = Object.create(Object.getPrototypeOf(value));
-	seen.set(value, clone);
-	for (const key of Reflect.ownKeys(value)) {
-		const descriptor = Object.getOwnPropertyDescriptor(value, key);
-		if (descriptor == null) continue;
-		if ("value" in descriptor) descriptor.value = stripDeferredPromptValues(descriptor.value, seen);
-		Object.defineProperty(clone, key, descriptor);
-	}
-	return clone;
+function isPromiseLike(value) {
+	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
 }
 /**
-* Sets active config data for a context.
-* @internal
+* Detects native Promises and cross-realm Promises.  Cross-realm
+* Promises fail `instanceof Promise` but still carry the spec-required
+* `Symbol.toStringTag === "Promise"`.  Domain objects that merely
+* define a `then()` method are not matched unless they also set
+* `Symbol.toStringTag` to `"Promise"`.
 */
-function setActiveConfig(contextId, data) {
-	activeConfigRegistry.set(contextId, data);
+function isPromise(value) {
+	if (value instanceof Promise) return true;
+	if (value == null || typeof value !== "object" && typeof value !== "function") return false;
+	return isPromiseLike(value) && value[Symbol.toStringTag] === "Promise";
 }
-/**
-* Gets active config data for a context.
-* @internal
-*/
-function getActiveConfig(contextId) {
-	return activeConfigRegistry.get(contextId);
+function validateLoadResult(loaded) {
+	if (loaded == null) return void 0;
+	if (typeof loaded !== "object" || Array.isArray(loaded)) throw new TypeError(`Expected load() to return an object, but got: ${getTypeName(loaded)}.`);
+	if (!("config" in loaded)) throw new TypeError("Expected load() result to have a config property.");
+	const result = loaded;
+	if (isPromise(result.config)) throw new TypeError("Expected config in load() result to not be a Promise. Resolve the Promise before returning.");
+	if (isPromise(result.meta)) throw new TypeError("Expected meta in load() result to not be a Promise. Resolve the Promise before returning.");
+	return loaded;
 }
-/**
-* Clears active config data for a context.
-* @internal
-*/
-function clearActiveConfig(contextId) {
-	activeConfigRegistry.delete(contextId);
-}
-/**
-* Sets active config metadata for a context.
-* @internal
-*/
-function setActiveConfigMeta(contextId, meta) {
-	activeConfigMetaRegistry.set(contextId, meta);
-}
-/**
-* Gets active config metadata for a context.
-* @internal
-*/
-function getActiveConfigMeta(contextId) {
-	return activeConfigMetaRegistry.get(contextId);
-}
-/**
-* Clears active config metadata for a context.
-* @internal
-*/
-function clearActiveConfigMeta(contextId) {
-	activeConfigMetaRegistry.delete(contextId);
+function isStandardSchema(value) {
+	if (value == null || typeof value !== "object" && typeof value !== "function") return false;
+	if (!("~standard" in value)) return false;
+	const standard = value["~standard"];
+	if (standard == null || typeof standard !== "object" && typeof standard !== "function") return false;
+	return typeof standard.validate === "function";
 }
 function isErrnoException(error) {
 	return typeof error === "object" && error !== null && "code" in error;
@@ -325,13 +66,24 @@ function validateWithSchema(schema, rawData) {
 *
 * The config context implements the `SourceContext` interface and can be used
 * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
-* *@optique/run* to provide configuration file support.
+* *@optique/run* to provide configuration file support. Each runner call
+* receives its own annotation snapshot, so the same `ConfigContext`
+* instance can be reused safely across independent or concurrent runs.
+* When calling `context.getAnnotations()` manually, omit the request for a
+* phase-1 snapshot or pass `{ phase: "phase2", parsed }` for a phase-two
+* snapshot, then thread the returned annotations into low-level APIs such
+* as `parse()`, `parseAsync()`, `parser.complete()`, `suggest()`, or
+* `getDocPage()`. Calling `getAnnotations()` by itself does not affect
+* later parses unless those returned annotations are explicitly threaded
+* into a low-level API call.
 *
 * @template T The output type of the config schema.
 * @template TConfigMeta The metadata type for config sources.
 * @param options Configuration options including schema and optional file
 *   parser.
 * @returns A config context that can be used with `bindConfig()` and runners.
+* @throws {TypeError} If `schema` is not a valid Standard Schema object.
+* @throws {TypeError} If `fileParser` is provided but is not a function.
 * @since 0.10.0
 *
 * @example
@@ -348,46 +100,58 @@ function validateWithSchema(schema, rawData) {
 * ```
 */
 function createConfigContext(options) {
+	const rawSchema = options.schema;
+	if (!isStandardSchema(rawSchema)) throw new TypeError(`Expected schema to be a Standard Schema object, but got: ${getTypeName(rawSchema)}.`);
+	const rawFileParser = options.fileParser;
+	if (rawFileParser !== void 0 && typeof rawFileParser !== "function") throw new TypeError(`Expected fileParser to be a function, but got: ${getTypeName(rawFileParser)}.`);
 	const contextId = Symbol(`@optique/config:${Math.random()}`);
 	const context = {
 		id: contextId,
-		schema: options.schema,
-		mode: "dynamic",
-		[phase1ConfigAnnotationsKey](parsed, annotations) {
-			if (parsed === void 0) return { [contextId]: phase1ConfigAnnotationMarker };
+		schema: rawSchema,
+		phase: "two-pass",
+		getInternalAnnotations(request, annotations) {
+			if (request.phase === "phase1") return { [contextId]: phase1ConfigAnnotationMarker };
 			return Object.getOwnPropertySymbols(annotations).includes(contextId) ? void 0 : { [contextId]: void 0 };
 		},
-		getAnnotations(parsed, runtimeOptions) {
-			if (parsed === void 0) return {};
+		getAnnotations(request, runtimeOptions) {
+			if (request === void 0) return {};
+			if (request === null || typeof request !== "object" || !("phase" in request) || request.phase !== "phase1" && request.phase !== "phase2" || request.phase === "phase2" && !("parsed" in request)) throw new TypeError(`Expected getAnnotations() to receive no request or a SourceContextRequest ({ phase: "phase1" } or { phase: "phase2", parsed }), but got: ${getTypeName(request)}.`);
+			if (request.phase === "phase1") return {};
 			const opts = runtimeOptions;
 			if (!opts || !opts.getConfigPath && !opts.load) throw new TypeError("Either getConfigPath or load must be provided in the runner options when using ConfigContext.");
-			const parsedValue = isPhase2UndefinedParsedValue(parsed) ? void 0 : stripDeferredPromptValues(parsed);
-			const parsedPlaceholder = parsedValue;
+			if (opts.load !== void 0 && typeof opts.load !== "function") throw new TypeError(`Expected load to be a function, but got: ${getTypeName(opts.load)}.`);
+			if (!opts.load && opts.getConfigPath !== void 0 && typeof opts.getConfigPath !== "function") throw new TypeError(`Expected getConfigPath to be a function, but got: ${getTypeName(opts.getConfigPath)}.`);
+			const parsedPlaceholder = request.parsed;
+			const emptyAnnotations = () => ({});
 			const buildAnnotations = (configData, configMeta) => {
-				if (configData === void 0 || configData === null) return {};
-				setActiveConfig(contextId, configData);
-				if (configMeta !== void 0) {
-					setActiveConfigMeta(contextId, configMeta);
-					return { [contextId]: {
-						data: configData,
-						meta: configMeta
-					} };
-				}
+				if (configData === void 0 || configData === null) return emptyAnnotations();
+				if (configMeta !== void 0) return { [contextId]: {
+					data: configData,
+					meta: configMeta
+				} };
 				return { [contextId]: { data: configData } };
 			};
 			const validateAndBuildAnnotations = (rawData, configMeta) => {
-				const validated = validateWithSchema(options.schema, rawData);
+				const validated = validateWithSchema(rawSchema, rawData);
 				if (validated instanceof Promise) return validated.then((configData) => buildAnnotations(configData, configMeta));
 				return buildAnnotations(validated, configMeta);
 			};
 			if (opts.load) {
 				const loaded = opts.load(parsedPlaceholder);
-				if (loaded instanceof Promise) return loaded.then(({ config, meta }) => validateAndBuildAnnotations(config, meta));
-				return validateAndBuildAnnotations(loaded.config, loaded.meta);
+				if (isPromise(loaded)) return Promise.resolve(loaded).then((resolved) => {
+					const validated$1 = validateLoadResult(resolved);
+					if (validated$1 === void 0) return emptyAnnotations();
+					return validateAndBuildAnnotations(validated$1.config, validated$1.meta);
+				});
+				if (isPromiseLike(loaded)) throw new TypeError("Expected load() to return a plain object or Promise, but got a thenable. Use a real Promise instead.");
+				const validated = validateLoadResult(loaded);
+				if (validated === void 0) return emptyAnnotations();
+				return validateAndBuildAnnotations(validated.config, validated.meta);
 			}
 			if (opts.getConfigPath) {
 				const configPath = opts.getConfigPath(parsedPlaceholder);
-				if (!configPath) return {};
+				if (configPath !== void 0 && typeof configPath !== "string") throw new TypeError(`Expected getConfigPath() to return a string or undefined, but got: ${getTypeName(configPath)}.`);
+				if (!configPath) return emptyAnnotations();
 				const absoluteConfigPath = resolve(configPath);
 				const singleFileMeta = {
 					configDir: dirname(absoluteConfigPath),
@@ -396,24 +160,21 @@ function createConfigContext(options) {
 				try {
 					const contents = readFileSync(absoluteConfigPath);
 					let rawData;
-					if (options.fileParser) rawData = options.fileParser(contents);
+					if (rawFileParser) rawData = rawFileParser(contents);
 					else {
 						const text = new TextDecoder().decode(contents);
 						rawData = JSON.parse(text);
 					}
 					return validateAndBuildAnnotations(rawData, singleFileMeta);
 				} catch (error) {
-					if (isErrnoException(error) && error.code === "ENOENT") return {};
+					if (isErrnoException(error) && error.code === "ENOENT") return emptyAnnotations();
 					if (error instanceof SyntaxError) throw new Error(`Failed to parse config file ${absoluteConfigPath}: ${error.message}`);
 					throw error;
 				}
 			}
-			return {};
+			return emptyAnnotations();
 		},
-		[Symbol.dispose]() {
-			clearActiveConfig(contextId);
-			clearActiveConfigMeta(contextId);
-		}
+		[Symbol.dispose]() {}
 	};
 	return context;
 }
@@ -433,6 +194,12 @@ function createConfigContext(options) {
 * @param parser The parser to bind to config values.
 * @param options Binding options including context, key, and default.
 * @returns A new parser with config fallback behavior.
+* @throws {TypeError} If `key` is not a property key or function.
+* @throws {Error} If the inner parser's {@link Parser.validateValue} hook
+*                 throws while re-validating a fallback value (a
+*                 config-sourced value or the configured `default`) —
+*                 the hook can run even when no CLI tokens are parsed
+*                 (see issue #414).
 * @since 0.10.0
 *
 * @example
@@ -449,16 +216,19 @@ function createConfigContext(options) {
 * ```
 */
 function bindConfig(parser, options) {
+	const keyType = typeof options.key;
+	if (keyType !== "string" && keyType !== "number" && keyType !== "symbol" && keyType !== "function") throw new TypeError(`Expected key to be a property key or function, but got: ${getTypeName(options.key)}.`);
 	const configBindStateKey = Symbol("@optique/config/bindState");
 	function isConfigBindState(value) {
 		return value != null && typeof value === "object" && configBindStateKey in value;
 	}
-	function shouldDeferPromptUntilConfigResolves(state) {
+	function shouldDeferPromptUntilConfigResolves(state, _exec) {
 		const annotations = getAnnotations(state);
 		return annotations?.[options.context.id] === phase1ConfigAnnotationMarker;
 	}
+	const getSuggestInnerState = (state) => isConfigBindState(state) ? state.cliState === void 0 ? inheritAnnotations(state, parser.initialState) : state.cliState : state;
 	const boundParser = {
-		$mode: parser.$mode,
+		mode: parser.mode,
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
@@ -466,7 +236,13 @@ function bindConfig(parser, options) {
 			type: "optional",
 			terms: parser.usage
 		}] : parser.usage,
+		leadingNames: parser.leadingNames,
+		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
+		getSuggestRuntimeNodes(state, path) {
+			const innerState = getSuggestInnerState(state);
+			return delegateSuggestNodes(parser, boundParser, state, path, innerState);
+		},
 		parse: (context) => {
 			const annotations = getAnnotations(context.state);
 			const innerState = isConfigBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
@@ -477,14 +253,14 @@ function bindConfig(parser, options) {
 			const processResult = (result) => {
 				if (result.success) {
 					const cliConsumed = result.consumed.length > 0;
-					const newState$1 = {
+					const newState$1 = injectAnnotations({
 						[configBindStateKey]: true,
 						hasCliValue: cliConsumed,
-						cliState: result.next.state,
-						...annotations && { [annotationKey]: annotations }
-					};
+						cliState: result.next.state
+					}, annotations);
 					return {
 						success: true,
+						...result.provisional ? { provisional: true } : {},
 						next: {
 							...result.next,
 							state: newState$1
@@ -493,11 +269,10 @@ function bindConfig(parser, options) {
 					};
 				}
 				if (result.consumed > 0) return result;
-				const newState = {
+				const newState = injectAnnotations({
 					[configBindStateKey]: true,
-					hasCliValue: false,
-					...annotations && { [annotationKey]: annotations }
-				};
+					hasCliValue: false
+				}, annotations);
 				return {
 					success: true,
 					next: {
@@ -507,53 +282,181 @@ function bindConfig(parser, options) {
 					consumed: []
 				};
 			};
-			return mapModeValue(parser.$mode, parser.parse(innerContext), processResult);
+			return mapModeValue(parser.mode, parser.parse(innerContext), processResult);
 		},
-		complete: (state) => {
-			if (isConfigBindState(state) && state.hasCliValue) return parser.complete(state.cliState);
-			return wrapForMode(parser.$mode, getConfigOrDefault(state, options));
+		complete: (state, exec) => {
+			if (isConfigBindState(state) && state.hasCliValue) return parser.complete(state.cliState, exec);
+			return getConfigOrDefault(state, options, parser.mode, parser);
 		},
-		suggest: parser.suggest,
-		[deferPromptUntilConfigResolvesKey]: shouldDeferPromptUntilConfigResolves,
+		suggest: (context, prefix) => {
+			const innerState = getSuggestInnerState(context.state);
+			const innerContext = innerState !== context.state ? {
+				...context,
+				state: innerState
+			} : context;
+			return parser.suggest(innerContext, prefix);
+		},
+		shouldDeferCompletion: shouldDeferPromptUntilConfigResolves,
 		getDocFragments(state, upperDefaultValue) {
 			const defaultValue = upperDefaultValue ?? options.default;
 			return parser.getDocFragments(state, defaultValue);
 		}
 	};
+	defineTraits(boundParser, {
+		inheritsAnnotations: true,
+		completesFromSource: true
+	});
+	if ("placeholder" in parser) Object.defineProperty(boundParser, "placeholder", {
+		get() {
+			return parser.placeholder;
+		},
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.normalizeValue === "function") Object.defineProperty(boundParser, "normalizeValue", {
+		value: parser.normalizeValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	if (typeof parser.validateValue === "function") Object.defineProperty(boundParser, "validateValue", {
+		value: parser.validateValue.bind(parser),
+		configurable: true,
+		enumerable: false
+	});
+	const dependencyMetadata = mapSourceMetadata(parser, (sourceMetadata) => ({
+		...sourceMetadata,
+		getMissingSourceValue: sourceMetadata.preservesSourceValue !== false && options.default !== void 0 ? () => {
+			if (typeof parser.validateValue === "function") return parser.validateValue(options.default);
+			return {
+				success: true,
+				value: options.default
+			};
+		} : void 0,
+		extractSourceValue: (state) => {
+			if (!isConfigBindState(state)) {
+				if (sourceMetadata.preservesSourceValue) return getConfigSourceValue(state, options, state, sourceMetadata.extractSourceValue, parser);
+				return sourceMetadata.extractSourceValue(state);
+			}
+			if (state.hasCliValue) return sourceMetadata.extractSourceValue(state.cliState);
+			const fallbackState = state.cliState ?? state;
+			if (!sourceMetadata.preservesSourceValue) return sourceMetadata.extractSourceValue(fallbackState);
+			return getConfigSourceValue(state, options, fallbackState, sourceMetadata.extractSourceValue, parser);
+		}
+	}));
+	if (dependencyMetadata != null) Object.defineProperty(boundParser, "dependencyMetadata", {
+		value: dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	return boundParser;
 }
 /**
 * Helper function to get value from config or default.
-* Checks both annotations (for top-level parsers) and the active config
-* registry (for parsers nested inside object() when used with context-aware
-* runners).
+* Reads only from explicit annotations carried by the current parse state.
+*
+* When `innerParser.validateValue` is available, the returned fallback
+* value is routed through it so that the inner CLI parser's constraints
+* (regex patterns, numeric bounds, choices, etc.) are enforced on
+* config-sourced values and configured defaults (see issue #414).  If
+* `innerParser` is absent or does not implement `validateValue` (for
+* example, the inner parser is wrapped in `map()`), the value is
+* returned unchanged to preserve existing behavior.
+*
+* @throws {TypeError} If the key callback returns a Promise or thenable.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` (via
+*                 {@link validateFallbackValue}) while revalidating a
+*                 config-sourced value or the configured `default`
+*                 against the inner CLI parser's constraints (see
+*                 issue #414).
 */
-function getConfigOrDefault(state, options) {
+function getConfigOrDefault(state, options, mode, innerParser) {
 	const annotations = getAnnotations(state);
 	const contextId = options.context.id;
 	const annotationValue = annotations?.[contextId];
-	let configData = annotationValue?.data;
-	let configMeta = annotationValue?.meta;
-	if (configData === void 0 || configData === null) {
-		configData = getActiveConfig(contextId);
-		configMeta = getActiveConfigMeta(contextId);
-	}
+	const configData = annotationValue?.data;
+	const configMeta = annotationValue?.meta;
 	let configValue;
-	if (configData !== void 0 && configData !== null) if (typeof options.key === "function") configValue = options.key(configData, configMeta);
-	else configValue = configData[options.key];
-	if (configValue !== void 0) return {
+	if (configData !== void 0 && configData !== null) if (typeof options.key === "function") {
+		configValue = options.key(configData, configMeta);
+		if (configValue != null && (typeof configValue === "object" || typeof configValue === "function") && "then" in configValue && typeof configValue.then === "function") throw new TypeError("The key callback must return a synchronous value, but got a thenable.");
+	} else configValue = configData[options.key];
+	if (configValue !== void 0) return validateFallbackValue(mode, innerParser, configValue);
+	if (options.default !== void 0) return validateFallbackValue(mode, innerParser, options.default);
+	return wrapForMode(mode, {
+		success: false,
+		error: message`Missing required configuration value.`
+	});
+}
+/**
+* Routes a (successful) fallback value through the inner parser's
+* `validateValue()` hook, or returns the value unchanged when no
+* validator is available.  See {@link getConfigOrDefault} for context.
+*
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` while revalidating the
+*                 fallback value against the inner CLI parser's
+*                 constraints (see issue #414).  When the hook returns
+*                 a failed {@link Result} the failure is propagated
+*                 through the return value; only an actual exception
+*                 thrown by the hook escapes through this path.
+*/
+function validateFallbackValue(mode, innerParser, value) {
+	if (innerParser == null || typeof innerParser.validateValue !== "function") return wrapForMode(mode, {
 		success: true,
-		value: configValue
+		value
+	});
+	return innerParser.validateValue(value);
+}
+/**
+* Resolves a config-backed dependency source with fallback priority.
+*
+* This first checks annotations via {@link getConfigOrDefault}. If no
+* config-backed value is available, it falls back to `options.default` and
+* finally delegates to the wrapped parser's source extractor.
+*
+* When `innerParser` exposes `validateValue`, the returned fallback is
+* routed through it so that the inner CLI parser's constraints are
+* enforced on config-sourced source values and configured defaults
+* (see issue #414).  This helper is only invoked from the
+* `preservesSourceValue: true` branch in {@link bindConfig}, so the
+* source value type is guaranteed to equal `TValue`.
+*
+* @param state The wrapper state, which may carry config annotations.
+* @param options The binding options with lookup and default settings.
+* @param innerState The unwrapped inner state for delegated extraction.
+* @param extractInnerSourceValue The wrapped parser's source extractor.
+* @param innerParser The wrapped parser, used to revalidate fallback values.
+* @returns The resolved source value, an async source value, or `undefined`.
+* @throws {TypeError} If {@link getConfigOrDefault} rejects a thenable-returning
+*                     key callback.
+* @throws {Error} Propagates errors thrown by
+*                 `innerParser.validateValue()` (via
+*                 {@link getConfigOrDefault} / {@link validateFallbackValue})
+*                 while revalidating a config-sourced value or the
+*                 configured `default` against the inner CLI parser's
+*                 constraints (see issue #414).
+*/
+function getConfigSourceValue(state, options, innerState, extractInnerSourceValue, innerParser) {
+	const annotations = getAnnotations(state);
+	const contextId = options.context.id;
+	const annotationValue = annotations?.[contextId];
+	const configData = annotationValue?.data;
+	const validateFallback = (parsed) => {
+		if (!parsed.success) return parsed;
+		if (innerParser == null || typeof innerParser.validateValue !== "function") return parsed;
+		return innerParser.validateValue(parsed.value);
 	};
-	if (options.default !== void 0) return {
+	if (configData !== void 0 && configData !== null) {
+		const resolved = getConfigOrDefault(state, options, "sync", void 0);
+		if (resolved.success) return validateFallback(resolved);
+	}
+	if (options.default !== void 0) return validateFallback({
 		success: true,
 		value: options.default
-	};
-	return {
-		success: false,
-		error: message`Missing required configuration value.`
-	};
+	});
+	return extractInnerSourceValue(innerState);
 }
 
 //#endregion
-export { bindConfig, clearActiveConfig, clearActiveConfigMeta, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };
+export { bindConfig, createConfigContext };