import type { KnowledgeGraph } from '../contracts/graph.js';
import type { RetrieveResult } from './retrieve.js';
export interface GraphFreshnessMetadata {
    graphVersion: string;
    graphModifiedMs: number;
    graphModifiedAt: string;
}
export interface ResourceFreshnessMetadata extends GraphFreshnessMetadata {
    resourceBytes: number;
    resourceModifiedMs: number;
    resourceModifiedAt: string;
    etag: string;
}
export type GraphContextFreshnessStatus = 'fresh' | 'partially_stale' | 'possibly_stale' | 'stale' | 'missing';
export type SelectedContextFreshnessStatus = 'fresh' | 'possibly_stale' | 'stale' | 'unknown';
export interface GraphContextFreshnessSelection {
    selected_source_files?: readonly string[];
}
export interface GraphContextFreshness {
    status: GraphContextFreshnessStatus;
    graph_path: string;
    graph_version: string | null;
    graph_modified_ms: number | null;
    graph_modified_at: string | null;
    generated_ms: number | null;
    generated_at: string | null;
    madar_version: string;
    indexed_file_count: number;
    changed_source_count: number;
    missing_source_count: number;
    selected_context_status: SelectedContextFreshnessStatus;
    selected_context_file_count: number;
    changed_selected_context_count: number;
    missing_selected_context_count: number;
    changed_outside_selected_context_count: number;
    recommendation: string;
}
export declare function graphFreshnessStatusLabel(status: GraphContextFreshnessStatus): string;
export declare function selectedContextSourceFilesFromRetrieveResult(result: Pick<RetrieveResult, 'matched_nodes' | 'execution_slice' | 'slice'>): string[];
export declare function graphFreshnessMetadata(graphPath: string): GraphFreshnessMetadata;
export declare function analyzeGraphContextFreshness(graphPath: string, graph?: Pick<KnowledgeGraph, 'graph' | 'nodeEntries'>, selection?: GraphContextFreshnessSelection): GraphContextFreshness;
export declare function requireFreshGraph(freshness: Pick<GraphContextFreshness, 'status' | 'recommendation'>, optionName?: string): void;
export declare function requireFreshSelectedContext(freshness: Pick<GraphContextFreshness, 'selected_context_status' | 'recommendation'>, optionName?: string): void;
export declare function resourceFreshnessMetadata(graphPath: string, resourcePath: string): ResourceFreshnessMetadata;
export declare function freshnessAnnotations(metadata: ResourceFreshnessMetadata): Record<string, number | string>;
export declare function graphFreshnessHeaders(metadata: GraphFreshnessMetadata): Record<string, string>;
export declare function resourceFreshnessHeaders(metadata: ResourceFreshnessMetadata): Record<string, string>;