cto-ai-cli 6.1.0 → 8.0.0

package/dist/engine/index.d.ts

@@ -43,7 +43,7 @@ interface ProjectGraph {
 interface GraphEdge {
     from: string;
     to: string;
-    type: 'import' | 'export' | 're-export';
+    type: 'import' | 'export' | 're-export' | 'call';
 }
 interface HubNode {
     relativePath: string;
@@ -247,17 +247,6 @@ interface SelectionInput {
 }
 declare function selectContext(input: SelectionInput): Promise<ContextSelection>;
 
-declare function scoreAllFiles(files: AnalyzedFile[], graph: ProjectGraph, weights?: RiskWeights): void;
-declare function scoreFile(file: AnalyzedFile, graph: ProjectGraph, weights?: RiskWeights): number;
-
-declare function calculateCoverage(targetPaths: string[], includedPaths: string[], allFiles: AnalyzedFile[], graph: ProjectGraph, depth?: number): CoverageResult;
-
-declare function getPruneLevelForRisk(riskScore: number): PruneLevel;
-declare function optimizeBudget(files: AnalyzedFile[], budget: number): Promise<BudgetPlan>;
-
-declare function pruneFile(file: AnalyzedFile, level: PruneLevel): Promise<PrunedContent>;
-declare function pruneFiles(files: AnalyzedFile[], levelFn: (file: AnalyzedFile) => PruneLevel): Promise<PrunedContent[]>;
-
 /**
  * TF-IDF Semantic Matching Engine
  *
@@ -283,6 +272,7 @@ declare function pruneFiles(files: AnalyzedFile[], levelFn: (file: AnalyzedFile)
 interface TfIdfIndex {
     documents: Map<string, DocumentVector>;
     idf: Map<string, number>;
+    docFreq: Map<string, number>;
     avgDocLength: number;
     totalDocs: number;
 }
@@ -306,8 +296,10 @@ declare function buildIndex(files: {
 /**
  * Query the index with a task description.
  * Returns files ranked by semantic relevance (BM25 scoring).
+ *
+ * @param expandSynonyms - If true, expands query terms with synonyms for better recall
  */
-declare function query(index: TfIdfIndex, taskDescription: string, maxResults?: number): SemanticMatch[];
+declare function query(index: TfIdfIndex, taskDescription: string, maxResults?: number, expandSynonyms?: boolean): SemanticMatch[];
 /**
  * Compute pairwise similarity between two documents in the index.
  * Useful for finding related files (e.g., "what other files are similar to auth.ts?")
@@ -323,8 +315,177 @@ declare function tokenize(text: string): string[];
  * Boost TF-IDF scores based on file path relevance to the task.
  * This catches cases where the file content doesn't mention the task terms
  * but the file path does (e.g., task "fix auth" → src/auth/middleware.ts).
+ *
+ * Scoring:
+ *   - Directory segment match: 0.4 per term (structural relevance)
+ *   - Filename match: 0.25 per term (weaker — many files share names)
+ *   - Multiple directory matches multiply: "cache" + "seller" in path = 0.8
  */
 declare function boostByPath(matches: SemanticMatch[], allFiles: string[], taskDescription: string): SemanticMatch[];
+declare function boostByLayer(matches: SemanticMatch[], allFiles: string[], taskDescription: string): SemanticMatch[];
+/**
+ * Boost BM25 results by import chain proximity.
+ *
+ * Problem: In Java/TS projects, interfaces and type files have minimal content
+ * (8-20 lines). BM25 can't rank them because there aren't enough tokens.
+ * But they are IMPORTED by files that DO rank well.
+ *
+ * Solution: For each top-K BM25 result, find files it imports and files that
+ * import it. Give those a score boost proportional to the parent's score.
+ * Files imported by MULTIPLE top matches get proportionally more boost.
+ *
+ * @param matches - BM25 results (already scored)
+ * @param dependencies - Map of filePath → files it imports
+ * @param topK - How many top matches to expand (default: 10)
+ * @param boostFactor - How much of the parent's score to transfer (default: 0.4)
+ */
+declare function boostByImports(matches: SemanticMatch[], dependencies: Map<string, string[]>, topK?: number, boostFactor?: number): SemanticMatch[];
+/**
+ * Reciprocal Rank Fusion — state-of-the-art multi-signal ranking.
+ * Used by Elasticsearch 8, Pinecone, Cohere.
+ *
+ * Problem: Additive boosting (BM25 + path + import) saturates at 1.0.
+ * When multiple boosts stack, all top files get score=1.0 and ranking
+ * becomes arbitrary. This is why irrelevant files appear in top-K.
+ *
+ * Solution: Rank files independently by each signal, then fuse rankings.
+ * RRF_score(d) = Σ weight_i / (k + rank_i(d))
+ * where k=60 (smoothing constant, standard in literature).
+ *
+ * Files that rank well across MULTIPLE signals naturally float to the top.
+ * No saturation, no arbitrary caps.
+ *
+ * @param bm25Matches - Raw BM25 results
+ * @param allFiles - All file paths in the project
+ * @param taskDescription - The query/task
+ * @param dependencies - Import graph
+ * @param k - RRF smoothing constant (default: 60, standard)
+ */
+declare function reciprocalRankFusion$1(bm25Matches: SemanticMatch[], allFiles: string[], taskDescription: string, dependencies: Map<string, string[]>, k?: number): SemanticMatch[];
+
+/**
+ * Persistent TF-IDF Index Cache
+ *
+ * Problem: Building a TF-IDF index reads every source file and tokenizes it.
+ * For a 50K-file repo, that's 5-10 seconds per query. With 20K devs running
+ * queries concurrently, re-indexing on every call is unacceptable.
+ *
+ * Solution: Persist the index to disk with per-file mtime tracking.
+ * On subsequent queries, only re-index files that changed since last build.
+ *
+ * Storage: .cto/index-cache.json
+ *   {
+ *     version: 2,
+ *     builtAt: ISO timestamp,
+ *     files: { [relativePath]: { mtime: number, terms: { [term]: count }, length: number } },
+ *     idf: { [term]: number },
+ *     avgDocLength: number,
+ *     totalDocs: number,
+ *   }
+ *
+ * Invalidation:
+ *   - Per-file: mtime changed → re-tokenize that file
+ *   - New files: not in cache → tokenize and add
+ *   - Deleted files: in cache but not on disk → remove
+ *   - Version bump: cache format changed → full rebuild
+ *
+ * The IDF values are recomputed after any incremental update because
+ * document frequency changes affect all terms globally.
+ */
+
+interface IndexCacheStats {
+    /** Total files in the index */
+    totalFiles: number;
+    /** Files that were re-indexed (changed or new) */
+    updatedFiles: number;
+    /** Files removed from cache (deleted from disk) */
+    removedFiles: number;
+    /** Files reused from cache (unchanged) */
+    cachedFiles: number;
+    /** Whether the cache existed before this build */
+    cacheHit: boolean;
+    /** Time to build/update the index (ms) */
+    buildTimeMs: number;
+}
+/**
+ * Build or update a TF-IDF index with disk caching.
+ *
+ * First call: builds full index and writes cache to .cto/index-cache.json
+ * Subsequent calls: reads cache, updates only changed files, rewrites cache
+ *
+ * @param projectPath - Root of the project (for .cto/ directory)
+ * @param files - All files to index: { relativePath, absolutePath, content? }
+ *   If content is provided, it's used directly. Otherwise, the file is read from disk.
+ * @returns The TF-IDF index + stats about cache hits/misses
+ */
+declare function buildIndexCached(projectPath: string, files: {
+    relativePath: string;
+    absolutePath: string;
+    content?: string;
+}[]): {
+    index: TfIdfIndex;
+    stats: IndexCacheStats;
+};
+/**
+ * Invalidate the entire cache (force full rebuild on next call).
+ */
+declare function invalidateCache(projectPath: string): void;
+/**
+ * Get cache stats without rebuilding.
+ */
+declare function getCacheInfo(projectPath: string): {
+    exists: boolean;
+    fileCount: number;
+    builtAt: string | null;
+};
+
+/**
+ * Query Intent Parsing
+ *
+ * Before searching, parse the task description into a structured intent:
+ *   - action: what the developer wants to do (fix, add, refactor, trace)
+ *   - entities: domain objects mentioned (cache, user, order, chart)
+ *   - operations: specific operations (delete, create, update, validate)
+ *   - layers: architectural layers mentioned (controller, service, repository)
+ *   - qualifiers: narrowing terms (on KVS, in admin, for seller)
+ *
+ * This structured intent enables:
+ *   1. Weighted search: entities get higher BM25 weight than qualifiers
+ *   2. Layer-aware expansion: if service layer mentioned, also search use cases
+ *   3. Better multi-hop: expand through specific layers, not randomly
+ *   4. Smarter chunk selection: prioritize chunks matching entities + operations
+ */
+interface QueryIntent {
+    original: string;
+    action: ActionType;
+    entities: string[];
+    operations: string[];
+    layers: ArchLayer[];
+    qualifiers: string[];
+    confidence: number;
+}
+type ActionType = 'fix' | 'add' | 'refactor' | 'trace' | 'test' | 'docs' | 'remove' | 'optimize' | 'unknown';
+type ArchLayer = 'endpoint' | 'usecase' | 'service' | 'repository' | 'cache' | 'client' | 'model' | 'config' | 'queue' | 'middleware';
+/**
+ * Parse a task description into a structured query intent.
+ *
+ * @param task - Raw task description from the developer
+ * @returns Structured QueryIntent with action, entities, operations, layers
+ */
+declare function parseQueryIntent(task: string): QueryIntent;
+/**
+ * Build a weighted search query from the parsed intent.
+ * Entities get highest weight, operations next, qualifiers lowest.
+ *
+ * @param intent - Parsed query intent
+ * @returns Weighted query string with important terms repeated
+ */
+declare function buildWeightedQuery(intent: QueryIntent): string;
+/**
+ * Get suggested architectural layers to search based on the intent.
+ * If the developer mentions "service", we should also look at use cases and repositories.
+ */
+declare function expandLayers(layers: ArchLayer[]): ArchLayer[];
 
 /**
  * Usage Learner — Gets smarter with every use.
@@ -403,12 +564,1210 @@ declare function getLearnerStats(model: LearnerModel): {
  */
 declare function extractPattern(filePath: string): string;
 
+/**
+ * Multi-Repo Context Selection
+ *
+ * Discovers sibling repositories in a workspace and queries them
+ * for relevant files when selecting context for a task.
+ *
+ * How it works:
+ *   1. Discover sibling repos (scan parent dir or use explicit paths)
+ *   2. For each sibling: list source files, read contents, build TF-IDF index
+ *   3. Query each sibling's index with the task description
+ *   4. Return ranked matches with repo attribution
+ *
+ * This is NOT the cross-repo learning system (cross-repo.ts).
+ * This is actual multi-repo file discovery and querying.
+ */
+interface SiblingRepo {
+    /** Absolute path to the repo root */
+    path: string;
+    /** Short name (directory name) */
+    name: string;
+    /** Detected stack (from package.json, tsconfig, etc.) */
+    stack: string[];
+    /** Number of source files found */
+    fileCount: number;
+}
+interface SiblingMatch {
+    /** Which sibling repo this file belongs to */
+    repoName: string;
+    /** Absolute path to the repo */
+    repoPath: string;
+    /** Relative path within the sibling repo */
+    relativePath: string;
+    /** Absolute path to the file */
+    absolutePath: string;
+    /** Semantic relevance score (0-1) */
+    score: number;
+    /** File content */
+    content: string;
+    /** Estimated token count */
+    tokens: number;
+}
+interface MultiRepoResult {
+    /** Sibling repos that were discovered/used */
+    siblings: SiblingRepo[];
+    /** Top matches from sibling repos, ranked by score */
+    matches: SiblingMatch[];
+    /** Total time spent indexing + querying (ms) */
+    timeMs: number;
+}
+/**
+ * Discover sibling repositories by scanning the parent directory.
+ * A directory is a "repo" if it contains a known project marker file.
+ */
+declare function discoverSiblingRepos(projectPath: string): SiblingRepo[];
+/**
+ * Query sibling repos for files relevant to a task.
+ *
+ * For each sibling:
+ *   1. List source files
+ *   2. Build TF-IDF index from file contents
+ *   3. Query with task description
+ *   4. Return top matches with content
+ *
+ * @param siblings - Sibling repos to query (from discoverSiblingRepos or explicit paths)
+ * @param task - Task description to match against
+ * @param maxPerRepo - Max matches per repo (default 5)
+ * @param minScore - Minimum semantic score to include (default 0.3)
+ */
+declare function querySiblingRepos(siblings: SiblingRepo[], task: string, maxPerRepo?: number, minScore?: number): MultiRepoResult;
+/**
+ * Parse explicit repo paths from a comma-separated string.
+ * Resolves relative paths against the current project's parent directory.
+ */
+declare function parseSiblingPaths(pathsStr: string, projectPath: string): SiblingRepo[];
+/**
+ * Render multi-repo results for CLI output.
+ */
+declare function renderMultiRepoSummary(result: MultiRepoResult): string;
+
+/**
+ * Shared Context Pipeline
+ *
+ * Single function that runs the full context selection pipeline:
+ *   read files → build TF-IDF index → query → boost → load learner → selectContext
+ *
+ * Used by both CLI and MCP server. No duplication.
+ */
+
+interface ContextPipelineInput {
+    projectPath: string;
+    task: string;
+    analysis: ProjectAnalysis;
+    budget?: number;
+    /** Optional sibling repos for cross-repo context */
+    siblingRepos?: SiblingRepo[];
+}
+interface ContextPipelineResult {
+    selection: ContextSelection;
+    taskType: string;
+    fileContentMap: Map<string, string>;
+    semanticMap: Map<string, SemanticMatch>;
+    learnerMap: Map<string, LearnerBoost>;
+    /** Parsed query intent for downstream chunk selection */
+    queryIntent: QueryIntent;
+    /** Cross-repo results (only present if siblingRepos were provided) */
+    multiRepo?: MultiRepoResult;
+    /** Index cache stats (how many files were cached vs rebuilt) */
+    indexCacheStats?: IndexCacheStats;
+}
+/**
+ * Run the full context selection pipeline.
+ * One function, used everywhere. No copy-paste.
+ */
+declare function runContextPipeline(input: ContextPipelineInput): Promise<ContextPipelineResult>;
+
+declare function scoreAllFiles(files: AnalyzedFile[], graph: ProjectGraph, weights?: RiskWeights): void;
+declare function scoreFile(file: AnalyzedFile, graph: ProjectGraph, weights?: RiskWeights): number;
+
+declare function calculateCoverage(targetPaths: string[], includedPaths: string[], allFiles: AnalyzedFile[], graph: ProjectGraph, depth?: number): CoverageResult;
+
+declare function getPruneLevelForRisk(riskScore: number): PruneLevel;
+declare function optimizeBudget(files: AnalyzedFile[], budget: number): Promise<BudgetPlan>;
+
+declare function pruneFile(file: AnalyzedFile, level: PruneLevel): Promise<PrunedContent>;
+declare function pruneFiles(files: AnalyzedFile[], levelFn: (file: AnalyzedFile) => PruneLevel): Promise<PrunedContent[]>;
+
+/**
+ * Synonym Expansion for Query Enhancement
+ *
+ * Zero dependencies. Zero ML. Pure lookup tables.
+ *
+ * Expands query terms with domain-specific synonyms to improve recall
+ * without requiring exact textual overlap. This bridges the gap between
+ * BM25's lexical matching and full semantic embeddings.
+ *
+ * Example:
+ *   query("database") → ["database", "db", "repository", "orm", "sql", "prisma"]
+ *   query("auth") → ["auth", "authentication", "login", "session", "jwt", "token"]
+ *
+ * Why this works:
+ *   - Captures common abbreviations (db, auth, repo)
+ *   - Captures technology-specific terms (prisma, jwt, redis)
+ *   - Captures conceptual relationships (cache → redis, memcached)
+ *   - Deterministic, predictable, maintainable
+ *
+ * Trade-offs vs embeddings:
+ *   + Zero dependencies, zero latency, zero cost
+ *   + Deterministic (same query → same expansion)
+ *   + Easy to debug and extend
+ *   - Limited to manually curated vocabulary
+ *   - Doesn't capture novel relationships
+ *   - Estimated +5-8% recall vs embeddings' +10-15%
+ */
+interface SynonymExpansion {
+    original: string;
+    expanded: string[];
+}
+/**
+ * Expand a single term with its synonyms.
+ * Returns the original term plus all related terms.
+ */
+declare function expandTerm(term: string): string[];
+/**
+ * Expand all terms in a query.
+ * Deduplicates the result.
+ */
+declare function expandQuery(query: string): string[];
+/**
+ * Get expansion details for debugging/telemetry.
+ */
+declare function getExpansionDetails(query: string): SynonymExpansion[];
+/**
+ * Get statistics about the synonym dictionary.
+ */
+declare function getSynonymStats(): {
+    canonicalTerms: number;
+    totalSynonyms: number;
+    avgSynonymsPerTerm: number;
+    bidirectionalEntries: number;
+};
+
+/**
+ * Closed-Loop A/B Testing Engine
+ *
+ * The missing piece: the feedback system records data but never closes the loop.
+ * This module adds real experimentation:
+ *
+ *   1. Define experiments with control + variant strategies
+ *   2. Assign requests to groups (deterministic hashing for consistency)
+ *   3. Collect outcomes per group
+ *   4. Compute statistical significance (z-test for proportions)
+ *   5. Auto-promote winning variants when significance threshold met
+ *
+ * Example experiment:
+ *   - Control: default composite scoring (semantic 0.55, risk 0.25, learner 0.20)
+ *   - Variant: reranker-heavy scoring (reranker 0.70, risk 0.15, learner 0.15)
+ *   - Metric: acceptance rate
+ *   - Significance: p < 0.05
+ *
+ * Storage: .cto/experiments.json
+ * Design: Pure functions. No external deps. Deterministic assignment.
+ */
+interface Experiment {
+    /** Unique experiment ID */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** What we're testing */
+    description: string;
+    /** Current status */
+    status: 'running' | 'concluded' | 'paused';
+    /** When the experiment started */
+    startedAt: string;
+    /** When it concluded (if applicable) */
+    concludedAt?: string;
+    /** Traffic split: 0.5 = 50/50 */
+    trafficSplit: number;
+    /** Minimum observations per group before significance test */
+    minObservations: number;
+    /** P-value threshold for significance */
+    significanceThreshold: number;
+    /** Control group config */
+    control: ExperimentGroup;
+    /** Variant group config */
+    variant: ExperimentGroup;
+    /** Conclusion (when experiment ends) */
+    conclusion?: ExperimentConclusion;
+}
+interface ExperimentGroup {
+    /** Group name */
+    name: string;
+    /** Strategy parameters (passed to the engine) */
+    params: Record<string, unknown>;
+    /** Collected metrics */
+    metrics: GroupMetrics;
+}
+interface GroupMetrics {
+    /** Total observations */
+    total: number;
+    /** Successful outcomes (accepted) */
+    successes: number;
+    /** Accept rate = successes / total */
+    acceptRate: number;
+    /** Average time to accept (ms) */
+    avgTimeToAccept: number;
+    /** Compilable rate */
+    compilableRate: number;
+    /** Sum of time values (for running average) */
+    timeSum: number;
+    /** Count of compilable results */
+    compilableCount: number;
+}
+interface ExperimentConclusion {
+    /** Which group won */
+    winner: 'control' | 'variant' | 'no_difference';
+    /** Observed p-value */
+    pValue: number;
+    /** Effect size (difference in accept rates) */
+    effectSize: number;
+    /** Confidence interval for effect size */
+    confidenceInterval: [number, number];
+    /** Human-readable summary */
+    summary: string;
+}
+interface AssignmentResult {
+    /** Which group the request was assigned to */
+    group: 'control' | 'variant';
+    /** The strategy params for this group */
+    params: Record<string, unknown>;
+    /** Experiment ID for tracking */
+    experimentId: string;
+}
+declare function loadExperiments(projectPath: string): Experiment[];
+declare function saveExperiments(projectPath: string, experiments: Experiment[]): void;
+declare function createExperiment(id: string, name: string, description: string, controlParams: Record<string, unknown>, variantParams: Record<string, unknown>, options?: {
+    trafficSplit?: number;
+    minObservations?: number;
+    significanceThreshold?: number;
+}): Experiment;
+/**
+ * Assign a request to control or variant group.
+ * Uses deterministic hashing: same (experiment_id, task) → same group.
+ * This ensures consistency (retries get the same group).
+ */
+declare function assignGroup(experiment: Experiment, task: string): AssignmentResult | null;
+/**
+ * Record an outcome for an experiment group.
+ * Updates running statistics and checks for significance.
+ */
+declare function recordOutcome(experiment: Experiment, group: 'control' | 'variant', outcome: {
+    accepted: boolean;
+    compilable?: boolean;
+    timeToAcceptMs?: number;
+}): Experiment;
+interface SignificanceResult {
+    /** Two-sided p-value */
+    pValue: number;
+    /** Z-score */
+    zScore: number;
+    /** Effect size: variant rate - control rate */
+    effectSize: number;
+    /** 95% confidence interval for effect size */
+    confidenceInterval: [number, number];
+    /** Whether the result is significant at the experiment's threshold */
+    significant: boolean;
+}
+/**
+ * Two-proportion z-test for A/B testing.
+ *
+ * H0: p_control = p_variant
+ * H1: p_control ≠ p_variant (two-sided)
+ *
+ * This is the standard test for comparing conversion rates.
+ */
+declare function testSignificance(experiment: Experiment): SignificanceResult;
+/**
+ * Get the active experiment for this project (if any).
+ */
+declare function getActiveExperiment(experiments: Experiment[]): Experiment | null;
+/**
+ * Get all concluded experiments with their results.
+ */
+declare function getConcludedExperiments(experiments: Experiment[]): Experiment[];
+/**
+ * Render experiment summary for CLI/dashboard.
+ */
+declare function renderExperimentSummary(experiment: Experiment): string;
+
+/**
+ * Polyglot Dependency Graph — Import Parsing for Python, Go, Java, Rust
+ *
+ * Problem: The existing graph.ts uses ts-morph (AST) which only handles TS/JS.
+ * For a 20K-dev org with Java, Python, Go, Rust — the dependency graph is empty.
+ * No graph → no hub detection → no risk scoring → useless context selection.
+ *
+ * Solution: Regex-based import parsers for each language. Not AST-accurate, but
+ * good enough for dependency graph construction. We don't need perfect resolution;
+ * we need to know "file A probably depends on file B" for hub/risk scoring.
+ *
+ * Each parser:
+ *   1. Extracts import specifiers from file content using regex
+ *   2. Resolves specifiers to relative file paths within the project
+ *   3. Returns edges: { from: relativePath, to: relativePath }
+ *
+ * Supported languages:
+ *   - Python: import x, from x import y, relative imports
+ *   - Go: import "pkg", import ( "pkg" ... )
+ *   - Java: import com.example.Foo, package declaration
+ *   - Rust: use crate::x, mod x, use super::x
+ *
+ * Design: Pure functions. No external deps. Deterministic.
+ */
+
+type SupportedLanguage = 'python' | 'go' | 'java' | 'rust' | 'typescript';
+interface ImportSpec {
+    /** The raw import specifier as written in the source */
+    raw: string;
+    /** Whether this is a relative import */
+    isRelative: boolean;
+}
+declare function detectLanguage(filePath: string): SupportedLanguage | null;
+/**
+ * Parse imports from a non-TS file and resolve to project-relative paths.
+ * Returns dependency edges for the project graph.
+ *
+ * @param filePath - Absolute path to the source file
+ * @param relativePath - Project-relative path (e.g., "src/auth/login.py")
+ * @param projectPath - Absolute path to the project root
+ * @param allRelativePaths - Set of all file paths in the project (for resolution)
+ * @param content - Optional file content (read from disk if not provided)
+ */
+declare function parseImports(filePath: string, relativePath: string, projectPath: string, allRelativePaths: Set<string>, content?: string): GraphEdge[];
+/**
+ * Parse imports for ALL non-TS files in a project.
+ * Call this alongside ts-morph's buildProjectGraph for TS files.
+ */
+declare function parseAllPolyglotImports(files: {
+    relativePath: string;
+    absolutePath: string;
+    content?: string;
+}[], projectPath: string): GraphEdge[];
+/**
+ * Estimate cyclomatic complexity from source code using regex.
+ * Not AST-accurate but good enough for risk scoring.
+ */
+declare function estimateComplexity(content: string, lang: SupportedLanguage): number;
+
+/**
+ * Multi-Stage Reranker
+ *
+ * The problem: BM25 retrieval gets 54% precision. Adding risk scoring drops it
+ * to 33% because high-risk irrelevant files fill the budget.
+ *
+ * The solution: a 3-stage pipeline that turns BM25 candidates into a precision-
+ * optimized selection:
+ *
+ *   Stage 1: RETRIEVE (BM25 top-K) — already done by tfidf.ts
+ *   Stage 2: RERANK (multi-signal rescoring)
+ *     - Term coverage: what fraction of UNIQUE query terms does the file match?
+ *     - Term specificity: are the matched terms rare (high IDF) or generic?
+ *     - Bigram proximity: do query terms appear near each other in the file?
+ *     - Dependency signal: is this file in the dependency cone of a top match?
+ *     - Path relevance: does the file path match query terms?
+ *   Stage 3: QUALITY GATE (adaptive cutoff)
+ *     - Hard floor: files below absolute threshold are excluded
+ *     - Elbow detection: find the natural drop-off point in scores
+ *     - Don't fill budget with noise — stop when quality degrades
+ *
+ * This is a cross-encoder-like approach using hand-crafted features instead
+ * of a neural model. No ML dependencies. Deterministic.
+ */
+
+interface RerankInput {
+    /** Task description */
+    task: string;
+    /** BM25 candidates from tfidf.query() */
+    candidates: SemanticMatch[];
+    /** The TF-IDF index (for IDF weights) */
+    index: TfIdfIndex;
+    /** File contents for bigram proximity analysis */
+    fileContents: Map<string, string>;
+    /** Dependency edges: from → to[] */
+    dependencies: Map<string, string[]>;
+    /** All file paths in the project */
+    allFilePaths: string[];
+}
+interface RerankResult {
+    /** Reranked and filtered files — only high-quality matches */
+    files: RerankedFile[];
+    /** Files that were cut by the quality gate */
+    filtered: FilteredFile[];
+    /** The quality threshold used */
+    qualityThreshold: number;
+    /** Telemetry data for observability and debugging */
+    telemetry: RerankTelemetry;
+}
+interface RerankTelemetry {
+    /** Total candidates received from BM25 */
+    candidatesIn: number;
+    /** Files that passed the quality gate */
+    candidatesOut: number;
+    /** Files filtered out */
+    candidatesFiltered: number;
+    /** Timing in milliseconds */
+    durationMs: number;
+    /** Signal weight configuration used */
+    weights: typeof WEIGHTS;
+    /** Quality gate thresholds used */
+    gateConfig: {
+        absoluteFloor: number;
+        elbowDropRatio: number;
+        minTermCoverage: number;
+    };
+    /** Aggregate signal statistics across all candidates (before gate) */
+    signalStats: {
+        termCoverage: {
+            min: number;
+            max: number;
+            mean: number;
+            median: number;
+        };
+        termSpecificity: {
+            min: number;
+            max: number;
+            mean: number;
+            median: number;
+        };
+        bigramProximity: {
+            min: number;
+            max: number;
+            mean: number;
+            median: number;
+        };
+        dependencySignal: {
+            min: number;
+            max: number;
+            mean: number;
+            median: number;
+        };
+        pathRelevance: {
+            min: number;
+            max: number;
+            mean: number;
+            median: number;
+        };
+    };
+    /** Filter reason breakdown: reason → count */
+    filterReasons: Record<string, number>;
+    /** Score distribution: [min, p25, p50, p75, max] across all scored candidates */
+    scoreDistribution: [number, number, number, number, number];
+    /** Number of unique query terms */
+    queryTermCount: number;
+    /** Size of the dependency relevance cone */
+    relevanceConeSize: number;
+}
+interface RerankedFile {
+    filePath: string;
+    /** Final reranked score (0-1) */
+    score: number;
+    /** Original BM25 score */
+    bm25Score: number;
+    /** Individual signal scores */
+    signals: {
+        termCoverage: number;
+        termSpecificity: number;
+        bigramProximity: number;
+        dependencySignal: number;
+        pathRelevance: number;
+    };
+}
+interface FilteredFile {
+    filePath: string;
+    score: number;
+    reason: string;
+}
+declare const WEIGHTS: {
+    termCoverage: number;
+    termSpecificity: number;
+    bigramProximity: number;
+    dependencySignal: number;
+    pathRelevance: number;
+};
+/**
+ * Rerank BM25 candidates using multi-signal scoring + quality gate.
+ * Returns only files that pass the quality threshold.
+ */
+declare function rerank(input: RerankInput): RerankResult;
+
 declare function countTokensTiktoken(text: string): number;
 declare function countTokensChars4(sizeInBytes: number): number;
 declare function estimateTokens(content: string, sizeInBytes: number, method?: 'chars4' | 'tiktoken'): number;
 declare function estimateFileTokens(filePath: string, method?: 'chars4' | 'tiktoken'): Promise<number>;
 declare function freeEncoder(): void;
 
+/**
+ * Corpus-Learned Semantic Expansion
+ *
+ * Zero dependencies. Pure math.
+ *
+ * Problem: BM25 is lexical — "fix authentication" won't match a file about
+ * "OAuth2 token validator" because the terms don't overlap.
+ *
+ * Solution: Learn term associations from the codebase itself using
+ * Pointwise Mutual Information (PMI). If "auth" and "oauth" frequently
+ * co-occur in the same files, they're semantically related.
+ *
+ * How it works:
+ *   1. Build a co-occurrence matrix from the TF-IDF index
+ *   2. Compute PMI for each term pair: PMI(a,b) = log(P(a,b) / (P(a)·P(b)))
+ *   3. For each query term, find the top-K associated terms
+ *   4. Expand the query with these terms (weighted by PMI strength)
+ *
+ * This bridges vocabulary gaps like:
+ *   - "auth" → "oauth", "token", "jwt", "credential"
+ *   - "cache" → "redis", "ttl", "invalidat", "evict"
+ *   - "order" → "purchas", "cart", "checkout"
+ *
+ * Performance: O(|query| × |vocab|) per query — fast because we only
+ * compute PMI for query terms, not the full matrix.
+ *
+ * Also provides dense document embeddings via Random Indexing (Kanerva 2000):
+ *   - Each term gets a random sparse vector
+ *   - Document = sum of TF-IDF-weighted term vectors
+ *   - Cosine similarity captures latent semantic relationships
+ *   - Proven to approximate SVD/LSA without matrix decomposition
+ */
+
+interface SemanticExpansion {
+    /** Original query terms */
+    original: string[];
+    /** Expanded terms with weights (includes originals at weight 1.0) */
+    expanded: Map<string, number>;
+    /** Which expansions were added and why */
+    expansions: {
+        term: string;
+        source: string;
+        pmi: number;
+        weight: number;
+    }[];
+}
+interface CorpusEmbeddings {
+    /** Document embeddings: filePath → dense vector */
+    documents: Map<string, Float64Array>;
+    /** Embedding dimension */
+    dimension: number;
+    /** Term → random index vector (sparse representation) */
+    termVectors: Map<string, {
+        indices: number[];
+        signs: number[];
+    }>;
+}
+/**
+ * Expand query terms using corpus-learned PMI associations.
+ *
+ * For each query term, finds terms that co-occur with it significantly
+ * more than chance would predict. These are added to the query with
+ * reduced weight.
+ *
+ * @param index - TF-IDF index (provides term frequencies and doc frequencies)
+ * @param queryTerms - Tokenized query terms
+ * @param topK - Max expansions per query term (default: 3)
+ * @param minPmi - Minimum PMI score to be considered associated (default: 1.0)
+ * @param expansionWeight - Weight multiplier for expanded terms (default: 0.5)
+ */
+declare function expandQueryWithPMI(index: TfIdfIndex, queryTerms: string[], topK?: number, minPmi?: number, expansionWeight?: number): SemanticExpansion;
+/**
+ * Build dense document embeddings using Random Indexing.
+ *
+ * Random Indexing (Kanerva 2000, Sahlgren 2005) is a lightweight alternative
+ * to LSA/SVD that builds document embeddings incrementally:
+ *
+ *   1. Assign each vocabulary term a random sparse vector (index vector)
+ *      with mostly zeros and a few +1/-1 entries
+ *   2. A document's embedding = sum of TF-IDF-weighted index vectors of its terms
+ *   3. Query embedding = sum of index vectors of query terms
+ *   4. Similarity = cosine(query_embedding, doc_embedding)
+ *
+ * Proven to approximate SVD/LSA (Achlioptas 2003, Johnson-Lindenstrauss lemma).
+ * O(docs × terms × nnz) where nnz is the sparsity of index vectors (~6).
+ *
+ * @param index - TF-IDF index
+ * @param dimension - Embedding dimension (default: 128)
+ * @param nnz - Non-zero entries per index vector (default: 6)
+ * @param seed - Random seed for reproducibility (default: 42)
+ */
+declare function buildCorpusEmbeddings(index: TfIdfIndex, dimension?: number, nnz?: number, seed?: number): CorpusEmbeddings;
+/**
+ * Compute embedding for a query string.
+ */
+declare function embedQuery(query: string, embeddings: CorpusEmbeddings): Float64Array;
+/**
+ * Rank all documents by embedding similarity to a query.
+ * Returns sorted list of (filePath, similarity) pairs.
+ */
+declare function queryByEmbedding(queryVec: Float64Array, embeddings: CorpusEmbeddings, maxResults?: number): {
+    filePath: string;
+    similarity: number;
+}[];
+
+/**
+ * AST-Aware Tokenizer for Java, Python, Go
+ *
+ * Zero dependencies. Regex-based structural extraction.
+ *
+ * Problem: The generic tokenizer splits on whitespace and camelCase but doesn't
+ * understand language constructs. A Java file with `@Repository` annotation and
+ * `implements CacheService` has critical structural information that BM25 misses.
+ *
+ * Solution: Extract high-value structural tokens from source code:
+ *   - Class/interface/enum names (weighted 3×)
+ *   - Method/function names (weighted 2×)
+ *   - Annotations (@Repository, @Service, @Controller) as layer indicators
+ *   - Inheritance (extends/implements) as relationship signals
+ *   - Package/module declarations as structural context
+ *
+ * These tokens are prepended to the regular content, boosting their TF-IDF weight.
+ * The result: files with structurally relevant names rank higher even if their
+ * content is minimal (e.g., Java interfaces).
+ */
+interface StructuralTokens {
+    /** Class/interface/enum names found */
+    classNames: string[];
+    /** Method/function names found */
+    methodNames: string[];
+    /** Annotations found (without @) */
+    annotations: string[];
+    /** Parent classes/interfaces (extends/implements) */
+    parents: string[];
+    /** Package/module name */
+    packageName: string | null;
+    /** Detected language */
+    language: 'java' | 'python' | 'go' | 'typescript' | 'unknown';
+}
+/**
+ * Extract structural tokens from source code.
+ * Language is detected from file extension or content patterns.
+ */
+declare function extractStructuralTokens(content: string, filePath: string): StructuralTokens;
+/**
+ * Augment file content with structural tokens for better BM25 indexing.
+ *
+ * Prepends high-value structural information to the content:
+ *   - Class names repeated 3× (boosted weight)
+ *   - Method names repeated 2×
+ *   - Annotation-derived layer terms
+ *   - Parent class/interface names
+ *
+ * This causes BM25 to rank files higher when the query matches their
+ * structural identity, not just their content.
+ */
+declare function augmentContentWithStructure(content: string, filePath: string): string;
+/**
+ * Get structural summary for a file (for debugging/telemetry).
+ */
+declare function getStructuralSummary(content: string, filePath: string): string;
+
+/**
+ * Feedback-Driven Weight Tuner
+ *
+ * Zero dependencies. Bayesian optimization of signal weights.
+ *
+ * Problem: RRF and boost weights are static (BM25=0.40, path=0.25, import=0.20,
+ * className=0.15). Different codebases have different characteristics — a Java
+ * monolith benefits more from import boost, a microservice from path boost.
+ *
+ * Solution: Record which files the developer actually uses after context selection.
+ * Use this feedback to optimize weights per project using Thompson Sampling:
+ *
+ *   1. Each weight has a Beta distribution prior: Beta(α, β)
+ *   2. When a file ranked high by signal X is accepted → α_X++
+ *   3. When a file ranked high by signal X is rejected → β_X++
+ *   4. Sample from each Beta to get optimistic weights
+ *   5. Normalize to sum to 1.0
+ *
+ * This is the same algorithm used by recommendation systems at Netflix, Spotify.
+ * Converges to optimal weights in ~20-50 selections.
+ *
+ * Storage: .cto/weight-tuner.json — <2KB
+ * Integrates with existing A/B testing infrastructure.
+ */
+interface SignalWeight {
+    /** Signal name */
+    name: string;
+    /** Default weight (fallback) */
+    defaultWeight: number;
+    /** Bayesian prior: alpha (success count) */
+    alpha: number;
+    /** Bayesian prior: beta (failure count) */
+    beta: number;
+}
+interface WeightTunerModel {
+    version: 1;
+    updatedAt: string;
+    signals: SignalWeight[];
+    totalFeedback: number;
+    /** History of recent weight snapshots for trend analysis */
+    history: {
+        timestamp: string;
+        weights: Record<string, number>;
+    }[];
+}
+interface TunedWeights {
+    /** Optimized weights (sum to 1.0) */
+    weights: Record<string, number>;
+    /** Confidence: 0 = pure default, 1 = well-tuned (>50 observations) */
+    confidence: number;
+    /** Whether we're using learned weights or defaults */
+    source: 'learned' | 'default';
+}
+/**
+ * Load the weight tuner model from disk.
+ * Returns fresh model with default priors if none exists.
+ */
+declare function loadWeightTuner(projectPath: string): WeightTunerModel;
+/**
+ * Save the weight tuner model to disk.
+ */
+declare function saveWeightTuner(projectPath: string, model: WeightTunerModel): void;
+/**
+ * Create a fresh model with uniform priors.
+ * Alpha=1, Beta=1 is the non-informative prior (uniform distribution).
+ */
+declare function createFreshModel(): WeightTunerModel;
+/**
+ * Record feedback: which signal contributed to each accepted/rejected file.
+ *
+ * @param model - Current tuner model
+ * @param feedback - Array of (signalName, accepted) pairs
+ */
+declare function recordFeedback(model: WeightTunerModel, feedback: {
+    signal: string;
+    accepted: boolean;
+}[]): WeightTunerModel;
+/**
+ * Get optimized weights using Thompson Sampling.
+ *
+ * For each signal, sample from its Beta(α, β) distribution.
+ * The mean of Beta(α, β) is α/(α+β), which converges to the
+ * true acceptance rate as we collect more feedback.
+ *
+ * With few observations, falls back to default weights.
+ */
+declare function getOptimizedWeights(model: WeightTunerModel): TunedWeights;
+/**
+ * Determine which signal contributed most to a file's ranking.
+ * Used to attribute feedback to the right signal.
+ *
+ * @param filePath - The file being evaluated
+ * @param signalRanks - Map of signal name → rank of this file in that signal's ranking
+ * @returns The signal name that ranked this file highest
+ */
+declare function attributeToSignal(signalRanks: Record<string, number>): string;
+/**
+ * Render weight tuner status for CLI output.
+ */
+declare function renderWeightStatus(model: WeightTunerModel): string;
+
+/**
+ * Cross-File Call Graph Analysis
+ *
+ * Traces method/function calls across files to build execution paths.
+ * Goes beyond import edges: if endpoint A calls service B.method() which
+ * calls repository C.query(), we produce edges A→B and B→C with type 'call'.
+ *
+ * This is the signal that turns "fix cache retrieval" from matching random
+ * files that mention "cache" into tracing the actual execution path:
+ *   controller → use case → cache repository → cache implementation.
+ *
+ * Approach: lightweight regex-based static analysis per language.
+ * No AST parser dependency — works on raw file content.
+ *
+ * Supported: Java, TypeScript/JavaScript, Python, Go
+ */
+
+interface MethodDefinition {
+    name: string;
+    className?: string;
+    filePath: string;
+    isExported: boolean;
+}
+interface MethodCall {
+    callerFile: string;
+    receiverName: string;
+    methodName: string;
+}
+interface CallGraphResult {
+    definitions: MethodDefinition[];
+    calls: MethodCall[];
+    edges: GraphEdge[];
+}
+/**
+ * Build a cross-file call graph from file contents.
+ *
+ * Returns method definitions, method calls, and resolved call edges.
+ * Call edges connect the file making the call to the file defining the method.
+ *
+ * @param files - Array of {relativePath, content} pairs
+ * @returns CallGraphResult with definitions, calls, and resolved edges
+ */
+declare function buildCallGraph(files: {
+    relativePath: string;
+    content: string;
+}[]): CallGraphResult;
+/**
+ * Boost BM25 results using call graph edges.
+ *
+ * When a file ranks well in BM25, files it calls or is called by
+ * are likely relevant to the same task. This traces execution paths
+ * that import-only analysis misses.
+ *
+ * @param matches - Current ranked matches
+ * @param callEdges - Call graph edges (type 'call')
+ * @param topK - How many top matches to expand (default: 10)
+ * @param boostFactor - Score boost for called/calling files (default: 0.3)
+ */
+declare function boostByCallGraph(matches: {
+    filePath: string;
+    score: number;
+    matchedTerms: string[];
+}[], callEdges: GraphEdge[], topK?: number, boostFactor?: number): {
+    filePath: string;
+    score: number;
+    matchedTerms: string[];
+}[];
+
+/**
+ * Git-Aware Relevance
+ *
+ * Files that are frequently modified together are likely related.
+ * This is the signal that no competitor has — it captures implicit
+ * coupling that import analysis and call graphs miss.
+ *
+ * Examples:
+ *   - Controller + its DTO changed together 90% of the time
+ *   - Service + its test changed together 80% of the time
+ *   - Config + migration changed together in 3 out of 4 commits
+ *
+ * Approach:
+ *   1. Run `git log --name-only` to extract co-change history
+ *   2. Build a co-change matrix: file pairs → co-commit count
+ *   3. Normalize to Jaccard similarity: co(A,B) / (commits(A) + commits(B) - co(A,B))
+ *   4. When file A is selected, boost files with high co-change similarity
+ *
+ * Performance: O(C × F²) where C = commits, F = avg files per commit.
+ * Capped at 500 recent commits to keep it fast.
+ */
+interface CoChangeEntry {
+    fileA: string;
+    fileB: string;
+    coCommits: number;
+    similarity: number;
+}
+interface CoChangeMatrix {
+    entries: Map<string, CoChangeEntry[]>;
+    fileCommitCounts: Map<string, number>;
+    totalCommits: number;
+}
+/**
+ * Build a co-change matrix from git history.
+ *
+ * @param projectPath - Absolute path to the git repository
+ * @param maxCommits - Max commits to analyze (default: 500)
+ * @param minCoChanges - Minimum co-changes to include a pair (default: 2)
+ * @returns CoChangeMatrix with file pair similarities
+ */
+declare function buildCoChangeMatrix(projectPath: string, maxCommits?: number, minCoChanges?: number): CoChangeMatrix;
+/**
+ * Boost BM25 results using git co-change history.
+ *
+ * When file A ranks well and file B was frequently co-changed with A,
+ * B gets a score boost proportional to A's score × co-change similarity.
+ *
+ * @param matches - Current ranked matches
+ * @param coChangeMatrix - Pre-built co-change matrix
+ * @param topK - How many top matches to expand (default: 10)
+ * @param boostFactor - Max boost multiplier (default: 0.25)
+ * @param minSimilarity - Min Jaccard similarity to apply boost (default: 0.15)
+ */
+declare function boostByGitCoChange(matches: {
+    filePath: string;
+    score: number;
+    matchedTerms: string[];
+}[], coChangeMatrix: CoChangeMatrix, topK?: number, boostFactor?: number, minSimilarity?: number): {
+    filePath: string;
+    score: number;
+    matchedTerms: string[];
+}[];
+/**
+ * Get recently modified files from git log.
+ * Files modified more recently are more likely relevant to active work.
+ *
+ * @param projectPath - Absolute path to the git repository
+ * @param days - How many days back to look (default: 30)
+ * @returns Map of filePath → recency score (1.0 = today, decays with age)
+ */
+declare function getGitRecency(projectPath: string, days?: number): Map<string, number>;
+
+/**
+ * Multi-Hop Reasoning for Enterprise Queries
+ *
+ * Problem: "fix the seller info cache invalidation on KVS delete"
+ * Required chain:
+ *   1. Find delete KVS endpoint (BM25 matches "delete", "KVS")
+ *   2. Find what it calls (use case → dependency graph)
+ *   3. Find what the use case invalidates (cache repo → call graph)
+ *   4. Find the cache implementation
+ *
+ * Current system finds steps 1 and 3 independently.
+ * Multi-hop traces the chain and finds ALL 4.
+ *
+ * Algorithm: Iterative BM25 with dependency/call expansion
+ *   Hop 0: BM25(original query) → top-K files
+ *   Hop 1: For each top file, find deps + callees → re-query with expanded terms
+ *   Hop 2: Repeat with score decay
+ *   Aggregate: Combine scores across hops with exponential decay
+ *
+ * Max 3 hops. Each hop expands through both import deps AND call graph edges.
+ */
+
+interface MultiHopConfig {
+    maxHops: number;
+    topKPerHop: number;
+    decayFactor: number;
+    minScoreThreshold: number;
+}
+interface MultiHopResult {
+    matches: SemanticMatch[];
+    hops: HopDetail[];
+    totalFilesExplored: number;
+}
+interface HopDetail {
+    hop: number;
+    seedFiles: string[];
+    newFiles: string[];
+    expandedTerms: string[];
+}
+/**
+ * Execute a multi-hop reasoning query.
+ *
+ * Starting from BM25 results, iteratively expands through the dependency
+ * and call graphs, extracting terms from discovered files to broaden
+ * the search while maintaining relevance through score decay.
+ *
+ * @param index - TF-IDF index for BM25 queries
+ * @param task - Original task description
+ * @param deps - Import dependency map (file → files it imports)
+ * @param callEdges - Call graph edges (from → to with type 'call')
+ * @param fileContents - Map of filePath → file content (for term extraction)
+ * @param config - Multi-hop configuration
+ */
+declare function multiHopQuery(index: TfIdfIndex, task: string, deps: Map<string, string[]>, callEdges: {
+    from: string;
+    to: string;
+}[], fileContents: Map<string, string>, config?: Partial<MultiHopConfig>): MultiHopResult;
+
+/**
+ * IDE Telemetry — Incremental Learning from File Opens
+ *
+ * Tracks which files the developer actually opens after receiving context.
+ * If CTO suggests 15 files and the developer only uses 5, those 5 should
+ * be weighted higher next time for similar tasks.
+ *
+ * Storage: .cto/telemetry.json — lightweight, per-project.
+ *
+ * Integration points:
+ *   - VS Code extension: file-open events → recordFileOpen()
+ *   - LSP bridge: cto/telemetry method
+ *   - Context pipeline: getTelemetryBoosts() → selector
+ *
+ * Privacy: Only stores relative file paths and timestamps.
+ * No file contents, no user data.
+ */
+interface FileOpenEvent {
+    filePath: string;
+    timestamp: number;
+    taskContext?: string;
+}
+interface TelemetrySession {
+    taskDescription: string;
+    suggestedFiles: string[];
+    openedFiles: string[];
+    timestamp: number;
+}
+interface TelemetryModel {
+    version: number;
+    sessions: TelemetrySession[];
+    fileOpenCounts: Record<string, number>;
+    fileTaskCounts: Record<string, Record<string, number>>;
+    lastUpdated: number;
+}
+declare function loadTelemetry(projectPath: string): TelemetryModel;
+declare function saveTelemetry(projectPath: string, model: TelemetryModel): void;
+/**
+ * Record that the user opened a file after receiving context suggestions.
+ */
+declare function recordFileOpen(model: TelemetryModel, filePath: string, taskContext?: string): TelemetryModel;
+/**
+ * Record a complete session: what CTO suggested vs what the user used.
+ */
+declare function recordSession(model: TelemetryModel, taskDescription: string, suggestedFiles: string[], openedFiles: string[]): TelemetryModel;
+/**
+ * Get telemetry-based boosts for file ranking.
+ *
+ * Files the user frequently opens for similar tasks get a positive boost.
+ * Files that CTO suggests but the user never opens get a negative signal.
+ *
+ * @param model - Telemetry model
+ * @param taskType - Current task type (debug, feature, refactor, etc.)
+ * @param candidateFiles - Files to compute boosts for
+ * @returns Map of filePath → boost (-1.0 to +1.0)
+ */
+declare function getTelemetryBoosts(model: TelemetryModel, taskType: string, candidateFiles: string[]): Map<string, number>;
+/**
+ * Render a summary of telemetry data for debugging/display.
+ */
+declare function renderTelemetrySummary(model: TelemetryModel): string;
+
+/**
+ * Embedding-Based Retrieval
+ *
+ * Dense vector search to complement BM25 lexical matching.
+ * Catches semantic similarity that BM25 misses:
+ *   - "authentication" matches "login" (no lexical overlap)
+ *   - "cache invalidation" matches "clear stored data"
+ *
+ * Two backends:
+ *   1. TF-IDF Cosine (built-in, zero deps, always available)
+ *      — builds document vectors from TF-IDF weights, queries via cosine similarity
+ *      — accuracy: ~85% of neural embeddings for code search
+ *
+ *   2. ONNX Neural (optional, requires onnxruntime-node + model file)
+ *      — all-MiniLM-L6-v2 (23MB), 384-dim embeddings
+ *      — accuracy: best-in-class for semantic code search
+ *
+ * Integration: produces a ranked list of (filePath, score) that gets
+ * merged with BM25 results via RRF in the context pipeline.
+ */
+
+interface EmbeddingResult {
+    filePath: string;
+    score: number;
+}
+interface EmbeddingIndex {
+    backend: 'tfidf-cosine' | 'onnx-minilm';
+    dimensions: number;
+    documentCount: number;
+    query: (text: string, topK: number) => EmbeddingResult[];
+}
+/**
+ * Build a dense embedding index from TF-IDF vectors.
+ *
+ * Each document becomes a vector in IDF-weighted term space.
+ * Queries are vectorized the same way and matched via cosine similarity.
+ *
+ * This is surprisingly effective for code search because:
+ *   - Code has strong term distributions (class names, method names)
+ *   - IDF weighting naturally emphasizes discriminative terms
+ *   - Cosine similarity handles different document lengths well
+ *
+ * Performance: O(V) per query where V = vocabulary size × document count.
+ * For 1000 files × 5000 unique terms = 5M ops. Fast enough for CLI.
+ */
+declare function buildTfIdfEmbeddingIndex(index: TfIdfIndex): EmbeddingIndex;
+/**
+ * Merge BM25 results with embedding results using Reciprocal Rank Fusion.
+ *
+ * RRF(d) = Σ 1/(k + rank_i(d)) for each ranking i
+ *
+ * This is the standard way to combine lexical and semantic search.
+ * k=60 is the standard constant from the RRF paper (Cormack et al., 2009).
+ *
+ * @param bm25Results - BM25 ranked results (filePath, score)
+ * @param embeddingResults - Embedding ranked results (filePath, score)
+ * @param k - RRF constant (default: 60)
+ * @param bm25Weight - Weight for BM25 signal (default: 0.6)
+ * @param embeddingWeight - Weight for embedding signal (default: 0.4)
+ */
+declare function reciprocalRankFusion(bm25Results: {
+    filePath: string;
+    score: number;
+}[], embeddingResults: EmbeddingResult[], k?: number, bm25Weight?: number, embeddingWeight?: number): {
+    filePath: string;
+    score: number;
+}[];
+/**
+ * Check if ONNX Runtime is available for neural embeddings.
+ */
+declare function isOnnxAvailable(): Promise<boolean>;
+/**
+ * Build a neural embedding index using ONNX Runtime.
+ * Requires: npm install onnxruntime-node
+ * Model: all-MiniLM-L6-v2 (download separately to .cto/models/)
+ *
+ * Falls back to TF-IDF cosine if ONNX is not available.
+ */
+declare function buildNeuralEmbeddingIndex(_files: {
+    relativePath: string;
+    content: string;
+}[], modelPath?: string): Promise<EmbeddingIndex | null>;
+
+/**
+ * Chunk-Level Retrieval
+ *
+ * Instead of including entire files, extract semantic chunks
+ * (functions, methods, classes) and score each chunk independently.
+ *
+ * This is the single biggest efficiency win for context selection:
+ * - A 2000-line file with 1 relevant method → include 50 lines, not 2000
+ * - Token budget goes 10-40x further
+ * - More files can have their relevant parts included
+ *
+ * Chunk types:
+ *   - Function/method definition (with body)
+ *   - Class/interface declaration (with key members)
+ *   - Import block
+ *   - Top-level constant/variable block
+ *
+ * Scoring: BM25 term overlap + structural bonus (method name matches query)
+ */
+interface CodeChunk {
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    content: string;
+    kind: ChunkKind;
+    name: string;
+    className?: string;
+    score: number;
+    tokens: number;
+}
+type ChunkKind = 'function' | 'method' | 'class' | 'interface' | 'import' | 'constant' | 'type' | 'block';
+interface ChunkRetrievalResult {
+    chunks: CodeChunk[];
+    fileChunks: Map<string, CodeChunk[]>;
+    totalChunks: number;
+    totalTokensUsed: number;
+}
+/**
+ * Extract semantic chunks from a file.
+ */
+declare function chunkFile(content: string, filePath: string): CodeChunk[];
+/**
+ * Score chunks against a query.
+ * Uses BM25 term overlap + structural bonuses.
+ */
+declare function scoreChunks(chunks: CodeChunk[], task: string): CodeChunk[];
+/**
+ * Retrieve the most relevant chunks across multiple files.
+ *
+ * @param files - Array of {relativePath, content} pairs
+ * @param task - Task description to match against
+ * @param tokenBudget - Max tokens to include (default: 30000)
+ * @param minScore - Minimum chunk score to include (default: 0.1)
+ */
+declare function retrieveChunks(files: {
+    relativePath: string;
+    content: string;
+}[], task: string, tokenBudget?: number, minScore?: number): ChunkRetrievalResult;
+/**
+ * Render chunks for a single file as markdown.
+ * Shows relevant chunks with line numbers, connected by "..." for gaps.
+ */
+declare function renderFileChunks(filePath: string, chunks: CodeChunk[], ext: string): string;
+
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 interface LogEntry {
     level: LogLevel;
@@ -470,4 +1829,4 @@ interface AuditOptions {
 }
 declare function auditProject(projectPath: string, filePaths: string[], options?: AuditOptions): Promise<AuditResult>;
 
-export { CtoError, type CtoErrorCode, type DocumentVector, type LearnerBoost, type LearnerBoostInput, type LearnerModel, type LogEntry, type LogLevel, type Logger, type PatternStats, type SecretFinding, type SecretType, type SelectionInput, type SemanticMatch, type SemanticScore, type TfIdfIndex, analyzeProject, auditProject, bfsBidirectional, boostByPath, buildAdjacencyList, buildIndex, buildProjectGraph, calculateCoverage, classifyFileKind, countTokensChars4, countTokensTiktoken, createLogger, createProject, detectStack, estimateFileTokens, estimateTokens, extractPattern, freeEncoder, getLearnerBoosts, getLearnerStats, getPruneLevelForRisk, isCtoError, loadLearner, optimizeBudget, pruneFile, pruneFiles, query, recordSelection, sanitizeContent, saveLearner, scanContentForSecrets, scanFileForSecrets, scanProjectForSecrets, scoreAllFiles, scoreFile, selectContext, setJsonLogging, setLogLevel, similarity, tokenize, walkProject, wrapError };
+export { type ActionType, type ArchLayer, type AssignmentResult, type CallGraphResult, type ChunkKind, type ChunkRetrievalResult, type CoChangeEntry, type CoChangeMatrix, type CodeChunk, type ContextPipelineInput, type ContextPipelineResult, type CorpusEmbeddings, CtoError, type CtoErrorCode, type DocumentVector, type EmbeddingIndex, type EmbeddingResult, type Experiment, type ExperimentConclusion, type ExperimentGroup, type FileOpenEvent, type FilteredFile, type GroupMetrics, type HopDetail, type ImportSpec, type IndexCacheStats, type LearnerBoost, type LearnerBoostInput, type LearnerModel, type LogEntry, type LogLevel, type Logger, type MethodCall, type MethodDefinition, type MultiHopConfig, type MultiHopResult, type MultiRepoResult, type PatternStats, type QueryIntent, type RerankInput, type RerankResult, type RerankedFile, type SecretFinding, type SecretType, type SelectionInput, type SemanticExpansion, type SemanticMatch, type SemanticScore, type SiblingMatch, type SiblingRepo, type SignalWeight, type SignificanceResult, type StructuralTokens, type SupportedLanguage, type SynonymExpansion, type TelemetryModel, type TelemetrySession, type TfIdfIndex, type TunedWeights, type WeightTunerModel, analyzeProject, assignGroup, attributeToSignal, auditProject, augmentContentWithStructure, bfsBidirectional, boostByCallGraph, boostByGitCoChange, boostByImports, boostByLayer, boostByPath, buildAdjacencyList, buildCallGraph, buildCoChangeMatrix, buildCorpusEmbeddings, buildIndex, buildIndexCached, buildNeuralEmbeddingIndex, buildProjectGraph, buildTfIdfEmbeddingIndex, buildWeightedQuery, calculateCoverage, chunkFile, classifyFileKind, countTokensChars4, countTokensTiktoken, createExperiment, createFreshModel, createLogger, createProject, detectLanguage, detectStack, discoverSiblingRepos, embedQuery, reciprocalRankFusion as embeddingRRF, estimateComplexity, estimateFileTokens, estimateTokens, expandLayers, expandQuery, expandQueryWithPMI, expandTerm, extractPattern, extractStructuralTokens, freeEncoder, getActiveExperiment, getCacheInfo, getConcludedExperiments, getExpansionDetails, getGitRecency, getLearnerBoosts, getLearnerStats, getOptimizedWeights, getPruneLevelForRisk, getStructuralSummary, getSynonymStats, getTelemetryBoosts, invalidateCache, isCtoError, isOnnxAvailable, loadExperiments, loadLearner, loadTelemetry, loadWeightTuner, multiHopQuery, optimizeBudget, parseAllPolyglotImports, parseImports, parseQueryIntent, parseSiblingPaths, pruneFile, pruneFiles, query, queryByEmbedding, querySiblingRepos, reciprocalRankFusion$1 as reciprocalRankFusion, recordFeedback, recordFileOpen, recordOutcome, recordSelection, recordSession, renderExperimentSummary, renderFileChunks, renderMultiRepoSummary, renderTelemetrySummary, renderWeightStatus, rerank, retrieveChunks, runContextPipeline, sanitizeContent, saveExperiments, saveLearner, saveTelemetry, saveWeightTuner, scanContentForSecrets, scanFileForSecrets, scanProjectForSecrets, scoreAllFiles, scoreChunks, scoreFile, selectContext, setJsonLogging, setLogLevel, similarity, testSignificance, tokenize, walkProject, wrapError };