@optique/core 1.0.0-dev.1602 → 1.0.0-dev.1611

package/dist/dependency-runtime.cjs

@@ -0,0 +1,328 @@
+const require_dependency = require('./dependency.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) {
+		this.registry = registry;
+	}
+	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);
+	}
+};
+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.hasSource(id)) {
+			values.push(ctx.getSource(id));
+			usedDefaults.push(false);
+			resolvedCount++;
+		} else if (ctx.isSourceFailed(id)) {
+			values.push(void 0);
+			usedDefaults.push(false);
+		} 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());
+}
+/**
+* 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.
+* @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 (result == null) continue;
+		if (result.success) runtime.registerSource(meta.source.sourceId, result.value, "cli");
+		else runtime.markSourceFailed(meta.source.sourceId);
+	}
+}
+/**
+* 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;
+	const depValue = isMultiDep ? resolution.values : resolution.values[0];
+	const result = deferred.parser[require_dependency.parseWithDependency](deferred.rawInput, depValue);
+	if (result instanceof Promise) return deferred.preliminaryResult;
+	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.
+*/
+function collectSourcesFromState(state, runtime, visited = /* @__PURE__ */ new WeakSet()) {
+	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)) 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.
+* @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)) return state.map((item) => resolveDeferredInState(item, runtime, visited));
+	if (isPlainObject(state)) {
+		const resolved = Object.create(Object.getPrototypeOf(state));
+		for (const key of Reflect.ownKeys(state)) resolved[key] = resolveDeferredInState(state[key], runtime, visited);
+		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;
+		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)) return Promise.all(state.map((item) => resolveDeferredInStateAsync(item, runtime, visited)));
+	if (isPlainObject(state)) {
+		const resolved = Object.create(Object.getPrototypeOf(state));
+		const keys = Reflect.ownKeys(state);
+		await Promise.all(keys.map(async (key) => {
+			resolved[key] = await resolveDeferredInStateAsync(state[key], runtime, visited);
+		}));
+		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;
+	if (Array.isArray(fieldState) && fieldState.length === 1 && require_dependency.isPendingDependencySourceState(fieldState[0])) return false;
+	if (require_dependency.isPendingDependencySourceState(fieldState)) 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;
+}
+
+//#endregion
+exports.buildRuntimeNodesFromPairs = buildRuntimeNodesFromPairs;
+exports.collectExplicitSourceValues = collectExplicitSourceValues;
+exports.collectSourcesFromState = collectSourcesFromState;
+exports.createDependencyRuntimeContext = createDependencyRuntimeContext;
+exports.resolveStateWithRuntime = resolveStateWithRuntime;
+exports.resolveStateWithRuntimeAsync = resolveStateWithRuntimeAsync;

package/dist/dependency-runtime.js

@@ -0,0 +1,323 @@
+import { dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, parseWithDependency } from "./dependency.js";
+
+//#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) {
+		this.registry = registry;
+	}
+	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);
+	}
+};
+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.hasSource(id)) {
+			values.push(ctx.getSource(id));
+			usedDefaults.push(false);
+			resolvedCount++;
+		} else if (ctx.isSourceFailed(id)) {
+			values.push(void 0);
+			usedDefaults.push(false);
+		} 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());
+}
+/**
+* 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.
+* @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 (result == null) continue;
+		if (result.success) runtime.registerSource(meta.source.sourceId, result.value, "cli");
+		else runtime.markSourceFailed(meta.source.sourceId);
+	}
+}
+/**
+* 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;
+	const depValue = isMultiDep ? resolution.values : resolution.values[0];
+	const result = deferred.parser[parseWithDependency](deferred.rawInput, depValue);
+	if (result instanceof Promise) return deferred.preliminaryResult;
+	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.
+*/
+function collectSourcesFromState(state, runtime, visited = /* @__PURE__ */ new WeakSet()) {
+	if (state == null || typeof state !== "object") return;
+	if (visited.has(state)) return;
+	visited.add(state);
+	if (isDependencySourceState(state)) {
+		const depId = state[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 (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)) 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.
+* @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 (isDeferredParseState(state)) return resolveSingleDeferred(state, runtime);
+	if (isDependencySourceState(state)) return state;
+	if (Array.isArray(state)) return state.map((item) => resolveDeferredInState(item, runtime, visited));
+	if (isPlainObject(state)) {
+		const resolved = Object.create(Object.getPrototypeOf(state));
+		for (const key of Reflect.ownKeys(state)) resolved[key] = resolveDeferredInState(state[key], runtime, visited);
+		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 (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;
+		const depValue = isMultiDep ? resolution.values : resolution.values[0];
+		return Promise.resolve(deferred.parser[parseWithDependency](deferred.rawInput, depValue));
+	}
+	if (isDependencySourceState(state)) return state;
+	if (Array.isArray(state)) return Promise.all(state.map((item) => resolveDeferredInStateAsync(item, runtime, visited)));
+	if (isPlainObject(state)) {
+		const resolved = Object.create(Object.getPrototypeOf(state));
+		const keys = Reflect.ownKeys(state);
+		await Promise.all(keys.map(async (key) => {
+			resolved[key] = await resolveDeferredInStateAsync(state[key], runtime, visited);
+		}));
+		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;
+	if (Array.isArray(fieldState) && fieldState.length === 1 && isPendingDependencySourceState(fieldState[0])) return false;
+	if (isPendingDependencySourceState(fieldState)) 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;
+}
+
+//#endregion
+export { buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectSourcesFromState, createDependencyRuntimeContext, resolveStateWithRuntime, resolveStateWithRuntimeAsync };

package/dist/parser.d.cts

@@ -325,6 +325,25 @@ interface ExecutionContext {
    * @since 1.0.0
    */
   readonly dependencyRuntime?: DependencyRuntimeContext;
+  /**
+   * Immutable map of pre-completed results from the parent construct's
+   * Phase 1, keyed by field name.  Each construct passes its own
+   * `preCompleteAndRegisterDependencies` results directly to children
+   * in Phase 3.  Children read it in their own Phase 1 to avoid
+   * re-evaluating non-idempotent default thunks, but never write to
+   * it — this prevents sibling completions from leaking into each
+   * other.
+   *
+   * Field-name keying naturally handles parser reuse across different
+   * fields (e.g., `merge(object({a: shared}), object({b: shared}))`)
+   * because each field maps to its own result regardless of whether
+   * the underlying parser instance is the same.
+   *
+   * @see https://github.com/dahlia/optique/issues/762
+   * @internal
+   * @since 1.0.0
+   */
+  readonly preCompletedByParser?: ReadonlyMap<string | symbol, unknown>;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.

package/dist/parser.d.ts

@@ -325,6 +325,25 @@ interface ExecutionContext {
    * @since 1.0.0
    */
   readonly dependencyRuntime?: DependencyRuntimeContext;
+  /**
+   * Immutable map of pre-completed results from the parent construct's
+   * Phase 1, keyed by field name.  Each construct passes its own
+   * `preCompleteAndRegisterDependencies` results directly to children
+   * in Phase 3.  Children read it in their own Phase 1 to avoid
+   * re-evaluating non-idempotent default thunks, but never write to
+   * it — this prevents sibling completions from leaking into each
+   * other.
+   *
+   * Field-name keying naturally handles parser reuse across different
+   * fields (e.g., `merge(object({a: shared}), object({b: shared}))`)
+   * because each field maps to its own result regardless of whether
+   * the underlying parser instance is the same.
+   *
+   * @see https://github.com/dahlia/optique/issues/762
+   * @internal
+   * @since 1.0.0
+   */
+  readonly preCompletedByParser?: ReadonlyMap<string | symbol, unknown>;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.