connectai/src/retrieval/types.ts

/**
 * ============================================================
 * Retrieval Types (검색 결과 통합 타입)
 * 
 * 모든 검색 소스(Brain, Memory, Project, Episode)의 결과를
 * 통합 인터페이스로 정의합니다.
 * ============================================================
 */

export type RetrievalSource =
    | 'brain-trace'        // Second Brain Trace
    | 'brain-memory'       // findRelevantBrainMemory (legacy)
    | 'long-term-memory'   // Long-Term Memory
    | 'medium-term-memory' // Recent session summaries (memoryMediumTermSessions)
    | 'project-memory'     // Project Memory
    | 'procedural-memory'  // Procedural Memory
    | 'episodic-memory'    // Episodic Memory
    | 'project-scan'       // Local Project Path scan
    | 'recent-knowledge';  // Recent Project Knowledge record

export type ConflictSeverity = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH';

export interface RetrievalChunk {
    id: string;
    source: RetrievalSource;
    title: string;
    content: string;
    score: number;           // 0.0 ~ 1.0 normalized
    tokenEstimate: number;   // rough character / 4
    metadata: {
        filePath?: string;
        category?: string;
        isProjectEvidence?: boolean;
        lastUpdated?: number;

        // --- Scoring Intelligence (v2.75.0+) ---
        conflictDetected?: boolean;
        conflictSeverity?: ConflictSeverity;
        queryCoverage?: number;

        // --- Experience Memory ---
        /** True when this chunk comes from a lesson / playbook / qa-finding card in the brain. */
        isLesson?: boolean;
        /** 'lesson' | 'playbook' | 'qa-finding' when isLesson is true. */
        lessonKind?: string;
    };
}

export interface RetrievalResult {
    query: string;
    totalChunks: number;
    selectedChunks: RetrievalChunk[];
    droppedChunks: RetrievalChunk[];
    /** Lesson/playbook/qa-finding chunks that survived the budget — pulled out so callers can inject them prominently. */
    lessonChunks: RetrievalChunk[];
    totalTokensUsed: number;
    contextBudget: number;
    fusionLog: string[];      // 디버그용 융합 로그
}

export interface ContextBudgetConfig {
    totalBudget: number;       // 전체 토큰 예산
    retrievalRatio: number;    // 검색 결과 비율 (0.0~1.0)
    minChunks: number;         // 최소 포함 청크 수
    maxChunks: number;         // 최대 포함 청크 수
}