akm-cli 0.8.0-rc1 → 0.8.0

package/dist/indexer/ensure-index.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Auto-index: silently run an incremental `akm index` when the local index
  * is stale or absent, so that `search`, `show`, and `feedback` always operate

package/dist/indexer/file-context.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Flexible asset resolution system.
  *

package/dist/indexer/graph-boost.js

@@ -1,26 +1,31 @@
-/**
- * Search-time graph-boost integration for the `akm index` graph pass (#207).
- *
- * This module is the consumer half of the graph-extraction pass. It loads
- * the persisted graph snapshot from SQLite and exposes a single helper,
- * {@link computeGraphBoost}, that the existing FTS5+boosts loop in
- * `src/indexer/db-search.ts` calls per-entry to obtain an additive boost
- * value.
- *
- * CLAUDE.md / v1 spec compliance:
- *   - The graph signal feeds the **single** FTS5+boosts pipeline as one
- *     additive boost component. There is no parallel scoring track.
- *   - There is no second `SearchHit` scorer. `searchDatabase` continues to
- *     own ranking; this module just answers "what additive boost does the
- *     graph contribute for this (query, entry) pair?".
- *   - Missing graph rows → boost is `0`. The pipeline
- *     degrades gracefully to its non-graph behaviour, exactly as today.
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { loadStoredGraphMeta, loadStoredGraphSnapshot } from "./graph-db";
 function normalizeGraphName(value) {
     return value.trim().toLowerCase();
 }
 let cachedParsedGraph;
+/**
+ * Clear the module-level parsed-graph cache.
+ *
+ * The cache keeps the most recently parsed `ParsedGraphContext` keyed by
+ * (stashPath, generatedAt) tuples so back-to-back search invocations within
+ * the same process don't re-read the SQLite snapshot from disk. The cache
+ * persists across calls — which is the desired behaviour in production but
+ * pathological for tests that swap the underlying stash directory between
+ * test cases without bumping `generatedAt`. Such tests can observe stale
+ * graph nodes from a previous test's stash.
+ *
+ * Tests (and any tooling that swaps stash backings) should call this between
+ * setups to guarantee the next `loadGraphBoostContext` reads fresh state.
+ * Recommended placement: `beforeEach` for test files that mutate graph
+ * state, or after `deleteStoredGraph` / `replaceStoredGraph` calls that
+ * intentionally invalidate the cache.
+ */
+export function resetGraphBoostCache() {
+    cachedParsedGraph = undefined;
+}
 function resolveGraphBoostWeights(config) {
     const configured = config?.search?.graphBoost;
     return {
@@ -232,33 +237,150 @@ export function collectGraphRelatedHit(context, filePath) {
         relations,
     };
 }
+/**
+ * Find graph files that share entities with the given file.
+ *
+ * Implementation: SQL self-join on graph_file_entities, scoped by stash_root,
+ * grouped by entry_id, ordered by shared-entity count desc. Touches ~50-200
+ * rows instead of loading the entire snapshot into memory. Cold-call latency
+ * drops from ~30-60ms (full snapshot parse) to ~2-5ms on typical stashes.
+ *
+ * The returned `ref` field carries the canonical asset ref (`type:name`)
+ * resolved from entries.entry_key when the entry is indexed. Callers should
+ * fall back to formatting `path` when `ref` is undefined (orphan graph row).
+ */
 export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
-    const parsed = readParsedGraphContext([stashRoot], db);
-    if (!parsed)
+    if (!db) {
+        // Fallback: opening a transient DB here is not currently a use case (all
+        // callers pass a handle), so degrade to empty rather than reopening.
         return [];
-    const node = parsed.nodesByPath.get(filePath);
-    if (!node)
+    }
+    // Resolve target's entry_id from the stash_root + file_path. The graph rows
+    // are keyed on entry_id; without it we can't run the join.
+    let targetEntryId;
+    try {
+        const row = db
+            .prepare("SELECT entry_id FROM graph_files WHERE stash_root = ? AND file_path = ? LIMIT 1")
+            .get(stashRoot, filePath);
+        targetEntryId = row?.entry_id;
+    }
+    catch {
         return [];
-    const entitySet = new Set(node.entities.map(normalizeGraphName));
-    const results = [];
-    for (const candidate of parsed.graph.files) {
-        if (candidate.path === filePath)
-            continue;
-        const sharedEntities = candidate.entities.filter((entity) => entitySet.has(normalizeGraphName(entity)));
-        if (sharedEntities.length === 0)
+    }
+    if (targetEntryId == null)
+        return [];
+    const effectiveLimit = Math.max(1, limit);
+    // Shared-entity count per candidate entry_id.
+    let candidateRows;
+    try {
+        candidateRows = db
+            .prepare(`SELECT gf.entry_id    AS entry_id,
+                gf.file_path   AS file_path,
+                gf.file_type   AS file_type,
+                COUNT(*)       AS shared
+            FROM graph_file_entities target
+            JOIN graph_file_entities e
+              ON e.stash_root = target.stash_root
+             AND e.entity_norm = target.entity_norm
+             AND e.entry_id  != target.entry_id
+            JOIN graph_files gf
+              ON gf.entry_id = e.entry_id
+          WHERE target.entry_id  = ?
+            AND target.stash_root = ?
+          GROUP BY gf.entry_id
+          ORDER BY shared DESC, gf.file_path ASC
+          LIMIT ?`)
+            .all(targetEntryId, stashRoot, effectiveLimit);
+    }
+    catch {
+        return [];
+    }
+    if (candidateRows.length === 0)
+        return [];
+    const candidateIds = candidateRows.map((r) => r.entry_id);
+    const placeholders = candidateIds.map(() => "?").join(",");
+    // Pull the shared entity names (joined by normalized casing) for display.
+    const sharedRows = db
+        .prepare(`SELECT e.entry_id AS entry_id, e.entity AS entity
+         FROM graph_file_entities e
+         JOIN graph_file_entities target
+           ON target.stash_root = e.stash_root
+           AND target.entity_norm = e.entity_norm
+         WHERE e.entry_id IN (${placeholders})
+           AND target.entry_id = ?
+           AND target.stash_root = ?`)
+        .all(...candidateIds, targetEntryId, stashRoot);
+    const sharedByEntry = new Map();
+    for (const row of sharedRows) {
+        let bucket = sharedByEntry.get(row.entry_id);
+        if (!bucket) {
+            bucket = new Set();
+            sharedByEntry.set(row.entry_id, bucket);
+        }
+        bucket.add(row.entity);
+    }
+    // Relation count for each candidate (relations where either endpoint
+    // matches one of the shared entities).
+    const relationCountByEntry = new Map();
+    const relationRows = db
+        .prepare(`SELECT entry_id, from_entity, to_entity
+         FROM graph_file_relations
+        WHERE entry_id IN (${placeholders})`)
+        .all(...candidateIds);
+    for (const row of relationRows) {
+        const shared = sharedByEntry.get(row.entry_id);
+        if (!shared)
             continue;
-        const relationCount = candidate.relations.filter((relation) => entitySet.has(normalizeGraphName(relation.from)) || entitySet.has(normalizeGraphName(relation.to))).length;
-        results.push({
-            path: candidate.path,
-            type: candidate.type,
-            sharedEntities: [...new Set(sharedEntities)].sort((a, b) => a.localeCompare(b)),
-            relationCount,
-        });
+        if (shared.has(row.from_entity) || shared.has(row.to_entity)) {
+            relationCountByEntry.set(row.entry_id, (relationCountByEntry.get(row.entry_id) ?? 0) + 1);
+        }
+    }
+    // Optional: ref lookup via entries.entry_key. entry_key is stored as
+    // `${stash_dir}:${type}:${name}` — strip the stash-dir prefix to get the
+    // user-facing `type:name`.
+    const refByEntryId = new Map();
+    try {
+        const entryRows = db
+            .prepare(`SELECT id, entry_key, stash_dir FROM entries WHERE id IN (${placeholders})`)
+            .all(...candidateIds);
+        for (const row of entryRows) {
+            const ref = stripStashPrefix(row.entry_key, row.stash_dir);
+            if (ref)
+                refByEntryId.set(row.id, ref);
+        }
     }
-    results.sort((a, b) => b.sharedEntities.length - a.sharedEntities.length ||
-        b.relationCount - a.relationCount ||
-        a.path.localeCompare(b.path));
-    return results.slice(0, Math.max(1, limit));
+    catch {
+        /* ignore — refs are best-effort */
+    }
+    return candidateRows.map((row) => {
+        const sharedSet = sharedByEntry.get(row.entry_id) ?? new Set();
+        const sharedEntities = [...sharedSet].sort((a, b) => a.localeCompare(b));
+        const ref = refByEntryId.get(row.entry_id);
+        return {
+            ...(ref ? { ref } : {}),
+            path: row.file_path,
+            type: row.file_type,
+            sharedEntities,
+            relationCount: relationCountByEntry.get(row.entry_id) ?? 0,
+        };
+    });
+}
+/**
+ * Convert an entries.entry_key to a user-facing asset ref. Entry keys are
+ * stored as `${stash_dir}:${type}:${name}`; strip the stash-dir prefix.
+ */
+function stripStashPrefix(entryKey, stashDir) {
+    const prefix = `${stashDir}:`;
+    if (entryKey.startsWith(prefix))
+        return entryKey.slice(prefix.length);
+    // Fall back to last two colon-separated segments.
+    const lastColon = entryKey.lastIndexOf(":");
+    if (lastColon < 0)
+        return entryKey;
+    const prevColon = entryKey.lastIndexOf(":", lastColon - 1);
+    if (prevColon < 0)
+        return entryKey;
+    return entryKey.slice(prevColon + 1);
 }
 /**
  * Load and normalize graph data from SQLite once, then reuse it across all

package/dist/indexer/graph-db.js

@@ -1,5 +1,10 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
+import { rethrowIfTestIsolationError } from "../core/errors";
 import { getDbPath } from "../core/paths";
+import { warn } from "../core/warn";
 import { closeDatabase, openExistingDatabase } from "./db";
 function withReadableGraphDb(db, fn) {
     if (db)
@@ -18,6 +23,42 @@ function withReadableGraphDb(db, fn) {
 function uniqueSorted(values) {
     return [...new Set(values)].sort((a, b) => a.localeCompare(b));
 }
+function normalizeEntity(value) {
+    return value.trim().toLowerCase();
+}
+/**
+ * Resolve a file_path within a stash to its entries.id. Returns null when the
+ * path has no indexed entry (orphan graph row).
+ */
+export function resolveEntryIdForPath(db, stashRoot, filePath) {
+    try {
+        const row = db
+            .prepare("SELECT id FROM entries WHERE stash_dir = ? AND file_path = ? LIMIT 1")
+            .get(stashRoot, filePath);
+        if (row)
+            return row.id;
+        // Fall back to file_path-only match (legacy callers may pass a stash root
+        // that doesn't exactly match entries.stash_dir, e.g. trailing-slash diffs).
+        const fallback = db.prepare("SELECT id FROM entries WHERE file_path = ? LIMIT 1").get(filePath);
+        return fallback?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist (or update) a graph snapshot for a stash root.
+ *
+ * Implementation: incremental upsert keyed on entries.id. Unchanged files
+ * (matching body_hash) are skipped; changed files have their child rows
+ * deleted (CASCADE) and re-inserted; files in DB but absent from the new
+ * snapshot are deleted. The old behaviour wiped every row for the stash on
+ * each write, which produced ~22k row writes per re-index even when one
+ * asset changed.
+ *
+ * Orphan files (no entries row resolvable) are skipped and counted in a
+ * single warn() so the caller sees the magnitude without log spam.
+ */
 export function replaceStoredGraph(db, graph) {
     const upsertMeta = db.prepare(`INSERT INTO graph_meta (
        stash_root,
@@ -28,58 +69,172 @@ export function replaceStoredGraph(db, graph) {
        entity_count,
        relation_count,
        extraction_coverage,
-       density
-     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       density,
+       extractor_id,
+       extraction_run_id,
+       model,
+       prompt_version,
+       batch_size,
+       cache_hits,
+       cache_misses,
+       truncation_count,
+       failure_count
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
      ON CONFLICT(stash_root) DO UPDATE SET
-       schema_version = excluded.schema_version,
-       generated_at = excluded.generated_at,
-       considered_files = excluded.considered_files,
-       extracted_files = excluded.extracted_files,
-       entity_count = excluded.entity_count,
-       relation_count = excluded.relation_count,
-       extraction_coverage = excluded.extraction_coverage,
-       density = excluded.density`);
-    const deleteRelations = db.prepare("DELETE FROM graph_file_relations WHERE stash_root = ?");
-    const deleteEntities = db.prepare("DELETE FROM graph_file_entities WHERE stash_root = ?");
-    const deleteFiles = db.prepare("DELETE FROM graph_files WHERE stash_root = ?");
-    const insertFile = db.prepare(`INSERT INTO graph_files (stash_root, file_path, file_order, file_type, body_hash, confidence)
-     VALUES (?, ?, ?, ?, ?, ?)`);
-    const insertEntity = db.prepare(`INSERT INTO graph_file_entities (stash_root, file_path, entity_order, entity)
-     VALUES (?, ?, ?, ?)`);
+        schema_version = excluded.schema_version,
+        generated_at = excluded.generated_at,
+        considered_files = excluded.considered_files,
+        extracted_files = excluded.extracted_files,
+        entity_count = excluded.entity_count,
+        relation_count = excluded.relation_count,
+        extraction_coverage = excluded.extraction_coverage,
+        density = excluded.density,
+        extractor_id = excluded.extractor_id,
+        extraction_run_id = excluded.extraction_run_id,
+        model = excluded.model,
+        prompt_version = excluded.prompt_version,
+        batch_size = excluded.batch_size,
+        cache_hits = excluded.cache_hits,
+        cache_misses = excluded.cache_misses,
+        truncation_count = excluded.truncation_count,
+        failure_count = excluded.failure_count`);
+    const selectExisting = db.prepare("SELECT entry_id, file_path, body_hash FROM graph_files WHERE stash_root = ?");
+    const deleteFile = db.prepare("DELETE FROM graph_files WHERE entry_id = ?");
+    const deleteEntities = db.prepare("DELETE FROM graph_file_entities WHERE entry_id = ?");
+    const deleteRelations = db.prepare("DELETE FROM graph_file_relations WHERE entry_id = ?");
+    const insertFile = db.prepare(`INSERT INTO graph_files (
+       entry_id, stash_root, file_path, file_order, file_type, body_hash, confidence, status, reason, extraction_run_id
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const updateFileMeta = db.prepare(`UPDATE graph_files
+       SET file_order = ?, file_type = ?, confidence = ?, status = ?, reason = ?, extraction_run_id = ?
+        WHERE entry_id = ?`);
+    const insertEntity = db.prepare(`INSERT INTO graph_file_entities (entry_id, entity_order, stash_root, entity_norm, entity)
+     VALUES (?, ?, ?, ?, ?)`);
     const insertRelation = db.prepare(`INSERT INTO graph_file_relations (
-       stash_root,
-       file_path,
-       relation_order,
-       from_entity,
-       to_entity,
-       relation_type,
-       confidence
-     ) VALUES (?, ?, ?, ?, ?, ?, ?)`);
+       entry_id, relation_order, from_entity_norm, from_entity, to_entity_norm, to_entity, relation_type, confidence
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
     const quality = graph.quality;
+    const telemetry = graph.telemetry;
     db.transaction(() => {
-        upsertMeta.run(graph.stashRoot, graph.schemaVersion, graph.generatedAt, quality?.consideredFiles ?? graph.files.length, quality?.extractedFiles ?? graph.files.length, quality?.entityCount ?? graph.entities?.length ?? 0, quality?.relationCount ?? graph.relations?.length ?? 0, quality?.extractionCoverage ?? 0, quality?.density ?? 0);
-        deleteRelations.run(graph.stashRoot);
-        deleteEntities.run(graph.stashRoot);
-        deleteFiles.run(graph.stashRoot);
+        upsertMeta.run(graph.stashRoot, graph.schemaVersion, graph.generatedAt, quality?.consideredFiles ?? graph.files.length, quality?.extractedFiles ?? graph.files.length, quality?.entityCount ?? graph.entities?.length ?? 0, quality?.relationCount ?? graph.relations?.length ?? 0, quality?.extractionCoverage ?? 0, quality?.density ?? 0, telemetry?.extractorId ?? null, telemetry?.extractionRunId ?? null, telemetry?.model ?? null, telemetry?.promptVersion ?? null, telemetry?.batchSize ?? null, telemetry?.cacheHits ?? 0, telemetry?.cacheMisses ?? 0, telemetry?.truncationCount ?? 0, telemetry?.failureCount ?? 0);
+        // Build a snapshot of existing rows for incremental compare.
+        const existingRows = selectExisting.all(graph.stashRoot);
+        const existingByPath = new Map();
+        for (const row of existingRows)
+            existingByPath.set(row.file_path, row);
+        let orphanCount = 0;
+        const presentEntryIds = new Set();
         for (const [fileOrder, node] of graph.files.entries()) {
-            insertFile.run(graph.stashRoot, node.path, fileOrder, node.type, node.bodyHash ?? null, node.confidence ?? null);
+            // body_hash is NOT NULL in schema v2; default to a sentinel for inputs
+            // (test fixtures, legacy imports) that don't supply one. The sentinel
+            // never equals a real hash so subsequent staleness checks always
+            // re-extract — correct behaviour for "unknown" bodies.
+            const bodyHash = node.bodyHash && node.bodyHash.length > 0 ? node.bodyHash : "";
+            const entryId = resolveEntryIdForPath(db, graph.stashRoot, node.path);
+            if (entryId == null) {
+                orphanCount += 1;
+                continue;
+            }
+            presentEntryIds.add(entryId);
+            const existing = existingByPath.get(node.path);
+            if (existing && existing.entry_id === entryId && existing.body_hash === bodyHash) {
+                // Body unchanged — only fix up file_order/confidence in case they drifted.
+                updateFileMeta.run(fileOrder, node.type, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null, entryId);
+                continue;
+            }
+            if (existing) {
+                // Stale row (different body_hash, or entry_id moved to a different
+                // path under the same file_path). Wipe child rows; CASCADE would do
+                // it but explicit DELETE keeps the order deterministic.
+                deleteEntities.run(existing.entry_id);
+                deleteRelations.run(existing.entry_id);
+                deleteFile.run(existing.entry_id);
+            }
+            insertFile.run(entryId, graph.stashRoot, node.path, fileOrder, node.type, bodyHash, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null);
             for (const [entityOrder, entity] of node.entities.entries()) {
-                insertEntity.run(graph.stashRoot, node.path, entityOrder, entity);
+                insertEntity.run(entryId, entityOrder, graph.stashRoot, normalizeEntity(entity), entity);
             }
             for (const [relationOrder, relation] of node.relations.entries()) {
-                insertRelation.run(graph.stashRoot, node.path, relationOrder, relation.from, relation.to, relation.type ?? null, relation.confidence ?? null);
+                insertRelation.run(entryId, relationOrder, normalizeEntity(relation.from), relation.from, normalizeEntity(relation.to), relation.to, relation.type ?? null, relation.confidence ?? null);
+            }
+        }
+        // Delete files present in DB but absent from the new snapshot. Child
+        // tables CASCADE on entry_id.
+        for (const row of existingRows) {
+            if (!presentEntryIds.has(row.entry_id)) {
+                deleteEntities.run(row.entry_id);
+                deleteRelations.run(row.entry_id);
+                deleteFile.run(row.entry_id);
             }
         }
+        if (orphanCount > 0) {
+            warn(`[graph] replaceStoredGraph: skipped ${orphanCount} file(s) with no resolvable entry under ${graph.stashRoot}.`);
+        }
     })();
 }
 export function deleteStoredGraph(db, stashPath) {
     db.transaction(() => {
-        db.prepare("DELETE FROM graph_file_relations WHERE stash_root = ?").run(stashPath);
-        db.prepare("DELETE FROM graph_file_entities WHERE stash_root = ?").run(stashPath);
+        // Child rows cascade via entry_id; deleting graph_files clears them.
         db.prepare("DELETE FROM graph_files WHERE stash_root = ?").run(stashPath);
         db.prepare("DELETE FROM graph_meta WHERE stash_root = ?").run(stashPath);
     })();
 }
+/**
+ * Scoped loader — only the graph_meta row for a stash. Used by callers that
+ * only need summary numbers (e.g. `akm graph summary`).
+ */
+export function loadGraphMetaOnly(stashPath, db) {
+    return loadStoredGraphMeta(stashPath, db);
+}
+/**
+ * Scoped loader — graph_files rows without entities/relations. Used for
+ * orphan detection and entity overview commands.
+ */
+export function loadGraphFilesOnly(stashPath, db) {
+    try {
+        return withReadableGraphDb(db, (readDb) => {
+            try {
+                const rows = readDb
+                    .prepare(`SELECT entry_id, file_path, file_type, body_hash, confidence, status, reason
+                FROM graph_files
+                WHERE stash_root = ?
+                ORDER BY file_order`)
+                    .all(stashPath);
+                return rows.map((row) => ({
+                    entryId: row.entry_id,
+                    path: row.file_path,
+                    type: row.file_type,
+                    bodyHash: row.body_hash,
+                    ...(typeof row.confidence === "number" ? { confidence: row.confidence } : {}),
+                    ...(row.status ? { status: row.status } : {}),
+                    ...(row.reason ? { reason: row.reason } : {}),
+                }));
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch (err) {
+        // Never mask the bun-test isolation guard as "no stored graph files".
+        rethrowIfTestIsolationError(err);
+        return [];
+    }
+}
+/**
+ * Scoped loader — entities for a single entry_id. Used by per-asset lookups.
+ */
+export function loadGraphEntitiesByEntry(db, entryId) {
+    try {
+        const rows = db
+            .prepare("SELECT entity FROM graph_file_entities WHERE entry_id = ? ORDER BY entity_order")
+            .all(entryId);
+        return rows.map((r) => r.entity);
+    }
+    catch {
+        return [];
+    }
+}
 export function loadStoredGraphMeta(stashPath, db) {
     try {
         return withReadableGraphDb(db, (readDb) => {
@@ -94,9 +249,18 @@ export function loadStoredGraphMeta(stashPath, db) {
                entity_count,
                relation_count,
                extraction_coverage,
-               density
-             FROM graph_meta
-             WHERE stash_root = ?`)
+               density,
+               extractor_id,
+               extraction_run_id,
+               model,
+               prompt_version,
+               batch_size,
+               cache_hits,
+               cache_misses,
+               truncation_count,
+               failure_count
+              FROM graph_meta
+              WHERE stash_root = ?`)
                     .get(stashPath);
                 if (!row)
                     return null;
@@ -113,6 +277,17 @@ export function loadStoredGraphMeta(stashPath, db) {
                         extractionCoverage: row.extraction_coverage,
                         density: row.density,
                     },
+                    telemetry: {
+                        ...(row.extractor_id ? { extractorId: row.extractor_id } : {}),
+                        ...(row.extraction_run_id ? { extractionRunId: row.extraction_run_id } : {}),
+                        ...(row.model ? { model: row.model } : {}),
+                        ...(row.prompt_version ? { promptVersion: row.prompt_version } : {}),
+                        ...(typeof row.batch_size === "number" ? { batchSize: row.batch_size } : {}),
+                        cacheHits: row.cache_hits,
+                        cacheMisses: row.cache_misses,
+                        truncationCount: row.truncation_count,
+                        failureCount: row.failure_count,
+                    },
                 };
             }
             catch {
@@ -120,7 +295,9 @@ export function loadStoredGraphMeta(stashPath, db) {
             }
         });
     }
-    catch {
+    catch (err) {
+        // Never mask the bun-test isolation guard as "no stored graph meta".
+        rethrowIfTestIsolationError(err);
         return null;
     }
 }
@@ -132,22 +309,29 @@ export function loadStoredGraphSnapshot(stashPath, db) {
                 return null;
             try {
                 const fileRows = readDb
-                    .prepare(`SELECT file_path, file_type, body_hash, confidence
-             FROM graph_files
-             WHERE stash_root = ?
-             ORDER BY file_order`)
+                    .prepare(`SELECT entry_id, file_path, file_type, body_hash, confidence, status, reason, extraction_run_id
+              FROM graph_files
+              WHERE stash_root = ?
+              ORDER BY file_order`)
                     .all(stashPath);
                 const entityRows = readDb
-                    .prepare(`SELECT file_path, entity
-             FROM graph_file_entities
-             WHERE stash_root = ?
-             ORDER BY file_path, entity_order`)
+                    .prepare(`SELECT gfe.entry_id AS entry_id, gf.file_path AS file_path, gfe.entity AS entity
+             FROM graph_file_entities gfe
+             JOIN graph_files gf ON gf.entry_id = gfe.entry_id
+             WHERE gf.stash_root = ?
+             ORDER BY gf.file_order, gfe.entity_order`)
                     .all(stashPath);
                 const relationRows = readDb
-                    .prepare(`SELECT file_path, from_entity, to_entity, relation_type, confidence
-             FROM graph_file_relations
-             WHERE stash_root = ?
-             ORDER BY file_path, relation_order`)
+                    .prepare(`SELECT gfr.entry_id AS entry_id,
+                    gf.file_path AS file_path,
+                    gfr.from_entity AS from_entity,
+                    gfr.to_entity AS to_entity,
+                    gfr.relation_type AS relation_type,
+                    gfr.confidence AS confidence
+             FROM graph_file_relations gfr
+             JOIN graph_files gf ON gf.entry_id = gfr.entry_id
+             WHERE gf.stash_root = ?
+             ORDER BY gf.file_order, gfr.relation_order`)
                     .all(stashPath);
                 const entitiesByPath = new Map();
                 for (const row of entityRows) {
@@ -178,6 +362,9 @@ export function loadStoredGraphSnapshot(stashPath, db) {
                     entities: entitiesByPath.get(row.file_path) ?? [],
                     relations: relationsByPath.get(row.file_path) ?? [],
                     ...(typeof row.confidence === "number" ? { confidence: row.confidence } : {}),
+                    ...(row.status ? { status: row.status } : {}),
+                    ...(row.reason ? { reason: row.reason } : {}),
+                    ...(row.extraction_run_id ? { extractionRunId: row.extraction_run_id } : {}),
                 }));
                 return {
                     stashPath: meta.stashPath,
@@ -185,6 +372,7 @@ export function loadStoredGraphSnapshot(stashPath, db) {
                     schemaVersion: meta.schemaVersion,
                     generatedAt: meta.generatedAt,
                     ...(meta.quality ? { quality: meta.quality } : {}),
+                    ...(meta.telemetry ? { telemetry: meta.telemetry } : {}),
                     files,
                     entities: uniqueSorted(files.flatMap((file) => file.entities)),
                     relations: files.flatMap((file) => file.relations),
@@ -195,7 +383,9 @@ export function loadStoredGraphSnapshot(stashPath, db) {
             }
         });
     }
-    catch {
+    catch (err) {
+        // Never mask the bun-test isolation guard as "no stored graph snapshot".
+        rethrowIfTestIsolationError(err);
         return null;
     }
 }

package/dist/indexer/graph-dedup.js

@@ -1,10 +1,6 @@
-/**
- * Pure graph deduplication utility — no LLM calls, no I/O.
- *
- * Extracted from src/llm/graph-extract.ts so it can be imported by
- * src/indexer/graph-extraction.ts without being replaced by test mocks
- * that stub the LLM layer.
- */
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 function normalizeRelationType(raw) {
     const normalized = raw?.trim().toLowerCase().replace(/\s+/g, " ") ?? "";
     if (!normalized)