@optique/core 1.3.0-dev.2398 → 1.3.0-dev.2401

package/dist/dependency-runtime.js

@@ -1,8 +1,34 @@
 import { message } from "./message.js";
-import { dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, parseWithDependency } from "./internal/dependency.js";
+import { dependencyId, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, parseWithDependency } from "./internal/dependency.js";
 import { unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 
 //#region src/dependency-runtime.ts
+/**
+* Stores the raw token parsed by a derived value parser on structural parser
+* states that can safely carry an in-band annotation.
+*
+* The execution trace remains the canonical diagnostic record.  This state
+* marker lets construct-independent dependency resolution replay a derived
+* source before downstream fields complete.
+* @internal
+* @since 1.3.0
+*/
+const derivedRawInputKey = Symbol("@optique/core/dependency-runtime/derivedRawInput");
+const derivedRawInputs = /* @__PURE__ */ new WeakMap();
+/**
+* Records a derived parser's raw token without modifying its parse result.
+*
+* Parse results may be frozen or carry class private state, so primitives keep
+* their original identity and associate replay metadata out of band.
+*
+* @param state The original value parser result.
+* @param rawInput The token parsed into that result.
+* @internal
+* @since 1.3.0
+*/
+function recordDerivedRawInput(state, rawInput) {
+	derivedRawInputs.set(state, rawInput);
+}
 const symbolIds = /* @__PURE__ */ new WeakMap();
 let symbolCounter = 0;
 function stableSymbolKey(sym) {
@@ -19,6 +45,8 @@ var DependencyRuntimeContextImpl = class {
 	registry;
 	#replayCache = /* @__PURE__ */ new Map();
 	#failedSources = /* @__PURE__ */ new Set();
+	#sourceMetadata = /* @__PURE__ */ new Map();
+	#sourceFailures = /* @__PURE__ */ new Map();
 	constructor(registry) {
 		if (registry instanceof FailedAwareRegistry) {
 			this.registry = registry.rebindFailedSources(this.#failedSources);
@@ -28,6 +56,7 @@ var DependencyRuntimeContextImpl = class {
 	}
 	registerSource(sourceId, value) {
 		this.registry.set(sourceId, value);
+		this.#sourceFailures.delete(sourceId);
 	}
 	hasSource(sourceId) {
 		return this.registry.has(sourceId);
@@ -46,6 +75,45 @@ var DependencyRuntimeContextImpl = class {
 	}
 	markSourceFailed(sourceId) {
 		this.#failedSources.add(sourceId);
+		const lineage = this.#getSourceLineage(sourceId, /* @__PURE__ */ new Set());
+		const failure = {
+			chain: lineage.labels,
+			participants: lineage.sourceIds,
+			diagnosticChain: lineage.labels
+		};
+		this.#sourceFailures.set(sourceId, failure);
+		this.#promoteDiagnosticChain(failure);
+	}
+	registerSourceMetadata(sourceId, label, dependencyIds = []) {
+		this.#sourceMetadata.set(sourceId, {
+			label,
+			dependencyIds
+		});
+	}
+	propagateSourceFailure(dependencyIds, label, sourceId) {
+		const upstream = dependencyIds.filter((id) => this.isSourceFailed(id)).map((id) => this.#sourceFailures.get(id) ?? {
+			chain: [this.#getSourceLabel(id)],
+			participants: [id],
+			diagnosticChain: [this.#getSourceLabel(id)]
+		}).sort((left, right) => right.chain.length - left.chain.length)[0];
+		if (upstream == null) return false;
+		const chain = upstream.chain.at(-1) === label ? upstream.chain : [...upstream.chain, label];
+		const participants = sourceId == null || upstream.participants.includes(sourceId) ? upstream.participants : [...upstream.participants, sourceId];
+		const failure = {
+			chain,
+			participants,
+			diagnosticChain: chain
+		};
+		if (sourceId != null) {
+			this.#failedSources.add(sourceId);
+			this.#sourceFailures.set(sourceId, failure);
+		}
+		this.#promoteDiagnosticChain(failure);
+		return true;
+	}
+	getSourceFailureChain(sourceId) {
+		if (!this.#failedSources.has(sourceId)) return void 0;
+		return this.#sourceFailures.get(sourceId)?.diagnosticChain;
 	}
 	isSourceFailed(sourceId) {
 		return this.#failedSources.has(sourceId);
@@ -53,6 +121,31 @@ var DependencyRuntimeContextImpl = class {
 	getSuggestionDependencies(request) {
 		return resolveRequest(this, request);
 	}
+	#getSourceLabel(sourceId) {
+		return this.#sourceMetadata.get(sourceId)?.label ?? sourceId.description ?? String(sourceId);
+	}
+	#getSourceLineage(sourceId, visited) {
+		if (visited.has(sourceId)) return {
+			labels: [this.#getSourceLabel(sourceId)],
+			sourceIds: [sourceId]
+		};
+		visited.add(sourceId);
+		const metadata = this.#sourceMetadata.get(sourceId);
+		const upstream = (metadata?.dependencyIds ?? []).map((id) => this.#getSourceLineage(id, new Set(visited))).sort((left, right) => right.labels.length - left.labels.length)[0];
+		return upstream == null ? {
+			labels: [this.#getSourceLabel(sourceId)],
+			sourceIds: [sourceId]
+		} : {
+			labels: [...upstream.labels, this.#getSourceLabel(sourceId)],
+			sourceIds: [...upstream.sourceIds, sourceId]
+		};
+	}
+	#promoteDiagnosticChain(failure) {
+		for (const sourceId of failure.participants) {
+			const current = this.#sourceFailures.get(sourceId);
+			if (current != null && current.diagnosticChain.length < failure.diagnosticChain.length) current.diagnosticChain = failure.diagnosticChain;
+		}
+	}
 };
 /**
 * Registry wrapper that hides values for sources that have failed.
@@ -251,14 +344,17 @@ function createReplayKey(path, rawInput, dependencyValues, replayParse) {
 * @since 1.0.0
 */
 function collectExplicitSourceValues(nodes, runtime) {
+	registerRuntimeSourceMetadata(nodes, runtime);
 	for (const node of nodes) {
 		const meta = node.parser.dependencyMetadata;
 		if (meta?.source == null) continue;
 		if (meta.source.extractSourceValue == null) continue;
+		if (meta.derived != null && getNodeRawInput(node) != null) continue;
 		const result = meta.source.extractSourceValue(node.state);
 		if (isPromiseLike(result)) throw new TypeError(`collectExplicitSourceValues() received an async extractSourceValue() result for ${String(meta.source.sourceId)}. Use collectExplicitSourceValuesAsync() instead.`);
 		registerExplicitSourceValue(meta.source.sourceId, result, runtime);
 	}
+	resolveDerivedSourceValues(nodes, runtime);
 }
 function registerExplicitSourceValue(sourceId, result, runtime) {
 	if (result == null) return;
@@ -280,13 +376,192 @@ function isPromiseLike(value) {
 * @since 1.0.0
 */
 async function collectExplicitSourceValuesAsync(nodes, runtime) {
+	registerRuntimeSourceMetadata(nodes, runtime);
 	for (const node of nodes) {
 		const meta = node.parser.dependencyMetadata;
 		if (meta?.source == null) continue;
 		if (meta.source.extractSourceValue == null) continue;
+		if (meta.derived != null && getNodeRawInput(node) != null) continue;
 		const result = await meta.source.extractSourceValue(node.state);
 		registerExplicitSourceValue(meta.source.sourceId, result, runtime);
 	}
+	await resolveDerivedSourceValuesAsync(nodes, runtime);
+}
+/**
+* Orders runtime nodes so every in-scope provider precedes a derived source
+* that consumes it.  Independent nodes retain declaration order.
+*
+* Missing providers create no edge because the consumer may use its declared
+* default.  Scheduling barriers act as providers for the source IDs their
+* selected subtree may expose and depend on their discriminator source.
+*
+* @param nodes Runtime nodes in declaration order.
+* @returns The same nodes in stable dependency order.
+* @throws {TypeError} If active provider edges contain a cycle.
+* @internal
+* @since 1.3.0
+*/
+function orderDependencyNodes(nodes) {
+	const providers = /* @__PURE__ */ new Map();
+	const addProvider = (sourceId, node) => {
+		const existing = providers.get(sourceId);
+		if (existing == null) providers.set(sourceId, [node]);
+		else existing.push(node);
+	};
+	for (const node of nodes) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source != null) addProvider(source.sourceId, node);
+		for (const sourceId of node.providesSourceIds ?? []) addProvider(sourceId, node);
+	}
+	const outgoing = /* @__PURE__ */ new Map();
+	const indegree = /* @__PURE__ */ new Map();
+	for (const node of nodes) indegree.set(node, 0);
+	const addEdge = (provider, consumer) => {
+		const edges = outgoing.get(provider) ?? /* @__PURE__ */ new Set();
+		if (edges.has(consumer)) return;
+		edges.add(consumer);
+		outgoing.set(provider, edges);
+		indegree.set(consumer, (indegree.get(consumer) ?? 0) + 1);
+	};
+	for (const node of nodes) {
+		const derived = node.parser.dependencyMetadata?.derived;
+		if (derived != null) for (const dependencySourceId of derived.dependencyIds) for (const provider of providers.get(dependencySourceId) ?? []) addEdge(provider, node);
+		if (node.requiresSourceId != null) {
+			for (const provider of providers.get(node.requiresSourceId) ?? []) if (provider !== node) addEdge(provider, node);
+		}
+	}
+	const declarationOrder = new Map(nodes.map((node, index) => [node, index]));
+	const ready = nodes.filter((node) => indegree.get(node) === 0);
+	const ordered = [];
+	while (ready.length > 0) {
+		ready.sort((left, right) => declarationOrder.get(left) - declarationOrder.get(right));
+		const node = ready.shift();
+		ordered.push(node);
+		for (const consumer of outgoing.get(node) ?? []) {
+			const next = (indegree.get(consumer) ?? 0) - 1;
+			indegree.set(consumer, next);
+			if (next === 0) ready.push(consumer);
+		}
+	}
+	if (ordered.length !== nodes.length) {
+		const cycle = nodes.filter((node) => (indegree.get(node) ?? 0) > 0);
+		const labels = cycle.map(formatDependencyNodeLabel).join(" -> ");
+		throw new TypeError(`Circular dependency detected among derived sources: ${labels}.`);
+	}
+	return ordered;
+}
+/** Resolves and publishes matched derived sources in stable dependency order. */
+function resolveDerivedSourceValues(nodes, runtime, options) {
+	resolveDerivedSourceValuesInOrder(orderDependencyNodes(nodes), nodes, runtime, (node, rawInput) => replayDerivedParser(node, rawInput, runtime), options);
+}
+/** Async version of {@link resolveDerivedSourceValues}. */
+async function resolveDerivedSourceValuesAsync(nodes, runtime, options) {
+	await resolveDerivedSourceValuesInOrderAsync(orderDependencyNodes(nodes), nodes, runtime, options);
+}
+function resolveDerivedSourceValuesInOrder(ordered, allNodes, runtime, replay, options) {
+	const providers = collectSourceProviders(allNodes);
+	const settled = /* @__PURE__ */ new Set();
+	for (const node of ordered) {
+		const metadata = node.parser.dependencyMetadata;
+		const rawInput = getNodeRawInput(node);
+		if (metadata?.derived == null) continue;
+		const label = formatDependencyNodeMetavar(node);
+		if (runtime.propagateSourceFailure(metadata.derived.dependencyIds, label, metadata.source?.sourceId)) {
+			if (metadata.source != null) settled.add(node);
+			continue;
+		}
+		if (metadata.source == null || rawInput == null) continue;
+		if (hasPendingProvider(node, providers, settled, runtime, options)) continue;
+		settleDerivedSource(node, rawInput, runtime, replay);
+		settled.add(node);
+	}
+}
+async function resolveDerivedSourceValuesInOrderAsync(ordered, allNodes, runtime, options) {
+	const providers = collectSourceProviders(allNodes);
+	const settled = /* @__PURE__ */ new Set();
+	for (const node of ordered) {
+		const metadata = node.parser.dependencyMetadata;
+		const rawInput = getNodeRawInput(node);
+		if (metadata?.derived == null) continue;
+		const label = formatDependencyNodeMetavar(node);
+		if (runtime.propagateSourceFailure(metadata.derived.dependencyIds, label, metadata.source?.sourceId)) {
+			if (metadata.source != null) settled.add(node);
+			continue;
+		}
+		if (metadata.source == null || rawInput == null) continue;
+		if (hasPendingProvider(node, providers, settled, runtime, options)) continue;
+		const result = await replayDerivedParserAsync(node, rawInput, runtime);
+		publishDerivedSourceResult(metadata.source.sourceId, result, runtime);
+		settled.add(node);
+	}
+}
+function settleDerivedSource(node, rawInput, runtime, replay) {
+	const metadata = node.parser.dependencyMetadata;
+	publishDerivedSourceResult(metadata.source.sourceId, replay(node, rawInput), runtime);
+}
+function publishDerivedSourceResult(sourceId, result, runtime) {
+	if (result == null || result.success && result.deferred === true) return;
+	if (!result.success) runtime.markSourceFailed(sourceId);
+	else runtime.registerSource(sourceId, result.value);
+}
+function collectSourceProviders(nodes) {
+	const providers = /* @__PURE__ */ new Map();
+	for (const node of nodes) {
+		const sourceId = node.parser.dependencyMetadata?.source?.sourceId;
+		if (sourceId == null) continue;
+		const existing = providers.get(sourceId);
+		if (existing == null) providers.set(sourceId, [node]);
+		else existing.push(node);
+	}
+	return providers;
+}
+function hasPendingProvider(node, providers, settled, runtime, options) {
+	const derived = node.parser.dependencyMetadata.derived;
+	return derived.dependencyIds.some((sourceId) => (providers.get(sourceId) ?? []).some((provider) => {
+		if (provider === node || runtime.hasSource(sourceId) || runtime.isSourceFailed(sourceId)) return false;
+		const metadata = provider.parser.dependencyMetadata;
+		if (metadata?.derived != null && getNodeRawInput(provider) != null) return !settled.has(provider);
+		return options?.effectfulProviders !== "inactive" && metadata?.source?.completeSource != null;
+	}));
+}
+function getNodeRawInput(node) {
+	return node.rawInput ?? extractRawInputFromState(node.state);
+}
+function registerRuntimeSourceMetadata(nodes, runtime) {
+	for (const node of nodes) {
+		const metadata = node.parser.dependencyMetadata;
+		if (metadata?.source == null) continue;
+		runtime.registerSourceMetadata(metadata.source.sourceId, formatDependencyNodeMetavar(node), metadata.derived?.dependencyIds);
+	}
+}
+function propagateRuntimeSourceFailures(nodes, runtime) {
+	for (const node of orderDependencyNodes(nodes)) {
+		const metadata = node.parser.dependencyMetadata;
+		if (metadata?.derived == null) continue;
+		runtime.propagateSourceFailure(metadata.derived.dependencyIds, formatDependencyNodeMetavar(node), metadata.source?.sourceId);
+	}
+}
+/**
+* Appends the recorded dependency chain to a source failure.
+*
+* @param error The source failure to annotate.
+* @param sourceId The identifier of the failed source.
+* @param runtime The dependency runtime that recorded the failure chain.
+* @returns The annotated failure, or the original failure when no chain exists.
+* @internal
+* @since 1.3.0
+*/
+function includeSourceFailureChain(error, sourceId, runtime) {
+	const chain = runtime.getSourceFailureChain(sourceId);
+	return chain == null || chain.length < 2 ? error : message`${error} Dependency chain: ${chain.join(" -> ")}.`;
+}
+function formatDependencyNodeMetavar(node) {
+	return node.parser.dependencyMetadata?.derived?.metavar ?? node.parser.dependencyMetadata?.source?.metavar ?? (node.path.map(String).join(".") || "<root>");
+}
+function formatDependencyNodeLabel(node) {
+	const metavar = node.parser.dependencyMetadata?.derived?.metavar ?? node.parser.dependencyMetadata?.source?.metavar;
+	const path = node.path.map(String).join(".") || "<root>";
+	return metavar == null ? path : `${metavar} (${path})`;
 }
 /**
 * Fills missing source defaults for source parsers whose state is
@@ -339,6 +614,7 @@ function fillMissingSourceDefaults(nodes, runtime) {
 			error: result
 		});
 	}
+	resolveDerivedSourceValues(nodes, runtime);
 	return failures;
 }
 /**
@@ -383,6 +659,7 @@ async function fillMissingSourceDefaultsAsync(nodes, runtime) {
 			error: result
 		});
 	}
+	await resolveDerivedSourceValuesAsync(nodes, runtime);
 	return failures;
 }
 /**
@@ -414,6 +691,10 @@ function replayDerivedParser(node, rawInput, runtime) {
 	});
 	if (resolution.kind === "missing") return void 0;
 	if (resolution.kind === "partial") return void 0;
+	if (resolution.usedDefaults.every((usedDefault) => usedDefault)) {
+		const preliminary = extractPreliminaryResultFromState(node.state);
+		if (preliminary != null) return preliminary;
+	}
 	const key = createReplayKey(node.path, rawInput, resolution.values, meta.derived.replayParse);
 	const cached = runtime.getReplayResult(key);
 	if (cached != null) return cached;
@@ -449,6 +730,10 @@ async function replayDerivedParserAsync(node, rawInput, runtime) {
 	});
 	if (resolution.kind === "missing") return void 0;
 	if (resolution.kind === "partial") return void 0;
+	if (resolution.usedDefaults.every((usedDefault) => usedDefault)) {
+		const preliminary = extractPreliminaryResultFromState(node.state);
+		if (preliminary != null) return preliminary;
+	}
 	const key = createReplayKey(node.path, rawInput, resolution.values, meta.derived.replayParse);
 	const cached = runtime.getReplayResult(key);
 	if (cached != null) return cached;
@@ -471,10 +756,60 @@ async function replayDerivedParserAsync(node, rawInput, runtime) {
 * @since 1.0.0
 */
 function extractRawInputFromState(state) {
+	return extractRawInputFromStateInner(state, /* @__PURE__ */ new Set());
+}
+function extractRawInputFromStateInner(state, visited) {
 	if (state == null) return void 0;
 	if (typeof state !== "object") return void 0;
+	if (visited.has(state)) return void 0;
+	visited.add(state);
+	const recordedRawInput = getRecordedDerivedRawInput(state);
+	if (recordedRawInput != null) return recordedRawInput;
 	if (isDeferredParseState(state)) return state.rawInput;
-	if (Array.isArray(state) && state.length === 1 && isDeferredParseState(state[0])) return state[0].rawInput;
+	if (Array.isArray(state)) {
+		for (let index = state.length - 1; index >= 0; index--) {
+			const rawInput = extractRawInputFromStateInner(state[index], visited);
+			if (rawInput != null) return rawInput;
+		}
+		return void 0;
+	}
+	const nested = /* @__PURE__ */ new Set();
+	for (const value of Object.values(state)) {
+		const rawInput = extractRawInputFromStateInner(value, visited);
+		if (rawInput != null) nested.add(rawInput);
+	}
+	return nested.size === 1 ? nested.values().next().value : void 0;
+}
+function extractPreliminaryResultFromState(state) {
+	return extractPreliminaryResultFromStateInner(state, /* @__PURE__ */ new Set());
+}
+function extractPreliminaryResultFromStateInner(state, visited) {
+	if (state == null || typeof state !== "object") return void 0;
+	if (visited.has(state)) return void 0;
+	visited.add(state);
+	if (isDeferredParseState(state)) return state.preliminaryResult;
+	if (getRecordedDerivedRawInput(state) != null && "success" in state && typeof state.success === "boolean") {
+		if (state.success === true && "value" in state) return state;
+		if (state.success === false && "error" in state) return state;
+	}
+	if (Array.isArray(state)) {
+		for (let index = state.length - 1; index >= 0; index--) {
+			const result = extractPreliminaryResultFromStateInner(state[index], visited);
+			if (result != null) return result;
+		}
+		return void 0;
+	}
+	const nested = /* @__PURE__ */ new Set();
+	for (const value of Object.values(state)) {
+		const result = extractPreliminaryResultFromStateInner(value, visited);
+		if (result != null) nested.add(result);
+	}
+	return nested.size === 1 ? nested.values().next().value : void 0;
+}
+function getRecordedDerivedRawInput(state) {
+	const recorded = derivedRawInputs.get(state);
+	if (recorded != null) return recorded;
+	if (derivedRawInputKey in state && typeof state[derivedRawInputKey] === "string") return state[derivedRawInputKey];
 	return void 0;
 }
 /**
@@ -658,6 +993,7 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 		completed: []
 	};
 	if (exec == null || exec.phase !== "complete") return empty;
+	registerRuntimeSourceMetadata(nodes, runtime);
 	const session = exec.effectfulCompletionSession;
 	if (session?.policy === "demand-only") {
 		const demandNodes = options?.demandNodes ?? nodes;
@@ -667,6 +1003,12 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 		while (demandAdded) {
 			demandAdded = false;
 			for (const node of nodes) {
+				const metadata = node.parser.dependencyMetadata;
+				if (metadata?.source != null && metadata.derived != null && session.demanded.has(metadata.source.sourceId)) for (const dependencySourceId of metadata.derived.dependencyIds) {
+					if (session.demanded.has(dependencySourceId)) continue;
+					session.demanded.add(dependencySourceId);
+					demandAdded = true;
+				}
 				if (node.requiresSourceId == null || node.providesSourceIds == null) continue;
 				if (session.demanded.has(node.requiresSourceId)) continue;
 				for (const provided of node.providesSourceIds) if (session.demanded.has(provided)) {
@@ -686,7 +1028,7 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 	const schedulable = nodes.filter((node) => node.parser.dependencyMetadata?.source?.completeSource != null || node.prepare != null);
 	if (schedulable.length === 0 && options?.includeStructural !== true) return empty;
 	const completed = [];
-	for (const node of nodes) {
+	for (const node of orderDependencyNodes(nodes)) {
 		if (node.prepare != null) {
 			const barrierFailure = await node.prepare({
 				runtime,
@@ -703,6 +1045,28 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 		const source = node.parser.dependencyMetadata?.source;
 		if (source == null) continue;
 		if (source.completeSource == null) {
+			const derived = node.parser.dependencyMetadata?.derived;
+			const rawInput = getNodeRawInput(node);
+			if (derived != null && rawInput != null) {
+				if (runtime.propagateSourceFailure(derived.dependencyIds, formatDependencyNodeMetavar(node), source.sourceId)) continue;
+				const replayed = await replayDerivedParserAsync(node, rawInput, runtime);
+				if (replayed == null) continue;
+				if (!replayed.success) {
+					runtime.markSourceFailed(source.sourceId);
+					propagateRuntimeSourceFailures(nodes, runtime);
+					return {
+						success: false,
+						error: includeSourceFailureChain(replayed.error, source.sourceId, runtime)
+					};
+				}
+				if (replayed.deferred === true) continue;
+				runtime.registerSource(source.sourceId, replayed.value);
+				if (source.preservesSourceValue && (options?.isReusable?.(node) ?? true)) completed.push({
+					key: node.path[node.path.length - 1],
+					result: replayed
+				});
+				continue;
+			}
 			const collected = options?.isCollected?.(node) ?? options?.isReusable?.(node) ?? true;
 			if (source.extractSourceValue == null || collected === false) continue;
 			const extracted = await source.extractSourceValue(node.state);
@@ -728,9 +1092,10 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 		if (result == null) continue;
 		if (!result.success) {
 			runtime.markSourceFailed(source.sourceId);
+			propagateRuntimeSourceFailures(nodes, runtime);
 			return {
 				success: false,
-				error: result.error
+				error: includeSourceFailureChain(result.error, source.sourceId, runtime)
 			};
 		}
 		if (result.deferred === true) continue;
@@ -960,11 +1325,15 @@ function buildRuntimeNodesFromPairs(pairs, state, parentPath) {
 	const nodes = [];
 	for (const [field, parser] of pairs) {
 		const fieldState = Object.hasOwn(state, field) ? state[field] : void 0;
+		const rawInput = extractRawInputFromState(fieldState);
+		const defaultDependencyValues = getDefaultDependencySnapshot(fieldState);
 		nodes.push({
 			path: [...prefix, field],
 			parser,
 			state: fieldState,
-			matched: isMatchedState(fieldState, parser)
+			matched: isMatchedState(fieldState, parser),
+			...rawInput != null ? { rawInput } : {},
+			...defaultDependencyValues != null ? { defaultDependencyValues } : {}
 		});
 	}
 	return nodes;
@@ -987,15 +1356,42 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 	for (let i = 0; i < parsers.length; i++) {
 		const parser = parsers[i];
 		const elemState = i < stateArray.length ? stateArray[i] : void 0;
+		const rawInput = extractRawInputFromState(elemState);
+		const defaultDependencyValues = getDefaultDependencySnapshot(elemState);
 		nodes.push({
 			path: [...prefix, i],
 			parser,
 			state: elemState,
-			matched: isMatchedState(elemState, parser)
+			matched: isMatchedState(elemState, parser),
+			...rawInput != null ? { rawInput } : {},
+			...defaultDependencyValues != null ? { defaultDependencyValues } : {}
 		});
 	}
 	return nodes;
 }
+function getDefaultDependencySnapshot(state) {
+	return getDefaultDependencySnapshotInner(state, /* @__PURE__ */ new Set());
+}
+function getDefaultDependencySnapshotInner(state, visited) {
+	if (state == null || typeof state !== "object") return void 0;
+	if (visited.has(state)) return void 0;
+	visited.add(state);
+	const direct = getSnapshottedDefaultDependencyValues(state);
+	if (direct != null) return direct;
+	if (Array.isArray(state)) {
+		for (let index = state.length - 1; index >= 0; index--) {
+			const snapshot = getDefaultDependencySnapshotInner(state[index], visited);
+			if (snapshot != null) return snapshot;
+		}
+		return void 0;
+	}
+	const nested = [];
+	for (const value of Object.values(state)) {
+		const snapshot = getDefaultDependencySnapshotInner(value, visited);
+		if (snapshot != null) nested.push(snapshot);
+	}
+	return nested.length === 1 ? nested[0] : void 0;
+}
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/internal/dependency.cjs

@@ -9,6 +9,16 @@ const require_message = require('../message.cjs');
 */
 const dependencySourceMarker = Symbol.for("@optique/core/dependency/dependencySourceMarker");
 /**
+* A unique symbol used to store a dependency source's own identity.
+*
+* This is distinct from {@link dependencyId}, which stores an upstream
+* reference on a derived parser.  A parser wrapped with `dependency()` after
+* derivation carries both values.
+* @internal
+* @since 1.3.0
+*/
+const dependencySourceId = Symbol.for("@optique/core/dependency/dependencySourceId");
+/**
 * A unique symbol used to identify derived value parsers at compile time.
 * This marker is used to distinguish {@link DerivedValueParser} from regular
 * {@link ValueParser} instances.
@@ -66,6 +76,8 @@ const suggestWithDependency = Symbol.for("@optique/core/dependency/suggestWithDe
 * A dependency source wraps an existing value parser and enables creating
 * derived parsers that depend on the parsed value. This is useful for
 * scenarios where one option's valid values depend on another option's value.
+* A derived parser can itself become a source by wrapping it with
+* `dependency()`, allowing dependency chains of any depth.
 *
 * @template M The execution mode of the value parser.
 * @template T The type of value the parser produces.
@@ -87,15 +99,23 @@ const suggestWithDependency = Symbol.for("@optique/core/dependency/suggestWithDe
 *   factory: (dir) => gitBranch({ dir }),
 *   defaultValue: () => process.cwd(),
 * });
+*
+* // A derived parser can provide the next dependency level.
+* const branchSource = dependency(branchParser);
+* const commitParser = branchSource.deriveSync({
+*   metavar: "COMMIT",
+*   factory: (branch) => gitCommit({ branch }),
+*   defaultValue: () => "main",
+* });
 * ```
 * @since 0.10.0
 */
 function dependency(parser) {
 	const id = Symbol();
-	const result = {
-		...parser,
+	const result = Object.create(Object.getPrototypeOf(parser), Object.getOwnPropertyDescriptors(parser));
+	Object.defineProperties(result, Object.getOwnPropertyDescriptors({
 		[dependencySourceMarker]: true,
-		[dependencyId]: id,
+		[dependencySourceId]: id,
 		derive(options) {
 			if (options.mode !== "sync" && options.mode !== "async") throw new TypeError("derive() requires an explicit mode field (\"sync\" or \"async\").");
 			return createDerivedValueParser(id, parser, options, options.mode);
@@ -107,7 +127,7 @@ function dependency(parser) {
 		deriveAsync(options) {
 			return createAsyncDerivedParserFromAsyncFactory(id, options);
 		}
-	};
+	}));
 	return result;
 }
 /**
@@ -166,7 +186,7 @@ function isDerivedValueParser(parser) {
 function deriveFrom(options) {
 	if (options.mode !== "sync" && options.mode !== "async") throw new TypeError("deriveFrom() requires an explicit mode field (\"sync\" or \"async\").");
 	const depsAsync = options.dependencies.some((dep) => dep.mode === "async");
-	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
+	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencySourceId] : Symbol();
 	const factoryReturnsAsync = options.mode === "async";
 	const isAsync = depsAsync || factoryReturnsAsync;
 	if (isAsync) {
@@ -191,7 +211,7 @@ function deriveFrom(options) {
 */
 function deriveFromSync(options) {
 	const depsAsync = options.dependencies.some((dep) => dep.mode === "async");
-	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
+	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencySourceId] : Symbol();
 	if (depsAsync) return createAsyncDerivedFromParserFromSyncFactory(sourceId, options);
 	return createSyncDerivedFromParser(sourceId, options);
 }
@@ -210,7 +230,7 @@ function deriveFromSync(options) {
 * @since 0.10.0
 */
 function deriveFromAsync(options) {
-	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
+	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencySourceId] : Symbol();
 	return createAsyncDerivedFromParserFromAsyncFactory(sourceId, options);
 }
 function isAsyncModeParser(parser) {
@@ -282,7 +302,7 @@ async function parseDerivedResultWithSnapshotAsync(parser, input, sourceValues)
 	return attachDefaultDependencySnapshot(await parseDerivedResultAsync(parser, input), snapshot);
 }
 function createSyncDerivedFromParser(sourceId, options) {
-	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
+	const alldependencyIds = options.dependencies.map((dep) => dep[dependencySourceId]);
 	return {
 		mode: "sync",
 		metavar: options.metavar,
@@ -387,7 +407,7 @@ function createSyncDerivedFromParser(sourceId, options) {
 * factory returns an async parser.
 */
 function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
-	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
+	const alldependencyIds = options.dependencies.map((dep) => dep[dependencySourceId]);
 	return {
 		mode: "async",
 		metavar: options.metavar,
@@ -475,7 +495,7 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
 * sources are async but the factory returns a sync parser.
 */
 function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
-	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
+	const alldependencyIds = options.dependencies.map((dep) => dep[dependencySourceId]);
 	return {
 		mode: "async",
 		metavar: options.metavar,
@@ -1089,6 +1109,7 @@ exports.deferredParseMarker = deferredParseMarker;
 exports.dependency = dependency;
 exports.dependencyId = dependencyId;
 exports.dependencyIds = dependencyIds;
+exports.dependencySourceId = dependencySourceId;
 exports.dependencySourceMarker = dependencySourceMarker;
 exports.dependencySourceStateMarker = dependencySourceStateMarker;
 exports.deriveFrom = deriveFrom;