@optique/core 1.3.0-dev.2379 → 1.3.0-dev.2380

package/dist/internal/parser.cjs

@@ -14,6 +14,21 @@ const require_input_trace = require('../input-trace.cjs');
 */
 const parseLanesKey = Symbol("parseLanes");
 /**
+* Creates a fresh {@link EffectfulCompletionSession}.
+*
+* @internal
+* @since 1.3.0
+*/
+function createEffectfulCompletionSession(policy = "eager") {
+	return {
+		policy,
+		results: /* @__PURE__ */ new Map(),
+		demanded: /* @__PURE__ */ new Set(),
+		effectfulSources: /* @__PURE__ */ new Set(),
+		completedByPath: /* @__PURE__ */ new Map()
+	};
+}
+/**
 * Internal marker for wrappers whose `{ hasCliValue: false }` states should
 * be treated as unmatched dependency-source states during completion-time
 * Phase 1.
@@ -21,7 +36,9 @@ const parseLanesKey = Symbol("parseLanes");
 * Wrappers like `bindEnv()` and `bindConfig()` opt in because their missing
 * CLI states still carry enough fallback context to pre-complete exactly
 * once. Wrappers like `prompt()` intentionally do not opt in because
-* prompted values are not yet registered as dependency sources.
+* Phase 1 must stay effect-free; prompted values register instead through
+* the `completeSource` capability during the serial effectful completion
+* pass that runs before dependency replay.
 *
 * @internal
 */
@@ -130,7 +147,8 @@ function parseSync(parser, args, options) {
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
 		commandPath: context.exec?.commandPath ?? exec.commandPath,
-		trace: context.exec?.trace ?? context.trace ?? exec.trace
+		trace: context.exec?.trace ?? context.trace ?? exec.trace,
+		effectfulCompletionSession: createEffectfulCompletionSession()
 	};
 	const endResult = parser.complete(context.state, completeExec);
 	return endResult.success ? {
@@ -203,7 +221,8 @@ async function parseAsync(parser, args, options) {
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
 		commandPath: context.exec?.commandPath ?? exec.commandPath,
-		trace: context.exec?.trace ?? context.trace ?? exec.trace
+		trace: context.exec?.trace ?? context.trace ?? exec.trace,
+		effectfulCompletionSession: createEffectfulCompletionSession()
 	};
 	const endResult = await parser.complete(context.state, completeExec);
 	return endResult.success ? {
@@ -884,6 +903,7 @@ function findNextMatchedCommandArgIndex(args, matchedCommandArgIndices, start) {
 //#endregion
 exports.annotationWrapperRequiresSourceBindingKey = annotationWrapperRequiresSourceBindingKey;
 exports.composeWrappedSourceMetadata = composeWrappedSourceMetadata;
+exports.createEffectfulCompletionSession = createEffectfulCompletionSession;
 exports.createParserContext = createParserContext;
 exports.defineInheritedAnnotationParser = defineInheritedAnnotationParser;
 exports.defineParseLanes = defineParseLanes;

package/dist/internal/parser.d.cts

@@ -5,8 +5,8 @@ import { DocFragments, DocPage } from "../doc.cjs";
 import { DependencyRegistryLike } from "../registry-types.cjs";
 import { DeferredMap, ValueParserResult } from "../valueparser.cjs";
 import { ParserDependencyMetadata } from "../dependency-metadata.cjs";
-import { DependencyRuntimeContext, RuntimeNode } from "../dependency-runtime.cjs";
 import { InputTrace } from "../input-trace.cjs";
+import { DependencyRuntimeContext, RuntimeNode } from "../dependency-runtime.cjs";
 
 //#region src/internal/parser.d.ts
 
@@ -412,6 +412,72 @@ interface ParseFrame<TState> {
  * @since 1.0.0
  */
 type ExecutionPhase = "parse" | "precomplete" | "resolve" | "complete" | "suggest";
+/**
+ * Run-scoped state for effectful source completions such as `prompt()`.
+ *
+ * A session is created once per parse operation (or once per `runWith()`
+ * run, shared by the phase-two seed pass and the final pass) and threaded
+ * through {@link ExecutionContext}.  It guarantees that an effectful source
+ * completion runs at most once per run: the completion result is cached by
+ * dependency source ID, and a cache hit is returned without repeating the
+ * effect.  Results never leak between runs because the session is discarded
+ * when the run ends.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface EffectfulCompletionSession {
+  /**
+   * The scheduling policy for effectful source completions.
+   *
+   * `"demand-only"` is used during the phase-two seed pass of a two-pass
+   * source context run: an effectful source completion runs only when a
+   * phase-one consumer demands its source (see
+   * {@link EffectfulCompletionSession.demanded}); otherwise it defers to
+   * the final pass.  `"eager"` is used everywhere else.
+   */
+  readonly policy: "demand-only" | "eager";
+  /**
+   * Effectful completion results keyed by completion occurrence (e.g.,
+   * a per-`prompt()`-wrapper cache key), shared across the passes of a
+   * run.  Occurrence keys, rather than dependency source IDs, keep two
+   * distinct effectful wrappers around the same source—such as duplicate
+   * `merge()` fields—from observing each other's local results.
+   */
+  readonly results: Map<symbol, ValueParserResult<unknown>>;
+  /**
+   * Source IDs demanded by phase-one consumers.  Constructs add entries
+   * before scheduling effectful completions; the set accumulates across
+   * constructs within a run.
+   */
+  readonly demanded: Set<symbol>;
+  /**
+   * Source IDs whose registered value came from an effectful completion
+   * (a prompt that actually executed) rather than from a structural
+   * source such as CLI state, environment, configuration, or a default.
+   * The scheduler uses this to keep structural precedence while still
+   * letting a later prompted occurrence of the same source overwrite an
+   * earlier prompted answer, matching repeated command-line occurrences.
+   */
+  readonly effectfulSources: Set<symbol>;
+  /**
+   * Effectful source completion results keyed by serialized node path,
+   * scoped to a single pass like {@link effectfulSources}.  A completion
+   * scheduled for an expanded nested node is recorded here so that the
+   * owning nested construct's own scheduling pass reuses it instead of
+   * completing the same node again—keeping lazy wrapper defaults at one
+   * evaluation per pass and the registered dependency value identical to
+   * the field's final value.
+   */
+  readonly completedByPath: Map<string, ValueParserResult<unknown>>;
+}
+/**
+ * Creates a fresh {@link EffectfulCompletionSession}.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare function createEffectfulCompletionSession(policy?: "demand-only" | "eager"): EffectfulCompletionSession;
 /**
  * Shared execution context carrying cross-cutting runtime data.
  * This includes information that is shared across all parsers in a parse
@@ -495,6 +561,15 @@ interface ExecutionContext {
    * @internal
    */
   readonly excludedSourceFields?: ReadonlySet<string | symbol>;
+  /**
+   * Run-scoped state for effectful source completions such as `prompt()`.
+   * Created at the top-level parse entry points and shared across the
+   * passes of a `runWith()` run.
+   *
+   * @internal
+   * @since 1.3.0
+   */
+  readonly effectfulCompletionSession?: EffectfulCompletionSession;
 }
 /**
  * Internal marker for wrappers whose `{ hasCliValue: false }` states should
@@ -504,7 +579,9 @@ interface ExecutionContext {
  * Wrappers like `bindEnv()` and `bindConfig()` opt in because their missing
  * CLI states still carry enough fallback context to pre-complete exactly
  * once. Wrappers like `prompt()` intentionally do not opt in because
- * prompted values are not yet registered as dependency sources.
+ * Phase 1 must stay effect-free; prompted values register instead through
+ * the `completeSource` capability during the serial effectful completion
+ * pass that runs before dependency replay.
  *
  * @internal
  */
@@ -1060,4 +1137,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, ParseLane, ParseLaneConsumptionGroup, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };
+export { CombineModes, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, ParseLane, ParseLaneConsumptionGroup, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createEffectfulCompletionSession, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };

package/dist/internal/parser.d.ts

@@ -5,8 +5,8 @@ import { DocFragments, DocPage } from "../doc.js";
 import { DependencyRegistryLike } from "../registry-types.js";
 import { DeferredMap, ValueParserResult } from "../valueparser.js";
 import { ParserDependencyMetadata } from "../dependency-metadata.js";
-import { DependencyRuntimeContext, RuntimeNode } from "../dependency-runtime.js";
 import { InputTrace } from "../input-trace.js";
+import { DependencyRuntimeContext, RuntimeNode } from "../dependency-runtime.js";
 
 //#region src/internal/parser.d.ts
 
@@ -412,6 +412,72 @@ interface ParseFrame<TState> {
  * @since 1.0.0
  */
 type ExecutionPhase = "parse" | "precomplete" | "resolve" | "complete" | "suggest";
+/**
+ * Run-scoped state for effectful source completions such as `prompt()`.
+ *
+ * A session is created once per parse operation (or once per `runWith()`
+ * run, shared by the phase-two seed pass and the final pass) and threaded
+ * through {@link ExecutionContext}.  It guarantees that an effectful source
+ * completion runs at most once per run: the completion result is cached by
+ * dependency source ID, and a cache hit is returned without repeating the
+ * effect.  Results never leak between runs because the session is discarded
+ * when the run ends.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface EffectfulCompletionSession {
+  /**
+   * The scheduling policy for effectful source completions.
+   *
+   * `"demand-only"` is used during the phase-two seed pass of a two-pass
+   * source context run: an effectful source completion runs only when a
+   * phase-one consumer demands its source (see
+   * {@link EffectfulCompletionSession.demanded}); otherwise it defers to
+   * the final pass.  `"eager"` is used everywhere else.
+   */
+  readonly policy: "demand-only" | "eager";
+  /**
+   * Effectful completion results keyed by completion occurrence (e.g.,
+   * a per-`prompt()`-wrapper cache key), shared across the passes of a
+   * run.  Occurrence keys, rather than dependency source IDs, keep two
+   * distinct effectful wrappers around the same source—such as duplicate
+   * `merge()` fields—from observing each other's local results.
+   */
+  readonly results: Map<symbol, ValueParserResult<unknown>>;
+  /**
+   * Source IDs demanded by phase-one consumers.  Constructs add entries
+   * before scheduling effectful completions; the set accumulates across
+   * constructs within a run.
+   */
+  readonly demanded: Set<symbol>;
+  /**
+   * Source IDs whose registered value came from an effectful completion
+   * (a prompt that actually executed) rather than from a structural
+   * source such as CLI state, environment, configuration, or a default.
+   * The scheduler uses this to keep structural precedence while still
+   * letting a later prompted occurrence of the same source overwrite an
+   * earlier prompted answer, matching repeated command-line occurrences.
+   */
+  readonly effectfulSources: Set<symbol>;
+  /**
+   * Effectful source completion results keyed by serialized node path,
+   * scoped to a single pass like {@link effectfulSources}.  A completion
+   * scheduled for an expanded nested node is recorded here so that the
+   * owning nested construct's own scheduling pass reuses it instead of
+   * completing the same node again—keeping lazy wrapper defaults at one
+   * evaluation per pass and the registered dependency value identical to
+   * the field's final value.
+   */
+  readonly completedByPath: Map<string, ValueParserResult<unknown>>;
+}
+/**
+ * Creates a fresh {@link EffectfulCompletionSession}.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare function createEffectfulCompletionSession(policy?: "demand-only" | "eager"): EffectfulCompletionSession;
 /**
  * Shared execution context carrying cross-cutting runtime data.
  * This includes information that is shared across all parsers in a parse
@@ -495,6 +561,15 @@ interface ExecutionContext {
    * @internal
    */
   readonly excludedSourceFields?: ReadonlySet<string | symbol>;
+  /**
+   * Run-scoped state for effectful source completions such as `prompt()`.
+   * Created at the top-level parse entry points and shared across the
+   * passes of a `runWith()` run.
+   *
+   * @internal
+   * @since 1.3.0
+   */
+  readonly effectfulCompletionSession?: EffectfulCompletionSession;
 }
 /**
  * Internal marker for wrappers whose `{ hasCliValue: false }` states should
@@ -504,7 +579,9 @@ interface ExecutionContext {
  * Wrappers like `bindEnv()` and `bindConfig()` opt in because their missing
  * CLI states still carry enough fallback context to pre-complete exactly
  * once. Wrappers like `prompt()` intentionally do not opt in because
- * prompted values are not yet registered as dependency sources.
+ * Phase 1 must stay effect-free; prompted values register instead through
+ * the `completeSource` capability during the serial effectful completion
+ * pass that runs before dependency replay.
  *
  * @internal
  */
@@ -1060,4 +1137,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
-export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, ParseLane, ParseLaneConsumptionGroup, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };
+export { CombineModes, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, ParseLane, ParseLaneConsumptionGroup, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createEffectfulCompletionSession, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };

package/dist/internal/parser.js

@@ -14,6 +14,21 @@ import { createInputTrace } from "../input-trace.js";
 */
 const parseLanesKey = Symbol("parseLanes");
 /**
+* Creates a fresh {@link EffectfulCompletionSession}.
+*
+* @internal
+* @since 1.3.0
+*/
+function createEffectfulCompletionSession(policy = "eager") {
+	return {
+		policy,
+		results: /* @__PURE__ */ new Map(),
+		demanded: /* @__PURE__ */ new Set(),
+		effectfulSources: /* @__PURE__ */ new Set(),
+		completedByPath: /* @__PURE__ */ new Map()
+	};
+}
+/**
 * Internal marker for wrappers whose `{ hasCliValue: false }` states should
 * be treated as unmatched dependency-source states during completion-time
 * Phase 1.
@@ -21,7 +36,9 @@ const parseLanesKey = Symbol("parseLanes");
 * Wrappers like `bindEnv()` and `bindConfig()` opt in because their missing
 * CLI states still carry enough fallback context to pre-complete exactly
 * once. Wrappers like `prompt()` intentionally do not opt in because
-* prompted values are not yet registered as dependency sources.
+* Phase 1 must stay effect-free; prompted values register instead through
+* the `completeSource` capability during the serial effectful completion
+* pass that runs before dependency replay.
 *
 * @internal
 */
@@ -130,7 +147,8 @@ function parseSync(parser, args, options) {
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
 		commandPath: context.exec?.commandPath ?? exec.commandPath,
-		trace: context.exec?.trace ?? context.trace ?? exec.trace
+		trace: context.exec?.trace ?? context.trace ?? exec.trace,
+		effectfulCompletionSession: createEffectfulCompletionSession()
 	};
 	const endResult = parser.complete(context.state, completeExec);
 	return endResult.success ? {
@@ -203,7 +221,8 @@ async function parseAsync(parser, args, options) {
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
 		commandPath: context.exec?.commandPath ?? exec.commandPath,
-		trace: context.exec?.trace ?? context.trace ?? exec.trace
+		trace: context.exec?.trace ?? context.trace ?? exec.trace,
+		effectfulCompletionSession: createEffectfulCompletionSession()
 	};
 	const endResult = await parser.complete(context.state, completeExec);
 	return endResult.success ? {
@@ -882,4 +901,4 @@ function findNextMatchedCommandArgIndex(args, matchedCommandArgIndices, start) {
 }
 
 //#endregion
-export { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };
+export { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createEffectfulCompletionSession, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };

package/dist/modifiers.cjs

@@ -1,6 +1,7 @@
 const require_internal_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
+const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
 const require_execution_context = require('./execution-context.cjs');
@@ -456,8 +457,24 @@ function optional(parser) {
 	}
 	if (parser.dependencyMetadata != null) {
 		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "optional");
-		if (composed != null) optionalParser.dependencyMetadata = composed;
+		if (composed != null) {
+			const rebound = composed.source?.completeSource == null ? composed : composed.source.preservesSourceValue === false ? {
+				...composed,
+				source: {
+					...composed.source,
+					completeSource: void 0
+				}
+			} : {
+				...composed,
+				source: {
+					...composed.source,
+					completeSource: (state, exec) => Promise.resolve(optionalParser.complete(state, exec))
+				}
+			};
+			optionalParser.dependencyMetadata = rebound;
+		}
 	}
+	require_dependency_runtime.defineForwardedEffectfulSchedulingNodes(optionalParser, parser, (state) => Array.isArray(state) && state.length === 1 ? state[0] : state);
 	require_internal_parser.defineParseLanes(optionalParser, adaptOptionalStyleParseLanes(parser));
 	require_internal_parser.defineInheritedAnnotationParser(optionalParser);
 	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
@@ -691,8 +708,24 @@ function withDefault(parser, defaultValue, options) {
 				value: v
 			};
 		} });
-		if (composed != null) withDefaultParser.dependencyMetadata = composed;
+		if (composed != null) {
+			const rebound = composed.source?.completeSource == null ? composed : composed.source.preservesSourceValue === false ? {
+				...composed,
+				source: {
+					...composed.source,
+					completeSource: void 0
+				}
+			} : {
+				...composed,
+				source: {
+					...composed.source,
+					completeSource: (state, exec) => Promise.resolve(withDefaultParser.complete(state, exec))
+				}
+			};
+			withDefaultParser.dependencyMetadata = rebound;
+		}
 	}
+	require_dependency_runtime.defineForwardedEffectfulSchedulingNodes(withDefaultParser, parser, (state) => Array.isArray(state) && state.length === 1 ? state[0] : state);
 	require_internal_parser.defineParseLanes(withDefaultParser, adaptOptionalStyleParseLanes(parser));
 	require_internal_parser.defineInheritedAnnotationParser(withDefaultParser);
 	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
@@ -884,6 +917,7 @@ function map(parser, transform) {
 		}
 		if (composed != null) mappedParser.dependencyMetadata = composed;
 	}
+	require_dependency_runtime.defineForwardedEffectfulSchedulingNodes(mappedParser, parser);
 	return fluent(mappedParser);
 }
 const deferredValueBrand = Symbol.for("@optique/core/deferredValue");
@@ -1660,6 +1694,7 @@ function multiple(parser, options = {}) {
 				source: {
 					...innerSource,
 					preservesSourceValue: false,
+					completeSource: void 0,
 					extractSourceValue: (state) => {
 						if (!Array.isArray(state)) return innerSource.extractSourceValue(state);
 						const scan = (index) => {
@@ -1785,6 +1820,11 @@ function nonEmpty(parser) {
 			return lane.parse(context);
 		}
 	})));
+	if (parser.dependencyMetadata != null) Object.defineProperty(nonEmptyParser, "dependencyMetadata", {
+		value: parser.dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	if ("placeholder" in parser) Object.defineProperty(nonEmptyParser, "placeholder", {
 		get() {
 			return parser.placeholder;
@@ -1809,6 +1849,7 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	require_dependency_runtime.defineForwardedEffectfulSchedulingNodes(nonEmptyParser, parser);
 	return fluent(nonEmptyParser);
 }
 const fluentParserMarker = Symbol.for("@optique/core/fluent");

package/dist/modifiers.js

@@ -1,6 +1,7 @@
 import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { formatMessage, message, text } from "./message.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
+import { defineForwardedEffectfulSchedulingNodes } from "./dependency-runtime.js";
 import { defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getOwnParseLanes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
@@ -456,8 +457,24 @@ function optional(parser) {
 	}
 	if (parser.dependencyMetadata != null) {
 		const composed = composeDependencyMetadata(parser.dependencyMetadata, "optional");
-		if (composed != null) optionalParser.dependencyMetadata = composed;
+		if (composed != null) {
+			const rebound = composed.source?.completeSource == null ? composed : composed.source.preservesSourceValue === false ? {
+				...composed,
+				source: {
+					...composed.source,
+					completeSource: void 0
+				}
+			} : {
+				...composed,
+				source: {
+					...composed.source,
+					completeSource: (state, exec) => Promise.resolve(optionalParser.complete(state, exec))
+				}
+			};
+			optionalParser.dependencyMetadata = rebound;
+		}
 	}
+	defineForwardedEffectfulSchedulingNodes(optionalParser, parser, (state) => Array.isArray(state) && state.length === 1 ? state[0] : state);
 	defineParseLanes(optionalParser, adaptOptionalStyleParseLanes(parser));
 	defineInheritedAnnotationParser(optionalParser);
 	defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
@@ -691,8 +708,24 @@ function withDefault(parser, defaultValue, options) {
 				value: v
 			};
 		} });
-		if (composed != null) withDefaultParser.dependencyMetadata = composed;
+		if (composed != null) {
+			const rebound = composed.source?.completeSource == null ? composed : composed.source.preservesSourceValue === false ? {
+				...composed,
+				source: {
+					...composed.source,
+					completeSource: void 0
+				}
+			} : {
+				...composed,
+				source: {
+					...composed.source,
+					completeSource: (state, exec) => Promise.resolve(withDefaultParser.complete(state, exec))
+				}
+			};
+			withDefaultParser.dependencyMetadata = rebound;
+		}
 	}
+	defineForwardedEffectfulSchedulingNodes(withDefaultParser, parser, (state) => Array.isArray(state) && state.length === 1 ? state[0] : state);
 	defineParseLanes(withDefaultParser, adaptOptionalStyleParseLanes(parser));
 	defineInheritedAnnotationParser(withDefaultParser);
 	defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
@@ -884,6 +917,7 @@ function map(parser, transform) {
 		}
 		if (composed != null) mappedParser.dependencyMetadata = composed;
 	}
+	defineForwardedEffectfulSchedulingNodes(mappedParser, parser);
 	return fluent(mappedParser);
 }
 const deferredValueBrand = Symbol.for("@optique/core/deferredValue");
@@ -1660,6 +1694,7 @@ function multiple(parser, options = {}) {
 				source: {
 					...innerSource,
 					preservesSourceValue: false,
+					completeSource: void 0,
 					extractSourceValue: (state) => {
 						if (!Array.isArray(state)) return innerSource.extractSourceValue(state);
 						const scan = (index) => {
@@ -1785,6 +1820,11 @@ function nonEmpty(parser) {
 			return lane.parse(context);
 		}
 	})));
+	if (parser.dependencyMetadata != null) Object.defineProperty(nonEmptyParser, "dependencyMetadata", {
+		value: parser.dependencyMetadata,
+		configurable: true,
+		enumerable: false
+	});
 	if ("placeholder" in parser) Object.defineProperty(nonEmptyParser, "placeholder", {
 		get() {
 			return parser.placeholder;
@@ -1809,6 +1849,7 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
+	defineForwardedEffectfulSchedulingNodes(nonEmptyParser, parser);
 	return fluent(nonEmptyParser);
 }
 const fluentParserMarker = Symbol.for("@optique/core/fluent");

package/dist/parser.d.cts

@@ -1,3 +1,3 @@
 import { ParseOptions } from "./internal/annotations.cjs";
-import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
-export { type CombineModes, type DocState, type ExecutionContext, type ExecutionPhase, type InferMode, type InferValue, type Mode, type ModeIterable, type ModeValue, type ParseFrame, type ParseOptions, type Parser, type ParserContext, type ParserResult, type Result, type Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };
+import { CombineModes, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
+export { type CombineModes, type DocState, type EffectfulCompletionSession, type ExecutionContext, type ExecutionPhase, type InferMode, type InferValue, type Mode, type ModeIterable, type ModeValue, type ParseFrame, type ParseOptions, type Parser, type ParserContext, type ParserResult, type Result, type Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };

package/dist/parser.d.ts

@@ -1,3 +1,3 @@
 import { ParseOptions } from "./internal/annotations.js";
-import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
-export { type CombineModes, type DocState, type ExecutionContext, type ExecutionPhase, type InferMode, type InferValue, type Mode, type ModeIterable, type ModeValue, type ParseFrame, type ParseOptions, type Parser, type ParserContext, type ParserResult, type Result, type Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };
+import { CombineModes, DocState, EffectfulCompletionSession, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
+export { type CombineModes, type DocState, type EffectfulCompletionSession, type ExecutionContext, type ExecutionPhase, type InferMode, type InferValue, type Mode, type ModeIterable, type ModeValue, type ParseFrame, type ParseOptions, type Parser, type ParserContext, type ParserResult, type Result, type Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };

package/dist/primitives.cjs

@@ -1706,6 +1706,20 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	Object.defineProperty(result, require_dependency_runtime.effectfulSchedulingNodesKey, {
+		value: ((state, parentPath) => {
+			const normalizedState = normalizeCommandState(state);
+			if (normalizedState == null) return [];
+			const innerState = normalizedState[0] === "parsing" ? normalizedState[1] : parser.initialState;
+			return [{
+				path: [...parentPath ?? [], name],
+				parser,
+				state: getCommandChildState(state, innerState, parser)
+			}];
+		}),
+		configurable: true,
+		enumerable: false
+	});
 	return require_modifiers.fluent(result);
 }
 /**

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 { replayDerivedParser, replayDerivedParserAsync } from "./dependency-runtime.js";
+import { effectfulSchedulingNodesKey, replayDerivedParser, replayDerivedParserAsync } 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";
@@ -1706,6 +1706,20 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
+	Object.defineProperty(result, effectfulSchedulingNodesKey, {
+		value: ((state, parentPath) => {
+			const normalizedState = normalizeCommandState(state);
+			if (normalizedState == null) return [];
+			const innerState = normalizedState[0] === "parsing" ? normalizedState[1] : parser.initialState;
+			return [{
+				path: [...parentPath ?? [], name],
+				parser,
+				state: getCommandChildState(state, innerState, parser)
+			}];
+		}),
+		configurable: true,
+		enumerable: false
+	});
 	return fluent(result);
 }
 /**