@pellux/goodvibes-sdk 0.37.2 → 0.38.0

package/dist/platform/state/code-index-store.js

@@ -0,0 +1,612 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * CodeIndexStore — an incremental, tree-sitter-chunked, embedding-backed index
+ * of a repo's source tree (Wave-5, W5.3, Stage A).
+ *
+ * Deliberately MIRRORS MemoryStore + SqliteVecMemoryIndex (state/memory-store.ts,
+ * state/memory-vector-store.ts) rather than reusing them: those classes are
+ * hard-keyed to MemoryRecord (schema columns, memoryVectorSourceHash,
+ * buildMemoryEmbeddingText, record-shaped search filters). Code chunks are a
+ * different record shape entirely, so this module is a parallel, independent
+ * implementation that reuses only:
+ *   - the sqlite-vec native extension loader (sqlite-vec-loader.ts)
+ *   - MEMORY_VECTOR_DIMS / the shared MemoryEmbeddingProviderRegistry instance,
+ *     so code and memory embeddings share one provider and one dimensionality.
+ *   - CodeIntelligence.getSymbols (tree-sitter-backed chunking; the chunking
+ *     itself lives in code-index-chunking.ts)
+ *   - the file-walk helpers already shipped for the `find` tool
+ *     (tools/find/shared.ts: buildGitignoreMatcher, findNestedGitignoreFiles,
+ *     collectGlobFiles, isBinary, readTextFile) — no new ignore-file parsing
+ *     or directory-walk logic. Ignore rules: the ROOT .gitignore plus nested
+ *     .gitignore files (each applied relative to its own directory). Nested
+ *     coverage is bounded by findNestedGitignoreFiles' own cap (currently the
+ *     first 5 nested files found, in walk order) — a repo with more nested
+ *     .gitignore files than that has the excess UNAPPLIED, same as the find
+ *     tool itself.
+ *
+ * Storage: a single bun:sqlite database (schema + all table ops live in
+ * code-index-db.ts) — `code_chunks` (chunk metadata), `code_vectors` (vec0
+ * virtual table), and `code_index_meta` (build provenance: the embedding
+ * provider id the index was last fully built with). When the current default
+ * embedding provider differs from the stored one, search() refuses to run the
+ * vector path — a query embedded in provider-Y space compared against
+ * provider-X vectors is meaningless — and degrades to an honestly-labeled
+ * lexical match over chunk symbol/path metadata until a rebuild re-embeds
+ * (buildFull() detects the mismatch and forces a full re-embed).
+ *
+ * Incremental reindex is LAZY, never a watcher: a recursive fs.watch over a
+ * repo tree is a per-file-descriptor liability and races the agent's own
+ * writes. `reindexFile()` re-chunks and re-embeds a single path on demand.
+ * `buildFull()` walks the whole tree once; concurrent calls coalesce through a
+ * single-flight promise guard, mirroring MemoryStore.rebuildVectorIndexAsync.
+ *
+ * Lifecycle honesty: `reroot()`/`close()` bump an epoch counter; an in-flight
+ * build re-checks the epoch after every await and aborts cleanly when stale
+ * (per-file writes are atomic — all of a file's chunks are embedded before any
+ * row is written — so an aborted build never writes wrong-rooted chunks into
+ * the new database). Aborted builds return stats carrying
+ * `abortReason: 'build aborted by reroot'` and never become `lastBuild`.
+ *
+ * The index never blocks a turn: buildFull() awaits `embedAsync` on a bounded
+ * per-file queue with periodic event-loop yields, and every read (`search`,
+ * `stats`) returns whatever is currently indexed — it never waits on an
+ * in-flight build.
+ */
+import { dirname, join, relative, sep } from 'node:path';
+import { mkdirSync, statSync } from 'node:fs';
+import { Database } from 'bun:sqlite';
+import { loadSqliteVecExtension } from './sqlite-vec-loader.js';
+import { HASHED_MEMORY_EMBEDDING_PROVIDER, MemoryEmbeddingProviderRegistry, normalizeMemoryEmbeddingVector, } from './memory-embeddings.js';
+import { MEMORY_VECTOR_DIMS } from './memory-vector-store.js';
+import { CodeIntelligence } from '../intelligence/facade.js';
+import { chunkFileContent, sha256, } from './code-index-chunking.js';
+import { CHUNK_ROW_COLUMNS, EMBEDDING_PROVIDER_META_KEY, createCodeIndexSchema, countChunksForPath, countIndexedChunks, countIndexedFiles, deleteChunksForPath, getChunkById, getCodeIndexMeta, getFileHash, listIndexedPaths, rowToChunk, setCodeIndexMeta, writeChunk, } from './code-index-db.js';
+import { buildGitignoreMatcher, collectGlobFiles, createFindDiagnostics, findNestedGitignoreFiles, isBinary, readTextFile, } from '../tools/find/shared.js';
+import { logger } from '../utils/logger.js';
+import { summarizeError } from '../utils/error-display.js';
+const DEFAULT_MAX_FILES = 5000;
+const DEFAULT_MAX_FILE_BYTES = 512 * 1024;
+const DEFAULT_MAX_TOTAL_BYTES = 256 * 1024 * 1024;
+const BUILD_ABORTED_BY_REROOT = 'build aborted by reroot';
+function distanceToSimilarity(distance) {
+    if (!Number.isFinite(distance))
+        return 0;
+    return Math.max(0, Math.min(1, 1 - distance / 2));
+}
+function yieldToEventLoop() {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, 0);
+        timer.unref?.();
+    });
+}
+function emptySkipReport() {
+    return { tooLarge: 0, overFileCap: 0, overTotalBytes: 0, binary: 0, ignoredByGitignore: 0, readErrors: 0, chunkedByWindow: 0 };
+}
+// ---------------------------------------------------------------------------
+// CodeIndexStore
+// ---------------------------------------------------------------------------
+export class CodeIndexStore {
+    embeddingRegistry;
+    options;
+    db = null;
+    available = false;
+    error;
+    building = false;
+    buildStartedAtMs = null;
+    buildPromise = null;
+    lastBuild = null;
+    progress = null;
+    intelligence;
+    intelligenceReadyPromise = null;
+    /**
+     * Lifecycle generation counter. Bumped by reroot() and close(); an in-flight
+     * runBuild() captures the value at start and re-checks it after EVERY await,
+     * aborting cleanly when stale so a build started against one root can never
+     * write wrong-rooted chunks into a database opened for a different root.
+     */
+    epoch = 0;
+    rootDir;
+    dbPath;
+    constructor(rootDir, dbPath, embeddingRegistry, options = {}) {
+        this.embeddingRegistry = embeddingRegistry;
+        this.options = options;
+        this.rootDir = rootDir;
+        this.dbPath = dbPath;
+        this.intelligence = new CodeIntelligence();
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+    init() {
+        if (this.db)
+            return;
+        try {
+            if (this.dbPath !== ':memory:') {
+                mkdirSync(dirname(this.dbPath), { recursive: true });
+            }
+            this.db = new Database(this.dbPath);
+            loadSqliteVecExtension(this.db);
+            this.available = true;
+            createCodeIndexSchema(this.db);
+        }
+        catch (err) {
+            this.close();
+            this.available = false;
+            this.error = summarizeError(err);
+            logger.warn('Code index unavailable', { backend: 'sqlite-vec', error: this.error });
+        }
+    }
+    close() {
+        if (!this.db)
+            return;
+        this.epoch++;
+        this.db.close();
+        this.db = null;
+        this.available = false;
+    }
+    /**
+     * Re-root the store to a new working directory + db path (workspace swap).
+     * Bumps the build epoch (aborting any in-flight build at its next await),
+     * closes existing handles, reopens at the new path, and clears in-memory
+     * build state. Does NOT re-trigger a build — the caller decides when to
+     * call scheduleBuild()/buildFull() again, exactly as it decided to open the
+     * store originally.
+     */
+    async reroot(newRootDir, newDbPath) {
+        this.epoch++;
+        this.close();
+        this.buildPromise = null;
+        this.building = false;
+        this.buildStartedAtMs = null;
+        this.lastBuild = null;
+        this.progress = null;
+        this.rootDir = newRootDir;
+        this.dbPath = newDbPath;
+        this.init();
+    }
+    // ── Status ───────────────────────────────────────────────────────────────
+    isBuilding() {
+        return this.building;
+    }
+    buildProgress() {
+        return this.building ? this.progress : null;
+    }
+    /** Wall-clock start time of the in-flight build, or null when idle. */
+    buildStartedAt() {
+        return this.building ? this.buildStartedAtMs : null;
+    }
+    /** True unless the only active embedding provider is the deterministic hashed fallback. */
+    hasSemanticProvider() {
+        return this.embeddingRegistry.getDefaultProviderId() !== HASHED_MEMORY_EMBEDDING_PROVIDER.id;
+    }
+    /** Stated once, honest: why Stage-B auto-retrieval (a later wave) would be absent right now. Null when a real provider is active. */
+    describeDegradation() {
+        return this.hasSemanticProvider()
+            ? null
+            : 'code auto-retrieval disabled: no semantic embedding provider configured';
+    }
+    /**
+     * Human-readable provider-space mismatch, or null when the stored vectors
+     * were built with the current default provider (or provenance is unknown —
+     * an index that predates provenance tracking keeps its legacy behavior
+     * until the next build stamps it).
+     */
+    getProviderMismatch() {
+        if (!this.db || !this.available)
+            return null;
+        const stored = getCodeIndexMeta(this.db, EMBEDDING_PROVIDER_META_KEY);
+        const current = this.embeddingRegistry.getDefaultProviderId();
+        if (stored === null || stored === current)
+            return null;
+        return `embeddings built with ${stored}, current provider ${current} — rebuild to re-embed`;
+    }
+    stats() {
+        const provider = this.embeddingRegistry.getDefaultProviderOrNull();
+        const mismatch = this.getProviderMismatch();
+        return {
+            backend: 'sqlite-vec',
+            enabled: this.available,
+            available: this.available,
+            path: this.dbPath,
+            dimensions: MEMORY_VECTOR_DIMS,
+            indexedFiles: this.db && this.available ? countIndexedFiles(this.db) : 0,
+            indexedChunks: this.db && this.available ? countIndexedChunks(this.db) : 0,
+            embeddingProviderId: provider?.id ?? this.embeddingRegistry.getDefaultProviderId(),
+            embeddingProviderLabel: provider?.label ?? `Unregistered (${this.embeddingRegistry.getDefaultProviderId()})`,
+            semanticRetrievalAvailable: this.hasSemanticProvider(),
+            ...(mismatch ? { embeddingProviderMismatch: mismatch } : {}),
+            building: this.building,
+            lastBuild: this.lastBuild,
+            ...(this.error ? { error: this.error } : {}),
+        };
+    }
+    // ── Search (Stage A explicit query) ─────────────────────────────────────
+    search(query, opts = {}) {
+        if (!this.db || !this.available)
+            return [];
+        const trimmed = query.trim();
+        if (!trimmed)
+            return [];
+        const limit = Math.max(1, Math.min(50, opts.limit ?? 10));
+        // Provider-space honesty: a query embedded under the CURRENT provider is
+        // meaningless against vectors stored under a DIFFERENT one — skip the
+        // vector path entirely and degrade to lexical metadata matching.
+        if (this.getProviderMismatch() !== null) {
+            return this.searchLexical(trimmed, limit);
+        }
+        let embedding;
+        try {
+            const result = this.embeddingRegistry.embedSync({
+                text: trimmed,
+                dimensions: MEMORY_VECTOR_DIMS,
+                usage: 'query',
+            });
+            embedding = normalizeMemoryEmbeddingVector(result.vector, MEMORY_VECTOR_DIMS);
+        }
+        catch (err) {
+            logger.warn('Code index query embedding failed', { error: summarizeError(err) });
+            return [];
+        }
+        const rows = this.db.query('SELECT rowid, chunk_id, distance FROM code_vectors WHERE embedding MATCH ? AND k = ? ORDER BY distance').all(embedding, limit);
+        const label = this.hasSemanticProvider() ? 'semantic' : 'lexical';
+        const results = [];
+        for (const row of rows) {
+            const chunk = getChunkById(this.db, row.chunk_id);
+            if (!chunk)
+                continue;
+            results.push({
+                chunk,
+                distance: Number(row.distance),
+                similarity: distanceToSimilarity(Number(row.distance)),
+                label,
+            });
+        }
+        return results;
+    }
+    /**
+     * Lexical fallback used when the vector path is disabled by a provider
+     * mismatch: token match over chunk symbol/path metadata (chunk text is not
+     * stored, so this is name/path matching only — labeled 'lexical', never
+     * 'semantic'). Similarity is the matched-token fraction.
+     */
+    searchLexical(query, limit) {
+        if (!this.db)
+            return [];
+        const tokens = Array.from(new Set(query.toLowerCase().split(/[^a-z0-9_$]+/).filter((token) => token.length >= 2)));
+        if (tokens.length === 0)
+            return [];
+        const where = tokens.map(() => '(lower(symbol) LIKE ? OR lower(path) LIKE ?)').join(' OR ');
+        const bindings = tokens.flatMap((token) => [`%${token}%`, `%${token}%`]);
+        const rows = this.db.query(`SELECT ${CHUNK_ROW_COLUMNS} FROM code_chunks WHERE ${where} LIMIT ?`).all(...bindings, limit * 5);
+        const scored = rows.map((row) => {
+            const haystack = `${row.symbol} ${row.path}`.toLowerCase();
+            const matched = tokens.filter((token) => haystack.includes(token)).length;
+            const similarity = matched / tokens.length;
+            return {
+                chunk: rowToChunk(row),
+                distance: 2 * (1 - similarity),
+                similarity,
+                label: 'lexical',
+            };
+        });
+        scored.sort((a, b) => b.similarity - a.similarity);
+        return scored.slice(0, limit);
+    }
+    // ── Build / reindex ──────────────────────────────────────────────────────
+    /** Fire-and-forget kickoff; concurrent/repeated calls while a build is running are no-ops. Never awaited by the caller — never blocks a turn. */
+    scheduleBuild() {
+        if (this.building)
+            return;
+        void this.buildFull().catch((err) => {
+            logger.warn('Code index build failed', { error: summarizeError(err) });
+        });
+    }
+    /** Full source-tree walk. Concurrent calls coalesce onto the same in-flight promise (mirrors MemoryStore.rebuildVectorIndexAsync). */
+    async buildFull() {
+        if (!this.db || !this.available) {
+            return this.lastBuild ?? emptyBuildStats();
+        }
+        if (!this.buildPromise) {
+            const buildEpoch = this.epoch;
+            this.building = true;
+            this.buildStartedAtMs = Date.now();
+            this.progress = { scanned: 0, total: 0 };
+            this.buildPromise = this.runBuild(buildEpoch).finally(() => {
+                // A reroot() already reset these for the NEW lifecycle; a stale
+                // build's cleanup must not clobber state belonging to a newer epoch.
+                if (this.epoch === buildEpoch) {
+                    this.building = false;
+                    this.buildStartedAtMs = null;
+                    this.buildPromise = null;
+                    this.progress = null;
+                }
+            });
+        }
+        return this.buildPromise;
+    }
+    /**
+     * Reindex a single file on demand. Intended to be called from the file
+     * read/write tool paths and from an explicit reindex command — wiring
+     * those call sites is out of scope for this module (see module doc).
+     * A no-op (chunks removed) if the path is gitignored or no longer exists.
+     */
+    async reindexFile(absPath) {
+        if (!this.db || !this.available)
+            return { indexed: false, mode: 'empty' };
+        const callEpoch = this.epoch;
+        const rel = relative(this.rootDir, absPath);
+        if (rel.startsWith('..'))
+            return { indexed: false, mode: 'empty' };
+        const diagnostics = createFindDiagnostics();
+        const isIgnored = this.buildIgnoreMatcher(diagnostics);
+        if (isIgnored(absPath, rel)) {
+            deleteChunksForPath(this.db, rel);
+            return { indexed: false, mode: 'empty' };
+        }
+        let stat;
+        try {
+            stat = statSync(absPath);
+        }
+        catch {
+            deleteChunksForPath(this.db, rel);
+            return { indexed: false, mode: 'empty' };
+        }
+        const maxFileBytes = this.options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+        if (stat.size > maxFileBytes)
+            return { indexed: false, mode: 'empty' };
+        if (await isBinary(absPath, diagnostics))
+            return { indexed: false, mode: 'empty' };
+        const text = await readTextFile(absPath, diagnostics);
+        if (text === null)
+            return { indexed: false, mode: 'empty' };
+        const outcome = await this.indexFileContent(rel, absPath, text, stat.mtimeMs, callEpoch, false);
+        if (outcome === null)
+            return { indexed: false, mode: 'empty' };
+        return { indexed: outcome.indexed, mode: outcome.mode };
+    }
+    // ── Build internals ──────────────────────────────────────────────────────
+    async runBuild(buildEpoch) {
+        const startedAt = Date.now();
+        const diagnostics = createFindDiagnostics();
+        const maxFiles = this.options.maxFiles ?? DEFAULT_MAX_FILES;
+        const maxFileBytes = this.options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+        const maxTotalBytes = this.options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
+        const skip = emptySkipReport();
+        // Provider-space honesty: if the stored vectors were embedded under a
+        // different provider than the current default, the unchanged-file
+        // shortcut would silently keep stale-space vectors — force a full
+        // re-embed so a completed build always leaves a single-provider index.
+        const currentProviderId = this.embeddingRegistry.getDefaultProviderId();
+        const storedProviderId = this.db ? getCodeIndexMeta(this.db, EMBEDDING_PROVIDER_META_KEY) : null;
+        const forceReembed = storedProviderId !== null && storedProviderId !== currentProviderId;
+        const isIgnored = this.buildIgnoreMatcher(diagnostics);
+        const scanned = await collectGlobFiles(this.rootDir, ['**/*'], false, false, diagnostics);
+        if (this.epoch !== buildEpoch)
+            return abortedBuildStats(startedAt, scanned.size, skip);
+        // Deterministic order so identical trees always chunk identically (chunking determinism test).
+        const candidateFiles = Array.from(scanned).sort();
+        const keepPaths = new Set();
+        let filesIndexed = 0;
+        let filesUnchanged = 0;
+        let chunksIndexed = 0;
+        let chunksUnchanged = 0;
+        let totalBytes = 0;
+        let acceptedCount = 0;
+        for (const absPath of candidateFiles) {
+            const rel = relative(this.rootDir, absPath);
+            if (isIgnored(absPath, rel)) {
+                skip.ignoredByGitignore++;
+                continue;
+            }
+            if (acceptedCount >= maxFiles) {
+                skip.overFileCap++;
+                continue;
+            }
+            let stat;
+            try {
+                stat = statSync(absPath);
+            }
+            catch {
+                skip.readErrors++;
+                continue;
+            }
+            if (stat.size > maxFileBytes) {
+                skip.tooLarge++;
+                continue;
+            }
+            if (totalBytes + stat.size > maxTotalBytes) {
+                skip.overTotalBytes++;
+                continue;
+            }
+            const binary = await isBinary(absPath, diagnostics);
+            if (this.epoch !== buildEpoch)
+                return abortedBuildStats(startedAt, candidateFiles.length, skip);
+            if (binary) {
+                skip.binary++;
+                continue;
+            }
+            const text = await readTextFile(absPath, diagnostics);
+            if (this.epoch !== buildEpoch)
+                return abortedBuildStats(startedAt, candidateFiles.length, skip);
+            if (text === null) {
+                skip.readErrors++;
+                continue;
+            }
+            acceptedCount++;
+            totalBytes += stat.size;
+            keepPaths.add(rel);
+            const outcome = await this.indexFileContent(rel, absPath, text, stat.mtimeMs, buildEpoch, forceReembed);
+            if (outcome === null)
+                return abortedBuildStats(startedAt, candidateFiles.length, skip);
+            if (outcome.mode === 'window')
+                skip.chunkedByWindow++;
+            if (outcome.mode === 'unchanged') {
+                filesUnchanged++;
+                chunksUnchanged += outcome.chunkCount;
+            }
+            else {
+                if (outcome.indexed)
+                    filesIndexed++;
+                chunksIndexed += outcome.chunkCount;
+            }
+            this.progress = { scanned: acceptedCount, total: candidateFiles.length };
+            if (acceptedCount % 20 === 0) {
+                await yieldToEventLoop();
+                if (this.epoch !== buildEpoch)
+                    return abortedBuildStats(startedAt, candidateFiles.length, skip);
+            }
+        }
+        // Final staleness check before the destructive sweep: a stale build's
+        // keepPaths describes the OLD tree and must never delete the new one's rows.
+        if (this.epoch !== buildEpoch || !this.db) {
+            return abortedBuildStats(startedAt, candidateFiles.length, skip);
+        }
+        // Sweep: a file that no longer exists (deleted, renamed, or newly gitignored) loses its chunks.
+        let filesRemoved = 0;
+        for (const path of listIndexedPaths(this.db)) {
+            if (!keepPaths.has(path)) {
+                deleteChunksForPath(this.db, path);
+                filesRemoved++;
+            }
+        }
+        // Stamp provenance only on a COMPLETED build — every chunk that survives
+        // to this point is either freshly embedded under currentProviderId or was
+        // verified same-provider by the forceReembed logic above.
+        setCodeIndexMeta(this.db, EMBEDDING_PROVIDER_META_KEY, currentProviderId);
+        const completedAt = Date.now();
+        const stats = {
+            filesScanned: candidateFiles.length,
+            filesIndexed,
+            filesUnchanged,
+            chunksIndexed,
+            chunksUnchanged,
+            filesRemoved,
+            skip: Object.freeze({ ...skip }),
+            startedAt,
+            completedAt,
+            durationMs: completedAt - startedAt,
+        };
+        this.lastBuild = stats;
+        return stats;
+    }
+    /**
+     * Compose the root .gitignore with any nested .gitignore files (each nested
+     * file's patterns apply relative to its own directory, per git semantics).
+     * Nested coverage is bounded by findNestedGitignoreFiles' cap (see module doc).
+     */
+    buildIgnoreMatcher(diagnostics) {
+        const rootGitignorePath = join(this.rootDir, '.gitignore');
+        const rootMatcher = buildGitignoreMatcher(rootGitignorePath, diagnostics);
+        const nested = findNestedGitignoreFiles(this.rootDir, rootGitignorePath)
+            .map((path) => ({ dir: dirname(path), matcher: buildGitignoreMatcher(path, diagnostics) }))
+            .filter((entry) => entry.matcher !== null);
+        return (absPath, rel) => {
+            if (rootMatcher !== null && rootMatcher(rel))
+                return true;
+            for (const entry of nested) {
+                if (absPath.startsWith(entry.dir + sep) && entry.matcher(relative(entry.dir, absPath))) {
+                    return true;
+                }
+            }
+            return false;
+        };
+    }
+    /**
+     * Index one file's content. Short-circuits on an unchanged file_hash (no
+     * re-chunk, no re-embed) — the "content_hash stable across re-index of
+     * unchanged file" contract — unless forceReembed is set (provider mismatch).
+     *
+     * Epoch honesty: all of a file's chunks are embedded (every await) BEFORE
+     * any row is deleted or written, and the epoch is re-checked after each
+     * await — so a reroot() mid-file aborts with the database untouched for
+     * that file (returns null; the caller abandons the build).
+     */
+    async indexFileContent(relPath, absPath, content, mtimeMs, callEpoch, forceReembed) {
+        if (!this.db)
+            return null;
+        const fileHash = sha256(content);
+        if (!forceReembed) {
+            const existingHash = getFileHash(this.db, relPath);
+            if (existingHash === fileHash) {
+                return { indexed: true, mode: 'unchanged', chunkCount: countChunksForPath(this.db, relPath) };
+            }
+        }
+        await this.ensureIntelligenceReady();
+        if (this.epoch !== callEpoch)
+            return null;
+        const { drafts, mode } = await chunkFileContent({
+            intelligence: this.intelligence,
+            absPath,
+            relPath,
+            content,
+            fileHash,
+            mtimeMs,
+            windowLines: this.options.windowLines,
+            windowOverlapLines: this.options.windowOverlapLines,
+        });
+        if (this.epoch !== callEpoch)
+            return null;
+        const embeddings = [];
+        for (const draft of drafts) {
+            const embedding = await this.embedChunkAsync(draft.embedText);
+            if (this.epoch !== callEpoch)
+                return null;
+            embeddings.push(embedding);
+        }
+        // All awaits are done — the delete+write below is synchronous, so the
+        // whole file lands atomically with respect to reroot()/close().
+        if (!this.db)
+            return null;
+        deleteChunksForPath(this.db, relPath);
+        for (let i = 0; i < drafts.length; i++) {
+            writeChunk(this.db, drafts[i].chunk, embeddings[i]);
+        }
+        return { indexed: drafts.length > 0 || mode === 'empty', mode, chunkCount: drafts.length };
+    }
+    async ensureIntelligenceReady() {
+        if (!this.intelligenceReadyPromise) {
+            this.intelligenceReadyPromise = this.intelligence.initialize().catch((err) => {
+                logger.warn('CodeIndexStore: tree-sitter init failed', { error: summarizeError(err) });
+            });
+        }
+        return this.intelligenceReadyPromise;
+    }
+    async embedChunkAsync(text) {
+        const result = await this.embeddingRegistry.embedAsync({
+            text,
+            dimensions: MEMORY_VECTOR_DIMS,
+            usage: 'record',
+        });
+        return normalizeMemoryEmbeddingVector(result.vector, MEMORY_VECTOR_DIMS);
+    }
+}
+function abortedBuildStats(startedAt, filesScanned, skip) {
+    const completedAt = Date.now();
+    logger.warn('Code index build aborted by reroot', { filesScanned });
+    return {
+        filesScanned,
+        filesIndexed: 0,
+        filesUnchanged: 0,
+        chunksIndexed: 0,
+        chunksUnchanged: 0,
+        filesRemoved: 0,
+        skip: Object.freeze({ ...skip }),
+        startedAt,
+        completedAt,
+        durationMs: completedAt - startedAt,
+        abortReason: BUILD_ABORTED_BY_REROOT,
+    };
+}
+function emptyBuildStats() {
+    const now = Date.now();
+    return {
+        filesScanned: 0,
+        filesIndexed: 0,
+        filesUnchanged: 0,
+        chunksIndexed: 0,
+        chunksUnchanged: 0,
+        filesRemoved: 0,
+        skip: emptySkipReport(),
+        startedAt: now,
+        completedAt: now,
+        durationMs: 0,
+    };
+}

package/dist/platform/state/index.d.ts

@@ -24,6 +24,8 @@ export type { MemoryVectorCandidate, MemoryVectorStats } from './memory-vector-s
 export { DEFAULT_MEMORY_EMBEDDING_DIMS, HASHED_MEMORY_EMBEDDING_PROVIDER, MemoryEmbeddingProviderRegistry, normalizeMemoryEmbeddingVector, } from './memory-embeddings.js';
 export { createBuiltinMemoryEmbeddingProviders } from './memory-embedding-http.js';
 export type { MemoryEmbeddingDoctorReport, MemoryEmbeddingProvider, MemoryEmbeddingProviderState, MemoryEmbeddingProviderStatus, MemoryEmbeddingRequest, MemoryEmbeddingResult, MemoryEmbeddingUsage, } from './memory-embeddings.js';
-export type { KnowledgeInjection } from './knowledge-injection.js';
-export { selectKnowledgeForTask, buildKnowledgeInjectionPrompt } from './knowledge-injection.js';
+export type { KnowledgeInjection, ScoredKnowledgeInjection } from './knowledge-injection.js';
+export { selectKnowledgeForTask, selectKnowledgeForTaskScored, buildKnowledgeInjectionPrompt } from './knowledge-injection.js';
+export { CodeIndexStore } from './code-index-store.js';
+export type { CodeChunk, CodeChunkMode, CodeContextResult, CodeIndexBuildProgress, CodeIndexBuildStats, CodeIndexOptions, CodeIndexSkipReport, CodeIndexStats, } from './code-index-store.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/platform/state/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,6BAA6B,EAC7B,gCAAgC,EAChC,mCAAmC,EACnC,oCAAoC,GACrC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACzF,OAAO,EACL,6BAA6B,EAC7B,gCAAgC,EAChC,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,qCAAqC,EAAE,MAAM,4BAA4B,CAAC;AACnF,YAAY,EACV,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,6BAA6B,EAC7B,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,0BAA0B,EAC1B,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,6BAA6B,EAC7B,gCAAgC,EAChC,mCAAmC,EACnC,oCAAoC,GACrC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACzF,OAAO,EACL,6BAA6B,EAC7B,gCAAgC,EAChC,+BAA+B,EAC/B,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,qCAAqC,EAAE,MAAM,4BAA4B,CAAC;AACnF,YAAY,EACV,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,6BAA6B,EAC7B,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAC7F,OAAO,EAAE,sBAAsB,EAAE,4BAA4B,EAAE,6BAA6B,EAAE,MAAM,0BAA0B,CAAC;AAC/H,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,GACf,MAAM,uBAAuB,CAAC"}

package/dist/platform/state/index.js

@@ -15,4 +15,5 @@ export { buildIncidentMemoryAddOptions, buildMcpSecurityMemoryAddOptions, buildP
 export { MEMORY_VECTOR_DIMS, embedMemoryText, resolveMemoryVectorDbPath, SqliteVecMemoryIndex, } from './memory-vector-store.js';
 export { DEFAULT_MEMORY_EMBEDDING_DIMS, HASHED_MEMORY_EMBEDDING_PROVIDER, MemoryEmbeddingProviderRegistry, normalizeMemoryEmbeddingVector, } from './memory-embeddings.js';
 export { createBuiltinMemoryEmbeddingProviders } from './memory-embedding-http.js';
-export { selectKnowledgeForTask, buildKnowledgeInjectionPrompt } from './knowledge-injection.js';
+export { selectKnowledgeForTask, selectKnowledgeForTaskScored, buildKnowledgeInjectionPrompt } from './knowledge-injection.js';
+export { CodeIndexStore } from './code-index-store.js';

package/dist/platform/state/knowledge-injection.d.ts

@@ -18,6 +18,29 @@ type KnowledgeRegistrySource = {
     getAll(): readonly MemoryRecord[];
     searchSemantic?(input: Parameters<MemoryRegistry['searchSemantic']>[0]): readonly MemorySemanticSearchResult[];
 };
+/**
+ * One scored candidate from the ranking pipeline: the fully-built
+ * `KnowledgeInjection` plus the numeric score that placed it, before any
+ * `limit` slice is applied. Exists so callers other than the spawn-time
+ * baseline (e.g. per-turn retrieval in turn-knowledge-injection.ts) can
+ * apply their own relevance floor / budget trim over the SAME ranked list
+ * without re-implementing scoreKnowledge/determineReason/determineIngestMode.
+ */
+export interface ScoredKnowledgeInjection {
+    readonly injection: KnowledgeInjection;
+    readonly score: number;
+}
+/**
+ * Full ranking pipeline, unsliced: scores every registry record that clears
+ * the confidence>=55 gate against `task`/`writeScope`, folds in semantic
+ * similarity when the registry supports it, and returns every candidate with
+ * score>0 sorted best-first. `limit` only widens the semantic-search
+ * candidate pool (`Math.max(limit*4,12)`, mirroring the historical
+ * behavior) — it does NOT slice the returned array. Callers that want the
+ * spawn-time top-N behavior should slice the result themselves; see
+ * `selectKnowledgeForTask` below.
+ */
+export declare function selectKnowledgeForTaskScored(registry: KnowledgeRegistrySource, task: string, writeScope?: readonly string[], limit?: number): ScoredKnowledgeInjection[];
 export declare function selectKnowledgeForTask(registry: KnowledgeRegistrySource, task: string, writeScope?: readonly string[], limit?: number): KnowledgeInjection[];
 export declare function buildKnowledgeInjectionPrompt(injections: readonly KnowledgeInjectionPromptInput[]): string | null;
 export {};