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

package/dist/dependency-runtime.cjs

@@ -3,6 +3,32 @@ const require_internal_dependency = require('./internal/dependency.cjs');
 const require_internal_parser = require('./internal/parser.cjs');
 
 //#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,182 @@ 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);
+	}
+}
+function includeSourceFailureChain(error, sourceId, runtime) {
+	const chain = runtime.getSourceFailureChain(sourceId);
+	return chain == null || chain.length < 2 ? error : require_message.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 +604,7 @@ function fillMissingSourceDefaults(nodes, runtime) {
 			error: result
 		});
 	}
+	resolveDerivedSourceValues(nodes, runtime);
 	return failures;
 }
 /**
@@ -383,6 +649,7 @@ async function fillMissingSourceDefaultsAsync(nodes, runtime) {
 			error: result
 		});
 	}
+	await resolveDerivedSourceValuesAsync(nodes, runtime);
 	return failures;
 }
 /**
@@ -414,6 +681,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 +720,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 +746,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 (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;
+	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 (require_internal_dependency.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 +983,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 +993,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 +1018,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 +1035,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 +1082,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 +1315,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 +1346,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 = require_internal_dependency.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
 exports.buildRuntimeNodesFromArray = buildRuntimeNodesFromArray;
@@ -1009,12 +1395,17 @@ exports.createDependencyFingerprint = createDependencyFingerprint;
 exports.createDependencyRuntimeContext = createDependencyRuntimeContext;
 exports.createReplayKey = createReplayKey;
 exports.defineForwardedEffectfulSchedulingNodes = defineForwardedEffectfulSchedulingNodes;
+exports.derivedRawInputKey = derivedRawInputKey;
 exports.effectfulSchedulingNodesKey = effectfulSchedulingNodesKey;
 exports.extractRawInputFromState = extractRawInputFromState;
 exports.fillMissingSourceDefaults = fillMissingSourceDefaults;
 exports.fillMissingSourceDefaultsAsync = fillMissingSourceDefaultsAsync;
+exports.orderDependencyNodes = orderDependencyNodes;
+exports.recordDerivedRawInput = recordDerivedRawInput;
 exports.replayDerivedParser = replayDerivedParser;
 exports.replayDerivedParserAsync = replayDerivedParserAsync;
+exports.resolveDerivedSourceValues = resolveDerivedSourceValues;
+exports.resolveDerivedSourceValuesAsync = resolveDerivedSourceValuesAsync;
 exports.resolveStateWithRuntime = resolveStateWithRuntime;
 exports.resolveStateWithRuntimeAsync = resolveStateWithRuntimeAsync;
 exports.serializeSchedulingPath = serializeSchedulingPath;

package/dist/dependency-runtime.d.cts

@@ -7,6 +7,29 @@ import { ExecutionContext } from "./internal/parser.cjs";
 
 //#region src/dependency-runtime.d.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
+ */
+declare const derivedRawInputKey: unique symbol;
+/**
+ * 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
+ */
+declare function recordDerivedRawInput(state: object, rawInput: string): void;
 /**
  * A request to resolve one or more dependency values.
  *
@@ -89,6 +112,8 @@ interface RuntimeNode {
   };
   /** The parser's current state. */
   readonly state: unknown;
+  /** Raw input captured for a derived parser, when this node matched. */
+  readonly rawInput?: string;
   /**
    * Whether the parser consumed explicit input during parsing.
    * When `true`, the parser's state reflects user-provided input (which
@@ -142,6 +167,20 @@ interface RuntimeNode {
    */
   readonly requiresSourceId?: symbol;
 }
+/**
+ * Options for resolving matched derived source values.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface ResolveDerivedSourceValuesOptions {
+  /**
+   * Whether an unpopulated effectful source can still provide a value later.
+   * Suggestion generation sets this to `"inactive"` because it never runs
+   * effects and must let downstream parsers use declared dependency defaults.
+   */
+  readonly effectfulProviders?: "pending" | "inactive";
+}
 /**
  * The context handed to a {@link RuntimeNode.prepare} barrier.
  *
@@ -190,6 +229,15 @@ interface DependencyRuntimeContext {
    * defaults for failed sources.
    */
   markSourceFailed(sourceId: symbol): void;
+  /** Register a source's diagnostic label and upstream dependencies. */
+  registerSourceMetadata(sourceId: symbol, label: string, dependencyIds?: readonly symbol[]): void;
+  /**
+   * Propagate a failed upstream source through one derived dependency edge.
+   * Returns whether any upstream source had failed.
+   */
+  propagateSourceFailure(dependencyIds: readonly symbol[], label: string, sourceId?: symbol): boolean;
+  /** Return the most informative dependency chain for a failed source. */
+  getSourceFailureChain(sourceId: symbol): readonly string[] | undefined;
   /**
    * Check if a source was explicitly attempted but failed validation.
    */
@@ -242,6 +290,25 @@ declare function collectExplicitSourceValues(nodes: readonly RuntimeNode[], runt
  * @since 1.0.0
  */
 declare function collectExplicitSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<void>;
+/**
+ * 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
+ */
+declare function orderDependencyNodes(nodes: readonly RuntimeNode[]): readonly RuntimeNode[];
+/** Resolves and publishes matched derived sources in stable dependency order. */
+declare function resolveDerivedSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): void;
+/** Async version of {@link resolveDerivedSourceValues}. */
+declare function resolveDerivedSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): Promise<void>;
 /**
  * Fills missing source defaults for source parsers whose state is
  * unpopulated.
@@ -616,4 +683,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };