@optique/core 1.3.0-dev.2425 → 1.3.0-dev.2428

package/dist/constructs.cjs

@@ -185,6 +185,68 @@ function collectStaticSourceIds(parser, out, seen) {
 	const scope = parser[require_dependency_runtime.staticSourceScopeKey];
 	if (scope != null) for (const child of scope) collectStaticSourceIds(child, out, seen);
 }
+/**
+* Statically collects the completion dependencies reachable through a
+* parser's composed metadata and flattened field pairs, mirroring
+* {@link collectStaticSourceIds}.  Every completion consumer joins the
+* ordering union, while demand edges record only parsers that are both
+* a source and a completion consumer—the flat demand rule never
+* demands a consumer-only completion's prerequisites, because such a
+* completion defers itself out of the seed pass.
+*/
+function collectStaticCompletionDependencies(parser, orderingDependencyIds, demandEdges, seen) {
+	if (seen.has(parser)) return;
+	seen.add(parser);
+	const metadata = parser.dependencyMetadata;
+	const completion = metadata?.completion;
+	if (completion != null) {
+		for (const id of completion.dependencyIds) orderingDependencyIds.add(id);
+		const consumerSourceId = metadata?.source?.sourceId;
+		if (consumerSourceId != null) demandEdges.push({
+			consumerSourceId,
+			dependencyIds: completion.dependencyIds
+		});
+	}
+	const pairs = parser[fieldParsersKey];
+	if (pairs != null) for (const [, child] of pairs) collectStaticCompletionDependencies(child, orderingDependencyIds, demandEdges, seen);
+	const scope = parser[require_dependency_runtime.staticSourceScopeKey];
+	if (scope != null) for (const child of scope) collectStaticCompletionDependencies(child, orderingDependencyIds, demandEdges, seen);
+}
+/**
+* Recomputes a speculative barrier's completion dependencies from the
+* guessed branch's expanded runtime nodes, so an occurrence already
+* satisfied by the command line or a binding contributes neither
+* ordering edges nor demand, mirroring the flat inactive-completion
+* rule.  Nested barriers contribute their own aggregates, which remain
+* static estimates.
+*/
+function computeBarrierDependenciesFromNodes(nodes, provides) {
+	const ordering = /* @__PURE__ */ new Set();
+	const demandEdges = [];
+	for (const node of nodes) {
+		const metadata = node.parser.dependencyMetadata;
+		const completion = metadata?.completion;
+		if (completion != null && !require_dependency_runtime.hasInactiveCompletion(node)) {
+			for (const id of completion.dependencyIds) ordering.add(id);
+			const consumerSourceId = metadata?.source?.sourceId;
+			if (consumerSourceId != null) demandEdges.push({
+				consumerSourceId,
+				dependencyIds: completion.dependencyIds
+			});
+		}
+		const nested = node.barrierCompletionDependencies;
+		if (nested != null) {
+			for (const id of nested.orderingDependencyIds) ordering.add(id);
+			demandEdges.push(...nested.demandEdges);
+		}
+	}
+	const orderingDependencyIds = [...ordering].filter((id) => !provides.has(id));
+	if (orderingDependencyIds.length < 1 && demandEdges.length < 1) return void 0;
+	return {
+		orderingDependencyIds,
+		demandEdges
+	};
+}
 function isDeferredCompletionResult(result) {
 	return typeof result === "object" && result !== null && "success" in result && result.success === true && "deferred" in result && result.deferred === true;
 }
@@ -6443,12 +6505,51 @@ function conditional(discriminator, branches, defaultBranch, options) {
 	};
 	const preparedKeyPrefix = `c${++conditionalInstanceCounter}|`;
 	const preparedKeyFor = (parentPath) => preparedKeyPrefix + require_dependency_runtime.serializeSchedulingPath(parentPath ?? []);
-	const branchProvidedSourceIds = (() => {
-		const out = /* @__PURE__ */ new Set();
-		const seen = /* @__PURE__ */ new Set();
-		for (const key of Object.keys(branches)) collectStaticSourceIds(branches[key], out, seen);
-		if (defaultBranch != null) collectStaticSourceIds(defaultBranch, out, seen);
-		return out;
+	const { branchProvidedSourceIds, mergedBarrierDependencies, barrierDependenciesByKey } = (() => {
+		const provided = /* @__PURE__ */ new Set();
+		const byParser = /* @__PURE__ */ new Map();
+		const computeBranch = (branch) => {
+			const memoized = byParser.get(branch);
+			if (memoized != null) return memoized;
+			const provides = /* @__PURE__ */ new Set();
+			collectStaticSourceIds(branch, provides, /* @__PURE__ */ new Set());
+			for (const id of provides) provided.add(id);
+			const ordering = /* @__PURE__ */ new Set();
+			const demandEdges = [];
+			collectStaticCompletionDependencies(branch, ordering, demandEdges, /* @__PURE__ */ new Set());
+			const orderingDependencyIds = [...ordering].filter((id) => !provides.has(id));
+			const estimate = {
+				provides,
+				...orderingDependencyIds.length < 1 && demandEdges.length < 1 ? {} : { dependencies: {
+					orderingDependencyIds,
+					demandEdges
+				} }
+			};
+			byParser.set(branch, estimate);
+			return estimate;
+		};
+		const byKey = /* @__PURE__ */ new Map();
+		for (const key of Object.keys(branches)) {
+			const estimate = computeBranch(branches[key]);
+			if (estimate.dependencies != null) byKey.set(key, estimate);
+		}
+		if (defaultBranch != null) computeBranch(defaultBranch);
+		const orderingUnion = /* @__PURE__ */ new Set();
+		const mergedEdges = [];
+		for (const estimate of new Set(byParser.values())) {
+			if (estimate.dependencies == null) continue;
+			for (const id of estimate.dependencies.orderingDependencyIds) orderingUnion.add(id);
+			mergedEdges.push(...estimate.dependencies.demandEdges);
+		}
+		const merged = orderingUnion.size < 1 && mergedEdges.length < 1 ? void 0 : {
+			orderingDependencyIds: [...orderingUnion],
+			demandEdges: mergedEdges
+		};
+		return {
+			branchProvidedSourceIds: provided,
+			mergedBarrierDependencies: merged,
+			barrierDependenciesByKey: byKey
+		};
 	})();
 	const buildConditionalSchedulingNodes = (state, parentPath) => {
 		if (state == null || typeof state !== "object") return [];
@@ -6494,12 +6595,24 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			if (selected?.kind !== "branch" || innerCompleteSource == null) return nodes;
 			teeDiscriminatorNode();
 			const speculativeKey = selected.key;
+			const speculativeBarrierDependencies = (() => {
+				const estimate = barrierDependenciesByKey.get(speculativeKey);
+				if (estimate?.dependencies == null) return void 0;
+				const branchParser = branches[speculativeKey];
+				if (branchParser == null) return estimate.dependencies;
+				return computeBarrierDependenciesFromNodes(expandEffectfulRuntimeNodes([{
+					path: [...parentPath ?? [], "_branch"],
+					parser: branchParser,
+					state: require_annotation_state.getWrappedChildState(conditionalState, conditionalState.branchState, branchParser)
+				}]), estimate.provides);
+			})();
 			nodes.push({
 				path: [...parentPath ?? [], "_branch"],
 				parser: {},
 				state: conditionalState,
 				...discriminatorSource != null ? { requiresSourceId: discriminatorSource.sourceId } : {},
 				providesSourceIds: branchProvidedSourceIds,
+				...speculativeBarrierDependencies != null ? { barrierCompletionDependencies: speculativeBarrierDependencies } : {},
 				prepare: async (ctx) => {
 					const session = ctx.exec?.effectfulCompletionSession;
 					if (session == null) return void 0;
@@ -6526,6 +6639,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			state: conditionalState,
 			...discriminatorSource != null ? { requiresSourceId: discriminatorSource.sourceId } : {},
 			providesSourceIds: branchProvidedSourceIds,
+			...mergedBarrierDependencies != null ? { barrierCompletionDependencies: mergedBarrierDependencies } : {},
 			prepare: async (ctx) => {
 				const session = ctx.exec?.effectfulCompletionSession;
 				if (session == null) return void 0;

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, completeEffectfulSourcesAsync, createDependencyRuntimeContext, effectfulSchedulingNodesKey, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
+import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyRuntimeContext, effectfulSchedulingNodesKey, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, hasInactiveCompletion, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey } 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";
@@ -185,6 +185,68 @@ function collectStaticSourceIds(parser, out, seen) {
 	const scope = parser[staticSourceScopeKey];
 	if (scope != null) for (const child of scope) collectStaticSourceIds(child, out, seen);
 }
+/**
+* Statically collects the completion dependencies reachable through a
+* parser's composed metadata and flattened field pairs, mirroring
+* {@link collectStaticSourceIds}.  Every completion consumer joins the
+* ordering union, while demand edges record only parsers that are both
+* a source and a completion consumer—the flat demand rule never
+* demands a consumer-only completion's prerequisites, because such a
+* completion defers itself out of the seed pass.
+*/
+function collectStaticCompletionDependencies(parser, orderingDependencyIds, demandEdges, seen) {
+	if (seen.has(parser)) return;
+	seen.add(parser);
+	const metadata = parser.dependencyMetadata;
+	const completion = metadata?.completion;
+	if (completion != null) {
+		for (const id of completion.dependencyIds) orderingDependencyIds.add(id);
+		const consumerSourceId = metadata?.source?.sourceId;
+		if (consumerSourceId != null) demandEdges.push({
+			consumerSourceId,
+			dependencyIds: completion.dependencyIds
+		});
+	}
+	const pairs = parser[fieldParsersKey];
+	if (pairs != null) for (const [, child] of pairs) collectStaticCompletionDependencies(child, orderingDependencyIds, demandEdges, seen);
+	const scope = parser[staticSourceScopeKey];
+	if (scope != null) for (const child of scope) collectStaticCompletionDependencies(child, orderingDependencyIds, demandEdges, seen);
+}
+/**
+* Recomputes a speculative barrier's completion dependencies from the
+* guessed branch's expanded runtime nodes, so an occurrence already
+* satisfied by the command line or a binding contributes neither
+* ordering edges nor demand, mirroring the flat inactive-completion
+* rule.  Nested barriers contribute their own aggregates, which remain
+* static estimates.
+*/
+function computeBarrierDependenciesFromNodes(nodes, provides) {
+	const ordering = /* @__PURE__ */ new Set();
+	const demandEdges = [];
+	for (const node of nodes) {
+		const metadata = node.parser.dependencyMetadata;
+		const completion = metadata?.completion;
+		if (completion != null && !hasInactiveCompletion(node)) {
+			for (const id of completion.dependencyIds) ordering.add(id);
+			const consumerSourceId = metadata?.source?.sourceId;
+			if (consumerSourceId != null) demandEdges.push({
+				consumerSourceId,
+				dependencyIds: completion.dependencyIds
+			});
+		}
+		const nested = node.barrierCompletionDependencies;
+		if (nested != null) {
+			for (const id of nested.orderingDependencyIds) ordering.add(id);
+			demandEdges.push(...nested.demandEdges);
+		}
+	}
+	const orderingDependencyIds = [...ordering].filter((id) => !provides.has(id));
+	if (orderingDependencyIds.length < 1 && demandEdges.length < 1) return void 0;
+	return {
+		orderingDependencyIds,
+		demandEdges
+	};
+}
 function isDeferredCompletionResult(result) {
 	return typeof result === "object" && result !== null && "success" in result && result.success === true && "deferred" in result && result.deferred === true;
 }
@@ -6443,12 +6505,51 @@ function conditional(discriminator, branches, defaultBranch, options) {
 	};
 	const preparedKeyPrefix = `c${++conditionalInstanceCounter}|`;
 	const preparedKeyFor = (parentPath) => preparedKeyPrefix + serializeSchedulingPath(parentPath ?? []);
-	const branchProvidedSourceIds = (() => {
-		const out = /* @__PURE__ */ new Set();
-		const seen = /* @__PURE__ */ new Set();
-		for (const key of Object.keys(branches)) collectStaticSourceIds(branches[key], out, seen);
-		if (defaultBranch != null) collectStaticSourceIds(defaultBranch, out, seen);
-		return out;
+	const { branchProvidedSourceIds, mergedBarrierDependencies, barrierDependenciesByKey } = (() => {
+		const provided = /* @__PURE__ */ new Set();
+		const byParser = /* @__PURE__ */ new Map();
+		const computeBranch = (branch) => {
+			const memoized = byParser.get(branch);
+			if (memoized != null) return memoized;
+			const provides = /* @__PURE__ */ new Set();
+			collectStaticSourceIds(branch, provides, /* @__PURE__ */ new Set());
+			for (const id of provides) provided.add(id);
+			const ordering = /* @__PURE__ */ new Set();
+			const demandEdges = [];
+			collectStaticCompletionDependencies(branch, ordering, demandEdges, /* @__PURE__ */ new Set());
+			const orderingDependencyIds = [...ordering].filter((id) => !provides.has(id));
+			const estimate = {
+				provides,
+				...orderingDependencyIds.length < 1 && demandEdges.length < 1 ? {} : { dependencies: {
+					orderingDependencyIds,
+					demandEdges
+				} }
+			};
+			byParser.set(branch, estimate);
+			return estimate;
+		};
+		const byKey = /* @__PURE__ */ new Map();
+		for (const key of Object.keys(branches)) {
+			const estimate = computeBranch(branches[key]);
+			if (estimate.dependencies != null) byKey.set(key, estimate);
+		}
+		if (defaultBranch != null) computeBranch(defaultBranch);
+		const orderingUnion = /* @__PURE__ */ new Set();
+		const mergedEdges = [];
+		for (const estimate of new Set(byParser.values())) {
+			if (estimate.dependencies == null) continue;
+			for (const id of estimate.dependencies.orderingDependencyIds) orderingUnion.add(id);
+			mergedEdges.push(...estimate.dependencies.demandEdges);
+		}
+		const merged = orderingUnion.size < 1 && mergedEdges.length < 1 ? void 0 : {
+			orderingDependencyIds: [...orderingUnion],
+			demandEdges: mergedEdges
+		};
+		return {
+			branchProvidedSourceIds: provided,
+			mergedBarrierDependencies: merged,
+			barrierDependenciesByKey: byKey
+		};
 	})();
 	const buildConditionalSchedulingNodes = (state, parentPath) => {
 		if (state == null || typeof state !== "object") return [];
@@ -6494,12 +6595,24 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			if (selected?.kind !== "branch" || innerCompleteSource == null) return nodes;
 			teeDiscriminatorNode();
 			const speculativeKey = selected.key;
+			const speculativeBarrierDependencies = (() => {
+				const estimate = barrierDependenciesByKey.get(speculativeKey);
+				if (estimate?.dependencies == null) return void 0;
+				const branchParser = branches[speculativeKey];
+				if (branchParser == null) return estimate.dependencies;
+				return computeBarrierDependenciesFromNodes(expandEffectfulRuntimeNodes([{
+					path: [...parentPath ?? [], "_branch"],
+					parser: branchParser,
+					state: getWrappedChildState(conditionalState, conditionalState.branchState, branchParser)
+				}]), estimate.provides);
+			})();
 			nodes.push({
 				path: [...parentPath ?? [], "_branch"],
 				parser: {},
 				state: conditionalState,
 				...discriminatorSource != null ? { requiresSourceId: discriminatorSource.sourceId } : {},
 				providesSourceIds: branchProvidedSourceIds,
+				...speculativeBarrierDependencies != null ? { barrierCompletionDependencies: speculativeBarrierDependencies } : {},
 				prepare: async (ctx) => {
 					const session = ctx.exec?.effectfulCompletionSession;
 					if (session == null) return void 0;
@@ -6526,6 +6639,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			state: conditionalState,
 			...discriminatorSource != null ? { requiresSourceId: discriminatorSource.sourceId } : {},
 			providesSourceIds: branchProvidedSourceIds,
+			...mergedBarrierDependencies != null ? { barrierCompletionDependencies: mergedBarrierDependencies } : {},
 			prepare: async (ctx) => {
 				const session = ctx.exec?.effectfulCompletionSession;
 				if (session == null) return void 0;

package/dist/dependency-runtime.cjs

@@ -393,7 +393,9 @@ async function collectExplicitSourceValuesAsync(nodes, runtime) {
 *
 * Missing providers create no edge because the consumer may use its declared
 * default.  Scheduling barriers act as providers for the source IDs their
-* selected subtree may expose and depend on their discriminator source.
+* selected subtree may expose and depend on their discriminator source as
+* well as on outer providers of the completion dependencies their
+* selectable subtrees aggregate.
 *
 * @param nodes Runtime nodes in declaration order.
 * @returns The same nodes in stable dependency order.
@@ -437,6 +439,10 @@ function orderDependencyNodes(nodes) {
 		if (node.requiresSourceId != null) {
 			for (const provider of providers.get(node.requiresSourceId) ?? []) if (provider !== node) addEdge(provider, node);
 		}
+		const barrierDeps = node.barrierCompletionDependencies;
+		if (barrierDeps != null) {
+			for (const dependencySourceId of barrierDeps.orderingDependencyIds) for (const provider of providers.get(dependencySourceId) ?? []) if (provider !== node) addEdge(provider, node);
+		}
 	}
 	const declarationOrder = new Map(nodes.map((node, index) => [node, index]));
 	const ready = nodes.filter((node) => indegree.get(node) === 0);
@@ -553,6 +559,9 @@ const inactiveCompletionCache = /* @__PURE__ */ new WeakMap();
 * the completion active (the effectful completion is its recovery
 * path), and an asynchronous extraction is conservatively treated as
 * active because it cannot be decided synchronously.
+*
+* @internal
+* @since 1.3.0
 */
 function hasInactiveCompletion(node) {
 	const cached = inactiveCompletionCache.get(node);
@@ -1062,6 +1071,14 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 					session.demanded.add(dependencySourceId);
 					demandAdded = true;
 				}
+				if (node.barrierCompletionDependencies != null) for (const edge of node.barrierCompletionDependencies.demandEdges) {
+					if (!session.demanded.has(edge.consumerSourceId)) continue;
+					for (const dependencySourceId of edge.dependencyIds) {
+						if (session.demanded.has(dependencySourceId)) continue;
+						session.demanded.add(dependencySourceId);
+						demandAdded = true;
+					}
+				}
 				if (node.requiresSourceId == null || node.providesSourceIds == null) continue;
 				if (session.demanded.has(node.requiresSourceId)) continue;
 				for (const provided of node.providesSourceIds) if (session.demanded.has(provided)) {
@@ -1465,6 +1482,7 @@ exports.effectfulSchedulingNodesKey = effectfulSchedulingNodesKey;
 exports.extractRawInputFromState = extractRawInputFromState;
 exports.fillMissingSourceDefaults = fillMissingSourceDefaults;
 exports.fillMissingSourceDefaultsAsync = fillMissingSourceDefaultsAsync;
+exports.hasInactiveCompletion = hasInactiveCompletion;
 exports.includeSourceFailureChain = includeSourceFailureChain;
 exports.orderDependencyNodes = orderDependencyNodes;
 exports.recordDerivedRawInput = recordDerivedRawInput;

package/dist/dependency-runtime.d.cts

@@ -166,6 +166,63 @@ interface RuntimeNode {
    * @since 1.3.0
    */
   readonly requiresSourceId?: symbol;
+  /**
+   * Completion dependencies aggregated from the selectable subtrees
+   * guarded by this barrier, so the outer pass can order the barrier
+   * after the providers those subtrees' effectful completions read and
+   * propagate demand to them.
+   *
+   * The sets are static estimates: they describe every selectable
+   * branch, not the one preparation will eventually choose.  They are
+   * advisory for ordering and demand only and never join failure
+   * lineage—a failed prerequisite used only by an unselected branch
+   * must not fail the barrier.
+   *
+   * @since 1.3.0
+   */
+  readonly barrierCompletionDependencies?: BarrierCompletionDependencies;
+}
+/**
+ * An exact demand edge inside a scheduling barrier's subtree: when the
+ * consumer's own source is demanded, the completion dependencies its
+ * effectful completion reads become demanded as well, mirroring the
+ * flat demand rule for parsers whose completion consumes dependency
+ * values.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface BarrierCompletionDemandEdge {
+  /** The branch consumer's own source ID (the demand trigger). */
+  readonly consumerSourceId: symbol;
+  /** The completion dependency IDs that consumer reads. */
+  readonly dependencyIds: readonly symbol[];
+}
+/**
+ * Completion dependencies a scheduling barrier aggregates from its
+ * selectable subtrees.  See
+ * {@link RuntimeNode.barrierCompletionDependencies}.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface BarrierCompletionDependencies {
+  /**
+   * Union of the branches' completion dependency IDs, with each
+   * branch's own statically providable IDs subtracted.  Used only to
+   * order the barrier after outer providers; a missing provider
+   * creates no edge.
+   */
+  readonly orderingDependencyIds: readonly symbol[];
+  /**
+   * Exact demand edges collected from branch parsers that are both a
+   * source and a completion consumer.  Unlike
+   * {@link BarrierCompletionDependencies.orderingDependencyIds}, these
+   * keep branch-internal prerequisites: a demanded consumer must also
+   * demand an internal source prompt so it does not defer out of the
+   * seed pass.
+   */
+  readonly demandEdges: readonly BarrierCompletionDemandEdge[];
 }
 /**
  * Options for resolving matched derived source values.
@@ -296,7 +353,9 @@ declare function collectExplicitSourceValuesAsync(nodes: readonly RuntimeNode[],
  *
  * Missing providers create no edge because the consumer may use its declared
  * default.  Scheduling barriers act as providers for the source IDs their
- * selected subtree may expose and depend on their discriminator source.
+ * selected subtree may expose and depend on their discriminator source as
+ * well as on outer providers of the completion dependencies their
+ * selectable subtrees aggregate.
  *
  * @param nodes Runtime nodes in declaration order.
  * @returns The same nodes in stable dependency order.
@@ -309,6 +368,20 @@ declare function orderDependencyNodes(nodes: readonly RuntimeNode[]): readonly R
 declare function resolveDerivedSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): void;
 /** Async version of {@link resolveDerivedSourceValues}. */
 declare function resolveDerivedSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): Promise<void>;
+/**
+ * Whether a node's completion dependencies are inactive because this
+ * occurrence's own state already extracts a value: a field satisfied by
+ * the command line or a binding never runs its configuration resolver,
+ * so its completion dependencies must not order scheduling, demand
+ * upstream sources, or join failure lineage.  A failed extraction keeps
+ * the completion active (the effectful completion is its recovery
+ * path), and an asynchronous extraction is conservatively treated as
+ * active because it cannot be decided synchronously.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare function hasInactiveCompletion(node: RuntimeNode): boolean;
 /**
  * Appends the recorded dependency chain to a source failure.
  *
@@ -694,4 +767,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.d.ts

@@ -166,6 +166,63 @@ interface RuntimeNode {
    * @since 1.3.0
    */
   readonly requiresSourceId?: symbol;
+  /**
+   * Completion dependencies aggregated from the selectable subtrees
+   * guarded by this barrier, so the outer pass can order the barrier
+   * after the providers those subtrees' effectful completions read and
+   * propagate demand to them.
+   *
+   * The sets are static estimates: they describe every selectable
+   * branch, not the one preparation will eventually choose.  They are
+   * advisory for ordering and demand only and never join failure
+   * lineage—a failed prerequisite used only by an unselected branch
+   * must not fail the barrier.
+   *
+   * @since 1.3.0
+   */
+  readonly barrierCompletionDependencies?: BarrierCompletionDependencies;
+}
+/**
+ * An exact demand edge inside a scheduling barrier's subtree: when the
+ * consumer's own source is demanded, the completion dependencies its
+ * effectful completion reads become demanded as well, mirroring the
+ * flat demand rule for parsers whose completion consumes dependency
+ * values.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface BarrierCompletionDemandEdge {
+  /** The branch consumer's own source ID (the demand trigger). */
+  readonly consumerSourceId: symbol;
+  /** The completion dependency IDs that consumer reads. */
+  readonly dependencyIds: readonly symbol[];
+}
+/**
+ * Completion dependencies a scheduling barrier aggregates from its
+ * selectable subtrees.  See
+ * {@link RuntimeNode.barrierCompletionDependencies}.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface BarrierCompletionDependencies {
+  /**
+   * Union of the branches' completion dependency IDs, with each
+   * branch's own statically providable IDs subtracted.  Used only to
+   * order the barrier after outer providers; a missing provider
+   * creates no edge.
+   */
+  readonly orderingDependencyIds: readonly symbol[];
+  /**
+   * Exact demand edges collected from branch parsers that are both a
+   * source and a completion consumer.  Unlike
+   * {@link BarrierCompletionDependencies.orderingDependencyIds}, these
+   * keep branch-internal prerequisites: a demanded consumer must also
+   * demand an internal source prompt so it does not defer out of the
+   * seed pass.
+   */
+  readonly demandEdges: readonly BarrierCompletionDemandEdge[];
 }
 /**
  * Options for resolving matched derived source values.
@@ -296,7 +353,9 @@ declare function collectExplicitSourceValuesAsync(nodes: readonly RuntimeNode[],
  *
  * Missing providers create no edge because the consumer may use its declared
  * default.  Scheduling barriers act as providers for the source IDs their
- * selected subtree may expose and depend on their discriminator source.
+ * selected subtree may expose and depend on their discriminator source as
+ * well as on outer providers of the completion dependencies their
+ * selectable subtrees aggregate.
  *
  * @param nodes Runtime nodes in declaration order.
  * @returns The same nodes in stable dependency order.
@@ -309,6 +368,20 @@ declare function orderDependencyNodes(nodes: readonly RuntimeNode[]): readonly R
 declare function resolveDerivedSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): void;
 /** Async version of {@link resolveDerivedSourceValues}. */
 declare function resolveDerivedSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): Promise<void>;
+/**
+ * Whether a node's completion dependencies are inactive because this
+ * occurrence's own state already extracts a value: a field satisfied by
+ * the command line or a binding never runs its configuration resolver,
+ * so its completion dependencies must not order scheduling, demand
+ * upstream sources, or join failure lineage.  A failed extraction keeps
+ * the completion active (the effectful completion is its recovery
+ * path), and an asynchronous extraction is conservatively treated as
+ * active because it cannot be decided synchronously.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare function hasInactiveCompletion(node: RuntimeNode): boolean;
 /**
  * Appends the recorded dependency chain to a source failure.
  *
@@ -694,4 +767,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.js

@@ -393,7 +393,9 @@ async function collectExplicitSourceValuesAsync(nodes, runtime) {
 *
 * Missing providers create no edge because the consumer may use its declared
 * default.  Scheduling barriers act as providers for the source IDs their
-* selected subtree may expose and depend on their discriminator source.
+* selected subtree may expose and depend on their discriminator source as
+* well as on outer providers of the completion dependencies their
+* selectable subtrees aggregate.
 *
 * @param nodes Runtime nodes in declaration order.
 * @returns The same nodes in stable dependency order.
@@ -437,6 +439,10 @@ function orderDependencyNodes(nodes) {
 		if (node.requiresSourceId != null) {
 			for (const provider of providers.get(node.requiresSourceId) ?? []) if (provider !== node) addEdge(provider, node);
 		}
+		const barrierDeps = node.barrierCompletionDependencies;
+		if (barrierDeps != null) {
+			for (const dependencySourceId of barrierDeps.orderingDependencyIds) for (const provider of providers.get(dependencySourceId) ?? []) if (provider !== node) addEdge(provider, node);
+		}
 	}
 	const declarationOrder = new Map(nodes.map((node, index) => [node, index]));
 	const ready = nodes.filter((node) => indegree.get(node) === 0);
@@ -553,6 +559,9 @@ const inactiveCompletionCache = /* @__PURE__ */ new WeakMap();
 * the completion active (the effectful completion is its recovery
 * path), and an asynchronous extraction is conservatively treated as
 * active because it cannot be decided synchronously.
+*
+* @internal
+* @since 1.3.0
 */
 function hasInactiveCompletion(node) {
 	const cached = inactiveCompletionCache.get(node);
@@ -1062,6 +1071,14 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 					session.demanded.add(dependencySourceId);
 					demandAdded = true;
 				}
+				if (node.barrierCompletionDependencies != null) for (const edge of node.barrierCompletionDependencies.demandEdges) {
+					if (!session.demanded.has(edge.consumerSourceId)) continue;
+					for (const dependencySourceId of edge.dependencyIds) {
+						if (session.demanded.has(dependencySourceId)) continue;
+						session.demanded.add(dependencySourceId);
+						demandAdded = true;
+					}
+				}
 				if (node.requiresSourceId == null || node.providesSourceIds == null) continue;
 				if (session.demanded.has(node.requiresSourceId)) continue;
 				for (const provided of node.providesSourceIds) if (session.demanded.has(provided)) {
@@ -1449,4 +1466,4 @@ function getDefaultDependencySnapshotInner(state, visited) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2425",
+  "version": "1.3.0-dev.2428",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -221,7 +221,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2425+957c64e5",
+    "@optique/env": "1.3.0-dev.2428+5fa651a4",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",