@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/facade.js

@@ -1,295 +1,282 @@
-import { injectAnnotations } from "./annotations.js";
+import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
-import { dispatchByMode } from "./mode-dispatch.js";
+import { validateCommandNames, validateContextIds, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
 import { formatUsage } from "./usage.js";
-import { group, longestMatch, object } from "./constructs.js";
 import { formatDocPage } from "./doc.js";
+import { dispatchByMode } from "./internal/mode-dispatch.js";
+import { createDependencyRuntimeContext } from "./dependency-runtime.js";
+import { createInputTrace } from "./input-trace.js";
+import { createParserContext, getDocPage, suggest, suggestAsync } from "./internal/parser.js";
+import { completeOrExtractPhase2Seed } from "./phase2-seed.js";
+import { group, longestMatch, object } from "./constructs.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
 import { string } from "./valueparser.js";
 import { argument, command, constant, flag, option } from "./primitives.js";
-import { getDocPage, parseAsync, parseSync, suggest, suggestAsync } from "./parser.js";
 
 //#region src/facade.ts
-const phase1ConfigAnnotationsKey = Symbol.for("@optique/config/phase1PromptAnnotations");
-const phase2UndefinedParsedValueKey = Symbol.for("@optique/config/phase2UndefinedParsedValue");
-const deferredPromptValueKey = Symbol.for("@optique/inquirer/deferredPromptValue");
-function isDeferredPromptValue(value$1) {
-	return value$1 != null && typeof value$1 === "object" && deferredPromptValueKey in value$1;
-}
+const SuppressedErrorCtor = typeof SuppressedError === "function" ? SuppressedError : (() => {
+	class SuppressedErrorPolyfill extends Error {
+		error;
+		suppressed;
+		constructor(error, suppressed, message$1) {
+			super(message$1);
+			this.name = "SuppressedError";
+			this.error = error;
+			this.suppressed = suppressed;
+		}
+	}
+	return SuppressedErrorPolyfill;
+})();
 function isPlainObject(value$1) {
 	const proto = Object.getPrototypeOf(value$1);
 	return proto === Object.prototype || proto === null;
 }
-function shouldSkipCollectionOwnKey(value$1, key) {
-	if (Array.isArray(value$1)) return key === "length" || typeof key === "string" && Number.isInteger(Number(key)) && String(Number(key)) === key;
-	return false;
-}
-function containsDeferredPromptValuesInOwnProperties(value$1, seen) {
-	for (const key of Reflect.ownKeys(value$1)) {
-		if (shouldSkipCollectionOwnKey(value$1, key)) continue;
-		const descriptor = Object.getOwnPropertyDescriptor(value$1, key);
-		if (descriptor != null && "value" in descriptor && containsDeferredPromptValuesForContexts(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 = stripDeferredPromptValuesForContexts(descriptor.value, seen);
-		Object.defineProperty(target, key, descriptor);
-	}
-}
-function createArrayCloneLike(value$1) {
-	try {
-		const arrayCtor = value$1.constructor;
-		return Reflect.construct(Array, [value$1.length], arrayCtor);
-	} catch {
-		return new Array(value$1.length);
+function prepareParsedForContexts(parsed, deferred, deferredKeys) {
+	if (!deferred) return parsed;
+	if (deferredKeys != null && deferredKeys.size === 0 && parsed != null && typeof parsed === "object") return void 0;
+	if (deferredKeys != null && deferredKeys.size > 0 && parsed != null && typeof parsed === "object" && !isPlainObject(parsed) && !Array.isArray(parsed)) return void 0;
+	if (deferredKeys != null && deferredKeys.size > 0 && parsed != null && typeof parsed === "object" && (isPlainObject(parsed) || Array.isArray(parsed))) {
+		const getDeferredEntry = (key) => {
+			const entry = deferredKeys.get(key);
+			if (entry !== void 0) return entry;
+			if (typeof key === "string") {
+				const num = Number(key);
+				if (Number.isInteger(num)) return deferredKeys.get(num);
+			} else if (typeof key === "number") return deferredKeys.get(String(key));
+			return void 0;
+		};
+		const ownKeys = Reflect.ownKeys(parsed);
+		let hasMatchingKey = false;
+		for (const key of ownKeys) if (getDeferredEntry(key) !== void 0) {
+			hasMatchingKey = true;
+			break;
+		}
+		if (hasMatchingKey) {
+			const isArray = Array.isArray(parsed);
+			let allDeferred = true;
+			for (const key of ownKeys) {
+				if (isArray && key === "length") continue;
+				const desc = Object.getOwnPropertyDescriptor(parsed, key);
+				if (desc != null && "value" in desc && getDeferredEntry(key) === void 0) {
+					allDeferred = false;
+					break;
+				}
+			}
+			if (allDeferred) return void 0;
+			const clone = isArray ? new Array(parsed.length) : Object.create(Object.getPrototypeOf(parsed));
+			for (const key of ownKeys) {
+				const desc = Object.getOwnPropertyDescriptor(parsed, key);
+				if (desc == null) continue;
+				const entry = getDeferredEntry(key);
+				if ("value" in desc && entry !== void 0) if (entry === null) Object.defineProperty(clone, key, {
+					...desc,
+					value: void 0
+				});
+				else Object.defineProperty(clone, key, {
+					...desc,
+					value: prepareParsedForContexts(desc.value, true, entry)
+				});
+				else Object.defineProperty(clone, key, desc);
+			}
+			return clone;
+		}
+		return void 0;
 	}
+	if (parsed == null || typeof parsed !== "object") return void 0;
+	return parsed;
 }
-function createSetCloneLike(value$1) {
-	try {
-		const setCtor = value$1.constructor;
-		return Reflect.construct(Set, [], setCtor);
-	} catch {
-		return /* @__PURE__ */ new Set();
-	}
+function isBufferUnchanged(previous, current) {
+	return current.length > 0 && current.length === previous.length && current.every((item, i) => item === previous[i]);
 }
-function createMapCloneLike(value$1) {
-	try {
-		const mapCtor = value$1.constructor;
-		return Reflect.construct(Map, [], mapCtor);
-	} catch {
-		return /* @__PURE__ */ new Map();
-	}
+function getFailureProgress(args, buffer, consumedInStep) {
+	return {
+		remainingArgs: buffer.slice(consumedInStep),
+		consumedCount: args.length - buffer.length + consumedInStep
+	};
 }
-function containsDeferredPromptValuesForContexts(value$1, seen = /* @__PURE__ */ new WeakSet()) {
-	if (isDeferredPromptValue(value$1)) return true;
-	if (value$1 == null || typeof value$1 !== "object") return false;
-	if (seen.has(value$1)) return false;
-	seen.add(value$1);
-	if (Array.isArray(value$1)) {
-		if (value$1.some((item) => containsDeferredPromptValuesForContexts(item, seen))) return true;
-		return containsDeferredPromptValuesInOwnProperties(value$1, seen);
-	}
-	if (value$1 instanceof Set) {
-		for (const entryValue of value$1) if (containsDeferredPromptValuesForContexts(entryValue, seen)) return true;
-		return containsDeferredPromptValuesInOwnProperties(value$1, seen);
-	}
-	if (value$1 instanceof Map) {
-		for (const [key, entryValue] of value$1) if (containsDeferredPromptValuesForContexts(key, seen) || containsDeferredPromptValuesForContexts(entryValue, seen)) return true;
-		return containsDeferredPromptValuesInOwnProperties(value$1, seen);
-	}
-	return containsDeferredPromptValuesInOwnProperties(value$1, seen);
+function createParseExec(parser) {
+	return {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		commandPath: [],
+		trace: createInputTrace()
+	};
 }
-function stripDeferredPromptValuesForContexts(value$1, seen = /* @__PURE__ */ new WeakMap()) {
-	if (isDeferredPromptValue(value$1)) return void 0;
-	if (value$1 == null || typeof value$1 !== "object") return value$1;
-	const cached = seen.get(value$1);
-	if (cached !== void 0) return cached;
-	if (Array.isArray(value$1)) {
-		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
-		const clone$1 = createArrayCloneLike(value$1);
-		seen.set(value$1, clone$1);
-		for (let i = 0; i < value$1.length; i++) clone$1[i] = stripDeferredPromptValuesForContexts(value$1[i], seen);
-		copySanitizedOwnProperties(value$1, clone$1, seen);
-		return clone$1;
-	}
-	if (value$1 instanceof Set) {
-		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
-		const clone$1 = createSetCloneLike(value$1);
-		seen.set(value$1, clone$1);
-		for (const entryValue of value$1) clone$1.add(stripDeferredPromptValuesForContexts(entryValue, seen));
-		copySanitizedOwnProperties(value$1, clone$1, seen);
-		return clone$1;
-	}
-	if (value$1 instanceof Map) {
-		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
-		const clone$1 = createMapCloneLike(value$1);
-		seen.set(value$1, clone$1);
-		for (const [key, entryValue] of value$1) clone$1.set(stripDeferredPromptValuesForContexts(key, seen), stripDeferredPromptValuesForContexts(entryValue, seen));
-		copySanitizedOwnProperties(value$1, clone$1, seen);
-		return clone$1;
-	}
-	if (!isPlainObject(value$1)) {
-		if (!containsDeferredPromptValuesForContexts(value$1)) return value$1;
-		return createSanitizedNonPlainContextView(value$1, seen);
-	}
-	const clone = Object.create(Object.getPrototypeOf(value$1));
-	seen.set(value$1, clone);
-	for (const key of Reflect.ownKeys(value$1)) {
-		const descriptor = Object.getOwnPropertyDescriptor(value$1, key);
-		if (descriptor == null) continue;
-		if ("value" in descriptor) descriptor.value = stripDeferredPromptValuesForContexts(descriptor.value, seen);
-		Object.defineProperty(clone, key, descriptor);
-	}
-	return clone;
+function getCommandPath(exec) {
+	return exec?.commandPath ?? [];
 }
-function finalizeParsedForContext(context, parsed) {
-	if (parsed !== void 0 || !Reflect.has(context, phase1ConfigAnnotationsKey)) return parsed;
-	return { [phase2UndefinedParsedValueKey]: true };
+function createCompleteExec(exec, context) {
+	const runtime = createDependencyRuntimeContext();
+	return {
+		...exec,
+		phase: "complete",
+		dependencyRuntime: runtime,
+		dependencyRegistry: runtime.registry,
+		commandPath: getCommandPath(context.exec) ?? exec.commandPath,
+		trace: context.exec?.trace ?? context.trace ?? exec.trace
+	};
 }
-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;
-				}
-			}
+function attemptParseSync(parser, args, mode = "complete") {
+	const shouldUnwrapAnnotatedValue = isInjectedAnnotationWrapper(parser.initialState);
+	const exec = createParseExec(parser);
+	let context = createParserContext({
+		buffer: args,
+		state: parser.initialState,
+		optionsTerminated: false
+	}, exec);
+	do {
+		const result = parser.parse(context);
+		if (!result.success) {
+			const progress = getFailureProgress(args, context.buffer, result.consumed);
+			return {
+				kind: "failure",
+				error: result.error,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
+			};
 		}
-		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 {}
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) {
+			const progress = getFailureProgress(args, previousBuffer, result.consumed.length);
+			return {
+				kind: "failure",
+				error: message`Unexpected option or argument: ${context.buffer[0]}.`,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
+			};
 		}
-	}
-	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);
+	} while (context.buffer.length > 0);
+	if (mode === "parse-only") return {
+		kind: "success",
+		value: void 0
+	};
+	const endResult = parser.complete(context.state, createCompleteExec(exec, context));
+	if (!endResult.success) return {
+		kind: "failure",
+		error: endResult.error,
+		remainingArgs: [],
+		consumedCount: args.length,
+		optionsTerminated: context.optionsTerminated,
+		commandPath: getCommandPath(context.exec)
+	};
+	return {
+		kind: "success",
+		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
+	};
 }
-function createSanitizedNonPlainContextView(value$1, seen) {
-	const methodCache = /* @__PURE__ */ new Map();
-	const proxy = new Proxy(value$1, {
-		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 = stripDeferredPromptValuesForContexts(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 stripDeferredPromptValuesForContexts(val.apply(this, args), seen);
-						return callMethodOnSanitizedTarget(val, proxy, target, args, stripDeferredPromptValuesForContexts, 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 stripDeferredPromptValuesForContexts(result.apply(this, args), seen);
-						return callMethodOnSanitizedTarget(result, proxy, target, args, stripDeferredPromptValuesForContexts, seen);
-					};
-					methodCache.set(key, {
-						fn: result,
-						wrapper
-					});
-					return wrapper;
-				}
-				return function(...args) {
-					if (this !== proxy) return stripDeferredPromptValuesForContexts(result.apply(this, args), seen);
-					return callMethodOnSanitizedTarget(result, proxy, target, args, stripDeferredPromptValuesForContexts, seen);
-				};
-			}
-			return stripDeferredPromptValuesForContexts(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;
+async function attemptParseAsync(parser, args, mode = "complete") {
+	const shouldUnwrapAnnotatedValue = isInjectedAnnotationWrapper(parser.initialState);
+	const exec = createParseExec(parser);
+	let context = createParserContext({
+		buffer: args,
+		state: parser.initialState,
+		optionsTerminated: false
+	}, exec);
+	do {
+		const result = await parser.parse(context);
+		if (!result.success) {
+			const progress = getFailureProgress(args, context.buffer, result.consumed);
 			return {
-				...descriptor,
-				value: stripDeferredPromptValuesForContexts(descriptor.value, seen)
+				kind: "failure",
+				error: result.error,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
 			};
 		}
-	});
-	seen.set(value$1, proxy);
-	return proxy;
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) {
+			const progress = getFailureProgress(args, previousBuffer, result.consumed.length);
+			return {
+				kind: "failure",
+				error: message`Unexpected option or argument: ${context.buffer[0]}.`,
+				remainingArgs: progress.remainingArgs,
+				consumedCount: progress.consumedCount,
+				optionsTerminated: context.optionsTerminated,
+				commandPath: getCommandPath(context.exec)
+			};
+		}
+	} while (context.buffer.length > 0);
+	if (mode === "parse-only") return {
+		kind: "success",
+		value: void 0
+	};
+	const endResult = await parser.complete(context.state, createCompleteExec(exec, context));
+	if (!endResult.success) return {
+		kind: "failure",
+		error: endResult.error,
+		remainingArgs: [],
+		consumedCount: args.length,
+		optionsTerminated: context.optionsTerminated,
+		commandPath: getCommandPath(context.exec)
+	};
+	return {
+		kind: "success",
+		value: shouldUnwrapAnnotatedValue ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
+	};
 }
-function prepareParsedForContexts(parsed) {
-	if (parsed == null || typeof parsed !== "object") return stripDeferredPromptValuesForContexts(parsed);
-	if (isDeferredPromptValue(parsed)) return void 0;
-	if (Array.isArray(parsed) || isPlainObject(parsed) || parsed instanceof Set || parsed instanceof Map) {
-		if (!containsDeferredPromptValuesForContexts(parsed)) return parsed;
-		return stripDeferredPromptValuesForContexts(parsed);
-	}
-	if (!containsDeferredPromptValuesForContexts(parsed)) return parsed;
-	return createSanitizedNonPlainContextView(parsed, /* @__PURE__ */ new WeakMap());
+function createPhase2SeedExec(parser, context) {
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		commandPath: [],
+		trace: createInputTrace()
+	};
+	const runtime = createDependencyRuntimeContext();
+	return {
+		...exec,
+		phase: "complete",
+		dependencyRuntime: runtime,
+		dependencyRegistry: runtime.registry,
+		commandPath: getCommandPath(context.exec),
+		trace: context.exec?.trace ?? context.trace ?? exec.trace
+	};
+}
+function createPhase2SeedContext(parser, args) {
+	const exec = {
+		usage: parser.usage,
+		phase: "parse",
+		path: [],
+		commandPath: [],
+		trace: createInputTrace()
+	};
+	return createParserContext({
+		buffer: args,
+		state: parser.initialState,
+		optionsTerminated: false
+	}, exec);
+}
+function extractPhase2SeedSync(parser, args) {
+	let context = createPhase2SeedContext(parser, args);
+	do {
+		const result = parser.parse(context);
+		if (!result.success) return completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+	} while (context.buffer.length > 0);
+	return completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
 }
-function withPreparedParsedForContext(context, preparedParsed, run) {
-	return run(finalizeParsedForContext(context, preparedParsed));
+async function extractPhase2SeedAsync(parser, args) {
+	let context = createPhase2SeedContext(parser, args);
+	do {
+		const result = await parser.parse(context);
+		if (!result.success) return await completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return await completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+	} while (context.buffer.length > 0);
+	return await completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
 }
 /**
 * Creates help parsers based on the sub-config.
@@ -348,9 +335,6 @@ function createVersionParser(commandConfig, optionConfig) {
 	};
 }
 const metaResultBrand = Symbol("@optique/core/facade/meta");
-function isMetaParseResult(value$1) {
-	return typeof value$1 === "object" && value$1 != null && metaResultBrand in value$1;
-}
 /**
 * Creates completion parsers based on the sub-config.
 */
@@ -406,11 +390,13 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	const effectiveVersionOptionNames = versionOptionNames ?? ["--version"];
 	if (helpParsers.helpOption) {
 		const lenientHelpParser = {
-			$mode: "sync",
+			mode: "sync",
 			$valueType: [],
 			$stateType: [],
 			priority: 200,
 			usage: helpParsers.helpOption.usage,
+			leadingNames: helpParsers.helpOption.leadingNames,
+			acceptingAnyToken: false,
 			initialState: null,
 			parse(context) {
 				const { buffer, optionsTerminated } = context;
@@ -485,11 +471,13 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	}
 	if (versionParsers.versionOption) {
 		const lenientVersionParser = {
-			$mode: "sync",
+			mode: "sync",
 			$valueType: [],
 			$stateType: [],
 			priority: 200,
 			usage: versionParsers.versionOption.usage,
+			leadingNames: versionParsers.versionOption.leadingNames,
+			acceptingAnyToken: false,
 			initialState: null,
 			parse(context) {
 				const { buffer, optionsTerminated } = context;
@@ -614,54 +602,115 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	}
 	return combined;
 }
-/**
-* Classifies the parsing result into a discriminated union for cleaner
-* handling.
-*/
-function classifyResult(result, args, helpOptionNames, helpCommandNames, versionOptionNames, versionCommandNames, completionCommandNames) {
-	if (!result.success) return {
-		type: "error",
-		error: result.error
-	};
-	const value$1 = result.value;
-	if (isMetaParseResult(value$1)) {
-		const parsedValue = value$1;
-		const hasVersionOption = versionOptionNames.some((n) => args.includes(n));
-		const hasVersionCommand = args.length > 0 && versionCommandNames.includes(args[0]);
-		const hasHelpOption = helpOptionNames.some((n) => args.includes(n));
-		const hasHelpCommand = args.length > 0 && helpCommandNames.includes(args[0]);
-		const hasCompletionCommand = args.length > 0 && completionCommandNames.includes(args[0]);
-		if (hasVersionCommand && hasHelpOption && parsedValue.helpFlag) return {
-			type: "help",
-			commands: [args[0]]
+function classifyOptionMeta(scanArgs, fullArgs, helpOptionNames, versionOptionNames, completionOptionNames) {
+	let lastHelpVersion;
+	for (let i = 0; i < scanArgs.length; i++) {
+		const arg = scanArgs[i];
+		if (helpOptionNames.includes(arg)) lastHelpVersion = {
+			index: i,
+			kind: "help"
 		};
-		if (hasCompletionCommand && hasHelpOption && parsedValue.helpFlag) return {
-			type: "help",
-			commands: [args[0]]
+		else if (versionOptionNames.includes(arg)) lastHelpVersion = {
+			index: i,
+			kind: "version"
+		};
+		const equalsMatch = completionOptionNames.find((name) => arg.startsWith(name + "="));
+		if (equalsMatch != null) return {
+			lastHelpVersion,
+			completion: {
+				index: i,
+				shell: arg.slice(equalsMatch.length + 1),
+				args: fullArgs.slice(i + 1)
+			}
 		};
-		if (parsedValue.help && (hasHelpOption || hasHelpCommand)) {
-			let commandContext = [];
-			if (Array.isArray(parsedValue.commands)) commandContext = parsedValue.commands;
-			else if (typeof parsedValue.commands === "object" && parsedValue.commands != null && "length" in parsedValue.commands) commandContext = parsedValue.commands;
+		if (completionOptionNames.includes(arg)) {
+			const shell = scanArgs[i + 1] ?? "";
 			return {
-				type: "help",
-				commands: commandContext
+				lastHelpVersion,
+				completion: {
+					index: i,
+					shell,
+					args: shell === "" ? [] : fullArgs.slice(i + 2)
+				}
 			};
 		}
-		if ((hasVersionOption || hasVersionCommand) && (parsedValue.version || parsedValue.versionFlag)) return { type: "version" };
-		if (parsedValue.completion && parsedValue.completionData) return {
+	}
+	return { lastHelpVersion };
+}
+function getHelpCommandContext(commandPath, args, helpIndex) {
+	const commands = [...commandPath];
+	for (let i = 0; i < helpIndex; i++) {
+		const arg = args[i];
+		if (!arg.startsWith("-")) commands.push(arg);
+	}
+	return commands;
+}
+function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versionOptionNames, versionCommandNames, completionOptionNames, completionCommandNames) {
+	if (failure.remainingArgs.length < 1) return {
+		type: "error",
+		error: failure.error
+	};
+	const hasConsumedPrefix = failure.consumedCount > 0;
+	const firstArg = failure.remainingArgs[0];
+	if (!hasConsumedPrefix && completionCommandNames.includes(firstArg)) {
+		const secondArg = failure.remainingArgs[1];
+		if (helpOptionNames.includes(secondArg)) return {
+			type: "help",
+			commands: [firstArg]
+		};
+		return {
 			type: "completion",
-			shell: parsedValue.completionData.shell ?? "",
-			args: parsedValue.completionData.args ?? []
+			source: "command",
+			shell: secondArg ?? "",
+			args: failure.remainingArgs.slice(2)
+		};
+	}
+	const optionArgs = failure.optionsTerminated ? [] : (() => {
+		const terminatorIndex = failure.remainingArgs.indexOf("--");
+		return terminatorIndex >= 0 ? failure.remainingArgs.slice(0, terminatorIndex) : failure.remainingArgs;
+	})();
+	const { lastHelpVersion, completion } = classifyOptionMeta(optionArgs, failure.remainingArgs, helpOptionNames, versionOptionNames, completionOptionNames);
+	if (!hasConsumedPrefix && versionCommandNames.includes(firstArg)) {
+		const secondArg = failure.remainingArgs[1];
+		if (helpOptionNames.includes(secondArg)) return {
+			type: "help",
+			commands: [firstArg]
 		};
+		const isCompletionImmediatelyAfter = completion?.index === 1;
+		if (secondArg == null || isCompletionImmediatelyAfter || lastHelpVersion?.index === 1 && lastHelpVersion.kind === "version") return { type: "version" };
 		return {
-			type: "success",
-			value: "result" in parsedValue ? parsedValue.result : value$1
+			type: "error",
+			error: failure.error
 		};
 	}
+	let commandAction;
+	if (!hasConsumedPrefix && helpCommandNames.includes(firstArg)) commandAction = {
+		index: 0,
+		kind: "help"
+	};
+	const winner = lastHelpVersion == null ? commandAction : commandAction == null || lastHelpVersion.index >= commandAction.index ? lastHelpVersion : commandAction;
+	if (winner?.kind === "help") {
+		if (winner === commandAction) return {
+			type: "help",
+			commands: failure.remainingArgs.slice(1)
+		};
+		return {
+			type: "help",
+			commands: getHelpCommandContext(failure.commandPath, failure.remainingArgs, winner.index),
+			preferUserCommandDocs: failure.commandPath.length > 0
+		};
+	}
+	if (winner?.kind === "version") return { type: "version" };
+	if (completion != null) return {
+		type: "completion",
+		source: "option",
+		shell: completion.shell,
+		commandPath: failure.commandPath,
+		args: completion.args
+	};
 	return {
-		type: "success",
-		value: value$1
+		type: "error",
+		error: failure.error
 	};
 }
 /**
@@ -676,7 +725,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 	if (!shellName) {
 		stderr("Error: Missing shell name for completion.\n");
 		if (completionParser) {
-			const displayName = completionCommandDisplayName ?? "completion";
+			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 			const doc = getDocPage(completionParser, [displayName]);
 			if (doc) stderr(formatDocPage(programName, doc, {
 				colors,
@@ -684,7 +733,11 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 				sectionOrder
 			}));
 		}
-		return dispatchByMode(parser.$mode, () => callOnError(1), () => Promise.resolve(callOnError(1)));
+		return dispatchByMode(parser.mode, () => {
+			const result = callOnError(1);
+			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
+			return result;
+		}, async () => callOnError(1));
 	}
 	const shell = availableShells[shellName];
 	if (!shell) {
@@ -697,25 +750,52 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			colors,
 			quotes: !colors
 		}));
-		return dispatchByMode(parser.$mode, () => callOnError(1), () => Promise.resolve(callOnError(1)));
+		return dispatchByMode(parser.mode, () => {
+			const result = callOnError(1);
+			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
+			return result;
+		}, async () => callOnError(1));
 	}
 	if (args.length === 0) {
 		const completionArg = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
 		const script = shell.generateScript(programName, [completionArg, shellName]);
 		stdout(script);
-		return dispatchByMode(parser.$mode, () => callOnCompletion(0), () => Promise.resolve(callOnCompletion(0)));
+		return dispatchByMode(parser.mode, () => {
+			const result = callOnCompletion(0);
+			if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
+			return result;
+		}, async () => callOnCompletion(0));
 	}
-	return dispatchByMode(parser.$mode, () => {
+	return dispatchByMode(parser.mode, () => {
 		const syncParser = parser;
 		const suggestions = suggest(syncParser, args);
 		for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
-		return callOnCompletion(0);
+		const result = callOnCompletion(0);
+		if (result instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
+		return result;
 	}, async () => {
 		const suggestions = await suggestAsync(parser, args);
 		for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
 		return callOnCompletion(0);
 	});
 }
+/**
+* Validates the configured version value.
+*
+* @param value Runtime version value from configuration.
+* @returns The validated version string.
+* @throws {TypeError} If the value is not a string, is empty, or contains
+*         ASCII control characters.
+*/
+function validateVersionValue(value$1) {
+	if (typeof value$1 !== "string") {
+		const type = Array.isArray(value$1) ? "array" : typeof value$1;
+		throw new TypeError(`Expected version value to be a string, but got ${type}.`);
+	}
+	if (value$1 === "") throw new TypeError("Version value must not be empty.");
+	if (/[\x00-\x1f\x7f]/.test(value$1)) throw new TypeError("Version value must not contain control characters.");
+	return value$1;
+}
 function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsParam) {
 	const isProgram = typeof programNameOrArgs !== "string";
 	let parser;
@@ -743,6 +823,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		args = argsOrOptions;
 		options = optionsParam ?? {};
 	}
+	validateProgramName(programName);
 	const { colors, maxWidth, showDefault, showChoices, sectionOrder, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
@@ -752,19 +833,58 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	const onHelp = options.help?.onShow ?? (() => ({}));
 	const versionCommandConfig = norm(options.version?.command);
 	const versionOptionConfig = norm(options.version?.option);
-	const versionValue = options.version?.value ?? "";
+	const versionValue = options.version ? validateVersionValue(options.version.value) : void 0;
 	const onVersion = options.version?.onShow ?? (() => ({}));
 	const completionCommandConfig = norm(options.completion?.command);
 	const completionOptionConfig = norm(options.completion?.option);
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
 	const onCompletionResult = (code) => onCompletion(code);
 	const onErrorResult = (code) => onError(code);
+	if (helpOptionConfig?.names) validateOptionNames(helpOptionConfig.names, "Help option");
+	if (helpCommandConfig?.names) validateCommandNames(helpCommandConfig.names, "Help command");
+	if (versionOptionConfig?.names) validateOptionNames(versionOptionConfig.names, "Version option");
+	if (versionCommandConfig?.names) validateCommandNames(versionCommandConfig.names, "Version command");
+	if (completionOptionConfig?.names) validateOptionNames(completionOptionConfig.names, "Completion option");
+	if (completionCommandConfig?.names) validateCommandNames(completionCommandConfig.names, "Completion command");
 	const helpOptionNames = helpOptionConfig?.names ?? ["--help"];
 	const helpCommandNames = helpCommandConfig?.names ?? ["help"];
 	const versionOptionNames = versionOptionConfig?.names ?? ["--version"];
 	const versionCommandNames = versionCommandConfig?.names ?? ["version"];
 	const completionCommandNames = completionCommandConfig?.names ?? ["completion"];
 	const completionOptionNames = completionOptionConfig?.names ?? ["--completion"];
+	const activeMetaEntries = [];
+	if (options.help && helpOptionConfig) activeMetaEntries.push([
+		"option",
+		"help option",
+		helpOptionNames
+	]);
+	if (options.help && helpCommandConfig) activeMetaEntries.push([
+		"command",
+		"help command",
+		helpCommandNames
+	]);
+	if (options.version && versionOptionConfig) activeMetaEntries.push([
+		"option",
+		"version option",
+		versionOptionNames
+	]);
+	if (options.version && versionCommandConfig) activeMetaEntries.push([
+		"command",
+		"version command",
+		versionCommandNames
+	]);
+	if (options.completion && completionOptionConfig) activeMetaEntries.push([
+		"option",
+		"completion option",
+		completionOptionNames,
+		true
+	]);
+	if (options.completion && completionCommandConfig) activeMetaEntries.push([
+		"command",
+		"completion command",
+		completionCommandNames
+	]);
+	validateMetaNameCollisions(activeMetaEntries);
 	const defaultShells = {
 		bash,
 		fish,
@@ -788,25 +908,6 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommand: null,
 		completionOption: null
 	};
-	if (options.completion) {
-		const hasHelpOption = helpOptionConfig ? helpOptionNames.some((n) => args.includes(n)) : false;
-		if (completionCommandConfig && args.length >= 1 && completionCommandNames.includes(args[0]) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], false, sectionOrder);
-		if (completionOptionConfig) for (let i = 0; i < args.length; i++) {
-			const arg = args[i];
-			const equalsMatch = completionOptionNames.find((n) => arg.startsWith(n + "="));
-			if (equalsMatch) {
-				const shell = arg.slice(equalsMatch.length + 1);
-				const completionArgs = args.slice(i + 1);
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
-			}
-			const exactMatch = completionOptionNames.includes(arg);
-			if (exactMatch) {
-				const shell = i + 1 < args.length ? args[i + 1] : "";
-				const completionArgs = i + 1 < args.length ? args.slice(i + 2) : [];
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], true, sectionOrder);
-			}
-		}
-	}
 	const augmentedParser = !options.help && !options.version && !options.completion ? parser : combineWithHelpVersion(parser, helpParsers, versionParsers, completionParsers, {
 		helpCommandGroup: helpCommandConfig?.group,
 		helpOptionGroup: helpOptionConfig?.group,
@@ -815,14 +916,17 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		completionCommandGroup: completionCommandConfig?.group,
 		completionOptionGroup: completionOptionConfig?.group
 	}, helpOptionConfig ? [...helpOptionNames] : void 0, versionOptionConfig ? [...versionOptionNames] : void 0);
-	const handleResult = (result) => {
-		const classified = classifyResult(result, args, helpOptionConfig ? [...helpOptionNames] : [], helpCommandConfig ? [...helpCommandNames] : [], versionOptionConfig ? [...versionOptionNames] : [], versionCommandConfig ? [...versionCommandNames] : [], completionCommandConfig ? [...completionCommandNames] : []);
+	const handleResult = (classified) => {
 		switch (classified.type) {
 			case "success": return classified.value;
 			case "version":
 				stdout(versionValue);
 				return onVersion(0);
-			case "completion": throw new RunParserError("Completion should be handled by early return");
+			case "completion": return handleCompletion([
+				classified.shell,
+				...classified.commandPath ?? [],
+				...classified.args
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder);
 			case "help": {
 				let helpGeneratorParser;
 				const helpAsCommand = helpCommandConfig != null;
@@ -832,9 +936,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				const versionAsOption = versionOptionConfig != null;
 				const completionAsOption = completionOptionConfig != null;
 				const requestedCommand = classified.commands[0];
-				if (requestedCommand != null && completionCommandNames.includes(requestedCommand) && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
-				else if (requestedCommand != null && helpCommandNames.includes(requestedCommand) && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
-				else if (requestedCommand != null && versionCommandNames.includes(requestedCommand) && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
+				if (requestedCommand != null && !classified.preferUserCommandDocs && completionCommandNames.includes(requestedCommand) && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
+				else if (requestedCommand != null && !classified.preferUserCommandDocs && helpCommandNames.includes(requestedCommand) && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
+				else if (requestedCommand != null && !classified.preferUserCommandDocs && versionCommandNames.includes(requestedCommand) && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
 				else {
 					const commandParsers = [parser];
 					const groupedMeta = {};
@@ -926,8 +1030,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					while (validationResult === "continue") {
 						const stepResult = helpGeneratorParser.parse(validationContext);
 						if (stepResult instanceof Promise) {
-							const asyncValidate = async (result$1) => {
-								let res = processStep(result$1);
+							const asyncValidate = async (result) => {
+								let res = processStep(result);
 								while (res === "continue") {
 									const next = helpGeneratorParser.parse(validationContext);
 									const resolved = next instanceof Promise ? await next : next;
@@ -991,15 +1095,23 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			default: throw new RunParserError("Unexpected parse result type");
 		}
 	};
-	const parserMode = parser.$mode;
+	const parserMode = parser.mode;
 	return dispatchByMode(parserMode, () => {
-		const result = parseSync(augmentedParser, args);
-		const handled = handleResult(result);
+		const attempted = attemptParseSync(parser, args);
+		const classified = attempted.kind === "success" ? {
+			type: "success",
+			value: attempted.value
+		} : classifyParseFailure(attempted, helpOptionConfig ? [...helpOptionNames] : [], helpCommandConfig ? [...helpCommandNames] : [], versionOptionConfig ? [...versionOptionNames] : [], versionCommandConfig ? [...versionCommandNames] : [], completionOptionConfig ? [...completionOptionNames] : [], completionCommandConfig ? [...completionCommandNames] : []);
+		const handled = handleResult(classified);
 		if (handled instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 		return handled;
 	}, async () => {
-		const result = await parseAsync(augmentedParser, args);
-		const handled = handleResult(result);
+		const attempted = await attemptParseAsync(parser, args);
+		const classified = attempted.kind === "success" ? {
+			type: "success",
+			value: attempted.value
+		} : classifyParseFailure(attempted, helpOptionConfig ? [...helpOptionNames] : [], helpCommandConfig ? [...helpCommandNames] : [], versionOptionConfig ? [...versionOptionNames] : [], versionCommandConfig ? [...versionCommandNames] : [], completionOptionConfig ? [...completionOptionNames] : [], completionCommandConfig ? [...completionCommandNames] : []);
+		const handled = handleResult(classified);
 		return handled instanceof Promise ? await handled : handled;
 	});
 }
@@ -1018,9 +1130,12 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 * @param args The command-line arguments to parse.
 * @param options Configuration options for customizing behavior.
 * @returns The parsed result if successful.
+* @throws {TypeError} If an async parser is passed at runtime.  Use
+* {@link runParser} or {@link runParserAsync} for async parsers.
 * @since 0.9.0
 */
 function runParserSync(parser, programName, args, options) {
+	if (parser.mode !== "sync") throw new TypeError("Cannot use an async parser with runParserSync(). Use runParser() or runParserAsync() instead.");
 	return runParser(parser, programName, args, options);
 }
 /**
@@ -1057,47 +1172,38 @@ var RunParserError = class extends Error {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+function isMetaEarlyExit(classified) {
+	return classified.type === "help" || classified.type === "version" || classified.type === "completion";
+}
+function classifyEarlyExitFailure(failure, options) {
+	const norm = (c) => c === true ? {} : c;
+	const helpOptionConfig = norm(options.help?.option);
+	const helpCommandConfig = norm(options.help?.command);
+	const versionOptionConfig = norm(options.version?.option);
+	const versionCommandConfig = norm(options.version?.command);
+	const completionOptionConfig = norm(options.completion?.option);
+	const completionCommandConfig = norm(options.completion?.command);
+	return classifyParseFailure(failure, helpOptionConfig ? [...helpOptionConfig.names ?? ["--help"]] : [], helpCommandConfig ? [...helpCommandConfig.names ?? ["help"]] : [], versionOptionConfig ? [...versionOptionConfig.names ?? ["--version"]] : [], versionCommandConfig ? [...versionCommandConfig.names ?? ["version"]] : [], completionOptionConfig ? [...completionOptionConfig.names ?? ["--completion"]] : [], completionCommandConfig ? [...completionCommandConfig.names ?? ["completion"]] : []);
+}
+function shouldProbeEarlyExit(options, needsTwoPhase) {
+	return needsTwoPhase && (options.help != null || options.version != null || options.completion != null);
+}
 /**
-* Checks if the arguments contain help, version, or completion requests
-* that should be handled immediately without context processing.
-*
-* This enables early exit optimization: when users request help, version,
-* or completion, we skip annotation collection and context processing
-* entirely, delegating directly to runParser().
-*
-* @param args Command-line arguments to check.
-* @param options Run options containing help/version/completion configuration.
-* @returns `true` if early exit should be performed, `false` otherwise.
+* Checks if the arguments contain parser-visible meta requests that can be
+* handled without collecting source-context annotations first.
 */
-function needsEarlyExit(args, options) {
-	const norm = (c) => c === true ? {} : c;
-	if (options.help) {
-		const helpOptionConfig = norm(options.help.option);
-		const helpCommandConfig = norm(options.help.command);
-		const helpOptionNames = helpOptionConfig?.names ?? ["--help"];
-		const helpCommandNames = helpCommandConfig?.names ?? ["help"];
-		if (helpOptionConfig && helpOptionNames.some((n) => args.includes(n))) return true;
-		if (helpCommandConfig && helpCommandNames.includes(args[0])) return true;
-	}
-	if (options.version) {
-		const versionOptionConfig = norm(options.version.option);
-		const versionCommandConfig = norm(options.version.command);
-		const versionOptionNames = versionOptionConfig?.names ?? ["--version"];
-		const versionCommandNames = versionCommandConfig?.names ?? ["version"];
-		if (versionOptionConfig && versionOptionNames.some((n) => args.includes(n))) return true;
-		if (versionCommandConfig && versionCommandNames.includes(args[0])) return true;
-	}
-	if (options.completion) {
-		const completionCommandConfig = norm(options.completion.command);
-		const completionOptionConfig = norm(options.completion.option);
-		const completionCommandNames = completionCommandConfig?.names ?? ["completion"];
-		const completionOptionNames = completionOptionConfig?.names ?? ["--completion"];
-		if (completionCommandConfig && completionCommandNames.includes(args[0])) return true;
-		if (completionOptionConfig) {
-			for (const arg of args) for (const name of completionOptionNames) if (arg === name || arg.startsWith(name + "=")) return true;
-		}
-	}
-	return false;
+function needsEarlyExitSync(parser, args, options) {
+	const attempted = attemptParseSync(parser, args, "parse-only");
+	if (attempted.kind === "success") return false;
+	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));
+}
+/**
+* Async variant of {@link needsEarlyExitSync}.
+*/
+async function needsEarlyExitAsync(parser, args, options) {
+	const attempted = await attemptParseAsync(parser, args, "parse-only");
+	if (attempted.kind === "success") return false;
+	return isMetaEarlyExit(classifyEarlyExitFailure(attempted, options));
 }
 /**
 * Merges multiple annotation objects, with earlier contexts having priority.
@@ -1116,56 +1222,73 @@ function mergeAnnotations(annotationsList) {
 	}
 	return result;
 }
+function validateContextPhases(contexts) {
+	for (const context of contexts) {
+		const phase = context.phase;
+		if (phase !== "single-pass" && phase !== "two-pass") throw new TypeError(`Context ${String(context.id)} must declare phase as "single-pass" or "two-pass".`);
+	}
+}
 /**
 * Collects phase 1 annotations from all contexts and determines whether
 * two-phase parsing is needed.
 *
 * @param contexts Source contexts to collect annotations from.
 * @param options Optional context-required options to pass to each context.
-* @returns Promise with merged annotations and dynamic-context hint.
+* @returns Promise with merged annotations, per-context snapshots, and a
+* two-phase hint.
 */
 async function collectPhase1Annotations(contexts, options) {
 	const annotationsList = [];
-	let hasDynamic = false;
+	let snapshots;
 	for (const context of contexts) {
-		const result = context.getAnnotations(void 0, options);
-		hasDynamic ||= needsTwoPhaseContext(context, result);
+		const request = { phase: "phase1" };
+		const result = context.getAnnotations(request, options);
 		const annotations = result instanceof Promise ? await result : result;
-		const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
-		const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, void 0, annotations) : void 0;
-		annotationsList.push(internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]));
+		const internalAnnotations = context.getInternalAnnotations?.(request, annotations);
+		const snapshot = internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
+		annotationsList.push(snapshot);
+		if (snapshots != null) snapshots.push(snapshot);
+		else if (context.phase === "two-pass") snapshots = [...annotationsList];
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
-		annotationsList,
-		hasDynamic
+		needsTwoPhase: snapshots != null,
+		snapshots: snapshots ?? []
 	};
 }
 /**
-* Collects annotations from all contexts.
+* Collects final annotations from all contexts.
+*
+* `single-pass` contexts reuse their phase-1 snapshot. `two-pass` contexts
+* are recollected with the parsed value and replace their own phase-1
+* snapshot in the final merge.
 *
 * @param contexts Source contexts to collect annotations from.
+* @param phase1Snapshots Per-context snapshots collected during phase 1.
 * @param parsed Optional parsed result from a previous parse pass.
 * @param options Optional context-required options to pass to each context.
 * @returns Promise that resolves to merged annotations.
 */
-async function collectAnnotations(contexts, parsed, options) {
+async function collectFinalAnnotations(contexts, phase1Snapshots, parsed, options, deferred, deferredKeys) {
 	const annotationsList = [];
-	const preparedParsed = prepareParsedForContexts(parsed);
-	for (const context of contexts) {
-		const mergedAnnotations = await withPreparedParsedForContext(context, preparedParsed, async (contextParsed) => {
-			const result = context.getAnnotations(contextParsed, options);
-			const annotations = result instanceof Promise ? await result : result;
-			const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
-			const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, contextParsed, annotations) : void 0;
-			return internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
-		});
+	const preparedParsed = prepareParsedForContexts(parsed, deferred, deferredKeys);
+	for (let index = 0; index < contexts.length; index++) {
+		const context = contexts[index];
+		if (context.phase === "single-pass") {
+			annotationsList.push(phase1Snapshots[index]);
+			continue;
+		}
+		const request = {
+			phase: "phase2",
+			parsed: preparedParsed
+		};
+		const result = context.getAnnotations(request, options);
+		const annotations = result instanceof Promise ? await result : result;
+		const internalAnnotations = context.getInternalAnnotations?.(request, annotations);
+		const mergedAnnotations = internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
 		annotationsList.push(mergedAnnotations);
 	}
-	return {
-		annotations: mergeAnnotations(annotationsList),
-		annotationsList
-	};
+	return { annotations: mergeAnnotations(annotationsList) };
 }
 /**
 * Collects phase 1 annotations from all contexts synchronously and determines
@@ -1173,70 +1296,62 @@ async function collectAnnotations(contexts, parsed, options) {
 *
 * @param contexts Source contexts to collect annotations from.
 * @param options Optional context-required options to pass to each context.
-* @returns Merged annotations with dynamic-context hint.
-* @throws Error if any context returns a Promise.
+* @returns Merged annotations, per-context snapshots, and a two-phase hint.
+* @throws {TypeError} If any context returns a Promise.
 */
 function collectPhase1AnnotationsSync(contexts, options) {
 	const annotationsList = [];
-	let hasDynamic = false;
+	let snapshots;
 	for (const context of contexts) {
-		const result = context.getAnnotations(void 0, options);
-		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		hasDynamic ||= needsTwoPhaseContext(context, result);
-		const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
-		const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, void 0, result) : void 0;
-		annotationsList.push(internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]));
+		const request = { phase: "phase1" };
+		const result = context.getAnnotations(request, options);
+		if (result instanceof Promise) throw new TypeError(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		const internalAnnotations = context.getInternalAnnotations?.(request, result);
+		const snapshot = internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
+		annotationsList.push(snapshot);
+		if (snapshots != null) snapshots.push(snapshot);
+		else if (context.phase === "two-pass") snapshots = [...annotationsList];
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
-		annotationsList,
-		hasDynamic
+		needsTwoPhase: snapshots != null,
+		snapshots: snapshots ?? []
 	};
 }
 /**
-* Determines whether a context requires a second parse pass.
+* Collects final annotations from all contexts synchronously.
 *
-* Explicit `mode` declarations take precedence over legacy heuristics so
-* static contexts are not forced into two-phase parsing when they return
-* empty annotations or a Promise.
-*/
-function needsTwoPhaseContext(context, result) {
-	if (context.mode !== void 0) return context.mode === "dynamic";
-	if (result instanceof Promise) return true;
-	return Object.getOwnPropertySymbols(result).length === 0;
-}
-/**
-* Collects annotations from all contexts synchronously.
+* `single-pass` contexts reuse their phase-1 snapshot. `two-pass` contexts
+* are recollected with the parsed value and replace their own phase-1
+* snapshot in the final merge.
 *
 * @param contexts Source contexts to collect annotations from.
+* @param phase1Snapshots Per-context snapshots collected during phase 1.
 * @param parsed Optional parsed result from a previous parse pass.
 * @param options Optional context-required options to pass to each context.
 * @returns Merged annotations.
-* @throws Error if any context returns a Promise.
+* @throws {TypeError} If any context returns a Promise.
 */
-function collectAnnotationsSync(contexts, parsed, options) {
+function collectFinalAnnotationsSync(contexts, phase1Snapshots, parsed, options, deferred, deferredKeys) {
 	const annotationsList = [];
-	const preparedParsed = prepareParsedForContexts(parsed);
-	for (const context of contexts) {
-		const mergedAnnotations = withPreparedParsedForContext(context, preparedParsed, (contextParsed) => {
-			const result = context.getAnnotations(contextParsed, options);
-			if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-			const internalAnnotationsGetter = Reflect.get(context, phase1ConfigAnnotationsKey);
-			const internalAnnotations = typeof internalAnnotationsGetter === "function" ? internalAnnotationsGetter.call(context, contextParsed, result) : void 0;
-			return internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
-		});
+	const preparedParsed = prepareParsedForContexts(parsed, deferred, deferredKeys);
+	for (let index = 0; index < contexts.length; index++) {
+		const context = contexts[index];
+		if (context.phase === "single-pass") {
+			annotationsList.push(phase1Snapshots[index]);
+			continue;
+		}
+		const request = {
+			phase: "phase2",
+			parsed: preparedParsed
+		};
+		const result = context.getAnnotations(request, options);
+		if (result instanceof Promise) throw new TypeError(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		const internalAnnotations = context.getInternalAnnotations?.(request, result);
+		const mergedAnnotations = internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
 		annotationsList.push(mergedAnnotations);
 	}
-	return {
-		annotations: mergeAnnotations(annotationsList),
-		annotationsList
-	};
-}
-function mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList) {
-	const mergedPerContext = [];
-	const length = Math.max(phase1AnnotationsList.length, phase2AnnotationsList.length);
-	for (let i = 0; i < length; i++) mergedPerContext.push(mergeAnnotations([phase2AnnotationsList[i] ?? {}, phase1AnnotationsList[i] ?? {}]));
-	return mergeAnnotations(mergedPerContext);
+	return { annotations: mergeAnnotations(annotationsList) };
 }
 /**
 * Disposes all contexts that implement `AsyncDisposable` or `Disposable`.
@@ -1276,22 +1391,63 @@ function disposeContextsSync(contexts) {
 	if (errors.length > 1) throw new AggregateError(errors, "Failed to dispose one or more source contexts.");
 }
 /**
+* Body of {@link runWith}, extracted so that the caller can handle
+* disposal outside a `finally` block (avoiding `no-unsafe-finally` lint).
+*/
+async function runWithBody(parser, programName, contexts, args, options) {
+	validateContextIds(contexts);
+	validateContextPhases(contexts);
+	const ctxOptions = options.contextOptions;
+	const { annotations: phase1Annotations, needsTwoPhase, snapshots: phase1Snapshots } = await collectPhase1Annotations(contexts, ctxOptions);
+	if (shouldProbeEarlyExit(options, needsTwoPhase)) {
+		const earlyExitParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (await needsEarlyExitAsync(earlyExitParser, args, options)) {
+			if (parser.mode === "async") return runParser(earlyExitParser, programName, args, options);
+			return Promise.resolve(runParser(earlyExitParser, programName, args, options));
+		}
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	if (!needsTwoPhase) {
+		if (parser.mode === "async") return runParser(augmentedParser1, programName, args, options);
+		return Promise.resolve(runParser(augmentedParser1, programName, args, options));
+	}
+	const firstPassSeed = await dispatchByMode(parser.mode, () => extractPhase2SeedSync(augmentedParser1, args), () => extractPhase2SeedAsync(augmentedParser1, args));
+	if (firstPassSeed == null) {
+		const fallbackParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (parser.mode === "async") return runParser(fallbackParser, programName, args, options);
+		return Promise.resolve(runParser(fallbackParser, programName, args, options));
+	}
+	const { annotations: finalAnnotations } = await collectFinalAnnotations(contexts, phase1Snapshots, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	if (parser.mode === "async") return runParser(augmentedParser2, programName, args, options);
+	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
+}
+/**
 * Runs a parser with multiple source contexts.
 *
-* This function automatically handles static and dynamic contexts with proper
-* priority. Earlier contexts in the array override later ones.
+* This function automatically handles single-pass and two-pass contexts with
+* proper priority. Earlier contexts in the array override later ones.
 *
 * The function uses a smart two-phase approach:
 *
-* 1. *Phase 1*: Collect annotations from all contexts (static contexts return
-*    their data, dynamic contexts may return empty).
-* 2. *First parse*: Parse with Phase 1 annotations.
-* 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
-*    parse result.
-* 4. *Second parse*: Parse again with merged annotations from both phases.
+* 1. *Phase 1*: Collect annotations from all contexts.
+* 2. *First parse*: Parse with Phase 1 annotations. If that pass finishes
+*    successfully, its value becomes the phase-two input. If the parser
+*    reaches a usable intermediate state but still does not complete
+*    successfully, the runner extracts a best-effort seed from that state
+*    instead.
+* 3. *Phase 2*: Call `getAnnotations({ phase: "phase2", parsed })` on all
+*    two-pass contexts with the first pass value. Deferred or otherwise
+*    unresolved fields in `parsed` may be `undefined`. Each two-pass
+*    context's phase-two return
+*    value replaces its own phase-one contribution for the final parse, so
+*    returning `{}` clears any annotations that context provided during
+*    phase 1. Single-pass contexts reuse their phase-one snapshot.
+* 4. *Second parse*: Parse again with the merged phase-two annotations.
 *
-* If all contexts are static (no dynamic contexts), the second parse is skipped
-* for optimization.
+* If all contexts are single-pass, the second parse is skipped for
+* optimization. Phase 2 is also skipped when the first pass does not yield
+* any usable seed at all.
 *
 * @template TParser The parser type.
 * @template THelp Return type when help is shown.
@@ -1301,6 +1457,13 @@ function disposeContextsSync(contexts) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns Promise that resolves to the parsed result.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
+* @throws {TypeError} If any context omits `phase` or declares an invalid
+* phase value.
+* @throws {SuppressedError} If the runner throws and a context's disposal
+* also throws.  The original error is available via `.suppressed` and the
+* disposal error via `.error`.
 * @since 0.10.0
 *
 * @example
@@ -1310,6 +1473,7 @@ function disposeContextsSync(contexts) {
 *
 * const envContext: SourceContext = {
 *   id: Symbol.for("@myapp/env"),
+*   phase: "single-pass",
 *   getAnnotations() {
 *     return { [Symbol.for("@myapp/env")]: process.env };
 *   }
@@ -1325,54 +1489,61 @@ function disposeContextsSync(contexts) {
 */
 async function runWith(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
-	if (needsEarlyExit(args, options)) {
-		if (parser.$mode === "async") return runParser(parser, programName, args, options);
-		return Promise.resolve(runParser(parser, programName, args, options));
-	}
 	if (contexts.length === 0) {
-		if (parser.$mode === "async") return runParser(parser, programName, args, options);
+		if (parser.mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
+	let result;
+	let primaryError;
+	let hasPrimaryError = false;
+	try {
+		result = await runWithBody(parser, programName, contexts, args, options);
+	} catch (error) {
+		hasPrimaryError = true;
+		primaryError = error;
+	}
 	try {
-		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, options);
-		if (!needsTwoPhase) {
-			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
-			return Promise.resolve(runParser(augmentedParser, programName, args, options));
-		}
-		const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-		let firstPassResult;
-		let firstPassFailed = false;
-		try {
-			if (parser.$mode === "async") firstPassResult = await parseAsync(augmentedParser1, args);
-			else firstPassResult = parseSync(augmentedParser1, args);
-			if (typeof firstPassResult === "object" && firstPassResult !== null && "success" in firstPassResult) {
-				const result = firstPassResult;
-				if (result.success) firstPassResult = result.value;
-				else firstPassFailed = true;
-			}
-		} catch {
-			firstPassFailed = true;
-		}
-		if (firstPassFailed) {
-			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-			if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
-			return Promise.resolve(runParser(augmentedParser, programName, args, options));
-		}
-		const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassResult, options);
-		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
-		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-		if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
-		return Promise.resolve(runParser(augmentedParser2, programName, args, options));
-	} finally {
 		await disposeContexts(contexts);
+	} catch (disposeError) {
+		if (hasPrimaryError) throw new SuppressedErrorCtor(disposeError, primaryError, "An error was suppressed during context disposal.");
+		throw disposeError;
 	}
+	if (hasPrimaryError) throw primaryError;
+	return result;
+}
+/**
+* Body of {@link runWithSync}, extracted so that the caller can handle
+* disposal outside a `finally` block (avoiding `no-unsafe-finally` lint).
+*/
+function runWithSyncBody(parser, programName, contexts, args, options) {
+	validateContextIds(contexts);
+	validateContextPhases(contexts);
+	const ctxOptions = options.contextOptions;
+	const { annotations: phase1Annotations, needsTwoPhase, snapshots: phase1Snapshots } = collectPhase1AnnotationsSync(contexts, ctxOptions);
+	if (shouldProbeEarlyExit(options, needsTwoPhase)) {
+		const earlyExitParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		if (needsEarlyExitSync(earlyExitParser, args, options)) return runParser(earlyExitParser, programName, args, options);
+	}
+	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
+	if (!needsTwoPhase) return runParser(augmentedParser1, programName, args, options);
+	const firstPassSeed = extractPhase2SeedSync(augmentedParser1, args);
+	if (firstPassSeed == null) {
+		const fallbackParser = injectAnnotationsIntoParser(parser, phase1Annotations);
+		return runParser(fallbackParser, programName, args, options);
+	}
+	const { annotations: finalAnnotations } = collectFinalAnnotationsSync(contexts, phase1Snapshots, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
+	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
+	return runParser(augmentedParser2, programName, args, options);
 }
 /**
 * Runs a synchronous parser with multiple source contexts.
 *
 * This is the sync-only variant of {@link runWith}. All contexts must return
-* annotations synchronously (not Promises).
+* annotations synchronously (not Promises). It uses the same two-phase
+* best-effort seed extraction as {@link runWith} when two-pass contexts are
+* present. In two-phase runs, each two-pass context's phase-two return value
+* replaces that context's phase-one contribution for the final parse, so
+* returning `{}` clears any annotations that context provided during phase 1.
 *
 * @template TParser The sync parser type.
 * @template THelp Return type when help is shown.
@@ -1382,36 +1553,40 @@ async function runWith(parser, programName, contexts, options) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns The parsed result.
-* @throws Error if any context returns a Promise or if a context's
+* @throws {TypeError} If an async parser is passed at runtime.  Use
+* {@link runWith} or {@link runWithAsync} for async parsers.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
+* @throws {TypeError} If any context omits `phase` or declares an invalid
+* phase value.
+* @throws {TypeError} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
+* @throws {SuppressedError} If the runner throws and a context's disposal
+* also throws.  The original error is available via `.suppressed` and the
+* disposal error via `.error`.
 * @since 0.10.0
 */
 function runWithSync(parser, programName, contexts, options) {
+	if (parser.mode !== "sync") throw new TypeError("Cannot use an async parser with runWithSync(). Use runWith() or runWithAsync() instead.");
 	const args = options?.args ?? [];
-	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
+	let result;
+	let primaryError;
+	let hasPrimaryError = false;
+	try {
+		result = runWithSyncBody(parser, programName, contexts, args, options);
+	} catch (error) {
+		hasPrimaryError = true;
+		primaryError = error;
+	}
 	try {
-		const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, options);
-		if (!needsTwoPhase) {
-			const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-			return runParser(augmentedParser, programName, args, options);
-		}
-		const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
-		let firstPassResult;
-		try {
-			const result = parseSync(augmentedParser1, args);
-			if (result.success) firstPassResult = result.value;
-			else return runParser(augmentedParser1, programName, args, options);
-		} catch {
-			return runParser(augmentedParser1, programName, args, options);
-		}
-		const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassResult, options);
-		const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
-		const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-		return runParser(augmentedParser2, programName, args, options);
-	} finally {
 		disposeContextsSync(contexts);
+	} catch (disposeError) {
+		if (hasPrimaryError) throw new SuppressedErrorCtor(disposeError, primaryError, "An error was suppressed during context disposal.");
+		throw disposeError;
 	}
+	if (hasPrimaryError) throw primaryError;
+	return result;
 }
 /**
 * Runs any parser asynchronously with multiple source contexts.
@@ -1427,6 +1602,11 @@ function runWithSync(parser, programName, contexts, options) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns Promise that resolves to the parsed result.
+* @throws {TypeError} If two or more contexts share the same
+* {@link SourceContext.id}.
+* @throws {SuppressedError} If the runner throws and a context's disposal
+* also throws.  The original error is available via `.suppressed` and the
+* disposal error via `.error`.
 * @since 0.10.0
 */
 function runWithAsync(parser, programName, contexts, options) {
@@ -1441,10 +1621,25 @@ function runWithAsync(parser, programName, contexts, options) {
 */
 function injectAnnotationsIntoParser(parser, annotations) {
 	const newInitialState = injectAnnotations(parser.initialState, annotations);
-	return {
-		...parser,
-		initialState: newInitialState
+	const descriptors = { ...Object.getOwnPropertyDescriptors(parser) };
+	const initialState = descriptors.initialState;
+	descriptors.initialState = initialState == null ? {
+		value: newInitialState,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	} : "get" in initialState || "set" in initialState ? {
+		value: newInitialState,
+		writable: true,
+		enumerable: initialState.enumerable ?? true,
+		configurable: initialState.configurable ?? true
+	} : {
+		value: newInitialState,
+		writable: initialState.writable ?? true,
+		enumerable: initialState.enumerable ?? true,
+		configurable: initialState.configurable ?? true
 	};
+	return Object.create(Object.getPrototypeOf(parser), descriptors);
 }
 
 //#endregion