import { MeasureCacheStats } from './cache.js';
/**
 * Performance metrics for page token resolution.
 * Tracks timing and iteration counts for monitoring rollout health.
 */
export interface PageTokenMetrics {
    /** Total time spent in token resolution (milliseconds) */
    totalTimeMs: number;
    /** Number of convergence iterations (0 = no tokens, 1+ = resolution occurred) */
    iterations: number;
    /** Number of blocks affected by token resolution */
    affectedBlocks: number;
    /** Time spent re-measuring blocks (milliseconds) */
    remeasureTimeMs: number;
    /** Time spent re-running layout (milliseconds) */
    relayoutTimeMs: number;
    /** Whether convergence was achieved within max iterations */
    converged: boolean;
}
/**
 * Header/footer cache metrics.
 * Tracks cache performance for optimization and capacity planning.
 */
export interface HeaderFooterCacheMetrics {
    /** Cache hit count for this operation */
    hits: number;
    /** Cache miss count for this operation */
    misses: number;
    /** Hit rate percentage (0-100) */
    hitRate: number;
    /** Current cache size (number of entries) */
    cacheSize: number;
    /** Estimated memory usage (bytes) */
    memoryEstimate: number;
    /** Number of evictions due to LRU policy */
    evictions: number;
}
/**
 * Layout performance metrics.
 * High-level timing for the entire layout operation.
 */
export interface LayoutMetrics {
    /** Total layout time including all phases (milliseconds) */
    totalTimeMs: number;
    /** Measurement phase time (milliseconds) */
    measureTimeMs: number;
    /** Initial pagination time (milliseconds) */
    paginationTimeMs: number;
    /** Token resolution phase time (milliseconds) */
    tokenResolutionTimeMs: number;
    /** Header/footer layout time (milliseconds) */
    headerFooterTimeMs: number;
}
/**
 * Debug logger for page token resolution.
 * Only logs when SD_DEBUG_PAGE_TOKENS is enabled.
 */
export declare const PageTokenLogger: {
    /**
     * Logs the start of token resolution.
     *
     * @param iteration - Current iteration number (0-based)
     * @param totalPages - Total number of pages in the document
     */
    logIterationStart(iteration: number, totalPages: number): void;
    /**
     * Logs affected blocks during token resolution.
     *
     * @param iteration - Current iteration number (0-based)
     * @param affectedBlockIds - Set of affected block IDs
     * @param blockSamples - Sample block IDs for debugging (first 5)
     */
    logAffectedBlocks(iteration: number, affectedBlockIds: Set<string>, blockSamples?: string[]): void;
    /**
     * Logs convergence status.
     *
     * @param iteration - Final iteration number
     * @param converged - Whether convergence was achieved
     * @param totalTimeMs - Total time spent in token resolution
     */
    logConvergence(iteration: number, converged: boolean, totalTimeMs: number): void;
    /**
     * Logs token resolution error.
     *
     * @param blockId - Block ID where error occurred
     * @param error - Error object
     */
    logError(blockId: string, error: unknown): void;
    /**
     * Logs re-measurement details.
     *
     * @param blockCount - Number of blocks being re-measured
     * @param timeMs - Time spent re-measuring
     */
    logRemeasure(blockCount: number, timeMs: number): void;
};
/**
 * Debug logger for header/footer cache operations.
 * Only logs when SD_DEBUG_HF_CACHE is enabled.
 */
export declare const HeaderFooterCacheLogger: {
    /**
     * Logs cache hit for a header/footer variant.
     *
     * @param variantType - Variant type (default, first, even, odd)
     * @param pageNumber - Page number being cached
     * @param bucket - Digit bucket (d1, d2, d3, d4) or 'exact'
     */
    logCacheHit(variantType: string, pageNumber: number, bucket: string): void;
    /**
     * Logs cache miss for a header/footer variant.
     *
     * @param variantType - Variant type (default, first, even, odd)
     * @param pageNumber - Page number being cached
     * @param bucket - Digit bucket (d1, d2, d3, d4) or 'exact'
     */
    logCacheMiss(variantType: string, pageNumber: number, bucket: string): void;
    /**
     * Logs cache invalidation.
     *
     * @param reason - Reason for invalidation
     * @param affectedBlockIds - Block IDs being invalidated
     */
    logInvalidation(reason: string, affectedBlockIds: string[]): void;
    /**
     * Logs cache statistics.
     *
     * @param stats - Cache statistics object
     */
    logStats(stats: MeasureCacheStats): void;
    /**
     * Logs bucketing decision for large documents.
     *
     * @param totalPages - Total number of pages
     * @param useBucketing - Whether bucketing is being used
     * @param buckets - Buckets needed (if bucketing enabled)
     */
    logBucketingDecision(totalPages: number, useBucketing: boolean, buckets?: string[]): void;
};
/**
 * Metrics collector for performance monitoring.
 * Collects metrics even when debug logging is disabled, for production monitoring.
 */
export declare class MetricsCollector {
    private pageTokenMetrics;
    private headerFooterCacheMetrics;
    private layoutMetrics;
    /**
     * Records page token resolution metrics.
     *
     * @param metrics - Page token metrics
     */
    recordPageTokenMetrics(metrics: PageTokenMetrics): void;
    /**
     * Records header/footer cache metrics.
     *
     * @param stats - Cache statistics
     */
    recordHeaderFooterCacheMetrics(stats: MeasureCacheStats): void;
    /**
     * Records overall layout metrics.
     *
     * @param metrics - Layout metrics
     */
    recordLayoutMetrics(metrics: LayoutMetrics): void;
    /**
     * Gets all collected metrics.
     *
     * @returns Object with all metrics or null if not collected
     */
    getMetrics(): {
        pageTokens: PageTokenMetrics | null;
        headerFooterCache: HeaderFooterCacheMetrics | null;
        layout: LayoutMetrics | null;
    };
    /**
     * Resets all collected metrics.
     */
    reset(): void;
    /**
     * Checks for page token rollback triggers and logs warnings.
     *
     * Rollback triggers (from plan):
     * - Convergence > 2 iterations
     * - Token resolution time > 100ms per layout run
     *
     * @param metrics - Page token metrics
     */
    private checkPageTokenRollbackTriggers;
    /**
     * Checks for cache rollback triggers and logs warnings.
     *
     * Rollback triggers (from plan):
     * - Cache thrash (hit rate below 30%)
     * - Excessive memory usage (>1MB per 100 pages)
     *
     * @param metrics - Header/footer cache metrics
     */
    private checkCacheRollbackTriggers;
}
/**
 * Global metrics collector instance.
 * Can be accessed for monitoring and debugging.
 */
export declare const globalMetrics: MetricsCollector;
/**
 * Logger for layout version events.
 * Guards all logging behind SD_DEBUG_LAYOUT_VERSION flag for zero overhead in production.
 */
export declare const LayoutVersionLogger: {
    /**
     * Log when selection overlay attempts to use stale layout.
     *
     * @param versionGap - Number of PM versions ahead of layout
     * @param stalenessDuration - How long layout has been stale (ms)
     */
    logStaleLayoutRead(versionGap: number, stalenessDuration: number): void;
    /**
     * Log when geometry fallback is used due to missing pmStart/pmEnd.
     *
     * @param reason - Why fallback was needed
     * @param pos - PM position that failed
     */
    logGeometryFallback(reason: string, pos: number): void;
    /**
     * Log when layout catches up to current PM state.
     *
     * @param versionGap - How many versions layout was behind
     * @param stalenessDuration - Total duration layout was stale (ms)
     */
    logLayoutCaughtUp(versionGap: number, stalenessDuration: number): void;
    /**
     * Log PM transaction that increments version.
     *
     * @param newVersion - New PM version after transaction
     */
    logPmTransaction(newVersion: number): void;
    /**
     * Log layout completion.
     *
     * @param version - Version of the completed layout
     * @param isStale - Whether layout is still stale after this completion
     */
    logLayoutComplete(version: number, isStale: boolean): void;
};
//# sourceMappingURL=instrumentation.d.ts.map