/**
 * Which docs index the server opens.
 *
 * The npm package ships an index, and data-update.ts can download newer ones
 * into the data directory. The server uses the newest file it can validate.
 * Downloaded files are named by stamp and never overwritten, so several server
 * processes can share the directory without replacing a file another one reads.
 */
import { type DataMeta } from "./data-format.js";
export type DataMode = "auto" | "bundled";
export interface DataSourceOptions {
    /** The index inside the npm package. */
    bundledPath: string;
    /** Where downloaded indexes live. */
    dataDir: string;
    /** This server's package version, checked against each file's min_server_version. */
    serverVersion: string;
    mode: DataMode;
    /** FOOTBALL_DOCS_DB_PATH: use exactly this file. */
    pinnedPath?: string;
    log?: (message: string) => void;
}
export interface DataSelection {
    path: string;
    source: "bundled" | "downloaded" | "pinned";
    meta: DataMeta | null;
}
export declare function defaultDataDir(env?: NodeJS.ProcessEnv): string;
/**
 * FOOTBALL_DOCS_DATA picks the mode. Without it, a server running from a git
 * checkout uses its own bundled file, so development and tests always see the
 * working tree's docs and never touch the network or the user's cache.
 */
export declare function dataModeFor(env: NodeJS.ProcessEnv, packageRoot: string): DataMode;
export declare function cachedFileName(stampMs: number): string;
/**
 * Choose the index to open. The newest valid file wins; on a tie the bundled
 * file wins. If the bundled file fails validation (an index built before the
 * meta table existed, in a development checkout) it is still the fallback, so
 * the server behaves as it did before downloads existed.
 */
export declare function selectDatabase(options: DataSourceOptions): DataSelection;
/** The newest stamp among downloaded files, or null. Cheap: one directory listing. */
export declare function newestCachedStamp(dataDir: string): number | null;
/**
 * Holds the chosen index for a long-running server and chooses again when
 * needed: when the chosen file has gone (another process cleaned it up), or when
 * a newer downloaded file appears. The server may run for days, and another
 * server process sharing the data directory may be the one that downloads the
 * newer file, so this checks the directory on each call rather than waiting for
 * its own update check.
 */
export declare class IndexChooser {
    private readonly options;
    private selection;
    private newestSeen;
    constructor(options: DataSourceOptions);
    current(): DataSelection;
}
/**
 * Remove leftovers from the data directory: temporary downloads older than an
 * hour, and downloaded indexes older than the active one that have not changed
 * for a week. Errors are ignored; a file that cannot be removed now is tried again
 * at the next start.
 */
export declare function cleanDataDir(dataDir: string, activeStampMs: number | null, now?: number): void;