/**
 * Environment config resolution.
 *
 * Precedence chain (first match wins):
 *
 *   1. **explicit_arg** — the caller already handed us a fully-populated
 *      EnvironmentConfig (e.g. tool argument override). Always wins.
 *   2. **on_prem_store** — walk the supplied list of stores in order, pick the
 *      first that reports `isAvailable` AND has a document for the requested
 *      env_id/nickname. This is the production path.
 *   3. **env_var_fallback** — a partial config built from LOG10X_* env vars.
 *      Only used when no store has the env. Must (a) name the requested env
 *      via `env_id` or `nickname` AND (b) satisfy the schema, or we fail
 *      loudly (no silent partials, and no silently substituting a
 *      different env's partial when the requested name typos through).
 *
 * Stale-env-var detection: if an on-prem store returned the config AND
 * LOG10X_* env vars are also set, we compare the overlapping fields and emit
 * a warning per disagreement. Users get noisy reminders to remove stale env
 * vars rather than silent "wait, which value won?" debugging.
 *
 * `resolution_trace` is returned for every call so tools can surface "I read
 * this env from <store kind>" in their envelope without re-running discovery.
 */
import { type EnvironmentConfig } from './types.js';
import type { EnvConfigStore, StoreKind } from './store-interface.js';
export interface ResolveOptions {
    envIdOrNickname: string;
    stores: EnvConfigStore[];
    /**
     * Pre-supplied config that bypasses store lookup entirely. Used when a
     * tool already has the full document in hand (e.g. just wrote it).
     */
    explicit?: EnvironmentConfig;
    /**
     * Partial document constructed from LOG10X_* env vars. Tried only when no
     * store yields a match.
     */
    envVarFallback?: Partial<EnvironmentConfig>;
}
export interface ResolutionTraceStep {
    source: string;
    status: 'matched' | 'skipped' | 'failed';
    reason: string;
}
export interface ResolveResult {
    config: EnvironmentConfig;
    source: 'explicit_arg' | 'on_prem_store' | 'env_var_fallback';
    source_store_kind?: StoreKind;
    stale_env_var_warnings: string[];
    resolution_trace: ResolutionTraceStep[];
}
export declare class EnvConfigResolutionError extends Error {
    readonly trace: ResolutionTraceStep[];
    constructor(message: string, trace: ResolutionTraceStep[]);
}
/**
 * Resolve an environment by id or nickname, walking the precedence chain.
 * Throws `EnvConfigResolutionError` (with the trace attached) when nothing
 * matches — never returns a partial.
 */
export declare function resolveEnvConfig(opts: ResolveOptions): Promise<ResolveResult>;