@sanity/ailf 0.1.0

package/dist/sinks/webhook/index.js

@@ -0,0 +1,50 @@
+/**
+ * sinks/webhook/index.ts
+ *
+ * Generic HTTP webhook sink — POSTs the full report JSON to any endpoint.
+ * This is the universal adapter for integrations that don't have a
+ * dedicated sink (Airbyte, Zapier, custom services, etc.).
+ *
+ * @see docs/design-docs/report-store/sink-architecture.md
+ */
+export class WebhookSink {
+    url;
+    headers;
+    name;
+    constructor(url, headers = {}) {
+        this.url = url;
+        this.headers = headers;
+        try {
+            this.name = `webhook:${new URL(url).hostname}`;
+        }
+        catch {
+            this.name = "webhook:invalid-url";
+        }
+    }
+    healthCheck() {
+        try {
+            new URL(this.url);
+            return Promise.resolve({ healthy: true });
+        }
+        catch {
+            return Promise.resolve({
+                healthy: false,
+                reason: `Invalid URL: ${this.url}`,
+            });
+        }
+    }
+    async publish(report) {
+        const response = await fetch(this.url, {
+            body: JSON.stringify(report),
+            headers: { "Content-Type": "application/json", ...this.headers },
+            method: "POST",
+        });
+        if (!response.ok) {
+            return {
+                error: `HTTP ${response.status}: ${response.statusText}`,
+                status: "failed",
+            };
+        }
+        return { detail: `HTTP ${response.status}`, status: "success" };
+    }
+}

package/dist/sinks/webhook-sink.d.ts

@@ -0,0 +1,19 @@
+/**
+ * sinks/webhook-sink.ts
+ *
+ * Generic HTTP webhook sink — POSTs the full report JSON to any endpoint.
+ * This is the universal adapter for integrations that don't have a
+ * dedicated sink (Airbyte, Zapier, custom services, etc.).
+ *
+ * @see docs/design-docs/report-store/sink-architecture.md
+ */
+import type { Report, SinkHealthStatus, SinkResult } from "../pipeline/types.js";
+import type { ReportSink } from "./types.js";
+export declare class WebhookSink implements ReportSink {
+    private readonly url;
+    private readonly headers;
+    readonly name: string;
+    constructor(url: string, headers?: Record<string, string>);
+    healthCheck(): Promise<SinkHealthStatus>;
+    publish(report: Report): Promise<SinkResult>;
+}

package/dist/sinks/webhook-sink.js

@@ -0,0 +1,50 @@
+/**
+ * sinks/webhook-sink.ts
+ *
+ * Generic HTTP webhook sink — POSTs the full report JSON to any endpoint.
+ * This is the universal adapter for integrations that don't have a
+ * dedicated sink (Airbyte, Zapier, custom services, etc.).
+ *
+ * @see docs/design-docs/report-store/sink-architecture.md
+ */
+export class WebhookSink {
+    url;
+    headers;
+    name;
+    constructor(url, headers = {}) {
+        this.url = url;
+        this.headers = headers;
+        try {
+            this.name = `webhook:${new URL(url).hostname}`;
+        }
+        catch {
+            this.name = "webhook:invalid-url";
+        }
+    }
+    healthCheck() {
+        try {
+            new URL(this.url);
+            return Promise.resolve({ healthy: true });
+        }
+        catch {
+            return Promise.resolve({
+                healthy: false,
+                reason: `Invalid URL: ${this.url}`,
+            });
+        }
+    }
+    async publish(report) {
+        const response = await fetch(this.url, {
+            body: JSON.stringify(report),
+            headers: { "Content-Type": "application/json", ...this.headers },
+            method: "POST",
+        });
+        if (!response.ok) {
+            return {
+                error: `HTTP ${response.status}: ${response.statusText}`,
+                status: "failed",
+            };
+        }
+        return { detail: `HTTP ${response.status}`, status: "success" };
+    }
+}

package/dist/sources.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Sources.ts
+ *
+ * Loads and validates documentation source configurations from config/sources.yaml.
+ * Each source defines where to find documentation for evaluation — a Sanity
+ * dataset, a branch deploy URL, a local dev server, etc.
+ *
+ * Every source carries all fields needed by both evaluation modes:
+ *   - Baseline/Observed: uses projectId + dataset (GROQ queries to Sanity CMS)
+ *   - Agentic: uses baseUrl (agent browses the live site, llms.txt derived automatically)
+ *
+ * Environment variables in config/sources.yaml are resolved via ${{ VAR | default }}
+ * interpolation at load time.
+ */
+/**
+ * @deprecated Use {@link ResolvedSourceConfig} instead.
+ * Kept as a type alias for backward compatibility during the transition.
+ */
+export type DocSource = ResolvedSourceConfig;
+/**
+ * Fully resolved documentation source configuration.
+ *
+ * After all CLI flags, environment variables, URL classifications, and
+ * config/sources.yaml defaults are merged, the system produces a single
+ * ResolvedSourceConfig that drives the entire pipeline.
+ *
+ * All ${{ }} expressions have been expanded by the time this is constructed.
+ */
+export interface ResolvedSourceConfig {
+    /** Optional origin allowlist for agentic sandboxing */
+    allowedOrigins?: string[];
+    /** Base URL for documentation site (agentic mode + URL prefixes in context) */
+    baseUrl: string;
+    /** Sanity dataset name */
+    dataset: string;
+    /** Optional list of specific Sanity document IDs to fetch */
+    documentIds?: string[];
+    /** Custom HTTP headers to send with documentation requests (e.g., auth tokens) */
+    headers?: Record<string, string>;
+    /** URL to the llms.txt file — always derived as baseUrl + "/llms.txt" */
+    llmsTxt: string;
+    /** Source name (the key from config/sources.yaml, or "env-override") */
+    name: string;
+    /** Sanity release perspective ID (optional — for evaluating content releases) */
+    perspective?: string;
+    /** Hostname extracted from baseUrl — used for search result prioritization */
+    priorityDomain: string;
+    /** Sanity project ID */
+    projectId: string;
+    /** Sanity Studio base URL (for URL classification and Studio link generation) */
+    studioOrigin: string;
+    /** Direct documentation URLs (non-Sanity, from --url/--urls classification) */
+    urls: string[];
+}
+/**
+ * Check whether a URL is allowed by the given origin patterns.
+ *
+ * Returns `true` if:
+ * - `origins` is empty (no sandboxing configured), or
+ * - the URL's hostname matches at least one origin pattern.
+ *
+ * Returns `false` if the URL is invalid or doesn't match any pattern.
+ */
+export declare function isAllowedOrigin(url: string, origins: string[]): boolean;
+/**
+ * Overrides for source resolution. When provided, these values take
+ * precedence over environment variables. This allows callers with
+ * typed config (e.g., orchestration steps) to bypass the env var bridge.
+ */
+export interface SourceOverrides {
+    allowedOrigins?: string[];
+    baseUrl?: string;
+    dataset?: string;
+    directUrls?: string[];
+    documentIds?: string[];
+    headers?: Record<string, string>;
+    perspective?: string;
+    projectId?: string;
+    studioOrigin?: string;
+}
+/**
+ * Load a documentation source by name.
+ *
+ * Resolution order:
+ *   1. If DOC_BASE_URL env var is set, build an ad-hoc source from env vars
+ *   2. If config/sources.yaml exists, load and interpolate the named source
+ *   3. Fall back to the built-in default (sanity.io production)
+ *
+ * @param name - Source name from config/sources.yaml. If omitted, uses DOC_SOURCE
+ *               env var or the first source defined in config/sources.yaml.
+ */
+export declare function loadSource(name?: string, overrides?: SourceOverrides): ResolvedSourceConfig;
+/**
+ * Match a hostname against an origin pattern that may contain `*` wildcards.
+ *
+ * The `*` wildcard matches any substring within a single hostname segment
+ * (i.e., it does not cross dots). A bare `*` matches everything.
+ *
+ * @example
+ * matchesOrigin("branch.sanity.build", "*.sanity.build")   // true
+ * matchesOrigin("sanity.io", "*.sanity.build")              // false
+ * matchesOrigin("anything.example.com", "*")                // true
+ */
+export declare function matchesOrigin(hostname: string, pattern: string): boolean;

package/dist/sources.js

@@ -0,0 +1,292 @@
+/**
+ * Sources.ts
+ *
+ * Loads and validates documentation source configurations from config/sources.yaml.
+ * Each source defines where to find documentation for evaluation — a Sanity
+ * dataset, a branch deploy URL, a local dev server, etc.
+ *
+ * Every source carries all fields needed by both evaluation modes:
+ *   - Baseline/Observed: uses projectId + dataset (GROQ queries to Sanity CMS)
+ *   - Agentic: uses baseUrl (agent browses the live site, llms.txt derived automatically)
+ *
+ * Environment variables in config/sources.yaml are resolved via ${{ VAR | default }}
+ * interpolation at load time.
+ */
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { load } from "js-yaml";
+import { interpolate } from "./interpolate.js";
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SOURCES_PATH = resolve(__dirname, "..", "config", "sources.yaml");
+// ---------------------------------------------------------------------------
+// Default source — used when no config/sources.yaml exists or no --source flag
+// ---------------------------------------------------------------------------
+const DEFAULT_SOURCE = {
+    baseUrl: "https://www.sanity.io/docs",
+    dataset: "next",
+    documentIds: [],
+    llmsTxt: "https://www.sanity.io/docs/llms.txt",
+    name: "production",
+    perspective: undefined,
+    priorityDomain: "sanity.io",
+    projectId: "3do82whm",
+    studioOrigin: "https://admin.sanity.io",
+    urls: [],
+};
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/**
+ * Check whether a URL is allowed by the given origin patterns.
+ *
+ * Returns `true` if:
+ * - `origins` is empty (no sandboxing configured), or
+ * - the URL's hostname matches at least one origin pattern.
+ *
+ * Returns `false` if the URL is invalid or doesn't match any pattern.
+ */
+export function isAllowedOrigin(url, origins) {
+    if (origins.length === 0) {
+        return true;
+    }
+    try {
+        const hostname = new URL(url).hostname.replace(/^www\./, "");
+        return origins.some((origin) => matchesOrigin(hostname, origin));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Load a documentation source by name.
+ *
+ * Resolution order:
+ *   1. If DOC_BASE_URL env var is set, build an ad-hoc source from env vars
+ *   2. If config/sources.yaml exists, load and interpolate the named source
+ *   3. Fall back to the built-in default (sanity.io production)
+ *
+ * @param name - Source name from config/sources.yaml. If omitted, uses DOC_SOURCE
+ *               env var or the first source defined in config/sources.yaml.
+ */
+export function loadSource(name, overrides) {
+    // Priority 1: DOC_BASE_URL env var creates an ad-hoc source
+    const envBaseUrl = overrides?.baseUrl ?? process.env.DOC_BASE_URL;
+    if (envBaseUrl) {
+        const domain = extractHostname(envBaseUrl);
+        return {
+            allowedOrigins: overrides?.allowedOrigins ?? parseAllowedOriginsEnv(),
+            baseUrl: envBaseUrl,
+            // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back to default
+            dataset: overrides?.dataset ?? (process.env.SANITY_DATASET || "next"),
+            documentIds: overrides?.documentIds ?? parseDocumentIdsEnv(),
+            headers: overrides?.headers ?? parseHeadersEnv(),
+            llmsTxt: envBaseUrl + "/llms.txt",
+            name: "env-override",
+            // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back to undefined
+            perspective: overrides?.perspective ?? (process.env.SANITY_PERSPECTIVE || undefined),
+            priorityDomain: domain,
+            // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back to default
+            projectId: overrides?.projectId ?? (process.env.SANITY_PROJECT_ID || "3do82whm"),
+            studioOrigin: 
+            // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back to default
+            overrides?.studioOrigin ??
+                (process.env.SANITY_STUDIO_ORIGIN || "https://admin.sanity.io"),
+            urls: overrides?.directUrls ?? parseDirectUrlsEnv(),
+        };
+    }
+    // Priority 2: Load from config/sources.yaml
+    let rawFile;
+    try {
+        const content = readFileSync(SOURCES_PATH, "utf-8");
+        rawFile = load(content);
+    }
+    catch {
+        // No config/sources.yaml — use built-in default
+        console.log("  No config/sources.yaml found, using built-in default (sanity.io production)");
+        return DEFAULT_SOURCE;
+    }
+    if (!rawFile?.sources || Object.keys(rawFile.sources).length === 0) {
+        console.log("  config/sources.yaml is empty, using built-in default");
+        return DEFAULT_SOURCE;
+    }
+    // Resolve which source to use
+    const sourceName = 
+    // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty strings should fall through to next candidate
+    name || process.env.DOC_SOURCE || Object.keys(rawFile.sources)[0];
+    const rawEntry = rawFile.sources[sourceName];
+    if (!rawEntry) {
+        const available = Object.keys(rawFile.sources).join(", ");
+        throw new Error('Source "' +
+            sourceName +
+            '" not found in config/sources.yaml. Available: ' +
+            available);
+    }
+    // Interpolate ${{ VAR }} expressions
+    const resolved = interpolate(rawEntry);
+    // Validate after interpolation
+    validateSource(sourceName, resolved);
+    // Filter empty strings from YAML-interpolated allowedOrigins.
+    // An interpolation like ${{ DOC_ALLOWED_ORIGIN | }} resolves to "",
+    // Which would produce [""] — matching nothing and silently blocking all origins.
+    const filteredOrigins = resolved.allowedOrigins?.filter(Boolean);
+    return {
+        allowedOrigins: filteredOrigins && filteredOrigins.length > 0
+            ? filteredOrigins
+            : undefined,
+        baseUrl: resolved.baseUrl,
+        dataset: resolved.dataset,
+        documentIds: overrides?.documentIds ?? parseDocumentIdsEnv() ?? [],
+        headers: mergeHeaders(resolved.headers, overrides?.headers ?? parseHeadersEnv()),
+        llmsTxt: resolved.baseUrl + "/llms.txt",
+        name: sourceName,
+        // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back to undefined
+        perspective: overrides?.perspective ?? (process.env.SANITY_PERSPECTIVE || undefined),
+        priorityDomain: extractHostname(resolved.baseUrl),
+        projectId: resolved.projectId,
+        // oxlint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- empty string env var should fall back to default
+        studioOrigin: overrides?.studioOrigin ??
+            (process.env.SANITY_STUDIO_ORIGIN || "https://admin.sanity.io"),
+        urls: [],
+    };
+}
+/**
+ * Match a hostname against an origin pattern that may contain `*` wildcards.
+ *
+ * The `*` wildcard matches any substring within a single hostname segment
+ * (i.e., it does not cross dots). A bare `*` matches everything.
+ *
+ * @example
+ * matchesOrigin("branch.sanity.build", "*.sanity.build")   // true
+ * matchesOrigin("sanity.io", "*.sanity.build")              // false
+ * matchesOrigin("anything.example.com", "*")                // true
+ */
+export function matchesOrigin(hostname, pattern) {
+    if (pattern === "*") {
+        return true;
+    }
+    // Convert glob pattern to regex: escape dots, replace * with [^.]* (within-segment)
+    const regexStr = "^" + pattern.replace(/\./g, "\\.").replace(/\*/g, "[^.]*") + "$";
+    return new RegExp(regexStr).test(hostname);
+}
+function extractHostname(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Merge headers from config/sources.yaml with DOC_HEADERS env var.
+ * Env var headers take precedence over source-defined headers.
+ * Returns undefined if both are empty.
+ */
+function mergeHeaders(sourceHeaders, envHeaders) {
+    if (!sourceHeaders && !envHeaders) {
+        return undefined;
+    }
+    if (!sourceHeaders) {
+        return envHeaders;
+    }
+    if (!envHeaders) {
+        return sourceHeaders;
+    }
+    return { ...sourceHeaders, ...envHeaders };
+}
+/**
+ * Parse allowed origins from environment variables.
+ *
+ * Reads DOC_ALLOWED_ORIGINS (plural, comma-separated) first, then falls back
+ * to DOC_ALLOWED_ORIGIN (singular) for backward compatibility.
+ *
+ * Returns undefined if neither is set (no sandboxing).
+ */
+function parseAllowedOriginsEnv() {
+    const plural = process.env.DOC_ALLOWED_ORIGINS;
+    if (plural) {
+        const origins = plural
+            .split(",")
+            .map((o) => o.trim())
+            .filter(Boolean);
+        return origins.length > 0 ? origins : undefined;
+    }
+    const singular = process.env.DOC_ALLOWED_ORIGIN;
+    if (singular) {
+        return [singular];
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Origin matching (exported for use by agentic-provider and assertions)
+// ---------------------------------------------------------------------------
+/**
+ * Parse direct documentation URLs from the DOC_DIRECT_URLS environment
+ * variable (comma-separated). These are URLs classified as "direct-url"
+ * by the URL classifier — they point to documentation pages rather than
+ * Sanity CMS resources.
+ */
+function parseDirectUrlsEnv() {
+    const env = process.env.DOC_DIRECT_URLS;
+    if (!env) {
+        return [];
+    }
+    return env
+        .split(",")
+        .map((u) => u.trim())
+        .filter(Boolean);
+}
+/**
+ * Parse the SANITY_DOCUMENT_IDS env var (comma-separated UUIDs) into an array.
+ * Returns undefined if not set or empty.
+ */
+function parseDocumentIdsEnv() {
+    const raw = process.env.SANITY_DOCUMENT_IDS;
+    if (!raw) {
+        return undefined;
+    }
+    const ids = raw
+        .split(",")
+        .map((id) => id.trim())
+        .filter(Boolean);
+    return ids.length > 0 ? ids : undefined;
+}
+/**
+ * Parse the DOC_HEADERS env var (JSON string) into a Record.
+ * Returns undefined if not set or invalid.
+ */
+function parseHeadersEnv() {
+    const raw = process.env.DOC_HEADERS;
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Invalid JSON — ignore
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+function validateSource(name, raw) {
+    if (!raw.baseUrl) {
+        throw new Error('Source "' + name + '" is missing required field "baseUrl".');
+    }
+    if (!raw.projectId) {
+        throw new Error('Source "' + name + '" is missing required field "projectId".');
+    }
+    if (!raw.dataset) {
+        throw new Error('Source "' + name + '" is missing required field "dataset".');
+    }
+}

package/dist/webhook/budget.d.ts

@@ -0,0 +1,42 @@
+/**
+ * webhook/budget.ts
+ *
+ * Daily budget tracking for webhook-triggered evaluations.
+ *
+ * Evaluations cost $0.50–$5+ per run. Without guardrails, rapid-fire
+ * content edits could exhaust the evaluation budget. This module provides
+ * a simple in-memory counter that resets daily.
+ *
+ * For persistent budget tracking across process restarts, store the
+ * counter in Sanity or a KV store (future enhancement).
+ *
+ * @see docs/design-docs/report-store/visibility-workflows.md — Budget caps
+ */
+/** Budget tracker state */
+export interface BudgetState {
+    /** Number of dispatches today */
+    count: number;
+    /** ISO date string for the current day (YYYY-MM-DD) */
+    date: string;
+    /** Maximum dispatches per day */
+    limit: number;
+}
+export interface BudgetTracker {
+    /** Check if a dispatch is allowed (under budget) */
+    canDispatch(): boolean;
+    /** Current state */
+    currentState(): BudgetState;
+    /** Record a dispatch (increments counter) */
+    record(): void;
+    /** Remaining dispatches today */
+    remaining(): number;
+}
+/**
+ * Create a daily budget tracker.
+ *
+ * The counter resets automatically when the date changes (UTC).
+ * State is in-memory only — restarting the process resets the counter.
+ *
+ * @param dailyLimit - Maximum evaluations per day (default: 20)
+ */
+export declare function createBudgetTracker(dailyLimit?: number): BudgetTracker;

package/dist/webhook/budget.js

@@ -0,0 +1,60 @@
+/**
+ * webhook/budget.ts
+ *
+ * Daily budget tracking for webhook-triggered evaluations.
+ *
+ * Evaluations cost $0.50–$5+ per run. Without guardrails, rapid-fire
+ * content edits could exhaust the evaluation budget. This module provides
+ * a simple in-memory counter that resets daily.
+ *
+ * For persistent budget tracking across process restarts, store the
+ * counter in Sanity or a KV store (future enhancement).
+ *
+ * @see docs/design-docs/report-store/visibility-workflows.md — Budget caps
+ */
+/**
+ * Create a daily budget tracker.
+ *
+ * The counter resets automatically when the date changes (UTC).
+ * State is in-memory only — restarting the process resets the counter.
+ *
+ * @param dailyLimit - Maximum evaluations per day (default: 20)
+ */
+export function createBudgetTracker(dailyLimit = 20) {
+    const state = {
+        count: 0,
+        date: todayUTC(),
+        limit: dailyLimit,
+    };
+    function maybeReset() {
+        const today = todayUTC();
+        if (state.date !== today) {
+            state.count = 0;
+            state.date = today;
+        }
+    }
+    return {
+        canDispatch() {
+            maybeReset();
+            return state.count < state.limit;
+        },
+        currentState() {
+            maybeReset();
+            return { ...state };
+        },
+        record() {
+            maybeReset();
+            state.count++;
+        },
+        remaining() {
+            maybeReset();
+            return Math.max(0, state.limit - state.count);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function todayUTC() {
+    return new Date().toISOString().slice(0, 10);
+}

package/dist/webhook/debounce.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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;