/**
 * Token Supremacy Engine
 *
 * Purpose: Make every token count. This engine runs BEFORE any large context
 * operation and decides what to read, what to skip, what to summarize.
 *
 * Built for AntiGravity to reduce token waste by 50-70%.
 */
import { type AssemblyResult, type BudgetConfig } from './context-assembler.js';
import { type ContextTier } from './tiered-context.js';
export interface FileRef {
    path: string;
    sizeBytes: number;
    lastModified?: number;
}
export type ReadAction = 'skip' | 'outline' | 'partial' | 'full';
export interface FileReadPlan {
    file: FileRef;
    action: ReadAction;
    tier: ContextTier;
    startLine?: number;
    endLine?: number;
    reason: string;
    estimatedTokens: number;
}
export interface ReadingPlan {
    task: string;
    files: FileReadPlan[];
    totalEstimatedTokens: number;
    savings: number;
    sessionBudget: number;
    casCompression?: {
        enabled: boolean;
        compressionRatio: number;
        originalTokens: number;
        compressedTokens: number;
    };
}
export interface SessionSummary {
    sessionId: string;
    timestamp: number;
    files: string[];
    fileSHAs?: Record<string, string>;
    summary: string;
    keyDecisions: string[];
}
export interface ContextDelta {
    added: FileRef[];
    changed: FileRef[];
    unchanged: FileRef[];
    summary?: string;
    memoryContextSummary?: string;
}
export interface TokenBudget {
    total: number;
    allocated: Map<string, number>;
    remaining: number;
}
export interface TokenSupremacyOptions {
    qualityFloor?: number;
}
export declare class TokenSupremacyEngine {
    private static readonly FILE_HEAD_BYTES;
    private static readonly FILE_HEAD_CACHE_LIMIT;
    private sessionBudget;
    private sessionPath;
    private qualityFloor;
    private relevanceCache;
    private relevanceCachePath;
    private contextAssembler;
    private casEngine;
    private fileHeadCache;
    private relevanceScoreCache;
    private _dirsReady;
    constructor(sessionBudget?: number, options?: TokenSupremacyOptions);
    /**
     * Lazily ensure state directories exist and relevance cache is loaded.
     * All callers are async — this is the single init path.
     */
    init(): Promise<void>;
    /**
     * Plan a token-efficient reading strategy for a given task + files.
     */
    /**
     * Plan file reading with optional external file boosts (e.g. from graph memory or n-gram index).
     * fileBoosts: Map<filePath, boostScore> — added to relevance score before thresholding.
     */
    plan(task: string, files: FileRef[], fileBoosts?: Map<string, number>): Promise<ReadingPlan>;
    /**
     * Legacy compatibility wrapper for NexusPrime.
     */
    optimize(context: string[], task: string): Promise<ReadingPlan>;
    differential(prev: SessionSummary, curr: FileRef[]): ContextDelta;
    allocateBudget(workers: Array<{
        id: string;
        estimatedValue: number;
        estimatedCost: number;
    }>, totalBudget?: number): TokenBudget;
    learn(taskType: string, usefulFiles: string[], skipFiles: string[]): Promise<void>;
    private loadRelevanceCache;
    private saveRelevanceCache;
    saveSessionSummary(summary: SessionSummary): Promise<void>;
    loadLatestSessionSummary(): Promise<SessionSummary | null>;
    private extractKeywords;
    private scoreRelevance;
    private readFileHead;
    private readFileHeadKeywords;
    private estimateHotLines;
    private fingerprintFile;
    private isTaskReferenced;
    /**
     * Adjust token budget based on task complexity signals.
     * Complex tasks get +25% budget; simple lookups get -25%.
     */
    private hypertune;
    /**
     * HyperTune Max — Mathematical context assembly using greedy knapsack.
     * Chunks all files at function/class boundaries, scores each chunk
     * by relevance/recency/connectivity/novelty, and selects the optimal
     * combination that maximizes quality within the token budget.
     */
    hypertuneMax(task: string, files: FileRef[], graphConnectivity?: (chunk: {
        source: string;
        label: string;
    }) => number): Promise<{
        plan: ReadingPlan;
        assembly: AssemblyResult;
        budgetConfig: BudgetConfig;
    }>;
}
export declare function formatReadingPlan(plan: ReadingPlan): string;
export declare const createTokenSupremacyEngine: (budget?: number) => TokenSupremacyEngine;
