@optique/core 1.3.0-dev.2387 → 1.3.0-dev.2390

package/dist/dependency-runtime.cjs

@@ -494,6 +494,41 @@ function extractRawInputFromState(state) {
 */
 const effectfulSchedulingNodesKey = Symbol("@optique/core/dependency-runtime/effectfulSchedulingNodes");
 /**
+* Opt-in marker for parsers whose {@link effectfulSchedulingNodesKey}
+* hook also defines their explicit-source *collection* scope.
+*
+* A parent construct normally collects explicit source values from its
+* direct children only.  A parser carrying this marker (with value
+* `true`) asks the parent to expand it through its scheduling hook
+* before collecting, so command-line source values inside it—such as a
+* `conditional()` discriminator, a committed conditional branch, or a
+* selected `command()` subtree—register into the parent's dependency
+* runtime exactly like a prompt-completed value would.  Constructs
+* without the marker (plain nested `object()`, uncommitted exclusive
+* branches) keep their existing scope.
+*
+* @internal
+* @since 1.3.0
+*/
+const sourceCollectionExpansionKey = Symbol("@optique/core/dependency-runtime/sourceCollectionExpansion");
+/**
+* Static child parsers reachable for dependency-source estimation.
+*
+* `collectStaticSourceIds()` walks flattened field pairs, which stops at
+* parsers whose children are not field-shaped—a `command()`'s inner
+* parser, a nested `conditional()`'s branches, exclusive alternatives,
+* or a transparent wrapper's inner construct.  Such parsers expose their
+* children here so the walk can estimate every source a subtree may
+* provide.  The estimate feeds demand-only control dependencies, where
+* an overcount merely completes a discriminator earlier than strictly
+* needed, while an undercount delays an effectful completion to the
+* final pass and starves phase-two contexts of seed values.
+*
+* @internal
+* @since 1.3.0
+*/
+const staticSourceScopeKey = Symbol("@optique/core/dependency-runtime/staticSourceScope");
+/**
 * 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
@@ -511,6 +546,11 @@ const effectfulSchedulingNodesKey = Symbol("@optique/core/dependency-runtime/eff
 * @since 1.3.0
 */
 function defineForwardedEffectfulSchedulingNodes(wrapper, inner, adaptState) {
+	Object.defineProperty(wrapper, staticSourceScopeKey, {
+		value: [inner],
+		configurable: true,
+		enumerable: false
+	});
 	if (inner.dependencyMetadata?.source != null) return;
 	Object.defineProperty(wrapper, effectfulSchedulingNodesKey, {
 		value: ((state, parentPath) => [{
@@ -521,6 +561,11 @@ function defineForwardedEffectfulSchedulingNodes(wrapper, inner, adaptState) {
 		configurable: true,
 		enumerable: false
 	});
+	if (inner[sourceCollectionExpansionKey] === true) Object.defineProperty(wrapper, sourceCollectionExpansionKey, {
+		value: true,
+		configurable: true,
+		enumerable: false
+	});
 }
 /**
 * Collects the dependency source IDs demanded by consumers among the
@@ -570,12 +615,12 @@ function collectDeferredDemand(state, demanded, visited) {
 *
 * - Runs only during real completion (`exec.phase === "complete"`); probe
 *   and suggest phases return immediately without effects.
-* - Precedence is structural: a source whose value was registered before
-*   the pass begins (from CLI state, environment, configuration, or a
-*   default) or that has already failed is never completed effectfully.
-*   When several scheduled occurrences share one source, each occurrence
-*   still completes and re-registers, so the last occurrence wins—the
-*   same rule as repeated command-line source occurrences.
+* - Precedence is structural per occurrence: an effectful completion
+*   returns its own field's command-line or bound value without running
+*   the effect, and structural occurrences re-register their extracted
+*   values in declaration order.  When several scheduled occurrences
+*   share one source, the last occurrence wins—the same rule as repeated
+*   command-line source occurrences.
 * - Completion results that are `undefined` or marked `deferred` are
 *   treated as declined and neither registered nor cached.
 * - A successful result registers its value unless the value is
@@ -618,6 +663,19 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 		const demandNodes = options?.demandNodes ?? nodes;
 		const demanded = collectDemandedDependencyIds(demandNodes, state, exec.trace);
 		for (const id of demanded) session.demanded.add(id);
+		let demandAdded = true;
+		while (demandAdded) {
+			demandAdded = false;
+			for (const node of nodes) {
+				if (node.requiresSourceId == null || node.providesSourceIds == null) continue;
+				if (session.demanded.has(node.requiresSourceId)) continue;
+				for (const provided of node.providesSourceIds) if (session.demanded.has(provided)) {
+					session.demanded.add(node.requiresSourceId);
+					demandAdded = true;
+					break;
+				}
+			}
+		}
 	}
 	if (session != null) {
 		for (const result of session.results.values()) if (!result.success) return {
@@ -625,14 +683,28 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 			error: result.error
 		};
 	}
-	const schedulable = nodes.filter((node) => node.parser.dependencyMetadata?.source?.completeSource != null);
-	if (schedulable.length === 0) return empty;
+	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 nodes) {
+		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)
+			});
+			if (barrierFailure != null) return barrierFailure;
+			continue;
+		}
 		const source = node.parser.dependencyMetadata?.source;
 		if (source == null) continue;
 		if (source.completeSource == null) {
-			if (source.extractSourceValue == null || (options?.isReusable?.(node) ?? true) === false) continue;
+			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);
 			continue;
@@ -676,7 +748,12 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 }
 /**
 * Serializes a scheduling node path into a stable string key, using
-* length-prefixed segments so no separator escaping is needed.
+* length-prefixed segments so no separator escaping is needed.  Shared
+* with constructs that key run-scoped session entries by path (e.g.,
+* `conditional()`'s prepared branch selections).
+*
+* @internal
+* @since 1.3.0
 */
 function serializeSchedulingPath(path) {
 	return path.map(serializePathSegment).join("");
@@ -939,4 +1016,7 @@ exports.fillMissingSourceDefaultsAsync = fillMissingSourceDefaultsAsync;
 exports.replayDerivedParser = replayDerivedParser;
 exports.replayDerivedParserAsync = replayDerivedParserAsync;
 exports.resolveStateWithRuntime = resolveStateWithRuntime;
-exports.resolveStateWithRuntimeAsync = resolveStateWithRuntimeAsync;
+exports.resolveStateWithRuntimeAsync = resolveStateWithRuntimeAsync;
+exports.serializeSchedulingPath = serializeSchedulingPath;
+exports.sourceCollectionExpansionKey = sourceCollectionExpansionKey;
+exports.staticSourceScopeKey = staticSourceScopeKey;

package/dist/dependency-runtime.d.cts

@@ -105,6 +105,63 @@ interface RuntimeNode {
    * @since 1.0.0
    */
   readonly defaultDependencyValues?: readonly unknown[];
+  /**
+   * A scheduling barrier: a preparation step executed serially at this
+   * node's declaration position during the effectful completion pass.
+   *
+   * A `conditional()` whose branch selection is still unknown installs
+   * one after its discriminator node: the preparation resolves the
+   * branch from the discriminator's completion, caches the decision in
+   * the run-scoped session so final completion reuses it, and schedules
+   * the chosen branch's nodes through `ctx.schedule` within the same
+   * pass.  A failure aborts the pass like a failed effectful
+   * completion; `undefined` declines without effect.
+   *
+   * @since 1.3.0
+   */
+  readonly prepare?: (ctx: SchedulingBarrierContext) => Promise<{
+    readonly success: false;
+    readonly error: Message;
+  } | undefined>;
+  /**
+   * Source IDs that the subtree guarded by this barrier can provide.
+   * Used by the demand-only pass: when any of them is demanded, the
+   * barrier's {@link RuntimeNode.requiresSourceId} becomes demanded as
+   * a control dependency, so the guarding discriminator completes in
+   * the seed pass even though no consumer demands it directly.
+   *
+   * @since 1.3.0
+   */
+  readonly providesSourceIds?: ReadonlySet<symbol>;
+  /**
+   * The source ID whose completion this barrier's preparation depends
+   * on (a `conditional()` discriminator).  See
+   * {@link RuntimeNode.providesSourceIds}.
+   *
+   * @since 1.3.0
+   */
+  readonly requiresSourceId?: symbol;
+}
+/**
+ * The context handed to a {@link RuntimeNode.prepare} barrier.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface SchedulingBarrierContext {
+  /** The runtime the current pass registers source values into. */
+  readonly runtime: DependencyRuntimeContext;
+  /** The execution context of the current pass. */
+  readonly exec: ExecutionContext | undefined;
+  /**
+   * Schedules further (already expanded) nodes within the current pass,
+   * at the barrier's position.  Results are deduplicated through the
+   * run-scoped session and are not cached by the owning construct.
+   */
+  readonly schedule: (nodes: readonly RuntimeNode[]) => Promise<{
+    readonly success: false;
+    readonly error: Message;
+  } | undefined>;
 }
 /**
  * Dependency runtime context for centralized dependency resolution.
@@ -281,6 +338,41 @@ declare const effectfulSchedulingNodesKey: unique symbol;
  * @since 1.3.0
  */
 type EffectfulSchedulingNodesFn = (state: unknown, parentPath: readonly PropertyKey[] | undefined) => readonly RuntimeNode[];
+/**
+ * Opt-in marker for parsers whose {@link effectfulSchedulingNodesKey}
+ * hook also defines their explicit-source *collection* scope.
+ *
+ * A parent construct normally collects explicit source values from its
+ * direct children only.  A parser carrying this marker (with value
+ * `true`) asks the parent to expand it through its scheduling hook
+ * before collecting, so command-line source values inside it—such as a
+ * `conditional()` discriminator, a committed conditional branch, or a
+ * selected `command()` subtree—register into the parent's dependency
+ * runtime exactly like a prompt-completed value would.  Constructs
+ * without the marker (plain nested `object()`, uncommitted exclusive
+ * branches) keep their existing scope.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare const sourceCollectionExpansionKey: unique symbol;
+/**
+ * Static child parsers reachable for dependency-source estimation.
+ *
+ * `collectStaticSourceIds()` walks flattened field pairs, which stops at
+ * parsers whose children are not field-shaped—a `command()`'s inner
+ * parser, a nested `conditional()`'s branches, exclusive alternatives,
+ * or a transparent wrapper's inner construct.  Such parsers expose their
+ * children here so the walk can estimate every source a subtree may
+ * provide.  The estimate feeds demand-only control dependencies, where
+ * an overcount merely completes a discriminator earlier than strictly
+ * needed, while an undercount delays an effectful completion to the
+ * final pass and starves phase-two contexts of seed values.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare const staticSourceScopeKey: unique symbol;
 /**
  * Forwards effectful scheduling through a shape-preserving wrapper such
  * as `map()`, `optional()`, `withDefault()`, or `nonEmpty()`, so the
@@ -369,6 +461,25 @@ interface CompleteEffectfulSourcesOptions {
    * running twice, and are skipped when no session is available.
    */
   readonly isReusable?: (node: RuntimeNode) => boolean;
+  /**
+   * Whether a node participated in the owning construct's explicit
+   * source collection, and therefore must have its structural value
+   * re-registered at its declaration position so registration order
+   * follows declaration order across structural and effectful
+   * occurrences.  This is wider than {@link isReusable}: nodes expanded
+   * from an opted-in child (see `sourceCollectionExpansionKey`) are
+   * collected but not reusable.  Defaults to {@link isReusable}.
+   */
+  readonly isCollected?: (node: RuntimeNode) => boolean;
+  /**
+   * Processes structural source nodes even when no node carries an
+   * effectful completion or a barrier.  A barrier's nested scheduling
+   * call sets this: the branch it schedules may hold only structural
+   * (command-line) values, which still must register into the pass's
+   * runtime, while ordinary construct passes keep the cheap early
+   * return.
+   */
+  readonly includeStructural?: boolean;
 }
 /**
  * Runs effectful source completions (e.g., interactive prompts) serially
@@ -378,12 +489,12 @@ interface CompleteEffectfulSourcesOptions {
  *
  * - Runs only during real completion (`exec.phase === "complete"`); probe
  *   and suggest phases return immediately without effects.
- * - Precedence is structural: a source whose value was registered before
- *   the pass begins (from CLI state, environment, configuration, or a
- *   default) or that has already failed is never completed effectfully.
- *   When several scheduled occurrences share one source, each occurrence
- *   still completes and re-registers, so the last occurrence wins—the
- *   same rule as repeated command-line source occurrences.
+ * - Precedence is structural per occurrence: an effectful completion
+ *   returns its own field's command-line or bound value without running
+ *   the effect, and structural occurrences re-register their extracted
+ *   values in declaration order.  When several scheduled occurrences
+ *   share one source, the last occurrence wins—the same rule as repeated
+ *   command-line source occurrences.
  * - Completion results that are `undefined` or marked `deferred` are
  *   treated as declined and neither registered nor cached.
  * - A successful result registers its value unless the value is
@@ -416,6 +527,16 @@ interface CompleteEffectfulSourcesOptions {
  * @since 1.3.0
  */
 declare function completeEffectfulSourcesAsync(nodes: readonly RuntimeNode[], state: unknown, runtime: DependencyRuntimeContext, exec: ExecutionContext | undefined, options?: CompleteEffectfulSourcesOptions): Promise<EffectfulSourceCompletionResult>;
+/**
+ * Serializes a scheduling node path into a stable string key, using
+ * length-prefixed segments so no separator escaping is needed.  Shared
+ * with constructs that key run-scoped session entries by path (e.g.,
+ * `conditional()`'s prepared branch selections).
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare function serializeSchedulingPath(path: readonly PropertyKey[]): string;
 /**
  * Recursively collects dependency source values from {@link DependencySourceState}
  * objects found in the state tree and registers them in the runtime.
@@ -495,4 +616,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };
+export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.d.ts

@@ -105,6 +105,63 @@ interface RuntimeNode {
    * @since 1.0.0
    */
   readonly defaultDependencyValues?: readonly unknown[];
+  /**
+   * A scheduling barrier: a preparation step executed serially at this
+   * node's declaration position during the effectful completion pass.
+   *
+   * A `conditional()` whose branch selection is still unknown installs
+   * one after its discriminator node: the preparation resolves the
+   * branch from the discriminator's completion, caches the decision in
+   * the run-scoped session so final completion reuses it, and schedules
+   * the chosen branch's nodes through `ctx.schedule` within the same
+   * pass.  A failure aborts the pass like a failed effectful
+   * completion; `undefined` declines without effect.
+   *
+   * @since 1.3.0
+   */
+  readonly prepare?: (ctx: SchedulingBarrierContext) => Promise<{
+    readonly success: false;
+    readonly error: Message;
+  } | undefined>;
+  /**
+   * Source IDs that the subtree guarded by this barrier can provide.
+   * Used by the demand-only pass: when any of them is demanded, the
+   * barrier's {@link RuntimeNode.requiresSourceId} becomes demanded as
+   * a control dependency, so the guarding discriminator completes in
+   * the seed pass even though no consumer demands it directly.
+   *
+   * @since 1.3.0
+   */
+  readonly providesSourceIds?: ReadonlySet<symbol>;
+  /**
+   * The source ID whose completion this barrier's preparation depends
+   * on (a `conditional()` discriminator).  See
+   * {@link RuntimeNode.providesSourceIds}.
+   *
+   * @since 1.3.0
+   */
+  readonly requiresSourceId?: symbol;
+}
+/**
+ * The context handed to a {@link RuntimeNode.prepare} barrier.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface SchedulingBarrierContext {
+  /** The runtime the current pass registers source values into. */
+  readonly runtime: DependencyRuntimeContext;
+  /** The execution context of the current pass. */
+  readonly exec: ExecutionContext | undefined;
+  /**
+   * Schedules further (already expanded) nodes within the current pass,
+   * at the barrier's position.  Results are deduplicated through the
+   * run-scoped session and are not cached by the owning construct.
+   */
+  readonly schedule: (nodes: readonly RuntimeNode[]) => Promise<{
+    readonly success: false;
+    readonly error: Message;
+  } | undefined>;
 }
 /**
  * Dependency runtime context for centralized dependency resolution.
@@ -281,6 +338,41 @@ declare const effectfulSchedulingNodesKey: unique symbol;
  * @since 1.3.0
  */
 type EffectfulSchedulingNodesFn = (state: unknown, parentPath: readonly PropertyKey[] | undefined) => readonly RuntimeNode[];
+/**
+ * Opt-in marker for parsers whose {@link effectfulSchedulingNodesKey}
+ * hook also defines their explicit-source *collection* scope.
+ *
+ * A parent construct normally collects explicit source values from its
+ * direct children only.  A parser carrying this marker (with value
+ * `true`) asks the parent to expand it through its scheduling hook
+ * before collecting, so command-line source values inside it—such as a
+ * `conditional()` discriminator, a committed conditional branch, or a
+ * selected `command()` subtree—register into the parent's dependency
+ * runtime exactly like a prompt-completed value would.  Constructs
+ * without the marker (plain nested `object()`, uncommitted exclusive
+ * branches) keep their existing scope.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare const sourceCollectionExpansionKey: unique symbol;
+/**
+ * Static child parsers reachable for dependency-source estimation.
+ *
+ * `collectStaticSourceIds()` walks flattened field pairs, which stops at
+ * parsers whose children are not field-shaped—a `command()`'s inner
+ * parser, a nested `conditional()`'s branches, exclusive alternatives,
+ * or a transparent wrapper's inner construct.  Such parsers expose their
+ * children here so the walk can estimate every source a subtree may
+ * provide.  The estimate feeds demand-only control dependencies, where
+ * an overcount merely completes a discriminator earlier than strictly
+ * needed, while an undercount delays an effectful completion to the
+ * final pass and starves phase-two contexts of seed values.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare const staticSourceScopeKey: unique symbol;
 /**
  * Forwards effectful scheduling through a shape-preserving wrapper such
  * as `map()`, `optional()`, `withDefault()`, or `nonEmpty()`, so the
@@ -369,6 +461,25 @@ interface CompleteEffectfulSourcesOptions {
    * running twice, and are skipped when no session is available.
    */
   readonly isReusable?: (node: RuntimeNode) => boolean;
+  /**
+   * Whether a node participated in the owning construct's explicit
+   * source collection, and therefore must have its structural value
+   * re-registered at its declaration position so registration order
+   * follows declaration order across structural and effectful
+   * occurrences.  This is wider than {@link isReusable}: nodes expanded
+   * from an opted-in child (see `sourceCollectionExpansionKey`) are
+   * collected but not reusable.  Defaults to {@link isReusable}.
+   */
+  readonly isCollected?: (node: RuntimeNode) => boolean;
+  /**
+   * Processes structural source nodes even when no node carries an
+   * effectful completion or a barrier.  A barrier's nested scheduling
+   * call sets this: the branch it schedules may hold only structural
+   * (command-line) values, which still must register into the pass's
+   * runtime, while ordinary construct passes keep the cheap early
+   * return.
+   */
+  readonly includeStructural?: boolean;
 }
 /**
  * Runs effectful source completions (e.g., interactive prompts) serially
@@ -378,12 +489,12 @@ interface CompleteEffectfulSourcesOptions {
  *
  * - Runs only during real completion (`exec.phase === "complete"`); probe
  *   and suggest phases return immediately without effects.
- * - Precedence is structural: a source whose value was registered before
- *   the pass begins (from CLI state, environment, configuration, or a
- *   default) or that has already failed is never completed effectfully.
- *   When several scheduled occurrences share one source, each occurrence
- *   still completes and re-registers, so the last occurrence wins—the
- *   same rule as repeated command-line source occurrences.
+ * - Precedence is structural per occurrence: an effectful completion
+ *   returns its own field's command-line or bound value without running
+ *   the effect, and structural occurrences re-register their extracted
+ *   values in declaration order.  When several scheduled occurrences
+ *   share one source, the last occurrence wins—the same rule as repeated
+ *   command-line source occurrences.
  * - Completion results that are `undefined` or marked `deferred` are
  *   treated as declined and neither registered nor cached.
  * - A successful result registers its value unless the value is
@@ -416,6 +527,16 @@ interface CompleteEffectfulSourcesOptions {
  * @since 1.3.0
  */
 declare function completeEffectfulSourcesAsync(nodes: readonly RuntimeNode[], state: unknown, runtime: DependencyRuntimeContext, exec: ExecutionContext | undefined, options?: CompleteEffectfulSourcesOptions): Promise<EffectfulSourceCompletionResult>;
+/**
+ * Serializes a scheduling node path into a stable string key, using
+ * length-prefixed segments so no separator escaping is needed.  Shared
+ * with constructs that key run-scoped session entries by path (e.g.,
+ * `conditional()`'s prepared branch selections).
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare function serializeSchedulingPath(path: readonly PropertyKey[]): string;
 /**
  * Recursively collects dependency source values from {@link DependencySourceState}
  * objects found in the state tree and registers them in the runtime.
@@ -495,4 +616,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };
+export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.js

@@ -494,6 +494,41 @@ function extractRawInputFromState(state) {
 */
 const effectfulSchedulingNodesKey = Symbol("@optique/core/dependency-runtime/effectfulSchedulingNodes");
 /**
+* Opt-in marker for parsers whose {@link effectfulSchedulingNodesKey}
+* hook also defines their explicit-source *collection* scope.
+*
+* A parent construct normally collects explicit source values from its
+* direct children only.  A parser carrying this marker (with value
+* `true`) asks the parent to expand it through its scheduling hook
+* before collecting, so command-line source values inside it—such as a
+* `conditional()` discriminator, a committed conditional branch, or a
+* selected `command()` subtree—register into the parent's dependency
+* runtime exactly like a prompt-completed value would.  Constructs
+* without the marker (plain nested `object()`, uncommitted exclusive
+* branches) keep their existing scope.
+*
+* @internal
+* @since 1.3.0
+*/
+const sourceCollectionExpansionKey = Symbol("@optique/core/dependency-runtime/sourceCollectionExpansion");
+/**
+* Static child parsers reachable for dependency-source estimation.
+*
+* `collectStaticSourceIds()` walks flattened field pairs, which stops at
+* parsers whose children are not field-shaped—a `command()`'s inner
+* parser, a nested `conditional()`'s branches, exclusive alternatives,
+* or a transparent wrapper's inner construct.  Such parsers expose their
+* children here so the walk can estimate every source a subtree may
+* provide.  The estimate feeds demand-only control dependencies, where
+* an overcount merely completes a discriminator earlier than strictly
+* needed, while an undercount delays an effectful completion to the
+* final pass and starves phase-two contexts of seed values.
+*
+* @internal
+* @since 1.3.0
+*/
+const staticSourceScopeKey = Symbol("@optique/core/dependency-runtime/staticSourceScope");
+/**
 * 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
@@ -511,6 +546,11 @@ const effectfulSchedulingNodesKey = Symbol("@optique/core/dependency-runtime/eff
 * @since 1.3.0
 */
 function defineForwardedEffectfulSchedulingNodes(wrapper, inner, adaptState) {
+	Object.defineProperty(wrapper, staticSourceScopeKey, {
+		value: [inner],
+		configurable: true,
+		enumerable: false
+	});
 	if (inner.dependencyMetadata?.source != null) return;
 	Object.defineProperty(wrapper, effectfulSchedulingNodesKey, {
 		value: ((state, parentPath) => [{
@@ -521,6 +561,11 @@ function defineForwardedEffectfulSchedulingNodes(wrapper, inner, adaptState) {
 		configurable: true,
 		enumerable: false
 	});
+	if (inner[sourceCollectionExpansionKey] === true) Object.defineProperty(wrapper, sourceCollectionExpansionKey, {
+		value: true,
+		configurable: true,
+		enumerable: false
+	});
 }
 /**
 * Collects the dependency source IDs demanded by consumers among the
@@ -570,12 +615,12 @@ function collectDeferredDemand(state, demanded, visited) {
 *
 * - Runs only during real completion (`exec.phase === "complete"`); probe
 *   and suggest phases return immediately without effects.
-* - Precedence is structural: a source whose value was registered before
-*   the pass begins (from CLI state, environment, configuration, or a
-*   default) or that has already failed is never completed effectfully.
-*   When several scheduled occurrences share one source, each occurrence
-*   still completes and re-registers, so the last occurrence wins—the
-*   same rule as repeated command-line source occurrences.
+* - Precedence is structural per occurrence: an effectful completion
+*   returns its own field's command-line or bound value without running
+*   the effect, and structural occurrences re-register their extracted
+*   values in declaration order.  When several scheduled occurrences
+*   share one source, the last occurrence wins—the same rule as repeated
+*   command-line source occurrences.
 * - Completion results that are `undefined` or marked `deferred` are
 *   treated as declined and neither registered nor cached.
 * - A successful result registers its value unless the value is
@@ -618,6 +663,19 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 		const demandNodes = options?.demandNodes ?? nodes;
 		const demanded = collectDemandedDependencyIds(demandNodes, state, exec.trace);
 		for (const id of demanded) session.demanded.add(id);
+		let demandAdded = true;
+		while (demandAdded) {
+			demandAdded = false;
+			for (const node of nodes) {
+				if (node.requiresSourceId == null || node.providesSourceIds == null) continue;
+				if (session.demanded.has(node.requiresSourceId)) continue;
+				for (const provided of node.providesSourceIds) if (session.demanded.has(provided)) {
+					session.demanded.add(node.requiresSourceId);
+					demandAdded = true;
+					break;
+				}
+			}
+		}
 	}
 	if (session != null) {
 		for (const result of session.results.values()) if (!result.success) return {
@@ -625,14 +683,28 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 			error: result.error
 		};
 	}
-	const schedulable = nodes.filter((node) => node.parser.dependencyMetadata?.source?.completeSource != null);
-	if (schedulable.length === 0) return empty;
+	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 nodes) {
+		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)
+			});
+			if (barrierFailure != null) return barrierFailure;
+			continue;
+		}
 		const source = node.parser.dependencyMetadata?.source;
 		if (source == null) continue;
 		if (source.completeSource == null) {
-			if (source.extractSourceValue == null || (options?.isReusable?.(node) ?? true) === false) continue;
+			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);
 			continue;
@@ -676,7 +748,12 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 }
 /**
 * Serializes a scheduling node path into a stable string key, using
-* length-prefixed segments so no separator escaping is needed.
+* length-prefixed segments so no separator escaping is needed.  Shared
+* with constructs that key run-scoped session entries by path (e.g.,
+* `conditional()`'s prepared branch selections).
+*
+* @internal
+* @since 1.3.0
 */
 function serializeSchedulingPath(path) {
 	return path.map(serializePathSegment).join("");
@@ -921,4 +998,4 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };
+export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };