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

package/dist/dependency-runtime.d.ts

@@ -1,6 +1,9 @@
+import { Message } from "./message.js";
 import { DependencyRegistryLike } from "./registry-types.js";
 import { ValueParserResult } from "./valueparser.js";
 import { ParserDependencyMetadata } from "./dependency-metadata.js";
+import { InputTrace } from "./input-trace.js";
+import { ExecutionContext } from "./internal/parser.js";
 
 //#region src/dependency-runtime.d.ts
 
@@ -255,6 +258,164 @@ declare function replayDerivedParserAsync(node: RuntimeNode, rawInput: string, r
  * @since 1.0.0
  */
 declare function extractRawInputFromState(state: unknown): string | undefined;
+/**
+ * Internal parser hook for constructs whose effectful scheduling nodes
+ * cannot be derived from flattened field pairs alone.
+ *
+ * `merge()` installs it so a parent's scheduling expansion uses the same
+ * child-indexed paths, declaration order, and duplicate-field exclusion
+ * as the merge's own scheduling pass; `or()`/`longestMatch()` install it
+ * to expose the committed branch; `command()` installs it to expose its
+ * inner parser once the command has matched.  The returned node paths
+ * must match the execution paths used when the same parsers complete, so
+ * the run-scoped completion cache lines up.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare const effectfulSchedulingNodesKey: unique symbol;
+/**
+ * The shape of the {@link effectfulSchedulingNodesKey} hook.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+type EffectfulSchedulingNodesFn = (state: unknown, parentPath: readonly PropertyKey[] | undefined) => readonly RuntimeNode[];
+/**
+ * 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
+ * construct with nested effectful sources—stays visible to a parent
+ * construct's scheduling expansion.
+ *
+ * The installed hook simply re-exposes the inner parser as a node with
+ * the wrapper's own state shape unwrapped (`adaptState`, e.g. the
+ * `[innerState]` array used by `optional()`/`withDefault()`); the
+ * expansion then applies its ordinary rules to the inner parser, whether
+ * it carries its own hook, flattened field pairs, or source metadata.
+ * Wrappers are path-transparent, so the node keeps the wrapper's path.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+declare function defineForwardedEffectfulSchedulingNodes(wrapper: object, inner: {
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+}, adaptState?: (state: unknown) => unknown): void;
+/**
+ * A completed effectful source result to be reused by the owning
+ * construct's final completion phase, keyed by the node's last path
+ * segment (its field key or tuple index).
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface EffectfulSourceCompletion {
+  /** The node's field key or index (its last path segment). */
+  readonly key: PropertyKey;
+  /** The effectful completion result. */
+  readonly result: ValueParserResult<unknown>;
+}
+/**
+ * The result of scheduling effectful source completions.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+type EffectfulSourceCompletionResult = {
+  readonly success: true;
+  readonly completed: readonly EffectfulSourceCompletion[];
+} | {
+  readonly success: false;
+  readonly error: Message;
+};
+/**
+ * Collects the dependency source IDs demanded by consumers among the
+ * given nodes and state subtree.
+ *
+ * A consumer demands its sources when it has raw input evidence: either a
+ * trace entry recorded at its path during parsing, or a legacy
+ * `DeferredParseState` embedded in the state subtree.  Consumers without
+ * raw input never replay against real dependency values, so their sources
+ * are not demanded.
+ *
+ * @param nodes The direct-child runtime nodes of the owning construct.
+ * @param state The construct's state subtree (for legacy deferred states).
+ * @param trace The input trace recorded during parsing.
+ * @returns The set of demanded dependency source IDs.
+ * @internal
+ * @since 1.3.0
+ */
+declare function collectDemandedDependencyIds(nodes: readonly RuntimeNode[], state: unknown, trace: InputTrace | undefined): ReadonlySet<symbol>;
+/**
+ * Options for {@link completeEffectfulSourcesAsync}.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface CompleteEffectfulSourcesOptions {
+  /**
+   * Nodes used for demand detection instead of the scheduled nodes.
+   * Constructs whose parse-time trace paths differ from their scheduling
+   * node paths (e.g., `merge()`, which records child-indexed paths but
+   * schedules flattened field nodes) pass path-corrected nodes here.
+   */
+  readonly demandNodes?: readonly RuntimeNode[];
+  /**
+   * Whether a node's completion result may be cached by the owning
+   * construct for reuse in its final completion phase.  Defaults to
+   * treating every node as reusable.  Non-reusable completions (nodes
+   * expanded from nested children, or sources whose field value differs
+   * from the source value) rely on the run-scoped session cache to avoid
+   * running twice, and are skipped when no session is available.
+   */
+  readonly isReusable?: (node: RuntimeNode) => boolean;
+}
+/**
+ * Runs effectful source completions (e.g., interactive prompts) serially
+ * in declaration order for source nodes whose value is not yet registered.
+ *
+ * This is the scheduling half of the `completeSource` capability contract:
+ *
+ * - 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.
+ * - 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
+ *   `undefined`.  When the node is reusable (a direct child whose field
+ *   value is the source value), the result is also returned for reuse by
+ *   the owning construct so the node is not completed twice; otherwise the
+ *   effectful parser's own run-scoped session cache prevents a second
+ *   execution, so nodes that are not reusable are only scheduled when a
+ *   session is present.  For a source behind a transform such as `map()`
+ *   (`preservesSourceValue: false`), the `completeSource` contract still
+ *   yields the pre-transform source value, so registration stays correct
+ *   while the field's final value is produced separately.
+ * - A failed result (e.g., a cancelled prompt) marks the source as failed
+ *   and aborts immediately—later effectful completions do not run.
+ *
+ * When the run-scoped session policy is `"demand-only"` (the phase-two
+ * seed pass), the demanded source IDs from
+ * {@link collectDemandedDependencyIds} are added to the session before any
+ * completion runs, letting effectful parsers defer when no phase-one
+ * consumer demands their value.
+ *
+ * @param nodes The runtime nodes to schedule, in declaration order.
+ * @param state The construct's state subtree (for demand detection).
+ * @param runtime The dependency runtime context.
+ * @param exec The execution context of the owning construct.
+ * @param options Scheduling options.
+ * @returns The scheduling result: completed nodes for reuse, or the first
+ *   failure.
+ * @internal
+ * @since 1.3.0
+ */
+declare function completeEffectfulSourcesAsync(nodes: readonly RuntimeNode[], state: unknown, runtime: DependencyRuntimeContext, exec: ExecutionContext | undefined, options?: CompleteEffectfulSourcesOptions): Promise<EffectfulSourceCompletionResult>;
 /**
  * Recursively collects dependency source values from {@link DependencySourceState}
  * objects found in the state tree and registers them in the runtime.
@@ -334,4 +495,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { DependencyRequest, DependencyResolution, DependencyRuntimeContext, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };
+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 };

package/dist/dependency-runtime.js

@@ -478,6 +478,218 @@ function extractRawInputFromState(state) {
 	return void 0;
 }
 /**
+* Internal parser hook for constructs whose effectful scheduling nodes
+* cannot be derived from flattened field pairs alone.
+*
+* `merge()` installs it so a parent's scheduling expansion uses the same
+* child-indexed paths, declaration order, and duplicate-field exclusion
+* as the merge's own scheduling pass; `or()`/`longestMatch()` install it
+* to expose the committed branch; `command()` installs it to expose its
+* inner parser once the command has matched.  The returned node paths
+* must match the execution paths used when the same parsers complete, so
+* the run-scoped completion cache lines up.
+*
+* @internal
+* @since 1.3.0
+*/
+const effectfulSchedulingNodesKey = Symbol("@optique/core/dependency-runtime/effectfulSchedulingNodes");
+/**
+* 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
+* construct with nested effectful sources—stays visible to a parent
+* construct's scheduling expansion.
+*
+* The installed hook simply re-exposes the inner parser as a node with
+* the wrapper's own state shape unwrapped (`adaptState`, e.g. the
+* `[innerState]` array used by `optional()`/`withDefault()`); the
+* expansion then applies its ordinary rules to the inner parser, whether
+* it carries its own hook, flattened field pairs, or source metadata.
+* Wrappers are path-transparent, so the node keeps the wrapper's path.
+*
+* @internal
+* @since 1.3.0
+*/
+function defineForwardedEffectfulSchedulingNodes(wrapper, inner, adaptState) {
+	if (inner.dependencyMetadata?.source != null) return;
+	Object.defineProperty(wrapper, effectfulSchedulingNodesKey, {
+		value: ((state, parentPath) => [{
+			path: parentPath ?? [],
+			parser: inner,
+			state: adaptState == null ? state : adaptState(state)
+		}]),
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Collects the dependency source IDs demanded by consumers among the
+* given nodes and state subtree.
+*
+* A consumer demands its sources when it has raw input evidence: either a
+* trace entry recorded at its path during parsing, or a legacy
+* `DeferredParseState` embedded in the state subtree.  Consumers without
+* raw input never replay against real dependency values, so their sources
+* are not demanded.
+*
+* @param nodes The direct-child runtime nodes of the owning construct.
+* @param state The construct's state subtree (for legacy deferred states).
+* @param trace The input trace recorded during parsing.
+* @returns The set of demanded dependency source IDs.
+* @internal
+* @since 1.3.0
+*/
+function collectDemandedDependencyIds(nodes, state, trace) {
+	const demanded = /* @__PURE__ */ new Set();
+	for (const node of nodes) {
+		const derived = node.parser.dependencyMetadata?.derived;
+		if (derived == null) continue;
+		const hasRawInput = trace?.get(node.path)?.rawInput != null || extractRawInputFromState(node.state) != null;
+		if (!hasRawInput) continue;
+		for (const id of derived.dependencyIds) demanded.add(id);
+	}
+	collectDeferredDemand(state, demanded, /* @__PURE__ */ new WeakSet());
+	return demanded;
+}
+function collectDeferredDemand(state, demanded, visited) {
+	if (state == null || typeof state !== "object") return;
+	if (visited.has(state)) return;
+	visited.add(state);
+	if (isDeferredParseState(state)) {
+		const ids = state.dependencyIds != null && state.dependencyIds.length > 0 ? state.dependencyIds : [state.dependencyId];
+		for (const id of ids) demanded.add(id);
+		return;
+	}
+	for (const key of Reflect.ownKeys(state)) collectDeferredDemand(state[key], demanded, visited);
+}
+/**
+* Runs effectful source completions (e.g., interactive prompts) serially
+* in declaration order for source nodes whose value is not yet registered.
+*
+* This is the scheduling half of the `completeSource` capability contract:
+*
+* - 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.
+* - 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
+*   `undefined`.  When the node is reusable (a direct child whose field
+*   value is the source value), the result is also returned for reuse by
+*   the owning construct so the node is not completed twice; otherwise the
+*   effectful parser's own run-scoped session cache prevents a second
+*   execution, so nodes that are not reusable are only scheduled when a
+*   session is present.  For a source behind a transform such as `map()`
+*   (`preservesSourceValue: false`), the `completeSource` contract still
+*   yields the pre-transform source value, so registration stays correct
+*   while the field's final value is produced separately.
+* - A failed result (e.g., a cancelled prompt) marks the source as failed
+*   and aborts immediately—later effectful completions do not run.
+*
+* When the run-scoped session policy is `"demand-only"` (the phase-two
+* seed pass), the demanded source IDs from
+* {@link collectDemandedDependencyIds} are added to the session before any
+* completion runs, letting effectful parsers defer when no phase-one
+* consumer demands their value.
+*
+* @param nodes The runtime nodes to schedule, in declaration order.
+* @param state The construct's state subtree (for demand detection).
+* @param runtime The dependency runtime context.
+* @param exec The execution context of the owning construct.
+* @param options Scheduling options.
+* @returns The scheduling result: completed nodes for reuse, or the first
+*   failure.
+* @internal
+* @since 1.3.0
+*/
+async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, options) {
+	const empty = {
+		success: true,
+		completed: []
+	};
+	if (exec == null || exec.phase !== "complete") return empty;
+	const session = exec.effectfulCompletionSession;
+	if (session?.policy === "demand-only") {
+		const demandNodes = options?.demandNodes ?? nodes;
+		const demanded = collectDemandedDependencyIds(demandNodes, state, exec.trace);
+		for (const id of demanded) session.demanded.add(id);
+	}
+	if (session != null) {
+		for (const result of session.results.values()) if (!result.success) return {
+			success: false,
+			error: result.error
+		};
+	}
+	const schedulable = nodes.filter((node) => node.parser.dependencyMetadata?.source?.completeSource != null);
+	if (schedulable.length === 0) return empty;
+	const preexisting = /* @__PURE__ */ new Set();
+	for (const node of schedulable) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source != null && runtime.hasSource(source.sourceId) && session?.effectfulSources.has(source.sourceId) !== true) preexisting.add(source.sourceId);
+	}
+	const completed = [];
+	for (const node of schedulable) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source?.completeSource == null) continue;
+		const pathKey = serializeSchedulingPath(node.path);
+		const priorResult = session?.completedByPath.get(pathKey);
+		if (priorResult != null) {
+			if (source.preservesSourceValue && (options?.isReusable?.(node) ?? true)) completed.push({
+				key: node.path[node.path.length - 1],
+				result: priorResult
+			});
+			continue;
+		}
+		if (preexisting.has(source.sourceId)) continue;
+		const reusable = source.preservesSourceValue && (options?.isReusable?.(node) ?? true);
+		if (!reusable && session == null) continue;
+		const childExec = {
+			...exec,
+			path: node.path
+		};
+		const result = await source.completeSource(node.state, childExec);
+		if (result == null) continue;
+		if (!result.success) {
+			runtime.markSourceFailed(source.sourceId);
+			return {
+				success: false,
+				error: result.error
+			};
+		}
+		if (result.deferred === true) continue;
+		session?.completedByPath.set(pathKey, result);
+		if (reusable) completed.push({
+			key: node.path[node.path.length - 1],
+			result
+		});
+		if (result.value !== void 0) runtime.registerSource(source.sourceId, result.value);
+	}
+	return {
+		success: true,
+		completed
+	};
+}
+/**
+* Serializes a scheduling node path into a stable string key, using
+* length-prefixed segments so no separator escaping is needed.
+*/
+function serializeSchedulingPath(path) {
+	return path.map((segment) => {
+		if (typeof segment === "symbol") {
+			const key = stableSymbolKey(segment);
+			return `y${key.length}:${key}`;
+		}
+		const tag = typeof segment === "number" ? "n" : "s";
+		const text = String(segment);
+		return `${tag}${text.length}:${text}`;
+	}).join("");
+}
+/**
 * Checks if a value is a plain object (not a class instance) for the
 * purpose of recursive state traversal.
 */
@@ -717,4 +929,4 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, 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 };

package/dist/facade.cjs

@@ -116,7 +116,17 @@ function createParseExec(parser) {
 function getCommandPath(exec) {
 	return exec?.commandPath ?? [];
 }
-function createCompleteExec(exec, context) {
+const effectfulSessionOptionsKey = Symbol("@optique/core/facade/effectfulSessionOptionsKey");
+function getEffectfulSessionOption(options) {
+	return options[effectfulSessionOptionsKey];
+}
+function withEffectfulSessionOption(options, session) {
+	return {
+		...options,
+		[effectfulSessionOptionsKey]: session
+	};
+}
+function createCompleteExec(exec, context, session) {
 	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
 	return {
 		...exec,
@@ -124,10 +134,11 @@ function createCompleteExec(exec, context) {
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
 		commandPath: getCommandPath(context.exec) ?? exec.commandPath,
-		trace: context.exec?.trace ?? context.trace ?? exec.trace
+		trace: context.exec?.trace ?? context.trace ?? exec.trace,
+		effectfulCompletionSession: session ?? require_internal_parser.createEffectfulCompletionSession()
 	};
 }
-function attemptParseSync(parser, args, mode = "complete") {
+function attemptParseSync(parser, args, mode = "complete", session) {
 	const shouldUnwrapAnnotatedValue = require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = createParseExec(parser);
 	let context = require_internal_parser.createParserContext({
@@ -166,7 +177,7 @@ function attemptParseSync(parser, args, mode = "complete") {
 		kind: "success",
 		value: void 0
 	};
-	const endResult = parser.complete(context.state, createCompleteExec(exec, context));
+	const endResult = parser.complete(context.state, createCompleteExec(exec, context, session));
 	if (!endResult.success) return {
 		kind: "failure",
 		error: endResult.error,
@@ -180,7 +191,7 @@ function attemptParseSync(parser, args, mode = "complete") {
 		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	};
 }
-async function attemptParseAsync(parser, args, mode = "complete") {
+async function attemptParseAsync(parser, args, mode = "complete", session) {
 	const shouldUnwrapAnnotatedValue = require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = createParseExec(parser);
 	let context = require_internal_parser.createParserContext({
@@ -219,7 +230,7 @@ async function attemptParseAsync(parser, args, mode = "complete") {
 		kind: "success",
 		value: void 0
 	};
-	const endResult = await parser.complete(context.state, createCompleteExec(exec, context));
+	const endResult = await parser.complete(context.state, createCompleteExec(exec, context, session));
 	if (!endResult.success) return {
 		kind: "failure",
 		error: endResult.error,
@@ -233,7 +244,7 @@ async function attemptParseAsync(parser, args, mode = "complete") {
 		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	};
 }
-function createPhase2SeedExec(parser, context) {
+function createPhase2SeedExec(parser, context, session) {
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
@@ -248,7 +259,8 @@ function createPhase2SeedExec(parser, context) {
 		dependencyRuntime: runtime,
 		dependencyRegistry: runtime.registry,
 		commandPath: getCommandPath(context.exec),
-		trace: context.exec?.trace ?? context.trace ?? exec.trace
+		trace: context.exec?.trace ?? context.trace ?? exec.trace,
+		effectfulCompletionSession: session ?? require_internal_parser.createEffectfulCompletionSession()
 	};
 }
 function createPhase2SeedContext(parser, args) {
@@ -265,27 +277,27 @@ function createPhase2SeedContext(parser, args) {
 		optionsTerminated: false
 	}, exec);
 }
-function extractPhase2SeedSync(parser, args) {
+function extractPhase2SeedSync(parser, args, session) {
 	let context = createPhase2SeedContext(parser, args);
 	do {
 		const result = parser.parse(context);
-		if (!result.success) return require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		if (!result.success) return require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context, session));
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (isBufferUnchanged(previousBuffer, context.buffer)) return require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context, session));
 	} while (context.buffer.length > 0);
-	return require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+	return require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context, session));
 }
-async function extractPhase2SeedAsync(parser, args) {
+async function extractPhase2SeedAsync(parser, args, session) {
 	let context = createPhase2SeedContext(parser, args);
 	do {
 		const result = await parser.parse(context);
-		if (!result.success) return await require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		if (!result.success) return await require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context, session));
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (isBufferUnchanged(previousBuffer, context.buffer)) return await require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return await require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context, session));
 	} while (context.buffer.length > 0);
-	return await require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+	return await require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context, session));
 }
 function getMetaCommandAliases(names) {
 	const [, firstAlias, ...restAliases] = names;
@@ -1246,7 +1258,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	};
 	const parserMode = parser.mode;
 	return require_mode_dispatch.dispatchByMode(parserMode, () => {
-		const attempted = attemptParseSync(parser, args);
+		const attempted = attemptParseSync(parser, args, "complete", getEffectfulSessionOption(options));
 		const classified = attempted.kind === "success" ? {
 			type: "success",
 			value: attempted.value
@@ -1255,7 +1267,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		if (handled instanceof Promise) throw new RunParserError("Synchronous parser returned async result.");
 		return handled;
 	}, async () => {
-		const attempted = await attemptParseAsync(parser, args);
+		const attempted = await attemptParseAsync(parser, args, "complete", getEffectfulSessionOption(options));
 		const classified = attempted.kind === "success" ? {
 			type: "success",
 			value: attempted.value
@@ -1603,16 +1615,24 @@ async function runWithBody(parser, programName, contexts, args, options) {
 		if (parser.mode === "async") return runParser(augmentedParser1, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser1, programName, args, options));
 	}
-	const firstPassSeed = await require_mode_dispatch.dispatchByMode(parser.mode, () => extractPhase2SeedSync(augmentedParser1, args), () => extractPhase2SeedAsync(augmentedParser1, args));
+	const seedSession = require_internal_parser.createEffectfulCompletionSession("demand-only");
+	const finalSession = {
+		...seedSession,
+		policy: "eager",
+		effectfulSources: /* @__PURE__ */ new Set(),
+		completedByPath: /* @__PURE__ */ new Map()
+	};
+	const sessionOptions = withEffectfulSessionOption(options, finalSession);
+	const firstPassSeed = await require_mode_dispatch.dispatchByMode(parser.mode, () => extractPhase2SeedSync(augmentedParser1, args, seedSession), () => extractPhase2SeedAsync(augmentedParser1, args, seedSession));
 	if (firstPassSeed == null) {
 		const fallbackParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-		if (parser.mode === "async") return runParser(fallbackParser, programName, args, options);
-		return Promise.resolve(runParser(fallbackParser, programName, args, options));
+		if (parser.mode === "async") return runParser(fallbackParser, programName, args, sessionOptions);
+		return Promise.resolve(runParser(fallbackParser, programName, args, sessionOptions));
 	}
 	const { annotations: finalAnnotations } = await collectFinalAnnotations(contexts, phase1Snapshots, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-	if (parser.mode === "async") return runParser(augmentedParser2, programName, args, options);
-	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
+	if (parser.mode === "async") return runParser(augmentedParser2, programName, args, sessionOptions);
+	return Promise.resolve(runParser(augmentedParser2, programName, args, sessionOptions));
 }
 /**
 * Runs a parser with multiple source contexts.
@@ -1718,14 +1738,22 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 	}
 	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
 	if (!needsTwoPhase) return runParser(augmentedParser1, programName, args, options);
-	const firstPassSeed = extractPhase2SeedSync(augmentedParser1, args);
+	const seedSession = require_internal_parser.createEffectfulCompletionSession("demand-only");
+	const finalSession = {
+		...seedSession,
+		policy: "eager",
+		effectfulSources: /* @__PURE__ */ new Set(),
+		completedByPath: /* @__PURE__ */ new Map()
+	};
+	const sessionOptions = withEffectfulSessionOption(options, finalSession);
+	const firstPassSeed = extractPhase2SeedSync(augmentedParser1, args, seedSession);
 	if (firstPassSeed == null) {
 		const fallbackParser = injectAnnotationsIntoParser(parser, phase1Annotations);
-		return runParser(fallbackParser, programName, args, options);
+		return runParser(fallbackParser, programName, args, sessionOptions);
 	}
 	const { annotations: finalAnnotations } = collectFinalAnnotationsSync(contexts, phase1Snapshots, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
-	return runParser(augmentedParser2, programName, args, options);
+	return runParser(augmentedParser2, programName, args, sessionOptions);
 }
 /**
 * Runs a synchronous parser with multiple source contexts.