@optique/core 1.3.0-dev.2581 → 1.3.0-dev.2582

package/dist/constructs.cjs

@@ -115,18 +115,23 @@ const preExpandedBranchNodes = /* @__PURE__ */ new WeakSet();
 * numeric path segments and record states use their field keys, matching
 * the paths that child completion (and parse-time tracing) uses.
 */
-function expandEffectfulRuntimeNodes(nodes) {
+function expandEffectfulRuntimeNodes(nodes, options) {
 	const expanded = [];
 	const visit = (node) => {
 		const meta = node.parser.dependencyMetadata;
+		const optedIntoCollection = node.parser[require_dependency_runtime.sourceCollectionExpansionKey] === true;
+		if (options?.structuralOnly === true && !optedIntoCollection && require_dependency_runtime.exclusiveSourceScopeKey in node.parser) {
+			expanded.push(node);
+			return;
+		}
 		const schedulingNodes = node.parser[require_dependency_runtime.effectfulSchedulingNodesKey];
-		const expandsThroughHook = schedulingNodes != null && meta?.derived == null && node.parser[require_dependency_runtime.sourceCollectionExpansionKey] === true;
+		const expandsThroughHook = schedulingNodes != null && meta?.derived == null && optedIntoCollection;
 		if (!expandsThroughHook && (meta?.source?.completeSource != null || meta?.derived != null)) {
 			expanded.push(node);
 			return;
 		}
 		if (schedulingNodes != null) {
-			const children = schedulingNodes(node.state, node.path);
+			const children = schedulingNodes(node.state, node.path, options);
 			if (children.length === 0 && meta?.source != null) {
 				expanded.push(node);
 				return;
@@ -145,10 +150,16 @@ function expandEffectfulRuntimeNodes(nodes) {
 			if (duplicateFieldNames.has(field)) continue;
 			const segment = Array.isArray(state) && typeof field === "string" ? Number(field) : field;
 			const childState = Array.isArray(state) ? state[segment] : state[field];
+			const annotatedChildState = require_annotation_state.getWrappedChildState(state, childState, childParser);
+			const isDerived = childParser.dependencyMetadata?.derived != null;
+			const rawInput = isDerived ? require_dependency_runtime.extractRawInputFromState(annotatedChildState) : void 0;
+			const defaultDependencyValues = isDerived ? require_dependency_runtime.getDefaultDependencySnapshot(annotatedChildState) : void 0;
 			visit({
 				path: [...node.path, segment],
 				parser: childParser,
-				state: require_annotation_state.getWrappedChildState(state, childState, childParser)
+				state: annotatedChildState,
+				...rawInput != null ? { rawInput } : {},
+				...defaultDependencyValues != null ? { defaultDependencyValues } : {}
 			});
 		}
 	};
@@ -173,15 +184,101 @@ function expandSourceCollectionNodes(nodes) {
 	for (let i = 0; i < nodes.length; i++) {
 		const node = nodes[i];
 		const optedIn = node.parser[require_dependency_runtime.sourceCollectionExpansionKey] === true;
-		if (!optedIn) {
+		if (optedIn) {
+			if (expanded == null) expanded = nodes.slice(0, i);
+			expanded.push(...expandEffectfulRuntimeNodes([node]));
+			continue;
+		}
+		const nested = nestedCommandLineSourceNodes(node);
+		if (nested.length < 1) {
 			expanded?.push(node);
 			continue;
 		}
 		if (expanded == null) expanded = nodes.slice(0, i);
-		expanded.push(...expandEffectfulRuntimeNodes([node]));
+		expanded.push(node, ...nested);
 	}
 	return expanded ?? nodes;
 }
+/**
+* The command-line source occurrences a structural child contributes to
+* its enclosing construct's collection scope.
+*
+* A plain nested construct—an `object()`, `tuple()`, `concat()`,
+* `merge()`, or one of those behind a transparent wrapper—is part of the
+* enclosing declaration sequence, so a source it holds must reach a
+* consumer declared before it, exactly as a source declared directly
+* beside that consumer does.  Only occurrences that consumed
+* command-line input are contributed: an absent occurrence has no value
+* to publish, and a bound or defaulted one publishes through its own
+* construct's pre-completion, whose fallback readers and lazy defaults
+* must keep evaluating exactly once
+* (https://github.com/dahlia/optique/issues/958).
+*
+* @param node The structural child to look inside.
+* @returns The nested command-line source occurrences, in declaration
+*          order.  Empty for a child that holds none.
+*/
+function nestedCommandLineSourceNodes(node) {
+	const nested = [];
+	for (const descendant of expandEffectfulRuntimeNodes([node], { structuralOnly: true })) {
+		if (descendant === node) continue;
+		if (descendant.parser.dependencyMetadata?.source == null) continue;
+		if ((require_dependency_runtime.exclusiveSourceScopeKey in descendant.parser || descendant.parser.dependencyMetadata?.source?.exclusiveOccurrence === true) && descendant.parser[require_dependency_runtime.sourceCollectionExpansionKey] !== true) continue;
+		if (!hasCommandLineSourceInput(descendant)) continue;
+		nested.push({
+			...descendant,
+			matched: true
+		});
+	}
+	return nested;
+}
+/**
+* Whether a source occurrence's state holds no parsed input at all.
+*
+* State identity against `initialState` misses two shapes a wrapper
+* produces afresh on every parse: a repetition that matched nothing,
+* whose state is a new empty array, and a wrapper whose own initial
+* state is `undefined`, which annotation injection turns into an object
+* carrying nothing but annotation symbols.  Both look matched by
+* identity while holding nothing to publish, and neither forwards the
+* binding marker that would otherwise catch them.
+*
+* Treating an unrecognized shape as non-empty is the safe direction: the
+* occurrence is then subject to the remaining provenance checks.
+*
+* @param state The occurrence's state, already unwrapped one level.
+* @returns `true` when the state carries no parsed input.
+*/
+function isEmptySourceState(state) {
+	if (state == null) return true;
+	if (Array.isArray(state)) return state.length < 1;
+	if (typeof state !== "object") return false;
+	return Object.getOwnPropertyNames(state).length < 1;
+}
+/**
+* Whether a nested source occurrence holds a value the command line
+* supplied.
+*
+* A source that can complete from a binding (`bindEnv()`,
+* `bindConfig()`, and other `completesFromSource` wrappers) reaches an
+* annotated state even when nothing on the command line matched, so an
+* unmatched state alone does not prove provenance.  Such an occurrence
+* has to say so through its own state; otherwise extracting from it here
+* would run the binding's fallback reader in addition to the run its
+* owning construct's pre-completion already performs.
+*
+* @param node The nested source occurrence.
+* @returns `true` when the occurrence's state came from the command
+*          line, whether or not that input passed validation.
+*/
+function hasCommandLineSourceInput(node) {
+	const parser = node.parser;
+	if (!require_dependency_runtime.isMatchedState(node.state, parser)) return false;
+	const innerState = Array.isArray(node.state) && node.state.length === 1 ? node.state[0] : node.state;
+	if (isEmptySourceState(innerState)) return false;
+	if (parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] !== true) return true;
+	return innerState != null && typeof innerState === "object" && innerState.hasCliValue === true;
+}
 let conditionalInstanceCounter = 0;
 /**
 * Whether a source occurrence publishes a value even when its state
@@ -431,10 +528,11 @@ async function scheduleEffectfulSourceCompletions(nodes, state, runtime, exec, p
 	for (const node of nodes) {
 		const optedIn = node.parser[require_dependency_runtime.sourceCollectionExpansionKey] === true;
 		const preExpanded = preExpandedBranchNodes.has(node);
+		const nestedPaths = optedIn || preExpanded ? void 0 : new Set(nestedCommandLineSourceNodes(node).map((nested) => require_dependency_runtime.serializeSchedulingPath(nested.path)));
 		for (const expandedNode of expandEffectfulRuntimeNodes([node])) {
 			expandedNodes.push(expandedNode);
 			if (preExpanded) continue;
-			if (optedIn || expandedNode === node) collected.add(expandedNode);
+			if (optedIn || expandedNode === node || nestedPaths?.has(require_dependency_runtime.serializeSchedulingPath(expandedNode.path)) === true) collected.add(expandedNode);
 		}
 	}
 	const republish = exec?.republishCachedCompletions === true;
@@ -1245,6 +1343,7 @@ function composeExclusiveDependencyMetadata(parsers) {
 		...sharedSource,
 		getMissingSourceValue: void 0,
 		completesWhenMissing: false,
+		exclusiveOccurrence: true,
 		preservesSourceValue: everyBranchPreserves,
 		extractSourceValue(state) {
 			if (!Array.isArray(state) || state.length !== 2 || typeof state[0] !== "number") return void 0;
@@ -5981,6 +6080,7 @@ function group(label, parser, options = {}) {
 		...fieldParsersKey in parser ? { [fieldParsersKey]: parser[fieldParsersKey] } : {},
 		...require_dependency_runtime.effectfulSchedulingNodesKey in parser ? { [require_dependency_runtime.effectfulSchedulingNodesKey]: parser[require_dependency_runtime.effectfulSchedulingNodesKey] } : {},
 		...require_dependency_runtime.sourceCollectionExpansionKey in parser ? { [require_dependency_runtime.sourceCollectionExpansionKey]: parser[require_dependency_runtime.sourceCollectionExpansionKey] } : {},
+		...require_dependency_runtime.exclusiveSourceScopeKey in parser ? { [require_dependency_runtime.exclusiveSourceScopeKey]: parser[require_dependency_runtime.exclusiveSourceScopeKey] } : {},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
 		...typeof parser.canSkip === "function" ? { canSkip: parser.canSkip.bind(parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
@@ -6052,6 +6152,11 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true) Object.defineProperty(groupParser, require_internal_parser.unmatchedNonCliDependencySourceStateMarker, {
+		value: true,
+		configurable: true,
+		enumerable: true
+	});
 	if ("placeholder" in parser) Object.defineProperty(groupParser, "placeholder", {
 		get() {
 			return parser.placeholder;
@@ -6778,7 +6883,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		}
 		return ids;
 	};
-	const buildConditionalSchedulingNodes = (state, parentPath) => {
+	const buildConditionalSchedulingNodes = (state, parentPath, expandOptions) => {
 		if (state == null || typeof state !== "object") return [];
 		const conditionalState = state;
 		const annotatedDiscriminatorState = require_annotation_state.getWrappedChildState(conditionalState, conditionalState.discriminatorState, discriminator);
@@ -6797,7 +6902,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					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)) {
+				if (branchKey != null && options?.errors?.branchError != null) for (const expanded of wrapBranchBarrierNodes(expandEffectfulRuntimeNodes([branchNode], expandOptions), branchKey)) {
 					preExpandedBranchNodes.add(expanded);
 					nodes.push(expanded);
 				}

package/dist/constructs.js

@@ -5,7 +5,7 @@ import { message, optionName, text, values } from "./message.js";
 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, forkRuntimeForCommittedSubtree, guaranteedStaticSourceIdsKey, hasInactiveCompletion, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
+import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyRuntimeContext, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, getDefaultDependencySnapshot, guaranteedStaticSourceIdsKey, hasInactiveCompletion, isMatchedState, recordSourceScope, releaseUncollectedSourceValues, 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";
@@ -115,18 +115,23 @@ const preExpandedBranchNodes = /* @__PURE__ */ new WeakSet();
 * numeric path segments and record states use their field keys, matching
 * the paths that child completion (and parse-time tracing) uses.
 */
-function expandEffectfulRuntimeNodes(nodes) {
+function expandEffectfulRuntimeNodes(nodes, options) {
 	const expanded = [];
 	const visit = (node) => {
 		const meta = node.parser.dependencyMetadata;
+		const optedIntoCollection = node.parser[sourceCollectionExpansionKey] === true;
+		if (options?.structuralOnly === true && !optedIntoCollection && exclusiveSourceScopeKey in node.parser) {
+			expanded.push(node);
+			return;
+		}
 		const schedulingNodes = node.parser[effectfulSchedulingNodesKey];
-		const expandsThroughHook = schedulingNodes != null && meta?.derived == null && node.parser[sourceCollectionExpansionKey] === true;
+		const expandsThroughHook = schedulingNodes != null && meta?.derived == null && optedIntoCollection;
 		if (!expandsThroughHook && (meta?.source?.completeSource != null || meta?.derived != null)) {
 			expanded.push(node);
 			return;
 		}
 		if (schedulingNodes != null) {
-			const children = schedulingNodes(node.state, node.path);
+			const children = schedulingNodes(node.state, node.path, options);
 			if (children.length === 0 && meta?.source != null) {
 				expanded.push(node);
 				return;
@@ -145,10 +150,16 @@ function expandEffectfulRuntimeNodes(nodes) {
 			if (duplicateFieldNames.has(field)) continue;
 			const segment = Array.isArray(state) && typeof field === "string" ? Number(field) : field;
 			const childState = Array.isArray(state) ? state[segment] : state[field];
+			const annotatedChildState = getWrappedChildState(state, childState, childParser);
+			const isDerived = childParser.dependencyMetadata?.derived != null;
+			const rawInput = isDerived ? extractRawInputFromState(annotatedChildState) : void 0;
+			const defaultDependencyValues = isDerived ? getDefaultDependencySnapshot(annotatedChildState) : void 0;
 			visit({
 				path: [...node.path, segment],
 				parser: childParser,
-				state: getWrappedChildState(state, childState, childParser)
+				state: annotatedChildState,
+				...rawInput != null ? { rawInput } : {},
+				...defaultDependencyValues != null ? { defaultDependencyValues } : {}
 			});
 		}
 	};
@@ -173,15 +184,101 @@ function expandSourceCollectionNodes(nodes) {
 	for (let i = 0; i < nodes.length; i++) {
 		const node = nodes[i];
 		const optedIn = node.parser[sourceCollectionExpansionKey] === true;
-		if (!optedIn) {
+		if (optedIn) {
+			if (expanded == null) expanded = nodes.slice(0, i);
+			expanded.push(...expandEffectfulRuntimeNodes([node]));
+			continue;
+		}
+		const nested = nestedCommandLineSourceNodes(node);
+		if (nested.length < 1) {
 			expanded?.push(node);
 			continue;
 		}
 		if (expanded == null) expanded = nodes.slice(0, i);
-		expanded.push(...expandEffectfulRuntimeNodes([node]));
+		expanded.push(node, ...nested);
 	}
 	return expanded ?? nodes;
 }
+/**
+* The command-line source occurrences a structural child contributes to
+* its enclosing construct's collection scope.
+*
+* A plain nested construct—an `object()`, `tuple()`, `concat()`,
+* `merge()`, or one of those behind a transparent wrapper—is part of the
+* enclosing declaration sequence, so a source it holds must reach a
+* consumer declared before it, exactly as a source declared directly
+* beside that consumer does.  Only occurrences that consumed
+* command-line input are contributed: an absent occurrence has no value
+* to publish, and a bound or defaulted one publishes through its own
+* construct's pre-completion, whose fallback readers and lazy defaults
+* must keep evaluating exactly once
+* (https://github.com/dahlia/optique/issues/958).
+*
+* @param node The structural child to look inside.
+* @returns The nested command-line source occurrences, in declaration
+*          order.  Empty for a child that holds none.
+*/
+function nestedCommandLineSourceNodes(node) {
+	const nested = [];
+	for (const descendant of expandEffectfulRuntimeNodes([node], { structuralOnly: true })) {
+		if (descendant === node) continue;
+		if (descendant.parser.dependencyMetadata?.source == null) continue;
+		if ((exclusiveSourceScopeKey in descendant.parser || descendant.parser.dependencyMetadata?.source?.exclusiveOccurrence === true) && descendant.parser[sourceCollectionExpansionKey] !== true) continue;
+		if (!hasCommandLineSourceInput(descendant)) continue;
+		nested.push({
+			...descendant,
+			matched: true
+		});
+	}
+	return nested;
+}
+/**
+* Whether a source occurrence's state holds no parsed input at all.
+*
+* State identity against `initialState` misses two shapes a wrapper
+* produces afresh on every parse: a repetition that matched nothing,
+* whose state is a new empty array, and a wrapper whose own initial
+* state is `undefined`, which annotation injection turns into an object
+* carrying nothing but annotation symbols.  Both look matched by
+* identity while holding nothing to publish, and neither forwards the
+* binding marker that would otherwise catch them.
+*
+* Treating an unrecognized shape as non-empty is the safe direction: the
+* occurrence is then subject to the remaining provenance checks.
+*
+* @param state The occurrence's state, already unwrapped one level.
+* @returns `true` when the state carries no parsed input.
+*/
+function isEmptySourceState(state) {
+	if (state == null) return true;
+	if (Array.isArray(state)) return state.length < 1;
+	if (typeof state !== "object") return false;
+	return Object.getOwnPropertyNames(state).length < 1;
+}
+/**
+* Whether a nested source occurrence holds a value the command line
+* supplied.
+*
+* A source that can complete from a binding (`bindEnv()`,
+* `bindConfig()`, and other `completesFromSource` wrappers) reaches an
+* annotated state even when nothing on the command line matched, so an
+* unmatched state alone does not prove provenance.  Such an occurrence
+* has to say so through its own state; otherwise extracting from it here
+* would run the binding's fallback reader in addition to the run its
+* owning construct's pre-completion already performs.
+*
+* @param node The nested source occurrence.
+* @returns `true` when the occurrence's state came from the command
+*          line, whether or not that input passed validation.
+*/
+function hasCommandLineSourceInput(node) {
+	const parser = node.parser;
+	if (!isMatchedState(node.state, parser)) return false;
+	const innerState = Array.isArray(node.state) && node.state.length === 1 ? node.state[0] : node.state;
+	if (isEmptySourceState(innerState)) return false;
+	if (parser[unmatchedNonCliDependencySourceStateMarker] !== true) return true;
+	return innerState != null && typeof innerState === "object" && innerState.hasCliValue === true;
+}
 let conditionalInstanceCounter = 0;
 /**
 * Whether a source occurrence publishes a value even when its state
@@ -431,10 +528,11 @@ async function scheduleEffectfulSourceCompletions(nodes, state, runtime, exec, p
 	for (const node of nodes) {
 		const optedIn = node.parser[sourceCollectionExpansionKey] === true;
 		const preExpanded = preExpandedBranchNodes.has(node);
+		const nestedPaths = optedIn || preExpanded ? void 0 : new Set(nestedCommandLineSourceNodes(node).map((nested) => serializeSchedulingPath(nested.path)));
 		for (const expandedNode of expandEffectfulRuntimeNodes([node])) {
 			expandedNodes.push(expandedNode);
 			if (preExpanded) continue;
-			if (optedIn || expandedNode === node) collected.add(expandedNode);
+			if (optedIn || expandedNode === node || nestedPaths?.has(serializeSchedulingPath(expandedNode.path)) === true) collected.add(expandedNode);
 		}
 	}
 	const republish = exec?.republishCachedCompletions === true;
@@ -1245,6 +1343,7 @@ function composeExclusiveDependencyMetadata(parsers) {
 		...sharedSource,
 		getMissingSourceValue: void 0,
 		completesWhenMissing: false,
+		exclusiveOccurrence: true,
 		preservesSourceValue: everyBranchPreserves,
 		extractSourceValue(state) {
 			if (!Array.isArray(state) || state.length !== 2 || typeof state[0] !== "number") return void 0;
@@ -5981,6 +6080,7 @@ function group(label, parser, options = {}) {
 		...fieldParsersKey in parser ? { [fieldParsersKey]: parser[fieldParsersKey] } : {},
 		...effectfulSchedulingNodesKey in parser ? { [effectfulSchedulingNodesKey]: parser[effectfulSchedulingNodesKey] } : {},
 		...sourceCollectionExpansionKey in parser ? { [sourceCollectionExpansionKey]: parser[sourceCollectionExpansionKey] } : {},
+		...exclusiveSourceScopeKey in parser ? { [exclusiveSourceScopeKey]: parser[exclusiveSourceScopeKey] } : {},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
 		...typeof parser.canSkip === "function" ? { canSkip: parser.canSkip.bind(parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
@@ -6052,6 +6152,11 @@ function group(label, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	if (parser[unmatchedNonCliDependencySourceStateMarker] === true) Object.defineProperty(groupParser, unmatchedNonCliDependencySourceStateMarker, {
+		value: true,
+		configurable: true,
+		enumerable: true
+	});
 	if ("placeholder" in parser) Object.defineProperty(groupParser, "placeholder", {
 		get() {
 			return parser.placeholder;
@@ -6778,7 +6883,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		}
 		return ids;
 	};
-	const buildConditionalSchedulingNodes = (state, parentPath) => {
+	const buildConditionalSchedulingNodes = (state, parentPath, expandOptions) => {
 		if (state == null || typeof state !== "object") return [];
 		const conditionalState = state;
 		const annotatedDiscriminatorState = getWrappedChildState(conditionalState, conditionalState.discriminatorState, discriminator);
@@ -6797,7 +6902,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 					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)) {
+				if (branchKey != null && options?.errors?.branchError != null) for (const expanded of wrapBranchBarrierNodes(expandEffectfulRuntimeNodes([branchNode], expandOptions), branchKey)) {
 					preExpandedBranchNodes.add(expanded);
 					nodes.push(expanded);
 				}

package/dist/dependency-metadata.d.cts

@@ -73,6 +73,21 @@ interface DependencySourceCapability {
    * @since 1.3.0
    */
   readonly completesWhenMissing?: boolean;
+  /**
+   * Whether this capability publishes whichever mutually exclusive
+   * alternative the run selected, rather than an occurrence of its own.
+   *
+   * An `or()`/`longestMatch()` whose alternatives share one source
+   * composes such a capability.  The alternative is a scope of its own,
+   * so an enclosing construct's explicit source collection leaves it
+   * alone unless the exclusive parser opted into collection.  Wrappers
+   * compose source capabilities by spreading them, so the flag travels
+   * through `optional()`, `withDefault()`, `map()`, and `multiple()`
+   * without each having to forward it.
+   *
+   * @since 1.3.0
+   */
+  readonly exclusiveOccurrence?: boolean;
   /**
    * Whether the parser's output value is the actual dependency source value.
    * `false` when a transform like `map()` has been applied.

package/dist/dependency-metadata.d.ts

@@ -73,6 +73,21 @@ interface DependencySourceCapability {
    * @since 1.3.0
    */
   readonly completesWhenMissing?: boolean;
+  /**
+   * Whether this capability publishes whichever mutually exclusive
+   * alternative the run selected, rather than an occurrence of its own.
+   *
+   * An `or()`/`longestMatch()` whose alternatives share one source
+   * composes such a capability.  The alternative is a scope of its own,
+   * so an enclosing construct's explicit source collection leaves it
+   * alone unless the exclusive parser opted into collection.  Wrappers
+   * compose source capabilities by spreading them, so the flag travels
+   * through `optional()`, `withDefault()`, `map()`, and `multiple()`
+   * without each having to forward it.
+   *
+   * @since 1.3.0
+   */
+  readonly exclusiveOccurrence?: boolean;
   /**
    * Whether the parser's output value is the actual dependency source value.
    * `false` when a transform like `map()` has been applied.

package/dist/dependency-runtime.cjs

@@ -1850,6 +1850,13 @@ async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE_
 /**
 * Determines whether a parser state represents an explicit match (the user
 * provided input) rather than an initial/pending state.
+*
+* @param fieldState The parser's state.
+* @param parser The parser owning that state.
+* @returns `true` when the state reflects command-line input, whether or
+*          not that input passed validation.
+* @internal
+* @since 1.3.0
 */
 function isMatchedState(fieldState, parser) {
 	if (fieldState === void 0) return false;
@@ -1922,6 +1929,18 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 	}
 	return nodes;
 }
+/**
+* Reads a derived parser state's snapshotted default dependency values.
+*
+* Nodes must carry the parse-time snapshot so replay never re-evaluates a
+* dynamic `getDefaultDependencyValues()` thunk.
+*
+* @param state The derived parser's state.
+* @returns The snapshotted values, or `undefined` when the state carries
+*          none.
+* @internal
+* @since 1.3.0
+*/
 function getDefaultDependencySnapshot(state) {
 	return getDefaultDependencySnapshotInner(state, /* @__PURE__ */ new Set());
 }
@@ -1965,9 +1984,11 @@ exports.extractRawInputFromState = extractRawInputFromState;
 exports.fillMissingSourceDefaults = fillMissingSourceDefaults;
 exports.fillMissingSourceDefaultsAsync = fillMissingSourceDefaultsAsync;
 exports.forkRuntimeForCommittedSubtree = forkRuntimeForCommittedSubtree;
+exports.getDefaultDependencySnapshot = getDefaultDependencySnapshot;
 exports.guaranteedStaticSourceIdsKey = guaranteedStaticSourceIdsKey;
 exports.hasInactiveCompletion = hasInactiveCompletion;
 exports.includeSourceFailureChain = includeSourceFailureChain;
+exports.isMatchedState = isMatchedState;
 exports.orderDependencyNodes = orderDependencyNodes;
 exports.recordDerivedRawInput = recordDerivedRawInput;
 exports.recordSourceScope = recordSourceScope;

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 { EffectfulCompletionSession, ExecutionContext } from "./internal/parser.cjs";
+import { EffectfulCompletionSession, ExecutionContext, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.cjs";
 
 //#region src/dependency-runtime.d.ts
 
@@ -612,13 +612,29 @@ declare function extractRawInputFromState(state: unknown): string | undefined;
  * @since 1.3.0
  */
 declare const effectfulSchedulingNodesKey: unique symbol;
+/**
+ * Options that steer how far a runtime-node expansion walks.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface ExpandRuntimeNodesOptions {
+  /**
+   * Stops the walk at an exclusive parser—an `or()`, `longestMatch()`, or
+   * `conditional()` alternative—that has not opted into source
+   * collection, so a scope of its own is not folded into the enclosing
+   * one.  A hook that expands descendants itself must forward this to
+   * its own expansion.
+   */
+  readonly structuralOnly?: boolean;
+}
 /**
  * The shape of the {@link effectfulSchedulingNodesKey} hook.
  *
  * @internal
  * @since 1.3.0
  */
-type EffectfulSchedulingNodesFn = (state: unknown, parentPath: readonly PropertyKey[] | undefined) => readonly RuntimeNode[];
+type EffectfulSchedulingNodesFn = (state: unknown, parentPath: readonly PropertyKey[] | undefined, options?: ExpandRuntimeNodesOptions) => readonly RuntimeNode[];
 /**
  * Opt-in marker for parsers whose {@link effectfulSchedulingNodesKey}
  * hook also defines their explicit-source *collection* scope.
@@ -929,6 +945,22 @@ declare function resolveStateWithRuntime(state: unknown, runtime: DependencyRunt
  * @since 1.0.0
  */
 declare function resolveStateWithRuntimeAsync(state: unknown, runtime: DependencyRuntimeContext): Promise<unknown>;
+/**
+ * Determines whether a parser state represents an explicit match (the user
+ * provided input) rather than an initial/pending state.
+ *
+ * @param fieldState The parser's state.
+ * @param parser The parser owning that state.
+ * @returns `true` when the state reflects command-line input, whether or
+ *          not that input passed validation.
+ * @internal
+ * @since 1.3.0
+ */
+declare function isMatchedState(fieldState: unknown, parser: {
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+  readonly initialState?: unknown;
+  readonly [unmatchedNonCliDependencySourceStateMarker]?: true;
+}): boolean;
 /**
  * Builds {@link RuntimeNode}s from field→parser pairs and a state record.
  *
@@ -961,5 +993,18 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly dependencyMetadata?: ParserDependencyMetadata;
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
+/**
+ * Reads a derived parser state's snapshotted default dependency values.
+ *
+ * Nodes must carry the parse-time snapshot so replay never re-evaluates a
+ * dynamic `getDefaultDependencyValues()` thunk.
+ *
+ * @param state The derived parser's state.
+ * @returns The snapshotted values, or `undefined` when the state carries
+ *          none.
+ * @internal
+ * @since 1.3.0
+ */
+declare function getDefaultDependencySnapshot(state: unknown): readonly unknown[] | undefined;
 //#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, forkRuntimeForCommittedSubtree, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ExpandRuntimeNodesOptions, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, getDefaultDependencySnapshot, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, isMatchedState, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, 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 { EffectfulCompletionSession, ExecutionContext } from "./internal/parser.js";
+import { EffectfulCompletionSession, ExecutionContext, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 
 //#region src/dependency-runtime.d.ts
 
@@ -612,13 +612,29 @@ declare function extractRawInputFromState(state: unknown): string | undefined;
  * @since 1.3.0
  */
 declare const effectfulSchedulingNodesKey: unique symbol;
+/**
+ * Options that steer how far a runtime-node expansion walks.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface ExpandRuntimeNodesOptions {
+  /**
+   * Stops the walk at an exclusive parser—an `or()`, `longestMatch()`, or
+   * `conditional()` alternative—that has not opted into source
+   * collection, so a scope of its own is not folded into the enclosing
+   * one.  A hook that expands descendants itself must forward this to
+   * its own expansion.
+   */
+  readonly structuralOnly?: boolean;
+}
 /**
  * The shape of the {@link effectfulSchedulingNodesKey} hook.
  *
  * @internal
  * @since 1.3.0
  */
-type EffectfulSchedulingNodesFn = (state: unknown, parentPath: readonly PropertyKey[] | undefined) => readonly RuntimeNode[];
+type EffectfulSchedulingNodesFn = (state: unknown, parentPath: readonly PropertyKey[] | undefined, options?: ExpandRuntimeNodesOptions) => readonly RuntimeNode[];
 /**
  * Opt-in marker for parsers whose {@link effectfulSchedulingNodesKey}
  * hook also defines their explicit-source *collection* scope.
@@ -929,6 +945,22 @@ declare function resolveStateWithRuntime(state: unknown, runtime: DependencyRunt
  * @since 1.0.0
  */
 declare function resolveStateWithRuntimeAsync(state: unknown, runtime: DependencyRuntimeContext): Promise<unknown>;
+/**
+ * Determines whether a parser state represents an explicit match (the user
+ * provided input) rather than an initial/pending state.
+ *
+ * @param fieldState The parser's state.
+ * @param parser The parser owning that state.
+ * @returns `true` when the state reflects command-line input, whether or
+ *          not that input passed validation.
+ * @internal
+ * @since 1.3.0
+ */
+declare function isMatchedState(fieldState: unknown, parser: {
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+  readonly initialState?: unknown;
+  readonly [unmatchedNonCliDependencySourceStateMarker]?: true;
+}): boolean;
 /**
  * Builds {@link RuntimeNode}s from field→parser pairs and a state record.
  *
@@ -961,5 +993,18 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly dependencyMetadata?: ParserDependencyMetadata;
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
+/**
+ * Reads a derived parser state's snapshotted default dependency values.
+ *
+ * Nodes must carry the parse-time snapshot so replay never re-evaluates a
+ * dynamic `getDefaultDependencyValues()` thunk.
+ *
+ * @param state The derived parser's state.
+ * @returns The snapshotted values, or `undefined` when the state carries
+ *          none.
+ * @internal
+ * @since 1.3.0
+ */
+declare function getDefaultDependencySnapshot(state: unknown): readonly unknown[] | undefined;
 //#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, forkRuntimeForCommittedSubtree, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ExpandRuntimeNodesOptions, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, getDefaultDependencySnapshot, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, isMatchedState, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.js

@@ -1850,6 +1850,13 @@ async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE_
 /**
 * Determines whether a parser state represents an explicit match (the user
 * provided input) rather than an initial/pending state.
+*
+* @param fieldState The parser's state.
+* @param parser The parser owning that state.
+* @returns `true` when the state reflects command-line input, whether or
+*          not that input passed validation.
+* @internal
+* @since 1.3.0
 */
 function isMatchedState(fieldState, parser) {
 	if (fieldState === void 0) return false;
@@ -1922,6 +1929,18 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 	}
 	return nodes;
 }
+/**
+* Reads a derived parser state's snapshotted default dependency values.
+*
+* Nodes must carry the parse-time snapshot so replay never re-evaluates a
+* dynamic `getDefaultDependencyValues()` thunk.
+*
+* @param state The derived parser's state.
+* @returns The snapshotted values, or `undefined` when the state carries
+*          none.
+* @internal
+* @since 1.3.0
+*/
 function getDefaultDependencySnapshot(state) {
 	return getDefaultDependencySnapshotInner(state, /* @__PURE__ */ new Set());
 }
@@ -1947,4 +1966,4 @@ function getDefaultDependencySnapshotInner(state, visited) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, 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, forkRuntimeForCommittedSubtree, getDefaultDependencySnapshot, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, isMatchedState, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, 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.2581",
+  "version": "1.3.0-dev.2582",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2581+50dd484c",
+    "@optique/env": "1.3.0-dev.2582+e069abd2",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",