import { DependencyRegistryLike } from "./registry-types.js";
import { ValueParserResult } from "./valueparser.js";
import { ParserDependencyMetadata } from "./dependency-metadata.js";

//#region src/dependency-runtime.d.ts

/**
 * The origin of a dependency source value.
 *
 * @internal
 * @since 1.0.0
 */
type DependencyValueOrigin = "cli" | "default" | "config" | "env" | "prompt" | "derived-precomplete";
/**
 * A request to resolve one or more dependency values.
 *
 * @internal
 * @since 1.0.0
 */
interface DependencyRequest {
  /** The dependency source IDs to resolve. */
  readonly dependencyIds: readonly symbol[];
  /** Optional default values (one per ID) for missing sources. */
  readonly defaultValues?: readonly unknown[];
}
/**
 * The result of a dependency resolution request.
 *
 * @internal
 * @since 1.0.0
 */
interface DependencyResolution {
  /**
   * - `"resolved"`: all dependency values are available.
   * - `"partial"`: some are available, some are missing.
   * - `"missing"`: none are available.
   */
  readonly kind: "resolved" | "partial" | "missing";
  /** The resolved values (one per requested ID, `undefined` for missing). */
  readonly values: readonly unknown[];
  /** For each position, whether the value came from a default. */
  readonly usedDefaults: readonly boolean[];
}
/**
 * A failure that occurred while evaluating a missing-source default.
 * Returned by `fillMissingSourceDefaults()` so the caller can propagate
 * the error instead of silently treating the source as absent.
 *
 * @internal
 * @since 1.0.0
 */
interface SourceDefaultFailure {
  /** The source that failed. */
  readonly sourceId: symbol;
  /** The path of the node. */
  readonly path: readonly PropertyKey[];
  /** The failed result or error message. */
  readonly error: ValueParserResult<unknown>;
}
/**
 * A key for caching replayed parse results.
 *
 * @internal
 * @since 1.0.0
 */
interface ReplayKey {
  /** Path from root to the parser node. */
  readonly path: readonly PropertyKey[];
  /** The raw input string that was parsed. */
  readonly rawInput: string;
  /** A stable fingerprint of the dependency values used. */
  readonly dependencyFingerprint: string;
  /**
   * A per-parser identity string that disambiguates different derived
   * parsers sharing the same path (e.g., alternative branches).
   * @since 1.0.0
   */
  readonly parserFingerprint: string;
}
/**
 * A runtime node representing a child parser's position, metadata, and state.
 * Used as input to the shared runtime helpers.
 *
 * @internal
 * @since 1.0.0
 */
interface RuntimeNode {
  /** Path from root to this parser node. */
  readonly path: readonly PropertyKey[];
  /** The parser (only the metadata field is inspected). */
  readonly parser: {
    readonly dependencyMetadata?: ParserDependencyMetadata;
  };
  /** The parser's current state. */
  readonly state: unknown;
  /**
   * Whether the parser consumed explicit input during parsing.
   * When `true`, the parser's state reflects user-provided input (which
   * may have failed validation).  Missing-source defaults must not override
   * explicit parse failures.
   * @since 1.0.0
   */
  readonly matched?: boolean;
  /**
   * Snapshotted default dependency values for derived parsers.
   * Constructs should populate this at node creation time (once) to
   * avoid re-evaluating dynamic `getDefaultDependencyValues()` thunks
   * at replay time.
   * @since 1.0.0
   */
  readonly defaultDependencyValues?: readonly unknown[];
}
/**
 * Dependency runtime context for centralized dependency resolution.
 *
 * @internal
 * @since 1.0.0
 */
interface DependencyRuntimeContext {
  /** The underlying registry (for bridge interop). */
  readonly registry: DependencyRegistryLike;
  /** Register a source value with its origin. */
  registerSource(sourceId: symbol, value: unknown, origin: DependencyValueOrigin): void;
  /** Check if a source has been registered. */
  hasSource(sourceId: symbol): boolean;
  /** Get a registered source value. */
  getSource(sourceId: symbol): unknown;
  /** Resolve dependency values for a request. */
  resolveDependencies(request: DependencyRequest): DependencyResolution;
  /** Get a cached replay result. */
  getReplayResult(key: ReplayKey): ValueParserResult<unknown> | undefined;
  /** Cache a replay result. */
  setReplayResult(key: ReplayKey, result: ValueParserResult<unknown>): void;
  /**
   * Mark a source as explicitly failed (user provided input that did
   * not pass validation).  Derived parsers should not fall back to
   * defaults for failed sources.
   */
  markSourceFailed(sourceId: symbol): void;
  /**
   * Check if a source was explicitly attempted but failed validation.
   */
  isSourceFailed(sourceId: symbol): boolean;
  /** Resolve dependencies for suggestions (same semantics as resolve). */
  getSuggestionDependencies(request: DependencyRequest): DependencyResolution;
}
/**
 * Creates a new {@link DependencyRuntimeContext}.
 *
 * @param registry Optional existing registry to wrap for bridge interop.
 * @returns A new runtime context.
 * @internal
 * @since 1.0.0
 */
declare function createDependencyRuntimeContext(registry?: DependencyRegistryLike): DependencyRuntimeContext;
/**
 * Creates a stable fingerprint from dependency values.
 *
 * @param values The dependency values to fingerprint.
 * @returns A string fingerprint.
 * @internal
 * @since 1.0.0
 */
declare function createDependencyFingerprint(values: readonly unknown[]): string;
declare function createReplayKey(path: readonly PropertyKey[], rawInput: string, dependencyValues: readonly unknown[], replayParse?: Function): ReplayKey;
/**
 * Collects explicit source values from parser states and registers them
 * in the runtime context.
 *
 * @param nodes The runtime nodes to inspect.
 * @param runtime The dependency runtime context.
 * @throws Propagates synchronous errors thrown by `extractSourceValue()`.
 * @throws {TypeError} If `extractSourceValue()` returns a promise-like result.
 *         Use {@link collectExplicitSourceValuesAsync} when async source
 *         extraction is expected.
 * @internal
 * @since 1.0.0
 */
declare function collectExplicitSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): void;
/**
 * Async version of {@link collectExplicitSourceValues}.
 * Awaits async `extractSourceValue` results instead of rejecting
 * promise-like values as the synchronous variant does.
 *
 * @param nodes The runtime nodes to inspect.
 * @param runtime The dependency runtime context.
 * @throws Propagates errors thrown or rejected by `extractSourceValue()`.
 * @internal
 * @since 1.0.0
 */
declare function collectExplicitSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<void>;
/**
 * Fills missing source defaults for source parsers whose state is
 * unpopulated.
 *
 * Returns an array of failures for sources whose default evaluation
 * failed (either threw or returned `{ success: false }`).  The caller
 * should propagate these so that dependent parsers see the real error
 * instead of silently treating the source as absent.
 *
 * @param nodes The runtime nodes to inspect.
 * @param runtime The dependency runtime context.
 * @returns Failures from default evaluation (empty if all succeeded).
 * @throws {TypeError} If `getMissingSourceValue()` returns a promise-like
 *         result. Use {@link fillMissingSourceDefaultsAsync} when async
 *         default extraction is expected.
 * @internal
 * @since 1.0.0
 */
declare function fillMissingSourceDefaults(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): readonly SourceDefaultFailure[];
/**
 * Async version of {@link fillMissingSourceDefaults}.
 * Awaits async `getMissingSourceValue` results.
 *
 * @param nodes The runtime nodes to inspect.
 * @param runtime The dependency runtime context.
 * @returns Failures from default evaluation (empty if all succeeded).
 * @internal
 * @since 1.0.0
 */
declare function fillMissingSourceDefaultsAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<readonly SourceDefaultFailure[]>;
/**
 * Replays a derived parser with resolved dependency values (sync).
 *
 * Returns `undefined` if dependencies cannot be resolved.
 *
 * @param node The runtime node with derived metadata.
 * @param rawInput The raw input to replay.
 * @param runtime The dependency runtime context.
 * @returns The replay result, or `undefined`.
 * @throws {TypeError} If `replayParse()` returns a promise-like result.
 *         Use {@link replayDerivedParserAsync} for async replay.
 * @internal
 * @since 1.0.0
 */
declare function replayDerivedParser(node: RuntimeNode, rawInput: string, runtime: DependencyRuntimeContext): ValueParserResult<unknown> | undefined;
/**
 * Replays a derived parser with resolved dependency values (async).
 *
 * Returns `undefined` if dependencies cannot be resolved.
 *
 * @param node The runtime node with derived metadata.
 * @param rawInput The raw input to replay.
 * @param runtime The dependency runtime context.
 * @returns The replay result, or `undefined`.
 * @internal
 * @since 1.0.0
 */
declare function replayDerivedParserAsync(node: RuntimeNode, rawInput: string, runtime: DependencyRuntimeContext): Promise<ValueParserResult<unknown> | undefined>;
/**
 * Extracts `rawInput` from a parser state that may contain a
 * {@link DeferredParseState}.  During the transition period, primitives
 * still produce `DeferredParseState` with `rawInput`.
 *
 * Handles direct `DeferredParseState` and array-wrapped
 * `[DeferredParseState]` (from optional/withDefault wrappers).
 *
 * @param state The parser state to inspect.
 * @returns The raw input string, or `undefined` if the state does not
 *   contain a `DeferredParseState`.
 * @internal
 * @since 1.0.0
 */
declare function extractRawInputFromState(state: unknown): string | undefined;
/**
 * Recursively collects dependency source values from {@link DependencySourceState}
 * objects found in the state tree and registers them in the runtime.
 *
 * This must run BEFORE deferred resolution so that all source values
 * are available when replaying derived parsers.
 *
 * @param state The state tree to traverse.
 * @param runtime The dependency runtime context to populate.
 * @param visited Cycle guard for recursive traversal.
 * @param excludedFields Optional property keys to skip at the current level.
 *                       This exclusion set is not propagated recursively.
 */
declare function collectSourcesFromState(state: unknown, runtime: DependencyRuntimeContext, visited?: WeakSet<object>, excludedFields?: ReadonlySet<PropertyKey>): void;
/**
 * Recursively resolves all {@link DeferredParseState} objects in a state
 * tree using the dependency runtime (sync).
 *
 * Performs a two-pass traversal:
 *  1. Collect all {@link DependencySourceState} values into the runtime.
 *  2. Resolve all {@link DeferredParseState} using the populated runtime.
 *
 * This replaces the old `resolveDeferredParseStates` with runtime-based
 * resolution.  Only traverses plain objects and arrays; class instances
 * and primitives are returned as-is.
 *
 * @param state The state tree to resolve.
 * @param runtime The dependency runtime context.
 * @returns The resolved state tree.
 * @throws {TypeError} If a deferred parser returns a promise-like result from
 *         `parseWithDependency()`. Use {@link resolveStateWithRuntimeAsync}
 *         for async resolution.
 * @internal
 * @since 1.0.0
 */
declare function resolveStateWithRuntime(state: unknown, runtime: DependencyRuntimeContext): unknown;
/**
 * Async version of {@link resolveStateWithRuntime}.
 *
 * @param state The state tree to resolve.
 * @param runtime The dependency runtime context.
 * @returns The resolved state tree.
 * @internal
 * @since 1.0.0
 */
declare function resolveStateWithRuntimeAsync(state: unknown, runtime: DependencyRuntimeContext): Promise<unknown>;
/**
 * Builds {@link RuntimeNode}s from field→parser pairs and a state record.
 *
 * Used by `object()` and `merge()` constructs.
 *
 * @param pairs Field→parser pairs.
 * @param state The state record keyed by field name.
 * @param parentPath Optional parent path prefix.
 * @returns An array of runtime nodes.
 * @internal
 * @since 1.0.0
 */
declare function buildRuntimeNodesFromPairs(pairs: ReadonlyArray<readonly [PropertyKey, {
  readonly dependencyMetadata?: ParserDependencyMetadata;
  readonly initialState?: unknown;
}]>, state: Record<PropertyKey, unknown>, parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
/**
 * Builds {@link RuntimeNode}s from a parser array and a state array.
 *
 * Used by `tuple()` and `concat()` constructs.
 *
 * @param parsers The child parsers.
 * @param stateArray The state array (one element per parser).
 * @param parentPath Optional parent path prefix.
 * @returns An array of runtime nodes.
 * @internal
 * @since 1.0.0
 */
declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
  readonly dependencyMetadata?: ParserDependencyMetadata;
  readonly initialState?: unknown;
}>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
//#endregion
export { DependencyRequest, DependencyResolution, DependencyRuntimeContext, DependencyValueOrigin, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };