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

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,53 @@ 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;
+/**
+ * Internal marker for parsers that want parent-state annotations injected
+ * directly into rebuilt child states instead of relying on structural
+ * inheritance.
+ *
+ * Wrappers like `bindConfig()`, `bindEnv()`, and `prompt()` opt in because
+ * their fallback contracts depend on carrying annotations through wrapper
+ * state objects during parse, complete, and suggest.
+ *
+ * @internal
+ */
+declare const inheritParentAnnotationsKey: unique symbol;
+/**
+ * Internal marker for wrapper parsers that should only treat annotation-only
+ * primitive wrapper states as completable when a nested source-binding wrapper
+ * produced them.
+ *
+ * @internal
+ */
+declare const annotationWrapperRequiresSourceBindingKey: unique symbol;
 /**
  * The context of the parser, which includes the input buffer and the state.
  *
@@ -364,6 +438,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 +640,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 +687,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 +724,57 @@ 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[];
+/**
+ * Returns wrapper-aware suggest-time runtime nodes for parsers that delegate
+ * to an inner parser while also exposing their own source metadata.
+ *
+ * The inner parser's nodes are always preserved so nested wrappers and
+ * constructs can continue to seed the dependency runtime recursively. When
+ * the outer parser itself owns source metadata, its `(path, parser, state)`
+ * node is appended so outer precedence rules still apply.
+ *
+ * @internal
+ */
+declare function getDelegatingSuggestRuntimeNodes<TInnerState>(innerParser: Parser<Mode, unknown, TInnerState>, outerParser: Parser<Mode, unknown, unknown>, state: unknown, path: readonly PropertyKey[], innerState: TInnerState, outerPosition?: "append" | "prepend"): readonly RuntimeNode[];
+/**
+ * Composes source metadata for a wrapper parser while preserving any derived
+ * or transform capabilities from the inner parser unchanged.
+ *
+ * @internal
+ */
+declare function composeWrappedSourceMetadata(dependencyMetadata: ParserDependencyMetadata | undefined, wrapSource: (source: NonNullable<ParserDependencyMetadata["source"]>) => NonNullable<ParserDependencyMetadata["source"]>): ParserDependencyMetadata | undefined;
+/**
+ * Marks a parser as inheriting parent-state annotations through wrapper-state
+ * reconstruction.
+ *
+ * @internal
+ */
+declare function defineInheritedAnnotationParser(parser: object): void;
+/**
+ * Marks a wrapper parser as requiring a real source-binding state before
+ * annotation-only primitive wrappers should trigger completion.
+ *
+ * @internal
+ */
+declare function defineSourceBindingOnlyAnnotationCompletionParser(parser: object): void;
 /**
  * Generates command-line suggestions based on current parsing state.
  * This function processes the input arguments up to the last argument,
@@ -683,6 +816,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 +909,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, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };

package/dist/parser.js

@@ -1,16 +1,49 @@
 import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { cloneMessage, message } from "./message.js";
-import { isDeferredParseState } from "./dependency.js";
-import { collectSourcesFromState, createDependencyRuntimeContext, resolveStateWithRuntime, resolveStateWithRuntimeAsync } from "./dependency-runtime.js";
-import { dispatchByMode } from "./mode-dispatch.js";
 import { cloneUsage, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, isDocEntryHidden } from "./doc.js";
-import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { dispatchByMode } from "./mode-dispatch.js";
+import { createInputTrace } from "./input-trace.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
+import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
+import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 
 //#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");
+/**
+* Internal marker for parsers that want parent-state annotations injected
+* directly into rebuilt child states instead of relying on structural
+* inheritance.
+*
+* Wrappers like `bindConfig()`, `bindEnv()`, and `prompt()` opt in because
+* their fallback contracts depend on carrying annotations through wrapper
+* state objects during parse, complete, and suggest.
+*
+* @internal
+*/
+const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
+/**
+* Internal marker for wrapper parsers that should only treat annotation-only
+* primitive wrapper states as completable when a nested source-binding wrapper
+* produced them.
+*
+* @internal
+*/
+const annotationWrapperRequiresSourceBindingKey = Symbol.for("@optique/core/annotationWrapperRequiresSourceBinding");
+/**
 * 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 +58,7 @@ import { argument, command, constant, fail, flag, option, passThrough } from "./
 function createParserContext(frame, exec) {
 	return {
 		exec,
+		trace: exec.trace,
 		buffer: frame.buffer,
 		state: frame.state,
 		optionsTerminated: frame.optionsTerminated,
@@ -55,6 +89,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 +101,8 @@ function parseSync(parser, args, options) {
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
-		path: []
+		path: [],
+		trace: createInputTrace()
 	};
 	let context = createParserContext({
 		buffer: args,
@@ -86,14 +123,14 @@ function parseSync(parser, args, options) {
 		};
 	} while (context.buffer.length > 0);
 	const runtime = createDependencyRuntimeContext();
-	const resolvedState = isDeferredParseState(context.state) ? 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 ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
@@ -136,7 +173,8 @@ async function parseAsync(parser, args, options) {
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
-		path: []
+		path: [],
+		trace: createInputTrace()
 	};
 	let context = createParserContext({
 		buffer: args,
@@ -157,14 +195,14 @@ async function parseAsync(parser, args, options) {
 		};
 	} while (context.buffer.length > 0);
 	const runtime = createDependencyRuntimeContext();
-	const resolvedState = isDeferredParseState(context.state) ? await 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 ? unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value,
@@ -195,6 +233,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 +272,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 +289,17 @@ function suggestSync(parser, args, options) {
 	}, {
 		usage: parser.usage,
 		phase: "suggest",
-		path: []
+		path: [],
+		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,18 +308,113 @@ function suggestSync(parser, args, options) {
 * a context with a dependency registry.
 * @internal
 */
-function withSuggestRuntime(context) {
+function withSuggestRuntime(parser, context) {
 	const runtime = createDependencyRuntimeContext();
-	collectSourcesFromState(context.state, runtime);
+	const nodes = getParserSuggestRuntimeNodes(parser, context.state, context.exec?.path ?? []);
+	if (nodes.length > 0) 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 = createDependencyRuntimeContext();
+	const nodes = getParserSuggestRuntimeNodes(parser, context.state, context.exec?.path ?? []);
+	if (nodes.length > 0) await 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
+	}];
+}
+/**
+* Returns wrapper-aware suggest-time runtime nodes for parsers that delegate
+* to an inner parser while also exposing their own source metadata.
+*
+* The inner parser's nodes are always preserved so nested wrappers and
+* constructs can continue to seed the dependency runtime recursively. When
+* the outer parser itself owns source metadata, its `(path, parser, state)`
+* node is appended so outer precedence rules still apply.
+*
+* @internal
+*/
+function getDelegatingSuggestRuntimeNodes(innerParser, outerParser, state, path, innerState, outerPosition = "append") {
+	const innerNodes = getParserSuggestRuntimeNodes(innerParser, innerState, path);
+	if (outerParser.dependencyMetadata?.source == null) return innerNodes;
+	const outerNode = {
+		path,
+		parser: outerParser,
+		state
+	};
+	return outerPosition === "prepend" ? [outerNode, ...innerNodes] : [...innerNodes, outerNode];
+}
+/**
+* Composes source metadata for a wrapper parser while preserving any derived
+* or transform capabilities from the inner parser unchanged.
+*
+* @internal
+*/
+function composeWrappedSourceMetadata(dependencyMetadata, wrapSource) {
+	if (dependencyMetadata?.source == null) return dependencyMetadata;
+	return {
+		...dependencyMetadata,
+		source: wrapSource(dependencyMetadata.source)
+	};
+}
+/**
+* Marks a parser as inheriting parent-state annotations through wrapper-state
+* reconstruction.
+*
+* @internal
+*/
+function defineInheritedAnnotationParser(parser) {
+	Object.defineProperty(parser, inheritParentAnnotationsKey, {
+		value: true,
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Marks a wrapper parser as requiring a real source-binding state before
+* annotation-only primitive wrappers should trigger completion.
+*
+* @internal
+*/
+function defineSourceBindingOnlyAnnotationCompletionParser(parser) {
+	Object.defineProperty(parser, annotationWrapperRequiresSourceBindingKey, {
+		value: true,
+		configurable: true,
+		enumerable: false
+	});
+}
 /**
 * Generates command-line suggestions based on current parsing state.
 * This function processes the input arguments up to the last argument,
@@ -308,12 +446,13 @@ async function suggestAsync(parser, args, options) {
 	}, {
 		usage: parser.usage,
 		phase: "suggest",
-		path: []
+		path: [],
+		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 +461,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 +486,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.
 */
@@ -561,4 +702,4 @@ function buildDocPage(parser, context, args) {
 }
 
 //#endregion
-export { DuplicateOptionError, WithDefaultError, 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 { DuplicateOptionError, WithDefaultError, annotationWrapperRequiresSourceBindingKey, argument, command, composeWrappedSourceMetadata, concat, conditional, constant, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, fail, flag, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, group, inheritParentAnnotationsKey, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, unmatchedNonCliDependencySourceStateMarker, withDefault };