/**
 * WikiUsageService — the retrieval ledger.
 *
 * Every query against a vault appends one JSONL line: who asked, what,
 * which pages were read, and whether it was a miss (nothing relevant).
 * This is the only honest signal for "is the knowledge base alive":
 * pages nobody reads and questions nobody could answer both come out of
 * it, and the bookkeeping report turns them into work.
 *
 * @module services/wiki/wiki-usage.service
 */
/** One retrieval event. */
export interface WikiUsageEvent {
    at: string;
    /** `wiki-query` | `recall` | `search` | `page` */
    via: string;
    agent: string;
    query: string;
    /** Vault-relative pages returned/read. */
    hits: string[];
    /** True when nothing relevant came back — a capture gap. */
    miss: boolean;
}
/** Aggregate over a window. */
export interface WikiUsageReport {
    windowDays: number;
    queries: number;
    misses: number;
    /** Distinct pages read at least once in the window. */
    pagesRead: number;
    /** Most-read pages, descending. */
    topPages: Array<{
        path: string;
        reads: number;
    }>;
    /** Queries that found nothing (deduped, most recent first). */
    missedQueries: string[];
    /** Agents that queried, with counts. */
    byAgent: Array<{
        agent: string;
        queries: number;
    }>;
}
/**
 * Appends and summarises `llm-curated/usage.jsonl` per vault.
 */
export declare class WikiUsageService {
    private readonly now;
    private static instance;
    private readonly logger;
    constructor(now?: () => Date);
    static getInstance(): WikiUsageService;
    /** Test-only reset. */
    static _resetForTesting(): void;
    /**
     * Ledger path for a vault.
     *
     * @param vaultPath - Vault root
     * @returns `<vault>/llm-curated/usage.jsonl`
     */
    ledgerPath(vaultPath: string): string;
    /**
     * Append one event. Never throws (a ledger failure must not fail a query).
     *
     * @param vaultPath - Vault root
     * @param event - Event fields (`at` is filled in)
     */
    record(vaultPath: string, event: Omit<WikiUsageEvent, 'at'>): Promise<void>;
    /**
     * Read events in the last N days.
     *
     * @param vaultPath - Vault root
     * @param windowDays - Window (default {@link WIKI_KB_CONSTANTS.USAGE_WINDOW_DAYS})
     * @returns Events, oldest first
     */
    events(vaultPath: string, windowDays?: number): Promise<WikiUsageEvent[]>;
    /**
     * Summarise the window: read counts, misses, unread work.
     *
     * @param vaultPath - Vault root
     * @param windowDays - Window
     * @returns Report
     */
    report(vaultPath: string, windowDays?: number): Promise<WikiUsageReport>;
    /**
     * Pages never read in the window (given the full page list).
     *
     * @param vaultPath - Vault root
     * @param allPages - Vault-relative page paths
     * @param windowDays - Window
     * @returns Unread pages
     */
    unreadPages(vaultPath: string, allPages: string[], windowDays?: number): Promise<string[]>;
    private rotateIfLarge;
}
//# sourceMappingURL=wiki-usage.service.d.ts.map