cto-ai-cli 7.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;
@@ -272,6 +272,7 @@ declare function selectContext(input: SelectionInput): Promise<ContextSelection>
 interface TfIdfIndex {
     documents: Map<string, DocumentVector>;
     idf: Map<string, number>;
+    docFreq: Map<string, number>;
     avgDocLength: number;
     totalDocs: number;
 }
@@ -295,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?")
@@ -312,8 +315,53 @@ 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
@@ -391,6 +439,54 @@ declare function getCacheInfo(projectPath: string): {
     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.
  *
@@ -570,6 +666,8 @@ interface ContextPipelineResult {
     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) */
@@ -592,6 +690,61 @@ declare function optimizeBudget(files: AnalyzedFile[], budget: number): Promise<
 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
  *
@@ -945,6 +1098,676 @@ declare function estimateTokens(content: string, sizeInBytes: number, method?: '
 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;
@@ -1006,4 +1829,4 @@ interface AuditOptions {
 }
 declare function auditProject(projectPath: string, filePaths: string[], options?: AuditOptions): Promise<AuditResult>;
 
-export { type AssignmentResult, type ContextPipelineInput, type ContextPipelineResult, CtoError, type CtoErrorCode, type DocumentVector, type Experiment, type ExperimentConclusion, type ExperimentGroup, type FilteredFile, type GroupMetrics, type ImportSpec, type IndexCacheStats, type LearnerBoost, type LearnerBoostInput, type LearnerModel, type LogEntry, type LogLevel, type Logger, type MultiRepoResult, type PatternStats, type RerankInput, type RerankResult, type RerankedFile, type SecretFinding, type SecretType, type SelectionInput, type SemanticMatch, type SemanticScore, type SiblingMatch, type SiblingRepo, type SignificanceResult, type SupportedLanguage, type TfIdfIndex, analyzeProject, assignGroup, auditProject, bfsBidirectional, boostByPath, buildAdjacencyList, buildIndex, buildIndexCached, buildProjectGraph, calculateCoverage, classifyFileKind, countTokensChars4, countTokensTiktoken, createExperiment, createLogger, createProject, detectLanguage, detectStack, discoverSiblingRepos, estimateComplexity, estimateFileTokens, estimateTokens, extractPattern, freeEncoder, getActiveExperiment, getCacheInfo, getConcludedExperiments, getLearnerBoosts, getLearnerStats, getPruneLevelForRisk, invalidateCache, isCtoError, loadExperiments, loadLearner, optimizeBudget, parseAllPolyglotImports, parseImports, parseSiblingPaths, pruneFile, pruneFiles, query, querySiblingRepos, recordOutcome, recordSelection, renderExperimentSummary, renderMultiRepoSummary, rerank, runContextPipeline, sanitizeContent, saveExperiments, saveLearner, scanContentForSecrets, scanFileForSecrets, scanProjectForSecrets, scoreAllFiles, scoreFile, selectContext, setJsonLogging, setLogLevel, similarity, testSignificance, 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 };