import type { Token } from './token.js';
export type Lifetime = 'singleton' | 'scoped' | 'transient';
export type Factory<T> = (container: Container) => T;
/**
 * Hierarchical DI container.
 *
 * - `singleton`: one instance per application (stored in the container that owns the binding)
 * - `scoped`: one instance per scope (e.g. per request), created in the leaf container
 * - `transient`: new instance on every resolution
 */
export declare class Container {
    private readonly parent?;
    private readonly bindings;
    private readonly singletons;
    private readonly scopedInstances;
    /** Resolution stack for cycle detection — keyed by token symbol, not description. */
    private readonly resolving;
    /**
     * How many `singleton` builds are in flight on this container — O(1),
     * allocation-free guard for captive dependencies (a scoped resolution while
     * this is > 0 would be memoized into a singleton that outlives the scope).
     */
    private singletonBuilds;
    /** Dependency-graph recorder (devtools) — only set on the root once enabled. */
    private graphRecorder?;
    constructor(parent?: Container | undefined);
    register<T>(token: Token<T>, factory: Factory<T>, lifetime?: Lifetime): this;
    singleton<T>(token: Token<T>, factory: Factory<T>): this;
    scoped<T>(token: Token<T>, factory: Factory<T>): this;
    transient<T>(token: Token<T>, factory: Factory<T>): this;
    has<T>(token: Token<T>): boolean;
    get<T>(token: Token<T>): T;
    /** Creates a child scope (e.g. per request). Bindings are inherited; scoped instances are not. */
    createScope(): Container;
    private build;
    /** Description of the innermost in-flight singleton build (error path only). */
    private enclosingSingleton;
    private findBinding;
    /** Enable dependency-graph recording (off by default — zero overhead otherwise). */
    enableGraph(): this;
    private recorder;
    /**
     * The dependency graph observed **so far** — every `A depends on B` edge seen
     * during resolution since `enableGraph()`. Passive: it records real
     * resolutions and never forces eager construction.
     */
    dependencyGraph(): DependencyGraph;
    /** Static snapshot of every reachable binding — token, lifetime, and whether it's been built. */
    describe(): BindingInfo[];
}
export interface BindingInfo {
    token: string;
    lifetime: Lifetime;
    instantiated: boolean;
}
export interface DependencyGraph {
    nodes: {
        token: string;
        lifetime: Lifetime;
    }[];
    edges: {
        from: string;
        to: string;
    }[];
}