/**
 * Deprecation warning helpers for MCP tools.
 * Tracks and emits deprecation warnings with removal timelines.
 *
 * Coexists with `deprecation.ts` (different API):
 * - `deprecation.ts`: `emitDeprecationWarning({tool, replacement, deprecatedIn, removedIn})`
 * - `deprecation-helpers.ts`: `warnDeprecated({oldName, newName, removalVersion})`
 *
 * @module
 */
/**
 * Options for deprecation warnings.
 */
export interface WarnDeprecatedOptions {
    /** The deprecated tool/symbol name */
    oldName: string;
    /** The recommended replacement */
    newName: string;
    /** Version when removal is planned */
    removalVersion: string;
    /** Optional migration guide URL */
    migrationUrl?: string;
}
/**
 * Tracks which deprecation warnings have been emitted in this process.
 * Prevents log flooding from repeated calls.
 */
export declare class DeprecationRegistry {
    private readonly emitted;
    private readonly registry;
    /**
     * Register a known deprecation.
     */
    register(options: WarnDeprecatedOptions): void;
    /**
     * Emit a deprecation warning (only once per oldName per process).
     */
    warn(oldName: string): void;
    /**
     * Emit a warning and add to registry in one step.
     */
    warnOnce(options: WarnDeprecatedOptions): void;
    /**
     * Check if a deprecation has already been emitted.
     */
    hasEmitted(oldName: string): boolean;
    /**
     * Get all registered deprecations.
     */
    listRegistered(): WarnDeprecatedOptions[];
    /**
     * Reset all emitted warnings (for testing).
     */
    reset(): void;
    /**
     * Clear registry and emitted state (for testing).
     */
    clear(): void;
    private emitWarning;
}
/**
 * Singleton deprecation registry for the application.
 */
export declare const deprecationRegistry: DeprecationRegistry;
/**
 * Emit a deprecation warning using the global registry.
 * Only emits once per `oldName` per process lifetime.
 *
 * @example
 * ```typescript
 * warnDeprecated({
 *   oldName: 'hierarchical_prompt_builder',
 *   newName: 'prompt_engineering_framework',
 *   removalVersion: '0.16.0',
 * });
 * ```
 */
export declare function warnDeprecated(options: WarnDeprecatedOptions): void;
//# sourceMappingURL=deprecation-helpers.d.ts.map