@optique/core 1.0.0-dev.1799 → 1.0.0-dev.1802

package/dist/annotations.cjs

@@ -17,7 +17,7 @@
 const annotationKey = Symbol.for("@optique/core/parser/annotation");
 /**
 * Internal marker attached during the first pass of `runWith()` so wrappers
-* with side effects can defer work until dynamic contexts have resolved.
+* with side effects can defer work until two-pass contexts have resolved.
 *
 * @internal
 */

package/dist/annotations.d.cts

@@ -16,7 +16,7 @@
 declare const annotationKey: unique symbol;
 /**
  * Internal marker attached during the first pass of `runWith()` so wrappers
- * with side effects can defer work until dynamic contexts have resolved.
+ * with side effects can defer work until two-pass contexts have resolved.
  *
  * @internal
  */

package/dist/annotations.d.ts

@@ -16,7 +16,7 @@
 declare const annotationKey: unique symbol;
 /**
  * Internal marker attached during the first pass of `runWith()` so wrappers
- * with side effects can defer work until dynamic contexts have resolved.
+ * with side effects can defer work until two-pass contexts have resolved.
  *
  * @internal
  */

package/dist/annotations.js

@@ -16,7 +16,7 @@
 const annotationKey = Symbol.for("@optique/core/parser/annotation");
 /**
 * Internal marker attached during the first pass of `runWith()` so wrappers
-* with side effects can defer work until dynamic contexts have resolved.
+* with side effects can defer work until two-pass contexts have resolved.
 *
 * @internal
 */

package/dist/context.cjs

@@ -1,23 +0,0 @@
-
-//#region src/context.ts
-/**
-* Checks whether a context is static (returns annotations without needing
-* parsed results).
-*
-* A context is considered static if it declares `mode: "static"` or if
-* `getAnnotations()` called without arguments returns a non-empty
-* annotations object synchronously.
-*
-* @param context The source context to check.
-* @returns `true` if the context is static, `false` otherwise.
-* @since 0.10.0
-*/
-function isStaticContext(context) {
-	if (context.mode !== void 0) return context.mode === "static";
-	const result = context.getAnnotations();
-	if (result instanceof Promise) return false;
-	return Object.getOwnPropertySymbols(result).length > 0;
-}
-
-//#endregion
-exports.isStaticContext = isStaticContext;

package/dist/context.d.cts

@@ -3,16 +3,15 @@ import { Annotations } from "./annotations.cjs";
 //#region src/context.d.ts
 
 /**
- * Declares whether a {@link SourceContext} provides its annotations
- * immediately (`"static"`) or only after a prior parse pass (`"dynamic"`).
+ * Declares whether a {@link SourceContext} participates only in the initial
+ * annotation collection (`"single-pass"`) or is recollected after a usable
+ * first parse pass (`"two-pass"`).
  *
- * Used as the type of the optional `mode` field on {@link SourceContext}.
- * When set, {@link isStaticContext} reads this value directly instead of
- * calling `getAnnotations()`, preventing any side effects.
+ * Used as the type of the required `phase` field on {@link SourceContext}.
  *
  * @since 1.0.0
  */
-type SourceContextMode = "static" | "dynamic";
+type SourceContextPhase = "single-pass" | "two-pass";
 /**
  * Brand symbol for ParserValuePlaceholder type.
  * @internal
@@ -50,12 +49,14 @@ type ParserValuePlaceholder = {
 /**
  * A source context that can provide data to parsers via annotations.
  *
- * Source contexts are used to inject external data (like environment variables
- * or config files) into the parsing process. They can be either:
+ * Source contexts are used to inject external data (like environment
+ * variables or config files) into the parsing process. They can be either:
  *
- * - *Static*: Data is immediately available (e.g., environment variables)
- * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
- *   is determined by a CLI option)
+ * - *Single-pass*: The runner collects annotations once before parsing
+ *   (e.g., environment variables)
+ * - *Two-pass*: The runner collects annotations before parsing and then
+ *   recollects them after a usable first parse pass (e.g., config files whose
+ *   path is determined by a CLI option)
  *
  * Contexts may optionally implement `Disposable` or `AsyncDisposable` for
  * cleanup.  When present, `runWith()` and `runWithSync()` call the dispose
@@ -68,9 +69,10 @@ type ParserValuePlaceholder = {
  *
  * @example
  * ```typescript
- * // Static context example (environment variables) - no extra options needed
+ * // Single-pass context example (environment variables)
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
+ *   phase: "single-pass",
  *   getAnnotations() {
  *     return {
  *       [Symbol.for("@myapp/env")]: {
@@ -81,7 +83,7 @@ type ParserValuePlaceholder = {
  *   }
  * };
  *
- * // Dynamic context that requires options from runWith()
+ * // Two-pass context that requires options from runWith()
  * interface ConfigContext extends SourceContext<{
  *   getConfigPath: (parsed: ParserValuePlaceholder) => string | undefined;
  * }> {
@@ -107,42 +109,44 @@ interface SourceContext<TRequiredOptions = void> {
    */
   readonly $requiredOptions?: TRequiredOptions;
   /**
-   * Optional declaration of whether this context is static or dynamic.
+   * Declares whether this context is collected once or recollected after a
+   * usable first parse pass.
    *
-   * When present, {@link isStaticContext} reads this field directly instead
-   * of calling {@link getAnnotations}, avoiding any side effects that
-   * `getAnnotations` might have (such as mutating a global registry).
-   *
-   * If omitted, {@link isStaticContext} falls back to calling
-   * `getAnnotations()` with no arguments to determine static-ness.
+   * `single-pass` contexts contribute only their phase-1 annotations to the
+   * final parse. `two-pass` contexts are called again with the first-pass
+   * parsed value (or a best-effort seed extracted from parser state) and that
+   * second return value becomes the context's final annotation snapshot.
    *
    * @since 1.0.0
    */
-  readonly mode?: SourceContextMode;
+  readonly phase: SourceContextPhase;
   /**
    * Get annotations to inject into parsing.
    *
-   * This method is called twice during `runWith()` execution:
+   * This method is called during phase 1 for every context and during phase 2
+   * only for `two-pass` contexts:
    *
-   * 1. *First call*: `parsed` is `undefined`. Static contexts should return
-   *    their annotations, while dynamic contexts should return an empty object.
-   * 2. *Second call*: `parsed` contains the first pass result, or a
-   *    best-effort partial value extracted from parser state when the first
-   *    pass reached a usable intermediate state but still did not complete
-   *    successfully. Dynamic contexts can use this to load external data
-   *    (e.g., reading a config file whose path was determined in the first
-   *    pass). Deferred or otherwise unresolved fields may be `undefined`.
-   *    If the runner cannot extract a usable value at all, this second call
-   *    is skipped and the original parse failure is reported instead.
+   * 1. *Phase 1*: `parsed` is `undefined`.
+   * 2. *Phase 2*: `parsed` contains the first pass result, or a best-effort
+   *    partial value extracted from parser state when the first pass reached a
+   *    usable intermediate state but still did not complete successfully.
+   *    Deferred or otherwise unresolved fields may be `undefined`. This
+   *    second return value is treated as the context's final annotation
+   *    snapshot for the second parse pass, replacing that context's phase-one
+   *    contribution. If the runner cannot extract a usable value at all, this
+   *    second call is skipped and the original parse failure is reported
+   *    instead.
    *
    * @param parsed Optional parsed result from a previous parse pass.
-   *               Static contexts can ignore this parameter.
-   *               Dynamic contexts use this to extract necessary data.
+   *               `single-pass` contexts can ignore this parameter.
+   *               `two-pass` contexts use this to extract or refine data.
    * @param options Optional context-required options provided by the caller
    *               of `runWith()`. These are the options declared via the
    *               `TRequiredOptions` type parameter.
-   * @returns Annotations to merge into the parsing session. Can be a Promise
-   *          for async operations (e.g., loading config files).
+   * @returns Annotations to merge into the parsing session. During phase 2,
+   *          returning `{}` clears any annotations this context contributed
+   *          during phase 1. Can be a Promise for async operations (e.g.,
+   *          loading config files).
    */
   getAnnotations(parsed?: unknown, options?: unknown): Promise<Annotations> | Annotations;
   /**
@@ -188,18 +192,5 @@ interface SourceContext<TRequiredOptions = void> {
    */
   [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
-/**
- * Checks whether a context is static (returns annotations without needing
- * parsed results).
- *
- * A context is considered static if it declares `mode: "static"` or if
- * `getAnnotations()` called without arguments returns a non-empty
- * annotations object synchronously.
- *
- * @param context The source context to check.
- * @returns `true` if the context is static, `false` otherwise.
- * @since 0.10.0
- */
-declare function isStaticContext(context: SourceContext<unknown>): boolean;
 //#endregion
-export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextMode, isStaticContext };
+export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextPhase };

package/dist/context.d.ts

@@ -3,16 +3,15 @@ import { Annotations } from "./annotations.js";
 //#region src/context.d.ts
 
 /**
- * Declares whether a {@link SourceContext} provides its annotations
- * immediately (`"static"`) or only after a prior parse pass (`"dynamic"`).
+ * Declares whether a {@link SourceContext} participates only in the initial
+ * annotation collection (`"single-pass"`) or is recollected after a usable
+ * first parse pass (`"two-pass"`).
  *
- * Used as the type of the optional `mode` field on {@link SourceContext}.
- * When set, {@link isStaticContext} reads this value directly instead of
- * calling `getAnnotations()`, preventing any side effects.
+ * Used as the type of the required `phase` field on {@link SourceContext}.
  *
  * @since 1.0.0
  */
-type SourceContextMode = "static" | "dynamic";
+type SourceContextPhase = "single-pass" | "two-pass";
 /**
  * Brand symbol for ParserValuePlaceholder type.
  * @internal
@@ -50,12 +49,14 @@ type ParserValuePlaceholder = {
 /**
  * A source context that can provide data to parsers via annotations.
  *
- * Source contexts are used to inject external data (like environment variables
- * or config files) into the parsing process. They can be either:
+ * Source contexts are used to inject external data (like environment
+ * variables or config files) into the parsing process. They can be either:
  *
- * - *Static*: Data is immediately available (e.g., environment variables)
- * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
- *   is determined by a CLI option)
+ * - *Single-pass*: The runner collects annotations once before parsing
+ *   (e.g., environment variables)
+ * - *Two-pass*: The runner collects annotations before parsing and then
+ *   recollects them after a usable first parse pass (e.g., config files whose
+ *   path is determined by a CLI option)
  *
  * Contexts may optionally implement `Disposable` or `AsyncDisposable` for
  * cleanup.  When present, `runWith()` and `runWithSync()` call the dispose
@@ -68,9 +69,10 @@ type ParserValuePlaceholder = {
  *
  * @example
  * ```typescript
- * // Static context example (environment variables) - no extra options needed
+ * // Single-pass context example (environment variables)
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
+ *   phase: "single-pass",
  *   getAnnotations() {
  *     return {
  *       [Symbol.for("@myapp/env")]: {
@@ -81,7 +83,7 @@ type ParserValuePlaceholder = {
  *   }
  * };
  *
- * // Dynamic context that requires options from runWith()
+ * // Two-pass context that requires options from runWith()
  * interface ConfigContext extends SourceContext<{
  *   getConfigPath: (parsed: ParserValuePlaceholder) => string | undefined;
  * }> {
@@ -107,42 +109,44 @@ interface SourceContext<TRequiredOptions = void> {
    */
   readonly $requiredOptions?: TRequiredOptions;
   /**
-   * Optional declaration of whether this context is static or dynamic.
+   * Declares whether this context is collected once or recollected after a
+   * usable first parse pass.
    *
-   * When present, {@link isStaticContext} reads this field directly instead
-   * of calling {@link getAnnotations}, avoiding any side effects that
-   * `getAnnotations` might have (such as mutating a global registry).
-   *
-   * If omitted, {@link isStaticContext} falls back to calling
-   * `getAnnotations()` with no arguments to determine static-ness.
+   * `single-pass` contexts contribute only their phase-1 annotations to the
+   * final parse. `two-pass` contexts are called again with the first-pass
+   * parsed value (or a best-effort seed extracted from parser state) and that
+   * second return value becomes the context's final annotation snapshot.
    *
    * @since 1.0.0
    */
-  readonly mode?: SourceContextMode;
+  readonly phase: SourceContextPhase;
   /**
    * Get annotations to inject into parsing.
    *
-   * This method is called twice during `runWith()` execution:
+   * This method is called during phase 1 for every context and during phase 2
+   * only for `two-pass` contexts:
    *
-   * 1. *First call*: `parsed` is `undefined`. Static contexts should return
-   *    their annotations, while dynamic contexts should return an empty object.
-   * 2. *Second call*: `parsed` contains the first pass result, or a
-   *    best-effort partial value extracted from parser state when the first
-   *    pass reached a usable intermediate state but still did not complete
-   *    successfully. Dynamic contexts can use this to load external data
-   *    (e.g., reading a config file whose path was determined in the first
-   *    pass). Deferred or otherwise unresolved fields may be `undefined`.
-   *    If the runner cannot extract a usable value at all, this second call
-   *    is skipped and the original parse failure is reported instead.
+   * 1. *Phase 1*: `parsed` is `undefined`.
+   * 2. *Phase 2*: `parsed` contains the first pass result, or a best-effort
+   *    partial value extracted from parser state when the first pass reached a
+   *    usable intermediate state but still did not complete successfully.
+   *    Deferred or otherwise unresolved fields may be `undefined`. This
+   *    second return value is treated as the context's final annotation
+   *    snapshot for the second parse pass, replacing that context's phase-one
+   *    contribution. If the runner cannot extract a usable value at all, this
+   *    second call is skipped and the original parse failure is reported
+   *    instead.
    *
    * @param parsed Optional parsed result from a previous parse pass.
-   *               Static contexts can ignore this parameter.
-   *               Dynamic contexts use this to extract necessary data.
+   *               `single-pass` contexts can ignore this parameter.
+   *               `two-pass` contexts use this to extract or refine data.
    * @param options Optional context-required options provided by the caller
    *               of `runWith()`. These are the options declared via the
    *               `TRequiredOptions` type parameter.
-   * @returns Annotations to merge into the parsing session. Can be a Promise
-   *          for async operations (e.g., loading config files).
+   * @returns Annotations to merge into the parsing session. During phase 2,
+   *          returning `{}` clears any annotations this context contributed
+   *          during phase 1. Can be a Promise for async operations (e.g.,
+   *          loading config files).
    */
   getAnnotations(parsed?: unknown, options?: unknown): Promise<Annotations> | Annotations;
   /**
@@ -188,18 +192,5 @@ interface SourceContext<TRequiredOptions = void> {
    */
   [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
-/**
- * Checks whether a context is static (returns annotations without needing
- * parsed results).
- *
- * A context is considered static if it declares `mode: "static"` or if
- * `getAnnotations()` called without arguments returns a non-empty
- * annotations object synchronously.
- *
- * @param context The source context to check.
- * @returns `true` if the context is static, `false` otherwise.
- * @since 0.10.0
- */
-declare function isStaticContext(context: SourceContext<unknown>): boolean;
 //#endregion
-export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextMode, isStaticContext };
+export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextPhase };

package/dist/context.js

@@ -1,22 +0,0 @@
-//#region src/context.ts
-/**
-* Checks whether a context is static (returns annotations without needing
-* parsed results).
-*
-* A context is considered static if it declares `mode: "static"` or if
-* `getAnnotations()` called without arguments returns a non-empty
-* annotations object synchronously.
-*
-* @param context The source context to check.
-* @returns `true` if the context is static, `false` otherwise.
-* @since 0.10.0
-*/
-function isStaticContext(context) {
-	if (context.mode !== void 0) return context.mode === "static";
-	const result = context.getAnnotations();
-	if (result instanceof Promise) return false;
-	return Object.getOwnPropertySymbols(result).length > 0;
-}
-
-//#endregion
-export { isStaticContext };

package/dist/facade.cjs

@@ -1081,42 +1081,62 @@ function mergeAnnotations(annotationsList) {
 	}
 	return result;
 }
+function validateContextPhases(contexts) {
+	for (const context of contexts) {
+		const phase = context.phase;
+		if (phase !== "single-pass" && phase !== "two-pass") throw new TypeError(`Context ${String(context.id)} must declare phase as "single-pass" or "two-pass".`);
+	}
+}
 /**
 * Collects phase 1 annotations from all contexts and determines whether
 * two-phase parsing is needed.
 *
 * @param contexts Source contexts to collect annotations from.
 * @param options Optional context-required options to pass to each context.
-* @returns Promise with merged annotations and dynamic-context hint.
+* @returns Promise with merged annotations, per-context snapshots, and a
+* two-phase hint.
 */
 async function collectPhase1Annotations(contexts, options) {
 	const annotationsList = [];
-	let hasDynamic = false;
+	const snapshots = [];
+	let needsTwoPhase = false;
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
-		hasDynamic ||= needsTwoPhaseContext(context, result);
 		const annotations = result instanceof Promise ? await result : result;
 		const internalAnnotations = context.getInternalAnnotations?.(void 0, annotations);
-		annotationsList.push(internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]));
+		const snapshot = internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
+		annotationsList.push(snapshot);
+		snapshots.push(snapshot);
+		needsTwoPhase ||= context.phase === "two-pass";
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
-		annotationsList,
-		hasDynamic
+		needsTwoPhase,
+		snapshots
 	};
 }
 /**
-* Collects annotations from all contexts.
+* Collects final annotations from all contexts.
+*
+* `single-pass` contexts reuse their phase-1 snapshot. `two-pass` contexts
+* are recollected with the parsed value and replace their own phase-1
+* snapshot in the final merge.
 *
 * @param contexts Source contexts to collect annotations from.
+* @param phase1Snapshots Per-context snapshots collected during phase 1.
 * @param parsed Optional parsed result from a previous parse pass.
 * @param options Optional context-required options to pass to each context.
 * @returns Promise that resolves to merged annotations.
 */
-async function collectAnnotations(contexts, parsed, options, deferred, deferredKeys) {
+async function collectFinalAnnotations(contexts, phase1Snapshots, parsed, options, deferred, deferredKeys) {
 	const annotationsList = [];
 	const preparedParsed = prepareParsedForContexts(parsed, deferred, deferredKeys);
-	for (const context of contexts) {
+	for (let index = 0; index < contexts.length; index++) {
+		const context = contexts[index];
+		if (context.phase === "single-pass") {
+			annotationsList.push(phase1Snapshots[index]);
+			continue;
+		}
 		const mergedAnnotations = await withPreparedParsedForContext(context, preparedParsed, async (contextParsed) => {
 			const result = context.getAnnotations(contextParsed, options);
 			const annotations = result instanceof Promise ? await result : result;
@@ -1125,10 +1145,7 @@ async function collectAnnotations(contexts, parsed, options, deferred, deferredK
 		});
 		annotationsList.push(mergedAnnotations);
 	}
-	return {
-		annotations: mergeAnnotations(annotationsList),
-		annotationsList
-	};
+	return { annotations: mergeAnnotations(annotationsList) };
 }
 /**
 * Collects phase 1 annotations from all contexts synchronously and determines
@@ -1136,50 +1153,51 @@ async function collectAnnotations(contexts, parsed, options, deferred, deferredK
 *
 * @param contexts Source contexts to collect annotations from.
 * @param options Optional context-required options to pass to each context.
-* @returns Merged annotations with dynamic-context hint.
+* @returns Merged annotations, per-context snapshots, and a two-phase hint.
 * @throws Error if any context returns a Promise.
 */
 function collectPhase1AnnotationsSync(contexts, options) {
 	const annotationsList = [];
-	let hasDynamic = false;
+	const snapshots = [];
+	let needsTwoPhase = false;
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		hasDynamic ||= needsTwoPhaseContext(context, result);
 		const internalAnnotations = context.getInternalAnnotations?.(void 0, result);
-		annotationsList.push(internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]));
+		const snapshot = internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
+		annotationsList.push(snapshot);
+		snapshots.push(snapshot);
+		needsTwoPhase ||= context.phase === "two-pass";
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
-		annotationsList,
-		hasDynamic
+		needsTwoPhase,
+		snapshots
 	};
 }
 /**
-* Determines whether a context requires a second parse pass.
+* Collects final annotations from all contexts synchronously.
 *
-* Explicit `mode` declarations take precedence over legacy heuristics so
-* static contexts are not forced into two-phase parsing when they return
-* empty annotations or a Promise.
-*/
-function needsTwoPhaseContext(context, result) {
-	if (context.mode !== void 0) return context.mode === "dynamic";
-	if (result instanceof Promise) return true;
-	return Object.getOwnPropertySymbols(result).length === 0;
-}
-/**
-* Collects annotations from all contexts synchronously.
+* `single-pass` contexts reuse their phase-1 snapshot. `two-pass` contexts
+* are recollected with the parsed value and replace their own phase-1
+* snapshot in the final merge.
 *
 * @param contexts Source contexts to collect annotations from.
+* @param phase1Snapshots Per-context snapshots collected during phase 1.
 * @param parsed Optional parsed result from a previous parse pass.
 * @param options Optional context-required options to pass to each context.
 * @returns Merged annotations.
 * @throws Error if any context returns a Promise.
 */
-function collectAnnotationsSync(contexts, parsed, options, deferred, deferredKeys) {
+function collectFinalAnnotationsSync(contexts, phase1Snapshots, parsed, options, deferred, deferredKeys) {
 	const annotationsList = [];
 	const preparedParsed = prepareParsedForContexts(parsed, deferred, deferredKeys);
-	for (const context of contexts) {
+	for (let index = 0; index < contexts.length; index++) {
+		const context = contexts[index];
+		if (context.phase === "single-pass") {
+			annotationsList.push(phase1Snapshots[index]);
+			continue;
+		}
 		const mergedAnnotations = withPreparedParsedForContext(context, preparedParsed, (contextParsed) => {
 			const result = context.getAnnotations(contextParsed, options);
 			if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
@@ -1188,16 +1206,7 @@ function collectAnnotationsSync(contexts, parsed, options, deferred, deferredKey
 		});
 		annotationsList.push(mergedAnnotations);
 	}
-	return {
-		annotations: mergeAnnotations(annotationsList),
-		annotationsList
-	};
-}
-function mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList) {
-	const mergedPerContext = [];
-	const length = Math.max(phase1AnnotationsList.length, phase2AnnotationsList.length);
-	for (let i = 0; i < length; i++) mergedPerContext.push(mergeAnnotations([phase2AnnotationsList[i] ?? {}, phase1AnnotationsList[i] ?? {}]));
-	return mergeAnnotations(mergedPerContext);
+	return { annotations: mergeAnnotations(annotationsList) };
 }
 /**
 * Disposes all contexts that implement `AsyncDisposable` or `Disposable`.
@@ -1242,12 +1251,13 @@ function disposeContextsSync(contexts) {
 */
 async function runWithBody(parser, programName, contexts, args, options) {
 	require_validate.validateContextIds(contexts);
+	validateContextPhases(contexts);
 	if (needsEarlyExit(args, options)) {
 		if (parser.$mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	const ctxOptions = options.contextOptions;
-	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
+	const { annotations: phase1Annotations, needsTwoPhase, snapshots: phase1Snapshots } = await collectPhase1Annotations(contexts, ctxOptions);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
@@ -1260,8 +1270,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser, programName, args, options));
 	}
-	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
-	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const { annotations: finalAnnotations } = await collectFinalAnnotations(contexts, phase1Snapshots, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
 	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
@@ -1269,26 +1278,28 @@ async function runWithBody(parser, programName, contexts, args, options) {
 /**
 * Runs a parser with multiple source contexts.
 *
-* This function automatically handles static and dynamic contexts with proper
-* priority. Earlier contexts in the array override later ones.
+* This function automatically handles single-pass and two-pass contexts with
+* proper priority. Earlier contexts in the array override later ones.
 *
 * The function uses a smart two-phase approach:
 *
-* 1. *Phase 1*: Collect annotations from all contexts (static contexts return
-*    their data, dynamic contexts may return empty).
+* 1. *Phase 1*: Collect annotations from all contexts.
 * 2. *First parse*: Parse with Phase 1 annotations. If that pass finishes
 *    successfully, its value becomes the phase-two input. If the parser
 *    reaches a usable intermediate state but still does not complete
 *    successfully, the runner extracts a best-effort seed from that state
 *    instead.
-* 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
-*    pass value. Deferred or otherwise unresolved fields in `parsed` may be
-*    `undefined`.
-* 4. *Second parse*: Parse again with merged annotations from both phases.
+* 3. *Phase 2*: Call `getAnnotations(parsed)` on all two-pass contexts with
+*    the first pass value. Deferred or otherwise unresolved fields in
+*    `parsed` may be `undefined`. Each two-pass context's phase-two return
+*    value replaces its own phase-one contribution for the final parse, so
+*    returning `{}` clears any annotations that context provided during
+*    phase 1. Single-pass contexts reuse their phase-one snapshot.
+* 4. *Second parse*: Parse again with the merged phase-two annotations.
 *
-* If all contexts are static (no dynamic contexts), the second parse is
-* skipped for optimization. Phase 2 is also skipped when the first pass does
-* not yield any usable seed at all.
+* If all contexts are single-pass, the second parse is skipped for
+* optimization. Phase 2 is also skipped when the first pass does not yield
+* any usable seed at all.
 *
 * @template TParser The parser type.
 * @template THelp Return type when help is shown.
@@ -1300,6 +1311,8 @@ async function runWithBody(parser, programName, contexts, args, options) {
 * @returns Promise that resolves to the parsed result.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.
+* @throws {TypeError} If any context omits `phase` or declares an invalid
+* phase value.
 * @throws {SuppressedError} If the runner throws and a context's disposal
 * also throws.  The original error is available via `.suppressed` and the
 * disposal error via `.error`.
@@ -1312,6 +1325,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 *
 * const envContext: SourceContext = {
 *   id: Symbol.for("@myapp/env"),
+*   phase: "single-pass",
 *   getAnnotations() {
 *     return { [Symbol.for("@myapp/env")]: process.env };
 *   }
@@ -1355,9 +1369,10 @@ async function runWith(parser, programName, contexts, options) {
 */
 function runWithSyncBody(parser, programName, contexts, args, options) {
 	require_validate.validateContextIds(contexts);
+	validateContextPhases(contexts);
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	const ctxOptions = options.contextOptions;
-	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
+	const { annotations: phase1Annotations, needsTwoPhase, snapshots: phase1Snapshots } = collectPhase1AnnotationsSync(contexts, ctxOptions);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		return runParser(augmentedParser, programName, args, options);
@@ -1368,8 +1383,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		return runParser(augmentedParser, programName, args, options);
 	}
-	const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
-	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const { annotations: finalAnnotations } = collectFinalAnnotationsSync(contexts, phase1Snapshots, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	return runParser(augmentedParser2, programName, args, options);
 }
@@ -1378,8 +1392,10 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 *
 * This is the sync-only variant of {@link runWith}. All contexts must return
 * annotations synchronously (not Promises). It uses the same two-phase
-* best-effort seed extraction as {@link runWith} when dynamic contexts are
-* present.
+* best-effort seed extraction as {@link runWith} when two-pass contexts are
+* present. In two-phase runs, each two-pass context's phase-two return value
+* replaces that context's phase-one contribution for the final parse, so
+* returning `{}` clears any annotations that context provided during phase 1.
 *
 * @template TParser The sync parser type.
 * @template THelp Return type when help is shown.
@@ -1393,6 +1409,8 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * {@link runWith} or {@link runWithAsync} for async parsers.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.
+* @throws {TypeError} If any context omits `phase` or declares an invalid
+* phase value.
 * @throws {Error} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
 * @throws {SuppressedError} If the runner throws and a context's disposal

package/dist/facade.d.cts

@@ -405,26 +405,28 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
 /**
  * Runs a parser with multiple source contexts.
  *
- * This function automatically handles static and dynamic contexts with proper
- * priority. Earlier contexts in the array override later ones.
+ * This function automatically handles single-pass and two-pass contexts with
+ * proper priority. Earlier contexts in the array override later ones.
  *
  * The function uses a smart two-phase approach:
  *
- * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
- *    their data, dynamic contexts may return empty).
+ * 1. *Phase 1*: Collect annotations from all contexts.
  * 2. *First parse*: Parse with Phase 1 annotations. If that pass finishes
  *    successfully, its value becomes the phase-two input. If the parser
  *    reaches a usable intermediate state but still does not complete
  *    successfully, the runner extracts a best-effort seed from that state
  *    instead.
- * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
- *    pass value. Deferred or otherwise unresolved fields in `parsed` may be
- *    `undefined`.
- * 4. *Second parse*: Parse again with merged annotations from both phases.
+ * 3. *Phase 2*: Call `getAnnotations(parsed)` on all two-pass contexts with
+ *    the first pass value. Deferred or otherwise unresolved fields in
+ *    `parsed` may be `undefined`. Each two-pass context's phase-two return
+ *    value replaces its own phase-one contribution for the final parse, so
+ *    returning `{}` clears any annotations that context provided during
+ *    phase 1. Single-pass contexts reuse their phase-one snapshot.
+ * 4. *Second parse*: Parse again with the merged phase-two annotations.
  *
- * If all contexts are static (no dynamic contexts), the second parse is
- * skipped for optimization. Phase 2 is also skipped when the first pass does
- * not yield any usable seed at all.
+ * If all contexts are single-pass, the second parse is skipped for
+ * optimization. Phase 2 is also skipped when the first pass does not yield
+ * any usable seed at all.
  *
  * @template TParser The parser type.
  * @template THelp Return type when help is shown.
@@ -436,6 +438,8 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @returns Promise that resolves to the parsed result.
  * @throws {TypeError} If two or more contexts share the same
  * {@link SourceContext.id}.
+ * @throws {TypeError} If any context omits `phase` or declares an invalid
+ * phase value.
  * @throws {SuppressedError} If the runner throws and a context's disposal
  * also throws.  The original error is available via `.suppressed` and the
  * disposal error via `.error`.
@@ -448,6 +452,7 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  *
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
+ *   phase: "single-pass",
  *   getAnnotations() {
  *     return { [Symbol.for("@myapp/env")]: process.env };
  *   }
@@ -467,8 +472,10 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  *
  * This is the sync-only variant of {@link runWith}. All contexts must return
  * annotations synchronously (not Promises). It uses the same two-phase
- * best-effort seed extraction as {@link runWith} when dynamic contexts are
- * present.
+ * best-effort seed extraction as {@link runWith} when two-pass contexts are
+ * present. In two-phase runs, each two-pass context's phase-two return value
+ * replaces that context's phase-one contribution for the final parse, so
+ * returning `{}` clears any annotations that context provided during phase 1.
  *
  * @template TParser The sync parser type.
  * @template THelp Return type when help is shown.
@@ -482,6 +489,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * {@link runWith} or {@link runWithAsync} for async parsers.
  * @throws {TypeError} If two or more contexts share the same
  * {@link SourceContext.id}.
+ * @throws {TypeError} If any context omits `phase` or declares an invalid
+ * phase value.
  * @throws {Error} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
  * @throws {SuppressedError} If the runner throws and a context's disposal

package/dist/facade.d.ts

@@ -405,26 +405,28 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
 /**
  * Runs a parser with multiple source contexts.
  *
- * This function automatically handles static and dynamic contexts with proper
- * priority. Earlier contexts in the array override later ones.
+ * This function automatically handles single-pass and two-pass contexts with
+ * proper priority. Earlier contexts in the array override later ones.
  *
  * The function uses a smart two-phase approach:
  *
- * 1. *Phase 1*: Collect annotations from all contexts (static contexts return
- *    their data, dynamic contexts may return empty).
+ * 1. *Phase 1*: Collect annotations from all contexts.
  * 2. *First parse*: Parse with Phase 1 annotations. If that pass finishes
  *    successfully, its value becomes the phase-two input. If the parser
  *    reaches a usable intermediate state but still does not complete
  *    successfully, the runner extracts a best-effort seed from that state
  *    instead.
- * 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
- *    pass value. Deferred or otherwise unresolved fields in `parsed` may be
- *    `undefined`.
- * 4. *Second parse*: Parse again with merged annotations from both phases.
+ * 3. *Phase 2*: Call `getAnnotations(parsed)` on all two-pass contexts with
+ *    the first pass value. Deferred or otherwise unresolved fields in
+ *    `parsed` may be `undefined`. Each two-pass context's phase-two return
+ *    value replaces its own phase-one contribution for the final parse, so
+ *    returning `{}` clears any annotations that context provided during
+ *    phase 1. Single-pass contexts reuse their phase-one snapshot.
+ * 4. *Second parse*: Parse again with the merged phase-two annotations.
  *
- * If all contexts are static (no dynamic contexts), the second parse is
- * skipped for optimization. Phase 2 is also skipped when the first pass does
- * not yield any usable seed at all.
+ * If all contexts are single-pass, the second parse is skipped for
+ * optimization. Phase 2 is also skipped when the first pass does not yield
+ * any usable seed at all.
  *
  * @template TParser The parser type.
  * @template THelp Return type when help is shown.
@@ -436,6 +438,8 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  * @returns Promise that resolves to the parsed result.
  * @throws {TypeError} If two or more contexts share the same
  * {@link SourceContext.id}.
+ * @throws {TypeError} If any context omits `phase` or declares an invalid
+ * phase value.
  * @throws {SuppressedError} If the runner throws and a context's disposal
  * also throws.  The original error is available via `.suppressed` and the
  * disposal error via `.error`.
@@ -448,6 +452,7 @@ type ContextOptionsParam<TContexts extends readonly SourceContext<unknown>[], TV
  *
  * const envContext: SourceContext = {
  *   id: Symbol.for("@myapp/env"),
+ *   phase: "single-pass",
  *   getAnnotations() {
  *     return { [Symbol.for("@myapp/env")]: process.env };
  *   }
@@ -467,8 +472,10 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  *
  * This is the sync-only variant of {@link runWith}. All contexts must return
  * annotations synchronously (not Promises). It uses the same two-phase
- * best-effort seed extraction as {@link runWith} when dynamic contexts are
- * present.
+ * best-effort seed extraction as {@link runWith} when two-pass contexts are
+ * present. In two-phase runs, each two-pass context's phase-two return value
+ * replaces that context's phase-one contribution for the final parse, so
+ * returning `{}` clears any annotations that context provided during phase 1.
  *
  * @template TParser The sync parser type.
  * @template THelp Return type when help is shown.
@@ -482,6 +489,8 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * {@link runWith} or {@link runWithAsync} for async parsers.
  * @throws {TypeError} If two or more contexts share the same
  * {@link SourceContext.id}.
+ * @throws {TypeError} If any context omits `phase` or declares an invalid
+ * phase value.
  * @throws {Error} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
  * @throws {SuppressedError} If the runner throws and a context's disposal

package/dist/facade.js

@@ -1081,42 +1081,62 @@ function mergeAnnotations(annotationsList) {
 	}
 	return result;
 }
+function validateContextPhases(contexts) {
+	for (const context of contexts) {
+		const phase = context.phase;
+		if (phase !== "single-pass" && phase !== "two-pass") throw new TypeError(`Context ${String(context.id)} must declare phase as "single-pass" or "two-pass".`);
+	}
+}
 /**
 * Collects phase 1 annotations from all contexts and determines whether
 * two-phase parsing is needed.
 *
 * @param contexts Source contexts to collect annotations from.
 * @param options Optional context-required options to pass to each context.
-* @returns Promise with merged annotations and dynamic-context hint.
+* @returns Promise with merged annotations, per-context snapshots, and a
+* two-phase hint.
 */
 async function collectPhase1Annotations(contexts, options) {
 	const annotationsList = [];
-	let hasDynamic = false;
+	const snapshots = [];
+	let needsTwoPhase = false;
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
-		hasDynamic ||= needsTwoPhaseContext(context, result);
 		const annotations = result instanceof Promise ? await result : result;
 		const internalAnnotations = context.getInternalAnnotations?.(void 0, annotations);
-		annotationsList.push(internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]));
+		const snapshot = internalAnnotations == null ? annotations : mergeAnnotations([annotations, internalAnnotations]);
+		annotationsList.push(snapshot);
+		snapshots.push(snapshot);
+		needsTwoPhase ||= context.phase === "two-pass";
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
-		annotationsList,
-		hasDynamic
+		needsTwoPhase,
+		snapshots
 	};
 }
 /**
-* Collects annotations from all contexts.
+* Collects final annotations from all contexts.
+*
+* `single-pass` contexts reuse their phase-1 snapshot. `two-pass` contexts
+* are recollected with the parsed value and replace their own phase-1
+* snapshot in the final merge.
 *
 * @param contexts Source contexts to collect annotations from.
+* @param phase1Snapshots Per-context snapshots collected during phase 1.
 * @param parsed Optional parsed result from a previous parse pass.
 * @param options Optional context-required options to pass to each context.
 * @returns Promise that resolves to merged annotations.
 */
-async function collectAnnotations(contexts, parsed, options, deferred, deferredKeys) {
+async function collectFinalAnnotations(contexts, phase1Snapshots, parsed, options, deferred, deferredKeys) {
 	const annotationsList = [];
 	const preparedParsed = prepareParsedForContexts(parsed, deferred, deferredKeys);
-	for (const context of contexts) {
+	for (let index = 0; index < contexts.length; index++) {
+		const context = contexts[index];
+		if (context.phase === "single-pass") {
+			annotationsList.push(phase1Snapshots[index]);
+			continue;
+		}
 		const mergedAnnotations = await withPreparedParsedForContext(context, preparedParsed, async (contextParsed) => {
 			const result = context.getAnnotations(contextParsed, options);
 			const annotations = result instanceof Promise ? await result : result;
@@ -1125,10 +1145,7 @@ async function collectAnnotations(contexts, parsed, options, deferred, deferredK
 		});
 		annotationsList.push(mergedAnnotations);
 	}
-	return {
-		annotations: mergeAnnotations(annotationsList),
-		annotationsList
-	};
+	return { annotations: mergeAnnotations(annotationsList) };
 }
 /**
 * Collects phase 1 annotations from all contexts synchronously and determines
@@ -1136,50 +1153,51 @@ async function collectAnnotations(contexts, parsed, options, deferred, deferredK
 *
 * @param contexts Source contexts to collect annotations from.
 * @param options Optional context-required options to pass to each context.
-* @returns Merged annotations with dynamic-context hint.
+* @returns Merged annotations, per-context snapshots, and a two-phase hint.
 * @throws Error if any context returns a Promise.
 */
 function collectPhase1AnnotationsSync(contexts, options) {
 	const annotationsList = [];
-	let hasDynamic = false;
+	const snapshots = [];
+	let needsTwoPhase = false;
 	for (const context of contexts) {
 		const result = context.getAnnotations(void 0, options);
 		if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
-		hasDynamic ||= needsTwoPhaseContext(context, result);
 		const internalAnnotations = context.getInternalAnnotations?.(void 0, result);
-		annotationsList.push(internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]));
+		const snapshot = internalAnnotations == null ? result : mergeAnnotations([result, internalAnnotations]);
+		annotationsList.push(snapshot);
+		snapshots.push(snapshot);
+		needsTwoPhase ||= context.phase === "two-pass";
 	}
 	return {
 		annotations: mergeAnnotations(annotationsList),
-		annotationsList,
-		hasDynamic
+		needsTwoPhase,
+		snapshots
 	};
 }
 /**
-* Determines whether a context requires a second parse pass.
+* Collects final annotations from all contexts synchronously.
 *
-* Explicit `mode` declarations take precedence over legacy heuristics so
-* static contexts are not forced into two-phase parsing when they return
-* empty annotations or a Promise.
-*/
-function needsTwoPhaseContext(context, result) {
-	if (context.mode !== void 0) return context.mode === "dynamic";
-	if (result instanceof Promise) return true;
-	return Object.getOwnPropertySymbols(result).length === 0;
-}
-/**
-* Collects annotations from all contexts synchronously.
+* `single-pass` contexts reuse their phase-1 snapshot. `two-pass` contexts
+* are recollected with the parsed value and replace their own phase-1
+* snapshot in the final merge.
 *
 * @param contexts Source contexts to collect annotations from.
+* @param phase1Snapshots Per-context snapshots collected during phase 1.
 * @param parsed Optional parsed result from a previous parse pass.
 * @param options Optional context-required options to pass to each context.
 * @returns Merged annotations.
 * @throws Error if any context returns a Promise.
 */
-function collectAnnotationsSync(contexts, parsed, options, deferred, deferredKeys) {
+function collectFinalAnnotationsSync(contexts, phase1Snapshots, parsed, options, deferred, deferredKeys) {
 	const annotationsList = [];
 	const preparedParsed = prepareParsedForContexts(parsed, deferred, deferredKeys);
-	for (const context of contexts) {
+	for (let index = 0; index < contexts.length; index++) {
+		const context = contexts[index];
+		if (context.phase === "single-pass") {
+			annotationsList.push(phase1Snapshots[index]);
+			continue;
+		}
 		const mergedAnnotations = withPreparedParsedForContext(context, preparedParsed, (contextParsed) => {
 			const result = context.getAnnotations(contextParsed, options);
 			if (result instanceof Promise) throw new Error(`Context ${String(context.id)} returned a Promise in sync mode. Use runWith() or runWithAsync() for async contexts.`);
@@ -1188,16 +1206,7 @@ function collectAnnotationsSync(contexts, parsed, options, deferred, deferredKey
 		});
 		annotationsList.push(mergedAnnotations);
 	}
-	return {
-		annotations: mergeAnnotations(annotationsList),
-		annotationsList
-	};
-}
-function mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList) {
-	const mergedPerContext = [];
-	const length = Math.max(phase1AnnotationsList.length, phase2AnnotationsList.length);
-	for (let i = 0; i < length; i++) mergedPerContext.push(mergeAnnotations([phase2AnnotationsList[i] ?? {}, phase1AnnotationsList[i] ?? {}]));
-	return mergeAnnotations(mergedPerContext);
+	return { annotations: mergeAnnotations(annotationsList) };
 }
 /**
 * Disposes all contexts that implement `AsyncDisposable` or `Disposable`.
@@ -1242,12 +1251,13 @@ function disposeContextsSync(contexts) {
 */
 async function runWithBody(parser, programName, contexts, args, options) {
 	validateContextIds(contexts);
+	validateContextPhases(contexts);
 	if (needsEarlyExit(args, options)) {
 		if (parser.$mode === "async") return runParser(parser, programName, args, options);
 		return Promise.resolve(runParser(parser, programName, args, options));
 	}
 	const ctxOptions = options.contextOptions;
-	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = await collectPhase1Annotations(contexts, ctxOptions);
+	const { annotations: phase1Annotations, needsTwoPhase, snapshots: phase1Snapshots } = await collectPhase1Annotations(contexts, ctxOptions);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
@@ -1260,8 +1270,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 		if (parser.$mode === "async") return runParser(augmentedParser, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser, programName, args, options));
 	}
-	const { annotationsList: phase2AnnotationsList } = await collectAnnotations(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
-	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const { annotations: finalAnnotations } = await collectFinalAnnotations(contexts, phase1Snapshots, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	if (parser.$mode === "async") return runParser(augmentedParser2, programName, args, options);
 	return Promise.resolve(runParser(augmentedParser2, programName, args, options));
@@ -1269,26 +1278,28 @@ async function runWithBody(parser, programName, contexts, args, options) {
 /**
 * Runs a parser with multiple source contexts.
 *
-* This function automatically handles static and dynamic contexts with proper
-* priority. Earlier contexts in the array override later ones.
+* This function automatically handles single-pass and two-pass contexts with
+* proper priority. Earlier contexts in the array override later ones.
 *
 * The function uses a smart two-phase approach:
 *
-* 1. *Phase 1*: Collect annotations from all contexts (static contexts return
-*    their data, dynamic contexts may return empty).
+* 1. *Phase 1*: Collect annotations from all contexts.
 * 2. *First parse*: Parse with Phase 1 annotations. If that pass finishes
 *    successfully, its value becomes the phase-two input. If the parser
 *    reaches a usable intermediate state but still does not complete
 *    successfully, the runner extracts a best-effort seed from that state
 *    instead.
-* 3. *Phase 2*: Call `getAnnotations(parsed)` on all contexts with the first
-*    pass value. Deferred or otherwise unresolved fields in `parsed` may be
-*    `undefined`.
-* 4. *Second parse*: Parse again with merged annotations from both phases.
+* 3. *Phase 2*: Call `getAnnotations(parsed)` on all two-pass contexts with
+*    the first pass value. Deferred or otherwise unresolved fields in
+*    `parsed` may be `undefined`. Each two-pass context's phase-two return
+*    value replaces its own phase-one contribution for the final parse, so
+*    returning `{}` clears any annotations that context provided during
+*    phase 1. Single-pass contexts reuse their phase-one snapshot.
+* 4. *Second parse*: Parse again with the merged phase-two annotations.
 *
-* If all contexts are static (no dynamic contexts), the second parse is
-* skipped for optimization. Phase 2 is also skipped when the first pass does
-* not yield any usable seed at all.
+* If all contexts are single-pass, the second parse is skipped for
+* optimization. Phase 2 is also skipped when the first pass does not yield
+* any usable seed at all.
 *
 * @template TParser The parser type.
 * @template THelp Return type when help is shown.
@@ -1300,6 +1311,8 @@ async function runWithBody(parser, programName, contexts, args, options) {
 * @returns Promise that resolves to the parsed result.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.
+* @throws {TypeError} If any context omits `phase` or declares an invalid
+* phase value.
 * @throws {SuppressedError} If the runner throws and a context's disposal
 * also throws.  The original error is available via `.suppressed` and the
 * disposal error via `.error`.
@@ -1312,6 +1325,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 *
 * const envContext: SourceContext = {
 *   id: Symbol.for("@myapp/env"),
+*   phase: "single-pass",
 *   getAnnotations() {
 *     return { [Symbol.for("@myapp/env")]: process.env };
 *   }
@@ -1355,9 +1369,10 @@ async function runWith(parser, programName, contexts, options) {
 */
 function runWithSyncBody(parser, programName, contexts, args, options) {
 	validateContextIds(contexts);
+	validateContextPhases(contexts);
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	const ctxOptions = options.contextOptions;
-	const { annotations: phase1Annotations, annotationsList: phase1AnnotationsList, hasDynamic: needsTwoPhase } = collectPhase1AnnotationsSync(contexts, ctxOptions);
+	const { annotations: phase1Annotations, needsTwoPhase, snapshots: phase1Snapshots } = collectPhase1AnnotationsSync(contexts, ctxOptions);
 	if (!needsTwoPhase) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		return runParser(augmentedParser, programName, args, options);
@@ -1368,8 +1383,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 		const augmentedParser = injectAnnotationsIntoParser(parser, phase1Annotations);
 		return runParser(augmentedParser, programName, args, options);
 	}
-	const { annotationsList: phase2AnnotationsList } = collectAnnotationsSync(contexts, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
-	const finalAnnotations = mergeTwoPhaseAnnotations(phase1AnnotationsList, phase2AnnotationsList);
+	const { annotations: finalAnnotations } = collectFinalAnnotationsSync(contexts, phase1Snapshots, firstPassSeed.value, ctxOptions, firstPassSeed.deferred, firstPassSeed.deferredKeys);
 	const augmentedParser2 = injectAnnotationsIntoParser(parser, finalAnnotations);
 	return runParser(augmentedParser2, programName, args, options);
 }
@@ -1378,8 +1392,10 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 *
 * This is the sync-only variant of {@link runWith}. All contexts must return
 * annotations synchronously (not Promises). It uses the same two-phase
-* best-effort seed extraction as {@link runWith} when dynamic contexts are
-* present.
+* best-effort seed extraction as {@link runWith} when two-pass contexts are
+* present. In two-phase runs, each two-pass context's phase-two return value
+* replaces that context's phase-one contribution for the final parse, so
+* returning `{}` clears any annotations that context provided during phase 1.
 *
 * @template TParser The sync parser type.
 * @template THelp Return type when help is shown.
@@ -1393,6 +1409,8 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 * {@link runWith} or {@link runWithAsync} for async parsers.
 * @throws {TypeError} If two or more contexts share the same
 * {@link SourceContext.id}.
+* @throws {TypeError} If any context omits `phase` or declares an invalid
+* phase value.
 * @throws {Error} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
 * @throws {SuppressedError} If the runner throws and a context's disposal

package/dist/parser.d.cts

@@ -215,7 +215,7 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * A type-appropriate default value used as a stand-in during deferred
    * prompt resolution.  When present, combinators like `prompt()` use this
    * value instead of an internal sentinel during two-phase parsing, so that
-   * `map()` transforms and dynamic contexts always receive a valid value
+   * `map()` transforms and two-pass contexts always receive a valid value
    * of type {@link TValue}.
    *
    * This property is set automatically by `option()` and `argument()` from

package/dist/parser.d.ts

@@ -215,7 +215,7 @@ interface Parser<M extends Mode = "sync", TValue = unknown, TState = unknown> {
    * A type-appropriate default value used as a stand-in during deferred
    * prompt resolution.  When present, combinators like `prompt()` use this
    * value instead of an internal sentinel during two-phase parsing, so that
-   * `map()` transforms and dynamic contexts always receive a valid value
+   * `map()` transforms and two-pass contexts always receive a valid value
    * of type {@link TValue}.
    *
    * This property is set automatically by `option()` and `argument()` from

package/dist/valueparser.d.cts

@@ -100,7 +100,7 @@ interface ValueParser<M extends Mode = "sync", T = unknown> {
    * A type-appropriate default value used as a stand-in during deferred
    * prompt resolution.  When an interactive prompt is deferred during
    * two-phase parsing, this value is used instead of an internal sentinel
-   * so that `map()` transforms and dynamic contexts always receive a valid
+   * so that `map()` transforms and two-pass contexts always receive a valid
    * value of type {@link T}.
    *
    * The placeholder does not need to be meaningful; it only needs to be

package/dist/valueparser.d.ts

@@ -100,7 +100,7 @@ interface ValueParser<M extends Mode = "sync", T = unknown> {
    * A type-appropriate default value used as a stand-in during deferred
    * prompt resolution.  When an interactive prompt is deferred during
    * two-phase parsing, this value is used instead of an internal sentinel
-   * so that `map()` transforms and dynamic contexts always receive a valid
+   * so that `map()` transforms and two-pass contexts always receive a valid
    * value of type {@link T}.
    *
    * The placeholder does not need to be meaningful; it only needs to be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1799+bc120a8c",
+  "version": "1.0.0-dev.1802+accfecbe",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",