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

package/dist/dependency-runtime.cjs

@@ -404,6 +404,17 @@ async function collectExplicitSourceValuesAsync(nodes, runtime) {
 * @since 1.3.0
 */
 function orderDependencyNodes(nodes) {
+	return drainDependencyGraph(buildDependencyGraph(nodes));
+}
+/**
+* Builds the provider-edge graph over runtime nodes.
+*
+* Scheduling barriers act as providers for the source IDs their
+* selected subtree may expose and depend on their discriminator source
+* as well as on outer providers of the completion dependencies their
+* selectable subtrees aggregate.
+*/
+function buildDependencyGraph(nodes) {
 	const providers = /* @__PURE__ */ new Map();
 	const addProvider = (sourceId, node) => {
 		const existing = providers.get(sourceId);
@@ -418,51 +429,162 @@ function orderDependencyNodes(nodes) {
 	const outgoing = /* @__PURE__ */ new Map();
 	const indegree = /* @__PURE__ */ new Map();
 	for (const node of nodes) indegree.set(node, 0);
-	const addEdge = (provider, consumer) => {
-		const edges = outgoing.get(provider) ?? /* @__PURE__ */ new Set();
-		if (edges.has(consumer)) return;
-		edges.add(consumer);
+	const addEdge = (provider, consumer, advisory) => {
+		const edges = outgoing.get(provider) ?? /* @__PURE__ */ new Map();
+		const existing = edges.get(consumer);
+		if (existing != null) {
+			if (existing && !advisory) edges.set(consumer, false);
+			return;
+		}
+		edges.set(consumer, advisory);
 		outgoing.set(provider, edges);
 		indegree.set(consumer, (indegree.get(consumer) ?? 0) + 1);
 	};
 	for (const node of nodes) {
 		const derived = node.parser.dependencyMetadata?.derived;
-		if (derived != null) for (const dependencySourceId of derived.dependencyIds) for (const provider of providers.get(dependencySourceId) ?? []) addEdge(provider, node);
+		if (derived != null) for (const dependencySourceId of derived.dependencyIds) for (const provider of providers.get(dependencySourceId) ?? []) addEdge(provider, node, false);
 		const completion = node.parser.dependencyMetadata?.completion;
 		if (completion != null && !hasInactiveCompletion(node)) {
 			const ownSourceId = node.parser.dependencyMetadata?.source?.sourceId;
 			for (const dependencySourceId of completion.dependencyIds) {
 				if (dependencySourceId === ownSourceId) continue;
-				for (const provider of providers.get(dependencySourceId) ?? []) if (provider !== node) addEdge(provider, node);
+				for (const provider of providers.get(dependencySourceId) ?? []) if (provider !== node) addEdge(provider, node, false);
 			}
 		}
 		if (node.requiresSourceId != null) {
-			for (const provider of providers.get(node.requiresSourceId) ?? []) if (provider !== node) addEdge(provider, node);
+			for (const provider of providers.get(node.requiresSourceId) ?? []) if (provider !== node) addEdge(provider, node, false);
 		}
 		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 advisory = node.barrierResolutionState !== "resolved";
+			for (const dependencySourceId of barrierDeps.orderingDependencyIds) for (const provider of providers.get(dependencySourceId) ?? []) if (provider !== node) addEdge(provider, node, advisory);
 		}
 	}
 	const declarationOrder = new Map(nodes.map((node, index) => [node, index]));
+	return {
+		nodes,
+		outgoing,
+		indegree,
+		declarationOrder
+	};
+}
+/**
+* Drains the graph in stable topological order.
+*
+* A stall—no node with indegree zero remains—normally means a genuine
+* cycle.  When the stalled region contains an unresolved barrier's
+* advisory ordering edges within one strongly connected component, the
+* apparent cycle aggregates edges from branches that cannot be selected
+* together, so those advisory edges are relaxed and the drain resumes;
+* the barrier's own resolution later replaces the estimate with
+* concrete edges, and a cycle among those still throws.
+*
+* @throws {TypeError} If active provider edges contain a cycle.
+*/
+function drainDependencyGraph(graph) {
+	const { nodes, outgoing, declarationOrder } = graph;
+	const indegree = new Map(graph.indegree);
 	const ready = nodes.filter((node) => indegree.get(node) === 0);
 	const ordered = [];
-	while (ready.length > 0) {
-		ready.sort((left, right) => declarationOrder.get(left) - declarationOrder.get(right));
-		const node = ready.shift();
-		ordered.push(node);
-		for (const consumer of outgoing.get(node) ?? []) {
-			const next = (indegree.get(consumer) ?? 0) - 1;
-			indegree.set(consumer, next);
-			if (next === 0) ready.push(consumer);
+	while (true) {
+		while (ready.length > 0) {
+			ready.sort((left, right) => declarationOrder.get(left) - declarationOrder.get(right));
+			const node = ready.shift();
+			ordered.push(node);
+			for (const consumer of outgoing.get(node)?.keys() ?? []) {
+				const next = (indegree.get(consumer) ?? 0) - 1;
+				indegree.set(consumer, next);
+				if (next === 0) ready.push(consumer);
+			}
+		}
+		if (ordered.length === nodes.length) return ordered;
+		const residual = nodes.filter((node) => (indegree.get(node) ?? 0) > 0);
+		const sccOf = findStronglyConnected(residual, outgoing);
+		let relaxed = false;
+		for (const provider of residual) {
+			const edges = outgoing.get(provider);
+			if (edges == null) continue;
+			for (const [consumer, advisory] of edges) {
+				if (!advisory) continue;
+				const providerScc = sccOf.get(provider);
+				if (providerScc == null || providerScc !== sccOf.get(consumer)) continue;
+				edges.delete(consumer);
+				const next = (indegree.get(consumer) ?? 0) - 1;
+				indegree.set(consumer, next);
+				if (next === 0) ready.push(consumer);
+				relaxed = true;
+			}
+		}
+		if (!relaxed) {
+			const labels = residual.map(formatDependencyNodeLabel).join(" -> ");
+			throw new TypeError(`Circular dependency detected among dependency sources: ${labels}.`);
 		}
 	}
-	if (ordered.length !== nodes.length) {
-		const cycle = nodes.filter((node) => (indegree.get(node) ?? 0) > 0);
-		const labels = cycle.map(formatDependencyNodeLabel).join(" -> ");
-		throw new TypeError(`Circular dependency detected among dependency sources: ${labels}.`);
-	}
-	return ordered;
+}
+/**
+* Assigns each node in `subset` to a strongly connected component of
+* the induced subgraph.  Only components with more than one node are
+* recorded—an acyclic node cannot be part of an apparent cycle.
+*/
+function findStronglyConnected(subset, outgoing) {
+	const inSubset = new Set(subset);
+	const index = /* @__PURE__ */ new Map();
+	const lowLink = /* @__PURE__ */ new Map();
+	const onStack = /* @__PURE__ */ new Set();
+	const stack = [];
+	const sccOf = /* @__PURE__ */ new Map();
+	let nextIndex = 0;
+	let nextScc = 0;
+	const strongConnect = (root) => {
+		const frames = [{
+			node: root,
+			children: [...outgoing.get(root)?.keys() ?? []].filter((child) => inSubset.has(child)),
+			i: 0
+		}];
+		index.set(root, nextIndex);
+		lowLink.set(root, nextIndex);
+		nextIndex++;
+		stack.push(root);
+		onStack.add(root);
+		while (frames.length > 0) {
+			const frame = frames[frames.length - 1];
+			if (frame.i < frame.children.length) {
+				const child = frame.children[frame.i++];
+				if (!index.has(child)) {
+					index.set(child, nextIndex);
+					lowLink.set(child, nextIndex);
+					nextIndex++;
+					stack.push(child);
+					onStack.add(child);
+					frames.push({
+						node: child,
+						children: [...outgoing.get(child)?.keys() ?? []].filter((c) => inSubset.has(c)),
+						i: 0
+					});
+				} else if (onStack.has(child)) lowLink.set(frame.node, Math.min(lowLink.get(frame.node), index.get(child)));
+				continue;
+			}
+			frames.pop();
+			const node = frame.node;
+			if (lowLink.get(node) === index.get(node)) {
+				const members = [];
+				while (true) {
+					const member = stack.pop();
+					onStack.delete(member);
+					members.push(member);
+					if (member === node) break;
+				}
+				if (members.length > 1) {
+					for (const member of members) sccOf.set(member, nextScc);
+					nextScc++;
+				}
+			}
+			const parent = frames[frames.length - 1];
+			if (parent != null) lowLink.set(parent.node, Math.min(lowLink.get(parent.node), lowLink.get(node)));
+		}
+	};
+	for (const node of subset) if (!index.has(node)) strongConnect(node);
+	return sccOf;
 }
 /** Resolves and publishes matched derived sources in stable dependency order. */
 function resolveDerivedSourceValues(nodes, runtime, options) {
@@ -921,6 +1043,35 @@ const sourceCollectionExpansionKey = Symbol("@optique/core/dependency-runtime/so
 */
 const staticSourceScopeKey = Symbol("@optique/core/dependency-runtime/staticSourceScope");
 /**
+* Static child parsers reachable only through a mutually exclusive
+* selection, such as `or()` alternatives, a `conditional()`'s branches,
+* or a `command()`'s inner parser.
+*
+* The walk unions sources and completion dependencies from this scope
+* exactly like {@link staticSourceScopeKey}, but a source occurrence
+* reached through an exclusive edge is never a *guaranteed* provider:
+* the run may select a sibling instead, so a scheduling barrier must not
+* assume the occurrence will publish.  See issue #924.
+*
+* @internal
+* @since 1.3.0
+*/
+const exclusiveSourceScopeKey = Symbol("@optique/core/dependency-runtime/exclusiveSourceScope");
+/**
+* Source IDs a parser guarantees to provide on every successful route
+* through it, regardless of which internal alternative is selected.
+*
+* A `conditional()` installs the intersection of its branches' guaranteed
+* provides here (including the default branch when present), so an outer
+* scheduling barrier can treat a source that *every* selectable route
+* publishes as guaranteed even though each individual branch edge is
+* exclusive.  See issue #924.
+*
+* @internal
+* @since 1.3.0
+*/
+const guaranteedStaticSourceIdsKey = Symbol("@optique/core/dependency-runtime/guaranteedStaticSourceIds");
+/**
 * Forwards effectful scheduling through a shape-preserving wrapper such
 * as `map()`, `optional()`, `withDefault()`, or `nonEmpty()`, so the
 * wrapped parser—a selected exclusive or command branch, or an ordinary
@@ -1098,17 +1249,54 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 	const schedulable = nodes.filter((node) => node.parser.dependencyMetadata?.source?.completeSource != null || node.prepare != null);
 	if (schedulable.length === 0 && options?.includeStructural !== true) return empty;
 	const completed = [];
-	for (const node of orderDependencyNodes(nodes)) {
+	const barrierContext = {
+		runtime,
+		exec,
+		schedule: (barrierNodes) => completeEffectfulSourcesAsync(barrierNodes, state, runtime, exec, {
+			isReusable: () => false,
+			isCollected: () => true,
+			includeStructural: true
+		}).then((result) => result.success ? void 0 : result)
+	};
+	const pending = [...nodes];
+	const providesId = (node, id) => node.parser.dependencyMetadata?.source?.sourceId === id || node.providesSourceIds?.has(id) === true;
+	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 ? {
+			...candidate,
+			barrierResolutionState: "unresolvable"
+		} : {
+			...candidate,
+			barrierResolutionState: "resolved",
+			providesSourceIds: resolution.activeProvidesSourceIds,
+			barrierCompletionDependencies: {
+				orderingDependencyIds: resolution.orderingDependencyIds,
+				demandEdges: []
+			}
+		};
+		return void 0;
+	};
+	while (pending.length > 0) {
+		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 (pending.some((other) => other !== candidate && providesId(other, requires))) continue;
+			const failure = await resolveBarrierAt(i);
+			if (failure != null) return failure;
+		}
+		const node = orderDependencyNodes(pending)[0];
+		if (node.resolveBarrier != null && node.barrierResolutionState == null) {
+			const failure = await resolveBarrierAt(pending.indexOf(node));
+			if (failure != null) return failure;
+			continue;
+		}
+		pending.splice(pending.indexOf(node), 1);
 		if (node.prepare != null) {
-			const barrierFailure = await node.prepare({
-				runtime,
-				exec,
-				schedule: (barrierNodes) => completeEffectfulSourcesAsync(barrierNodes, state, runtime, exec, {
-					isReusable: () => false,
-					isCollected: () => true,
-					includeStructural: true
-				}).then((result$1) => result$1.success ? void 0 : result$1)
-			});
+			const barrierFailure = await node.prepare(barrierContext);
 			if (barrierFailure != null) return barrierFailure;
 			continue;
 		}
@@ -1140,7 +1328,34 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 			const collected = options?.isCollected?.(node) ?? options?.isReusable?.(node) ?? true;
 			if (source.extractSourceValue == null || collected === false) continue;
 			const extracted = await source.extractSourceValue(node.state);
-			if (extracted?.success === true && extracted.value !== void 0) runtime.registerSource(source.sourceId, extracted.value);
+			if (extracted?.success === true && extracted.value !== void 0) {
+				runtime.registerSource(source.sourceId, extracted.value);
+				continue;
+			}
+			if (options?.includeStructural === true && extracted?.success !== false && node.matched !== true && source.preservesSourceValue && source.getMissingSourceValue != null && !runtime.hasSource(source.sourceId) && !runtime.isSourceFailed(source.sourceId)) {
+				let fallback = session?.missingDefaultsByOccurrence.get(source.getMissingSourceValue);
+				if (fallback == null) {
+					try {
+						fallback = await source.getMissingSourceValue();
+					} catch (e) {
+						const msg = e instanceof Error ? e.message : String(e);
+						fallback = {
+							success: false,
+							error: require_message.message`Default value evaluation failed: ${msg}`
+						};
+					}
+					session?.missingDefaultsByOccurrence.set(source.getMissingSourceValue, fallback);
+				}
+				if (fallback.success) runtime.registerSource(source.sourceId, fallback.value);
+				else {
+					runtime.markSourceFailed(source.sourceId);
+					propagateRuntimeSourceFailures(nodes, runtime);
+					return {
+						success: false,
+						error: includeSourceFailureChain(fallback.error, source.sourceId, runtime)
+					};
+				}
+			}
 			continue;
 		}
 		const pathKey = serializeSchedulingPath(node.path);
@@ -1479,9 +1694,11 @@ exports.createReplayKey = createReplayKey;
 exports.defineForwardedEffectfulSchedulingNodes = defineForwardedEffectfulSchedulingNodes;
 exports.derivedRawInputKey = derivedRawInputKey;
 exports.effectfulSchedulingNodesKey = effectfulSchedulingNodesKey;
+exports.exclusiveSourceScopeKey = exclusiveSourceScopeKey;
 exports.extractRawInputFromState = extractRawInputFromState;
 exports.fillMissingSourceDefaults = fillMissingSourceDefaults;
 exports.fillMissingSourceDefaultsAsync = fillMissingSourceDefaultsAsync;
+exports.guaranteedStaticSourceIdsKey = guaranteedStaticSourceIdsKey;
 exports.hasInactiveCompletion = hasInactiveCompletion;
 exports.includeSourceFailureChain = includeSourceFailureChain;
 exports.orderDependencyNodes = orderDependencyNodes;

package/dist/dependency-runtime.d.cts

@@ -148,6 +148,36 @@ interface RuntimeNode {
     readonly success: false;
     readonly error: Message;
   } | undefined>;
+  /**
+   * Resolves this barrier's *active* dependencies once its control
+   * dependencies (see {@link RuntimeNode.requiresSourceId}) are
+   * satisfied, before the barrier itself executes.
+   *
+   * A `conditional()` resolves the selected branch here—completing an
+   * effect-free discriminator, or reading an effectful one's cached
+   * completion—and reports which completion dependencies the branch
+   * actually has and which sources it will actively provide, so the
+   * scheduler can replace the static advisory estimate with concrete
+   * edges (see issue #924).  Returning `undefined` leaves the static
+   * estimate in place; a failure aborts the pass.  The scheduler calls
+   * this at most once per pass, and never lets advisory ordering edges
+   * delay it.
+   *
+   * @since 1.3.0
+   */
+  readonly resolveBarrier?: (ctx: SchedulingBarrierContext) => Promise<{
+    readonly success: false;
+    readonly error: Message;
+  } | BarrierResolution | undefined>;
+  /**
+   * Internal marker the effectful scheduler sets on the replacement
+   * node after {@link RuntimeNode.resolveBarrier} ran: `"resolved"`
+   * edges are concrete (a cycle through them is genuine), while
+   * `"unresolvable"` keeps the advisory estimate.
+   *
+   * @since 1.3.0
+   */
+  readonly barrierResolutionState?: "resolved" | "unresolvable";
   /**
    * Source IDs that the subtree guarded by this barrier can provide.
    * Used by the demand-only pass: when any of them is demanded, the
@@ -158,6 +188,15 @@ interface RuntimeNode {
    * @since 1.3.0
    */
   readonly providesSourceIds?: ReadonlySet<symbol>;
+  /**
+   * Source IDs every selectable route through this barrier's subtree is
+   * guaranteed to provide, regardless of which branch is selected.  An
+   * enclosing barrier's resolution treats these as active provides; the
+   * rest of {@link RuntimeNode.providesSourceIds} stays merely possible.
+   *
+   * @since 1.3.0
+   */
+  readonly guaranteedProvidesSourceIds?: ReadonlySet<symbol>;
   /**
    * The source ID whose completion this barrier's preparation depends
    * on (a `conditional()` discriminator).  See
@@ -224,6 +263,29 @@ interface BarrierCompletionDependencies {
    */
   readonly demandEdges: readonly BarrierCompletionDemandEdge[];
 }
+/**
+ * The concrete dependencies a scheduling barrier reports from
+ * {@link RuntimeNode.resolveBarrier} once its selection is known.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface BarrierResolution {
+  /**
+   * The completion dependency IDs the selected subtree actually reads,
+   * minus the sources it actively provides itself.  These replace the
+   * static advisory ordering estimate with concrete edges.
+   */
+  readonly orderingDependencyIds: readonly symbol[];
+  /**
+   * The source IDs the selected subtree will actively publish: a
+   * guaranteed occurrence (an unconditional prompt or a publishable
+   * default) or one whose state already extracts a value.  These
+   * replace {@link RuntimeNode.providesSourceIds} for ordering, so a
+   * sibling consumer no longer waits for a merely possible provider.
+   */
+  readonly activeProvidesSourceIds: ReadonlySet<symbol>;
+}
 /**
  * Options for resolving matched derived source values.
  *
@@ -524,6 +586,35 @@ declare const sourceCollectionExpansionKey: unique symbol;
  * @since 1.3.0
  */
 declare const staticSourceScopeKey: unique symbol;
+/**
+ * Static child parsers reachable only through a mutually exclusive
+ * selection, such as `or()` alternatives, a `conditional()`'s branches,
+ * or a `command()`'s inner parser.
+ *
+ * The walk unions sources and completion dependencies from this scope
+ * exactly like {@link staticSourceScopeKey}, but a source occurrence
+ * reached through an exclusive edge is never a *guaranteed* provider:
+ * the run may select a sibling instead, so a scheduling barrier must not
+ * assume the occurrence will publish.  See issue #924.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare const exclusiveSourceScopeKey: unique symbol;
+/**
+ * Source IDs a parser guarantees to provide on every successful route
+ * through it, regardless of which internal alternative is selected.
+ *
+ * A `conditional()` installs the intersection of its branches' guaranteed
+ * provides here (including the default branch when present), so an outer
+ * scheduling barrier can treat a source that *every* selectable route
+ * publishes as guaranteed even though each individual branch edge is
+ * exclusive.  See issue #924.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare const guaranteedStaticSourceIdsKey: unique symbol;
 /**
  * Forwards effectful scheduling through a shape-preserving wrapper such
  * as `map()`, `optional()`, `withDefault()`, or `nonEmpty()`, so the
@@ -767,4 +858,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-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 };
+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 };

package/dist/dependency-runtime.d.ts

@@ -148,6 +148,36 @@ interface RuntimeNode {
     readonly success: false;
     readonly error: Message;
   } | undefined>;
+  /**
+   * Resolves this barrier's *active* dependencies once its control
+   * dependencies (see {@link RuntimeNode.requiresSourceId}) are
+   * satisfied, before the barrier itself executes.
+   *
+   * A `conditional()` resolves the selected branch here—completing an
+   * effect-free discriminator, or reading an effectful one's cached
+   * completion—and reports which completion dependencies the branch
+   * actually has and which sources it will actively provide, so the
+   * scheduler can replace the static advisory estimate with concrete
+   * edges (see issue #924).  Returning `undefined` leaves the static
+   * estimate in place; a failure aborts the pass.  The scheduler calls
+   * this at most once per pass, and never lets advisory ordering edges
+   * delay it.
+   *
+   * @since 1.3.0
+   */
+  readonly resolveBarrier?: (ctx: SchedulingBarrierContext) => Promise<{
+    readonly success: false;
+    readonly error: Message;
+  } | BarrierResolution | undefined>;
+  /**
+   * Internal marker the effectful scheduler sets on the replacement
+   * node after {@link RuntimeNode.resolveBarrier} ran: `"resolved"`
+   * edges are concrete (a cycle through them is genuine), while
+   * `"unresolvable"` keeps the advisory estimate.
+   *
+   * @since 1.3.0
+   */
+  readonly barrierResolutionState?: "resolved" | "unresolvable";
   /**
    * Source IDs that the subtree guarded by this barrier can provide.
    * Used by the demand-only pass: when any of them is demanded, the
@@ -158,6 +188,15 @@ interface RuntimeNode {
    * @since 1.3.0
    */
   readonly providesSourceIds?: ReadonlySet<symbol>;
+  /**
+   * Source IDs every selectable route through this barrier's subtree is
+   * guaranteed to provide, regardless of which branch is selected.  An
+   * enclosing barrier's resolution treats these as active provides; the
+   * rest of {@link RuntimeNode.providesSourceIds} stays merely possible.
+   *
+   * @since 1.3.0
+   */
+  readonly guaranteedProvidesSourceIds?: ReadonlySet<symbol>;
   /**
    * The source ID whose completion this barrier's preparation depends
    * on (a `conditional()` discriminator).  See
@@ -224,6 +263,29 @@ interface BarrierCompletionDependencies {
    */
   readonly demandEdges: readonly BarrierCompletionDemandEdge[];
 }
+/**
+ * The concrete dependencies a scheduling barrier reports from
+ * {@link RuntimeNode.resolveBarrier} once its selection is known.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface BarrierResolution {
+  /**
+   * The completion dependency IDs the selected subtree actually reads,
+   * minus the sources it actively provides itself.  These replace the
+   * static advisory ordering estimate with concrete edges.
+   */
+  readonly orderingDependencyIds: readonly symbol[];
+  /**
+   * The source IDs the selected subtree will actively publish: a
+   * guaranteed occurrence (an unconditional prompt or a publishable
+   * default) or one whose state already extracts a value.  These
+   * replace {@link RuntimeNode.providesSourceIds} for ordering, so a
+   * sibling consumer no longer waits for a merely possible provider.
+   */
+  readonly activeProvidesSourceIds: ReadonlySet<symbol>;
+}
 /**
  * Options for resolving matched derived source values.
  *
@@ -524,6 +586,35 @@ declare const sourceCollectionExpansionKey: unique symbol;
  * @since 1.3.0
  */
 declare const staticSourceScopeKey: unique symbol;
+/**
+ * Static child parsers reachable only through a mutually exclusive
+ * selection, such as `or()` alternatives, a `conditional()`'s branches,
+ * or a `command()`'s inner parser.
+ *
+ * The walk unions sources and completion dependencies from this scope
+ * exactly like {@link staticSourceScopeKey}, but a source occurrence
+ * reached through an exclusive edge is never a *guaranteed* provider:
+ * the run may select a sibling instead, so a scheduling barrier must not
+ * assume the occurrence will publish.  See issue #924.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare const exclusiveSourceScopeKey: unique symbol;
+/**
+ * Source IDs a parser guarantees to provide on every successful route
+ * through it, regardless of which internal alternative is selected.
+ *
+ * A `conditional()` installs the intersection of its branches' guaranteed
+ * provides here (including the default branch when present), so an outer
+ * scheduling barrier can treat a source that *every* selectable route
+ * publishes as guaranteed even though each individual branch edge is
+ * exclusive.  See issue #924.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare const guaranteedStaticSourceIdsKey: unique symbol;
 /**
  * Forwards effectful scheduling through a shape-preserving wrapper such
  * as `map()`, `optional()`, `withDefault()`, or `nonEmpty()`, so the
@@ -767,4 +858,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-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 };
+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 };