/**
 * webhook/debounce.ts
 *
 * Time-window debouncing for content change webhooks.
 *
 * When multiple documents are edited in rapid succession (e.g., an editor
 * updating several related articles), we coalesce them into a single
 * evaluation dispatch. This prevents wasting evaluation budget on
 * intermediate states.
 *
 * Strategy: accumulate changed slugs in a time window (default: 5 minutes).
 * When the window expires, dispatch a single evaluation for all accumulated
 * areas. New edits during the window reset the timer ("trailing edge").
 *
 * @see docs/design-docs/report-store/visibility-workflows.md — Debouncing
 */
/** Callback invoked when the debounce window closes */
export type DebounceCallback = (slugs: string[]) => Promise<void> | void;
/**
 * A debouncer that coalesces rapid document changes into batched dispatches.
 *
 * Each call to `push()` adds a slug to the current window and resets the
 * trailing-edge timer. When the timer fires (no new edits for `windowMs`),
 * the callback is invoked with all accumulated slugs.
 *
 * Usage:
 * ```ts
 * const debouncer = createDebouncer(300_000, async (slugs) => {
 *   const impact = assessImpact(slugs, reverseMapping)
 *   await dispatch(impact)
 * })
 *
 * // Called for each webhook:
 * debouncer.push("groq-introduction")
 * debouncer.push("how-queries-work")
 * // ... 5 minutes of silence ...
 * // → callback fires with ["groq-introduction", "how-queries-work"]
 * ```
 */
export interface Debouncer {
    /** Cancel the current window without dispatching */
    cancel(): void;
    /** Flush the current window immediately (for shutdown) */
    flush(): Promise<void>;
    /** Number of slugs in the current window */
    pending(): number;
    /** Add a slug to the current debounce window */
    push(slug: string): void;
    /** Current state (for inspection/testing) */
    state(): DebounceState;
}
/** State of a debounce window */
export interface DebounceState {
    /** Accumulated document slugs */
    slugs: Set<string>;
    /** Timer handle for the trailing edge */
    timer: null | ReturnType<typeof setTimeout>;
    /** When the current window opened */
    windowStart: number;
}
/**
 * Create a debouncer with a configurable time window.
 *
 * @param windowMs - Debounce window in milliseconds (default: 300_000 = 5 min)
 * @param onFlush - Callback invoked when the window closes
 */
export declare function createDebouncer(windowMs: number, onFlush: DebounceCallback): Debouncer;
