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

package/dist/facade.js

@@ -6,7 +6,7 @@ import { formatDocPage } from "./doc.js";
 import { dispatchByMode } from "./internal/mode-dispatch.js";
 import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
 import { createInputTrace } from "./input-trace.js";
-import { createParserContext, getDocPage } from "./internal/parser.js";
+import { createEffectfulCompletionSession, createParserContext, getDocPage } from "./internal/parser.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { allowDuplicateLeadingCommandNamesKey, hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { completeOrExtractPhase2Seed } from "./phase2-seed.js";
@@ -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 = 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 ?? createEffectfulCompletionSession()
 	};
 }
-function attemptParseSync(parser, args, mode = "complete") {
+function attemptParseSync(parser, args, mode = "complete", session) {
 	const shouldUnwrapAnnotatedValue = isInjectedAnnotationWrapper(parser.initialState);
 	const exec = createParseExec(parser);
 	let context = 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 ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	};
 }
-async function attemptParseAsync(parser, args, mode = "complete") {
+async function attemptParseAsync(parser, args, mode = "complete", session) {
 	const shouldUnwrapAnnotatedValue = isInjectedAnnotationWrapper(parser.initialState);
 	const exec = createParseExec(parser);
 	let context = 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 ? 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 ?? 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 completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		if (!result.success) return completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context, session));
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (isBufferUnchanged(previousBuffer, context.buffer)) return completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context, session));
 	} while (context.buffer.length > 0);
-	return completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+	return 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 completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		if (!result.success) return await completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context, session));
 		const previousBuffer = context.buffer;
 		context = result.next;
-		if (isBufferUnchanged(previousBuffer, context.buffer)) return await completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+		if (isBufferUnchanged(previousBuffer, context.buffer)) return await completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context, session));
 	} while (context.buffer.length > 0);
-	return await completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
+	return await 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 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 dispatchByMode(parser.mode, () => extractPhase2SeedSync(augmentedParser1, args), () => extractPhase2SeedAsync(augmentedParser1, args));
+	const seedSession = createEffectfulCompletionSession("demand-only");
+	const finalSession = {
+		...seedSession,
+		policy: "eager",
+		effectfulSources: /* @__PURE__ */ new Set(),
+		completedByPath: /* @__PURE__ */ new Map()
+	};
+	const sessionOptions = withEffectfulSessionOption(options, finalSession);
+	const firstPassSeed = await 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 = 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.

package/dist/index.d.cts

@@ -4,7 +4,7 @@ import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLin
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.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";
+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";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.cjs";
@@ -12,4 +12,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.cjs";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLin
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid } from "./valueparser.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";
+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";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
@@ -12,4 +12,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandListMode, CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandListMode, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DeferredValue, DeferredValueOptions, DeferredValueSource, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TransformMapping, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, biject, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, deferredValue, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredValue, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, regExp, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, transform, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

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 };