/**
 * schedules/digest.ts
 *
 * Weekly digest engine — aggregates evaluation reports from a time window
 * and computes trend summaries for notification delivery.
 *
 * The digest answers: "How did our AI literacy scores trend this week?"
 *
 * Data flow:
 * 1. Query Sanity for all reports in the lookback window
 * 2. Group by feature area
 * 3. Compute trend direction and magnitude per area
 * 4. Identify regressions, improvements, and stable areas
 * 5. Return a structured DigestSummary for formatting
 *
 * @see docs/design-docs/report-store/notifications.md
 * @see docs/design-docs/report-store/implementation.md — Phase 5
 */
import type { SanityClient } from "@sanity/client";
/** Trend analysis for a single feature area */
export interface AreaTrend {
    /** Feature area name */
    area: string;
    /** Score at the start of the window */
    firstScore: number;
    /** Score at the end of the window */
    lastScore: number;
    /** Number of data points in the window */
    reportCount: number;
    /** Net score change (last - first) */
    scoreDelta: number;
    /** Trend direction */
    trend: TrendDirection;
}
/** A single report data point from the lookback window */
export interface DigestReportEntry {
    /** ISO timestamp */
    completedAt: string;
    /** Duration in milliseconds */
    durationMs: number;
    /** Evaluation mode */
    mode: string;
    /** Overall average score */
    overallScore: number;
    /** Report ID */
    reportId: string;
    /** Per-area scores */
    scores: {
        feature: string;
        totalScore: number;
    }[];
    /** Documentation source name */
    sourceName: string;
    /** Report tag (schedule name) */
    tag?: string;
}
/** The complete digest summary */
export interface DigestSummary {
    /** Per-area trend breakdown */
    areaTrends: AreaTrend[];
    /** Areas that improved by more than the noise threshold */
    improved: string[];
    /** End of the lookback window (usually "now") */
    lookbackEnd: string;
    /** Start of the lookback window */
    lookbackStart: string;
    /** Overall score delta across the window */
    overallDelta: number;
    /** Overall score at the end of the window */
    overallLatest: number;
    /** Overall trend direction */
    overallTrend: TrendDirection;
    /** Areas that regressed by more than the noise threshold */
    regressed: string[];
    /** Total number of reports in the window */
    reportCount: number;
    /** Areas with score changes within the noise threshold */
    stable: string[];
    /** Total evaluation cost in the window (if available) */
    totalCost?: number;
}
/** Trend direction for a feature area or overall score */
export type TrendDirection = "improving" | "regressing" | "stable";
export interface DigestOptions {
    /** Override the Sanity client (for testing) */
    client?: SanityClient;
    /** Sanity dataset for report queries (independent of eval dataset) */
    dataset?: string;
    /** How many days to look back (default: 7) */
    lookbackDays?: number;
    /** Noise threshold for trend classification (default: 2) */
    noiseThreshold?: number;
    /** Sanity project ID for report queries (independent of eval project) */
    projectId?: string;
    /** Sanity API token */
    token?: string;
}
/**
 * Build a digest summary from a chronologically-ordered list of reports.
 *
 * Pure function — no I/O, fully testable.
 */
export declare function buildDigestSummary(reports: DigestReportEntry[], lookbackStart: Date, lookbackEnd: Date, noiseThreshold?: number): DigestSummary;
/**
 * Classify a score delta into a trend direction.
 */
export declare function classifyTrend(delta: number, threshold?: number): TrendDirection;
/**
 * Generate a digest summary from recent evaluation reports.
 *
 * Queries the Sanity Content Lake for all reports within the lookback
 * window and computes trend analysis per area.
 *
 * @returns DigestSummary, or null if no reports found or on error
 */
export declare function generateDigest(options?: DigestOptions): Promise<DigestSummary | null>;
