@a13xu/lucid 1.1.0 → 1.9.0

package/build/indexer/project.js

@@ -0,0 +1,320 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { join, extname, basename } from "path";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function readFile(path) {
+    try {
+        return readFileSync(path, { encoding: "utf-8" });
+    }
+    catch {
+        return null;
+    }
+}
+function upsert(stmts, name, type, observations) {
+    const existing = stmts.getEntityByName.get(name);
+    if (existing) {
+        const current = JSON.parse(existing.observations);
+        const merged = [...current];
+        for (const obs of observations) {
+            if (!merged.includes(obs))
+                merged.push(obs);
+        }
+        stmts.updateEntity.run(JSON.stringify(merged), existing.id);
+    }
+    else {
+        stmts.insertEntity.run(name, type, JSON.stringify(observations));
+    }
+}
+function relate(stmts, from, to, type) {
+    const fromRow = stmts.getEntityByName.get(from);
+    const toRow = stmts.getEntityByName.get(to);
+    if (fromRow && toRow) {
+        stmts.insertRelation.run(fromRow.id, toRow.id, type);
+    }
+}
+// ---------------------------------------------------------------------------
+// Parsers per file type
+// ---------------------------------------------------------------------------
+function indexClaudeMd(path, stmts, results) {
+    const content = readFile(path);
+    if (!content)
+        return;
+    // Indexează fiecare secțiune H2 ca observație separată pe entitatea proiectului
+    const sections = content.split(/\n##\s+/).filter(Boolean);
+    const observations = [];
+    for (const section of sections) {
+        const lines = section.trim().split("\n");
+        const title = lines[0]?.trim() ?? "directive";
+        const body = lines.slice(1).join("\n").trim();
+        if (body.length > 0) {
+            observations.push(`[${title}] ${body.slice(0, 300)}`);
+        }
+    }
+    if (observations.length > 0) {
+        upsert(stmts, "CLAUDE.md directives", "convention", observations);
+        results.push({ entity: "CLAUDE.md directives", type: "convention", observations: observations.length, source: "CLAUDE.md" });
+    }
+}
+function indexPackageJson(path, stmts, results) {
+    const content = readFile(path);
+    if (!content)
+        return;
+    let pkg;
+    try {
+        pkg = JSON.parse(content);
+    }
+    catch {
+        return;
+    }
+    const name = pkg["name"] ?? "project";
+    const version = pkg["version"] ?? "unknown";
+    const description = pkg["description"] ?? "";
+    const projectName = name.replace(/^@[\w-]+\//, ""); // strip scope
+    const obs = [`version: ${version}`];
+    if (description)
+        obs.push(`description: ${description}`);
+    // Scripts
+    const scripts = pkg["scripts"];
+    if (scripts) {
+        for (const [k, v] of Object.entries(scripts).slice(0, 6)) {
+            obs.push(`script ${k}: ${v}`);
+        }
+    }
+    upsert(stmts, projectName, "project", obs);
+    results.push({ entity: projectName, type: "project", observations: obs.length, source: "package.json" });
+    // Dependențe principale
+    const deps = {
+        ...(pkg["dependencies"] ?? {}),
+        ...(pkg["devDependencies"] ?? {}),
+    };
+    for (const [dep, ver] of Object.entries(deps).slice(0, 20)) {
+        upsert(stmts, dep, "tool", [`version: ${ver}`, `used in: ${projectName}`]);
+        relate(stmts, projectName, dep, "depends_on");
+    }
+    if (Object.keys(deps).length > 0) {
+        results.push({ entity: `${Object.keys(deps).length} dependencies`, type: "tool", observations: 1, source: "package.json" });
+    }
+}
+function indexPyprojectToml(path, stmts, results) {
+    const content = readFile(path);
+    if (!content)
+        return;
+    const nameMatch = content.match(/^name\s*=\s*["']([^"']+)["']/m);
+    const versionMatch = content.match(/^version\s*=\s*["']([^"']+)["']/m);
+    const descMatch = content.match(/^description\s*=\s*["']([^"']+)["']/m);
+    const name = nameMatch?.[1] ?? "project";
+    const obs = [];
+    if (versionMatch?.[1])
+        obs.push(`version: ${versionMatch[1]}`);
+    if (descMatch?.[1])
+        obs.push(`description: ${descMatch[1]}`);
+    // Dependencies
+    const depsSection = content.match(/\[tool\.poetry\.dependencies\]([\s\S]*?)(?=\[|$)/)?.[1]
+        ?? content.match(/dependencies\s*=\s*\[([\s\S]*?)\]/)?.[1]
+        ?? "";
+    const deps = [...depsSection.matchAll(/["']?([\w-]+)["']?\s*[=:]/g)].map((m) => m[1]).filter(Boolean);
+    for (const dep of deps.slice(0, 20)) {
+        upsert(stmts, dep, "tool", [`used in: ${name}`]);
+        relate(stmts, name, dep, "depends_on");
+    }
+    upsert(stmts, name, "project", obs);
+    results.push({ entity: name, type: "project", observations: obs.length, source: "pyproject.toml" });
+}
+function indexReadme(path, projectName, stmts, results) {
+    const content = readFile(path);
+    if (!content)
+        return;
+    // Prima secțiune (descriere)
+    const firstParagraph = content.replace(/^#[^\n]*\n/, "").trim().split("\n\n")[0] ?? "";
+    if (firstParagraph.length < 10)
+        return;
+    upsert(stmts, projectName, "project", [
+        `README: ${firstParagraph.slice(0, 400)}`,
+    ]);
+    results.push({ entity: projectName, type: "project", observations: 1, source: "README.md" });
+}
+function indexMcpJson(path, stmts, results) {
+    const content = readFile(path);
+    if (!content)
+        return;
+    let cfg;
+    try {
+        cfg = JSON.parse(content);
+    }
+    catch {
+        return;
+    }
+    const servers = cfg.mcpServers ?? {};
+    for (const [serverName, config] of Object.entries(servers)) {
+        const c = config;
+        const obs = [`MCP server configured in project`];
+        if (c.command)
+            obs.push(`command: ${c.command} ${(c.args ?? []).join(" ")}`);
+        upsert(stmts, serverName, "tool", obs);
+        results.push({ entity: serverName, type: "tool", observations: obs.length, source: ".mcp.json" });
+    }
+}
+function indexLogicGuardianYaml(path, stmts, results) {
+    const content = readFile(path);
+    if (!content)
+        return;
+    // Extrage known_drift_patterns
+    const patternMatches = [...content.matchAll(/id:\s*["']?(DRIFT-\d+)["']?\s*\n\s*name:\s*["']?([^\n"']+)["']?\s*\n\s*description:\s*["']?([^\n"']+)/g)];
+    for (const m of patternMatches) {
+        const [, id, name, desc] = m;
+        upsert(stmts, `${id}: ${name.trim()}`, "pattern", [
+            `drift pattern: ${desc.trim()}`,
+            "source: logic-guardian.yaml",
+        ]);
+    }
+    // Invarianți de proiect
+    const invariantsMatch = content.match(/project_invariants:([\s\S]*?)(?=\n\w|\n#|$)/);
+    if (invariantsMatch) {
+        const invariants = [...invariantsMatch[1].matchAll(/-\s+"([^"]+)"/g)].map((m) => m[1]);
+        if (invariants.length > 0) {
+            upsert(stmts, "project invariants", "convention", invariants);
+            results.push({ entity: "project invariants", type: "convention", observations: invariants.length, source: "logic-guardian.yaml" });
+        }
+    }
+    if (patternMatches.length > 0) {
+        results.push({ entity: `${patternMatches.length} drift patterns`, type: "pattern", observations: patternMatches.length, source: "logic-guardian.yaml" });
+    }
+}
+// Source file indexing — extrage exporturi, clase, funcții principale
+const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"]);
+const SKIP_DIRS = new Set(["node_modules", ".git", "build", "dist", "__pycache__", ".next", "venv", ".venv", "target", ".cache", "coverage", ".nyc_output"]);
+const MAX_SOURCE_FILES = 10_000;
+function indexSourceFile(filepath, rootDir, projectName, stmts) {
+    const content = readFile(filepath);
+    if (!content)
+        return [];
+    const exports = [];
+    const lang = extname(filepath);
+    // TypeScript / JavaScript
+    if ([".ts", ".tsx", ".js", ".jsx"].includes(lang)) {
+        for (const m of content.matchAll(/export\s+(?:async\s+)?(?:function|class|const|type|interface)\s+(\w+)/g)) {
+            exports.push(m[1]);
+        }
+    }
+    // Python
+    if (lang === ".py") {
+        for (const m of content.matchAll(/^(?:def|class|async def)\s+(\w+)/gm)) {
+            if (!m[1].startsWith("_"))
+                exports.push(m[1]);
+        }
+    }
+    if (exports.length === 0)
+        return [];
+    // Cale relativă față de rădăcina proiectului
+    const relPath = filepath.replace(/\\/g, "/").replace(rootDir.replace(/\\/g, "/") + "/", "");
+    const obs = [`exports from ${relPath}: ${exports.slice(0, 10).join(", ")}`];
+    upsert(stmts, projectName, "project", obs);
+    return exports;
+}
+function scanSources(dir, projectName, stmts, results) {
+    const rootDir = dir.replace(/\\/g, "/");
+    let fileCount = 0;
+    const exportedSymbols = [];
+    function walk(d) {
+        if (fileCount >= MAX_SOURCE_FILES)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (SKIP_DIRS.has(entry))
+                continue;
+            const full = join(d, entry);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                walk(full);
+            }
+            else if (SOURCE_EXTS.has(extname(entry).toLowerCase())) {
+                const syms = indexSourceFile(full, rootDir, projectName, stmts);
+                exportedSymbols.push(...syms);
+                fileCount++;
+                if (fileCount >= MAX_SOURCE_FILES)
+                    return;
+            }
+        }
+    }
+    walk(dir);
+    if (fileCount > 0) {
+        results.push({
+            entity: projectName,
+            type: "project",
+            observations: fileCount,
+            source: `${fileCount} source files (${exportedSymbols.length} exports)`,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+export function indexProject(directory, stmts) {
+    const results = [];
+    const dir = directory.replace(/\\/g, "/");
+    // Detectează numele proiectului din package.json sau pyproject.toml
+    let projectName = basename(dir);
+    const pkgPath = join(dir, "package.json");
+    if (existsSync(pkgPath)) {
+        const raw = readFile(pkgPath);
+        if (raw) {
+            try {
+                const pkg = JSON.parse(raw);
+                if (pkg.name)
+                    projectName = pkg.name.replace(/^@[\w-]+\//, "");
+            }
+            catch { /* ignore */ }
+        }
+    }
+    // 1. CLAUDE.md — cel mai important
+    const claudeMdPaths = ["CLAUDE.md", ".claude/CLAUDE.md", "claude.md"];
+    for (const p of claudeMdPaths) {
+        const full = join(dir, p);
+        if (existsSync(full)) {
+            indexClaudeMd(full, stmts, results);
+            break;
+        }
+    }
+    // 2. package.json
+    if (existsSync(join(dir, "package.json"))) {
+        indexPackageJson(join(dir, "package.json"), stmts, results);
+    }
+    // 3. pyproject.toml
+    if (existsSync(join(dir, "pyproject.toml"))) {
+        indexPyprojectToml(join(dir, "pyproject.toml"), stmts, results);
+    }
+    // 4. README
+    for (const p of ["README.md", "readme.md", "Readme.md"]) {
+        if (existsSync(join(dir, p))) {
+            indexReadme(join(dir, p), projectName, stmts, results);
+            break;
+        }
+    }
+    // 5. MCP config
+    for (const p of [".mcp.json", "mcp.json"]) {
+        if (existsSync(join(dir, p))) {
+            indexMcpJson(join(dir, p), stmts, results);
+            break;
+        }
+    }
+    // 6. Logic Guardian config
+    if (existsSync(join(dir, "logic-guardian.yaml"))) {
+        indexLogicGuardianYaml(join(dir, "logic-guardian.yaml"), stmts, results);
+    }
+    // 7. Surse
+    scanSources(dir, projectName, stmts, results);
+    return results;
+}

package/build/memory/experience.d.ts

@@ -0,0 +1,11 @@
+import type { Statements } from "../database.js";
+export declare const getLastExperienceId: () => number | null;
+export declare const setLastExperienceId: (id: number) => void;
+export declare function decayedReward(reward: number, rewardedAt: number | null): number;
+export declare function createExperience(query: string, contextFps: string[], strategy: string, stmts: Statements): number;
+export declare function rewardExperience(id: number, delta: number, feedback: string | null, stmts: Statements): {
+    query: string;
+    fps: string[];
+} | null;
+export declare function implicitRewardFromSync(filepath: string, stmts: Statements): boolean;
+export declare function getFileRewardsMap(stmts: Statements): Map<string, number>;

package/build/memory/experience.js

@@ -0,0 +1,85 @@
+// Reward system — lightweight RL from get_context usage signals
+// Sources: explicit reward()/penalize(), implicit sync_file(), temporal decay
+// ---------------------------------------------------------------------------
+// In-process tracking of the last created experience (server is long-running)
+// ---------------------------------------------------------------------------
+let _lastId = null;
+export const getLastExperienceId = () => _lastId;
+export const setLastExperienceId = (id) => { _lastId = id; };
+// ---------------------------------------------------------------------------
+// Exponential decay — half-life ≈ 14 days (λ = ln(2)/14 ≈ 0.0495 ≈ 0.05)
+// ---------------------------------------------------------------------------
+export function decayedReward(reward, rewardedAt) {
+    if (rewardedAt === null || rewardedAt === 0)
+        return 0;
+    const daysSince = Math.max(0, (Date.now() / 1000 - rewardedAt) / 86400);
+    return reward * Math.exp(-0.05 * daysSince);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function tokenizeQuery(query) {
+    return query.toLowerCase().split(/\s+/).filter((t) => t.length > 1).join(" ");
+}
+function parseFps(contextFps) {
+    try {
+        return JSON.parse(contextFps);
+    }
+    catch {
+        return [];
+    }
+}
+// ---------------------------------------------------------------------------
+// Create experience — called after get_context returns results
+// ---------------------------------------------------------------------------
+export function createExperience(query, contextFps, strategy, stmts) {
+    const result = stmts.insertExperience.run(query, tokenizeQuery(query), JSON.stringify(contextFps), strategy);
+    const id = Number(result.lastInsertRowid);
+    setLastExperienceId(id);
+    return id;
+}
+// ---------------------------------------------------------------------------
+// Reward or penalize an experience (explicit feedback)
+// ---------------------------------------------------------------------------
+export function rewardExperience(id, delta, feedback, stmts) {
+    const exp = stmts.getExperienceById.get(id);
+    if (!exp)
+        return null;
+    stmts.updateExperienceReward.run(delta, feedback, id);
+    const fps = parseFps(exp.context_fps);
+    for (const fp of fps) {
+        stmts.upsertFileReward.run(fp, delta);
+    }
+    return { query: exp.query, fps };
+}
+// ---------------------------------------------------------------------------
+// Implicit reward from sync_file — if filepath was in the last context → +0.3
+// ---------------------------------------------------------------------------
+const IMPLICIT_DELTA = 0.3;
+export function implicitRewardFromSync(filepath, stmts) {
+    const lastId = getLastExperienceId();
+    if (lastId === null)
+        return false;
+    const exp = stmts.getExperienceById.get(lastId);
+    if (!exp)
+        return false;
+    const fps = parseFps(exp.context_fps);
+    if (!fps.includes(filepath))
+        return false;
+    stmts.updateExperienceReward.run(IMPLICIT_DELTA, null, lastId);
+    stmts.upsertFileReward.run(filepath, IMPLICIT_DELTA);
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Get file rewards map — for ranking boost in assembleContext()
+// ---------------------------------------------------------------------------
+export function getFileRewardsMap(stmts) {
+    const rows = stmts.getFileRewards.all();
+    const map = new Map();
+    for (const row of rows) {
+        const d = decayedReward(row.total_reward, row.last_rewarded);
+        if (d > 0)
+            map.set(row.filepath, d);
+    }
+    return map;
+}

package/build/retrieval/context.d.ts

@@ -0,0 +1,29 @@
+import type { Statements } from "../database.js";
+import type { ResolvedConfig } from "../config.js";
+export declare function estimateTokens(text: string): number;
+export declare function extractFragments(source: string, query: string, contextLines?: number): string;
+export declare function computeDiff(prev: string, curr: string, maxChanges?: number): string;
+export interface ContextFile {
+    filepath: string;
+    language: string;
+    tokens: number;
+    content: string;
+    reason: string;
+}
+export interface ContextResult {
+    files: ContextFile[];
+    totalTokens: number;
+    strategy: "qdrant" | "tfidf" | "recent";
+    truncated: boolean;
+    skippedFiles: number;
+}
+export interface ContextOptions {
+    maxTokens?: number;
+    maxTokensPerFile?: number;
+    dirs?: string[];
+    recentOnly?: boolean;
+    recentHours?: number;
+    skeletonOnly?: boolean;
+    topK?: number;
+}
+export declare function assembleContext(query: string, stmts: Statements, cfg: ResolvedConfig, opts?: ContextOptions): Promise<ContextResult>;

package/build/retrieval/context.js

@@ -0,0 +1,219 @@
+// Smart context assembly — TF-IDF + recency boost + AST skeleton pruning
+// Falls back gracefully: Qdrant → TF-IDF → recency-only
+import { decompress } from "../store/content.js";
+import { rankByRelevance } from "./tfidf.js";
+import { extractSkeleton, renderSkeleton } from "../indexer/ast.js";
+import { searchQdrant } from "./qdrant.js";
+import { getQdrantConfig } from "../config.js";
+import { getFileRewardsMap } from "../memory/experience.js";
+// ---------------------------------------------------------------------------
+// Token estimation (1 token ≈ 4 chars is the standard heuristic)
+// ---------------------------------------------------------------------------
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+// ---------------------------------------------------------------------------
+// Relevant fragment extraction (lines around query matches)
+// ---------------------------------------------------------------------------
+export function extractFragments(source, query, contextLines = 3) {
+    const lines = source.split("\n");
+    const terms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 2);
+    const hitLines = new Set();
+    for (let i = 0; i < lines.length; i++) {
+        const lower = lines[i].toLowerCase();
+        if (terms.some((t) => lower.includes(t))) {
+            for (let j = Math.max(0, i - contextLines); j <= Math.min(lines.length - 1, i + contextLines); j++) {
+                hitLines.add(j);
+            }
+        }
+    }
+    if (hitLines.size === 0)
+        return "";
+    const sorted = [...hitLines].sort((a, b) => a - b);
+    const out = [];
+    let prev = -2;
+    for (const n of sorted) {
+        if (n > prev + 1)
+            out.push("…");
+        out.push(`${n + 1}: ${lines[n]}`);
+        prev = n;
+    }
+    return out.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Simple line-level diff (no external deps)
+// ---------------------------------------------------------------------------
+export function computeDiff(prev, curr, maxChanges = 40) {
+    const pLines = prev.split("\n");
+    const cLines = curr.split("\n");
+    const out = [];
+    let changes = 0;
+    const maxLen = Math.max(pLines.length, cLines.length);
+    for (let i = 0; i < maxLen; i++) {
+        if (changes >= maxChanges) {
+            out.push(`[… +${Math.abs(cLines.length - pLines.length)} more line changes, truncated]`);
+            break;
+        }
+        const p = pLines[i];
+        const c = cLines[i];
+        if (p === c)
+            continue;
+        if (p === undefined) {
+            out.push(`+${i + 1}: ${c}`);
+        }
+        else if (c === undefined) {
+            out.push(`-${i + 1}: ${p}`);
+        }
+        else {
+            out.push(`-${i + 1}: ${p}`);
+            out.push(`+${i + 1}: ${c}`);
+        }
+        changes++;
+    }
+    return out.length > 0 ? out.join("\n") : "[no line changes]";
+}
+// ---------------------------------------------------------------------------
+// Main function
+// ---------------------------------------------------------------------------
+export async function assembleContext(query, stmts, cfg, opts = {}) {
+    const maxTokens = opts.maxTokens ?? cfg.maxContextTokens;
+    const maxPerFile = opts.maxTokensPerFile ?? cfg.maxTokensPerFile;
+    const recentHours = opts.recentHours ?? cfg.recentWindowHours;
+    const topK = opts.topK ?? 10;
+    const allRows = stmts.getAllFiles.all();
+    if (!Array.isArray(allRows) || allRows.length === 0) {
+        return { files: [], totalTokens: 0, strategy: "tfidf", truncated: false, skippedFiles: 0 };
+    }
+    // Apply whitelist dirs filter
+    const dirs = opts.dirs ?? cfg.whitelistDirs;
+    const filtered = dirs && dirs.length > 0
+        ? allRows.filter((r) => dirs.some((d) => r.filepath.replace(/\\/g, "/").includes(d)))
+        : allRows;
+    // Recency cutoff
+    const nowSec = Math.floor(Date.now() / 1000);
+    const cutoffSec = nowSec - recentHours * 3600;
+    const recentSet = new Set(filtered.filter((r) => (r.indexed_at ?? 0) >= cutoffSec).map((r) => r.filepath));
+    // If recentOnly, skip files outside the window
+    const candidates = opts.recentOnly
+        ? filtered.filter((r) => recentSet.has(r.filepath))
+        : filtered;
+    if (candidates.length === 0) {
+        return { files: [], totalTokens: 0, strategy: opts.recentOnly ? "recent" : "tfidf", truncated: false, skippedFiles: filtered.length };
+    }
+    // Decompress all candidates
+    const decompressed = candidates.map((r) => ({
+        filepath: r.filepath,
+        language: r.language,
+        indexedAt: r.indexed_at ?? 0,
+        text: decompress(r.content),
+    }));
+    // ---------------------------------------------------------------------------
+    // Ranking strategy
+    // ---------------------------------------------------------------------------
+    let strategy = "tfidf";
+    let ranked;
+    // Load experience-based rewards for ranking boost (decayed, normalized to +0.25 max)
+    const fileRewards = getFileRewardsMap(stmts);
+    const qdrantCfg = getQdrantConfig(cfg);
+    if (qdrantCfg && !opts.recentOnly) {
+        // Try Qdrant first
+        try {
+            const chunks = await searchQdrant(query, topK * 3, qdrantCfg);
+            if (chunks.length > 0) {
+                strategy = "qdrant";
+                // Deduplicate by filepath, preserve order
+                const seen = new Set();
+                const qdrantOrder = [];
+                for (const c of chunks) {
+                    if (!seen.has(c.filepath)) {
+                        seen.add(c.filepath);
+                        qdrantOrder.push(c.filepath);
+                    }
+                }
+                // Place Qdrant matches first, then remaining by TF-IDF + reward boost
+                const tfidfRanked = rankByRelevance(query, decompressed);
+                const tfidfOrder = tfidfRanked.map((s) => s.filepath).filter((fp) => !seen.has(fp));
+                const orderedFps = [...qdrantOrder, ...tfidfOrder];
+                const fpToDoc = new Map(decompressed.map((d) => [d.filepath, d]));
+                ranked = orderedFps.map((fp) => fpToDoc.get(fp)).filter(Boolean);
+            }
+            else {
+                ranked = rankAndBoost(query, decompressed, recentSet, fileRewards);
+            }
+        }
+        catch {
+            // Qdrant unreachable — fall back to TF-IDF
+            ranked = rankAndBoost(query, decompressed, recentSet, fileRewards);
+        }
+    }
+    else {
+        ranked = rankAndBoost(query, decompressed, recentSet, fileRewards);
+        if (opts.recentOnly)
+            strategy = "recent";
+    }
+    // ---------------------------------------------------------------------------
+    // Assemble context with token budget
+    // ---------------------------------------------------------------------------
+    const result = [];
+    let totalTokens = 0;
+    let truncated = false;
+    let skippedFiles = 0;
+    for (const file of ranked) {
+        if (totalTokens >= maxTokens) {
+            truncated = true;
+            break;
+        }
+        const remaining = maxTokens - totalTokens;
+        const fullTokens = estimateTokens(file.text);
+        const isRecent = recentSet.has(file.filepath);
+        let content;
+        let reason;
+        if (opts.skeletonOnly || fullTokens > maxPerFile) {
+            const sk = extractSkeleton(file.text, file.language);
+            const skText = renderSkeleton(sk, file.filepath);
+            const fragments = query ? extractFragments(file.text, query) : "";
+            content = fragments
+                ? `${skText}\n\n// — relevant fragments —\n${fragments}`
+                : skText;
+            reason = opts.skeletonOnly ? "skeleton" : `skeleton (${fullTokens} tokens > limit ${maxPerFile})`;
+        }
+        else {
+            content = file.text;
+            reason = "full";
+        }
+        if (isRecent)
+            reason += " +recent";
+        const contentTokens = estimateTokens(content);
+        if (contentTokens < 10) {
+            skippedFiles++;
+            continue;
+        }
+        // Truncate to remaining budget
+        const usedTokens = Math.min(contentTokens, remaining);
+        const finalContent = usedTokens < contentTokens
+            ? content.slice(0, usedTokens * 4) + "\n… [truncated]"
+            : content;
+        result.push({ filepath: file.filepath, language: file.language, tokens: usedTokens, content: finalContent, reason });
+        totalTokens += usedTokens;
+    }
+    skippedFiles += ranked.length - result.length - (truncated ? 0 : 0);
+    return { files: result, totalTokens, strategy, truncated, skippedFiles };
+}
+// ---------------------------------------------------------------------------
+// TF-IDF + recency boost ranking
+// ---------------------------------------------------------------------------
+function rankAndBoost(query, docs, recentSet, fileRewards) {
+    const scored = rankByRelevance(query, docs);
+    const scoreMap = new Map(scored.map((s) => [s.filepath, s.score]));
+    // Compute normalizer for experience boost (max 0.25, avoids dominating TF-IDF)
+    const maxReward = fileRewards && fileRewards.size > 0
+        ? Math.max(...fileRewards.values())
+        : 0;
+    return [...docs].sort((a, b) => {
+        const rewardBoostA = maxReward > 0 ? ((fileRewards.get(a.filepath) ?? 0) / maxReward) * 0.25 : 0;
+        const rewardBoostB = maxReward > 0 ? ((fileRewards.get(b.filepath) ?? 0) / maxReward) * 0.25 : 0;
+        const sA = (scoreMap.get(a.filepath) ?? 0) + (recentSet.has(a.filepath) ? 0.3 : 0) + rewardBoostA;
+        const sB = (scoreMap.get(b.filepath) ?? 0) + (recentSet.has(b.filepath) ? 0.3 : 0) + rewardBoostB;
+        return sB - sA;
+    });
+}

package/build/retrieval/qdrant.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedConfig } from "../config.js";
+type QdrantCfg = NonNullable<ResolvedConfig["qdrant"]>;
+export interface VectorChunk {
+    id: number;
+    filepath: string;
+    chunkIndex: number;
+    text: string;
+    score: number;
+}
+/** Index one file into Qdrant (called by sync_file when Qdrant is configured). */
+export declare function indexFileInQdrant(filepath: string, text: string, cfg: QdrantCfg): Promise<void>;
+/** Top-k semantic search across all indexed chunks. */
+export declare function searchQdrant(query: string, topK: number, cfg: QdrantCfg): Promise<VectorChunk[]>;
+/** Check if Qdrant collection exists and is reachable. */
+export declare function pingQdrant(cfg: QdrantCfg): Promise<boolean>;
+export {};