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

package/dist/dependency-runtime.js

@@ -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: 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);
@@ -1466,4 +1681,4 @@ function getDefaultDependencySnapshotInner(state, visited) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+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 };

package/dist/internal/parser.cjs

@@ -26,7 +26,8 @@ function createEffectfulCompletionSession(policy = "eager") {
 		demanded: /* @__PURE__ */ new Set(),
 		effectfulSources: /* @__PURE__ */ new Set(),
 		completedByPath: /* @__PURE__ */ new Map(),
-		preparedByPath: /* @__PURE__ */ new Map()
+		preparedByPath: /* @__PURE__ */ new Map(),
+		missingDefaultsByOccurrence: /* @__PURE__ */ new WeakMap()
 	};
 }
 /**

package/dist/internal/parser.d.cts

@@ -480,6 +480,22 @@ interface EffectfulCompletionSession {
    * re-completing the discriminator or re-selecting a branch.
    */
   readonly preparedByPath: Map<string, unknown>;
+  /**
+   * Missing-value default results published for structural source
+   * occurrences inside a scheduling barrier's nested pass, keyed by the
+   * occurrence's composed `getMissingSourceValue` function.  The
+   * function identifies the exact wrapper instance, so two branches of
+   * a `conditional()` sharing a node path never observe each other's
+   * defaults even when a phase-two binding changes the selection
+   * between passes.  Unlike {@link completedByPath} this cache is
+   * shared across the passes of a run: a default does not depend on
+   * pass-specific state, so caching it keeps a non-idempotent
+   * `withDefault()` thunk at one evaluation per run even when the
+   * nested pass repeats.
+   *
+   * @since 1.3.0
+   */
+  readonly missingDefaultsByOccurrence: WeakMap<object, ValueParserResult<unknown>>;
 }
 /**
  * Creates a fresh {@link EffectfulCompletionSession}.

package/dist/internal/parser.d.ts

@@ -480,6 +480,22 @@ interface EffectfulCompletionSession {
    * re-completing the discriminator or re-selecting a branch.
    */
   readonly preparedByPath: Map<string, unknown>;
+  /**
+   * Missing-value default results published for structural source
+   * occurrences inside a scheduling barrier's nested pass, keyed by the
+   * occurrence's composed `getMissingSourceValue` function.  The
+   * function identifies the exact wrapper instance, so two branches of
+   * a `conditional()` sharing a node path never observe each other's
+   * defaults even when a phase-two binding changes the selection
+   * between passes.  Unlike {@link completedByPath} this cache is
+   * shared across the passes of a run: a default does not depend on
+   * pass-specific state, so caching it keeps a non-idempotent
+   * `withDefault()` thunk at one evaluation per run even when the
+   * nested pass repeats.
+   *
+   * @since 1.3.0
+   */
+  readonly missingDefaultsByOccurrence: WeakMap<object, ValueParserResult<unknown>>;
 }
 /**
  * Creates a fresh {@link EffectfulCompletionSession}.

package/dist/internal/parser.js

@@ -26,7 +26,8 @@ function createEffectfulCompletionSession(policy = "eager") {
 		demanded: /* @__PURE__ */ new Set(),
 		effectfulSources: /* @__PURE__ */ new Set(),
 		completedByPath: /* @__PURE__ */ new Map(),
-		preparedByPath: /* @__PURE__ */ new Map()
+		preparedByPath: /* @__PURE__ */ new Map(),
+		missingDefaultsByOccurrence: /* @__PURE__ */ new WeakMap()
 	};
 }
 /**

package/dist/primitives.cjs

@@ -1731,7 +1731,7 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
-	Object.defineProperty(result, require_dependency_runtime.staticSourceScopeKey, {
+	Object.defineProperty(result, require_dependency_runtime.exclusiveSourceScopeKey, {
 		value: [parser],
 		configurable: true,
 		enumerable: false

package/dist/primitives.js

@@ -4,7 +4,7 @@ import { validateCommandNames, validateOptionNames } from "./validate.js";
 import { extractOptionNames, isDocHidden, isSuggestionHidden } from "./usage.js";
 import { dispatchByMode, dispatchIterableByMode, wrapForMode } from "./internal/mode-dispatch.js";
 import { getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDerivedValueParser, suggestWithDependency } from "./internal/dependency.js";
-import { effectfulSchedulingNodesKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
+import { effectfulSchedulingNodesKey, exclusiveSourceScopeKey, includeSourceFailureChain, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, sourceCollectionExpansionKey } from "./dependency-runtime.js";
 import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedInitialState, normalizeInjectedAnnotationState } from "./annotation-state.js";
 import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
@@ -1731,7 +1731,7 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
-	Object.defineProperty(result, staticSourceScopeKey, {
+	Object.defineProperty(result, exclusiveSourceScopeKey, {
 		value: [parser],
 		configurable: true,
 		enumerable: false

package/package.json

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