@optique/core 1.1.0-dev.2096 → 1.1.0-dev.2148

package/dist/constructs.js

@@ -8,9 +8,10 @@ import { createDependencySourceState, dependencyId, isDependencySourceState, isP
 import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyRuntimeContext, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync } from "./dependency-runtime.js";
 import { defineInheritedAnnotationParser, getParserSuggestRuntimeNodes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { annotationViewTargets, getWrappedChildParseState, getWrappedChildState, reconcileObjectChildState, unwrapAnnotationView } from "./annotation-state.js";
+import { allowDuplicateLeadingCommandNamesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
-import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar } from "./suggestion.js";
+import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, expandCommandAliasSuggestions, findSimilar } from "./suggestion.js";
 import { collectLeadingCandidates } from "./usage-internals.js";
 
 //#region src/constructs.ts
@@ -301,7 +302,12 @@ function createUnexpectedInputErrorWithScopedSuggestions(baseError, invalidInput
 	for (const parser of parsers) collectLeadingCandidates(parser.usage, options, commands);
 	const candidates = new Set([...options, ...commands]);
 	const suggestions = findSimilar(invalidInput, candidates, DEFAULT_FIND_SIMILAR_OPTIONS);
-	const suggestionMsg = customFormatter ? customFormatter(suggestions) : createSuggestionMessage(suggestions);
+	const aliasUsage = [{
+		type: "exclusive",
+		terms: parsers.map((parser) => parser.usage)
+	}];
+	const displaySuggestions = expandCommandAliasSuggestions(aliasUsage, suggestions);
+	const suggestionMsg = customFormatter ? customFormatter(displaySuggestions) : createSuggestionMessage(displaySuggestions);
 	return suggestionMsg.length > 0 ? [
 		...baseError,
 		text("\n\n"),
@@ -457,6 +463,18 @@ var DuplicateOptionError = class extends Error {
 	}
 };
 /**
+* Error class thrown when duplicate command names or aliases are detected
+* during parser construction. This is a programmer error, not a user error.
+*/
+var DuplicateCommandNameError = class extends TypeError {
+	constructor(commandName, sources) {
+		const sourceNames = sources.map((s) => typeof s === "symbol" ? s.description ?? s.toString() : s);
+		super(`Duplicate command name "${commandName}" found in parsers: ${sourceNames.join(", ")}. Each command name or alias must be unique within active parser alternatives.`);
+		this.commandName = commandName;
+		this.sources = sources;
+	}
+};
+/**
 * Checks for duplicate option names across parser sources and throws an error
 * if duplicates are found. This should be called at construction time.
 * @param parserSources Array of [source, usage] tuples
@@ -473,6 +491,48 @@ function checkDuplicateOptionNames(parserSources) {
 	}
 	for (const [name, sources] of optionNameSources) if (sources.length > 1) throw new DuplicateOptionError(name, sources);
 }
+function checkDuplicateLeadingCommandNames(parserSources) {
+	const commandNameSources = /* @__PURE__ */ new Map();
+	for (const [source, parser] of parserSources) {
+		const commandNames = extractCommandNames(parser.usage, true);
+		for (const name of parser.leadingNames) {
+			if (!commandNames.has(name)) continue;
+			const sources = commandNameSources.get(name);
+			commandNameSources.set(name, sources == null ? [source] : [...sources, source]);
+		}
+	}
+	for (const [name, sources] of commandNameSources) if (sources.length > 1) throw new DuplicateCommandNameError(name, sources);
+}
+function checkDuplicateReachableLeadingCommandNames(parserSources) {
+	const commandNameSources = /* @__PURE__ */ new Map();
+	const sortedSources = [...parserSources].sort(([, parserA], [, parserB]) => parserB.priority - parserA.priority);
+	const blockedNames = /* @__PURE__ */ new Set();
+	let positionalBlocked = false;
+	for (let i = 0; i < sortedSources.length;) {
+		const priority = sortedSources[i][1].priority;
+		const priorityGroup = [];
+		while (i < sortedSources.length && sortedSources[i][1].priority === priority) {
+			priorityGroup.push(sortedSources[i]);
+			i++;
+		}
+		const groupNames = /* @__PURE__ */ new Set();
+		let groupAcceptsAnyToken = false;
+		for (const [source, parser] of priorityGroup) {
+			if (parser.acceptingAnyToken) groupAcceptsAnyToken = true;
+			const commandNames = extractCommandNames(parser.usage, true);
+			for (const name of parser.leadingNames) {
+				if (!commandNames.has(name)) continue;
+				if (positionalBlocked || blockedNames.has(name)) continue;
+				groupNames.add(name);
+				const sources = commandNameSources.get(name);
+				commandNameSources.set(name, sources == null ? [source] : [...sources, source]);
+			}
+		}
+		for (const name of groupNames) blockedNames.add(name);
+		if (groupAcceptsAnyToken) positionalBlocked = true;
+	}
+	for (const [name, sources] of commandNameSources) if (sources.length > 1) throw new DuplicateCommandNameError(name, sources);
+}
 /**
 * Extracts option names that participate in CLI syntax.
 *
@@ -737,6 +797,7 @@ function or(...args) {
 	}
 	if (parsers.length < 1) throw new TypeError("or() requires at least one parser argument.");
 	assertParsers(parsers, "or()");
+	checkDuplicateLeadingCommandNames(parsers.map((parser, index) => [String(index), parser]));
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -1212,6 +1273,9 @@ function or(...args) {
 * @since 0.5.0
 */
 function longestMatch(...args) {
+	return createLongestMatch(...args);
+}
+function createLongestMatch(...args) {
 	let parsers;
 	let options;
 	if (args.length > 0 && args[args.length - 1] && typeof args[args.length - 1] === "object" && !("$valueType" in args[args.length - 1])) {
@@ -1223,6 +1287,8 @@ function longestMatch(...args) {
 	}
 	if (parsers.length < 1) throw new TypeError("longestMatch() requires at least one parser argument.");
 	assertParsers(parsers, "longestMatch()");
+	const allowDuplicateLeadingCommandNames = options?.[allowDuplicateLeadingCommandNamesKey] === true;
+	if (!allowDuplicateLeadingCommandNames) checkDuplicateLeadingCommandNames(parsers.map((parser, index) => [String(index), parser]));
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -1768,6 +1834,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		};
 	};
 	if (!options.allowDuplicates) checkDuplicateOptionNames(parserPairs.map(([field, parser]) => [field, parser.usage]));
+	checkDuplicateReachableLeadingCommandNames(parserPairs.map(([field, parser]) => [field, parser]));
 	const noMatchContext = analyzeNoMatchContext(parserKeys.map((k) => parsers[k]));
 	const combinedMode = parserKeys.some((k) => parsers[k].mode === "async") ? "async" : "sync";
 	const getInitialError = (context) => ({
@@ -3651,6 +3718,7 @@ function merge(...args) {
 	const syncSorted = syncWithIndex.toSorted(([a], [b]) => b.priority - a.priority);
 	const syncParsers = syncSorted.map(([p]) => p);
 	if (!options.allowDuplicates) checkDuplicateOptionNames(sorted.map(([parser, originalIndex]) => [String(originalIndex), parser.usage]));
+	checkDuplicateReachableLeadingCommandNames(sorted.map(([parser, originalIndex]) => [String(originalIndex), parser]));
 	const mergedFieldParsers = collectChildFieldParsers(parsers);
 	const duplicateOutputFieldNames = collectDuplicateFieldNames(mergedFieldParsers);
 	const parserStateKey = (index) => `__parser_${index}`;

package/dist/dependency-metadata.cjs

@@ -1,4 +1,4 @@
-const require_dependency = require('./internal/dependency.cjs');
+const require_internal_dependency = require('./internal/dependency.cjs');
 
 //#region src/dependency-metadata.ts
 /**
@@ -14,27 +14,27 @@ const require_dependency = require('./internal/dependency.cjs');
 * @since 1.0.0
 */
 function extractDependencyMetadata(valueParser) {
-	if (require_dependency.isDependencySource(valueParser)) return { source: {
+	if (require_internal_dependency.isDependencySource(valueParser)) return { source: {
 		kind: "source",
-		sourceId: valueParser[require_dependency.dependencyId],
+		sourceId: valueParser[require_internal_dependency.dependencyId],
 		extractSourceValue: extractFromBareState,
 		preservesSourceValue: true
 	} };
-	if (require_dependency.isDerivedValueParser(valueParser)) {
-		const isMultiSource = require_dependency.dependencyIds in valueParser && valueParser[require_dependency.dependencyIds] != null;
-		const allIds = isMultiSource ? valueParser[require_dependency.dependencyIds] : [valueParser[require_dependency.dependencyId]];
+	if (require_internal_dependency.isDerivedValueParser(valueParser)) {
+		const isMultiSource = require_internal_dependency.dependencyIds in valueParser && valueParser[require_internal_dependency.dependencyIds] != null;
+		const allIds = isMultiSource ? valueParser[require_internal_dependency.dependencyIds] : [valueParser[require_internal_dependency.dependencyId]];
 		let defaultValuesFn;
-		if (require_dependency.defaultValues in valueParser && valueParser[require_dependency.defaultValues] != null) defaultValuesFn = valueParser[require_dependency.defaultValues];
-		else if (require_dependency.singleDefaultValue in valueParser && valueParser[require_dependency.singleDefaultValue] != null) {
-			const singleFn = valueParser[require_dependency.singleDefaultValue];
+		if (require_internal_dependency.defaultValues in valueParser && valueParser[require_internal_dependency.defaultValues] != null) defaultValuesFn = valueParser[require_internal_dependency.defaultValues];
+		else if (require_internal_dependency.singleDefaultValue in valueParser && valueParser[require_internal_dependency.singleDefaultValue] != null) {
+			const singleFn = valueParser[require_internal_dependency.singleDefaultValue];
 			defaultValuesFn = () => [singleFn()];
 		}
 		const parser = valueParser;
 		const replayParse = (rawInput, depValues) => {
 			const depArg = isMultiSource ? depValues : depValues[0];
-			return parser[require_dependency.parseWithDependency](rawInput, depArg);
+			return parser[require_internal_dependency.parseWithDependency](rawInput, depArg);
 		};
-		const suggestFn = require_dependency.suggestWithDependency in parser ? parser[require_dependency.suggestWithDependency] : void 0;
+		const suggestFn = require_internal_dependency.suggestWithDependency in parser ? parser[require_internal_dependency.suggestWithDependency] : void 0;
 		const replaySuggest = suggestFn != null ? (prefix, depValues) => {
 			const depArg = isMultiSource ? depValues : depValues[0];
 			return suggestFn(prefix, depArg);
@@ -58,7 +58,7 @@ function extractDependencyMetadata(valueParser) {
 * dependency sources.
 */
 function extractFromBareState(state) {
-	if (require_dependency.isDependencySourceState(state)) return state.result;
+	if (require_internal_dependency.isDependencySourceState(state)) return state.result;
 	if (state != null && typeof state === "object" && Object.hasOwn(state, "success") && typeof state.success === "boolean" && (state.success && Object.hasOwn(state, "value") || !state.success && Object.hasOwn(state, "error"))) return state;
 	return void 0;
 }

package/dist/dependency-metadata.d.cts

@@ -1,5 +1,5 @@
-import { ValueParserResult } from "./valueparser.cjs";
-import { Suggestion } from "./internal/parser.cjs";
+import { ValueParser, ValueParserResult } from "./valueparser.cjs";
+import { Mode, Suggestion } from "./internal/parser.cjs";
 
 //#region src/dependency-metadata.d.ts
 
@@ -108,5 +108,36 @@ interface ParserDependencyMetadata {
  * @internal
  * @since 1.0.0
  */
+declare function extractDependencyMetadata<M extends Mode, T>(valueParser: ValueParser<M, T>): ParserDependencyMetadata | undefined;
+/**
+ * Options for `composeDependencyMetadata` when the wrapper kind is
+ * `"withDefault"`.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface WithDefaultCompositionOptions {
+  /** Thunk returning the default value as a `ValueParserResult`. */
+  readonly defaultValue: () => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
+}
+/**
+ * Composes dependency metadata through a modifier wrapper.
+ *
+ * - `"optional"`: composes `extractSourceValue` with array unwrapping.
+ * - `"withDefault"`: adds `getMissingSourceValue` if the inner parser
+ *   preserves a dependency source.
+ * - `"map"`: sets `transformsSourceValue` and clears
+ *   `preservesSourceValue`.
+ *
+ * Returns `undefined` if `inner` is `undefined`.
+ *
+ * @param inner The inner parser's metadata.
+ * @param wrapperKind The type of modifier being applied.
+ * @param options Additional options for certain wrapper kinds.
+ * @returns Composed metadata, or `undefined`.
+ * @internal
+ * @since 1.0.0
+ */
+declare function composeDependencyMetadata(inner: ParserDependencyMetadata | undefined, wrapperKind: "optional" | "withDefault" | "map", options?: WithDefaultCompositionOptions): ParserDependencyMetadata | undefined;
 //#endregion
-export { ParserDependencyMetadata };
+export { DependencySourceCapability, DependencyTransformCapability, DerivedDependencyCapability, ParserDependencyMetadata, WithDefaultCompositionOptions, composeDependencyMetadata, extractDependencyMetadata };

package/dist/dependency-metadata.d.ts

@@ -1,5 +1,5 @@
-import { ValueParserResult } from "./valueparser.js";
-import { Suggestion } from "./internal/parser.js";
+import { ValueParser, ValueParserResult } from "./valueparser.js";
+import { Mode, Suggestion } from "./internal/parser.js";
 
 //#region src/dependency-metadata.d.ts
 
@@ -108,5 +108,36 @@ interface ParserDependencyMetadata {
  * @internal
  * @since 1.0.0
  */
+declare function extractDependencyMetadata<M extends Mode, T>(valueParser: ValueParser<M, T>): ParserDependencyMetadata | undefined;
+/**
+ * Options for `composeDependencyMetadata` when the wrapper kind is
+ * `"withDefault"`.
+ *
+ * @internal
+ * @since 1.0.0
+ */
+interface WithDefaultCompositionOptions {
+  /** Thunk returning the default value as a `ValueParserResult`. */
+  readonly defaultValue: () => ValueParserResult<unknown> | Promise<ValueParserResult<unknown>>;
+}
+/**
+ * Composes dependency metadata through a modifier wrapper.
+ *
+ * - `"optional"`: composes `extractSourceValue` with array unwrapping.
+ * - `"withDefault"`: adds `getMissingSourceValue` if the inner parser
+ *   preserves a dependency source.
+ * - `"map"`: sets `transformsSourceValue` and clears
+ *   `preservesSourceValue`.
+ *
+ * Returns `undefined` if `inner` is `undefined`.
+ *
+ * @param inner The inner parser's metadata.
+ * @param wrapperKind The type of modifier being applied.
+ * @param options Additional options for certain wrapper kinds.
+ * @returns Composed metadata, or `undefined`.
+ * @internal
+ * @since 1.0.0
+ */
+declare function composeDependencyMetadata(inner: ParserDependencyMetadata | undefined, wrapperKind: "optional" | "withDefault" | "map", options?: WithDefaultCompositionOptions): ParserDependencyMetadata | undefined;
 //#endregion
-export { ParserDependencyMetadata };
+export { DependencySourceCapability, DependencyTransformCapability, DerivedDependencyCapability, ParserDependencyMetadata, WithDefaultCompositionOptions, composeDependencyMetadata, extractDependencyMetadata };

package/dist/dependency-runtime.cjs

@@ -1,6 +1,6 @@
 const require_message = require('./message.cjs');
-const require_dependency = require('./internal/dependency.cjs');
-const require_parser = require('./internal/parser.cjs');
+const require_internal_dependency = require('./internal/dependency.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
 
 //#region src/dependency-runtime.ts
 const symbolIds = /* @__PURE__ */ new WeakMap();
@@ -457,6 +457,27 @@ async function replayDerivedParserAsync(node, rawInput, runtime) {
 	return result;
 }
 /**
+* Extracts `rawInput` from a parser state that may contain a
+* {@link DeferredParseState}.  During the transition period, primitives
+* still produce `DeferredParseState` with `rawInput`.
+*
+* Handles direct `DeferredParseState` and array-wrapped
+* `[DeferredParseState]` (from optional/withDefault wrappers).
+*
+* @param state The parser state to inspect.
+* @returns The raw input string, or `undefined` if the state does not
+*   contain a `DeferredParseState`.
+* @internal
+* @since 1.0.0
+*/
+function extractRawInputFromState(state) {
+	if (state == null) return void 0;
+	if (typeof state !== "object") return void 0;
+	if (require_internal_dependency.isDeferredParseState(state)) return state.rawInput;
+	if (Array.isArray(state) && state.length === 1 && require_internal_dependency.isDeferredParseState(state[0])) return state[0].rawInput;
+	return void 0;
+}
+/**
 * Checks if a value is a plain object (not a class instance) for the
 * purpose of recursive state traversal.
 */
@@ -481,7 +502,7 @@ function resolveSingleDeferred(deferred, runtime) {
 	if (resolution.kind !== "resolved") return deferred.preliminaryResult;
 	if (resolution.usedDefaults.every((d) => d)) return deferred.preliminaryResult;
 	const depValue = isMultiDep ? resolution.values : resolution.values[0];
-	const result = deferred.parser[require_dependency.parseWithDependency](deferred.rawInput, depValue);
+	const result = deferred.parser[require_internal_dependency.parseWithDependency](deferred.rawInput, depValue);
 	if (isPromiseLike(result)) throw new TypeError("resolveStateWithRuntime() received an async parseWithDependency() result. Use resolveStateWithRuntimeAsync() instead.");
 	return result;
 }
@@ -495,7 +516,7 @@ function resolveSingleDeferredAsync(deferred, runtime) {
 	if (resolution.kind !== "resolved") return Promise.resolve(deferred.preliminaryResult);
 	if (resolution.usedDefaults.every((d) => d)) return Promise.resolve(deferred.preliminaryResult);
 	const depValue = isMultiDep ? resolution.values : resolution.values[0];
-	return Promise.resolve(deferred.parser[require_dependency.parseWithDependency](deferred.rawInput, depValue));
+	return Promise.resolve(deferred.parser[require_internal_dependency.parseWithDependency](deferred.rawInput, depValue));
 }
 /**
 * Recursively collects dependency source values from {@link DependencySourceState}
@@ -514,14 +535,14 @@ function collectSourcesFromState(state, runtime, visited = /* @__PURE__ */ new W
 	if (state == null || typeof state !== "object") return;
 	if (visited.has(state)) return;
 	visited.add(state);
-	if (require_dependency.isDependencySourceState(state)) {
-		const depId = state[require_dependency.dependencyId];
+	if (require_internal_dependency.isDependencySourceState(state)) {
+		const depId = state[require_internal_dependency.dependencyId];
 		const result = state.result;
 		if (depId != null && result.success) runtime.registerSource(depId, result.value, "cli");
 		else if (depId != null) runtime.markSourceFailed(depId);
 		return;
 	}
-	if (require_dependency.isDeferredParseState(state)) return;
+	if (require_internal_dependency.isDeferredParseState(state)) return;
 	if (Array.isArray(state)) {
 		for (const item of state) collectSourcesFromState(item, runtime, visited);
 		return;
@@ -559,14 +580,14 @@ function resolveStateWithRuntime(state, runtime) {
 /** Pass 2 helper: recursively replace DeferredParseState with resolved values. */
 function resolveDeferredInState(state, runtime, visited = /* @__PURE__ */ new WeakSet(), deferredCache = /* @__PURE__ */ new WeakMap()) {
 	if (state == null) return state;
-	if (require_dependency.isDeferredParseState(state)) {
+	if (require_internal_dependency.isDeferredParseState(state)) {
 		const cached = deferredCache.get(state);
 		if (cached !== void 0) return cached;
 		const resolved = resolveSingleDeferred(state, runtime);
 		deferredCache.set(state, resolved);
 		return resolved;
 	}
-	if (require_dependency.isDependencySourceState(state)) return state;
+	if (require_internal_dependency.isDependencySourceState(state)) return state;
 	if (typeof state === "object") {
 		if (visited.has(state)) return state;
 		visited.add(state);
@@ -601,14 +622,14 @@ function resolveStateWithRuntimeAsync(state, runtime) {
 /** Async pass 2 helper. */
 async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE__ */ new WeakSet(), deferredCache = /* @__PURE__ */ new WeakMap()) {
 	if (state == null) return state;
-	if (require_dependency.isDeferredParseState(state)) {
+	if (require_internal_dependency.isDeferredParseState(state)) {
 		const cached = deferredCache.get(state);
 		if (cached !== void 0) return cached;
 		const resolved = resolveSingleDeferredAsync(state, runtime);
 		deferredCache.set(state, resolved);
 		return resolved;
 	}
-	if (require_dependency.isDependencySourceState(state)) return state;
+	if (require_internal_dependency.isDependencySourceState(state)) return state;
 	if (typeof state === "object") {
 		if (visited.has(state)) return state;
 		visited.add(state);
@@ -636,8 +657,8 @@ async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE_
 function isMatchedState(fieldState, parser) {
 	if (fieldState === void 0) return false;
 	const innerState = Array.isArray(fieldState) && fieldState.length === 1 ? fieldState[0] : fieldState;
-	if (require_dependency.isPendingDependencySourceState(innerState)) return false;
-	if (parser[require_parser.unmatchedNonCliDependencySourceStateMarker] === true && innerState != null && typeof innerState === "object" && Object.hasOwn(innerState, "hasCliValue") && innerState.hasCliValue === false) return false;
+	if (require_internal_dependency.isPendingDependencySourceState(innerState)) return false;
+	if (parser[require_internal_parser.unmatchedNonCliDependencySourceStateMarker] === true && innerState != null && typeof innerState === "object" && Object.hasOwn(innerState, "hasCliValue") && innerState.hasCliValue === false) return false;
 	if (fieldState === parser.initialState) return false;
 	return true;
 }
@@ -701,7 +722,10 @@ exports.buildRuntimeNodesFromPairs = buildRuntimeNodesFromPairs;
 exports.collectExplicitSourceValues = collectExplicitSourceValues;
 exports.collectExplicitSourceValuesAsync = collectExplicitSourceValuesAsync;
 exports.collectSourcesFromState = collectSourcesFromState;
+exports.createDependencyFingerprint = createDependencyFingerprint;
 exports.createDependencyRuntimeContext = createDependencyRuntimeContext;
+exports.createReplayKey = createReplayKey;
+exports.extractRawInputFromState = extractRawInputFromState;
 exports.fillMissingSourceDefaults = fillMissingSourceDefaults;
 exports.fillMissingSourceDefaultsAsync = fillMissingSourceDefaultsAsync;
 exports.replayDerivedParser = replayDerivedParser;

package/dist/dependency-runtime.d.cts

@@ -49,7 +49,14 @@ interface DependencyResolution {
  * @internal
  * @since 1.0.0
  */
-
+interface SourceDefaultFailure {
+  /** The source that failed. */
+  readonly sourceId: symbol;
+  /** The path of the node. */
+  readonly path: readonly PropertyKey[];
+  /** The failed result or error message. */
+  readonly error: ValueParserResult<unknown>;
+}
 /**
  * A key for caching replayed parse results.
  *
@@ -145,5 +152,193 @@ interface DependencyRuntimeContext {
  * @internal
  * @since 1.0.0
  */
+declare function createDependencyRuntimeContext(registry?: DependencyRegistryLike): DependencyRuntimeContext;
+/**
+ * Creates a stable fingerprint from dependency values.
+ *
+ * @param values The dependency values to fingerprint.
+ * @returns A string fingerprint.
+ * @internal
+ * @since 1.0.0
+ */
+declare function createDependencyFingerprint(values: readonly unknown[]): string;
+declare function createReplayKey(path: readonly PropertyKey[], rawInput: string, dependencyValues: readonly unknown[], replayParse?: Function): ReplayKey;
+/**
+ * Collects explicit source values from parser states and registers them
+ * in the runtime context.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @throws Propagates synchronous errors thrown by `extractSourceValue()`.
+ * @throws {TypeError} If `extractSourceValue()` returns a promise-like result.
+ *         Use {@link collectExplicitSourceValuesAsync} when async source
+ *         extraction is expected.
+ * @internal
+ * @since 1.0.0
+ */
+declare function collectExplicitSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): void;
+/**
+ * Async version of {@link collectExplicitSourceValues}.
+ * Awaits async `extractSourceValue` results instead of rejecting
+ * promise-like values as the synchronous variant does.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @throws Propagates errors thrown or rejected by `extractSourceValue()`.
+ * @internal
+ * @since 1.0.0
+ */
+declare function collectExplicitSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<void>;
+/**
+ * Fills missing source defaults for source parsers whose state is
+ * unpopulated.
+ *
+ * Returns an array of failures for sources whose default evaluation
+ * failed (either threw or returned `{ success: false }`).  The caller
+ * should propagate these so that dependent parsers see the real error
+ * instead of silently treating the source as absent.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @returns Failures from default evaluation (empty if all succeeded).
+ * @throws {TypeError} If `getMissingSourceValue()` returns a promise-like
+ *         result. Use {@link fillMissingSourceDefaultsAsync} when async
+ *         default extraction is expected.
+ * @internal
+ * @since 1.0.0
+ */
+declare function fillMissingSourceDefaults(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): readonly SourceDefaultFailure[];
+/**
+ * Async version of {@link fillMissingSourceDefaults}.
+ * Awaits async `getMissingSourceValue` results.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @returns Failures from default evaluation (empty if all succeeded).
+ * @internal
+ * @since 1.0.0
+ */
+declare function fillMissingSourceDefaultsAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<readonly SourceDefaultFailure[]>;
+/**
+ * Replays a derived parser with resolved dependency values (sync).
+ *
+ * Returns `undefined` if dependencies cannot be resolved.
+ *
+ * @param node The runtime node with derived metadata.
+ * @param rawInput The raw input to replay.
+ * @param runtime The dependency runtime context.
+ * @returns The replay result, or `undefined`.
+ * @throws {TypeError} If `replayParse()` returns a promise-like result.
+ *         Use {@link replayDerivedParserAsync} for async replay.
+ * @internal
+ * @since 1.0.0
+ */
+declare function replayDerivedParser(node: RuntimeNode, rawInput: string, runtime: DependencyRuntimeContext): ValueParserResult<unknown> | undefined;
+/**
+ * Replays a derived parser with resolved dependency values (async).
+ *
+ * Returns `undefined` if dependencies cannot be resolved.
+ *
+ * @param node The runtime node with derived metadata.
+ * @param rawInput The raw input to replay.
+ * @param runtime The dependency runtime context.
+ * @returns The replay result, or `undefined`.
+ * @internal
+ * @since 1.0.0
+ */
+declare function replayDerivedParserAsync(node: RuntimeNode, rawInput: string, runtime: DependencyRuntimeContext): Promise<ValueParserResult<unknown> | undefined>;
+/**
+ * Extracts `rawInput` from a parser state that may contain a
+ * {@link DeferredParseState}.  During the transition period, primitives
+ * still produce `DeferredParseState` with `rawInput`.
+ *
+ * Handles direct `DeferredParseState` and array-wrapped
+ * `[DeferredParseState]` (from optional/withDefault wrappers).
+ *
+ * @param state The parser state to inspect.
+ * @returns The raw input string, or `undefined` if the state does not
+ *   contain a `DeferredParseState`.
+ * @internal
+ * @since 1.0.0
+ */
+declare function extractRawInputFromState(state: unknown): string | undefined;
+/**
+ * Recursively collects dependency source values from {@link DependencySourceState}
+ * objects found in the state tree and registers them in the runtime.
+ *
+ * This must run BEFORE deferred resolution so that all source values
+ * are available when replaying derived parsers.
+ *
+ * @param state The state tree to traverse.
+ * @param runtime The dependency runtime context to populate.
+ * @param visited Cycle guard for recursive traversal.
+ * @param excludedFields Optional property keys to skip at the current level.
+ *                       This exclusion set is not propagated recursively.
+ */
+declare function collectSourcesFromState(state: unknown, runtime: DependencyRuntimeContext, visited?: WeakSet<object>, excludedFields?: ReadonlySet<PropertyKey>): void;
+/**
+ * Recursively resolves all {@link DeferredParseState} objects in a state
+ * tree using the dependency runtime (sync).
+ *
+ * Performs a two-pass traversal:
+ *  1. Collect all {@link DependencySourceState} values into the runtime.
+ *  2. Resolve all {@link DeferredParseState} using the populated runtime.
+ *
+ * This replaces the old `resolveDeferredParseStates` with runtime-based
+ * resolution.  Only traverses plain objects and arrays; class instances
+ * and primitives are returned as-is.
+ *
+ * @param state The state tree to resolve.
+ * @param runtime The dependency runtime context.
+ * @returns The resolved state tree.
+ * @throws {TypeError} If a deferred parser returns a promise-like result from
+ *         `parseWithDependency()`. Use {@link resolveStateWithRuntimeAsync}
+ *         for async resolution.
+ * @internal
+ * @since 1.0.0
+ */
+declare function resolveStateWithRuntime(state: unknown, runtime: DependencyRuntimeContext): unknown;
+/**
+ * Async version of {@link resolveStateWithRuntime}.
+ *
+ * @param state The state tree to resolve.
+ * @param runtime The dependency runtime context.
+ * @returns The resolved state tree.
+ * @internal
+ * @since 1.0.0
+ */
+declare function resolveStateWithRuntimeAsync(state: unknown, runtime: DependencyRuntimeContext): Promise<unknown>;
+/**
+ * Builds {@link RuntimeNode}s from field→parser pairs and a state record.
+ *
+ * Used by `object()` and `merge()` constructs.
+ *
+ * @param pairs Field→parser pairs.
+ * @param state The state record keyed by field name.
+ * @param parentPath Optional parent path prefix.
+ * @returns An array of runtime nodes.
+ * @internal
+ * @since 1.0.0
+ */
+declare function buildRuntimeNodesFromPairs(pairs: ReadonlyArray<readonly [PropertyKey, {
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+  readonly initialState?: unknown;
+}]>, state: Record<PropertyKey, unknown>, parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
+/**
+ * Builds {@link RuntimeNode}s from a parser array and a state array.
+ *
+ * Used by `tuple()` and `concat()` constructs.
+ *
+ * @param parsers The child parsers.
+ * @param stateArray The state array (one element per parser).
+ * @param parentPath Optional parent path prefix.
+ * @returns An array of runtime nodes.
+ * @internal
+ * @since 1.0.0
+ */
+declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+  readonly initialState?: unknown;
+}>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { DependencyRuntimeContext, RuntimeNode };
+export { DependencyRequest, DependencyResolution, DependencyRuntimeContext, DependencyValueOrigin, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };