/**
 * Container — dependency injection with explicit bind / override / decorate.
 *
 * Invariants:
 *   bind()     — throws if token already bound
 *   override() — throws if nothing to replace
 *   decorate() — stacks; cached value cleared on register
 */
export type Token<T> = symbol & {
    readonly __type?: T;
};
export type Factory<T> = (c: Container) => T;
export type Decorator<T> = (inner: T, c: Container) => T;
export interface BindOptions {
    singleton?: boolean | undefined;
    owner?: string | undefined;
}
export declare class Container {
    private readonly entries;
    /**
     * Tokens currently mid-resolve. Tracked so we can detect circular
     * dependencies (A → B → A) and throw a structured error instead of
     * overflowing the call stack with "Maximum call stack size exceeded".
     *
     * Not a memoization cache — the per-entry `cache` field is the source
     * of truth for "have I built this before?". This set only lives for
     * the duration of a single resolve call.
     */
    private readonly resolving;
    bind<T>(token: Token<T>, factory: Factory<T>, opts?: BindOptions): void;
    override<T>(token: Token<T>, factory: Factory<T>, opts?: BindOptions): void;
    decorate<T>(token: Token<T>, decorator: Decorator<T>, owner?: string): void;
    resolve<T>(token: Token<T>): T;
    /**
     * Build a human-readable description of the dependency cycle that
     * caused the resolution to re-enter. Lists the tokens in the order
     * they were entered, then appends the re-entered token to close the
     * loop. Falls back to a generic message if the resolving set is
     * somehow empty (shouldn't happen, but defensive).
     */
    private describeCycle;
    has<T>(token: Token<T>): boolean;
    /**
     * Resolve a token if it is bound, otherwise return undefined.
     * Unlike `resolve()`, this does not throw if the token is unbound.
     *
     * Single map lookup — `has()` + `resolve()` would walk the entries
     * map twice. The bound check is folded into the resolve path so a
     * non-existent token can never enter the `resolving` cycle-detection
     * set.
     */
    safeResolve<T>(token: Token<T>): T | undefined;
    ownerOf<T>(token: Token<T>): string | undefined;
    /**
     * Remove a token's binding (along with any decorators stacked on it).
     * Returns true if the token existed. Use this to withdraw temporary
     * bindings installed by a short-lived run or plugin — without it, the
     * entry persists in the map forever.
     */
    unbind<T>(token: Token<T>): boolean;
    /**
     * Drop every binding. Intended for tests and short-lived CLI invocations
     * that rebuild the container from scratch. Production code should prefer
     * `unbind` on the specific tokens it owns.
     */
    clear(): void;
    list(): Array<{
        token: symbol;
        owner: string;
    }>;
    /**
     * Inspect a binding's full shape, including decorator count and whether
     * a singleton value is cached. Returns null if the token is unbound.
     * Decorator and factory function references are not exposed — only counts
     * and metadata, to keep internal state hidden.
     */
    inspect<T>(token: Token<T>): {
        owner: string;
        singleton: boolean;
        decoratorCount: number;
        cached: boolean;
    } | null;
}
//# sourceMappingURL=container.d.ts.map