/**
 * Periodic refresher for the dispatch-queue depth breakdown.
 *
 * Runs on a fixed interval (default 5s) — short enough that the
 * Prometheus observable-gauge callback (which reads the JobQueue's
 * synchronous cache) never serves data older than one refresh tick,
 * long enough that a single orchestrator does not hammer the DB.
 *
 * Two responsibilities:
 *
 *   1. Call {@link JobQueue.getDepthBreakdown} to refresh the internal
 *      cache and feed {@link setDispatchQueueDepthBreakdown} so
 *      `kici_orch_dispatch_queue_depth` / `..._by_label` are always
 *      recent when Prometheus scrapes.
 *   2. Watch for sustained backpressure: when the pending depth stays
 *      at or above {@link RefresherOptions.thresholdGetter | threshold}
 *      for two consecutive refreshes, emit a `logger.warn` that points
 *      operators at the per-label Grafana panel. The two-in-a-row
 *      guard suppresses transient spikes without needing a cooldown.
 *
 * Threshold is resolved lazily on every tick via `thresholdGetter` so
 * live config reloads (SIGHUP / cluster propagation) take effect
 * immediately without restarting the refresher.
 *
 * A threshold of `0` disables the warning entirely — the refresher
 * still runs so metrics keep flowing.
 */
import type { Logger } from '@kici-dev/shared';
import { type JobQueue } from './job-queue.js';
export interface DepthRefresherOptions {
    queue: JobQueue;
    logger: Logger;
    /**
     * How often to refresh the cache / evaluate the warning threshold.
     * Defaults to 5 seconds — short enough that Prometheus's default 15s
     * scrape interval never sees data older than one tick.
     */
    intervalMs?: number;
    /**
     * Called on every tick to get the current backpressure warn
     * threshold. `0` disables warnings.
     */
    thresholdGetter: () => number;
    /**
     * Optional hook invoked after each successful tick, for tests.
     */
    onTick?: (pendingDepth: number) => void;
}
export interface DepthRefresher {
    /** Start the periodic timer. Idempotent. */
    start(): void;
    /** Stop the periodic timer. Idempotent. */
    stop(): void;
    /** Run one refresh synchronously (used at startup and in tests). */
    refreshNow(): Promise<void>;
}
/**
 * Create a dispatch-queue depth refresher.
 *
 * The returned object is NOT started automatically — call `start()`
 * after the orchestrator is otherwise ready. `stop()` must be called
 * during shutdown to avoid leaking the interval handle.
 */
export declare function createDepthRefresher(options: DepthRefresherOptions): DepthRefresher;
//# sourceMappingURL=depth-refresher.d.ts.map