@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/dependency-runtime.cjs

@@ -0,0 +1,698 @@
+const require_message = require('./message.cjs');
+const require_dependency = require('./internal/dependency.cjs');
+const require_parser = require('./internal/parser.cjs');
+
+//#region src/dependency-runtime.ts
+const symbolIds = /* @__PURE__ */ new WeakMap();
+let symbolCounter = 0;
+function stableSymbolKey(sym) {
+	const registeredKey = Symbol.keyFor(sym);
+	if (registeredKey !== void 0) return `reg:${registeredKey}`;
+	let id = symbolIds.get(sym);
+	if (id === void 0) {
+		id = `sym:${symbolCounter++}`;
+		symbolIds.set(sym, id);
+	}
+	return id;
+}
+var DependencyRuntimeContextImpl = class {
+	registry;
+	#replayCache = /* @__PURE__ */ new Map();
+	#failedSources = /* @__PURE__ */ new Set();
+	constructor(registry) {
+		if (registry instanceof FailedAwareRegistry) {
+			this.registry = registry.rebindFailedSources(this.#failedSources);
+			return;
+		}
+		this.registry = new FailedAwareRegistry(registry, this.#failedSources);
+	}
+	registerSource(sourceId, value, _origin) {
+		this.registry.set(sourceId, value);
+	}
+	hasSource(sourceId) {
+		return this.registry.has(sourceId);
+	}
+	getSource(sourceId) {
+		return this.registry.get(sourceId);
+	}
+	resolveDependencies(request) {
+		return resolveRequest(this, request);
+	}
+	getReplayResult(key) {
+		return this.#replayCache.get(serializeReplayKey(key));
+	}
+	setReplayResult(key, result) {
+		this.#replayCache.set(serializeReplayKey(key), result);
+	}
+	markSourceFailed(sourceId) {
+		this.#failedSources.add(sourceId);
+	}
+	isSourceFailed(sourceId) {
+		return this.#failedSources.has(sourceId);
+	}
+	getSuggestionDependencies(request) {
+		return resolveRequest(this, request);
+	}
+};
+/**
+* Registry wrapper that hides values for sources that have failed.
+*
+* The wrapper lets clones share an underlying registry while maintaining
+* an isolated failed-source view, so later lookups do not reuse stale
+* values after extraction errors.
+*
+* @internal
+*/
+var FailedAwareRegistry = class FailedAwareRegistry {
+	#inner;
+	#failedSources;
+	constructor(inner, failedSources) {
+		this.#inner = inner;
+		this.#failedSources = failedSources;
+	}
+	set(id, value) {
+		this.#inner.set(id, value);
+		this.#failedSources.delete(id);
+	}
+	get(id) {
+		if (this.#failedSources.has(id)) return void 0;
+		return this.#inner.get(id);
+	}
+	has(id) {
+		if (this.#failedSources.has(id)) return false;
+		return this.#inner.has(id);
+	}
+	copyFailedSources(target) {
+		for (const sourceId of this.#failedSources) target.add(sourceId);
+	}
+	rebindFailedSources(target) {
+		this.copyFailedSources(target);
+		return new FailedAwareRegistry(this.#inner, target);
+	}
+	clone() {
+		const failedSources = new Set(this.#failedSources);
+		const innerClone = this.#inner.clone();
+		return innerClone instanceof FailedAwareRegistry ? innerClone.rebindFailedSources(failedSources) : new FailedAwareRegistry(innerClone, failedSources);
+	}
+};
+function resolveRequest(ctx, request) {
+	const values = [];
+	const usedDefaults = [];
+	let resolvedCount = 0;
+	let defaultedCount = 0;
+	for (let i = 0; i < request.dependencyIds.length; i++) {
+		const id = request.dependencyIds[i];
+		if (ctx.isSourceFailed(id)) {
+			values.push(void 0);
+			usedDefaults.push(false);
+		} else if (ctx.hasSource(id)) {
+			values.push(ctx.getSource(id));
+			usedDefaults.push(false);
+			resolvedCount++;
+		} else if (request.defaultValues != null && i < request.defaultValues.length) {
+			values.push(request.defaultValues[i]);
+			usedDefaults.push(true);
+			defaultedCount++;
+		} else {
+			values.push(void 0);
+			usedDefaults.push(false);
+		}
+	}
+	const total = request.dependencyIds.length;
+	const foundOrDefaulted = resolvedCount + defaultedCount;
+	let kind;
+	if (foundOrDefaulted === total) kind = "resolved";
+	else if (resolvedCount === 0 && defaultedCount === 0) kind = "missing";
+	else kind = "partial";
+	return {
+		kind,
+		values,
+		usedDefaults
+	};
+}
+/** Length-prefix a segment so that no delimiter escaping is needed. */
+function lengthPrefix(s) {
+	return `${s.length}:${s}`;
+}
+function serializePathSegment(p) {
+	if (typeof p === "string") return lengthPrefix(`s${p}`);
+	if (typeof p === "number") return lengthPrefix(`n${p}`);
+	return lengthPrefix(`y${stableSymbolKey(p)}`);
+}
+function serializeReplayKey(key) {
+	const pathStr = key.path.map(serializePathSegment).join("");
+	return `${pathStr}\x01${lengthPrefix(key.rawInput)}\x01${key.dependencyFingerprint}\x01${key.parserFingerprint}`;
+}
+/** Minimal registry implementation for standalone use. */
+var SimpleRegistry = class SimpleRegistry {
+	#map = /* @__PURE__ */ new Map();
+	set(id, value) {
+		this.#map.set(id, value);
+	}
+	get(id) {
+		return this.#map.get(id);
+	}
+	has(id) {
+		return this.#map.has(id);
+	}
+	clone() {
+		const copy = new SimpleRegistry();
+		for (const [k, v] of this.#map) copy.set(k, v);
+		return copy;
+	}
+};
+/**
+* Creates a new {@link DependencyRuntimeContext}.
+*
+* @param registry Optional existing registry to wrap for bridge interop.
+* @returns A new runtime context.
+* @internal
+* @since 1.0.0
+*/
+function createDependencyRuntimeContext(registry) {
+	return new DependencyRuntimeContextImpl(registry ?? new SimpleRegistry());
+}
+/**
+* Creates a stable fingerprint from dependency values.
+*
+* @param values The dependency values to fingerprint.
+* @returns A string fingerprint.
+* @internal
+* @since 1.0.0
+*/
+function createDependencyFingerprint(values) {
+	return values.map((v) => {
+		const raw = fingerprintValue(v);
+		return `${raw.length}:${raw}`;
+	}).join("");
+}
+const objectIds = /* @__PURE__ */ new WeakMap();
+let objectIdCounter = 0;
+function fingerprintValue(v) {
+	if (v === void 0) return "u:";
+	if (v === null) return "n:";
+	if (typeof v === "string") return `s:${v}`;
+	if (typeof v === "number") {
+		if (Object.is(v, -0)) return "d:-0";
+		return `d:${v}`;
+	}
+	if (typeof v === "boolean") return `b:${v}`;
+	if (typeof v === "symbol") return `y:${stableSymbolKey(v)}`;
+	if (typeof v === "object" || typeof v === "function") {
+		let id = objectIds.get(v);
+		if (id === void 0) {
+			id = objectIdCounter++;
+			objectIds.set(v, id);
+		}
+		return `o:${id}`;
+	}
+	return `?:${String(v)}`;
+}
+/**
+* Creates a {@link ReplayKey} from a path, raw input, and dependency values.
+*
+* @param path The parser path.
+* @param rawInput The raw input string.
+* @param dependencyValues The dependency values.
+* @returns A replay key.
+* @internal
+* @since 1.0.0
+*/
+const parserIds = /* @__PURE__ */ new WeakMap();
+let parserIdCounter = 0;
+/** Get a stable identity string for a replayParse function reference. */
+function getParserFingerprint(replayParse) {
+	let id = parserIds.get(replayParse);
+	if (id === void 0) {
+		id = parserIdCounter++;
+		parserIds.set(replayParse, id);
+	}
+	return `p:${id}`;
+}
+function createReplayKey(path, rawInput, dependencyValues, replayParse) {
+	return {
+		path,
+		rawInput,
+		dependencyFingerprint: createDependencyFingerprint(dependencyValues),
+		parserFingerprint: replayParse != null ? getParserFingerprint(replayParse) : ""
+	};
+}
+/**
+* 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
+*/
+function collectExplicitSourceValues(nodes, runtime) {
+	for (const node of nodes) {
+		const meta = node.parser.dependencyMetadata;
+		if (meta?.source == null) continue;
+		if (meta.source.extractSourceValue == 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);
+	}
+}
+function registerExplicitSourceValue(sourceId, result, runtime) {
+	if (result == null) return;
+	if (result.success) runtime.registerSource(sourceId, result.value, "cli");
+	else runtime.markSourceFailed(sourceId);
+}
+function isPromiseLike(value) {
+	return value != null && (typeof value === "object" || typeof value === "function") && "then" in value && typeof value.then === "function";
+}
+/**
+* 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
+*/
+async function collectExplicitSourceValuesAsync(nodes, runtime) {
+	for (const node of nodes) {
+		const meta = node.parser.dependencyMetadata;
+		if (meta?.source == null) continue;
+		if (meta.source.extractSourceValue == null) continue;
+		const result = await meta.source.extractSourceValue(node.state);
+		registerExplicitSourceValue(meta.source.sourceId, result, runtime);
+	}
+}
+/**
+* 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
+*/
+function fillMissingSourceDefaults(nodes, runtime) {
+	const failures = [];
+	for (const node of nodes) {
+		const meta = node.parser.dependencyMetadata;
+		if (meta?.source == null) continue;
+		if (runtime.hasSource(meta.source.sourceId)) continue;
+		if (runtime.isSourceFailed(meta.source.sourceId)) continue;
+		if (node.matched === true) continue;
+		if (!meta.source.preservesSourceValue) continue;
+		if (meta.source.getMissingSourceValue == null) continue;
+		let result;
+		try {
+			result = meta.source.getMissingSourceValue();
+		} catch (e) {
+			const msg = e instanceof Error ? e.message : String(e);
+			failures.push({
+				sourceId: meta.source.sourceId,
+				path: node.path,
+				error: {
+					success: false,
+					error: require_message.message`Default value evaluation failed: ${msg}`
+				}
+			});
+			continue;
+		}
+		if (isPromiseLike(result)) throw new TypeError(`fillMissingSourceDefaults() received an async getMissingSourceValue() result for ${String(meta.source.sourceId)}. Use fillMissingSourceDefaultsAsync() instead.`);
+		if (result.success) runtime.registerSource(meta.source.sourceId, result.value, "default");
+		else failures.push({
+			sourceId: meta.source.sourceId,
+			path: node.path,
+			error: result
+		});
+	}
+	return failures;
+}
+/**
+* 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
+*/
+async function fillMissingSourceDefaultsAsync(nodes, runtime) {
+	const failures = [];
+	for (const node of nodes) {
+		const meta = node.parser.dependencyMetadata;
+		if (meta?.source == null) continue;
+		if (runtime.hasSource(meta.source.sourceId)) continue;
+		if (runtime.isSourceFailed(meta.source.sourceId)) continue;
+		if (node.matched === true) continue;
+		if (!meta.source.preservesSourceValue) continue;
+		if (meta.source.getMissingSourceValue == null) continue;
+		let result;
+		try {
+			result = await meta.source.getMissingSourceValue();
+		} catch (e) {
+			const msg = e instanceof Error ? e.message : String(e);
+			failures.push({
+				sourceId: meta.source.sourceId,
+				path: node.path,
+				error: {
+					success: false,
+					error: require_message.message`Default value evaluation failed: ${msg}`
+				}
+			});
+			continue;
+		}
+		if (result.success) runtime.registerSource(meta.source.sourceId, result.value, "default");
+		else failures.push({
+			sourceId: meta.source.sourceId,
+			path: node.path,
+			error: result
+		});
+	}
+	return failures;
+}
+/**
+* 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
+*/
+function replayDerivedParser(node, rawInput, runtime) {
+	const meta = node.parser.dependencyMetadata;
+	if (meta?.derived == null) return void 0;
+	let defaults = node.defaultDependencyValues;
+	if (defaults == null && meta.derived.getDefaultDependencyValues != null) try {
+		defaults = meta.derived.getDefaultDependencyValues();
+	} catch {
+		return void 0;
+	}
+	const resolution = runtime.resolveDependencies({
+		dependencyIds: meta.derived.dependencyIds,
+		defaultValues: defaults
+	});
+	if (resolution.kind === "missing") return void 0;
+	if (resolution.kind === "partial") return void 0;
+	const key = createReplayKey(node.path, rawInput, resolution.values, meta.derived.replayParse);
+	const cached = runtime.getReplayResult(key);
+	if (cached != null) return cached;
+	const result = meta.derived.replayParse(rawInput, resolution.values);
+	if (isPromiseLike(result)) throw new TypeError("replayDerivedParser() received an async replayParse() result. Use replayDerivedParserAsync() instead.");
+	runtime.setReplayResult(key, result);
+	return result;
+}
+/**
+* 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
+*/
+async function replayDerivedParserAsync(node, rawInput, runtime) {
+	const meta = node.parser.dependencyMetadata;
+	if (meta?.derived == null) return void 0;
+	let defaults = node.defaultDependencyValues;
+	if (defaults == null && meta.derived.getDefaultDependencyValues != null) try {
+		defaults = meta.derived.getDefaultDependencyValues();
+	} catch {
+		return void 0;
+	}
+	const resolution = runtime.resolveDependencies({
+		dependencyIds: meta.derived.dependencyIds,
+		defaultValues: defaults
+	});
+	if (resolution.kind === "missing") return void 0;
+	if (resolution.kind === "partial") return void 0;
+	const key = createReplayKey(node.path, rawInput, resolution.values, meta.derived.replayParse);
+	const cached = runtime.getReplayResult(key);
+	if (cached != null) return cached;
+	const result = await meta.derived.replayParse(rawInput, resolution.values);
+	runtime.setReplayResult(key, result);
+	return result;
+}
+/**
+* Checks if a value is a plain object (not a class instance) for the
+* purpose of recursive state traversal.
+*/
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* Resolves a single {@link DeferredParseState} using the dependency runtime.
+*
+* Returns the replay result if all dependencies are available, or the
+* preliminary result if dependencies are missing.
+*/
+function resolveSingleDeferred(deferred, runtime) {
+	const isMultiDep = deferred.dependencyIds != null && deferred.dependencyIds.length > 0;
+	const depIds = isMultiDep ? deferred.dependencyIds : [deferred.dependencyId];
+	const resolution = runtime.resolveDependencies({
+		dependencyIds: depIds,
+		defaultValues: deferred.defaultValues
+	});
+	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);
+	if (isPromiseLike(result)) throw new TypeError("resolveStateWithRuntime() received an async parseWithDependency() result. Use resolveStateWithRuntimeAsync() instead.");
+	return result;
+}
+/**
+* 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.
+*/
+function collectSourcesFromState(state, runtime, visited = /* @__PURE__ */ new WeakSet(), excludedFields) {
+	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];
+		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 (Array.isArray(state)) {
+		for (const item of state) collectSourcesFromState(item, runtime, visited);
+		return;
+	}
+	if (typeof state === "object") for (const key of Reflect.ownKeys(state)) {
+		if (excludedFields?.has(key)) continue;
+		collectSourcesFromState(state[key], runtime, visited);
+	}
+}
+/**
+* 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
+*/
+function resolveStateWithRuntime(state, runtime) {
+	collectSourcesFromState(state, runtime);
+	return resolveDeferredInState(state, runtime);
+}
+/** Pass 2 helper: recursively replace DeferredParseState with resolved values. */
+function resolveDeferredInState(state, runtime, visited = /* @__PURE__ */ new WeakSet()) {
+	if (state == null) return state;
+	if (typeof state === "object") {
+		if (visited.has(state)) return state;
+		visited.add(state);
+	}
+	if (require_dependency.isDeferredParseState(state)) return resolveSingleDeferred(state, runtime);
+	if (require_dependency.isDependencySourceState(state)) return state;
+	if (Array.isArray(state)) {
+		const resolved = state.map((item) => resolveDeferredInState(item, runtime, visited));
+		return resolved.every((item, index) => item === state[index]) ? state : resolved;
+	}
+	if (isPlainObject(state)) {
+		const keys = Reflect.ownKeys(state);
+		const resolvedEntries = keys.map((key) => [key, resolveDeferredInState(state[key], runtime, visited)]);
+		if (resolvedEntries.every(([key, value]) => value === state[key])) return state;
+		const resolved = Object.create(Object.getPrototypeOf(state));
+		for (const [key, value] of resolvedEntries) resolved[key] = value;
+		return resolved;
+	}
+	return state;
+}
+/**
+* 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
+*/
+function resolveStateWithRuntimeAsync(state, runtime) {
+	collectSourcesFromState(state, runtime);
+	return resolveDeferredInStateAsync(state, runtime);
+}
+/** Async pass 2 helper. */
+async function resolveDeferredInStateAsync(state, runtime, visited = /* @__PURE__ */ new WeakSet()) {
+	if (state == null) return state;
+	if (typeof state === "object") {
+		if (visited.has(state)) return state;
+		visited.add(state);
+	}
+	if (require_dependency.isDeferredParseState(state)) {
+		const deferred = state;
+		const isMultiDep = deferred.dependencyIds != null && deferred.dependencyIds.length > 0;
+		const depIds = isMultiDep ? deferred.dependencyIds : [deferred.dependencyId];
+		const resolution = runtime.resolveDependencies({
+			dependencyIds: depIds,
+			defaultValues: deferred.defaultValues
+		});
+		if (resolution.kind !== "resolved") return deferred.preliminaryResult;
+		if (resolution.usedDefaults.every((d) => d)) return deferred.preliminaryResult;
+		const depValue = isMultiDep ? resolution.values : resolution.values[0];
+		return Promise.resolve(deferred.parser[require_dependency.parseWithDependency](deferred.rawInput, depValue));
+	}
+	if (require_dependency.isDependencySourceState(state)) return state;
+	if (Array.isArray(state)) {
+		const resolved = await Promise.all(state.map((item) => resolveDeferredInStateAsync(item, runtime, visited)));
+		return resolved.every((item, index) => item === state[index]) ? state : resolved;
+	}
+	if (isPlainObject(state)) {
+		const keys = Reflect.ownKeys(state);
+		const resolvedEntries = await Promise.all(keys.map(async (key) => {
+			return [key, await resolveDeferredInStateAsync(state[key], runtime, visited)];
+		}));
+		if (resolvedEntries.every(([key, value]) => value === state[key])) return state;
+		const resolved = Object.create(Object.getPrototypeOf(state));
+		for (const [key, value] of resolvedEntries) resolved[key] = value;
+		return resolved;
+	}
+	return state;
+}
+/**
+* Determines whether a parser state represents an explicit match (the user
+* provided input) rather than an initial/pending state.
+*/
+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 (fieldState === parser.initialState) return false;
+	return true;
+}
+/**
+* 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
+*/
+function buildRuntimeNodesFromPairs(pairs, state, parentPath) {
+	const prefix = parentPath ?? [];
+	const nodes = [];
+	for (const [field, parser] of pairs) {
+		const fieldState = Object.hasOwn(state, field) ? state[field] : void 0;
+		nodes.push({
+			path: [...prefix, field],
+			parser,
+			state: fieldState,
+			matched: isMatchedState(fieldState, parser)
+		});
+	}
+	return nodes;
+}
+/**
+* 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
+*/
+function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
+	const prefix = parentPath ?? [];
+	const nodes = [];
+	for (let i = 0; i < parsers.length; i++) {
+		const parser = parsers[i];
+		const elemState = i < stateArray.length ? stateArray[i] : void 0;
+		nodes.push({
+			path: [...prefix, i],
+			parser,
+			state: elemState,
+			matched: isMatchedState(elemState, parser)
+		});
+	}
+	return nodes;
+}
+
+//#endregion
+exports.buildRuntimeNodesFromArray = buildRuntimeNodesFromArray;
+exports.buildRuntimeNodesFromPairs = buildRuntimeNodesFromPairs;
+exports.collectExplicitSourceValues = collectExplicitSourceValues;
+exports.collectExplicitSourceValuesAsync = collectExplicitSourceValuesAsync;
+exports.collectSourcesFromState = collectSourcesFromState;
+exports.createDependencyRuntimeContext = createDependencyRuntimeContext;
+exports.fillMissingSourceDefaults = fillMissingSourceDefaults;
+exports.fillMissingSourceDefaultsAsync = fillMissingSourceDefaultsAsync;
+exports.replayDerivedParser = replayDerivedParser;
+exports.replayDerivedParserAsync = replayDerivedParserAsync;
+exports.resolveStateWithRuntime = resolveStateWithRuntime;
+exports.resolveStateWithRuntimeAsync = resolveStateWithRuntimeAsync;