@optique/core 0.10.0-dev.377 → 0.10.0-dev.381

package/dist/constructs.cjs

@@ -666,8 +666,12 @@ async function* suggestObjectAsync(context, prefix, parserPairs) {
 * Recursively collects dependency values from DependencySourceState objects
 * found anywhere in the state tree.
 */
-function collectDependencies(state, registry) {
+function collectDependencies(state, registry, visited = /* @__PURE__ */ new WeakSet()) {
 	if (state === null || state === void 0) return;
+	if (typeof state === "object") {
+		if (visited.has(state)) return;
+		visited.add(state);
+	}
 	if (require_dependency.isDependencySourceState(state)) {
 		const depId = state[require_dependency.dependencyId];
 		const result = state.result;
@@ -675,10 +679,10 @@ function collectDependencies(state, registry) {
 		return;
 	}
 	if (Array.isArray(state)) {
-		for (const item of state) collectDependencies(item, registry);
+		for (const item of state) collectDependencies(item, registry, visited);
 		return;
 	}
-	if (typeof state === "object" && !require_dependency.isDeferredParseState(state)) for (const key of Reflect.ownKeys(state)) collectDependencies(state[key], registry);
+	if (typeof state === "object" && !require_dependency.isDeferredParseState(state)) for (const key of Reflect.ownKeys(state)) collectDependencies(state[key], registry, visited);
 }
 /**
 * Checks if a value is a plain object (created with `{}` or `Object.create(null)`).
@@ -727,8 +731,12 @@ function collectDependencyValues(deferredState, registry) {
 * Does NOT traverse class instances (e.g., Temporal.PlainDate, URL) since these
 * are user values that should be preserved as-is.
 */
-function resolveDeferred(state, registry) {
+function resolveDeferred(state, registry, visited = /* @__PURE__ */ new WeakSet()) {
 	if (state === null || state === void 0) return state;
+	if (typeof state === "object") {
+		if (visited.has(state)) return state;
+		visited.add(state);
+	}
 	if (require_dependency.isDeferredParseState(state)) {
 		const deferredState = state;
 		const dependencyValue = collectDependencyValues(deferredState, registry);
@@ -738,10 +746,10 @@ function resolveDeferred(state, registry) {
 		return reParseResult;
 	}
 	if (require_dependency.isDependencySourceState(state)) return state;
-	if (Array.isArray(state)) return state.map((item) => resolveDeferred(item, registry));
+	if (Array.isArray(state)) return state.map((item) => resolveDeferred(item, registry, visited));
 	if (isPlainObject(state)) {
 		const resolved = {};
-		for (const key of Reflect.ownKeys(state)) resolved[key] = resolveDeferred(state[key], registry);
+		for (const key of Reflect.ownKeys(state)) resolved[key] = resolveDeferred(state[key], registry, visited);
 		return resolved;
 	}
 	return state;
@@ -764,8 +772,12 @@ function resolveDeferredParseStates(fieldStates) {
 * Does NOT traverse class instances (e.g., Temporal.PlainDate, URL) since these
 * are user values that should be preserved as-is.
 */
-async function resolveDeferredAsync(state, registry) {
+async function resolveDeferredAsync(state, registry, visited = /* @__PURE__ */ new WeakSet()) {
 	if (state === null || state === void 0) return state;
+	if (typeof state === "object") {
+		if (visited.has(state)) return state;
+		visited.add(state);
+	}
 	if (require_dependency.isDeferredParseState(state)) {
 		const deferredState = state;
 		const dependencyValue = collectDependencyValues(deferredState, registry);
@@ -774,12 +786,12 @@ async function resolveDeferredAsync(state, registry) {
 		return Promise.resolve(reParseResult);
 	}
 	if (require_dependency.isDependencySourceState(state)) return state;
-	if (Array.isArray(state)) return Promise.all(state.map((item) => resolveDeferredAsync(item, registry)));
+	if (Array.isArray(state)) return Promise.all(state.map((item) => resolveDeferredAsync(item, registry, visited)));
 	if (isPlainObject(state)) {
 		const resolved = {};
 		const keys = Reflect.ownKeys(state);
 		await Promise.all(keys.map(async (key) => {
-			resolved[key] = await resolveDeferredAsync(state[key], registry);
+			resolved[key] = await resolveDeferredAsync(state[key], registry, visited);
 		}));
 		return resolved;
 	}

package/dist/constructs.js

@@ -666,8 +666,12 @@ async function* suggestObjectAsync(context, prefix, parserPairs) {
 * Recursively collects dependency values from DependencySourceState objects
 * found anywhere in the state tree.
 */
-function collectDependencies(state, registry) {
+function collectDependencies(state, registry, visited = /* @__PURE__ */ new WeakSet()) {
 	if (state === null || state === void 0) return;
+	if (typeof state === "object") {
+		if (visited.has(state)) return;
+		visited.add(state);
+	}
 	if (isDependencySourceState(state)) {
 		const depId = state[dependencyId];
 		const result = state.result;
@@ -675,10 +679,10 @@ function collectDependencies(state, registry) {
 		return;
 	}
 	if (Array.isArray(state)) {
-		for (const item of state) collectDependencies(item, registry);
+		for (const item of state) collectDependencies(item, registry, visited);
 		return;
 	}
-	if (typeof state === "object" && !isDeferredParseState(state)) for (const key of Reflect.ownKeys(state)) collectDependencies(state[key], registry);
+	if (typeof state === "object" && !isDeferredParseState(state)) for (const key of Reflect.ownKeys(state)) collectDependencies(state[key], registry, visited);
 }
 /**
 * Checks if a value is a plain object (created with `{}` or `Object.create(null)`).
@@ -727,8 +731,12 @@ function collectDependencyValues(deferredState, registry) {
 * Does NOT traverse class instances (e.g., Temporal.PlainDate, URL) since these
 * are user values that should be preserved as-is.
 */
-function resolveDeferred(state, registry) {
+function resolveDeferred(state, registry, visited = /* @__PURE__ */ new WeakSet()) {
 	if (state === null || state === void 0) return state;
+	if (typeof state === "object") {
+		if (visited.has(state)) return state;
+		visited.add(state);
+	}
 	if (isDeferredParseState(state)) {
 		const deferredState = state;
 		const dependencyValue = collectDependencyValues(deferredState, registry);
@@ -738,10 +746,10 @@ function resolveDeferred(state, registry) {
 		return reParseResult;
 	}
 	if (isDependencySourceState(state)) return state;
-	if (Array.isArray(state)) return state.map((item) => resolveDeferred(item, registry));
+	if (Array.isArray(state)) return state.map((item) => resolveDeferred(item, registry, visited));
 	if (isPlainObject(state)) {
 		const resolved = {};
-		for (const key of Reflect.ownKeys(state)) resolved[key] = resolveDeferred(state[key], registry);
+		for (const key of Reflect.ownKeys(state)) resolved[key] = resolveDeferred(state[key], registry, visited);
 		return resolved;
 	}
 	return state;
@@ -764,8 +772,12 @@ function resolveDeferredParseStates(fieldStates) {
 * Does NOT traverse class instances (e.g., Temporal.PlainDate, URL) since these
 * are user values that should be preserved as-is.
 */
-async function resolveDeferredAsync(state, registry) {
+async function resolveDeferredAsync(state, registry, visited = /* @__PURE__ */ new WeakSet()) {
 	if (state === null || state === void 0) return state;
+	if (typeof state === "object") {
+		if (visited.has(state)) return state;
+		visited.add(state);
+	}
 	if (isDeferredParseState(state)) {
 		const deferredState = state;
 		const dependencyValue = collectDependencyValues(deferredState, registry);
@@ -774,12 +786,12 @@ async function resolveDeferredAsync(state, registry) {
 		return Promise.resolve(reParseResult);
 	}
 	if (isDependencySourceState(state)) return state;
-	if (Array.isArray(state)) return Promise.all(state.map((item) => resolveDeferredAsync(item, registry)));
+	if (Array.isArray(state)) return Promise.all(state.map((item) => resolveDeferredAsync(item, registry, visited)));
 	if (isPlainObject(state)) {
 		const resolved = {};
 		const keys = Reflect.ownKeys(state);
 		await Promise.all(keys.map(async (key) => {
-			resolved[key] = await resolveDeferredAsync(state[key], registry);
+			resolved[key] = await resolveDeferredAsync(state[key], registry, visited);
 		}));
 		return resolved;
 	}

package/dist/dependency.cjs

@@ -199,6 +199,9 @@ function determineFactoryModeForDeriveFrom(options) {
 	const parser = options.factory(...defaultValues$1);
 	return parser.$mode === "async";
 }
+function isAsyncModeParser(parser) {
+	return parser.$mode === "async";
+}
 function createSyncDerivedFromParser(sourceId, options) {
 	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
 	return {
@@ -211,6 +214,10 @@ function createSyncDerivedFromParser(sourceId, options) {
 		parse(input) {
 			const sourceValues = options.defaultValues();
 			const derivedParser = options.factory(...sourceValues);
+			if (isAsyncModeParser(derivedParser)) return {
+				success: false,
+				error: require_message.message`Factory returned an async parser where a sync parser is required.`
+			};
 			return derivedParser.parse(input);
 		},
 		[parseWithDependency](input, dependencyValue) {
@@ -224,6 +231,10 @@ function createSyncDerivedFromParser(sourceId, options) {
 					error: require_message.message`Factory error: ${msg}`
 				};
 			}
+			if (isAsyncModeParser(derivedParser)) return {
+				success: false,
+				error: require_message.message`Factory returned an async parser where a sync parser is required.`
+			};
 			return derivedParser.parse(input);
 		},
 		format(value) {
@@ -241,8 +252,12 @@ function createSyncDerivedFromParser(sourceId, options) {
 			try {
 				derivedParser = options.factory(...dependencyValue);
 			} catch {
-				const sourceValues = options.defaultValues();
-				derivedParser = options.factory(...sourceValues);
+				try {
+					const sourceValues = options.defaultValues();
+					derivedParser = options.factory(...sourceValues);
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		}
@@ -294,8 +309,12 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
 			try {
 				derivedParser = options.factory(...dependencyValue);
 			} catch {
-				const sourceValues = options.defaultValues();
-				derivedParser = options.factory(...sourceValues);
+				try {
+					const sourceValues = options.defaultValues();
+					derivedParser = options.factory(...sourceValues);
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
 		}
@@ -347,8 +366,12 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
 			try {
 				derivedParser = options.factory(...dependencyValue);
 			} catch {
-				const sourceValues = options.defaultValues();
-				derivedParser = options.factory(...sourceValues);
+				try {
+					const sourceValues = options.defaultValues();
+					derivedParser = options.factory(...sourceValues);
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		}
@@ -381,6 +404,10 @@ function createSyncDerivedParser(sourceId, options) {
 		parse(input) {
 			const sourceValue = options.defaultValue();
 			const derivedParser = options.factory(sourceValue);
+			if (isAsyncModeParser(derivedParser)) return {
+				success: false,
+				error: require_message.message`Factory returned an async parser where a sync parser is required.`
+			};
 			return derivedParser.parse(input);
 		},
 		[parseWithDependency](input, dependencyValue) {
@@ -394,6 +421,10 @@ function createSyncDerivedParser(sourceId, options) {
 					error: require_message.message`Factory error: ${msg}`
 				};
 			}
+			if (isAsyncModeParser(derivedParser)) return {
+				success: false,
+				error: require_message.message`Factory returned an async parser where a sync parser is required.`
+			};
 			return derivedParser.parse(input);
 		},
 		format(value) {
@@ -411,7 +442,11 @@ function createSyncDerivedParser(sourceId, options) {
 			try {
 				derivedParser = options.factory(dependencyValue);
 			} catch {
-				derivedParser = options.factory(options.defaultValue());
+				try {
+					derivedParser = options.factory(options.defaultValue());
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		}
@@ -460,7 +495,11 @@ function createAsyncDerivedParserFromAsyncFactory(sourceId, options) {
 			try {
 				derivedParser = options.factory(dependencyValue);
 			} catch {
-				derivedParser = options.factory(options.defaultValue());
+				try {
+					derivedParser = options.factory(options.defaultValue());
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
 		}
@@ -509,7 +548,11 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
 			try {
 				derivedParser = options.factory(dependencyValue);
 			} catch {
-				derivedParser = options.factory(options.defaultValue());
+				try {
+					derivedParser = options.factory(options.defaultValue());
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		}

package/dist/dependency.js

@@ -199,6 +199,9 @@ function determineFactoryModeForDeriveFrom(options) {
 	const parser = options.factory(...defaultValues$1);
 	return parser.$mode === "async";
 }
+function isAsyncModeParser(parser) {
+	return parser.$mode === "async";
+}
 function createSyncDerivedFromParser(sourceId, options) {
 	const alldependencyIds = options.dependencies.map((dep) => dep[dependencyId]);
 	return {
@@ -211,6 +214,10 @@ function createSyncDerivedFromParser(sourceId, options) {
 		parse(input) {
 			const sourceValues = options.defaultValues();
 			const derivedParser = options.factory(...sourceValues);
+			if (isAsyncModeParser(derivedParser)) return {
+				success: false,
+				error: message`Factory returned an async parser where a sync parser is required.`
+			};
 			return derivedParser.parse(input);
 		},
 		[parseWithDependency](input, dependencyValue) {
@@ -224,6 +231,10 @@ function createSyncDerivedFromParser(sourceId, options) {
 					error: message`Factory error: ${msg}`
 				};
 			}
+			if (isAsyncModeParser(derivedParser)) return {
+				success: false,
+				error: message`Factory returned an async parser where a sync parser is required.`
+			};
 			return derivedParser.parse(input);
 		},
 		format(value) {
@@ -241,8 +252,12 @@ function createSyncDerivedFromParser(sourceId, options) {
 			try {
 				derivedParser = options.factory(...dependencyValue);
 			} catch {
-				const sourceValues = options.defaultValues();
-				derivedParser = options.factory(...sourceValues);
+				try {
+					const sourceValues = options.defaultValues();
+					derivedParser = options.factory(...sourceValues);
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		}
@@ -294,8 +309,12 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
 			try {
 				derivedParser = options.factory(...dependencyValue);
 			} catch {
-				const sourceValues = options.defaultValues();
-				derivedParser = options.factory(...sourceValues);
+				try {
+					const sourceValues = options.defaultValues();
+					derivedParser = options.factory(...sourceValues);
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
 		}
@@ -347,8 +366,12 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
 			try {
 				derivedParser = options.factory(...dependencyValue);
 			} catch {
-				const sourceValues = options.defaultValues();
-				derivedParser = options.factory(...sourceValues);
+				try {
+					const sourceValues = options.defaultValues();
+					derivedParser = options.factory(...sourceValues);
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		}
@@ -381,6 +404,10 @@ function createSyncDerivedParser(sourceId, options) {
 		parse(input) {
 			const sourceValue = options.defaultValue();
 			const derivedParser = options.factory(sourceValue);
+			if (isAsyncModeParser(derivedParser)) return {
+				success: false,
+				error: message`Factory returned an async parser where a sync parser is required.`
+			};
 			return derivedParser.parse(input);
 		},
 		[parseWithDependency](input, dependencyValue) {
@@ -394,6 +421,10 @@ function createSyncDerivedParser(sourceId, options) {
 					error: message`Factory error: ${msg}`
 				};
 			}
+			if (isAsyncModeParser(derivedParser)) return {
+				success: false,
+				error: message`Factory returned an async parser where a sync parser is required.`
+			};
 			return derivedParser.parse(input);
 		},
 		format(value) {
@@ -411,7 +442,11 @@ function createSyncDerivedParser(sourceId, options) {
 			try {
 				derivedParser = options.factory(dependencyValue);
 			} catch {
-				derivedParser = options.factory(options.defaultValue());
+				try {
+					derivedParser = options.factory(options.defaultValue());
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		}
@@ -460,7 +495,11 @@ function createAsyncDerivedParserFromAsyncFactory(sourceId, options) {
 			try {
 				derivedParser = options.factory(dependencyValue);
 			} catch {
-				derivedParser = options.factory(options.defaultValue());
+				try {
+					derivedParser = options.factory(options.defaultValue());
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
 		}
@@ -509,7 +548,11 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
 			try {
 				derivedParser = options.factory(dependencyValue);
 			} catch {
-				derivedParser = options.factory(options.defaultValue());
+				try {
+					derivedParser = options.factory(options.defaultValue());
+				} catch {
+					return;
+				}
 			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		}

package/dist/facade.cjs

@@ -808,6 +808,31 @@ function mergeAnnotations(annotationsList) {
 	return result;
 }
 /**
+* Collects phase 1 annotations from all contexts and determines whether
+* two-phase parsing is needed.
+*
+* @param contexts Source contexts to collect annotations from.
+* @returns Promise with merged annotations and dynamic-context hint.
+*/
+async function collectPhase1Annotations(contexts) {
+	const annotationsList = [];
+	let hasDynamic = false;
+	for (const context of contexts) {
+		const result = context.getAnnotations();
+		if (result instanceof Promise) {
+			hasDynamic = true;
+			annotationsList.push(await result);
+		} else {
+			if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
+			annotationsList.push(result);
+		}
+	}
+	return {
+		annotations: mergeAnnotations(annotationsList),
+		hasDynamic
+	};
+}
+/**
 * Collects annotations from all contexts.
 *
 * @param contexts Source contexts to collect annotations from.
@@ -818,47 +843,48 @@ async function collectAnnotations(contexts, parsed) {
 	const annotationsList = [];
 	for (const context of contexts) {
 		const result = context.getAnnotations(parsed);
-		if (result instanceof Promise) annotationsList.push(await result);
-		else annotationsList.push(result);
+		annotationsList.push(result instanceof Promise ? await result : result);
 	}
 	return mergeAnnotations(annotationsList);
 }
 /**
-* Collects annotations from all contexts synchronously.
+* Collects phase 1 annotations from all contexts synchronously and determines
+* whether two-phase parsing is needed.
 *
 * @param contexts Source contexts to collect annotations from.
-* @param parsed Optional parsed result from a previous parse pass.
-* @returns Merged annotations.
+* @returns Merged annotations with dynamic-context hint.
 * @throws Error if any context returns a Promise.
 */
-function collectAnnotationsSync(contexts, parsed) {
+function collectPhase1AnnotationsSync(contexts) {
 	const annotationsList = [];
+	let hasDynamic = false;
 	for (const context of contexts) {
-		const result = context.getAnnotations(parsed);
+		const result = context.getAnnotations();
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
 		annotationsList.push(result);
 	}
-	return mergeAnnotations(annotationsList);
+	return {
+		annotations: mergeAnnotations(annotationsList),
+		hasDynamic
+	};
 }
 /**
-* Checks if any context has dynamic behavior (returns different annotations
-* when called with parsed results).
-*
-* A context is considered dynamic if:
-* - It returns a Promise
-* - It returns empty annotations without parsed results but may return
-*   non-empty annotations with parsed results
+* Collects annotations from all contexts synchronously.
 *
-* @param contexts Source contexts to check.
-* @returns `true` if any context appears to be dynamic.
+* @param contexts Source contexts to collect annotations from.
+* @param parsed Optional parsed result from a previous parse pass.
+* @returns Merged annotations.
+* @throws Error if any context returns a Promise.
 */
-function hasDynamicContexts(contexts) {
+function collectAnnotationsSync(contexts, parsed) {
+	const annotationsList = [];
 	for (const context of contexts) {
-		const result = context.getAnnotations();
-		if (result instanceof Promise) return true;
-		if (Object.getOwnPropertySymbols(result).length === 0) return true;
+		const result = context.getAnnotations(parsed);
+		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		annotationsList.push(result);
 	}
-	return false;
+	return mergeAnnotations(annotationsList);
 }
 /**
 * Runs a parser with multiple source contexts.
@@ -918,8 +944,7 @@ async function runWith(parser, programName, contexts, options) {
 		if (parser.$mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
-	const phase1Annotations = await collectAnnotations(contexts);
-	const needsTwoPhase = hasDynamicContexts(contexts);
+	const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
@@ -971,8 +996,7 @@ function runWithSync(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
-	const phase1Annotations = collectAnnotationsSync(contexts);
-	const needsTwoPhase = hasDynamicContexts(contexts);
+	const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		return runParser(augmentedParser, programName, args, options);

package/dist/facade.js

@@ -808,6 +808,31 @@ function mergeAnnotations(annotationsList) {
 	return result;
 }
 /**
+* Collects phase 1 annotations from all contexts and determines whether
+* two-phase parsing is needed.
+*
+* @param contexts Source contexts to collect annotations from.
+* @returns Promise with merged annotations and dynamic-context hint.
+*/
+async function collectPhase1Annotations(contexts) {
+	const annotationsList = [];
+	let hasDynamic = false;
+	for (const context of contexts) {
+		const result = context.getAnnotations();
+		if (result instanceof Promise) {
+			hasDynamic = true;
+			annotationsList.push(await result);
+		} else {
+			if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
+			annotationsList.push(result);
+		}
+	}
+	return {
+		annotations: mergeAnnotations(annotationsList),
+		hasDynamic
+	};
+}
+/**
 * Collects annotations from all contexts.
 *
 * @param contexts Source contexts to collect annotations from.
@@ -818,47 +843,48 @@ async function collectAnnotations(contexts, parsed) {
 	const annotationsList = [];
 	for (const context of contexts) {
 		const result = context.getAnnotations(parsed);
-		if (result instanceof Promise) annotationsList.push(await result);
-		else annotationsList.push(result);
+		annotationsList.push(result instanceof Promise ? await result : result);
 	}
 	return mergeAnnotations(annotationsList);
 }
 /**
-* Collects annotations from all contexts synchronously.
+* Collects phase 1 annotations from all contexts synchronously and determines
+* whether two-phase parsing is needed.
 *
 * @param contexts Source contexts to collect annotations from.
-* @param parsed Optional parsed result from a previous parse pass.
-* @returns Merged annotations.
+* @returns Merged annotations with dynamic-context hint.
 * @throws Error if any context returns a Promise.
 */
-function collectAnnotationsSync(contexts, parsed) {
+function collectPhase1AnnotationsSync(contexts) {
 	const annotationsList = [];
+	let hasDynamic = false;
 	for (const context of contexts) {
-		const result = context.getAnnotations(parsed);
+		const result = context.getAnnotations();
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		if (Object.getOwnPropertySymbols(result).length === 0) hasDynamic = true;
 		annotationsList.push(result);
 	}
-	return mergeAnnotations(annotationsList);
+	return {
+		annotations: mergeAnnotations(annotationsList),
+		hasDynamic
+	};
 }
 /**
-* Checks if any context has dynamic behavior (returns different annotations
-* when called with parsed results).
-*
-* A context is considered dynamic if:
-* - It returns a Promise
-* - It returns empty annotations without parsed results but may return
-*   non-empty annotations with parsed results
+* Collects annotations from all contexts synchronously.
 *
-* @param contexts Source contexts to check.
-* @returns `true` if any context appears to be dynamic.
+* @param contexts Source contexts to collect annotations from.
+* @param parsed Optional parsed result from a previous parse pass.
+* @returns Merged annotations.
+* @throws Error if any context returns a Promise.
 */
-function hasDynamicContexts(contexts) {
+function collectAnnotationsSync(contexts, parsed) {
+	const annotationsList = [];
 	for (const context of contexts) {
-		const result = context.getAnnotations();
-		if (result instanceof Promise) return true;
-		if (Object.getOwnPropertySymbols(result).length === 0) return true;
+		const result = context.getAnnotations(parsed);
+		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
+		annotationsList.push(result);
 	}
-	return false;
+	return mergeAnnotations(annotationsList);
 }
 /**
 * Runs a parser with multiple source contexts.
@@ -918,8 +944,7 @@ async function runWith(parser, programName, contexts, options) {
 		if (parser.$mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
-	const phase1Annotations = await collectAnnotations(contexts);
-	const needsTwoPhase = hasDynamicContexts(contexts);
+	const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
@@ -971,8 +996,7 @@ function runWithSync(parser, programName, contexts, options) {
 	const args = options?.args ?? [];
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);
-	const phase1Annotations = collectAnnotationsSync(contexts);
-	const needsTwoPhase = hasDynamicContexts(contexts);
+	const { annotations: phase1Annotations, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		return runParser(augmentedParser, programName, args, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.10.0-dev.377+69abd2d5",
+  "version": "0.10.0-dev.381+8e08d6d0",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",