@optique/core 1.3.0-dev.2430 → 1.3.0-dev.2433

package/dist/constructs.cjs

@@ -169,21 +169,47 @@ function expandSourceCollectionNodes(nodes) {
 }
 let conditionalInstanceCounter = 0;
 /**
+* Whether a source occurrence publishes a value even when its state
+* holds no parsed one: its composed effectful completion always fires
+* (`completesWhenMissing`), or it exposes a publishable missing-value
+* default.
+*/
+function isGuaranteedSourceProvider(source) {
+	return source.completeSource != null && source.completesWhenMissing === true || source.getMissingSourceValue != null && source.preservesSourceValue !== false;
+}
+/**
 * Statically collects the dependency source IDs reachable through a
-* parser's composed metadata and flattened field pairs.  Used as the
-* `providesSourceIds` estimate for a conditional()'s branches: an
-* undercount only delays an effectful completion from the seed pass to
-* the final pass of a `runWith()` run.
+* parser's composed metadata and flattened field pairs, classifying each
+* as merely possible or guaranteed.
+*
+* `exclusive` marks descent through a mutually exclusive edge (an `or()`
+* alternative, a `conditional()` branch, an unmatched `command()`); an
+* occurrence reached that way never counts as guaranteed.  `suppressId`
+* carries the source ID of an enclosing wrapper whose composed metadata
+* already decided that chain's classification, so the raw inner
+* occurrence (e.g., the bare prompt inside `optional(prompt(...))`) does
+* not overrule the wrapper.
 */
-function collectStaticSourceIds(parser, out, seen) {
-	if (seen.has(parser)) return;
-	seen.add(parser);
+function collectStaticProvides(parser, out, exclusive, suppressId, seen) {
+	const visitBit = 1 << ((exclusive ? 1 : 0) | (suppressId != null ? 2 : 0));
+	const visited = seen.get(parser) ?? 0;
+	if ((visited & visitBit) !== 0) return;
+	seen.set(parser, visited | visitBit);
 	const source = parser.dependencyMetadata?.source;
-	if (source != null) out.add(source.sourceId);
+	let childSuppressId = suppressId;
+	if (source != null) {
+		out.may.add(source.sourceId);
+		if (!exclusive && source.sourceId !== suppressId && isGuaranteedSourceProvider(source)) out.guaranteed.add(source.sourceId);
+		childSuppressId = source.sourceId;
+	}
+	const routeGuaranteed = parser[require_dependency_runtime.guaranteedStaticSourceIdsKey];
+	if (routeGuaranteed != null && !exclusive) for (const id of routeGuaranteed) out.guaranteed.add(id);
 	const pairs = parser[fieldParsersKey];
-	if (pairs != null) for (const [, child] of pairs) collectStaticSourceIds(child, out, seen);
+	if (pairs != null) for (const [, child] of pairs) collectStaticProvides(child, out, exclusive, childSuppressId, seen);
 	const scope = parser[require_dependency_runtime.staticSourceScopeKey];
-	if (scope != null) for (const child of scope) collectStaticSourceIds(child, out, seen);
+	if (scope != null) for (const child of scope) collectStaticProvides(child, out, exclusive, childSuppressId, seen);
+	const exclusiveScope = parser[require_dependency_runtime.exclusiveSourceScopeKey];
+	if (exclusiveScope != null) for (const child of exclusiveScope) collectStaticProvides(child, out, true, childSuppressId, seen);
 }
 /**
 * Statically collects the completion dependencies reachable through a
@@ -211,16 +237,55 @@ function collectStaticCompletionDependencies(parser, orderingDependencyIds, dema
 	if (pairs != null) for (const [, child] of pairs) collectStaticCompletionDependencies(child, orderingDependencyIds, demandEdges, seen);
 	const scope = parser[require_dependency_runtime.staticSourceScopeKey];
 	if (scope != null) for (const child of scope) collectStaticCompletionDependencies(child, orderingDependencyIds, demandEdges, seen);
+	const exclusiveScope = parser[require_dependency_runtime.exclusiveSourceScopeKey];
+	if (exclusiveScope != null) for (const child of exclusiveScope) collectStaticCompletionDependencies(child, orderingDependencyIds, demandEdges, seen);
+}
+/**
+* Collects the source IDs a set of expanded branch nodes will actively
+* publish: a guaranteed occurrence (an unconditional effectful
+* completion or a publishable default), an occurrence whose state
+* already extracts a value, or a nested barrier's every-route
+* guarantees.  Synchronous extraction only;
+* {@link computeActiveBarrierDependencies} additionally awaits
+* promise-shaped extractions, so a bound value that validates
+* asynchronously still counts as active.
+*/
+function collectActiveProvidesSync(nodes) {
+	const active = /* @__PURE__ */ new Set();
+	for (const node of nodes) {
+		const source = node.parser.dependencyMetadata?.source;
+		if (source != null && !active.has(source.sourceId)) {
+			if (isGuaranteedSourceProvider(source)) active.add(source.sourceId);
+			else if (source.extractSourceValue != null) {
+				let extracted;
+				try {
+					extracted = source.extractSourceValue(node.state);
+				} catch {
+					extracted = void 0;
+				}
+				if (extracted != null && isPromiseLike(extracted)) Promise.resolve(extracted).catch(() => {});
+				else if (extracted?.success === true && extracted.value !== void 0) active.add(source.sourceId);
+			}
+		}
+		for (const id of node.guaranteedProvidesSourceIds ?? []) active.add(id);
+	}
+	return active;
+}
+function isPromiseLike(value) {
+	return typeof value?.then === "function";
 }
 /**
 * Recomputes a speculative barrier's completion dependencies from the
 * guessed branch's expanded runtime nodes, so an occurrence already
 * satisfied by the command line or a binding contributes neither
 * ordering edges nor demand, mirroring the flat inactive-completion
-* rule.  Nested barriers contribute their own aggregates, which remain
-* static estimates.
+* rule.  Only *active* provides are subtracted from the ordering
+* union—a merely possible provider (an absent `optional()`, an
+* unselected nested alternative) must not hide a matching provider
+* declared after the conditional (issue #924).  Nested barriers
+* contribute their own aggregates, which remain static estimates.
 */
-function computeBarrierDependenciesFromNodes(nodes, provides) {
+function computeBarrierDependenciesFromNodes(nodes) {
 	const ordering = /* @__PURE__ */ new Set();
 	const demandEdges = [];
 	for (const node of nodes) {
@@ -240,13 +305,52 @@ function computeBarrierDependenciesFromNodes(nodes, provides) {
 			demandEdges.push(...nested.demandEdges);
 		}
 	}
-	const orderingDependencyIds = [...ordering].filter((id) => !provides.has(id));
+	const active = collectActiveProvidesSync(nodes);
+	const orderingDependencyIds = [...ordering].filter((id) => !active.has(id));
 	if (orderingDependencyIds.length < 1 && demandEdges.length < 1) return void 0;
 	return {
 		orderingDependencyIds,
 		demandEdges
 	};
 }
+/**
+* Computes a resolved barrier's concrete dependencies from the selected
+* branch's expanded runtime nodes: the completion dependencies its
+* active consumers read, minus the sources the branch actively
+* provides, and the active provides themselves.  Unlike the
+* synchronous estimate, promise-shaped state extractions are awaited,
+* so an asynchronously validating bound value counts as active.
+*/
+async function computeActiveBarrierDependencies(nodes) {
+	const active = /* @__PURE__ */ new Set();
+	const ordering = /* @__PURE__ */ new Set();
+	for (const node of nodes) {
+		const metadata = node.parser.dependencyMetadata;
+		const source = metadata?.source;
+		const completion = metadata?.completion;
+		const guaranteed = source != null && isGuaranteedSourceProvider(source);
+		let extracted;
+		if (source?.extractSourceValue != null && (completion != null || !guaranteed && !active.has(source.sourceId))) try {
+			extracted = await source.extractSourceValue(node.state);
+		} catch {
+			extracted = void 0;
+		}
+		if (source != null) {
+			if (guaranteed || extracted?.success === true && extracted.value !== void 0) active.add(source.sourceId);
+		}
+		for (const id of node.guaranteedProvidesSourceIds ?? []) active.add(id);
+		if (completion != null) {
+			const inactive = source?.extractSourceValue != null ? extracted?.success === true : require_dependency_runtime.hasInactiveCompletion(node);
+			if (!inactive) for (const id of completion.dependencyIds) ordering.add(id);
+		}
+		const nested = node.barrierCompletionDependencies;
+		if (nested != null) for (const id of nested.orderingDependencyIds) ordering.add(id);
+	}
+	return {
+		orderingDependencyIds: [...ordering].filter((id) => !active.has(id)),
+		activeProvidesSourceIds: active
+	};
+}
 function isDeferredCompletionResult(result) {
 	return typeof result === "object" && result !== null && "success" in result && result.success === true && "deferred" in result && result.deferred === true;
 }
@@ -1064,7 +1168,7 @@ function defineExclusiveSchedulingNodes(exclusiveParser, parsers) {
 		configurable: true,
 		enumerable: false
 	});
-	Object.defineProperty(exclusiveParser, require_dependency_runtime.staticSourceScopeKey, {
+	Object.defineProperty(exclusiveParser, require_dependency_runtime.exclusiveSourceScopeKey, {
 		value: parsers,
 		configurable: true,
 		enumerable: false
@@ -1095,6 +1199,7 @@ function composeExclusiveDependencyMetadata(parsers) {
 	return { source: {
 		...sharedSource,
 		getMissingSourceValue: void 0,
+		completesWhenMissing: false,
 		preservesSourceValue: everyBranchPreserves,
 		extractSourceValue(state) {
 			if (!Array.isArray(state) || state.length !== 2 || typeof state[0] !== "number") return void 0;
@@ -6505,21 +6610,25 @@ function conditional(discriminator, branches, defaultBranch, options) {
 	};
 	const preparedKeyPrefix = `c${++conditionalInstanceCounter}|`;
 	const preparedKeyFor = (parentPath) => preparedKeyPrefix + require_dependency_runtime.serializeSchedulingPath(parentPath ?? []);
-	const { branchProvidedSourceIds, mergedBarrierDependencies, barrierDependenciesByKey } = (() => {
+	const { branchProvidedSourceIds, branchGuaranteedIntersection, mergedBarrierDependencies, barrierDependenciesByKey } = (() => {
 		const provided = /* @__PURE__ */ new Set();
 		const byParser = /* @__PURE__ */ new Map();
 		const computeBranch = (branch) => {
 			const memoized = byParser.get(branch);
 			if (memoized != null) return memoized;
-			const provides = /* @__PURE__ */ new Set();
-			collectStaticSourceIds(branch, provides, /* @__PURE__ */ new Set());
-			for (const id of provides) provided.add(id);
+			const provides = {
+				may: /* @__PURE__ */ new Set(),
+				guaranteed: /* @__PURE__ */ new Set()
+			};
+			collectStaticProvides(branch, provides, false, void 0, /* @__PURE__ */ new Map());
+			for (const id of provides.may) provided.add(id);
 			const ordering = /* @__PURE__ */ new Set();
 			const demandEdges = [];
 			collectStaticCompletionDependencies(branch, ordering, demandEdges, /* @__PURE__ */ new Set());
-			const orderingDependencyIds = [...ordering].filter((id) => !provides.has(id));
+			const orderingDependencyIds = [...ordering].filter((id) => !provides.guaranteed.has(id));
 			const estimate = {
-				provides,
+				mayProvides: provides.may,
+				guaranteedProvides: provides.guaranteed,
 				...orderingDependencyIds.length < 1 && demandEdges.length < 1 ? {} : { dependencies: {
 					orderingDependencyIds,
 					demandEdges
@@ -6528,12 +6637,17 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			byParser.set(branch, estimate);
 			return estimate;
 		};
+		const routes = [];
 		const byKey = /* @__PURE__ */ new Map();
 		for (const key of Object.keys(branches)) {
 			const estimate = computeBranch(branches[key]);
-			if (estimate.dependencies != null) byKey.set(key, estimate);
+			routes.push(estimate);
+			byKey.set(key, estimate);
 		}
-		if (defaultBranch != null) computeBranch(defaultBranch);
+		if (defaultBranch != null) routes.push(computeBranch(defaultBranch));
+		let intersection;
+		for (const route of routes) if (intersection == null) intersection = new Set(route.guaranteedProvides);
+		else for (const id of intersection) if (!route.guaranteedProvides.has(id)) intersection.delete(id);
 		const orderingUnion = /* @__PURE__ */ new Set();
 		const mergedEdges = [];
 		for (const estimate of new Set(byParser.values())) {
@@ -6547,6 +6661,7 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		};
 		return {
 			branchProvidedSourceIds: provided,
+			branchGuaranteedIntersection: intersection ?? /* @__PURE__ */ new Set(),
 			mergedBarrierDependencies: merged,
 			barrierDependenciesByKey: byKey
 		};
@@ -6595,16 +6710,20 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			if (selected?.kind !== "branch" || innerCompleteSource == null) return nodes;
 			teeDiscriminatorNode();
 			const speculativeKey = selected.key;
-			const speculativeBarrierDependencies = (() => {
-				const estimate = barrierDependenciesByKey.get(speculativeKey);
-				if (estimate?.dependencies == null) return void 0;
+			const expandGuessedBranchNodes = () => {
 				const branchParser = branches[speculativeKey];
-				if (branchParser == null) return estimate.dependencies;
-				return computeBarrierDependenciesFromNodes(expandEffectfulRuntimeNodes([{
+				if (branchParser == null) return [];
+				return expandEffectfulRuntimeNodes([{
 					path: [...parentPath ?? [], "_branch"],
 					parser: branchParser,
 					state: require_annotation_state.getWrappedChildState(conditionalState, conditionalState.branchState, branchParser)
-				}]), estimate.provides);
+				}]);
+			};
+			const speculativeEstimate = barrierDependenciesByKey.get(speculativeKey);
+			const speculativeBarrierDependencies = (() => {
+				if (speculativeEstimate?.dependencies == null) return void 0;
+				if (branches[speculativeKey] == null) return speculativeEstimate.dependencies;
+				return computeBarrierDependenciesFromNodes(expandGuessedBranchNodes());
 			})();
 			nodes.push({
 				path: [...parentPath ?? [], "_branch"],
@@ -6612,20 +6731,27 @@ function conditional(discriminator, branches, defaultBranch, options) {
 				state: conditionalState,
 				...discriminatorSource != null ? { requiresSourceId: discriminatorSource.sourceId } : {},
 				providesSourceIds: branchProvidedSourceIds,
+				...speculativeEstimate != null && speculativeEstimate.guaranteedProvides.size > 0 ? { guaranteedProvidesSourceIds: speculativeEstimate.guaranteedProvides } : {},
 				...speculativeBarrierDependencies != null ? { barrierCompletionDependencies: speculativeBarrierDependencies } : {},
+				resolveBarrier: async (ctx) => {
+					const session = ctx.exec?.effectfulCompletionSession;
+					if (session == null) return void 0;
+					const result = cell.result ?? session.completedByPath.get(discriminatorPathKey);
+					if (result == null || isDeferredCompletionResult(result) || result.success !== true) return void 0;
+					if (String(result.value) !== speculativeKey || branches[speculativeKey] == null) return {
+						orderingDependencyIds: [],
+						activeProvidesSourceIds: /* @__PURE__ */ new Set()
+					};
+					return await computeActiveBarrierDependencies(expandGuessedBranchNodes());
+				},
 				prepare: async (ctx) => {
 					const session = ctx.exec?.effectfulCompletionSession;
 					if (session == null) return void 0;
 					const result = cell.result ?? session.completedByPath.get(discriminatorPathKey);
 					if (result == null || isDeferredCompletionResult(result) || result.success !== true) return void 0;
 					if (String(result.value) !== speculativeKey) return void 0;
-					const branchParser = branches[speculativeKey];
-					if (branchParser == null) return void 0;
-					return await ctx.schedule(expandEffectfulRuntimeNodes([{
-						path: [...parentPath ?? [], "_branch"],
-						parser: branchParser,
-						state: require_annotation_state.getWrappedChildState(conditionalState, conditionalState.branchState, branchParser)
-					}]));
+					if (branches[speculativeKey] == null) return void 0;
+					return await ctx.schedule(expandGuessedBranchNodes());
 				}
 			});
 			return nodes;
@@ -6633,61 +6759,79 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		if (selected !== void 0) return nodes;
 		if (discriminatorSource == null && typeof discriminator.shouldDeferCompletion === "function") return nodes;
 		teeDiscriminatorNode();
+		const resolvePreparedSelection = async (ctx) => {
+			const session = ctx.exec?.effectfulCompletionSession;
+			if (session == null) return void 0;
+			const key = preparedKeyFor(parentPath);
+			let prepared = session.preparedByPath.get(key);
+			if (prepared == null) {
+				let discriminatorResult = cell.result ?? session.completedByPath.get(discriminatorPathKey);
+				if (discriminatorResult == null && innerCompleteSource == null) {
+					const discriminatorExec = ctx.exec == null ? void 0 : {
+						...ctx.exec,
+						path: [...parentPath ?? [], "_discriminator"]
+					};
+					discriminatorResult = unwrapCompleteResult(await discriminator.complete(annotatedDiscriminatorState, discriminatorExec));
+				}
+				if (discriminatorResult == null || isDeferredCompletionResult(discriminatorResult)) return void 0;
+				const namedBranch = discriminatorResult.success ? branches[String(discriminatorResult.value)] : void 0;
+				const branchParser = namedBranch ?? defaultBranch;
+				let branchState;
+				if (branchParser != null) {
+					const branchExec = ctx.exec == null ? void 0 : {
+						...ctx.exec,
+						path: [...parentPath ?? [], "_branch"]
+					};
+					const annotatedInitial = require_annotation_state.getWrappedChildState(conditionalState, branchParser.initialState, branchParser);
+					const replayResult = await branchParser.parse({
+						buffer: [],
+						optionsTerminated: false,
+						usage: [],
+						exec: branchExec,
+						dependencyRegistry: ctx.exec?.dependencyRegistry,
+						state: annotatedInitial
+					});
+					branchState = replayResult.success ? replayResult.next.state : annotatedInitial;
+				}
+				prepared = {
+					discriminatorResult,
+					branchParser,
+					branchKey: namedBranch != null ? String(discriminatorResult.value) : void 0,
+					branchState
+				};
+				session.preparedByPath.set(key, prepared);
+			}
+			return prepared;
+		};
+		const expandPreparedBranchNodes = (prepared) => {
+			if (prepared.branchParser == null) return [];
+			return expandEffectfulRuntimeNodes([{
+				path: [...parentPath ?? [], "_branch"],
+				parser: prepared.branchParser,
+				state: require_annotation_state.getWrappedChildState(conditionalState, prepared.branchState, prepared.branchParser)
+			}]);
+		};
 		nodes.push({
 			path: [...parentPath ?? [], "_branch"],
 			parser: {},
 			state: conditionalState,
 			...discriminatorSource != null ? { requiresSourceId: discriminatorSource.sourceId } : {},
 			providesSourceIds: branchProvidedSourceIds,
+			...branchGuaranteedIntersection.size > 0 ? { guaranteedProvidesSourceIds: branchGuaranteedIntersection } : {},
 			...mergedBarrierDependencies != null ? { barrierCompletionDependencies: mergedBarrierDependencies } : {},
+			resolveBarrier: async (ctx) => {
+				const prepared = await resolvePreparedSelection(ctx);
+				if (prepared == null) return void 0;
+				if (prepared.branchParser == null) return {
+					orderingDependencyIds: [],
+					activeProvidesSourceIds: /* @__PURE__ */ new Set()
+				};
+				return await computeActiveBarrierDependencies(expandPreparedBranchNodes(prepared));
+			},
 			prepare: async (ctx) => {
-				const session = ctx.exec?.effectfulCompletionSession;
-				if (session == null) return void 0;
-				const key = preparedKeyFor(parentPath);
-				let prepared = session.preparedByPath.get(key);
-				if (prepared == null) {
-					let discriminatorResult = cell.result ?? session.completedByPath.get(discriminatorPathKey);
-					if (discriminatorResult == null && innerCompleteSource == null) {
-						const discriminatorExec = ctx.exec == null ? void 0 : {
-							...ctx.exec,
-							path: [...parentPath ?? [], "_discriminator"]
-						};
-						discriminatorResult = unwrapCompleteResult(await discriminator.complete(annotatedDiscriminatorState, discriminatorExec));
-					}
-					if (discriminatorResult == null || isDeferredCompletionResult(discriminatorResult)) return void 0;
-					const namedBranch = discriminatorResult.success ? branches[String(discriminatorResult.value)] : void 0;
-					const branchParser = namedBranch ?? defaultBranch;
-					let branchState;
-					if (branchParser != null) {
-						const branchExec = ctx.exec == null ? void 0 : {
-							...ctx.exec,
-							path: [...parentPath ?? [], "_branch"]
-						};
-						const annotatedInitial = require_annotation_state.getWrappedChildState(conditionalState, branchParser.initialState, branchParser);
-						const replayResult = await branchParser.parse({
-							buffer: [],
-							optionsTerminated: false,
-							usage: [],
-							exec: branchExec,
-							dependencyRegistry: ctx.exec?.dependencyRegistry,
-							state: annotatedInitial
-						});
-						branchState = replayResult.success ? replayResult.next.state : annotatedInitial;
-					}
-					prepared = {
-						discriminatorResult,
-						branchParser,
-						branchKey: namedBranch != null ? String(discriminatorResult.value) : void 0,
-						branchState
-					};
-					session.preparedByPath.set(key, prepared);
-				}
-				if (prepared.branchParser == null) return void 0;
-				return await ctx.schedule(expandEffectfulRuntimeNodes([{
-					path: [...parentPath ?? [], "_branch"],
-					parser: prepared.branchParser,
-					state: require_annotation_state.getWrappedChildState(conditionalState, prepared.branchState, prepared.branchParser)
-				}]));
+				const prepared = await resolvePreparedSelection(ctx);
+				if (prepared?.branchParser == null) return void 0;
+				return await ctx.schedule(expandPreparedBranchNodes(prepared));
 			}
 		});
 		return nodes;
@@ -7093,11 +7237,17 @@ function conditional(discriminator, branches, defaultBranch, options) {
 		enumerable: false
 	});
 	Object.defineProperty(conditionalParser, require_dependency_runtime.staticSourceScopeKey, {
-		value: [
-			discriminator,
-			...Object.values(branches),
-			...defaultBranch != null ? [defaultBranch] : []
-		],
+		value: [discriminator],
+		configurable: true,
+		enumerable: false
+	});
+	Object.defineProperty(conditionalParser, require_dependency_runtime.exclusiveSourceScopeKey, {
+		value: [...Object.values(branches), ...defaultBranch != null ? [defaultBranch] : []],
+		configurable: true,
+		enumerable: false
+	});
+	if (branchGuaranteedIntersection.size > 0) Object.defineProperty(conditionalParser, require_dependency_runtime.guaranteedStaticSourceIdsKey, {
+		value: branchGuaranteedIntersection,
 		configurable: true,
 		enumerable: false
 	});