@optique/core 1.0.0-dev.1658 → 1.0.0-dev.1661

package/dist/constructs.js

@@ -1,4 +1,4 @@
-import { getAnnotations, inheritAnnotations, injectAnnotations } from "./annotations.js";
+import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, injectAnnotations } from "./annotations.js";
 import { message, optionName, text, values } from "./message.js";
 import { createDependencySourceState, dependencyId, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, wrappedDependencySourceMarker } from "./dependency.js";
 import { validateLabel } from "./validate.js";
@@ -7,7 +7,7 @@ import { deduplicateDocFragments } from "./doc.js";
 import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar } from "./suggestion.js";
 import { collectLeadingCandidates } from "./usage-internals.js";
-import { getParserSuggestRuntimeNodes, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
+import { defineInheritedAnnotationParser, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "./parser.js";
 import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyRuntimeContext, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync } from "./dependency-runtime.js";
 
 //#region src/constructs.ts
@@ -38,12 +38,13 @@ function mergeChildExec(parent, child) {
 		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
 	};
 }
-function withChildContext(context, segment, state, usage) {
+function withChildContext(context, segment, state, parser, usage) {
 	const exec = withChildExecPath(context.exec, segment);
 	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
+	const childState = parser == null ? state : getParseChildState(context.state, state, parser);
 	return {
 		...context,
-		state,
+		state: childState,
 		...usage != null ? { usage } : {},
 		...exec != null ? {
 			exec: dependencyRegistry === exec.dependencyRegistry ? exec : {
@@ -69,6 +70,13 @@ function filterPreCompletedRuntimeNodes(nodes, preCompletedKeys) {
 		return segment == null || !preCompletedKeys.has(segment);
 	});
 }
+function buildIndexedParserPairs(parsers) {
+	return parsers.map((parser, index) => [String(index), parser]);
+}
+function createAnnotatedArrayStateRecord(stateArray) {
+	const stateRecord = Object.fromEntries(stateArray.map((state, index) => [String(index), state]));
+	return inheritAnnotations(stateArray, stateRecord);
+}
 /**
 * Computes the union of `leadingNames` from all given parsers.
 * Used for alternative combinators (`or()`, `longestMatch()`) where all
@@ -101,7 +109,6 @@ function sharedBufferLeadingNames(parsers) {
 	}
 	return names.size === 0 ? EMPTY_LEADING_NAMES : names;
 }
-const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
 /**
 * Internal symbol for exposing field-level parser pairs from `object()`
 * and `merge()` parsers.  This allows `merge()` to pre-complete dependency
@@ -116,9 +123,77 @@ const fieldParsersKey = Symbol("fieldParsers");
 * to consume results from parsers that still return `DependencySourceState`.
 * @internal
 */
+function unwrapAnnotationView(value) {
+	if (value == null || typeof value !== "object") return value;
+	return annotationViewTargets.get(value) ?? value;
+}
+function containsAnnotationView(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value == null || typeof value !== "object") return false;
+	const candidate = value;
+	if (annotationViewTargets.has(candidate)) return true;
+	const source = unwrapAnnotationView(candidate);
+	if (seen.has(source)) return false;
+	seen.add(source);
+	if (Array.isArray(source)) return source.some((item) => containsAnnotationView(item, seen));
+	const proto = Object.getPrototypeOf(source);
+	if (proto !== Object.prototype && proto !== null) return false;
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	return Reflect.ownKeys(descriptors).some((key) => {
+		const descriptor = descriptors[key];
+		return descriptor != null && "value" in descriptor ? containsAnnotationView(descriptor.value, seen) : false;
+	});
+}
+function unwrapNestedAnnotationViews(value, seen = /* @__PURE__ */ new WeakMap()) {
+	if (value == null || typeof value !== "object") return value;
+	const source = unwrapAnnotationView(value);
+	if (seen.has(source)) return seen.get(source);
+	if (Array.isArray(source)) {
+		let changed$1 = false;
+		const clone$1 = [...source];
+		seen.set(source, clone$1);
+		for (let i = 0; i < source.length; i++) {
+			const nextValue = unwrapNestedAnnotationViews(source[i], seen);
+			if (nextValue !== source[i]) {
+				clone$1[i] = nextValue;
+				changed$1 = true;
+			}
+		}
+		return changed$1 ? clone$1 : source;
+	}
+	const proto = Object.getPrototypeOf(source);
+	if (proto !== Object.prototype && proto !== null) return source;
+	const descriptors = Object.getOwnPropertyDescriptors(source);
+	let changed = false;
+	const clone = Object.create(proto);
+	seen.set(source, clone);
+	for (const key of Reflect.ownKeys(descriptors)) {
+		const descriptor = descriptors[key];
+		if (descriptor != null && "value" in descriptor) {
+			const nextValue = unwrapNestedAnnotationViews(descriptor.value, seen);
+			if (nextValue !== descriptor.value) {
+				descriptors[key] = {
+					...descriptor,
+					value: nextValue
+				};
+				changed = true;
+			}
+		}
+	}
+	if (!changed) {
+		seen.set(source, source);
+		return source;
+	}
+	Object.defineProperties(clone, descriptors);
+	return clone;
+}
 function unwrapCompleteResult(result) {
-	if (isDependencySourceState(result)) return result.result;
-	return result;
+	const unwrappedResult = isDependencySourceState(result) ? result.result : result;
+	if (!unwrappedResult.success || !containsAnnotationView(unwrappedResult.value)) return unwrappedResult;
+	const value = unwrapNestedAnnotationViews(unwrappedResult.value);
+	return value === unwrappedResult.value ? unwrappedResult : {
+		...unwrappedResult,
+		value
+	};
 }
 /**
 * Prepares a field state for completion by wrapping `undefined` state
@@ -139,22 +214,81 @@ function prepareStateForCompletion(fieldState, parser) {
 }
 /**
 * Returns the field state with parent annotations inherited, respecting
-* the parser's {@link inheritParentAnnotationsKey} flag.  This is the
-* same logic as {@link createFieldStateGetter} inside `object()` but
-* without the per-state cache, for use in module-level helpers like
+* the parser's annotation-inheritance contract. This is the same logic as
+* {@link createFieldStateGetter} inside `object()` but without the per-state
+* cache, for use in module-level helpers like
 * {@link pendingDependencyDefaults}.
 * @internal
 */
 function getAnnotatedFieldState(parentState, field, parser) {
 	const sourceState = parentState != null && typeof parentState === "object" && field in parentState ? parentState[field] : parser.initialState;
+	return getAnnotatedChildState(parentState, sourceState, parser);
+}
+const annotationViewTargets = /* @__PURE__ */ new WeakMap();
+function withAnnotationView(state, annotations) {
+	const target = unwrapAnnotationView(state);
+	const view = new Proxy(target, {
+		get(target$1, key) {
+			if (key === annotationKey) return annotations;
+			const value = Reflect.get(target$1, key, target$1);
+			return typeof value === "function" ? value.bind(target$1) : value;
+		},
+		has(target$1, key) {
+			return key === annotationKey || Reflect.has(target$1, key);
+		}
+	});
+	annotationViewTargets.set(view, target);
+	return view;
+}
+function getParseChildState(parentState, childState, parser) {
 	const annotations = getAnnotations(parentState);
-	if (sourceState == null) {
-		if (annotations !== void 0 && Reflect.get(parser, inheritParentAnnotationsKey) === true) return injectAnnotations({}, annotations);
-		return sourceState;
+	const shouldInheritAnnotations = Reflect.get(parser, inheritParentAnnotationsKey) === true;
+	if (childState == null) {
+		if (annotations !== void 0 && shouldInheritAnnotations) return injectAnnotations({}, annotations);
+		return childState;
+	}
+	if (annotations === void 0 || typeof childState !== "object" || getAnnotations(childState) === annotations || !shouldInheritAnnotations) return childState;
+	const injectedState = injectAnnotations(childState, annotations);
+	return getAnnotations(injectedState) === annotations ? injectedState : childState;
+}
+function getObjectParseChildState(parentState, childState, _parser) {
+	const annotations = getAnnotations(parentState);
+	if (annotations === void 0 || childState == null || typeof childState !== "object" || getAnnotations(childState) === annotations) return childState;
+	return inheritAnnotations(parentState, childState);
+}
+function getAnnotatedChildState(parentState, childState, parser) {
+	const annotations = getAnnotations(parentState);
+	const shouldInheritAnnotations = Reflect.get(parser, inheritParentAnnotationsKey) === true;
+	if (childState == null) {
+		if (annotations !== void 0 && shouldInheritAnnotations) return injectAnnotations({}, annotations);
+		return childState;
+	}
+	if (typeof childState !== "object") return childState;
+	if (annotations === void 0 || getAnnotations(childState) === annotations) return childState;
+	if (shouldInheritAnnotations) {
+		const injectedState = injectAnnotations(childState, annotations);
+		if (getAnnotations(injectedState) === annotations) return injectedState;
 	}
-	if (typeof sourceState !== "object") return sourceState;
-	if (annotations === void 0 || getAnnotations(sourceState) === annotations) return sourceState;
-	return Reflect.get(parser, inheritParentAnnotationsKey) === true ? injectAnnotations(sourceState, annotations) : inheritAnnotations(parentState, sourceState);
+	return withAnnotationView(childState, annotations);
+}
+function buildSuggestRuntimeNodesFromPairs(pairs, state, parentPath) {
+	const prefix = parentPath ?? [];
+	const nodes = [];
+	for (const [field, parser] of pairs) {
+		const fieldState = Object.hasOwn(state, field) ? state[field] : parser.initialState;
+		nodes.push(...getParserSuggestRuntimeNodes(parser, getAnnotatedChildState(state, fieldState, parser), [...prefix, field]));
+	}
+	return nodes;
+}
+function buildSuggestRuntimeNodesFromArray(parsers, stateArray, parentPath) {
+	const prefix = parentPath ?? [];
+	const nodes = [];
+	for (let i = 0; i < parsers.length; i++) {
+		const parser = parsers[i];
+		const elementState = i < stateArray.length ? stateArray[i] : void 0;
+		nodes.push(...getParserSuggestRuntimeNodes(parser, getAnnotatedChildState(stateArray, elementState, parser), [...prefix, i]));
+	}
+	return nodes;
 }
 function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput, parsers, customFormatter) {
 	const options = /* @__PURE__ */ new Set();
@@ -918,8 +1052,10 @@ function registerCompletedDependency(completed, registry) {
 * @see https://github.com/dahlia/optique/issues/186
 * @internal
 */
-function* pendingDependencyDefaults(context, parserPairs) {
+function* pendingDependencyDefaults(context, parserPairs, registry) {
 	for (const [field, fieldParser] of parserPairs) {
+		const sourceId = fieldParser.dependencyMetadata?.source?.sourceId ?? (isWrappedDependencySource(fieldParser) ? fieldParser[wrappedDependencySourceMarker][dependencyId] : isPendingDependencySourceState(fieldParser.initialState) ? fieldParser.initialState[dependencyId] : void 0);
+		if (sourceId != null && registry?.has(sourceId)) continue;
 		const fieldState = context.state != null && typeof context.state === "object" && field in context.state ? context.state[field] : void 0;
 		const annotatedFieldState = getAnnotatedFieldState(context.state, field, fieldParser);
 		if (fieldParser.dependencyMetadata?.source?.getMissingSourceValue != null && isUnmatchedDependencyState(fieldState, fieldParser)) {
@@ -963,7 +1099,7 @@ function* pendingDependencyDefaults(context, parserPairs) {
 * @internal
 */
 function completeDependencySourceDefaults(context, parserPairs, registry, exec) {
-	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) {
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs, registry)) {
 		const completed = parser.complete(state, exec);
 		const depState = wrapAsDependencySourceState(completed, parser);
 		if (depState) registerCompletedDependency(depState, registry);
@@ -1000,7 +1136,7 @@ function wrapAsDependencySourceState(completed, parser) {
 * @internal
 */
 async function completeDependencySourceDefaultsAsync(context, parserPairs, registry, exec) {
-	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs)) {
+	for (const { parser, state } of pendingDependencyDefaults(context, parserPairs, registry)) {
 		const completed = await parser.complete(state, exec);
 		const depState = wrapAsDependencySourceState(completed, parser);
 		if (depState) registerCompletedDependency(depState, registry);
@@ -1194,7 +1330,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		return state;
 	};
 	const inheritedFieldStateCache = /* @__PURE__ */ new WeakMap();
-	const createFieldStateGetter = (parentState) => {
+	const createFieldStateGetter = (parentState, annotateChildState = getAnnotatedChildState) => {
 		return (field, parser) => {
 			const fieldKey = field;
 			const cache = parentState != null && typeof parentState === "object" ? inheritedFieldStateCache.get(parentState) ?? (() => {
@@ -1204,25 +1340,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			})() : void 0;
 			if (cache?.has(fieldKey)) return cache.get(fieldKey);
 			const sourceState = parentState != null && typeof parentState === "object" && fieldKey in parentState ? parentState[fieldKey] : parser.initialState;
-			const annotations = getAnnotations(parentState);
-			if (sourceState == null) {
-				if (annotations !== void 0 && Reflect.get(parser, inheritParentAnnotationsKey) === true) {
-					const inheritedState$1 = injectAnnotations({}, annotations);
-					cache?.set(fieldKey, inheritedState$1);
-					return inheritedState$1;
-				}
-				cache?.set(fieldKey, sourceState);
-				return sourceState;
-			}
-			if (typeof sourceState !== "object") {
-				cache?.set(fieldKey, sourceState);
-				return sourceState;
-			}
-			if (annotations === void 0 || getAnnotations(sourceState) === annotations) {
-				cache?.set(fieldKey, sourceState);
-				return sourceState;
-			}
-			const inheritedState = Reflect.get(parser, inheritParentAnnotationsKey) === true ? injectAnnotations(sourceState, annotations) : inheritAnnotations(parentState, sourceState);
+			const inheritedState = annotateChildState(parentState, sourceState, parser);
 			cache?.set(fieldKey, inheritedState);
 			return inheritedState;
 		};
@@ -1251,7 +1369,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
-			const getFieldState = createFieldStateGetter(currentContext.state);
+			const getFieldState = createFieldStateGetter(currentContext.state, getObjectParseChildState);
 			for (const [field, parser] of parserPairs) {
 				const result = parser.parse(withChildContext(currentContext, field, getFieldState(field, parser)));
 				if (result.success && result.consumed.length > 0) {
@@ -1262,7 +1380,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 						optionsTerminated: result.next.optionsTerminated,
 						state: {
 							...currentContext.state,
-							[field]: result.next.state
+							[field]: getAnnotatedChildState(currentContext.state, result.next.state, parser)
 						},
 						...mergedExec != null ? {
 							trace: mergedExec.trace,
@@ -1312,7 +1430,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		let madeProgress = true;
 		while (madeProgress && currentContext.buffer.length > 0) {
 			madeProgress = false;
-			const getFieldState = createFieldStateGetter(currentContext.state);
+			const getFieldState = createFieldStateGetter(currentContext.state, getObjectParseChildState);
 			for (const [field, parser] of parserPairs) {
 				const resultOrPromise = parser.parse(withChildContext(currentContext, field, getFieldState(field, parser)));
 				const result = await resultOrPromise;
@@ -1324,7 +1442,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 						optionsTerminated: result.next.optionsTerminated,
 						state: {
 							...currentContext.state,
-							[field]: result.next.state
+							[field]: getAnnotatedChildState(currentContext.state, result.next.state, parser)
 						},
 						...mergedExec != null ? {
 							trace: mergedExec.trace,
@@ -1571,49 +1689,226 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		configurable: true,
 		enumerable: false
 	});
+	defineInheritedAnnotationParser(objectParser);
 	return objectParser;
 }
 function suggestTupleSync(context, prefix, parsers) {
 	const suggestions = [];
-	const stateArray = context.state;
-	const runtime = createDependencyRuntimeContext(context.dependencyRegistry?.clone());
+	const advanced = advanceTupleSuggestContextSync(context, parsers);
+	const advancedContext = advanced.context;
+	const stateArray = advancedContext.state;
+	const runtime = createDependencyRuntimeContext(advancedContext.dependencyRegistry?.clone());
 	if (stateArray && Array.isArray(stateArray)) {
-		collectExplicitSourceValues(buildRuntimeNodesFromArray(parsers, stateArray, context.exec?.path), runtime);
+		const nodes = buildSuggestRuntimeNodesFromArray(parsers, stateArray, advancedContext.exec?.path);
+		collectExplicitSourceValues(nodes, runtime);
+		fillMissingSourceDefaults(nodes, runtime);
 		collectSourcesFromState(stateArray, runtime);
+		completeDependencySourceDefaults({
+			...advancedContext,
+			state: createAnnotatedArrayStateRecord(stateArray)
+		}, buildIndexedParserPairs(parsers), runtime.registry, advancedContext.exec);
 	}
+	markFailedTupleSuggestSources(parsers, stateArray, advanced.failedParserIndexes, runtime, advancedContext.exec?.path);
 	const contextWithRegistry = {
-		...context,
-		dependencyRegistry: runtime.registry
+		...advancedContext,
+		dependencyRegistry: runtime.registry,
+		...advancedContext.exec != null ? { exec: {
+			...advancedContext.exec,
+			dependencyRuntime: runtime,
+			dependencyRegistry: runtime.registry
+		} } : {}
 	};
 	for (let i = 0; i < parsers.length; i++) {
 		const parser = parsers[i];
 		const parserState = stateArray && Array.isArray(stateArray) ? stateArray[i] : parser.initialState;
-		const parserSuggestions = parser.suggest(withChildContext(contextWithRegistry, i, parserState), prefix);
+		const parserSuggestions = parser.suggest(withChildContext(contextWithRegistry, i, parserState, parser), prefix);
 		suggestions.push(...parserSuggestions);
 	}
 	return deduplicateSuggestions(suggestions);
 }
 async function* suggestTupleAsync(context, prefix, parsers) {
 	const suggestions = [];
-	const stateArray = context.state;
-	const runtime = createDependencyRuntimeContext(context.dependencyRegistry?.clone());
+	const advanced = await advanceTupleSuggestContextAsync(context, parsers);
+	const advancedContext = advanced.context;
+	const stateArray = advancedContext.state;
+	const runtime = createDependencyRuntimeContext(advancedContext.dependencyRegistry?.clone());
 	if (stateArray && Array.isArray(stateArray)) {
-		await collectExplicitSourceValuesAsync(buildRuntimeNodesFromArray(parsers, stateArray, context.exec?.path), runtime);
+		const nodes = buildSuggestRuntimeNodesFromArray(parsers, stateArray, advancedContext.exec?.path);
+		await collectExplicitSourceValuesAsync(nodes, runtime);
+		await fillMissingSourceDefaultsAsync(nodes, runtime);
 		collectSourcesFromState(stateArray, runtime);
+		await completeDependencySourceDefaultsAsync({
+			...advancedContext,
+			state: createAnnotatedArrayStateRecord(stateArray)
+		}, buildIndexedParserPairs(parsers), runtime.registry, advancedContext.exec);
 	}
+	markFailedTupleSuggestSources(parsers, stateArray, advanced.failedParserIndexes, runtime, advancedContext.exec?.path);
 	const contextWithRegistry = {
-		...context,
-		dependencyRegistry: runtime.registry
+		...advancedContext,
+		dependencyRegistry: runtime.registry,
+		...advancedContext.exec != null ? { exec: {
+			...advancedContext.exec,
+			dependencyRuntime: runtime,
+			dependencyRegistry: runtime.registry
+		} } : {}
 	};
 	for (let i = 0; i < parsers.length; i++) {
 		const parser = parsers[i];
 		const parserState = stateArray && Array.isArray(stateArray) ? stateArray[i] : parser.initialState;
-		const parserSuggestions = parser.suggest(withChildContext(contextWithRegistry, i, parserState), prefix);
+		const parserSuggestions = parser.suggest(withChildContext(contextWithRegistry, i, parserState, parser), prefix);
 		if (parser.$mode === "async") for await (const s of parserSuggestions) suggestions.push(s);
 		else suggestions.push(...parserSuggestions);
 	}
 	yield* deduplicateSuggestions(suggestions);
 }
+function advanceTupleSuggestContextSync(context, parsers) {
+	let currentContext = context;
+	const matchedParsers = /* @__PURE__ */ new Set();
+	while (currentContext.buffer.length > 0 && matchedParsers.size < parsers.length) {
+		let foundMatch = false;
+		let failedParserIndexes = [];
+		let deepestFailure = 0;
+		const stateArray = Array.isArray(currentContext.state) ? [...currentContext.state] : parsers.map((parser) => parser.initialState);
+		const remainingParsers = parsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
+		for (const [parser, index] of remainingParsers) {
+			const result = parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
+			if (result.success && result.consumed.length > 0) {
+				const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : state));
+				const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
+				currentContext = {
+					...currentContext,
+					buffer: result.next.buffer,
+					optionsTerminated: result.next.optionsTerminated,
+					state: newStateArray,
+					...mergedExec != null ? {
+						exec: mergedExec,
+						dependencyRegistry: mergedExec.dependencyRegistry
+					} : {}
+				};
+				matchedParsers.add(index);
+				foundMatch = true;
+				break;
+			} else if (!result.success && result.consumed > 0) {
+				if (result.consumed > deepestFailure) {
+					deepestFailure = result.consumed;
+					failedParserIndexes = [index];
+				} else if (result.consumed === deepestFailure) failedParserIndexes.push(index);
+			}
+		}
+		if (!foundMatch) for (const [parser, index] of remainingParsers) {
+			const result = parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
+			if (result.success && result.consumed.length < 1) {
+				const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : state));
+				const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
+				currentContext = {
+					...currentContext,
+					state: newStateArray,
+					...mergedExec != null ? {
+						exec: mergedExec,
+						dependencyRegistry: mergedExec.dependencyRegistry
+					} : {}
+				};
+				matchedParsers.add(index);
+				foundMatch = true;
+				break;
+			} else if (!result.success && result.consumed < 1) {
+				matchedParsers.add(index);
+				foundMatch = true;
+				break;
+			}
+		}
+		if (!foundMatch) return {
+			context: currentContext,
+			failedParserIndexes
+		};
+	}
+	return {
+		context: currentContext,
+		failedParserIndexes: []
+	};
+}
+async function advanceTupleSuggestContextAsync(context, parsers) {
+	let currentContext = context;
+	const matchedParsers = /* @__PURE__ */ new Set();
+	while (currentContext.buffer.length > 0 && matchedParsers.size < parsers.length) {
+		let foundMatch = false;
+		let failedParserIndexes = [];
+		let deepestFailure = 0;
+		const stateArray = Array.isArray(currentContext.state) ? [...currentContext.state] : parsers.map((parser) => parser.initialState);
+		const remainingParsers = parsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
+		for (const [parser, index] of remainingParsers) {
+			const result = await parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
+			if (result.success && result.consumed.length > 0) {
+				const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : state));
+				const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
+				currentContext = {
+					...currentContext,
+					buffer: result.next.buffer,
+					optionsTerminated: result.next.optionsTerminated,
+					state: newStateArray,
+					...mergedExec != null ? {
+						exec: mergedExec,
+						dependencyRegistry: mergedExec.dependencyRegistry
+					} : {}
+				};
+				matchedParsers.add(index);
+				foundMatch = true;
+				break;
+			} else if (!result.success && result.consumed > 0) {
+				if (result.consumed > deepestFailure) {
+					deepestFailure = result.consumed;
+					failedParserIndexes = [index];
+				} else if (result.consumed === deepestFailure) failedParserIndexes.push(index);
+			}
+		}
+		if (!foundMatch) for (const [parser, index] of remainingParsers) {
+			const result = await parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
+			if (result.success && result.consumed.length < 1) {
+				const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((state, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : state));
+				const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
+				currentContext = {
+					...currentContext,
+					state: newStateArray,
+					...mergedExec != null ? {
+						exec: mergedExec,
+						dependencyRegistry: mergedExec.dependencyRegistry
+					} : {}
+				};
+				matchedParsers.add(index);
+				foundMatch = true;
+				break;
+			} else if (!result.success && result.consumed < 1) {
+				matchedParsers.add(index);
+				foundMatch = true;
+				break;
+			}
+		}
+		if (!foundMatch) return {
+			context: currentContext,
+			failedParserIndexes
+		};
+	}
+	return {
+		context: currentContext,
+		failedParserIndexes: []
+	};
+}
+function markFailedTupleSuggestSources(parsers, stateArray, failedParserIndexes, runtime, parentPath) {
+	if (failedParserIndexes.length < 1) return;
+	const prefix = parentPath ?? [];
+	const failedSourceIds = /* @__PURE__ */ new Set();
+	for (const index of failedParserIndexes) {
+		const parser = parsers[index];
+		if (parser == null) continue;
+		const parserState = stateArray && Array.isArray(stateArray) ? stateArray[index] : parser.initialState;
+		const nodes = getParserSuggestRuntimeNodes(parser, getAnnotatedChildState(stateArray, parserState, parser), [...prefix, index]);
+		for (const node of nodes) {
+			const sourceId = node.parser.dependencyMetadata?.source?.sourceId;
+			if (sourceId != null) failedSourceIds.add(sourceId);
+		}
+	}
+	for (const sourceId of failedSourceIds) runtime.markSourceFailed(sourceId);
+}
 function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
 	if (label != null) validateLabel(label);
@@ -1642,9 +1937,9 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			const stateArray = currentContext.state;
 			const remainingParsers = syncParsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
 			for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext(currentContext, index, stateArray[index]));
+				const result = parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = stateArray.map((s, idx) => idx === index ? result.next.state : s);
+					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -1663,9 +1958,9 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				} else if (!result.success && error.consumed < result.consumed) error = result;
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext(currentContext, index, stateArray[index]));
+				const result = parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = stateArray.map((s, idx) => idx === index ? result.next.state : s);
+					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -1708,10 +2003,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 			const stateArray = currentContext.state;
 			const remainingParsers = parsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
 			for (const [parser, index] of remainingParsers) {
-				const resultOrPromise = parser.parse(withChildContext(currentContext, index, stateArray[index]));
+				const resultOrPromise = parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = stateArray.map((s, idx) => idx === index ? result.next.state : s);
+					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -1730,10 +2025,10 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				} else if (!result.success && error.consumed < result.consumed) error = result;
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const resultOrPromise = parser.parse(withChildContext(currentContext, index, stateArray[index]));
+				const resultOrPromise = parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
 				const result = await resultOrPromise;
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = stateArray.map((s, idx) => idx === index ? result.next.state : s);
+					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -1784,8 +2079,8 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					...exec,
 					dependencyRuntime: runtime
 				};
-				const tuplePairs = syncParsers.map((p, i) => [String(i), p]);
-				const tupleState = Object.fromEntries(stateArray.map((s, i) => [String(i), s]));
+				const tuplePairs = buildIndexedParserPairs(syncParsers);
+				const tupleState = createAnnotatedArrayStateRecord(stateArray);
 				const preCompleted = preCompleteAndRegisterDependencies(tupleState, tuplePairs, runtime.registry, childExec);
 				collectExplicitSourceValues(filterPreCompletedRuntimeNodes(buildRuntimeNodesFromArray(syncParsers, stateArray, exec?.path), new Set(preCompleted.keys())), runtime);
 				const phase3Exec = {
@@ -1831,8 +2126,8 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					...exec,
 					dependencyRuntime: runtime
 				};
-				const tuplePairs = parsers.map((p, i) => [String(i), p]);
-				const tupleState = Object.fromEntries(stateArray.map((s, i) => [String(i), s]));
+				const tuplePairs = buildIndexedParserPairs(parsers);
+				const tupleState = createAnnotatedArrayStateRecord(stateArray);
 				const preCompleted = await preCompleteAndRegisterDependenciesAsync(tupleState, tuplePairs, runtime.registry, childExec);
 				await collectExplicitSourceValuesAsync(filterPreCompletedRuntimeNodes(buildRuntimeNodesFromArray(parsers, stateArray, exec?.path), new Set(preCompleted.keys())), runtime);
 				const phase3Exec = {
@@ -1930,6 +2225,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		configurable: true,
 		enumerable: false
 	});
+	defineInheritedAnnotationParser(tupleParser);
 	return tupleParser;
 }
 function merge(...args) {
@@ -2425,6 +2721,7 @@ function merge(...args) {
 			};
 		}
 	};
+	defineInheritedAnnotationParser(mergeParser);
 	return mergeParser;
 }
 /**
@@ -2437,17 +2734,26 @@ function buildSuggestRegistry(preParsedContext, parsers) {
 	const stateArray = preParsedContext.state;
 	const runtime = createDependencyRuntimeContext(preParsedContext.dependencyRegistry?.clone());
 	if (stateArray && Array.isArray(stateArray)) {
-		const nodes = buildRuntimeNodesFromArray(parsers, stateArray, preParsedContext.exec?.path);
+		const nodes = buildSuggestRuntimeNodesFromArray(parsers, stateArray, preParsedContext.exec?.path);
 		collectExplicitSourceValues(nodes, runtime);
-		collectSourcesFromState(stateArray, runtime);
 		fillMissingSourceDefaults(nodes, runtime);
+		collectSourcesFromState(stateArray, runtime);
+		completeDependencySourceDefaults({
+			...preParsedContext,
+			state: createAnnotatedArrayStateRecord(stateArray)
+		}, buildIndexedParserPairs(parsers), runtime.registry, preParsedContext.exec);
 		const prefix = preParsedContext.exec?.path ?? [];
-		for (let i = 0; i < parsers.length; i++) seedSuggestRuntimeFromFieldParsers(parsers[i], stateArray[i], runtime, [...prefix, i]);
+		for (let i = 0; i < parsers.length; i++) seedSuggestRuntimeFromFieldParsers(parsers[i], getAnnotatedChildState(stateArray, stateArray[i], parsers[i]), runtime, [...prefix, i]);
 	}
 	return {
 		context: {
 			...preParsedContext,
-			dependencyRegistry: runtime.registry
+			dependencyRegistry: runtime.registry,
+			...preParsedContext.exec != null ? { exec: {
+				...preParsedContext.exec,
+				dependencyRuntime: runtime,
+				dependencyRegistry: runtime.registry
+			} } : {}
 		},
 		stateArray
 	};
@@ -2456,17 +2762,26 @@ async function buildSuggestRegistryAsync(preParsedContext, parsers) {
 	const stateArray = preParsedContext.state;
 	const runtime = createDependencyRuntimeContext(preParsedContext.dependencyRegistry?.clone());
 	if (stateArray && Array.isArray(stateArray)) {
-		const nodes = buildRuntimeNodesFromArray(parsers, stateArray, preParsedContext.exec?.path);
+		const nodes = buildSuggestRuntimeNodesFromArray(parsers, stateArray, preParsedContext.exec?.path);
 		await collectExplicitSourceValuesAsync(nodes, runtime);
-		collectSourcesFromState(stateArray, runtime);
 		await fillMissingSourceDefaultsAsync(nodes, runtime);
+		collectSourcesFromState(stateArray, runtime);
+		await completeDependencySourceDefaultsAsync({
+			...preParsedContext,
+			state: createAnnotatedArrayStateRecord(stateArray)
+		}, buildIndexedParserPairs(parsers), runtime.registry, preParsedContext.exec);
 		const prefix = preParsedContext.exec?.path ?? [];
-		for (let i = 0; i < parsers.length; i++) await seedSuggestRuntimeFromFieldParsersAsync(parsers[i], stateArray[i], runtime, [...prefix, i]);
+		for (let i = 0; i < parsers.length; i++) await seedSuggestRuntimeFromFieldParsersAsync(parsers[i], getAnnotatedChildState(stateArray, stateArray[i], parsers[i]), runtime, [...prefix, i]);
 	}
 	return {
 		context: {
 			...preParsedContext,
-			dependencyRegistry: runtime.registry
+			dependencyRegistry: runtime.registry,
+			...preParsedContext.exec != null ? { exec: {
+				...preParsedContext.exec,
+				dependencyRuntime: runtime,
+				dependencyRegistry: runtime.registry
+			} } : {}
 		},
 		stateArray
 	};
@@ -2477,11 +2792,31 @@ function seedSuggestRuntimeFromFieldParsers(parser, state, runtime, parentPath)
 	const duplicateFieldNames = collectDuplicateFieldNames(rawPairs);
 	const pairs = filterDuplicateFieldParsers(rawPairs);
 	const stateRecord = state != null && typeof state === "object" ? state : {};
-	const nodes = buildRuntimeNodesFromPairs(pairs, stateRecord, parentPath);
+	const nodes = buildSuggestRuntimeNodesFromPairs(pairs, stateRecord, parentPath);
 	collectExplicitSourceValues(nodes, runtime);
-	collectSourcesFromState(state, runtime, /* @__PURE__ */ new WeakSet(), duplicateFieldNames);
 	fillMissingSourceDefaults(nodes, runtime);
-	for (const [field, childParser] of pairs) seedSuggestRuntimeFromFieldParsers(childParser, Object.hasOwn(stateRecord, field) ? stateRecord[field] : void 0, runtime, [...parentPath, field]);
+	collectSourcesFromState(state, runtime, /* @__PURE__ */ new WeakSet(), duplicateFieldNames);
+	completeDependencySourceDefaults({
+		buffer: [],
+		optionsTerminated: false,
+		state: stateRecord,
+		usage: parser.usage,
+		dependencyRegistry: runtime.registry,
+		exec: {
+			usage: parser.usage,
+			phase: "suggest",
+			path: parentPath,
+			dependencyRuntime: runtime,
+			dependencyRegistry: runtime.registry
+		}
+	}, pairs, runtime.registry, {
+		usage: parser.usage,
+		phase: "suggest",
+		path: parentPath,
+		dependencyRuntime: runtime,
+		dependencyRegistry: runtime.registry
+	});
+	for (const [field, childParser] of pairs) seedSuggestRuntimeFromFieldParsers(childParser, getAnnotatedFieldState(stateRecord, field, childParser), runtime, [...parentPath, field]);
 }
 async function seedSuggestRuntimeFromFieldParsersAsync(parser, state, runtime, parentPath) {
 	if (!(fieldParsersKey in parser)) return;
@@ -2489,11 +2824,31 @@ async function seedSuggestRuntimeFromFieldParsersAsync(parser, state, runtime, p
 	const duplicateFieldNames = collectDuplicateFieldNames(rawPairs);
 	const pairs = filterDuplicateFieldParsers(rawPairs);
 	const stateRecord = state != null && typeof state === "object" ? state : {};
-	const nodes = buildRuntimeNodesFromPairs(pairs, stateRecord, parentPath);
+	const nodes = buildSuggestRuntimeNodesFromPairs(pairs, stateRecord, parentPath);
 	await collectExplicitSourceValuesAsync(nodes, runtime);
-	collectSourcesFromState(state, runtime, /* @__PURE__ */ new WeakSet(), duplicateFieldNames);
 	await fillMissingSourceDefaultsAsync(nodes, runtime);
-	for (const [field, childParser] of pairs) await seedSuggestRuntimeFromFieldParsersAsync(childParser, Object.hasOwn(stateRecord, field) ? stateRecord[field] : void 0, runtime, [...parentPath, field]);
+	collectSourcesFromState(state, runtime, /* @__PURE__ */ new WeakSet(), duplicateFieldNames);
+	await completeDependencySourceDefaultsAsync({
+		buffer: [],
+		optionsTerminated: false,
+		state: stateRecord,
+		usage: parser.usage,
+		dependencyRegistry: runtime.registry,
+		exec: {
+			usage: parser.usage,
+			phase: "suggest",
+			path: parentPath,
+			dependencyRuntime: runtime,
+			dependencyRegistry: runtime.registry
+		}
+	}, pairs, runtime.registry, {
+		usage: parser.usage,
+		phase: "suggest",
+		path: parentPath,
+		dependencyRuntime: runtime,
+		dependencyRegistry: runtime.registry
+	});
+	for (const [field, childParser] of pairs) await seedSuggestRuntimeFromFieldParsersAsync(childParser, getAnnotatedFieldState(stateRecord, field, childParser), runtime, [...parentPath, field]);
 }
 /**
 * This helper replays child parsers in priority order (mirroring
@@ -2502,7 +2857,7 @@ async function seedSuggestRuntimeFromFieldParsersAsync(parser, state, runtime, p
 */
 function preParseSuggestContext(context, parsers) {
 	if (context.buffer.length < 1 || !Array.isArray(context.state)) return context;
-	return preParseSuggestLoop(context, context.state.slice(), parsers);
+	return preParseSuggestLoop(context, annotateFreshArray(context.state, context.state.slice()), parsers);
 }
 /**
 * Async variant of {@link preParseSuggestContext} that awaits async child
@@ -2511,7 +2866,7 @@ function preParseSuggestContext(context, parsers) {
 */
 async function preParseSuggestContextAsync(context, parsers) {
 	if (context.buffer.length < 1 || !Array.isArray(context.state)) return context;
-	return await preParseSuggestLoop(context, context.state.slice(), parsers);
+	return await preParseSuggestLoop(context, annotateFreshArray(context.state, context.state.slice()), parsers);
 }
 /**
 * Shared loop for sync and async concat suggest pre-parse.  When a child
@@ -2547,12 +2902,12 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 	for (let ri = 0; ri < remaining.length; ri++) {
 		const [parser, index] = remaining[ri];
 		const parserState = index < stateArray.length ? stateArray[index] : parser.initialState;
-		const resultOrPromise = parser.parse(withChildContext(context, index, parserState));
+		const resultOrPromise = parser.parse(withChildContext(context, index, parserState, parser));
 		if (resultOrPromise != null && typeof resultOrPromise === "object" && "then" in resultOrPromise && typeof resultOrPromise.then === "function") {
 			const tail = remaining.slice(ri + 1);
 			return resultOrPromise.then((result$1) => {
 				if (result$1.success && result$1.consumed.length > 0) {
-					stateArray[index] = result$1.next.state;
+					stateArray[index] = getAnnotatedChildState(context.state, result$1.next.state, parser);
 					matchedParsers.add(index);
 					const mergedExec = mergeChildExec(context.exec, result$1.next.exec);
 					return preParseSuggestLoop({
@@ -2579,7 +2934,7 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 		}
 		const result = resultOrPromise;
 		if (result.success && result.consumed.length > 0) {
-			stateArray[index] = result.next.state;
+			stateArray[index] = getAnnotatedChildState(context.state, result.next.state, parser);
 			matchedParsers.add(index);
 			const mergedExec = mergeChildExec(context.exec, result.next.exec);
 			return {
@@ -2616,9 +2971,9 @@ function concat(...parsers) {
 			const stateArray = currentContext.state;
 			const remainingParsers = syncParsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
 			for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext(currentContext, index, stateArray[index]));
+				const result = parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = stateArray.map((s, idx) => idx === index ? result.next.state : s);
+					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -2637,9 +2992,9 @@ function concat(...parsers) {
 				} else if (!result.success && error.consumed < result.consumed) error = result;
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const result = parser.parse(withChildContext(currentContext, index, stateArray[index]));
+				const result = parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = stateArray.map((s, idx) => idx === index ? result.next.state : s);
+					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -2682,9 +3037,9 @@ function concat(...parsers) {
 			const stateArray = currentContext.state;
 			const remainingParsers = parsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
 			for (const [parser, index] of remainingParsers) {
-				const result = await parser.parse(withChildContext(currentContext, index, stateArray[index]));
+				const result = await parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length > 0) {
-					const newStateArray = stateArray.map((s, idx) => idx === index ? result.next.state : s);
+					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -2703,9 +3058,9 @@ function concat(...parsers) {
 				} else if (!result.success && error.consumed < result.consumed) error = result;
 			}
 			if (!foundMatch) for (const [parser, index] of remainingParsers) {
-				const result = await parser.parse(withChildContext(currentContext, index, stateArray[index]));
+				const result = await parser.parse(withChildContext(currentContext, index, stateArray[index], parser));
 				if (result.success && result.consumed.length < 1) {
-					const newStateArray = stateArray.map((s, idx) => idx === index ? result.next.state : s);
+					const newStateArray = annotateFreshArray(currentContext.state, stateArray.map((s, idx) => idx === index ? getAnnotatedChildState(currentContext.state, result.next.state, parser) : s));
 					const mergedExec = mergeChildExec(currentContext.exec, result.next.exec);
 					currentContext = {
 						...currentContext,
@@ -2740,7 +3095,14 @@ function concat(...parsers) {
 		const runtime = exec?.dependencyRuntime ?? createDependencyRuntimeContext(exec?.dependencyRegistry);
 		const childExec = {
 			...exec,
-			dependencyRuntime: runtime,
+			dependencyRuntime: runtime
+		};
+		const concatPairs = buildIndexedParserPairs(syncParsers);
+		const concatState = createAnnotatedArrayStateRecord(stateArray);
+		const preCompleted = preCompleteAndRegisterDependencies(concatState, concatPairs, runtime.registry, childExec);
+		collectExplicitSourceValues(filterPreCompletedRuntimeNodes(buildRuntimeNodesFromArray(syncParsers, stateArray, exec?.path), new Set(preCompleted.keys())), runtime);
+		const phase3Exec = {
+			...childExec,
 			preCompletedByParser: void 0
 		};
 		const resolvedArray = resolveStateWithRuntime(stateArray, runtime);
@@ -2749,8 +3111,8 @@ function concat(...parsers) {
 		let hasDeferred = false;
 		for (let i = 0; i < syncParsers.length; i++) {
 			const parser = syncParsers[i];
-			const parserState = prepareStateForCompletion(resolvedArray[i], parser);
-			const result = unwrapCompleteResult(parser.complete(parserState, withChildExecPath(childExec, i)));
+			const preCompletedResult = preCompleted.get(String(i));
+			const result = preCompletedResult !== void 0 ? unwrapCompleteResult(preCompletedResult) : unwrapCompleteResult(parser.complete(prepareStateForCompletion(resolvedArray[i], parser), withChildExecPath(phase3Exec, i)));
 			if (!result.success) return result;
 			const baseIndex = results.length;
 			if (Array.isArray(result.value)) {
@@ -2783,7 +3145,14 @@ function concat(...parsers) {
 		const runtime = exec?.dependencyRuntime ?? createDependencyRuntimeContext(exec?.dependencyRegistry);
 		const childExec = {
 			...exec,
-			dependencyRuntime: runtime,
+			dependencyRuntime: runtime
+		};
+		const concatPairs = buildIndexedParserPairs(parsers);
+		const concatState = createAnnotatedArrayStateRecord(stateArray);
+		const preCompleted = await preCompleteAndRegisterDependenciesAsync(concatState, concatPairs, runtime.registry, childExec);
+		await collectExplicitSourceValuesAsync(filterPreCompletedRuntimeNodes(buildRuntimeNodesFromArray(parsers, stateArray, exec?.path), new Set(preCompleted.keys())), runtime);
+		const phase3Exec = {
+			...childExec,
 			preCompletedByParser: void 0
 		};
 		const resolvedArray = await resolveStateWithRuntimeAsync(stateArray, runtime);
@@ -2792,8 +3161,8 @@ function concat(...parsers) {
 		let hasDeferred = false;
 		for (let i = 0; i < parsers.length; i++) {
 			const parser = parsers[i];
-			const parserState = prepareStateForCompletion(resolvedArray[i], parser);
-			const result = unwrapCompleteResult(await parser.complete(parserState, withChildExecPath(childExec, i)));
+			const preCompletedResult = preCompleted.get(String(i));
+			const result = preCompletedResult !== void 0 ? unwrapCompleteResult(preCompletedResult) : unwrapCompleteResult(await parser.complete(prepareStateForCompletion(resolvedArray[i], parser), withChildExecPath(phase3Exec, i)));
 			if (!result.success) return result;
 			const baseIndex = results.length;
 			if (Array.isArray(result.value)) {
@@ -2821,7 +3190,7 @@ function concat(...parsers) {
 			} : {}
 		};
 	};
-	return {
+	const concatParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -2846,7 +3215,7 @@ function concat(...parsers) {
 				for (let i = 0; i < parsers.length; i++) {
 					const parser = parsers[i];
 					const parserState = stateArray$1 && Array.isArray(stateArray$1) ? stateArray$1[i] : parser.initialState;
-					const parserSuggestions = parser.suggest(withChildContext(contextWithRegistry$1, i, parserState), prefix);
+					const parserSuggestions = parser.suggest(withChildContext(contextWithRegistry$1, i, parserState, parser), prefix);
 					if (parser.$mode === "async") for await (const s of parserSuggestions) suggestions.push(s);
 					else suggestions.push(...parserSuggestions);
 				}
@@ -2859,7 +3228,7 @@ function concat(...parsers) {
 				for (let i = 0; i < syncParsers.length; i++) {
 					const parser = syncParsers[i];
 					const parserState = stateArray && Array.isArray(stateArray) ? stateArray[i] : parser.initialState;
-					const parserSuggestions = parser.suggest(withChildContext(contextWithRegistry, i, parserState), prefix);
+					const parserSuggestions = parser.suggest(withChildContext(contextWithRegistry, i, parserState, parser), prefix);
 					suggestions.push(...parserSuggestions);
 				}
 				yield* deduplicateSuggestions(suggestions);
@@ -2891,6 +3260,8 @@ function concat(...parsers) {
 			return { fragments: result };
 		}
 	};
+	defineInheritedAnnotationParser(concatParser);
+	return concatParser;
 }
 function group(label, parser, options = {}) {
 	validateLabel(label);
@@ -3054,7 +3425,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		const syncDefaultBranch = defaultBranch;
 		if (state.selectedBranch !== void 0) {
 			const branchParser = state.selectedBranch.kind === "default" ? syncDefaultBranch : syncBranches[state.selectedBranch.key];
-			const branchResult = branchParser.parse(withChildContext(context, "_branch", state.branchState, branchParser.usage));
+			const branchResult = branchParser.parse(withChildContext(context, "_branch", state.branchState, branchParser, branchParser.usage));
 			if (branchResult.success) {
 				const mergedExec = mergeChildExec(context.exec, branchResult.next.exec);
 				return {
@@ -3090,7 +3461,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 								exec: discriminatorExec,
 								dependencyRegistry: discriminatorExec.dependencyRegistry
 							} : {}
-						}, "_branch", branchParser.initialState, branchParser.usage),
+						}, "_branch", branchParser.initialState, branchParser, branchParser.usage),
 						buffer: discriminatorResult.next.buffer,
 						optionsTerminated: discriminatorResult.next.optionsTerminated
 					});
@@ -3141,7 +3512,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			}
 		}
 		if (syncDefaultBranch !== void 0) {
-			const defaultResult = syncDefaultBranch.parse(withChildContext(context, "_branch", state.branchState ?? syncDefaultBranch.initialState, syncDefaultBranch.usage));
+			const defaultResult = syncDefaultBranch.parse(withChildContext(context, "_branch", state.branchState ?? syncDefaultBranch.initialState, syncDefaultBranch, syncDefaultBranch.usage));
 			if (defaultResult.success && defaultResult.consumed.length > 0) {
 				const mergedExec = mergeChildExec(context.exec, defaultResult.next.exec);
 				return {
@@ -3172,7 +3543,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		const state = context.state ?? initialState;
 		if (state.selectedBranch !== void 0) {
 			const branchParser = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
-			const branchResult = await branchParser.parse(withChildContext(context, "_branch", state.branchState, branchParser.usage));
+			const branchResult = await branchParser.parse(withChildContext(context, "_branch", state.branchState, branchParser, branchParser.usage));
 			if (branchResult.success) {
 				const mergedExec = mergeChildExec(context.exec, branchResult.next.exec);
 				return {
@@ -3208,7 +3579,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 								exec: discriminatorExec,
 								dependencyRegistry: discriminatorExec.dependencyRegistry
 							} : {}
-						}, "_branch", branchParser.initialState, branchParser.usage),
+						}, "_branch", branchParser.initialState, branchParser, branchParser.usage),
 						buffer: discriminatorResult.next.buffer,
 						optionsTerminated: discriminatorResult.next.optionsTerminated
 					});
@@ -3259,7 +3630,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			}
 		}
 		if (defaultBranch !== void 0) {
-			const defaultResult = await defaultBranch.parse(withChildContext(context, "_branch", state.branchState ?? defaultBranch.initialState, defaultBranch.usage));
+			const defaultResult = await defaultBranch.parse(withChildContext(context, "_branch", state.branchState ?? defaultBranch.initialState, defaultBranch, defaultBranch.usage));
 			if (defaultResult.success && defaultResult.consumed.length > 0) {
 				const mergedExec = mergeChildExec(context.exec, defaultResult.next.exec);
 				return {
@@ -3293,7 +3664,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		if (state.selectedBranch === void 0) {
 			if (syncDefaultBranch !== void 0) {
 				const branchState = state.branchState ?? syncDefaultBranch.initialState;
-				const defaultResult = syncDefaultBranch.complete(branchState, withChildExecPath(exec, "_branch"));
+				const defaultResult = unwrapCompleteResult(syncDefaultBranch.complete(branchState, withChildExecPath(exec, "_branch")));
 				if (!defaultResult.success) return defaultResult;
 				return {
 					success: true,
@@ -3329,7 +3700,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			dependencyRegistry: runtime.registry
 		};
 		const discriminatorCompleteResult = state.selectedBranch.kind === "default" ? void 0 : syncDiscriminator.complete(state.discriminatorState, withChildExecPath(completionExec, "_discriminator"));
-		const branchResult = branchParser.complete(resolvedBranchState, withChildExecPath(completionExec, "_branch"));
+		const branchResult = unwrapCompleteResult(branchParser.complete(resolvedBranchState, withChildExecPath(completionExec, "_branch")));
 		if (!branchResult.success) {
 			if (state.discriminatorValue !== void 0 && options?.errors?.branchError) return {
 				success: false,
@@ -3356,7 +3727,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		if (state.selectedBranch === void 0) {
 			if (defaultBranch !== void 0) {
 				const branchState = state.branchState ?? defaultBranch.initialState;
-				const defaultResult = await defaultBranch.complete(branchState, withChildExecPath(exec, "_branch"));
+				const defaultResult = unwrapCompleteResult(await defaultBranch.complete(branchState, withChildExecPath(exec, "_branch")));
 				if (!defaultResult.success) return defaultResult;
 				return {
 					success: true,
@@ -3392,7 +3763,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			dependencyRegistry: runtime.registry
 		};
 		const discriminatorCompleteResult = state.selectedBranch.kind === "default" ? void 0 : await discriminator.complete(state.discriminatorState, withChildExecPath(completionExec, "_discriminator"));
-		const branchResult = await branchParser.complete(resolvedBranchState, withChildExecPath(completionExec, "_branch"));
+		const branchResult = unwrapCompleteResult(await branchParser.complete(resolvedBranchState, withChildExecPath(completionExec, "_branch")));
 		if (!branchResult.success) {
 			if (state.discriminatorValue !== void 0 && options?.errors?.branchError) return {
 				success: false,
@@ -3506,7 +3877,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			yield* branchParser.suggest(withChildContext(suggestContext, "_branch", state.branchState), prefix);
 		}
 	}
-	return {
+	const conditionalParser = {
 		$mode: combinedMode,
 		$valueType: [],
 		$stateType: [],
@@ -3554,6 +3925,8 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			return { fragments };
 		}
 	};
+	defineInheritedAnnotationParser(conditionalParser);
+	return conditionalParser;
 }
 
 //#endregion