@optique/core 1.3.0-dev.2379 → 1.3.0-dev.2380

package/dist/constructs.js

@@ -5,7 +5,7 @@ import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDoc
 import { deduplicateDocFragments } from "./doc.js";
 import { dispatchByMode, dispatchIterableByMode } from "./internal/mode-dispatch.js";
 import { createDependencySourceState, dependencyId, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, wrappedDependencySourceMarker } from "./internal/dependency.js";
-import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyRuntimeContext, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync } from "./dependency-runtime.js";
+import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyRuntimeContext, effectfulSchedulingNodesKey, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync } from "./dependency-runtime.js";
 import { defineInheritedAnnotationParser, defineParseLanes, getOwnParseLanes, getParserSuggestRuntimeNodes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { annotationViewTargets, getWrappedChildParseState, getWrappedChildState, reconcileObjectChildState, unwrapAnnotationView } from "./annotation-state.js";
 import { allowDuplicateLeadingCommandNamesKey } from "./internal/command-alias.js";
@@ -58,6 +58,117 @@ function filterPreCompletedRuntimeNodes(nodes, preCompletedKeys) {
 		return segment == null || !preCompletedKeys.has(segment);
 	});
 }
+/**
+* Runs the effectful source completion pass for a construct's direct
+* children and merges the completed results into the construct's
+* pre-completed cache so its final completion phase reuses them instead
+* of completing the same field twice.
+*
+* Returns a failure when an effectful completion fails (e.g., a cancelled
+* prompt); the construct should propagate it as its own completion
+* failure.  Returns `undefined` on success.
+*/
+/**
+* Expands runtime nodes through nested constructs for effectful source
+* scheduling and demand detection.
+*
+* A node without effectful-source or consumer metadata whose parser
+* exposes child field pairs (e.g., a `tuple()` child of `concat()`, or a
+* nested `object()` field) is replaced by nodes for its children so that
+* an effectful source nested one or more constructs deep is still
+* completed before any sibling consumer completes.  Array states use
+* numeric path segments and record states use their field keys, matching
+* the paths that child completion (and parse-time tracing) uses.
+*/
+function expandEffectfulRuntimeNodes(nodes) {
+	const expanded = [];
+	const visit = (node) => {
+		const meta = node.parser.dependencyMetadata;
+		if (meta?.source?.completeSource != null || meta?.derived != null) {
+			expanded.push(node);
+			return;
+		}
+		const schedulingNodes = node.parser[effectfulSchedulingNodesKey];
+		if (schedulingNodes != null) {
+			for (const child of schedulingNodes(node.state, node.path)) visit(child);
+			return;
+		}
+		const pairs = node.parser[fieldParsersKey];
+		if (pairs == null || node.state == null || typeof node.state !== "object") {
+			expanded.push(node);
+			return;
+		}
+		const duplicateFieldNames = collectDuplicateFieldNames(pairs);
+		const state = node.state;
+		for (const [field, childParser] of pairs) {
+			if (duplicateFieldNames.has(field)) continue;
+			const segment = Array.isArray(state) && typeof field === "string" ? Number(field) : field;
+			const childState = Array.isArray(state) ? state[segment] : state[field];
+			visit({
+				path: [...node.path, segment],
+				parser: childParser,
+				state: getWrappedChildState(state, childState, childParser)
+			});
+		}
+	};
+	for (const node of nodes) visit(node);
+	return expanded;
+}
+function isDeferredCompletionResult(result) {
+	return typeof result === "object" && result !== null && "success" in result && result.success === true && "deferred" in result && result.deferred === true;
+}
+/**
+* Returns the keys of pre-completed results that are settled (not
+* deferred).
+*
+* A deferred pre-completion—e.g., a demand-only prompt invoked during
+* Phase 1 through a source binding wrapper, before consumer demand was
+* known—must remain visible to the effectful scheduling pass so it can
+* complete once demand is discovered; the scheduler then replaces the
+* cached placeholder result with the real one.
+*/
+function settledPreCompletedKeys(preCompleted) {
+	const keys = /* @__PURE__ */ new Set();
+	for (const [key, result] of preCompleted) {
+		if (isDeferredCompletionResult(result)) continue;
+		keys.add(key);
+	}
+	return keys;
+}
+/**
+* Returns the first failure among pre-completed results, if any.
+*
+* A failed pre-completion (e.g., a prompt cancelled during Phase 1
+* through a source binding wrapper) fails the construct in its final
+* completion phase anyway, so the scheduling pass must not run further
+* effectful completions after it—cancellation stops later prompts
+* immediately.
+*/
+function firstPreCompletedFailure(preCompleted) {
+	for (const result of preCompleted.values()) if (typeof result === "object" && result !== null && "success" in result && result.success === false && "error" in result) return result.error;
+	return void 0;
+}
+async function scheduleEffectfulSourceCompletions(nodes, state, runtime, exec, preCompleted, demandNodes) {
+	const preCompletedFailure = firstPreCompletedFailure(preCompleted);
+	if (preCompletedFailure != null) return {
+		success: false,
+		error: preCompletedFailure
+	};
+	const direct = new Set(nodes);
+	const effectful = await completeEffectfulSourcesAsync(expandEffectfulRuntimeNodes(nodes), state, runtime, exec, {
+		...demandNodes != null ? { demandNodes: expandEffectfulRuntimeNodes(demandNodes) } : {},
+		isReusable: (node) => direct.has(node)
+	});
+	if (!effectful.success) return {
+		success: false,
+		error: effectful.error
+	};
+	for (const { key, result } of effectful.completed) {
+		const cacheKey = typeof key === "number" ? String(key) : key;
+		preCompleted.set(cacheKey, result);
+	}
+	return void 0;
+}
 function buildIndexedParserPairs(parsers) {
 	return parsers.map((parser, index) => [String(index), parser]);
 }
@@ -792,16 +903,42 @@ function getNoMatchError(options, noMatchContext) {
 	const customNoMatch = options?.errors?.noMatch;
 	return customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
 }
+/**
+* Installs the effectful scheduling hook on an exclusive parser
+* (`or()`/`longestMatch()`), exposing the committed branch so a parent
+* construct's scheduling expansion can complete a source nested in the
+* selected branch before parent-level dependency replay.  The branch
+* node's path appends the branch index, matching the execution path used
+* when the committed branch completes.
+*/
+function defineExclusiveSchedulingNodes(exclusiveParser, parsers) {
+	Object.defineProperty(exclusiveParser, effectfulSchedulingNodesKey, {
+		value: ((state, parentPath) => {
+			const active = normalizeExclusiveState(state);
+			if (active == null) return [];
+			const [index, result] = active;
+			if (result?.success !== true) return [];
+			return [{
+				path: [...parentPath ?? [], index],
+				parser: parsers[index],
+				state: result.next.state
+			}];
+		}),
+		configurable: true,
+		enumerable: false
+	});
+}
 function composeExclusiveDependencyMetadata(parsers) {
 	const sourceBranches = parsers.filter((parser) => parser.dependencyMetadata?.source != null);
 	if (sourceBranches.length < 1) return void 0;
 	const sourceIds = new Set(sourceBranches.map((parser) => parser.dependencyMetadata.source.sourceId));
 	if (sourceIds.size !== 1) return void 0;
 	const sharedSource = sourceBranches[0].dependencyMetadata.source;
+	const everyBranchPreserves = sourceBranches.length === parsers.length && sourceBranches.every((parser) => parser.dependencyMetadata?.source?.preservesSourceValue !== false);
 	return { source: {
 		...sharedSource,
 		getMissingSourceValue: void 0,
-		preservesSourceValue: sourceBranches.every((parser) => parser.dependencyMetadata?.source?.preservesSourceValue !== false),
+		preservesSourceValue: everyBranchPreserves,
 		extractSourceValue(state) {
 			if (!Array.isArray(state) || state.length !== 2 || typeof state[0] !== "number") return void 0;
 			const [index, parserResult] = state;
@@ -809,6 +946,14 @@ function composeExclusiveDependencyMetadata(parsers) {
 			const branchSource = parsers[index].dependencyMetadata?.source;
 			if (branchSource?.extractSourceValue == null) return void 0;
 			return branchSource.extractSourceValue(parserResult.next.state);
+		},
+		completeSource(state, exec) {
+			if (!Array.isArray(state) || state.length !== 2 || typeof state[0] !== "number") return Promise.resolve(void 0);
+			const [index, parserResult] = state;
+			if (!parserResult?.success) return Promise.resolve(void 0);
+			const branchSource = parsers[index].dependencyMetadata?.source;
+			if (branchSource?.completeSource == null) return Promise.resolve(void 0);
+			return branchSource.completeSource(parserResult.next.state, exec);
 		}
 	} };
 }
@@ -1310,6 +1455,7 @@ function or(...args) {
 	};
 	const singleDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
 	if (singleDependencyMetadata != null) singleResult.dependencyMetadata = singleDependencyMetadata;
+	defineExclusiveSchedulingNodes(singleResult, parsers);
 	defineInheritedAnnotationParser(singleResult);
 	return fluent(singleResult);
 }
@@ -1525,6 +1671,7 @@ function createLongestMatch(...args) {
 	};
 	const multiDependencyMetadata = composeExclusiveDependencyMetadata(parsers);
 	if (multiDependencyMetadata != null) multiResult.dependencyMetadata = multiDependencyMetadata;
+	defineExclusiveSchedulingNodes(multiResult, parsers);
 	defineInheritedAnnotationParser(multiResult);
 	return fluent(multiResult);
 }
@@ -1634,8 +1781,11 @@ async function* suggestObjectAsync(context, prefix, parserPairs) {
 *
 * @internal
 */
-function registerCompletedDependency(completed, registry) {
-	if (isDependencySourceState(completed) && completed.result.success && !registry.has(completed[dependencyId])) registry.set(completed[dependencyId], completed.result.value);
+function registerCompletedDependency(completed, registry, exec) {
+	if (!isDependencySourceState(completed) || !completed.result.success) return;
+	const sourceId = completed[dependencyId];
+	const effectful = exec?.effectfulCompletionSession?.effectfulSources.has(sourceId) === true;
+	if (effectful || !registry.has(sourceId)) registry.set(sourceId, completed.result.value);
 }
 /**
 * Yields `(parser, state)` pairs for dependency source parsers whose field
@@ -1713,6 +1863,7 @@ function wrapAsDependencySourceState(completed, parser) {
 	const metadataSource = parser.dependencyMetadata?.source;
 	if (metadataSource?.preservesSourceValue === false) return void 0;
 	const hasDep = metadataSource != null || isWrappedDependencySource(parser) || isPendingDependencySourceState(parser.initialState);
+	if (isDeferredCompletionResult(completed)) return void 0;
 	if (hasDep && typeof completed === "object" && completed !== null && "success" in completed && completed.success && "value" in completed && completed.value !== void 0) {
 		const depId = metadataSource?.sourceId ?? (isWrappedDependencySource(parser) ? parser[wrappedDependencySourceMarker][dependencyId] : parser.initialState[dependencyId]);
 		return createDependencySourceState(completed, depId);
@@ -1856,47 +2007,49 @@ async function preCompleteAndRegisterDependenciesAsync(state, fieldParserPairs,
 	const preCompleted = /* @__PURE__ */ new Map();
 	const parentResults = exec?.preCompletedByParser;
 	for (const [field, fieldParser] of fieldParserPairs) {
+		if (firstPreCompletedFailure(preCompleted) != null) break;
 		const cached = parentResults?.get(field);
 		if (cached !== void 0) {
 			preCompleted.set(field, cached);
-			registerCompletedDependency(cached, registry);
+			registerCompletedDependency(cached, registry, exec);
 			continue;
 		}
+		if (fieldParser.dependencyMetadata?.source?.completeSource != null) continue;
 		const fieldState = state[field];
 		const annotatedFieldState = getAnnotatedFieldState(state, field, fieldParser);
 		if (fieldParser.dependencyMetadata?.source?.getMissingSourceValue != null && isUnmatchedDependencyState(fieldState, fieldParser)) {
 			const completed = await fieldParser.complete(annotatedFieldState, withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
 			const depState = wrapAsDependencySourceState(completed, fieldParser);
-			if (depState) registerCompletedDependency(depState, registry);
+			if (depState) registerCompletedDependency(depState, registry, exec);
 			continue;
 		}
 		if (fieldParser.dependencyMetadata?.source != null && isUnmatchedDependencyState(fieldState, fieldParser) && (annotatedFieldState !== fieldState || isNonCliBoundSourceState(fieldState, fieldParser))) {
 			const completed = await fieldParser.complete(annotatedFieldState, withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
 			const depState = wrapAsDependencySourceState(completed, fieldParser);
-			if (depState) registerCompletedDependency(depState, registry);
+			if (depState) registerCompletedDependency(depState, registry, exec);
 			continue;
 		}
 		if (Array.isArray(fieldState) && fieldState.length === 1 && isPendingDependencySourceState(fieldState[0])) {
 			const completed = await fieldParser.complete(fieldState, withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+			if (isDependencySourceState(completed)) registerCompletedDependency(completed, registry, exec);
 		} else if (fieldState === void 0 && isPendingDependencySourceState(fieldParser.initialState)) {
 			const completed = await fieldParser.complete([fieldParser.initialState], withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+			if (isDependencySourceState(completed)) registerCompletedDependency(completed, registry, exec);
 		} else if (fieldState === void 0 && isWrappedDependencySource(fieldParser)) {
 			const pendingState = fieldParser[wrappedDependencySourceMarker];
 			const completed = await fieldParser.complete([pendingState], withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
-			if (isDependencySourceState(completed)) registerCompletedDependency(completed, registry);
+			if (isDependencySourceState(completed)) registerCompletedDependency(completed, registry, exec);
 		} else if (fieldState != null && !Array.isArray(fieldState) && !isDependencySourceState(fieldState) && (isWrappedDependencySource(fieldParser) || isPendingDependencySourceState(fieldParser.initialState))) {
 			const annotatedFieldState$1 = getAnnotatedFieldState(state, field, fieldParser);
 			const completed = await fieldParser.complete(annotatedFieldState$1, withChildExecPath(exec, field));
 			preCompleted.set(field, completed);
 			const depState = wrapAsDependencySourceState(completed, fieldParser);
-			if (depState) registerCompletedDependency(depState, registry);
+			if (depState) registerCompletedDependency(depState, registry, exec);
 		}
 	}
 	return preCompleted;
@@ -2307,7 +2460,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					const fieldParser = parsers[field];
 					annotatedState[fieldKey] = getFieldState(field, fieldParser);
 				}
-				await collectExplicitSourceValuesAsync(filterPreCompletedRuntimeNodes(buildRuntimeNodesFromPairs(asyncParserPairs, annotatedState, exec?.path), new Set(preCompleted.keys())), runtime);
+				const allRuntimeNodes = buildRuntimeNodesFromPairs(asyncParserPairs, annotatedState, exec?.path);
+				const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
+				await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
+				const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), annotatedState, runtime, childExec, preCompleted);
+				if (effectfulFailure != null) return effectfulFailure;
 				const resolvedFieldStates = await resolveStateWithRuntimeAsync(annotatedState, runtime);
 				const result = {};
 				const deferredKeys = /* @__PURE__ */ new Map();
@@ -2429,7 +2586,11 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					const fieldParser = parsers[field];
 					annotatedState[fieldKey] = getFieldState(field, fieldParser);
 				}
-				await collectExplicitSourceValuesAsync(filterPreCompletedRuntimeNodes(buildRuntimeNodesFromPairs(asyncParserPairs, annotatedState, exec?.path), new Set(preCompleted.keys())), runtime);
+				const allRuntimeNodes = buildRuntimeNodesFromPairs(asyncParserPairs, annotatedState, exec?.path);
+				const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
+				await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
+				const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), annotatedState, runtime, childExec, preCompleted);
+				if (effectfulFailure != null) return null;
 				const resolvedFieldStates = await resolveStateWithRuntimeAsync(annotatedState, runtime);
 				const result = {};
 				const deferredKeys = /* @__PURE__ */ new Map();
@@ -2848,7 +3009,11 @@ function createSeqComplete(parsers, combinedMode) {
 		const pairs = buildIndexedParserPairs(parsers);
 		const stateRecord = createAnnotatedArrayStateRecord(stateArray);
 		const preCompleted = await preCompleteAndRegisterDependenciesAsync(stateRecord, pairs, runtime.registry, childExec);
-		await collectExplicitSourceValuesAsync(filterPreCompletedRuntimeNodes(buildRuntimeNodesFromArray(parsers, stateArray, exec?.path), new Set(preCompleted.keys())), runtime);
+		const allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
+		const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
+		await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
+		const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
+		if (effectfulFailure != null) return effectfulFailure;
 		const phase3Exec = {
 			...childExec,
 			preCompletedByParser: void 0
@@ -3339,7 +3504,11 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				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 allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
+				const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
+				await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
+				const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
+				if (effectfulFailure != null) return effectfulFailure;
 				const phase3Exec = {
 					...childExec,
 					preCompletedByParser: void 0
@@ -3423,7 +3592,11 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 				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 allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
+				const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
+				await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
+				const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
+				if (effectfulFailure != null) return null;
 				const phase3Exec = {
 					...childExec,
 					preCompletedByParser: void 0
@@ -3685,7 +3858,11 @@ function seq(...rawArgs) {
 				const pairs = buildIndexedParserPairs(parsers);
 				const stateRecord = createAnnotatedArrayStateRecord(stateArray);
 				const preCompleted = await preCompleteAndRegisterDependenciesAsync(stateRecord, pairs, runtime.registry, childExec);
-				await collectExplicitSourceValuesAsync(filterPreCompletedRuntimeNodes(buildRuntimeNodesFromArray(parsers, stateArray, exec?.path), new Set(preCompleted.keys())), runtime);
+				const allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
+				const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
+				await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
+				const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
+				if (effectfulFailure != null) return null;
 				const phase3Exec = {
 					...childExec,
 					preCompletedByParser: void 0
@@ -3868,6 +4045,43 @@ function merge(...args) {
 	const noMatchContext = analyzeNoMatchContext(rawParsers);
 	const mergedFieldParsers = collectChildFieldParsers(parsers);
 	const duplicateOutputFieldNames = collectDuplicateFieldNames(mergedFieldParsers);
+	const sortedIndexByOriginal = [];
+	sorted.forEach(([, originalIndex], sortedIndex) => {
+		sortedIndexByOriginal[originalIndex] = sortedIndex;
+	});
+	const buildMergeSchedulingNodes = (state, parentPath) => {
+		const extractChildSchedulingState = (parser, sortedIndex) => {
+			if (parser.initialState === void 0) {
+				const key = parserStateKey(sortedIndex);
+				return key in state ? state[key] : void 0;
+			}
+			if (parser.initialState && typeof parser.initialState === "object") {
+				const key = localObjectStateKey(sortedIndex);
+				if (shouldPreserveLocalChildState(parser) && key in state) return state[key];
+			}
+			return state;
+		};
+		const nodes = [];
+		rawParsers.forEach((parser, originalIndex) => {
+			if (!(fieldParsersKey in parser)) {
+				if (effectfulSchedulingNodesKey in parser) {
+					const sortedIndex = sortedIndexByOriginal[originalIndex];
+					nodes.push({
+						path: [...parentPath ?? [], sortedIndex],
+						parser,
+						state: extractChildSchedulingState(parser, sortedIndex)
+					});
+				}
+				return;
+			}
+			const pairs = parser[fieldParsersKey];
+			const unambiguousPairs = pairs.filter(([field]) => !duplicateOutputFieldNames.has(field));
+			const annotatedState = {};
+			for (const [field, fieldParser] of unambiguousPairs) annotatedState[field] = getAnnotatedFieldState(state, field, fieldParser);
+			nodes.push(...buildRuntimeNodesFromPairs(unambiguousPairs, annotatedState, [...parentPath ?? [], sortedIndexByOriginal[originalIndex]]));
+		});
+		return nodes;
+	};
 	const parserStateKey = (index) => `__parser_${index}`;
 	const localObjectStateKey = (index) => `__merge_local_${index}`;
 	const shouldPreserveLocalChildState = (parser) => parser.initialState != null && typeof parser.initialState === "object" && Object.keys(parser.initialState).some((field) => duplicateOutputFieldNames.has(field));
@@ -4271,6 +4485,7 @@ function merge(...args) {
 		$valueType: [],
 		$stateType: [],
 		[fieldParsersKey]: mergedFieldParsers,
+		[effectfulSchedulingNodesKey]: ((state, parentPath) => state != null && typeof state === "object" ? buildMergeSchedulingNodes(state, parentPath) : []),
 		priority: Math.max(...mergeParseLanes.map((lane) => lane.priority)),
 		usage: applyHiddenToUsage(parsers.flatMap((p) => p.usage), options.hidden),
 		leadingNames: sharedBufferLeadingNames(mergeParseLanes),
@@ -4379,25 +4594,50 @@ function merge(...args) {
 					dependencyRuntime: runtime
 				};
 				const duplicateFieldNames = collectDuplicateFieldNames(mergedFieldParsers);
-				const unambiguousFieldParsers = filterDuplicateFieldParsers(mergedFieldParsers);
-				const perChildPhase1 = [];
-				for (let i = 0; i < parsers.length; i++) {
-					const parser = parsers[i];
+				const perChildPhase1 = new Array(parsers.length);
+				for (let originalIndex = 0; originalIndex < rawParsers.length; originalIndex++) {
+					const parser = rawParsers[originalIndex];
+					const sortedIndex = sortedIndexByOriginal[originalIndex];
 					if (fieldParsersKey in parser) {
 						const pairs = parser[fieldParsersKey];
 						const excludedSourceFields = new Set(pairs.map(([field]) => field).filter((field) => duplicateFieldNames.has(field)));
 						const phase1Pairs = filterExcludedFieldParsers(pairs, excludedSourceFields);
-						const preCompleted = await preCompleteAndRegisterDependenciesAsync(state, phase1Pairs, runtime.registry, withChildExecPath(childExec, i));
-						perChildPhase1.push({
+						const preCompleted = await preCompleteAndRegisterDependenciesAsync(state, phase1Pairs, runtime.registry, withChildExecPath(childExec, sortedIndex));
+						const failure = firstPreCompletedFailure(preCompleted);
+						if (failure != null) return {
+							success: false,
+							error: failure
+						};
+						perChildPhase1[sortedIndex] = {
 							cache: filterDuplicateKeys(preCompleted, phase1Pairs),
 							excludedSourceFields: excludedSourceFields.size > 0 ? excludedSourceFields : void 0
-						});
-					} else perChildPhase1.push({
+						};
+					} else perChildPhase1[sortedIndex] = {
 						cache: void 0,
 						excludedSourceFields: void 0
-					});
+					};
+				}
+				const mergeNodes = buildMergeSchedulingNodes(state, exec?.path);
+				await collectExplicitSourceValuesAsync(mergeNodes, runtime);
+				const effectfulPreCompleted = /* @__PURE__ */ new Map();
+				const effectfulFailure = await scheduleEffectfulSourceCompletions(mergeNodes, state, runtime, childExec, effectfulPreCompleted);
+				if (effectfulFailure != null) return effectfulFailure;
+				if (effectfulPreCompleted.size > 0) for (let i = 0; i < parsers.length; i++) {
+					const parser = parsers[i];
+					if (!(fieldParsersKey in parser)) continue;
+					const pairs = parser[fieldParsersKey];
+					let cache;
+					for (const [field] of pairs) {
+						const completed = effectfulPreCompleted.get(field);
+						if (completed === void 0) continue;
+						cache ??= new Map(perChildPhase1[i].cache);
+						cache.set(field, completed);
+					}
+					if (cache != null) perChildPhase1[i] = {
+						...perChildPhase1[i],
+						cache
+					};
 				}
-				await collectExplicitSourceValuesAsync(buildRuntimeNodesFromPairs(unambiguousFieldParsers, state, exec?.path), runtime);
 				const resolvedState = await resolveStateWithRuntimeAsync(state, runtime);
 				const object$1 = {};
 				const deferredKeys = /* @__PURE__ */ new Map();
@@ -4525,25 +4765,46 @@ function merge(...args) {
 				const runtime = exec?.dependencyRuntime ?? createDependencyRuntimeContext(exec?.dependencyRegistry);
 				const childExec = withDependencyRuntimeExec(mergeParser.usage, exec, runtime);
 				const duplicateFieldNames = collectDuplicateFieldNames(mergedFieldParsers);
-				const unambiguousFieldParsers = filterDuplicateFieldParsers(mergedFieldParsers);
-				const perChildPhase1 = [];
-				for (let i = 0; i < parsers.length; i++) {
-					const parser = parsers[i];
+				const perChildPhase1 = new Array(parsers.length);
+				for (let originalIndex = 0; originalIndex < rawParsers.length; originalIndex++) {
+					const parser = rawParsers[originalIndex];
+					const sortedIndex = sortedIndexByOriginal[originalIndex];
 					if (fieldParsersKey in parser) {
 						const pairs = parser[fieldParsersKey];
 						const excludedSourceFields = new Set(pairs.map(([field]) => field).filter((field) => duplicateFieldNames.has(field)));
 						const phase1Pairs = filterExcludedFieldParsers(pairs, excludedSourceFields);
-						const preCompleted = await preCompleteAndRegisterDependenciesAsync(state, phase1Pairs, runtime.registry, withChildExecPath(childExec, i));
-						perChildPhase1.push({
+						const preCompleted = await preCompleteAndRegisterDependenciesAsync(state, phase1Pairs, runtime.registry, withChildExecPath(childExec, sortedIndex));
+						if (firstPreCompletedFailure(preCompleted) != null) return null;
+						perChildPhase1[sortedIndex] = {
 							cache: filterDuplicateKeys(preCompleted, phase1Pairs),
 							excludedSourceFields: excludedSourceFields.size > 0 ? excludedSourceFields : void 0
-						});
-					} else perChildPhase1.push({
+						};
+					} else perChildPhase1[sortedIndex] = {
 						cache: void 0,
 						excludedSourceFields: void 0
-					});
+					};
+				}
+				const mergeNodes = buildMergeSchedulingNodes(state, exec?.path);
+				await collectExplicitSourceValuesAsync(mergeNodes, runtime);
+				const effectfulPreCompleted = /* @__PURE__ */ new Map();
+				const effectfulFailure = await scheduleEffectfulSourceCompletions(mergeNodes, state, runtime, childExec, effectfulPreCompleted);
+				if (effectfulFailure != null) return null;
+				if (effectfulPreCompleted.size > 0) for (let i = 0; i < parsers.length; i++) {
+					const parser = parsers[i];
+					if (!(fieldParsersKey in parser)) continue;
+					const pairs = parser[fieldParsersKey];
+					let cache;
+					for (const [field] of pairs) {
+						const completed = effectfulPreCompleted.get(field);
+						if (completed === void 0) continue;
+						cache ??= new Map(perChildPhase1[i].cache);
+						cache.set(field, completed);
+					}
+					if (cache != null) perChildPhase1[i] = {
+						...perChildPhase1[i],
+						cache
+					};
 				}
-				await collectExplicitSourceValuesAsync(buildRuntimeNodesFromPairs(unambiguousFieldParsers, state, exec?.path), runtime);
 				const resolvedState = await resolveStateWithRuntimeAsync(state, runtime);
 				const object$1 = {};
 				const deferredKeys = /* @__PURE__ */ new Map();
@@ -5179,7 +5440,11 @@ function concat(...parsers) {
 		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 allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
+		const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
+		await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
+		const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
+		if (effectfulFailure != null) return effectfulFailure;
 		const phase3Exec = {
 			...childExec,
 			preCompletedByParser: void 0
@@ -5227,6 +5492,7 @@ function concat(...parsers) {
 		usage: parsers.flatMap((p) => p.usage),
 		leadingNames: sharedBufferLeadingNames(parsers),
 		acceptingAnyToken: parsers.some((p) => p.acceptingAnyToken),
+		[fieldParsersKey]: parsers.map((parser, index) => [String(index), parser]),
 		initialState,
 		canSkip(state, exec) {
 			const stateArray = state;
@@ -5282,7 +5548,11 @@ function concat(...parsers) {
 				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 allRuntimeNodes = buildRuntimeNodesFromArray(parsers, stateArray, exec?.path);
+				const runtimeNodes = filterPreCompletedRuntimeNodes(allRuntimeNodes, new Set(preCompleted.keys()));
+				await collectExplicitSourceValuesAsync(runtimeNodes, runtime);
+				const effectfulFailure = await scheduleEffectfulSourceCompletions(filterPreCompletedRuntimeNodes(allRuntimeNodes, settledPreCompletedKeys(preCompleted)), stateArray, runtime, childExec, preCompleted);
+				if (effectfulFailure != null) return null;
 				const phase3Exec = {
 					...childExec,
 					preCompletedByParser: void 0
@@ -5379,6 +5649,7 @@ function group(label, parser, options = {}) {
 		acceptingAnyToken: parser.acceptingAnyToken,
 		initialState: parser.initialState,
 		...fieldParsersKey in parser ? { [fieldParsersKey]: parser[fieldParsersKey] } : {},
+		...effectfulSchedulingNodesKey in parser ? { [effectfulSchedulingNodesKey]: parser[effectfulSchedulingNodesKey] } : {},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
 		...typeof parser.canSkip === "function" ? { canSkip: parser.canSkip.bind(parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
@@ -5440,6 +5711,11 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (parser.dependencyMetadata != null) Object.defineProperty(groupParser, "dependencyMetadata", {
+		value: parser.dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	if ("placeholder" in parser) Object.defineProperty(groupParser, "placeholder", {
 		get() {
 			return parser.placeholder;
@@ -6059,6 +6335,25 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			} : {}
 		};
 	};
+	const buildConditionalSchedulingNodes = (state, parentPath) => {
+		if (state == null || typeof state !== "object") return [];
+		const conditionalState = state;
+		const nodes = [{
+			path: [...parentPath ?? [], "_discriminator"],
+			parser: discriminator,
+			state: getWrappedChildState(conditionalState, conditionalState.discriminatorState, discriminator)
+		}];
+		const selected = conditionalState.selectedBranch;
+		if (selected !== void 0 && conditionalState.speculative !== true) {
+			const branchParser = selected.kind === "default" ? defaultBranch : branches[selected.key];
+			if (branchParser != null) nodes.push({
+				path: [...parentPath ?? [], "_branch"],
+				parser: branchParser,
+				state: getWrappedChildState(conditionalState, conditionalState.branchState, branchParser)
+			});
+		}
+		return nodes;
+	};
 	const completeAsync = async (state, exec) => {
 		let wasSpeculative = false;
 		if (state.speculative && state.selectedBranch?.kind === "branch") if (exec?.phase !== "parse" && exec?.phase !== "suggest") {
@@ -6156,6 +6451,12 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			dependencyRuntime: runtime,
 			dependencyRegistry: runtime.registry
 		};
+		{
+			const allSchedulingNodes = buildConditionalSchedulingNodes(state, exec?.path);
+			const schedulingNodes = wasSpeculative ? allSchedulingNodes.filter((node) => node.path.at(-1) === "_discriminator") : allSchedulingNodes;
+			const schedulingFailure = await scheduleEffectfulSourceCompletions(schedulingNodes, combinedState, runtime, completionExec, /* @__PURE__ */ new Map());
+			if (schedulingFailure != null) return schedulingFailure;
+		}
 		const needsDiscriminatorCompletion = state.selectedBranch.kind !== "default" && !(state.discriminatorValue != null && state.discriminatorValue === state.selectedBranch.key);
 		let discriminatorCompletionExec = completionExec;
 		if (wasSpeculative && needsDiscriminatorCompletion) {
@@ -6426,6 +6727,11 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		}
 	};
 	defineInheritedAnnotationParser(conditionalParser);
+	Object.defineProperty(conditionalParser, effectfulSchedulingNodesKey, {
+		value: buildConditionalSchedulingNodes,
+		configurable: true,
+		enumerable: false
+	});
 	return fluent(conditionalParser);
 }
 

package/dist/dependency-metadata.cjs

@@ -74,6 +74,16 @@ function unwrapArrayThenExtract(innerExtract) {
 	};
 }
 /**
+* Wraps an inner `completeSource` to unwrap `[innerState]` first, mirroring
+* `unwrapArrayThenExtract` for the effectful completion operation.
+*/
+function unwrapArrayThenComplete(innerComplete) {
+	return (state, exec) => {
+		if (Array.isArray(state) && state.length === 1) return innerComplete(state[0], exec);
+		return innerComplete(state, exec);
+	};
+}
+/**
 * Composes dependency metadata through a modifier wrapper.
 *
 * - `"optional"`: composes `extractSourceValue` with array unwrapping.
@@ -99,7 +109,8 @@ function composeDependencyMetadata(inner, wrapperKind, options) {
 				...inner,
 				source: {
 					...inner.source,
-					extractSourceValue: unwrapArrayThenExtract(inner.source.extractSourceValue)
+					extractSourceValue: unwrapArrayThenExtract(inner.source.extractSourceValue),
+					...inner.source.completeSource != null && { completeSource: unwrapArrayThenComplete(inner.source.completeSource) }
 				}
 			};
 			return inner;
@@ -112,6 +123,7 @@ function composeDependencyMetadata(inner, wrapperKind, options) {
 				source: {
 					...inner.source,
 					...wrappedExtract != null && { extractSourceValue: wrappedExtract },
+					...inner.source.completeSource != null && { completeSource: unwrapArrayThenComplete(inner.source.completeSource) },
 					...preservesSourceValue && options?.defaultValue != null && { getMissingSourceValue: options.defaultValue }
 				}
 			};