@optique/core 1.3.0-dev.2433 → 1.3.0-dev.2434

package/dist/constructs.cjs

@@ -89,6 +89,14 @@ function filterSchedulableRuntimeNodes(nodes, preCompleted) {
 * failure.  Returns `undefined` on success.
 */
 /**
+* Nodes a `conditional()` pre-expanded from a committed branch so a
+* `branchError` wrap can ride on the nested barrier nodes.  They are
+* expanded descendants despite appearing in a scheduling call's direct
+* node list, so {@link scheduleEffectfulSourceCompletions} must not
+* treat them as reusable or collected.
+*/
+const preExpandedBranchNodes = /* @__PURE__ */ new WeakSet();
+/**
 * Expands runtime nodes through nested constructs for effectful source
 * scheduling and demand detection.
 *
@@ -317,13 +325,18 @@ function computeBarrierDependenciesFromNodes(nodes) {
 * Computes a resolved barrier's concrete dependencies from the selected
 * branch's expanded runtime nodes: the completion dependencies its
 * active consumers read, minus the sources the branch actively
-* provides, and the active provides themselves.  Unlike the
-* synchronous estimate, promise-shaped state extractions are awaited,
-* so an asynchronously validating bound value counts as active.
+* provides, the active provides themselves, and the selection's demand
+* edges.  Unlike the synchronous estimate, promise-shaped state
+* extractions are awaited, so an asynchronously validating bound value
+* counts as active.  A nested barrier whose demand activation is
+* `"after-resolution"` contributes only its ordering aggregate: its
+* demand edges stay behind its own confirmation boundary and are
+* promoted by its own resolution within the nested scheduling pass.
 */
 async function computeActiveBarrierDependencies(nodes) {
 	const active = /* @__PURE__ */ new Set();
 	const ordering = /* @__PURE__ */ new Set();
+	const demandEdges = [];
 	for (const node of nodes) {
 		const metadata = node.parser.dependencyMetadata;
 		const source = metadata?.source;
@@ -341,14 +354,24 @@ async function computeActiveBarrierDependencies(nodes) {
 		for (const id of node.guaranteedProvidesSourceIds ?? []) active.add(id);
 		if (completion != null) {
 			const inactive = source?.extractSourceValue != null ? extracted?.success === true : require_dependency_runtime.hasInactiveCompletion(node);
-			if (!inactive) for (const id of completion.dependencyIds) ordering.add(id);
+			if (!inactive) {
+				for (const id of completion.dependencyIds) ordering.add(id);
+				if (source != null) demandEdges.push({
+					consumerSourceId: source.sourceId,
+					dependencyIds: completion.dependencyIds
+				});
+			}
 		}
 		const nested = node.barrierCompletionDependencies;
-		if (nested != null) for (const id of nested.orderingDependencyIds) ordering.add(id);
+		if (nested != null) {
+			for (const id of nested.orderingDependencyIds) ordering.add(id);
+			if (node.barrierDemandActivation !== "after-resolution" || node.barrierResolutionState === "resolved") demandEdges.push(...nested.demandEdges);
+		}
 	}
 	return {
 		orderingDependencyIds: [...ordering].filter((id) => !active.has(id)),
-		activeProvidesSourceIds: active
+		activeProvidesSourceIds: active,
+		demandEdges
 	};
 }
 function isDeferredCompletionResult(result) {
@@ -395,13 +418,15 @@ async function scheduleEffectfulSourceCompletions(nodes, state, runtime, exec, p
 		success: false,
 		error: preCompletedFailure
 	};
-	const direct = new Set(nodes);
+	const direct = new Set(nodes.filter((node) => !preExpandedBranchNodes.has(node)));
 	const collected = /* @__PURE__ */ new Set();
 	const expandedNodes = [];
 	for (const node of nodes) {
 		const optedIn = node.parser[require_dependency_runtime.sourceCollectionExpansionKey] === true;
+		const preExpanded = preExpandedBranchNodes.has(node);
 		for (const expandedNode of expandEffectfulRuntimeNodes([node])) {
 			expandedNodes.push(expandedNode);
+			if (preExpanded) continue;
 			if (optedIn || expandedNode === node) collected.add(expandedNode);
 		}
 	}
@@ -6610,6 +6635,47 @@ function conditional(discriminator, branches, defaultBranch, options) {
 	};
 	const preparedKeyPrefix = `c${++conditionalInstanceCounter}|`;
 	const preparedKeyFor = (parentPath) => preparedKeyPrefix + require_dependency_runtime.serializeSchedulingPath(parentPath ?? []);
+	const branchMismatchFailure = (resolvedValue, speculativeKey) => {
+		const resolvedKey = typeof resolvedValue === "string" ? resolvedValue : "<unknown>";
+		return {
+			success: false,
+			error: options?.errors?.branchMismatch ? options.errors.branchMismatch(resolvedKey, speculativeKey) : require_message.message`Branch mismatch: tokens for ${speculativeKey} were consumed, but the discriminator resolved to ${resolvedKey}.`
+		};
+	};
+	const wrapCachedBarrierFailure = (session, failure, branchKey) => {
+		const branchError = options?.errors?.branchError;
+		if (branchKey == null || branchError == null) return failure;
+		const wrapped = {
+			success: false,
+			error: branchError(branchKey, failure.error)
+		};
+		return require_dependency_runtime.replaceCachedBarrierFailure(session, failure, wrapped) ? wrapped : failure;
+	};
+	const wrapBranchBarrierNodes = (nodes, branchKey) => {
+		const branchError = options?.errors?.branchError;
+		if (branchKey == null || branchError == null) return nodes;
+		return nodes.map((node) => {
+			const resolveBarrier = node.resolveBarrier;
+			const prepare = node.prepare;
+			if (resolveBarrier == null && prepare == null) return node;
+			return {
+				...node,
+				...resolveBarrier == null ? {} : { resolveBarrier: async (ctx) => {
+					const result = await resolveBarrier(ctx);
+					if (result != null && "success" in result) return {
+						success: false,
+						error: branchError(branchKey, result.error)
+					};
+					return result;
+				} },
+				...prepare == null ? {} : { prepare: async (ctx) => {
+					const failure = await prepare(ctx);
+					if (failure == null) return void 0;
+					return wrapCachedBarrierFailure(ctx.exec?.effectfulCompletionSession, failure, branchKey);
+				} }
+			};
+		});
+	};
 	const { branchProvidedSourceIds, branchGuaranteedIntersection, mergedBarrierDependencies, barrierDependenciesByKey } = (() => {
 		const provided = /* @__PURE__ */ new Set();
 		const byParser = /* @__PURE__ */ new Map();
@@ -6678,11 +6744,19 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		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: require_annotation_state.getWrappedChildState(conditionalState, conditionalState.branchState, branchParser)
-			});
+			if (branchParser != null) {
+				const branchNode = {
+					path: [...parentPath ?? [], "_branch"],
+					parser: branchParser,
+					state: require_annotation_state.getWrappedChildState(conditionalState, conditionalState.branchState, branchParser)
+				};
+				const branchKey = selected.kind === "branch" ? selected.key : void 0;
+				if (branchKey != null && options?.errors?.branchError != null) for (const expanded of wrapBranchBarrierNodes(expandEffectfulRuntimeNodes([branchNode]), branchKey)) {
+					preExpandedBranchNodes.add(expanded);
+					nodes.push(expanded);
+				}
+				else nodes.push(branchNode);
+			}
 			return nodes;
 		}
 		const discriminatorSource = discriminator.dependencyMetadata?.source;
@@ -6733,14 +6807,17 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				providesSourceIds: branchProvidedSourceIds,
 				...speculativeEstimate != null && speculativeEstimate.guaranteedProvides.size > 0 ? { guaranteedProvidesSourceIds: speculativeEstimate.guaranteedProvides } : {},
 				...speculativeBarrierDependencies != null ? { barrierCompletionDependencies: speculativeBarrierDependencies } : {},
+				barrierDemandActivation: "after-resolution",
 				resolveBarrier: async (ctx) => {
 					const session = ctx.exec?.effectfulCompletionSession;
 					if (session == null) return void 0;
 					const result = cell.result ?? session.completedByPath.get(discriminatorPathKey);
 					if (result == null || isDeferredCompletionResult(result) || result.success !== true) return void 0;
-					if (String(result.value) !== speculativeKey || branches[speculativeKey] == null) return {
+					if (String(result.value) !== speculativeKey) return branchMismatchFailure(result.value, speculativeKey);
+					if (branches[speculativeKey] == null) return {
 						orderingDependencyIds: [],
-						activeProvidesSourceIds: /* @__PURE__ */ new Set()
+						activeProvidesSourceIds: /* @__PURE__ */ new Set(),
+						demandEdges: []
 					};
 					return await computeActiveBarrierDependencies(expandGuessedBranchNodes());
 				},
@@ -6751,7 +6828,9 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					if (result == null || isDeferredCompletionResult(result) || result.success !== true) return void 0;
 					if (String(result.value) !== speculativeKey) return void 0;
 					if (branches[speculativeKey] == null) return void 0;
-					return await ctx.schedule(expandGuessedBranchNodes());
+					const failure = await ctx.schedule(expandGuessedBranchNodes());
+					if (failure == null) return void 0;
+					return wrapCachedBarrierFailure(session, failure, speculativeKey);
 				}
 			});
 			return nodes;
@@ -6819,19 +6898,23 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			providesSourceIds: branchProvidedSourceIds,
 			...branchGuaranteedIntersection.size > 0 ? { guaranteedProvidesSourceIds: branchGuaranteedIntersection } : {},
 			...mergedBarrierDependencies != null ? { barrierCompletionDependencies: mergedBarrierDependencies } : {},
+			barrierDemandActivation: "after-resolution",
 			resolveBarrier: async (ctx) => {
 				const prepared = await resolvePreparedSelection(ctx);
 				if (prepared == null) return void 0;
 				if (prepared.branchParser == null) return {
 					orderingDependencyIds: [],
-					activeProvidesSourceIds: /* @__PURE__ */ new Set()
+					activeProvidesSourceIds: /* @__PURE__ */ new Set(),
+					demandEdges: []
 				};
 				return await computeActiveBarrierDependencies(expandPreparedBranchNodes(prepared));
 			},
 			prepare: async (ctx) => {
 				const prepared = await resolvePreparedSelection(ctx);
 				if (prepared?.branchParser == null) return void 0;
-				return await ctx.schedule(expandPreparedBranchNodes(prepared));
+				const failure = await ctx.schedule(expandPreparedBranchNodes(prepared));
+				if (failure == null) return void 0;
+				return wrapCachedBarrierFailure(ctx.exec?.effectfulCompletionSession, failure, prepared.branchKey);
 			}
 		});
 		return nodes;
@@ -6979,14 +7062,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			else if (wasSpeculative) return completedDiscriminator;
 			else discriminatorValue = state.selectedBranch.key;
 		}
-		if (wasSpeculative && state.selectedBranch.kind === "branch" && discriminatorValue !== state.selectedBranch.key) {
-			const speculativeKey = state.selectedBranch.key;
-			const resolvedKey = typeof discriminatorValue === "string" ? discriminatorValue : "<unknown>";
-			return {
-				success: false,
-				error: options?.errors?.branchMismatch ? options.errors.branchMismatch(resolvedKey, speculativeKey) : require_message.message`Branch mismatch: tokens for ${speculativeKey} were consumed, but the discriminator resolved to ${resolvedKey}.`
-			};
-		}
+		if (wasSpeculative && state.selectedBranch.kind === "branch" && discriminatorValue !== state.selectedBranch.key) return branchMismatchFailure(discriminatorValue, state.selectedBranch.key);
 		const resolvedBranchState = require_annotation_state.getWrappedChildState(state, await require_dependency_runtime.resolveStateWithRuntimeAsync(state.branchState, runtime), branchParser);
 		const branchResult = unwrapCompleteResult(await branchParser.complete(resolvedBranchState, require_execution_context.withChildExecPath(completionExec, "_branch")));
 		if (!branchResult.success) {

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, exclusiveSourceScopeKey, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
+import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyRuntimeContext, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, replaceCachedBarrierFailure, 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";
@@ -89,6 +89,14 @@ function filterSchedulableRuntimeNodes(nodes, preCompleted) {
 * failure.  Returns `undefined` on success.
 */
 /**
+* Nodes a `conditional()` pre-expanded from a committed branch so a
+* `branchError` wrap can ride on the nested barrier nodes.  They are
+* expanded descendants despite appearing in a scheduling call's direct
+* node list, so {@link scheduleEffectfulSourceCompletions} must not
+* treat them as reusable or collected.
+*/
+const preExpandedBranchNodes = /* @__PURE__ */ new WeakSet();
+/**
 * Expands runtime nodes through nested constructs for effectful source
 * scheduling and demand detection.
 *
@@ -317,13 +325,18 @@ function computeBarrierDependenciesFromNodes(nodes) {
 * Computes a resolved barrier's concrete dependencies from the selected
 * branch's expanded runtime nodes: the completion dependencies its
 * active consumers read, minus the sources the branch actively
-* provides, and the active provides themselves.  Unlike the
-* synchronous estimate, promise-shaped state extractions are awaited,
-* so an asynchronously validating bound value counts as active.
+* provides, the active provides themselves, and the selection's demand
+* edges.  Unlike the synchronous estimate, promise-shaped state
+* extractions are awaited, so an asynchronously validating bound value
+* counts as active.  A nested barrier whose demand activation is
+* `"after-resolution"` contributes only its ordering aggregate: its
+* demand edges stay behind its own confirmation boundary and are
+* promoted by its own resolution within the nested scheduling pass.
 */
 async function computeActiveBarrierDependencies(nodes) {
 	const active = /* @__PURE__ */ new Set();
 	const ordering = /* @__PURE__ */ new Set();
+	const demandEdges = [];
 	for (const node of nodes) {
 		const metadata = node.parser.dependencyMetadata;
 		const source = metadata?.source;
@@ -341,14 +354,24 @@ async function computeActiveBarrierDependencies(nodes) {
 		for (const id of node.guaranteedProvidesSourceIds ?? []) active.add(id);
 		if (completion != null) {
 			const inactive = source?.extractSourceValue != null ? extracted?.success === true : hasInactiveCompletion(node);
-			if (!inactive) for (const id of completion.dependencyIds) ordering.add(id);
+			if (!inactive) {
+				for (const id of completion.dependencyIds) ordering.add(id);
+				if (source != null) demandEdges.push({
+					consumerSourceId: source.sourceId,
+					dependencyIds: completion.dependencyIds
+				});
+			}
 		}
 		const nested = node.barrierCompletionDependencies;
-		if (nested != null) for (const id of nested.orderingDependencyIds) ordering.add(id);
+		if (nested != null) {
+			for (const id of nested.orderingDependencyIds) ordering.add(id);
+			if (node.barrierDemandActivation !== "after-resolution" || node.barrierResolutionState === "resolved") demandEdges.push(...nested.demandEdges);
+		}
 	}
 	return {
 		orderingDependencyIds: [...ordering].filter((id) => !active.has(id)),
-		activeProvidesSourceIds: active
+		activeProvidesSourceIds: active,
+		demandEdges
 	};
 }
 function isDeferredCompletionResult(result) {
@@ -395,13 +418,15 @@ async function scheduleEffectfulSourceCompletions(nodes, state, runtime, exec, p
 		success: false,
 		error: preCompletedFailure
 	};
-	const direct = new Set(nodes);
+	const direct = new Set(nodes.filter((node) => !preExpandedBranchNodes.has(node)));
 	const collected = /* @__PURE__ */ new Set();
 	const expandedNodes = [];
 	for (const node of nodes) {
 		const optedIn = node.parser[sourceCollectionExpansionKey] === true;
+		const preExpanded = preExpandedBranchNodes.has(node);
 		for (const expandedNode of expandEffectfulRuntimeNodes([node])) {
 			expandedNodes.push(expandedNode);
+			if (preExpanded) continue;
 			if (optedIn || expandedNode === node) collected.add(expandedNode);
 		}
 	}
@@ -6610,6 +6635,47 @@ function conditional(discriminator, branches, defaultBranch, options) {
 	};
 	const preparedKeyPrefix = `c${++conditionalInstanceCounter}|`;
 	const preparedKeyFor = (parentPath) => preparedKeyPrefix + serializeSchedulingPath(parentPath ?? []);
+	const branchMismatchFailure = (resolvedValue, speculativeKey) => {
+		const resolvedKey = typeof resolvedValue === "string" ? resolvedValue : "<unknown>";
+		return {
+			success: false,
+			error: options?.errors?.branchMismatch ? options.errors.branchMismatch(resolvedKey, speculativeKey) : message`Branch mismatch: tokens for ${speculativeKey} were consumed, but the discriminator resolved to ${resolvedKey}.`
+		};
+	};
+	const wrapCachedBarrierFailure = (session, failure, branchKey) => {
+		const branchError = options?.errors?.branchError;
+		if (branchKey == null || branchError == null) return failure;
+		const wrapped = {
+			success: false,
+			error: branchError(branchKey, failure.error)
+		};
+		return replaceCachedBarrierFailure(session, failure, wrapped) ? wrapped : failure;
+	};
+	const wrapBranchBarrierNodes = (nodes, branchKey) => {
+		const branchError = options?.errors?.branchError;
+		if (branchKey == null || branchError == null) return nodes;
+		return nodes.map((node) => {
+			const resolveBarrier = node.resolveBarrier;
+			const prepare = node.prepare;
+			if (resolveBarrier == null && prepare == null) return node;
+			return {
+				...node,
+				...resolveBarrier == null ? {} : { resolveBarrier: async (ctx) => {
+					const result = await resolveBarrier(ctx);
+					if (result != null && "success" in result) return {
+						success: false,
+						error: branchError(branchKey, result.error)
+					};
+					return result;
+				} },
+				...prepare == null ? {} : { prepare: async (ctx) => {
+					const failure = await prepare(ctx);
+					if (failure == null) return void 0;
+					return wrapCachedBarrierFailure(ctx.exec?.effectfulCompletionSession, failure, branchKey);
+				} }
+			};
+		});
+	};
 	const { branchProvidedSourceIds, branchGuaranteedIntersection, mergedBarrierDependencies, barrierDependenciesByKey } = (() => {
 		const provided = /* @__PURE__ */ new Set();
 		const byParser = /* @__PURE__ */ new Map();
@@ -6678,11 +6744,19 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		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)
-			});
+			if (branchParser != null) {
+				const branchNode = {
+					path: [...parentPath ?? [], "_branch"],
+					parser: branchParser,
+					state: getWrappedChildState(conditionalState, conditionalState.branchState, branchParser)
+				};
+				const branchKey = selected.kind === "branch" ? selected.key : void 0;
+				if (branchKey != null && options?.errors?.branchError != null) for (const expanded of wrapBranchBarrierNodes(expandEffectfulRuntimeNodes([branchNode]), branchKey)) {
+					preExpandedBranchNodes.add(expanded);
+					nodes.push(expanded);
+				}
+				else nodes.push(branchNode);
+			}
 			return nodes;
 		}
 		const discriminatorSource = discriminator.dependencyMetadata?.source;
@@ -6733,14 +6807,17 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				providesSourceIds: branchProvidedSourceIds,
 				...speculativeEstimate != null && speculativeEstimate.guaranteedProvides.size > 0 ? { guaranteedProvidesSourceIds: speculativeEstimate.guaranteedProvides } : {},
 				...speculativeBarrierDependencies != null ? { barrierCompletionDependencies: speculativeBarrierDependencies } : {},
+				barrierDemandActivation: "after-resolution",
 				resolveBarrier: async (ctx) => {
 					const session = ctx.exec?.effectfulCompletionSession;
 					if (session == null) return void 0;
 					const result = cell.result ?? session.completedByPath.get(discriminatorPathKey);
 					if (result == null || isDeferredCompletionResult(result) || result.success !== true) return void 0;
-					if (String(result.value) !== speculativeKey || branches[speculativeKey] == null) return {
+					if (String(result.value) !== speculativeKey) return branchMismatchFailure(result.value, speculativeKey);
+					if (branches[speculativeKey] == null) return {
 						orderingDependencyIds: [],
-						activeProvidesSourceIds: /* @__PURE__ */ new Set()
+						activeProvidesSourceIds: /* @__PURE__ */ new Set(),
+						demandEdges: []
 					};
 					return await computeActiveBarrierDependencies(expandGuessedBranchNodes());
 				},
@@ -6751,7 +6828,9 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					if (result == null || isDeferredCompletionResult(result) || result.success !== true) return void 0;
 					if (String(result.value) !== speculativeKey) return void 0;
 					if (branches[speculativeKey] == null) return void 0;
-					return await ctx.schedule(expandGuessedBranchNodes());
+					const failure = await ctx.schedule(expandGuessedBranchNodes());
+					if (failure == null) return void 0;
+					return wrapCachedBarrierFailure(session, failure, speculativeKey);
 				}
 			});
 			return nodes;
@@ -6819,19 +6898,23 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			providesSourceIds: branchProvidedSourceIds,
 			...branchGuaranteedIntersection.size > 0 ? { guaranteedProvidesSourceIds: branchGuaranteedIntersection } : {},
 			...mergedBarrierDependencies != null ? { barrierCompletionDependencies: mergedBarrierDependencies } : {},
+			barrierDemandActivation: "after-resolution",
 			resolveBarrier: async (ctx) => {
 				const prepared = await resolvePreparedSelection(ctx);
 				if (prepared == null) return void 0;
 				if (prepared.branchParser == null) return {
 					orderingDependencyIds: [],
-					activeProvidesSourceIds: /* @__PURE__ */ new Set()
+					activeProvidesSourceIds: /* @__PURE__ */ new Set(),
+					demandEdges: []
 				};
 				return await computeActiveBarrierDependencies(expandPreparedBranchNodes(prepared));
 			},
 			prepare: async (ctx) => {
 				const prepared = await resolvePreparedSelection(ctx);
 				if (prepared?.branchParser == null) return void 0;
-				return await ctx.schedule(expandPreparedBranchNodes(prepared));
+				const failure = await ctx.schedule(expandPreparedBranchNodes(prepared));
+				if (failure == null) return void 0;
+				return wrapCachedBarrierFailure(ctx.exec?.effectfulCompletionSession, failure, prepared.branchKey);
 			}
 		});
 		return nodes;
@@ -6979,14 +7062,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			else if (wasSpeculative) return completedDiscriminator;
 			else discriminatorValue = state.selectedBranch.key;
 		}
-		if (wasSpeculative && state.selectedBranch.kind === "branch" && discriminatorValue !== state.selectedBranch.key) {
-			const speculativeKey = state.selectedBranch.key;
-			const resolvedKey = typeof discriminatorValue === "string" ? discriminatorValue : "<unknown>";
-			return {
-				success: false,
-				error: options?.errors?.branchMismatch ? options.errors.branchMismatch(resolvedKey, speculativeKey) : message`Branch mismatch: tokens for ${speculativeKey} were consumed, but the discriminator resolved to ${resolvedKey}.`
-			};
-		}
+		if (wasSpeculative && state.selectedBranch.kind === "branch" && discriminatorValue !== state.selectedBranch.key) return branchMismatchFailure(discriminatorValue, state.selectedBranch.key);
 		const resolvedBranchState = getWrappedChildState(state, await resolveStateWithRuntimeAsync(state.branchState, runtime), branchParser);
 		const branchResult = unwrapCompleteResult(await branchParser.complete(resolvedBranchState, withChildExecPath(completionExec, "_branch")));
 		if (!branchResult.success) {

package/dist/dependency-runtime.cjs

@@ -1151,6 +1151,133 @@ function collectDeferredDemand(state, demanded, visited) {
 	for (const key of Reflect.ownKeys(state)) collectDeferredDemand(state[key], demanded, visited);
 }
 /**
+* Runs the monotonic demand fixed point over the given nodes' metadata,
+* adding to the session's demanded set until nothing changes:
+*
+* - a demanded derived source demands its dependency IDs;
+* - a demanded source whose effectful completion consumes other
+*   dependency values (a prompt with a derived configuration) demands
+*   those prerequisites, unless this occurrence is already satisfied;
+* - a barrier's demand edges mirror the flat completion rule for the
+*   consumers hidden behind it—only when a branch consumer's own source
+*   is demanded do its completion prerequisites become demanded—but a
+*   barrier whose {@link RuntimeNode.barrierDemandActivation} is
+*   `"after-resolution"` contributes its edges only once it has
+*   resolved, so an unselected branch's prerequisites are never
+*   demanded on the strength of a static estimate;
+* - when a source a barrier can provide is demanded, the barrier's
+*   control dependency (its discriminator source) becomes demanded.
+*
+* One barrier's branches can provide another barrier's discriminator
+* source, and the chain must propagate regardless of declaration order.
+* Each iteration adds at least one demanded ID, so the loop terminates.
+* The scheduler re-runs this after a gated barrier resolves, passing
+* the pass's metadata universe with resolved replacement nodes swapped
+* in, so promotion chains through already-visited metadata as well.
+*/
+function propagateDemand(universe, session) {
+	let demandAdded = true;
+	while (demandAdded) {
+		demandAdded = false;
+		for (const node of universe) {
+			const metadata = node.parser.dependencyMetadata;
+			if (metadata?.source != null && metadata.derived != null && session.demanded.has(metadata.source.sourceId)) for (const dependencySourceId of metadata.derived.dependencyIds) {
+				if (session.demanded.has(dependencySourceId)) continue;
+				session.demanded.add(dependencySourceId);
+				demandAdded = true;
+			}
+			if (metadata?.source != null && metadata.completion != null && session.demanded.has(metadata.source.sourceId) && !hasInactiveCompletion(node)) for (const dependencySourceId of metadata.completion.dependencyIds) {
+				if (session.demanded.has(dependencySourceId)) continue;
+				session.demanded.add(dependencySourceId);
+				demandAdded = true;
+			}
+			if (node.barrierCompletionDependencies != null && (node.barrierDemandActivation !== "after-resolution" || node.barrierResolutionState === "resolved")) 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)) {
+				session.demanded.add(node.requiresSourceId);
+				demandAdded = true;
+				break;
+			}
+		}
+	}
+}
+const barrierFailureDescription = "optique.barrierFailure";
+/**
+* Replaces a barrier failure cached in the run-scoped session with a
+* wrapped version of the same failure, identified by object identity.
+* A construct that decorates a nested barrier failure on its way out—a
+* `conditional()` applying its `branchError` hook—uses this so later
+* passes sharing the session (the eager fallback after a failed seed
+* pass) surface the wrapped error rather than the raw one.
+*
+* @param session The run-scoped effectful completion session.
+* @param original The failure exactly as the scheduling pass returned
+*   it.
+* @param replacement The decorated failure to cache in its place.
+* @returns Whether a cached barrier failure was found and replaced;
+*   `false` means the failure did not come from a barrier resolution
+*   and should propagate untouched.
+* @internal
+* @since 1.3.0
+*/
+function replaceCachedBarrierFailure(session, original, replacement) {
+	if (session == null) return false;
+	let replaced = false;
+	for (const [key, value] of session.results) if (key.description === barrierFailureDescription && value === original) {
+		session.results.set(key, replacement);
+		replaced = true;
+	}
+	return replaced;
+}
+/**
+* Whether the node is a scheduling barrier whose demand edges are gated
+* on resolution and whose resolution has not happened yet.  While any
+* such barrier is pending in a demand-only pass, the scheduler parks
+* not-yet-demanded effectful nodes instead of letting them defer, so a
+* later resolution can still demand them into their dependency slot.
+*/
+function isGatedUnresolvedBarrier(node) {
+	return node.resolveBarrier != null && node.barrierDemandActivation === "after-resolution" && node.barrierResolutionState == null;
+}
+/**
+* Collects the nodes a demand-only pass must not visit yet while a
+* gated barrier is unresolved: every effectful source node whose own
+* source is not demanded (its completion would defer irrevocably for
+* this pass, yet a barrier's resolution may still demand it), plus
+* every node reachable from a parked node along hard (non-advisory)
+* dependency edges, so a dependent—a derived replay, a barrier whose
+* control dependency is a parked discriminator—never runs ahead of a
+* parked provider.  The scheduling loop's all-blocked fallback keeps
+* the pass progressing even when this parks every pending node.
+*/
+function collectParkedNodes(pending, session) {
+	const parked = /* @__PURE__ */ new Set();
+	for (const node of pending) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source?.completeSource != null && !session.demanded.has(source.sourceId)) parked.add(node);
+	}
+	if (parked.size === 0) return parked;
+	const graph = buildDependencyGraph(pending);
+	const queue = [...parked];
+	while (queue.length > 0) {
+		const provider = queue.pop();
+		for (const [consumer, advisoryOnly] of graph.outgoing.get(provider) ?? []) {
+			if (advisoryOnly || parked.has(consumer)) continue;
+			parked.add(consumer);
+			queue.push(consumer);
+		}
+	}
+	return parked;
+}
+/**
 * Runs effectful source completions (e.g., interactive prompts) serially
 * in declaration order for source nodes whose value is not yet registered.
 *
@@ -1207,38 +1334,7 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 		const demandNodes = options?.demandNodes ?? nodes;
 		const demanded = collectDemandedDependencyIds(demandNodes, state, exec.trace);
 		for (const id of demanded) session.demanded.add(id);
-		let demandAdded = true;
-		while (demandAdded) {
-			demandAdded = false;
-			for (const node of nodes) {
-				const metadata = node.parser.dependencyMetadata;
-				if (metadata?.source != null && metadata.derived != null && session.demanded.has(metadata.source.sourceId)) for (const dependencySourceId of metadata.derived.dependencyIds) {
-					if (session.demanded.has(dependencySourceId)) continue;
-					session.demanded.add(dependencySourceId);
-					demandAdded = true;
-				}
-				if (metadata?.source != null && metadata.completion != null && session.demanded.has(metadata.source.sourceId) && !hasInactiveCompletion(node)) for (const dependencySourceId of metadata.completion.dependencyIds) {
-					if (session.demanded.has(dependencySourceId)) continue;
-					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)) {
-					session.demanded.add(node.requiresSourceId);
-					demandAdded = true;
-					break;
-				}
-			}
-		}
+		propagateDemand(nodes, session);
 	}
 	if (session != null) {
 		for (const result of session.results.values()) if (!result.success) return {
@@ -1259,12 +1355,17 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 		}).then((result) => result.success ? void 0 : result)
 	};
 	const pending = [...nodes];
+	const metadataUniverse = [...nodes];
 	const providesId = (node, id) => node.parser.dependencyMetadata?.source?.sourceId === id || node.providesSourceIds?.has(id) === true;
+	const demandSession = session?.policy === "demand-only" ? session : void 0;
 	const resolveBarrierAt = async (index) => {
 		const candidate = pending[index];
 		const resolution = await candidate.resolveBarrier(barrierContext);
-		if (resolution != null && "success" in resolution) return resolution;
-		pending[index] = resolution == null ? {
+		if (resolution != null && "success" in resolution) {
+			session?.results.set(Symbol(barrierFailureDescription), resolution);
+			return resolution;
+		}
+		const replacement = resolution == null ? {
 			...candidate,
 			barrierResolutionState: "unresolvable"
 		} : {
@@ -1273,22 +1374,44 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 			providesSourceIds: resolution.activeProvidesSourceIds,
 			barrierCompletionDependencies: {
 				orderingDependencyIds: resolution.orderingDependencyIds,
-				demandEdges: []
+				demandEdges: resolution.demandEdges
 			}
 		};
+		pending[index] = replacement;
+		const universeIndex = metadataUniverse.indexOf(candidate);
+		if (universeIndex >= 0) metadataUniverse[universeIndex] = replacement;
+		if (resolution != null && demandSession != null) propagateDemand(metadataUniverse, demandSession);
 		return void 0;
 	};
 	while (pending.length > 0) {
+		const parkingActive = demandSession != null && pending.some(isGatedUnresolvedBarrier);
 		for (let i = 0; i < pending.length; i++) {
 			const candidate = pending[i];
 			if (candidate.resolveBarrier == null || candidate.barrierResolutionState != null) continue;
 			const requires = candidate.requiresSourceId;
 			if (requires == null) continue;
+			if (parkingActive && demandSession != null && !demandSession.demanded.has(requires)) continue;
 			if (pending.some((other) => other !== candidate && providesId(other, requires))) continue;
 			const failure = await resolveBarrierAt(i);
 			if (failure != null) return failure;
 		}
-		const node = orderDependencyNodes(pending)[0];
+		const ordered = orderDependencyNodes(pending);
+		let node = ordered[0];
+		const parkingStillActive = demandSession != null && pending.some(isGatedUnresolvedBarrier);
+		if (parkingStillActive && demandSession != null) {
+			const parked = collectParkedNodes(pending, demandSession);
+			const isSkippedBarrier = (candidate) => candidate.resolveBarrier != null && candidate.barrierResolutionState == null && candidate.requiresSourceId != null && !demandSession.demanded.has(candidate.requiresSourceId);
+			const selectable = ordered.find((candidate) => !parked.has(candidate) && !isSkippedBarrier(candidate));
+			if (selectable != null) node = selectable;
+			else {
+				const stalled = ordered.find((candidate) => candidate.resolveBarrier != null && candidate.barrierResolutionState == null);
+				if (stalled != null) {
+					const failure = await resolveBarrierAt(pending.indexOf(stalled));
+					if (failure != null) return failure;
+					continue;
+				}
+			}
+		}
 		if (node.resolveBarrier != null && node.barrierResolutionState == null) {
 			const failure = await resolveBarrierAt(pending.indexOf(node));
 			if (failure != null) return failure;
@@ -1703,6 +1826,7 @@ exports.hasInactiveCompletion = hasInactiveCompletion;
 exports.includeSourceFailureChain = includeSourceFailureChain;
 exports.orderDependencyNodes = orderDependencyNodes;
 exports.recordDerivedRawInput = recordDerivedRawInput;
+exports.replaceCachedBarrierFailure = replaceCachedBarrierFailure;
 exports.replayDerivedParser = replayDerivedParser;
 exports.replayDerivedParserAsync = replayDerivedParserAsync;
 exports.resolveDerivedSourceValues = resolveDerivedSourceValues;

package/dist/dependency-runtime.d.cts

@@ -3,7 +3,7 @@ import { DependencyRegistryLike } from "./registry-types.cjs";
 import { ValueParserResult } from "./valueparser.cjs";
 import { ParserDependencyMetadata } from "./dependency-metadata.cjs";
 import { InputTrace } from "./input-trace.cjs";
-import { ExecutionContext } from "./internal/parser.cjs";
+import { EffectfulCompletionSession, ExecutionContext } from "./internal/parser.cjs";
 
 //#region src/dependency-runtime.d.ts
 
@@ -220,6 +220,22 @@ interface RuntimeNode {
    * @since 1.3.0
    */
   readonly barrierCompletionDependencies?: BarrierCompletionDependencies;
+  /**
+   * When `"after-resolution"`, the demand edges in
+   * {@link RuntimeNode.barrierCompletionDependencies} join demand
+   * propagation only once {@link RuntimeNode.resolveBarrier} has
+   * replaced the static estimate with the resolved selection's actual
+   * edges.  Until then the demand-only pass parks not-yet-demanded
+   * effectful nodes instead of letting them defer, so a prerequisite
+   * demanded only by an unselected branch never runs, while one the
+   * resolved selection reads still completes in its dependency slot.
+   * A barrier the pass marks `"unresolvable"` never activates its
+   * edges within that pass.  Ordering and control edges are unaffected.
+   * Default: `"immediate"`.
+   *
+   * @since 1.3.0
+   */
+  readonly barrierDemandActivation?: "immediate" | "after-resolution";
 }
 /**
  * An exact demand edge inside a scheduling barrier's subtree: when the
@@ -285,6 +301,19 @@ interface BarrierResolution {
    * sibling consumer no longer waits for a merely possible provider.
    */
   readonly activeProvidesSourceIds: ReadonlySet<symbol>;
+  /**
+   * The demand edges of the resolved selection: empty when the
+   * selection was rejected or has no completion consumers.  A
+   * demand-only pass applies them once the barrier resolves, so a
+   * prerequisite is demanded only for a selection that actually reads
+   * it.  Edges belonging to a nested barrier whose own demand
+   * activation is `"after-resolution"` and which is still unresolved
+   * must not appear here; the nested barrier promotes them itself
+   * within its own scheduling pass.
+   *
+   * @since 1.3.0
+   */
+  readonly demandEdges: readonly BarrierCompletionDemandEdge[];
 }
 /**
  * Options for resolving matched derived source values.
@@ -723,6 +752,31 @@ interface CompleteEffectfulSourcesOptions {
    */
   readonly includeStructural?: boolean;
 }
+/**
+ * Replaces a barrier failure cached in the run-scoped session with a
+ * wrapped version of the same failure, identified by object identity.
+ * A construct that decorates a nested barrier failure on its way out—a
+ * `conditional()` applying its `branchError` hook—uses this so later
+ * passes sharing the session (the eager fallback after a failed seed
+ * pass) surface the wrapped error rather than the raw one.
+ *
+ * @param session The run-scoped effectful completion session.
+ * @param original The failure exactly as the scheduling pass returned
+ *   it.
+ * @param replacement The decorated failure to cache in its place.
+ * @returns Whether a cached barrier failure was found and replaced;
+ *   `false` means the failure did not come from a barrier resolution
+ *   and should propagate untouched.
+ * @internal
+ * @since 1.3.0
+ */
+declare function replaceCachedBarrierFailure(session: EffectfulCompletionSession | undefined, original: {
+  readonly success: false;
+  readonly error: Message;
+}, replacement: {
+  readonly success: false;
+  readonly error: Message;
+}): boolean;
 /**
  * Runs effectful source completions (e.g., interactive prompts) serially
  * in declaration order for source nodes whose value is not yet registered.
@@ -858,4 +912,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, 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, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, 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, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.d.ts

@@ -3,7 +3,7 @@ import { DependencyRegistryLike } from "./registry-types.js";
 import { ValueParserResult } from "./valueparser.js";
 import { ParserDependencyMetadata } from "./dependency-metadata.js";
 import { InputTrace } from "./input-trace.js";
-import { ExecutionContext } from "./internal/parser.js";
+import { EffectfulCompletionSession, ExecutionContext } from "./internal/parser.js";
 
 //#region src/dependency-runtime.d.ts
 
@@ -220,6 +220,22 @@ interface RuntimeNode {
    * @since 1.3.0
    */
   readonly barrierCompletionDependencies?: BarrierCompletionDependencies;
+  /**
+   * When `"after-resolution"`, the demand edges in
+   * {@link RuntimeNode.barrierCompletionDependencies} join demand
+   * propagation only once {@link RuntimeNode.resolveBarrier} has
+   * replaced the static estimate with the resolved selection's actual
+   * edges.  Until then the demand-only pass parks not-yet-demanded
+   * effectful nodes instead of letting them defer, so a prerequisite
+   * demanded only by an unselected branch never runs, while one the
+   * resolved selection reads still completes in its dependency slot.
+   * A barrier the pass marks `"unresolvable"` never activates its
+   * edges within that pass.  Ordering and control edges are unaffected.
+   * Default: `"immediate"`.
+   *
+   * @since 1.3.0
+   */
+  readonly barrierDemandActivation?: "immediate" | "after-resolution";
 }
 /**
  * An exact demand edge inside a scheduling barrier's subtree: when the
@@ -285,6 +301,19 @@ interface BarrierResolution {
    * sibling consumer no longer waits for a merely possible provider.
    */
   readonly activeProvidesSourceIds: ReadonlySet<symbol>;
+  /**
+   * The demand edges of the resolved selection: empty when the
+   * selection was rejected or has no completion consumers.  A
+   * demand-only pass applies them once the barrier resolves, so a
+   * prerequisite is demanded only for a selection that actually reads
+   * it.  Edges belonging to a nested barrier whose own demand
+   * activation is `"after-resolution"` and which is still unresolved
+   * must not appear here; the nested barrier promotes them itself
+   * within its own scheduling pass.
+   *
+   * @since 1.3.0
+   */
+  readonly demandEdges: readonly BarrierCompletionDemandEdge[];
 }
 /**
  * Options for resolving matched derived source values.
@@ -723,6 +752,31 @@ interface CompleteEffectfulSourcesOptions {
    */
   readonly includeStructural?: boolean;
 }
+/**
+ * Replaces a barrier failure cached in the run-scoped session with a
+ * wrapped version of the same failure, identified by object identity.
+ * A construct that decorates a nested barrier failure on its way out—a
+ * `conditional()` applying its `branchError` hook—uses this so later
+ * passes sharing the session (the eager fallback after a failed seed
+ * pass) surface the wrapped error rather than the raw one.
+ *
+ * @param session The run-scoped effectful completion session.
+ * @param original The failure exactly as the scheduling pass returned
+ *   it.
+ * @param replacement The decorated failure to cache in its place.
+ * @returns Whether a cached barrier failure was found and replaced;
+ *   `false` means the failure did not come from a barrier resolution
+ *   and should propagate untouched.
+ * @internal
+ * @since 1.3.0
+ */
+declare function replaceCachedBarrierFailure(session: EffectfulCompletionSession | undefined, original: {
+  readonly success: false;
+  readonly error: Message;
+}, replacement: {
+  readonly success: false;
+  readonly error: Message;
+}): boolean;
 /**
  * Runs effectful source completions (e.g., interactive prompts) serially
  * in declaration order for source nodes whose value is not yet registered.
@@ -858,4 +912,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, 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, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, 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, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.js

@@ -1151,6 +1151,133 @@ function collectDeferredDemand(state, demanded, visited) {
 	for (const key of Reflect.ownKeys(state)) collectDeferredDemand(state[key], demanded, visited);
 }
 /**
+* Runs the monotonic demand fixed point over the given nodes' metadata,
+* adding to the session's demanded set until nothing changes:
+*
+* - a demanded derived source demands its dependency IDs;
+* - a demanded source whose effectful completion consumes other
+*   dependency values (a prompt with a derived configuration) demands
+*   those prerequisites, unless this occurrence is already satisfied;
+* - a barrier's demand edges mirror the flat completion rule for the
+*   consumers hidden behind it—only when a branch consumer's own source
+*   is demanded do its completion prerequisites become demanded—but a
+*   barrier whose {@link RuntimeNode.barrierDemandActivation} is
+*   `"after-resolution"` contributes its edges only once it has
+*   resolved, so an unselected branch's prerequisites are never
+*   demanded on the strength of a static estimate;
+* - when a source a barrier can provide is demanded, the barrier's
+*   control dependency (its discriminator source) becomes demanded.
+*
+* One barrier's branches can provide another barrier's discriminator
+* source, and the chain must propagate regardless of declaration order.
+* Each iteration adds at least one demanded ID, so the loop terminates.
+* The scheduler re-runs this after a gated barrier resolves, passing
+* the pass's metadata universe with resolved replacement nodes swapped
+* in, so promotion chains through already-visited metadata as well.
+*/
+function propagateDemand(universe, session) {
+	let demandAdded = true;
+	while (demandAdded) {
+		demandAdded = false;
+		for (const node of universe) {
+			const metadata = node.parser.dependencyMetadata;
+			if (metadata?.source != null && metadata.derived != null && session.demanded.has(metadata.source.sourceId)) for (const dependencySourceId of metadata.derived.dependencyIds) {
+				if (session.demanded.has(dependencySourceId)) continue;
+				session.demanded.add(dependencySourceId);
+				demandAdded = true;
+			}
+			if (metadata?.source != null && metadata.completion != null && session.demanded.has(metadata.source.sourceId) && !hasInactiveCompletion(node)) for (const dependencySourceId of metadata.completion.dependencyIds) {
+				if (session.demanded.has(dependencySourceId)) continue;
+				session.demanded.add(dependencySourceId);
+				demandAdded = true;
+			}
+			if (node.barrierCompletionDependencies != null && (node.barrierDemandActivation !== "after-resolution" || node.barrierResolutionState === "resolved")) 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)) {
+				session.demanded.add(node.requiresSourceId);
+				demandAdded = true;
+				break;
+			}
+		}
+	}
+}
+const barrierFailureDescription = "optique.barrierFailure";
+/**
+* Replaces a barrier failure cached in the run-scoped session with a
+* wrapped version of the same failure, identified by object identity.
+* A construct that decorates a nested barrier failure on its way out—a
+* `conditional()` applying its `branchError` hook—uses this so later
+* passes sharing the session (the eager fallback after a failed seed
+* pass) surface the wrapped error rather than the raw one.
+*
+* @param session The run-scoped effectful completion session.
+* @param original The failure exactly as the scheduling pass returned
+*   it.
+* @param replacement The decorated failure to cache in its place.
+* @returns Whether a cached barrier failure was found and replaced;
+*   `false` means the failure did not come from a barrier resolution
+*   and should propagate untouched.
+* @internal
+* @since 1.3.0
+*/
+function replaceCachedBarrierFailure(session, original, replacement) {
+	if (session == null) return false;
+	let replaced = false;
+	for (const [key, value] of session.results) if (key.description === barrierFailureDescription && value === original) {
+		session.results.set(key, replacement);
+		replaced = true;
+	}
+	return replaced;
+}
+/**
+* Whether the node is a scheduling barrier whose demand edges are gated
+* on resolution and whose resolution has not happened yet.  While any
+* such barrier is pending in a demand-only pass, the scheduler parks
+* not-yet-demanded effectful nodes instead of letting them defer, so a
+* later resolution can still demand them into their dependency slot.
+*/
+function isGatedUnresolvedBarrier(node) {
+	return node.resolveBarrier != null && node.barrierDemandActivation === "after-resolution" && node.barrierResolutionState == null;
+}
+/**
+* Collects the nodes a demand-only pass must not visit yet while a
+* gated barrier is unresolved: every effectful source node whose own
+* source is not demanded (its completion would defer irrevocably for
+* this pass, yet a barrier's resolution may still demand it), plus
+* every node reachable from a parked node along hard (non-advisory)
+* dependency edges, so a dependent—a derived replay, a barrier whose
+* control dependency is a parked discriminator—never runs ahead of a
+* parked provider.  The scheduling loop's all-blocked fallback keeps
+* the pass progressing even when this parks every pending node.
+*/
+function collectParkedNodes(pending, session) {
+	const parked = /* @__PURE__ */ new Set();
+	for (const node of pending) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source?.completeSource != null && !session.demanded.has(source.sourceId)) parked.add(node);
+	}
+	if (parked.size === 0) return parked;
+	const graph = buildDependencyGraph(pending);
+	const queue = [...parked];
+	while (queue.length > 0) {
+		const provider = queue.pop();
+		for (const [consumer, advisoryOnly] of graph.outgoing.get(provider) ?? []) {
+			if (advisoryOnly || parked.has(consumer)) continue;
+			parked.add(consumer);
+			queue.push(consumer);
+		}
+	}
+	return parked;
+}
+/**
 * Runs effectful source completions (e.g., interactive prompts) serially
 * in declaration order for source nodes whose value is not yet registered.
 *
@@ -1207,38 +1334,7 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 		const demandNodes = options?.demandNodes ?? nodes;
 		const demanded = collectDemandedDependencyIds(demandNodes, state, exec.trace);
 		for (const id of demanded) session.demanded.add(id);
-		let demandAdded = true;
-		while (demandAdded) {
-			demandAdded = false;
-			for (const node of nodes) {
-				const metadata = node.parser.dependencyMetadata;
-				if (metadata?.source != null && metadata.derived != null && session.demanded.has(metadata.source.sourceId)) for (const dependencySourceId of metadata.derived.dependencyIds) {
-					if (session.demanded.has(dependencySourceId)) continue;
-					session.demanded.add(dependencySourceId);
-					demandAdded = true;
-				}
-				if (metadata?.source != null && metadata.completion != null && session.demanded.has(metadata.source.sourceId) && !hasInactiveCompletion(node)) for (const dependencySourceId of metadata.completion.dependencyIds) {
-					if (session.demanded.has(dependencySourceId)) continue;
-					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)) {
-					session.demanded.add(node.requiresSourceId);
-					demandAdded = true;
-					break;
-				}
-			}
-		}
+		propagateDemand(nodes, session);
 	}
 	if (session != null) {
 		for (const result of session.results.values()) if (!result.success) return {
@@ -1259,12 +1355,17 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 		}).then((result) => result.success ? void 0 : result)
 	};
 	const pending = [...nodes];
+	const metadataUniverse = [...nodes];
 	const providesId = (node, id) => node.parser.dependencyMetadata?.source?.sourceId === id || node.providesSourceIds?.has(id) === true;
+	const demandSession = session?.policy === "demand-only" ? session : void 0;
 	const resolveBarrierAt = async (index) => {
 		const candidate = pending[index];
 		const resolution = await candidate.resolveBarrier(barrierContext);
-		if (resolution != null && "success" in resolution) return resolution;
-		pending[index] = resolution == null ? {
+		if (resolution != null && "success" in resolution) {
+			session?.results.set(Symbol(barrierFailureDescription), resolution);
+			return resolution;
+		}
+		const replacement = resolution == null ? {
 			...candidate,
 			barrierResolutionState: "unresolvable"
 		} : {
@@ -1273,22 +1374,44 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 			providesSourceIds: resolution.activeProvidesSourceIds,
 			barrierCompletionDependencies: {
 				orderingDependencyIds: resolution.orderingDependencyIds,
-				demandEdges: []
+				demandEdges: resolution.demandEdges
 			}
 		};
+		pending[index] = replacement;
+		const universeIndex = metadataUniverse.indexOf(candidate);
+		if (universeIndex >= 0) metadataUniverse[universeIndex] = replacement;
+		if (resolution != null && demandSession != null) propagateDemand(metadataUniverse, demandSession);
 		return void 0;
 	};
 	while (pending.length > 0) {
+		const parkingActive = demandSession != null && pending.some(isGatedUnresolvedBarrier);
 		for (let i = 0; i < pending.length; i++) {
 			const candidate = pending[i];
 			if (candidate.resolveBarrier == null || candidate.barrierResolutionState != null) continue;
 			const requires = candidate.requiresSourceId;
 			if (requires == null) continue;
+			if (parkingActive && demandSession != null && !demandSession.demanded.has(requires)) continue;
 			if (pending.some((other) => other !== candidate && providesId(other, requires))) continue;
 			const failure = await resolveBarrierAt(i);
 			if (failure != null) return failure;
 		}
-		const node = orderDependencyNodes(pending)[0];
+		const ordered = orderDependencyNodes(pending);
+		let node = ordered[0];
+		const parkingStillActive = demandSession != null && pending.some(isGatedUnresolvedBarrier);
+		if (parkingStillActive && demandSession != null) {
+			const parked = collectParkedNodes(pending, demandSession);
+			const isSkippedBarrier = (candidate) => candidate.resolveBarrier != null && candidate.barrierResolutionState == null && candidate.requiresSourceId != null && !demandSession.demanded.has(candidate.requiresSourceId);
+			const selectable = ordered.find((candidate) => !parked.has(candidate) && !isSkippedBarrier(candidate));
+			if (selectable != null) node = selectable;
+			else {
+				const stalled = ordered.find((candidate) => candidate.resolveBarrier != null && candidate.barrierResolutionState == null);
+				if (stalled != null) {
+					const failure = await resolveBarrierAt(pending.indexOf(stalled));
+					if (failure != null) return failure;
+					continue;
+				}
+			}
+		}
 		if (node.resolveBarrier != null && node.barrierResolutionState == null) {
 			const failure = await resolveBarrierAt(pending.indexOf(node));
 			if (failure != null) return failure;
@@ -1681,4 +1804,4 @@ function getDefaultDependencySnapshotInner(state, visited) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, 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, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/package.json

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