@optique/core 1.0.0-dev.1616 → 1.0.0-dev.1658

package/dist/parser.cjs

@@ -1,16 +1,29 @@
 const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
-const require_dependency = require('./dependency.cjs');
-const require_dependency_runtime = require('./dependency-runtime.cjs');
-const require_mode_dispatch = require('./mode-dispatch.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
-const require_constructs = require('./constructs.cjs');
+const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_input_trace = require('./input-trace.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_primitives = require('./primitives.cjs');
+const require_dependency_runtime = require('./dependency-runtime.cjs');
+const require_constructs = require('./constructs.cjs');
 
 //#region src/parser.ts
 /**
+* Internal marker for wrappers whose `{ hasCliValue: false }` states should
+* be treated as unmatched dependency-source states during completion-time
+* Phase 1.
+*
+* 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.
+*
+* @internal
+*/
+const unmatchedNonCliDependencySourceStateMarker = Symbol.for("@optique/core/parser/unmatchedNonCliDependencySourceStateMarker");
+/**
 * Creates a {@link ParserContext} from a {@link ParseFrame} and an
 * {@link ExecutionContext}.  The returned object provides both structured
 * access (`frame`, `exec`) and flat access (`buffer`, `state`, etc.)
@@ -25,6 +38,7 @@ const require_primitives = require('./primitives.cjs');
 function createParserContext(frame, exec) {
 	return {
 		exec,
+		trace: exec.trace,
 		buffer: frame.buffer,
 		state: frame.state,
 		optionsTerminated: frame.optionsTerminated,
@@ -55,6 +69,8 @@ function injectAnnotationsIntoState(state, options) {
 *          successful or not.  If successful, it contains the parsed value of
 *          type `T`.  If not, it contains an error message describing the
 *          failure.
+* @throws {TypeError} When a synchronous dependency source extractor returns a
+*         thenable during completion-time dependency seeding.
 * @since 0.9.0 Renamed from the original `parse` function which now delegates
 *              to this for sync parsers.
 * @since 0.10.0 Added optional `options` parameter for annotations support.
@@ -65,7 +81,8 @@ function parseSync(parser, args, options) {
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
-		path: []
+		path: [],
+		trace: require_input_trace.createInputTrace()
 	};
 	let context = createParserContext({
 		buffer: args,
@@ -86,14 +103,14 @@ function parseSync(parser, args, options) {
 		};
 	} while (context.buffer.length > 0);
 	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
-	const resolvedState = require_dependency.isDeferredParseState(context.state) ? require_dependency_runtime.resolveStateWithRuntime(context.state, runtime) : context.state;
 	const completeExec = {
 		...exec,
 		phase: "complete",
 		dependencyRuntime: runtime,
-		dependencyRegistry: runtime.registry
+		dependencyRegistry: runtime.registry,
+		trace: context.exec?.trace ?? context.trace ?? exec.trace
 	};
-	const endResult = parser.complete(resolvedState, completeExec);
+	const endResult = parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
 		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
@@ -136,7 +153,8 @@ async function parseAsync(parser, args, options) {
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
-		path: []
+		path: [],
+		trace: require_input_trace.createInputTrace()
 	};
 	let context = createParserContext({
 		buffer: args,
@@ -157,14 +175,14 @@ async function parseAsync(parser, args, options) {
 		};
 	} while (context.buffer.length > 0);
 	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
-	const resolvedState = require_dependency.isDeferredParseState(context.state) ? await require_dependency_runtime.resolveStateWithRuntimeAsync(context.state, runtime) : context.state;
 	const completeExec = {
 		...exec,
 		phase: "complete",
 		dependencyRuntime: runtime,
-		dependencyRegistry: runtime.registry
+		dependencyRegistry: runtime.registry,
+		trace: context.exec?.trace ?? context.trace ?? exec.trace
 	};
-	const endResult = await parser.complete(resolvedState, completeExec);
+	const endResult = await parser.complete(context.state, completeExec);
 	return endResult.success ? {
 		success: true,
 		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
@@ -195,6 +213,8 @@ async function parseAsync(parser, args, options) {
 * @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns A {@link Result} object (for sync) or Promise thereof (for async)
 *          indicating whether the parsing was successful or not.
+* @throws {TypeError} When a synchronous dependency source extractor returns a
+*         thenable during completion-time dependency seeding.
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
 function parse(parser, args, options) {
@@ -232,6 +252,8 @@ function parse(parser, args, options) {
 * const suggestions2 = suggestSync(parser, ["-v", "--format="]);
 * // Returns: [{ text: "--format=json" }, { text: "--format=yaml" }]
 * ```
+* @throws {TypeError} When a synchronous dependency source extractor returns a
+*         thenable during suggestion seeding.
 * @since 0.6.0
 * @since 0.9.0 Renamed from the original `suggest` function.
 * @since 0.10.0 Added optional `options` parameter for annotations support.
@@ -247,16 +269,17 @@ function suggestSync(parser, args, options) {
 	}, {
 		usage: parser.usage,
 		phase: "suggest",
-		path: []
+		path: [],
+		trace: require_input_trace.createInputTrace()
 	});
 	while (context.buffer.length > 0) {
 		const result = parser.parse(context);
-		if (!result.success) return Array.from(parser.suggest(withSuggestRuntime(context), prefix));
+		if (!result.success) return Array.from(parser.suggest(withSuggestRuntime(parser, context), prefix));
 		const previousBuffer = context.buffer;
 		context = result.next;
 		if (isBufferUnchanged(previousBuffer, context.buffer)) return [];
 	}
-	return Array.from(parser.suggest(withSuggestRuntime(context), prefix));
+	return Array.from(parser.suggest(withSuggestRuntime(parser, context), prefix));
 }
 /**
 * Creates a dependency runtime from the current parser state and returns
@@ -265,19 +288,54 @@ function suggestSync(parser, args, options) {
 * a context with a dependency registry.
 * @internal
 */
-function withSuggestRuntime(context) {
+function withSuggestRuntime(parser, context) {
+	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
+	const nodes = getParserSuggestRuntimeNodes(parser, context.state, context.exec?.path ?? []);
+	if (nodes.length > 0) require_dependency_runtime.collectExplicitSourceValues(nodes, runtime);
+	return {
+		...context,
+		dependencyRegistry: runtime.registry,
+		exec: context.exec ? {
+			...context.exec,
+			dependencyRuntime: runtime,
+			dependencyRegistry: runtime.registry
+		} : void 0
+	};
+}
+async function withSuggestRuntimeAsync(parser, context) {
 	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
-	require_dependency_runtime.collectSourcesFromState(context.state, runtime);
+	const nodes = getParserSuggestRuntimeNodes(parser, context.state, context.exec?.path ?? []);
+	if (nodes.length > 0) await require_dependency_runtime.collectExplicitSourceValuesAsync(nodes, runtime);
 	return {
 		...context,
 		dependencyRegistry: runtime.registry,
 		exec: context.exec ? {
 			...context.exec,
+			dependencyRuntime: runtime,
 			dependencyRegistry: runtime.registry
 		} : void 0
 	};
 }
 /**
+* Returns suggest-time runtime nodes for a parser, falling back to the
+* parser's own source metadata when it does not expose a custom hook.
+*
+* @param parser The parser whose suggest-time runtime nodes should be resolved.
+* @param state The current parser state.
+* @param path The path to this parser within the parse tree.
+* @returns The runtime nodes used to seed suggest-time dependency resolution.
+* @internal
+*/
+function getParserSuggestRuntimeNodes(parser, state, path) {
+	if (typeof parser.getSuggestRuntimeNodes === "function") return parser.getSuggestRuntimeNodes(state, path);
+	if (parser.dependencyMetadata?.source == null) return [];
+	return [{
+		path,
+		parser,
+		state
+	}];
+}
+/**
 * Generates command-line suggestions based on current parsing state.
 * This function processes the input arguments up to the last argument,
 * then calls the parser's suggest method with the remaining prefix.
@@ -308,12 +366,13 @@ async function suggestAsync(parser, args, options) {
 	}, {
 		usage: parser.usage,
 		phase: "suggest",
-		path: []
+		path: [],
+		trace: require_input_trace.createInputTrace()
 	});
 	while (context.buffer.length > 0) {
 		const result = await parser.parse(context);
 		if (!result.success) {
-			const ctx$1 = withSuggestRuntime(context);
+			const ctx$1 = await withSuggestRuntimeAsync(parser, context);
 			const suggestions$1 = [];
 			for await (const suggestion of parser.suggest(ctx$1, prefix)) suggestions$1.push(suggestion);
 			return suggestions$1;
@@ -322,7 +381,7 @@ async function suggestAsync(parser, args, options) {
 		context = result.next;
 		if (isBufferUnchanged(previousBuffer, context.buffer)) return [];
 	}
-	const ctx = withSuggestRuntime(context);
+	const ctx = await withSuggestRuntimeAsync(parser, context);
 	const suggestions = [];
 	for await (const suggestion of parser.suggest(ctx, prefix)) suggestions.push(suggestion);
 	return suggestions;
@@ -347,6 +406,8 @@ async function suggestAsync(parser, args, options) {
 * @param options Optional {@link ParseOptions} for customizing parsing behavior.
 * @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
 *          (for async) containing completion candidates.
+* @throws {TypeError} When a synchronous dependency source extractor returns a
+*         thenable during suggestion seeding.
 * @since 0.6.0
 * @since 0.10.0 Added optional `options` parameter for annotations support.
 */
@@ -574,6 +635,7 @@ exports.flag = require_primitives.flag;
 exports.getDocPage = getDocPage;
 exports.getDocPageAsync = getDocPageAsync;
 exports.getDocPageSync = getDocPageSync;
+exports.getParserSuggestRuntimeNodes = getParserSuggestRuntimeNodes;
 exports.group = require_constructs.group;
 exports.longestMatch = require_constructs.longestMatch;
 exports.map = require_modifiers.map;
@@ -592,4 +654,5 @@ exports.suggest = suggest;
 exports.suggestAsync = suggestAsync;
 exports.suggestSync = suggestSync;
 exports.tuple = require_constructs.tuple;
+exports.unmatchedNonCliDependencySourceStateMarker = unmatchedNonCliDependencySourceStateMarker;
 exports.withDefault = require_modifiers.withDefault;

package/dist/parser.d.cts

@@ -5,7 +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 } from "./dependency-runtime.cjs";
+import { DependencyRuntimeContext, RuntimeNode } from "./dependency-runtime.cjs";
+import { InputTrace } from "./input-trace.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.cjs";
@@ -150,6 +151,14 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * state when parsing starts.
    */
   readonly initialState: TState;
+  /**
+   * Internal marker for wrappers whose `{ hasCliValue: false }` states should
+   * be treated as unmatched dependency-source states during completion-time
+   * Phase 1.
+   *
+   * @internal
+   */
+  readonly [unmatchedNonCliDependencySourceStateMarker]?: true;
   /**
    * Parses the input context and returns a result indicating
    * whether the parsing was successful or not.
@@ -258,9 +267,22 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * capabilities.  Used by the dependency runtime to resolve dependencies
    * without relying on state-shape protocols.
    * @internal
-   * @since 1.0.0
    */
   readonly dependencyMetadata?: ParserDependencyMetadata;
+  /**
+   * Internal hook for top-level suggest-time dependency seeding.
+   *
+   * Wrapper parsers can expose the active parser/state pairs that should be
+   * scanned when `suggestSync()` or `suggestAsync()` builds a fresh dependency
+   * runtime.  When omitted, only this parser's own dependency source metadata
+   * is considered.
+   *
+   * @param state The current parser state.
+   * @param path The path to this parser within the parse tree.
+   * @returns Runtime nodes to seed into the suggestion-time dependency runtime.
+   * @internal
+   */
+  getSuggestRuntimeNodes?(state: TState, path: readonly PropertyKey[]): readonly RuntimeNode[];
 }
 /**
  * Parser-local frame data containing the input buffer and parser state.
@@ -312,6 +334,16 @@ interface ExecutionContext {
    * resolution and completion.
    */
   readonly path: readonly PropertyKey[];
+  /**
+   * Immutable trace of raw primitive inputs recorded during parsing.
+   *
+   * Primitives append trace entries keyed by {@link path}, allowing later
+   * completion phases to replay derived parsers with the resolved
+   * dependency values.
+   *
+   * @internal
+   */
+  readonly trace?: InputTrace;
   /**
    * A registry containing resolved dependency values from DependencySource
    * parsers.
@@ -322,7 +354,6 @@ interface ExecutionContext {
    * The dependency runtime context for dependency resolution.
    * Coexists with `dependencyRegistry` during the transition period.
    * @internal
-   * @since 1.0.0
    */
   readonly dependencyRuntime?: DependencyRuntimeContext;
   /**
@@ -341,10 +372,33 @@ interface ExecutionContext {
    *
    * @see https://github.com/dahlia/optique/issues/762
    * @internal
-   * @since 1.0.0
    */
   readonly preCompletedByParser?: ReadonlyMap<string | symbol, unknown>;
+  /**
+   * Field names that should be ignored when a construct seeds dependency
+   * sources from child state during completion.
+   *
+   * Used by outer `merge()` completions to suppress ambiguous duplicate
+   * keys while still allowing the child parser to finish its own value
+   * completion.
+   *
+   * @internal
+   */
+  readonly excludedSourceFields?: ReadonlySet<string | symbol>;
 }
+/**
+ * Internal marker for wrappers whose `{ hasCliValue: false }` states should
+ * be treated as unmatched dependency-source states during completion-time
+ * Phase 1.
+ *
+ * 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.
+ *
+ * @internal
+ */
+declare const unmatchedNonCliDependencySourceStateMarker: unique symbol;
 /**
  * The context of the parser, which includes the input buffer and the state.
  *
@@ -364,6 +418,15 @@ interface ParserContext<TState> {
    * @since 1.0.0
    */
   readonly exec?: ExecutionContext;
+  /**
+   * Immutable trace of raw primitive inputs recorded during parsing.
+   *
+   * Preserved as a flat compatibility field so wrapper parsers can forward
+   * trace data even when they rebuild the parser context without {@link exec}.
+   *
+   * @since 1.0.0
+   */
+  readonly trace?: InputTrace;
   /**
    * The array of input strings that the parser is currently processing.
    */
@@ -557,6 +620,8 @@ type Result<T> = {
  *          successful or not.  If successful, it contains the parsed value of
  *          type `T`.  If not, it contains an error message describing the
  *          failure.
+ * @throws {TypeError} When a synchronous dependency source extractor returns a
+ *         thenable during completion-time dependency seeding.
  * @since 0.9.0 Renamed from the original `parse` function which now delegates
  *              to this for sync parsers.
  * @since 0.10.0 Added optional `options` parameter for annotations support.
@@ -602,6 +667,8 @@ declare function parseAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly
  * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A {@link Result} object (for sync) or Promise thereof (for async)
  *          indicating whether the parsing was successful or not.
+ * @throws {TypeError} When a synchronous dependency source extractor returns a
+ *         thenable during completion-time dependency seeding.
  * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
 declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly string[], options?: ParseOptions): ModeValue<M, Result<T>>;
@@ -637,11 +704,24 @@ declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: r
  * const suggestions2 = suggestSync(parser, ["-v", "--format="]);
  * // Returns: [{ text: "--format=json" }, { text: "--format=yaml" }]
  * ```
+ * @throws {TypeError} When a synchronous dependency source extractor returns a
+ *         thenable during suggestion seeding.
  * @since 0.6.0
  * @since 0.9.0 Renamed from the original `suggest` function.
  * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
 declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readonly [string, ...readonly string[]], options?: ParseOptions): readonly Suggestion[];
+/**
+ * Returns suggest-time runtime nodes for a parser, falling back to the
+ * parser's own source metadata when it does not expose a custom hook.
+ *
+ * @param parser The parser whose suggest-time runtime nodes should be resolved.
+ * @param state The current parser state.
+ * @param path The path to this parser within the parse tree.
+ * @returns The runtime nodes used to seed suggest-time dependency resolution.
+ * @internal
+ */
+declare function getParserSuggestRuntimeNodes<TState>(parser: Parser<Mode, unknown, TState>, state: TState, path: readonly PropertyKey[]): readonly RuntimeNode[];
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -683,6 +763,8 @@ declare function suggestAsync<T>(parser: Parser<Mode, T, unknown>, args: readonl
  * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
  *          (for async) containing completion candidates.
+ * @throws {TypeError} When a synchronous dependency source extractor returns a
+ *         thenable during suggestion seeding.
  * @since 0.6.0
  * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
@@ -774,4 +856,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 { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, createParserContext, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, createParserContext, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };

package/dist/parser.d.ts

@@ -5,7 +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 } from "./dependency-runtime.js";
+import { DependencyRuntimeContext, RuntimeNode } from "./dependency-runtime.js";
+import { InputTrace } from "./input-trace.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
@@ -150,6 +151,14 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * state when parsing starts.
    */
   readonly initialState: TState;
+  /**
+   * Internal marker for wrappers whose `{ hasCliValue: false }` states should
+   * be treated as unmatched dependency-source states during completion-time
+   * Phase 1.
+   *
+   * @internal
+   */
+  readonly [unmatchedNonCliDependencySourceStateMarker]?: true;
   /**
    * Parses the input context and returns a result indicating
    * whether the parsing was successful or not.
@@ -258,9 +267,22 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * capabilities.  Used by the dependency runtime to resolve dependencies
    * without relying on state-shape protocols.
    * @internal
-   * @since 1.0.0
    */
   readonly dependencyMetadata?: ParserDependencyMetadata;
+  /**
+   * Internal hook for top-level suggest-time dependency seeding.
+   *
+   * Wrapper parsers can expose the active parser/state pairs that should be
+   * scanned when `suggestSync()` or `suggestAsync()` builds a fresh dependency
+   * runtime.  When omitted, only this parser's own dependency source metadata
+   * is considered.
+   *
+   * @param state The current parser state.
+   * @param path The path to this parser within the parse tree.
+   * @returns Runtime nodes to seed into the suggestion-time dependency runtime.
+   * @internal
+   */
+  getSuggestRuntimeNodes?(state: TState, path: readonly PropertyKey[]): readonly RuntimeNode[];
 }
 /**
  * Parser-local frame data containing the input buffer and parser state.
@@ -312,6 +334,16 @@ interface ExecutionContext {
    * resolution and completion.
    */
   readonly path: readonly PropertyKey[];
+  /**
+   * Immutable trace of raw primitive inputs recorded during parsing.
+   *
+   * Primitives append trace entries keyed by {@link path}, allowing later
+   * completion phases to replay derived parsers with the resolved
+   * dependency values.
+   *
+   * @internal
+   */
+  readonly trace?: InputTrace;
   /**
    * A registry containing resolved dependency values from DependencySource
    * parsers.
@@ -322,7 +354,6 @@ interface ExecutionContext {
    * The dependency runtime context for dependency resolution.
    * Coexists with `dependencyRegistry` during the transition period.
    * @internal
-   * @since 1.0.0
    */
   readonly dependencyRuntime?: DependencyRuntimeContext;
   /**
@@ -341,10 +372,33 @@ interface ExecutionContext {
    *
    * @see https://github.com/dahlia/optique/issues/762
    * @internal
-   * @since 1.0.0
    */
   readonly preCompletedByParser?: ReadonlyMap<string | symbol, unknown>;
+  /**
+   * Field names that should be ignored when a construct seeds dependency
+   * sources from child state during completion.
+   *
+   * Used by outer `merge()` completions to suppress ambiguous duplicate
+   * keys while still allowing the child parser to finish its own value
+   * completion.
+   *
+   * @internal
+   */
+  readonly excludedSourceFields?: ReadonlySet<string | symbol>;
 }
+/**
+ * Internal marker for wrappers whose `{ hasCliValue: false }` states should
+ * be treated as unmatched dependency-source states during completion-time
+ * Phase 1.
+ *
+ * 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.
+ *
+ * @internal
+ */
+declare const unmatchedNonCliDependencySourceStateMarker: unique symbol;
 /**
  * The context of the parser, which includes the input buffer and the state.
  *
@@ -364,6 +418,15 @@ interface ParserContext<TState> {
    * @since 1.0.0
    */
   readonly exec?: ExecutionContext;
+  /**
+   * Immutable trace of raw primitive inputs recorded during parsing.
+   *
+   * Preserved as a flat compatibility field so wrapper parsers can forward
+   * trace data even when they rebuild the parser context without {@link exec}.
+   *
+   * @since 1.0.0
+   */
+  readonly trace?: InputTrace;
   /**
    * The array of input strings that the parser is currently processing.
    */
@@ -557,6 +620,8 @@ type Result<T> = {
  *          successful or not.  If successful, it contains the parsed value of
  *          type `T`.  If not, it contains an error message describing the
  *          failure.
+ * @throws {TypeError} When a synchronous dependency source extractor returns a
+ *         thenable during completion-time dependency seeding.
  * @since 0.9.0 Renamed from the original `parse` function which now delegates
  *              to this for sync parsers.
  * @since 0.10.0 Added optional `options` parameter for annotations support.
@@ -602,6 +667,8 @@ declare function parseAsync<T>(parser: Parser<Mode, T, unknown>, args: readonly
  * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns A {@link Result} object (for sync) or Promise thereof (for async)
  *          indicating whether the parsing was successful or not.
+ * @throws {TypeError} When a synchronous dependency source extractor returns a
+ *         thenable during completion-time dependency seeding.
  * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
 declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: readonly string[], options?: ParseOptions): ModeValue<M, Result<T>>;
@@ -637,11 +704,24 @@ declare function parse<M extends Mode, T>(parser: Parser<M, T, unknown>, args: r
  * const suggestions2 = suggestSync(parser, ["-v", "--format="]);
  * // Returns: [{ text: "--format=json" }, { text: "--format=yaml" }]
  * ```
+ * @throws {TypeError} When a synchronous dependency source extractor returns a
+ *         thenable during suggestion seeding.
  * @since 0.6.0
  * @since 0.9.0 Renamed from the original `suggest` function.
  * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
 declare function suggestSync<T>(parser: Parser<"sync", T, unknown>, args: readonly [string, ...readonly string[]], options?: ParseOptions): readonly Suggestion[];
+/**
+ * Returns suggest-time runtime nodes for a parser, falling back to the
+ * parser's own source metadata when it does not expose a custom hook.
+ *
+ * @param parser The parser whose suggest-time runtime nodes should be resolved.
+ * @param state The current parser state.
+ * @param path The path to this parser within the parse tree.
+ * @returns The runtime nodes used to seed suggest-time dependency resolution.
+ * @internal
+ */
+declare function getParserSuggestRuntimeNodes<TState>(parser: Parser<Mode, unknown, TState>, state: TState, path: readonly PropertyKey[]): readonly RuntimeNode[];
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -683,6 +763,8 @@ declare function suggestAsync<T>(parser: Parser<Mode, T, unknown>, args: readonl
  * @param options Optional {@link ParseOptions} for customizing parsing behavior.
  * @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
  *          (for async) containing completion candidates.
+ * @throws {TypeError} When a synchronous dependency source extractor returns a
+ *         thenable during suggestion seeding.
  * @since 0.6.0
  * @since 0.10.0 Added optional `options` parameter for annotations support.
  */
@@ -774,4 +856,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 { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, createParserContext, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, ExecutionContext, ExecutionPhase, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, createParserContext, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };