@optique/core 1.3.0-dev.2398 → 1.3.0-dev.2401

package/dist/dependency-runtime.d.cts

@@ -7,6 +7,29 @@ import { ExecutionContext } from "./internal/parser.cjs";
 
 //#region src/dependency-runtime.d.ts
 
+/**
+ * Stores the raw token parsed by a derived value parser on structural parser
+ * states that can safely carry an in-band annotation.
+ *
+ * The execution trace remains the canonical diagnostic record.  This state
+ * marker lets construct-independent dependency resolution replay a derived
+ * source before downstream fields complete.
+ * @internal
+ * @since 1.3.0
+ */
+declare const derivedRawInputKey: unique symbol;
+/**
+ * Records a derived parser's raw token without modifying its parse result.
+ *
+ * Parse results may be frozen or carry class private state, so primitives keep
+ * their original identity and associate replay metadata out of band.
+ *
+ * @param state The original value parser result.
+ * @param rawInput The token parsed into that result.
+ * @internal
+ * @since 1.3.0
+ */
+declare function recordDerivedRawInput(state: object, rawInput: string): void;
 /**
  * A request to resolve one or more dependency values.
  *
@@ -89,6 +112,8 @@ interface RuntimeNode {
   };
   /** The parser's current state. */
   readonly state: unknown;
+  /** Raw input captured for a derived parser, when this node matched. */
+  readonly rawInput?: string;
   /**
    * Whether the parser consumed explicit input during parsing.
    * When `true`, the parser's state reflects user-provided input (which
@@ -142,6 +167,20 @@ interface RuntimeNode {
    */
   readonly requiresSourceId?: symbol;
 }
+/**
+ * Options for resolving matched derived source values.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface ResolveDerivedSourceValuesOptions {
+  /**
+   * Whether an unpopulated effectful source can still provide a value later.
+   * Suggestion generation sets this to `"inactive"` because it never runs
+   * effects and must let downstream parsers use declared dependency defaults.
+   */
+  readonly effectfulProviders?: "pending" | "inactive";
+}
 /**
  * The context handed to a {@link RuntimeNode.prepare} barrier.
  *
@@ -190,6 +229,15 @@ interface DependencyRuntimeContext {
    * defaults for failed sources.
    */
   markSourceFailed(sourceId: symbol): void;
+  /** Register a source's diagnostic label and upstream dependencies. */
+  registerSourceMetadata(sourceId: symbol, label: string, dependencyIds?: readonly symbol[]): void;
+  /**
+   * Propagate a failed upstream source through one derived dependency edge.
+   * Returns whether any upstream source had failed.
+   */
+  propagateSourceFailure(dependencyIds: readonly symbol[], label: string, sourceId?: symbol): boolean;
+  /** Return the most informative dependency chain for a failed source. */
+  getSourceFailureChain(sourceId: symbol): readonly string[] | undefined;
   /**
    * Check if a source was explicitly attempted but failed validation.
    */
@@ -242,6 +290,36 @@ declare function collectExplicitSourceValues(nodes: readonly RuntimeNode[], runt
  * @since 1.0.0
  */
 declare function collectExplicitSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<void>;
+/**
+ * Orders runtime nodes so every in-scope provider precedes a derived source
+ * that consumes it.  Independent nodes retain declaration order.
+ *
+ * Missing providers create no edge because the consumer may use its declared
+ * default.  Scheduling barriers act as providers for the source IDs their
+ * selected subtree may expose and depend on their discriminator source.
+ *
+ * @param nodes Runtime nodes in declaration order.
+ * @returns The same nodes in stable dependency order.
+ * @throws {TypeError} If active provider edges contain a cycle.
+ * @internal
+ * @since 1.3.0
+ */
+declare function orderDependencyNodes(nodes: readonly RuntimeNode[]): readonly RuntimeNode[];
+/** Resolves and publishes matched derived sources in stable dependency order. */
+declare function resolveDerivedSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): void;
+/** Async version of {@link resolveDerivedSourceValues}. */
+declare function resolveDerivedSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): Promise<void>;
+/**
+ * Appends the recorded dependency chain to a source failure.
+ *
+ * @param error The source failure to annotate.
+ * @param sourceId The identifier of the failed source.
+ * @param runtime The dependency runtime that recorded the failure chain.
+ * @returns The annotated failure, or the original failure when no chain exists.
+ * @internal
+ * @since 1.3.0
+ */
+declare function includeSourceFailureChain(error: Message, sourceId: symbol, runtime: DependencyRuntimeContext): Message;
 /**
  * Fills missing source defaults for source parsers whose state is
  * unpopulated.
@@ -616,4 +694,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };

package/dist/dependency-runtime.d.ts

@@ -7,6 +7,29 @@ import { ExecutionContext } from "./internal/parser.js";
 
 //#region src/dependency-runtime.d.ts
 
+/**
+ * Stores the raw token parsed by a derived value parser on structural parser
+ * states that can safely carry an in-band annotation.
+ *
+ * The execution trace remains the canonical diagnostic record.  This state
+ * marker lets construct-independent dependency resolution replay a derived
+ * source before downstream fields complete.
+ * @internal
+ * @since 1.3.0
+ */
+declare const derivedRawInputKey: unique symbol;
+/**
+ * Records a derived parser's raw token without modifying its parse result.
+ *
+ * Parse results may be frozen or carry class private state, so primitives keep
+ * their original identity and associate replay metadata out of band.
+ *
+ * @param state The original value parser result.
+ * @param rawInput The token parsed into that result.
+ * @internal
+ * @since 1.3.0
+ */
+declare function recordDerivedRawInput(state: object, rawInput: string): void;
 /**
  * A request to resolve one or more dependency values.
  *
@@ -89,6 +112,8 @@ interface RuntimeNode {
   };
   /** The parser's current state. */
   readonly state: unknown;
+  /** Raw input captured for a derived parser, when this node matched. */
+  readonly rawInput?: string;
   /**
    * Whether the parser consumed explicit input during parsing.
    * When `true`, the parser's state reflects user-provided input (which
@@ -142,6 +167,20 @@ interface RuntimeNode {
    */
   readonly requiresSourceId?: symbol;
 }
+/**
+ * Options for resolving matched derived source values.
+ *
+ * @internal
+ * @since 1.3.0
+ */
+interface ResolveDerivedSourceValuesOptions {
+  /**
+   * Whether an unpopulated effectful source can still provide a value later.
+   * Suggestion generation sets this to `"inactive"` because it never runs
+   * effects and must let downstream parsers use declared dependency defaults.
+   */
+  readonly effectfulProviders?: "pending" | "inactive";
+}
 /**
  * The context handed to a {@link RuntimeNode.prepare} barrier.
  *
@@ -190,6 +229,15 @@ interface DependencyRuntimeContext {
    * defaults for failed sources.
    */
   markSourceFailed(sourceId: symbol): void;
+  /** Register a source's diagnostic label and upstream dependencies. */
+  registerSourceMetadata(sourceId: symbol, label: string, dependencyIds?: readonly symbol[]): void;
+  /**
+   * Propagate a failed upstream source through one derived dependency edge.
+   * Returns whether any upstream source had failed.
+   */
+  propagateSourceFailure(dependencyIds: readonly symbol[], label: string, sourceId?: symbol): boolean;
+  /** Return the most informative dependency chain for a failed source. */
+  getSourceFailureChain(sourceId: symbol): readonly string[] | undefined;
   /**
    * Check if a source was explicitly attempted but failed validation.
    */
@@ -242,6 +290,36 @@ declare function collectExplicitSourceValues(nodes: readonly RuntimeNode[], runt
  * @since 1.0.0
  */
 declare function collectExplicitSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<void>;
+/**
+ * Orders runtime nodes so every in-scope provider precedes a derived source
+ * that consumes it.  Independent nodes retain declaration order.
+ *
+ * Missing providers create no edge because the consumer may use its declared
+ * default.  Scheduling barriers act as providers for the source IDs their
+ * selected subtree may expose and depend on their discriminator source.
+ *
+ * @param nodes Runtime nodes in declaration order.
+ * @returns The same nodes in stable dependency order.
+ * @throws {TypeError} If active provider edges contain a cycle.
+ * @internal
+ * @since 1.3.0
+ */
+declare function orderDependencyNodes(nodes: readonly RuntimeNode[]): readonly RuntimeNode[];
+/** Resolves and publishes matched derived sources in stable dependency order. */
+declare function resolveDerivedSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): void;
+/** Async version of {@link resolveDerivedSourceValues}. */
+declare function resolveDerivedSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext, options?: ResolveDerivedSourceValuesOptions): Promise<void>;
+/**
+ * Appends the recorded dependency chain to a source failure.
+ *
+ * @param error The source failure to annotate.
+ * @param sourceId The identifier of the failed source.
+ * @param runtime The dependency runtime that recorded the failure chain.
+ * @returns The annotated failure, or the original failure when no chain exists.
+ * @internal
+ * @since 1.3.0
+ */
+declare function includeSourceFailureChain(error: Message, sourceId: symbol, runtime: DependencyRuntimeContext): Message;
 /**
  * Fills missing source defaults for source parsers whose state is
  * unpopulated.
@@ -616,4 +694,4 @@ declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
   readonly initialState?: unknown;
 }>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };
+export { CompleteEffectfulSourcesOptions, DependencyRequest, DependencyResolution, DependencyRuntimeContext, EffectfulSchedulingNodesFn, EffectfulSourceCompletion, EffectfulSourceCompletionResult, ReplayKey, ResolveDerivedSourceValuesOptions, RuntimeNode, SchedulingBarrierContext, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectDemandedDependencyIds, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, completeEffectfulSourcesAsync, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, defineForwardedEffectfulSchedulingNodes, derivedRawInputKey, effectfulSchedulingNodesKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, includeSourceFailureChain, orderDependencyNodes, recordDerivedRawInput, replayDerivedParser, replayDerivedParserAsync, resolveDerivedSourceValues, resolveDerivedSourceValuesAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync, serializeSchedulingPath, sourceCollectionExpansionKey, staticSourceScopeKey };