import { type PluginId } from '@zhin.js/plugin-runtime';
import type { RuntimeEnvironment } from './environment.js';
export type EnvironmentSource = Readonly<Record<string, string | undefined>>;
export interface EnvironmentLayers {
    readonly base?: EnvironmentSource;
    readonly environments?: Readonly<Record<string, EnvironmentSource>>;
    readonly plugins?: Readonly<Record<string, EnvironmentSource>>;
}
/** Reloadable authority for environment layers and their watched files. */
export interface EnvironmentLayersPort {
    readonly sources: readonly string[];
    read(): Promise<EnvironmentLayers>;
}
export interface EnvSchema<T> {
    readonly secretKeys?: readonly string[];
    parse(source: EnvironmentSource): T;
}
export interface EnvStore {
    readonly owner: PluginId;
    readonly environment: RuntimeEnvironment;
    has(key: string): boolean;
    get(key: string): string | undefined;
    require(key: string): string;
    parse<T>(schema: EnvSchema<T>): Readonly<T>;
    /** Strict expansion: missing keys throw `EnvironmentVariableMissingError`. */
    expand<T>(value: T): T;
    /**
     * Config-document expansion for Root compose.
     * Missing keys become `""` so adapters that require credentials soft-fail at
     * create instead of treating literal `${VAR}` as a real token.
     */
    expandMissingAsEmpty<T>(value: T): T;
    redact(value: unknown, secretKeys: readonly string[]): unknown;
}
export declare const envStoreToken: import("@zhin.js/plugin-runtime").Token<EnvStore>;
export declare class EnvironmentVariableMissingError extends Error {
    readonly owner: PluginId;
    readonly key: string;
    constructor(owner: PluginId, key: string);
}
export declare class EnvSchemaParseError extends Error {
    readonly owner: PluginId;
    constructor(owner: PluginId, message: string);
}
/**
 * The PluginGraph owner path is the sole namespace for Plugin overlays.
 * Package names and bare instance keys are deliberately not accepted as
 * aliases: a layer for `root/a` can flow only to `root/a` and descendants.
 */
export declare function environmentOwnerPath(owner: PluginId): readonly PluginId[];
export declare function defineEnvSchema<T>(schema: EnvSchema<T>): Readonly<EnvSchema<T>>;
export declare function defineEnvironmentLayers(layers?: EnvironmentLayers): Readonly<EnvironmentLayers>;
export declare function createEnvStore(owner: PluginId, environment: RuntimeEnvironment, layers?: EnvironmentLayers): EnvStore;
/** Normalizes layers once, then derives immutable stores for each Plugin owner. */
export declare class EnvStoreFactory {
    #private;
    constructor(environment: RuntimeEnvironment, layers?: EnvironmentLayers);
    create(owner: PluginId): EnvStore;
}
/**
 * Standalone deep expansion over an arbitrary config value (e.g. a raw `ai`
 * config document before EnvStore scoping exists). Supports `${VAR}` and
 * `${VAR:-default}` / `${VAR:=default}` (default applies when the variable is
 * unset or empty). Missing plain references resolve via `onMissing`
 * (default: `""`, matching `EnvStore.expandMissingAsEmpty`).
 */
export declare function expandEnvironmentValue<T>(value: T, lookup: (key: string) => string | undefined, onMissing?: (key: string) => string): T;