@optique/core 1.3.0-dev.2576 → 1.3.0-dev.2581

package/dist/constructs.cjs

@@ -438,8 +438,12 @@ async function scheduleEffectfulSourceCompletions(nodes, state, runtime, exec, p
 		}
 	}
 	const republish = exec?.republishCachedCompletions === true;
+	const publishedSourceIds = /* @__PURE__ */ new Set();
 	const effectful = await require_dependency_runtime.completeEffectfulSourcesAsync(expandedNodes, state, runtime, exec, {
 		...demandNodes != null ? { demandNodes: expandEffectfulRuntimeNodes(demandNodes) } : {},
+		onPublish: (id) => {
+			publishedSourceIds.add(id);
+		},
 		isReusable: (node) => direct.has(node),
 		isCollected: republish ? () => true : (node) => collected.has(node),
 		...republish ? { includeStructural: true } : {}
@@ -452,6 +456,13 @@ async function scheduleEffectfulSourceCompletions(nodes, state, runtime, exec, p
 		const cacheKey = typeof key === "number" ? String(key) : key;
 		preCompleted.set(cacheKey, result);
 	}
+	require_dependency_runtime.recordSourceScope(runtime, publishedSourceIds, [...collected].flatMap((node) => {
+		const source = node.parser.dependencyMetadata?.source;
+		return source == null ? [] : [{
+			sourceId: source.sourceId,
+			path: node.path
+		}];
+	}));
 	return void 0;
 }
 function buildIndexedParserPairs(parsers) {
@@ -2251,6 +2262,7 @@ function filterExcludedFieldParsers(pairs, excludedFields) {
 * @internal
 */
 function preCompleteAndRegisterDependencies(state, fieldParserPairs, registry, exec) {
+	if (exec?.dependencyRuntime != null) require_dependency_runtime.releaseUncollectedSourceValues(expandSourceCollectionNodes(require_dependency_runtime.buildRuntimeNodesFromPairs(fieldParserPairs, state, exec.path)), exec.dependencyRuntime);
 	const preCompleted = /* @__PURE__ */ new Map();
 	const parentResults = exec?.preCompletedByParser;
 	for (const [field, fieldParser] of fieldParserPairs) {
@@ -2304,6 +2316,7 @@ function preCompleteAndRegisterDependencies(state, fieldParserPairs, registry, e
 * @internal
 */
 async function preCompleteAndRegisterDependenciesAsync(state, fieldParserPairs, registry, exec) {
+	if (exec?.dependencyRuntime != null) require_dependency_runtime.releaseUncollectedSourceValues(expandSourceCollectionNodes(require_dependency_runtime.buildRuntimeNodesFromPairs(fieldParserPairs, state, exec.path)), exec.dependencyRuntime);
 	const preCompleted = /* @__PURE__ */ new Map();
 	const parentResults = exec?.preCompletedByParser;
 	for (const [field, fieldParser] of fieldParserPairs) {
@@ -6618,7 +6631,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			_discriminator: annotatedDiscriminatorState,
 			_branch: require_annotation_state.getWrappedChildState(state, state.branchState, branchParser)
 		};
-		const runtime = require_dependency_runtime.createDependencyRuntimeContext(exec?.dependencyRegistry?.clone());
+		const runtime = state.speculative === true ? require_dependency_runtime.createDependencyRuntimeContext(exec?.dependencyRegistry?.clone()) : require_dependency_runtime.forkRuntimeForCommittedSubtree(exec, committedSourceIds(state, exec?.path));
 		require_dependency_runtime.collectExplicitSourceValues(expandSourceCollectionNodes(require_dependency_runtime.buildRuntimeNodesFromPairs([["_discriminator", discriminator], ["_branch", branchParser]], combinedState, exec?.path)), runtime);
 		require_dependency_runtime.collectSourcesFromState(combinedState, runtime);
 		const resolvedBranchState = require_annotation_state.getWrappedChildState(state, require_dependency_runtime.resolveStateWithRuntime(state.branchState, runtime), branchParser);
@@ -6757,6 +6770,14 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			barrierDependenciesByKey: byKey
 		};
 	})();
+	const committedSourceIds = (state, path) => {
+		const ids = /* @__PURE__ */ new Set();
+		for (const node of expandEffectfulRuntimeNodes(buildConditionalSchedulingNodes(state, path))) {
+			const source = node.parser.dependencyMetadata?.source;
+			if (source != null) ids.add(source.sourceId);
+		}
+		return ids;
+	};
 	const buildConditionalSchedulingNodes = (state, parentPath) => {
 		if (state == null || typeof state !== "object") return [];
 		const conditionalState = state;
@@ -7048,7 +7069,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			_discriminator: annotatedDiscriminatorState,
 			_branch: require_annotation_state.getWrappedChildState(state, state.branchState, branchParser)
 		};
-		const runtime = require_dependency_runtime.createDependencyRuntimeContext(exec?.dependencyRegistry?.clone());
+		const runtime = wasSpeculative ? require_dependency_runtime.createDependencyRuntimeContext(exec?.dependencyRegistry?.clone()) : require_dependency_runtime.forkRuntimeForCommittedSubtree(exec, committedSourceIds(state, exec?.path));
 		await require_dependency_runtime.collectExplicitSourceValuesAsync(expandSourceCollectionNodes(require_dependency_runtime.buildRuntimeNodesFromPairs([["_discriminator", discriminator], ["_branch", branchParser]], combinedState, exec?.path)), runtime);
 		require_dependency_runtime.collectSourcesFromState(combinedState, runtime);
 		const completionExec = {

package/dist/constructs.js

@@ -5,7 +5,7 @@ import { message, optionName, text, values } from "./message.js";
 import { deduplicateDocFragments } from "./doc.js";
 import { dispatchByMode, dispatchIterableByMode } from "./internal/mode-dispatch.js";
 import { createDependencySourceState, dependencyId, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, wrappedDependencySourceMarker } from "./internal/dependency.js";
-import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyRuntimeContext, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, replaceCachedBarrierFailure, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
+import { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyRuntimeContext, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, guaranteedStaticSourceIdsKey, hasInactiveCompletion, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey } from "./dependency-runtime.js";
 import { defineInheritedAnnotationParser, defineParseLanes, getOwnParseLanes, getParserSuggestRuntimeNodes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { annotationViewTargets, getWrappedChildParseState, getWrappedChildState, reconcileObjectChildState, unwrapAnnotationView } from "./annotation-state.js";
 import { allowDuplicateLeadingCommandNamesKey } from "./internal/command-alias.js";
@@ -438,8 +438,12 @@ async function scheduleEffectfulSourceCompletions(nodes, state, runtime, exec, p
 		}
 	}
 	const republish = exec?.republishCachedCompletions === true;
+	const publishedSourceIds = /* @__PURE__ */ new Set();
 	const effectful = await completeEffectfulSourcesAsync(expandedNodes, state, runtime, exec, {
 		...demandNodes != null ? { demandNodes: expandEffectfulRuntimeNodes(demandNodes) } : {},
+		onPublish: (id) => {
+			publishedSourceIds.add(id);
+		},
 		isReusable: (node) => direct.has(node),
 		isCollected: republish ? () => true : (node) => collected.has(node),
 		...republish ? { includeStructural: true } : {}
@@ -452,6 +456,13 @@ async function scheduleEffectfulSourceCompletions(nodes, state, runtime, exec, p
 		const cacheKey = typeof key === "number" ? String(key) : key;
 		preCompleted.set(cacheKey, result);
 	}
+	recordSourceScope(runtime, publishedSourceIds, [...collected].flatMap((node) => {
+		const source = node.parser.dependencyMetadata?.source;
+		return source == null ? [] : [{
+			sourceId: source.sourceId,
+			path: node.path
+		}];
+	}));
 	return void 0;
 }
 function buildIndexedParserPairs(parsers) {
@@ -2251,6 +2262,7 @@ function filterExcludedFieldParsers(pairs, excludedFields) {
 * @internal
 */
 function preCompleteAndRegisterDependencies(state, fieldParserPairs, registry, exec) {
+	if (exec?.dependencyRuntime != null) releaseUncollectedSourceValues(expandSourceCollectionNodes(buildRuntimeNodesFromPairs(fieldParserPairs, state, exec.path)), exec.dependencyRuntime);
 	const preCompleted = /* @__PURE__ */ new Map();
 	const parentResults = exec?.preCompletedByParser;
 	for (const [field, fieldParser] of fieldParserPairs) {
@@ -2304,6 +2316,7 @@ function preCompleteAndRegisterDependencies(state, fieldParserPairs, registry, e
 * @internal
 */
 async function preCompleteAndRegisterDependenciesAsync(state, fieldParserPairs, registry, exec) {
+	if (exec?.dependencyRuntime != null) releaseUncollectedSourceValues(expandSourceCollectionNodes(buildRuntimeNodesFromPairs(fieldParserPairs, state, exec.path)), exec.dependencyRuntime);
 	const preCompleted = /* @__PURE__ */ new Map();
 	const parentResults = exec?.preCompletedByParser;
 	for (const [field, fieldParser] of fieldParserPairs) {
@@ -6618,7 +6631,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			_discriminator: annotatedDiscriminatorState,
 			_branch: getWrappedChildState(state, state.branchState, branchParser)
 		};
-		const runtime = createDependencyRuntimeContext(exec?.dependencyRegistry?.clone());
+		const runtime = state.speculative === true ? createDependencyRuntimeContext(exec?.dependencyRegistry?.clone()) : forkRuntimeForCommittedSubtree(exec, committedSourceIds(state, exec?.path));
 		collectExplicitSourceValues(expandSourceCollectionNodes(buildRuntimeNodesFromPairs([["_discriminator", discriminator], ["_branch", branchParser]], combinedState, exec?.path)), runtime);
 		collectSourcesFromState(combinedState, runtime);
 		const resolvedBranchState = getWrappedChildState(state, resolveStateWithRuntime(state.branchState, runtime), branchParser);
@@ -6757,6 +6770,14 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			barrierDependenciesByKey: byKey
 		};
 	})();
+	const committedSourceIds = (state, path) => {
+		const ids = /* @__PURE__ */ new Set();
+		for (const node of expandEffectfulRuntimeNodes(buildConditionalSchedulingNodes(state, path))) {
+			const source = node.parser.dependencyMetadata?.source;
+			if (source != null) ids.add(source.sourceId);
+		}
+		return ids;
+	};
 	const buildConditionalSchedulingNodes = (state, parentPath) => {
 		if (state == null || typeof state !== "object") return [];
 		const conditionalState = state;
@@ -7048,7 +7069,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			_discriminator: annotatedDiscriminatorState,
 			_branch: getWrappedChildState(state, state.branchState, branchParser)
 		};
-		const runtime = createDependencyRuntimeContext(exec?.dependencyRegistry?.clone());
+		const runtime = wasSpeculative ? createDependencyRuntimeContext(exec?.dependencyRegistry?.clone()) : forkRuntimeForCommittedSubtree(exec, committedSourceIds(state, exec?.path));
 		await collectExplicitSourceValuesAsync(expandSourceCollectionNodes(buildRuntimeNodesFromPairs([["_discriminator", discriminator], ["_branch", branchParser]], combinedState, exec?.path)), runtime);
 		collectSourcesFromState(combinedState, runtime);
 		const completionExec = {

package/dist/dependency-runtime.cjs

@@ -55,6 +55,7 @@ var DependencyRuntimeContextImpl = class {
 		this.registry = new FailedAwareRegistry(registry, this.#failedSources);
 	}
 	registerSource(sourceId, value) {
+		if (this.registry.isPreserved(sourceId)) return;
 		this.registry.set(sourceId, value);
 		this.#sourceFailures.delete(sourceId);
 	}
@@ -74,6 +75,7 @@ var DependencyRuntimeContextImpl = class {
 		this.#replayCache.set(serializeReplayKey(key), result);
 	}
 	markSourceFailed(sourceId) {
+		if (this.registry.isPreserved(sourceId)) return;
 		this.#failedSources.add(sourceId);
 		const lineage = this.#getSourceLineage(sourceId, /* @__PURE__ */ new Set());
 		const failure = {
@@ -104,7 +106,7 @@ var DependencyRuntimeContextImpl = class {
 			participants,
 			diagnosticChain: chain
 		};
-		if (sourceId != null) {
+		if (sourceId != null && !this.registry.isPreserved(sourceId)) {
 			this.#failedSources.add(sourceId);
 			this.#sourceFailures.set(sourceId, failure);
 		}
@@ -159,11 +161,13 @@ var DependencyRuntimeContextImpl = class {
 var FailedAwareRegistry = class FailedAwareRegistry {
 	#inner;
 	#failedSources;
+	#preserved = /* @__PURE__ */ new Map();
 	constructor(inner, failedSources) {
 		this.#inner = inner;
 		this.#failedSources = failedSources;
 	}
 	set(id, value) {
+		if (this.isPreserved(id)) return;
 		this.#inner.set(id, value);
 		this.#failedSources.delete(id);
 	}
@@ -175,12 +179,24 @@ var FailedAwareRegistry = class FailedAwareRegistry {
 		if (this.#failedSources.has(id)) return false;
 		return this.#inner.has(id);
 	}
+	preserve(id, paths) {
+		this.#preserved.set(id, paths);
+	}
+	allowUncollectedOccurrence(id, path) {
+		const paths = this.#preserved.get(id);
+		if (paths != null && !paths.some((covered) => covered.length === path.length && covered.every((segment, index) => segment === path[index]))) this.#preserved.delete(id);
+	}
+	isPreserved(id) {
+		return this.#preserved.has(id);
+	}
 	copyFailedSources(target) {
 		for (const sourceId of this.#failedSources) target.add(sourceId);
 	}
 	rebindFailedSources(target) {
 		this.copyFailedSources(target);
-		return new FailedAwareRegistry(this.#inner, target);
+		const rebound = new FailedAwareRegistry(this.#inner, target);
+		for (const [id, paths] of this.#preserved) rebound.preserve(id, paths);
+		return rebound;
 	}
 	clone() {
 		const failedSources = new Set(this.#failedSources);
@@ -188,6 +204,90 @@ var FailedAwareRegistry = class FailedAwareRegistry {
 		return innerClone instanceof FailedAwareRegistry ? innerClone.rebindFailedSources(failedSources) : new FailedAwareRegistry(innerClone, failedSources);
 	}
 };
+const sourceScopes = /* @__PURE__ */ new WeakMap();
+function recordSourceCollection(nodes, runtime) {
+	const sources = nodes.flatMap((node) => {
+		const source = node.parser.dependencyMetadata?.source;
+		return source == null ? [] : [{
+			sourceId: source.sourceId,
+			path: node.path
+		}];
+	});
+	recordSourceScope(runtime, /* @__PURE__ */ new Set(), sources);
+}
+/**
+* Allows a source occurrence first discovered inside an opaque subtree to
+* publish. Preservation covers the enclosing collector's known occurrences,
+* not every later occurrence of the same dependency ID.
+* @param nodes The source occurrences about to complete or be collected.
+* @param runtime The runtime shared with the enclosing construct.
+* @internal
+* @since 1.3.0
+*/
+function releaseUncollectedSourceValues(nodes, runtime) {
+	if (!(runtime instanceof DependencyRuntimeContextImpl)) return;
+	for (const node of nodes) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source != null) runtime.registry.allowUncollectedOccurrence(source.sourceId, node.path);
+	}
+}
+/**
+* Records effective source values after a collection or scheduling pass.
+* Each pass retains its own coverage, so a sibling sharing the runtime cannot
+* replace its parent's snapshot. A newer pass only supersedes scopes for
+* the source paths it actually collects.
+* @param runtime The owning pass's runtime.
+* @param sourceIds Additional IDs published by the pass's scheduling barriers.
+* @param collectedSources The sources included in the owning scope's collection.
+* @internal
+* @since 1.3.0
+*/
+function recordSourceScope(runtime, sourceIds, collectedSources) {
+	if (collectedSources.length === 0) return;
+	const values = /* @__PURE__ */ new Map();
+	const ids = new Set([...sourceIds, ...collectedSources.map((source) => source.sourceId)]);
+	for (const id of ids) if (runtime.hasSource(id)) values.set(id, {
+		success: true,
+		value: runtime.getSource(id)
+	});
+	else if (runtime.isSourceFailed(id)) values.set(id, { success: false });
+	let scopes = sourceScopes.get(runtime);
+	if (scopes == null) {
+		scopes = [];
+		sourceScopes.set(runtime, scopes);
+	}
+	scopes.push({
+		values,
+		collectedSources
+	});
+}
+/**
+* Forks a CLI-committed subtree without letting its repeated collection
+* replace the enclosing scope's final source occurrences. Unknown sources
+* remain writable, including when no enclosing construct collected them.
+* Ordinary registry clones drop this protection so completion-selected
+* branches can establish their own scope.
+* @param exec The enclosing execution context.
+* @param sourceIds The sources exposed by the committed subtree.
+* @returns A runtime preserving the enclosing values for those sources.
+* @internal
+* @since 1.3.0
+*/
+function forkRuntimeForCommittedSubtree(exec, sourceIds) {
+	const runtime = new DependencyRuntimeContextImpl(exec?.dependencyRegistry?.clone() ?? new SimpleRegistry());
+	const scopes = exec?.dependencyRuntime == null ? void 0 : sourceScopes.get(exec.dependencyRuntime);
+	for (const id of sourceIds) {
+		const scope = scopes?.findLast((candidate) => candidate.collectedSources.some((source) => source.sourceId === id && exec?.path.every((segment, index) => source.path[index] === segment)));
+		if (scope == null) continue;
+		const publication = scope.values.get(id);
+		if (publication?.success) runtime.registerSource(id, publication.value);
+		else if (publication != null) runtime.markSourceFailed(id);
+		else if (runtime.hasSource(id)) {} else if (!runtime.isSourceFailed(id)) continue;
+		const paths = scope.collectedSources.filter((source) => source.sourceId === id).map((source) => source.path);
+		runtime.registry.preserve(id, paths);
+	}
+	return runtime;
+}
 function resolveRequest(ctx, request) {
 	const values = [];
 	const usedDefaults = [];
@@ -344,6 +444,7 @@ function createReplayKey(path, rawInput, dependencyValues, replayParse) {
 * @since 1.0.0
 */
 function collectExplicitSourceValues(nodes, runtime) {
+	releaseUncollectedSourceValues(nodes, runtime);
 	registerRuntimeSourceMetadata(nodes, runtime);
 	for (const node of nodes) {
 		const meta = node.parser.dependencyMetadata;
@@ -355,6 +456,7 @@ function collectExplicitSourceValues(nodes, runtime) {
 		registerExplicitSourceValue(meta.source.sourceId, result, runtime);
 	}
 	resolveDerivedSourceValues(nodes, runtime);
+	recordSourceCollection(nodes, runtime);
 }
 function registerExplicitSourceValue(sourceId, result, runtime) {
 	if (result == null) return;
@@ -376,6 +478,7 @@ function isPromiseLike(value) {
 * @since 1.0.0
 */
 async function collectExplicitSourceValuesAsync(nodes, runtime) {
+	releaseUncollectedSourceValues(nodes, runtime);
 	registerRuntimeSourceMetadata(nodes, runtime);
 	for (const node of nodes) {
 		const meta = node.parser.dependencyMetadata;
@@ -386,6 +489,7 @@ async function collectExplicitSourceValuesAsync(nodes, runtime) {
 		registerExplicitSourceValue(meta.source.sourceId, result, runtime);
 	}
 	await resolveDerivedSourceValuesAsync(nodes, runtime);
+	recordSourceCollection(nodes, runtime);
 }
 /**
 * Orders runtime nodes so every in-scope provider precedes a derived source
@@ -1860,11 +1964,14 @@ exports.exclusiveSourceScopeKey = exclusiveSourceScopeKey;
 exports.extractRawInputFromState = extractRawInputFromState;
 exports.fillMissingSourceDefaults = fillMissingSourceDefaults;
 exports.fillMissingSourceDefaultsAsync = fillMissingSourceDefaultsAsync;
+exports.forkRuntimeForCommittedSubtree = forkRuntimeForCommittedSubtree;
 exports.guaranteedStaticSourceIdsKey = guaranteedStaticSourceIdsKey;
 exports.hasInactiveCompletion = hasInactiveCompletion;
 exports.includeSourceFailureChain = includeSourceFailureChain;
 exports.orderDependencyNodes = orderDependencyNodes;
 exports.recordDerivedRawInput = recordDerivedRawInput;
+exports.recordSourceScope = recordSourceScope;
+exports.releaseUncollectedSourceValues = releaseUncollectedSourceValues;
 exports.replaceCachedBarrierFailure = replaceCachedBarrierFailure;
 exports.replayDerivedParser = replayDerivedParser;
 exports.replayDerivedParserAsync = replayDerivedParserAsync;

package/dist/dependency-runtime.d.cts

@@ -393,6 +393,45 @@ interface DependencyRuntimeContext {
   /** Resolve dependencies for suggestions (same semantics as resolve). */
   getSuggestionDependencies(request: DependencyRequest): DependencyResolution;
 }
+interface CollectedSource {
+  readonly sourceId: symbol;
+  readonly path: readonly PropertyKey[];
+}
+/**
+ * Allows a source occurrence first discovered inside an opaque subtree to
+ * publish. Preservation covers the enclosing collector's known occurrences,
+ * not every later occurrence of the same dependency ID.
+ * @param nodes The source occurrences about to complete or be collected.
+ * @param runtime The runtime shared with the enclosing construct.
+ * @internal
+ * @since 1.3.0
+ */
+declare function releaseUncollectedSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): void;
+/**
+ * Records effective source values after a collection or scheduling pass.
+ * Each pass retains its own coverage, so a sibling sharing the runtime cannot
+ * replace its parent's snapshot. A newer pass only supersedes scopes for
+ * the source paths it actually collects.
+ * @param runtime The owning pass's runtime.
+ * @param sourceIds Additional IDs published by the pass's scheduling barriers.
+ * @param collectedSources The sources included in the owning scope's collection.
+ * @internal
+ * @since 1.3.0
+ */
+declare function recordSourceScope(runtime: DependencyRuntimeContext, sourceIds: ReadonlySet<symbol>, collectedSources: readonly CollectedSource[]): void;
+/**
+ * Forks a CLI-committed subtree without letting its repeated collection
+ * replace the enclosing scope's final source occurrences. Unknown sources
+ * remain writable, including when no enclosing construct collected them.
+ * Ordinary registry clones drop this protection so completion-selected
+ * branches can establish their own scope.
+ * @param exec The enclosing execution context.
+ * @param sourceIds The sources exposed by the committed subtree.
+ * @returns A runtime preserving the enclosing values for those sources.
+ * @internal
+ * @since 1.3.0
+ */
+declare function forkRuntimeForCommittedSubtree(exec: ExecutionContext | undefined, sourceIds: ReadonlySet<symbol>): DependencyRuntimeContext;
 /**
  * Creates a new {@link DependencyRuntimeContext}.
  *
@@ -923,4 +962,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, 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, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, 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, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.d.ts

@@ -393,6 +393,45 @@ interface DependencyRuntimeContext {
   /** Resolve dependencies for suggestions (same semantics as resolve). */
   getSuggestionDependencies(request: DependencyRequest): DependencyResolution;
 }
+interface CollectedSource {
+  readonly sourceId: symbol;
+  readonly path: readonly PropertyKey[];
+}
+/**
+ * Allows a source occurrence first discovered inside an opaque subtree to
+ * publish. Preservation covers the enclosing collector's known occurrences,
+ * not every later occurrence of the same dependency ID.
+ * @param nodes The source occurrences about to complete or be collected.
+ * @param runtime The runtime shared with the enclosing construct.
+ * @internal
+ * @since 1.3.0
+ */
+declare function releaseUncollectedSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): void;
+/**
+ * Records effective source values after a collection or scheduling pass.
+ * Each pass retains its own coverage, so a sibling sharing the runtime cannot
+ * replace its parent's snapshot. A newer pass only supersedes scopes for
+ * the source paths it actually collects.
+ * @param runtime The owning pass's runtime.
+ * @param sourceIds Additional IDs published by the pass's scheduling barriers.
+ * @param collectedSources The sources included in the owning scope's collection.
+ * @internal
+ * @since 1.3.0
+ */
+declare function recordSourceScope(runtime: DependencyRuntimeContext, sourceIds: ReadonlySet<symbol>, collectedSources: readonly CollectedSource[]): void;
+/**
+ * Forks a CLI-committed subtree without letting its repeated collection
+ * replace the enclosing scope's final source occurrences. Unknown sources
+ * remain writable, including when no enclosing construct collected them.
+ * Ordinary registry clones drop this protection so completion-selected
+ * branches can establish their own scope.
+ * @param exec The enclosing execution context.
+ * @param sourceIds The sources exposed by the committed subtree.
+ * @returns A runtime preserving the enclosing values for those sources.
+ * @internal
+ * @since 1.3.0
+ */
+declare function forkRuntimeForCommittedSubtree(exec: ExecutionContext | undefined, sourceIds: ReadonlySet<symbol>): DependencyRuntimeContext;
 /**
  * Creates a new {@link DependencyRuntimeContext}.
  *
@@ -923,4 +962,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, 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, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { BarrierCompletionDemandEdge, BarrierCompletionDependencies, BarrierResolution, 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, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.js

@@ -55,6 +55,7 @@ var DependencyRuntimeContextImpl = class {
 		this.registry = new FailedAwareRegistry(registry, this.#failedSources);
 	}
 	registerSource(sourceId, value) {
+		if (this.registry.isPreserved(sourceId)) return;
 		this.registry.set(sourceId, value);
 		this.#sourceFailures.delete(sourceId);
 	}
@@ -74,6 +75,7 @@ var DependencyRuntimeContextImpl = class {
 		this.#replayCache.set(serializeReplayKey(key), result);
 	}
 	markSourceFailed(sourceId) {
+		if (this.registry.isPreserved(sourceId)) return;
 		this.#failedSources.add(sourceId);
 		const lineage = this.#getSourceLineage(sourceId, /* @__PURE__ */ new Set());
 		const failure = {
@@ -104,7 +106,7 @@ var DependencyRuntimeContextImpl = class {
 			participants,
 			diagnosticChain: chain
 		};
-		if (sourceId != null) {
+		if (sourceId != null && !this.registry.isPreserved(sourceId)) {
 			this.#failedSources.add(sourceId);
 			this.#sourceFailures.set(sourceId, failure);
 		}
@@ -159,11 +161,13 @@ var DependencyRuntimeContextImpl = class {
 var FailedAwareRegistry = class FailedAwareRegistry {
 	#inner;
 	#failedSources;
+	#preserved = /* @__PURE__ */ new Map();
 	constructor(inner, failedSources) {
 		this.#inner = inner;
 		this.#failedSources = failedSources;
 	}
 	set(id, value) {
+		if (this.isPreserved(id)) return;
 		this.#inner.set(id, value);
 		this.#failedSources.delete(id);
 	}
@@ -175,12 +179,24 @@ var FailedAwareRegistry = class FailedAwareRegistry {
 		if (this.#failedSources.has(id)) return false;
 		return this.#inner.has(id);
 	}
+	preserve(id, paths) {
+		this.#preserved.set(id, paths);
+	}
+	allowUncollectedOccurrence(id, path) {
+		const paths = this.#preserved.get(id);
+		if (paths != null && !paths.some((covered) => covered.length === path.length && covered.every((segment, index) => segment === path[index]))) this.#preserved.delete(id);
+	}
+	isPreserved(id) {
+		return this.#preserved.has(id);
+	}
 	copyFailedSources(target) {
 		for (const sourceId of this.#failedSources) target.add(sourceId);
 	}
 	rebindFailedSources(target) {
 		this.copyFailedSources(target);
-		return new FailedAwareRegistry(this.#inner, target);
+		const rebound = new FailedAwareRegistry(this.#inner, target);
+		for (const [id, paths] of this.#preserved) rebound.preserve(id, paths);
+		return rebound;
 	}
 	clone() {
 		const failedSources = new Set(this.#failedSources);
@@ -188,6 +204,90 @@ var FailedAwareRegistry = class FailedAwareRegistry {
 		return innerClone instanceof FailedAwareRegistry ? innerClone.rebindFailedSources(failedSources) : new FailedAwareRegistry(innerClone, failedSources);
 	}
 };
+const sourceScopes = /* @__PURE__ */ new WeakMap();
+function recordSourceCollection(nodes, runtime) {
+	const sources = nodes.flatMap((node) => {
+		const source = node.parser.dependencyMetadata?.source;
+		return source == null ? [] : [{
+			sourceId: source.sourceId,
+			path: node.path
+		}];
+	});
+	recordSourceScope(runtime, /* @__PURE__ */ new Set(), sources);
+}
+/**
+* Allows a source occurrence first discovered inside an opaque subtree to
+* publish. Preservation covers the enclosing collector's known occurrences,
+* not every later occurrence of the same dependency ID.
+* @param nodes The source occurrences about to complete or be collected.
+* @param runtime The runtime shared with the enclosing construct.
+* @internal
+* @since 1.3.0
+*/
+function releaseUncollectedSourceValues(nodes, runtime) {
+	if (!(runtime instanceof DependencyRuntimeContextImpl)) return;
+	for (const node of nodes) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source != null) runtime.registry.allowUncollectedOccurrence(source.sourceId, node.path);
+	}
+}
+/**
+* Records effective source values after a collection or scheduling pass.
+* Each pass retains its own coverage, so a sibling sharing the runtime cannot
+* replace its parent's snapshot. A newer pass only supersedes scopes for
+* the source paths it actually collects.
+* @param runtime The owning pass's runtime.
+* @param sourceIds Additional IDs published by the pass's scheduling barriers.
+* @param collectedSources The sources included in the owning scope's collection.
+* @internal
+* @since 1.3.0
+*/
+function recordSourceScope(runtime, sourceIds, collectedSources) {
+	if (collectedSources.length === 0) return;
+	const values = /* @__PURE__ */ new Map();
+	const ids = new Set([...sourceIds, ...collectedSources.map((source) => source.sourceId)]);
+	for (const id of ids) if (runtime.hasSource(id)) values.set(id, {
+		success: true,
+		value: runtime.getSource(id)
+	});
+	else if (runtime.isSourceFailed(id)) values.set(id, { success: false });
+	let scopes = sourceScopes.get(runtime);
+	if (scopes == null) {
+		scopes = [];
+		sourceScopes.set(runtime, scopes);
+	}
+	scopes.push({
+		values,
+		collectedSources
+	});
+}
+/**
+* Forks a CLI-committed subtree without letting its repeated collection
+* replace the enclosing scope's final source occurrences. Unknown sources
+* remain writable, including when no enclosing construct collected them.
+* Ordinary registry clones drop this protection so completion-selected
+* branches can establish their own scope.
+* @param exec The enclosing execution context.
+* @param sourceIds The sources exposed by the committed subtree.
+* @returns A runtime preserving the enclosing values for those sources.
+* @internal
+* @since 1.3.0
+*/
+function forkRuntimeForCommittedSubtree(exec, sourceIds) {
+	const runtime = new DependencyRuntimeContextImpl(exec?.dependencyRegistry?.clone() ?? new SimpleRegistry());
+	const scopes = exec?.dependencyRuntime == null ? void 0 : sourceScopes.get(exec.dependencyRuntime);
+	for (const id of sourceIds) {
+		const scope = scopes?.findLast((candidate) => candidate.collectedSources.some((source) => source.sourceId === id && exec?.path.every((segment, index) => source.path[index] === segment)));
+		if (scope == null) continue;
+		const publication = scope.values.get(id);
+		if (publication?.success) runtime.registerSource(id, publication.value);
+		else if (publication != null) runtime.markSourceFailed(id);
+		else if (runtime.hasSource(id)) {} else if (!runtime.isSourceFailed(id)) continue;
+		const paths = scope.collectedSources.filter((source) => source.sourceId === id).map((source) => source.path);
+		runtime.registry.preserve(id, paths);
+	}
+	return runtime;
+}
 function resolveRequest(ctx, request) {
 	const values = [];
 	const usedDefaults = [];
@@ -344,6 +444,7 @@ function createReplayKey(path, rawInput, dependencyValues, replayParse) {
 * @since 1.0.0
 */
 function collectExplicitSourceValues(nodes, runtime) {
+	releaseUncollectedSourceValues(nodes, runtime);
 	registerRuntimeSourceMetadata(nodes, runtime);
 	for (const node of nodes) {
 		const meta = node.parser.dependencyMetadata;
@@ -355,6 +456,7 @@ function collectExplicitSourceValues(nodes, runtime) {
 		registerExplicitSourceValue(meta.source.sourceId, result, runtime);
 	}
 	resolveDerivedSourceValues(nodes, runtime);
+	recordSourceCollection(nodes, runtime);
 }
 function registerExplicitSourceValue(sourceId, result, runtime) {
 	if (result == null) return;
@@ -376,6 +478,7 @@ function isPromiseLike(value) {
 * @since 1.0.0
 */
 async function collectExplicitSourceValuesAsync(nodes, runtime) {
+	releaseUncollectedSourceValues(nodes, runtime);
 	registerRuntimeSourceMetadata(nodes, runtime);
 	for (const node of nodes) {
 		const meta = node.parser.dependencyMetadata;
@@ -386,6 +489,7 @@ async function collectExplicitSourceValuesAsync(nodes, runtime) {
 		registerExplicitSourceValue(meta.source.sourceId, result, runtime);
 	}
 	await resolveDerivedSourceValuesAsync(nodes, runtime);
+	recordSourceCollection(nodes, runtime);
 }
 /**
 * Orders runtime nodes so every in-scope provider precedes a derived source
@@ -1843,4 +1947,4 @@ function getDefaultDependencySnapshotInner(state, visited) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, exclusiveSourceScopeKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, forkRuntimeForCommittedSubtree, guaranteedStaticSourceIdsKey, hasInactiveCompletion, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, recordSourceScope, releaseUncollectedSourceValues, replaceCachedBarrierFailure, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2576",
+  "version": "1.3.0-dev.2581",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2576+87e23289",
+    "@optique/env": "1.3.0-dev.2581+50dd484c",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",