/**
 * Convenience wrapper around `resolveEnvConfig()` for tools that need to read
 * cluster identifiers (offload bucket, SIEM vendor, retriever endpoint, queue
 * URLs) but DON'T already know which env they're talking about.
 *
 * The four tools that historically read these from process.env directly —
 * retriever-probe, configure-engine, doctor, advise-retriever — share the same
 * shape: pick a single resolved env document if one exists, fall through to
 * LOG10X_* env vars if not, and surface any disagreement between the two as
 * a warning the caller can append to envelope.warnings.
 *
 * Precedence chain (per resolver.ts):
 *
 *   explicit-arg > on-prem-store > env-var fallback > fail-loudly
 *
 * StoreKind discovery order:
 *
 *   K8s > AWS SSM > GCP Secret Manager > Azure App Configuration > Local File
 *
 * Each store reports `isAvailable: false` on a host that lacks the underlying
 * cloud, so instantiating all five eagerly is safe.
 */
import { type ResolveResult } from './resolver.js';
import type { EnvConfigStore } from './store-interface.js';
import type { EnvironmentConfig, OffloadDestination } from './types.js';
export interface ClusterConfigResolveOptions {
    /**
     * env_id or nickname to resolve. When undefined, tries — in order — the
     * `LOG10X_ENV_ID` env var, `LOG10X_ENV_NICKNAME` env var, and then `default`
     * as the well-known dev fallback. The resolver will throw if none of those
     * match a stored document AND env-var fallback can't satisfy the schema.
     */
    envIdOrNickname?: string;
    /**
     * Explicit document override. When the caller already has a fully-populated
     * EnvironmentConfig (e.g. just wrote it), pass it here to skip lookup.
     */
    explicit?: EnvironmentConfig;
    /**
     * Override the store chain. Used in tests. Production callers should pass
     * undefined to get the default K8s → SSM → GCP SM → Azure AC → Local order.
     */
    stores?: EnvConfigStore[];
}
export interface ClusterConfigResolveSuccess {
    ok: true;
    config: EnvironmentConfig;
    source: ResolveResult['source'];
    source_store_kind?: ResolveResult['source_store_kind'];
    /**
     * One warning per env-var field that disagrees with the on-prem store's
     * value. Callers should append these to envelope.warnings so users see
     * the stale-env-var nudge instead of debugging "but I set the env var".
     */
    stale_env_var_warnings: string[];
    /**
     * One step per store the resolver tried, in order. Useful for surfacing a
     * "I read this env from <store>" line in doctor / debug envelopes.
     */
    resolution_trace: ResolveResult['resolution_trace'];
    /**
     * The envIdOrNickname the caller originally asked for (if any), preserved
     * so callers can compare against the resolved config.env_id and surface
     * "you asked for X, we resolved Y" when they disagree. Undefined when no
     * explicit id was passed (i.e. the caller wanted whatever was discoverable).
     */
    requested_env_id_or_nickname?: string;
    /**
     * Soft warnings about the resolution itself (e.g. on-prem doc existed for
     * the requested id but was corrupt and we fell through to env-var fallback).
     * Distinct from `stale_env_var_warnings`, which is per-field disagreement.
     */
    resolution_warnings: string[];
}
export interface ClusterConfigResolveFailure {
    ok: false;
    error: string;
    resolution_trace: ResolveResult['resolution_trace'];
    /**
     * The envIdOrNickname the caller originally asked for, so a failure can
     * say "you asked for X" rather than dumping the (possibly synthetic)
     * candidate chain.
     */
    requested_env_id_or_nickname?: string;
    /**
     * Soft warnings about the resolution attempt (e.g. on-prem doc was present
     * but unparseable for the requested id). These name the failure mode so
     * callers don't have to grep the trace.
     */
    resolution_warnings: string[];
}
export type ClusterConfigResolveResult = ClusterConfigResolveSuccess | ClusterConfigResolveFailure;
/**
 * Default store chain in discovery order. Each store's `isAvailable` cheaply
 * checks for the underlying cloud (kubeconfig, AWS creds, GCP project, Azure
 * connection string, $HOME). The chain falls through on the first available
 * store that has a document for the requested env.
 */
export declare function defaultClusterConfigStoreChain(): EnvConfigStore[];
/**
 * Resolve an env-config document by walking the precedence chain. Returns a
 * tagged result so callers can attach the trace and warnings to their own
 * envelope without an exception-driven control flow.
 *
 * Note: only the FIRST candidate id that successfully resolves wins. We don't
 * union across stores or candidates — config is authoritative per env_id.
 */
export declare function resolveClusterConfig(opts?: ClusterConfigResolveOptions): Promise<ClusterConfigResolveResult>;
/**
 * Pick the single active offload destination from a resolved env-config.
 * The schema allows multiple — `status: "active"` is the runtime selector;
 * `draining` / `archived` / `failed` are bookkeeping states the Receiver
 * does NOT route new writes to.
 *
 * Returns the first active entry. Multi-active is a documented (multi-target
 * offload) use case; callers that care about all of them should iterate
 * `config.offload_destinations` directly.
 */
export declare function pickActiveOffload(config: EnvironmentConfig): OffloadDestination | undefined;
/**
 * Structured signal about whether multiple offload destinations are marked
 * `status: 'active'`. Consumers like retriever_probe call this to surface a
 * warning when the caller's intent (which active bucket?) is ambiguous: the
 * runtime picker (`pickActiveOffload`) silently picks the first match, which
 * is fine for the receiver but surprising for tools that print "the offload
 * bucket" in their envelope.
 *
 * Shape contract:
 *   - `multi_active` is true iff `active_count >= 2`.
 *   - `active_nicknames` is in array order (the same order `pickActiveOffload`
 *     walks), so `picked` is always `active_nicknames[0]` when non-empty.
 *   - `picked` is the empty string when zero destinations are active — callers
 *     that want a typed optional should branch on `active_count === 0`.
 *
 * Does NOT change `pickActiveOffload`'s behavior; this is a read-only
 * diagnostic over the same array.
 */
export interface MultiActiveOffloadSignal {
    multi_active: boolean;
    active_count: number;
    active_nicknames: string[];
    picked: string;
}
export declare function detectMultiActiveOffload(config: EnvironmentConfig): MultiActiveOffloadSignal;
/**
 * Compare a resolved env-config's offload bucket to `process.env.LOG10X_STREAMER_BUCKET`
 * / `process.env.LOG10X_OFFLOAD_BUCKET` and return a warning when they
 * disagree. Tools that fall back to env vars (retriever_probe, advise_retriever,
 * doctor) should append this to envelope.warnings so the user sees the stale
 * env var instead of silently going with the store value.
 */
export declare function detectStaleOffloadEnvVar(resolvedBucket: string | undefined): string | undefined;
/**
 * Same idea as detectStaleOffloadEnvVar, generalised over arbitrary
 * (label, resolved, envVar) triples. Returns one warning per disagreeing
 * pair; empty array when everything agrees or nothing is set.
 */
export declare function detectStaleEnvVarForField(label: string, resolvedValue: string | undefined, envVarName: string): string | undefined;