akm-cli 0.9.0-beta.6 → 0.9.0-rc.0

package/dist/indexer/db/entry-mapper.js

@@ -0,0 +1,41 @@
+// 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/.
+/**
+ * Shared `entries`-row projection + mapper, extracted from indexer/db/db.ts.
+ *
+ * Centralizes the one canonical `entries` SELECT column list and the
+ * JSON-parse-guarded row → {@link DbIndexedEntry} mapping that several queries
+ * used to reimplement. Corrupt `entry_json` rows are skipped (warn once) rather
+ * than crashing the caller.
+ */
+import { warn } from "../../core/warn.js";
+/**
+ * Canonical column list for reading a full indexed entry from the `entries`
+ * table, in the order {@link rowToIndexedEntry} expects.
+ */
+export const ENTRY_COLUMNS = "id, entry_key, dir_path, file_path, stash_dir, entry_json, search_text";
+/**
+ * Map one raw `entries` row to a {@link DbIndexedEntry}, parsing `entry_json`.
+ * Returns `null` (and warns, tagged with `context`) when the JSON is corrupt so
+ * callers can skip the row instead of crashing.
+ */
+export function rowToIndexedEntry(row, context) {
+    let entry;
+    try {
+        entry = JSON.parse(row.entry_json);
+    }
+    catch {
+        warn(`[db] ${context}: skipping entry id=${row.id} — corrupt entry_json`);
+        return null;
+    }
+    return {
+        id: row.id,
+        entryKey: row.entry_key,
+        dirPath: row.dir_path,
+        filePath: row.file_path,
+        stashDir: row.stash_dir,
+        entry,
+        searchText: row.search_text,
+    };
+}

package/dist/indexer/db/graph-db.js

@@ -4,7 +4,6 @@
 import fs from "node:fs";
 import { rethrowIfTestIsolationError } from "../../core/errors.js";
 import { getDbPath } from "../../core/paths.js";
-import { warn } from "../../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "./db.js";
 function withReadableGraphDb(db, fn) {
     if (db)
@@ -26,38 +25,16 @@ function uniqueSorted(values) {
 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.
+ * #624-P1: keyed on (stash_root, file_path, body_hash) — NOT entries.id. Graph
+ * rows are self-keyed by path, so they survive an entries delete + reinsert
+ * (a reindex) when body_hash is unchanged. Unchanged files (matching body_hash)
+ * only have their file-meta refreshed; files whose body_hash changed have their
+ * old row + child rows deleted and the new content inserted; files in DB but
+ * absent from the new snapshot are deleted. There is no entry_id resolution and
+ * no orphan-skip — a graph file no longer needs a matching entries row.
  */
 export function replaceStoredGraph(db, graph) {
     const upsertMeta = db.prepare(`INSERT INTO graph_meta (
@@ -98,87 +75,146 @@ export function replaceStoredGraph(db, graph) {
         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 selectExisting = db.prepare("SELECT file_path, body_hash, file_order FROM graph_files WHERE stash_root = ?");
+    const deleteFile = db.prepare("DELETE FROM graph_files WHERE stash_root = ? AND file_path = ? AND body_hash = ?");
+    const deleteEntities = db.prepare("DELETE FROM graph_file_entities WHERE stash_root = ? AND file_path = ? AND body_hash = ?");
+    const deleteRelations = db.prepare("DELETE FROM graph_file_relations WHERE stash_root = ? AND file_path = ? AND body_hash = ?");
     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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+       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 (?, ?, ?, ?, ?)`);
+        WHERE stash_root = ? AND file_path = ? AND body_hash = ?`);
+    const insertEntity = db.prepare(`INSERT INTO graph_file_entities (stash_root, file_path, body_hash, entity_order, entity_norm, entity)
+     VALUES (?, ?, ?, ?, ?, ?)`);
     const insertRelation = db.prepare(`INSERT INTO graph_file_relations (
-       entry_id, relation_order, from_entity_norm, from_entity, to_entity_norm, to_entity, relation_type, confidence
-     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+       stash_root, file_path, body_hash, 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, 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.
+        // Build a snapshot of existing rows for incremental compare. The unique
+        // index idx_graph_files_path guarantees at most one row per file_path.
         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();
+        const presentPaths = new Set();
         for (const [fileOrder, node] of graph.files.entries()) {
-            // 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.
+            // body_hash is part of the PK; 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. Distinct files in one stash
+            // are still keyed apart by file_path, so the empty sentinel is safe.
             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);
+            presentPaths.add(node.path);
             const existing = existingByPath.get(node.path);
-            if (existing && existing.entry_id === entryId && existing.body_hash === bodyHash) {
+            if (existing && 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);
+                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, graph.stashRoot, node.path, bodyHash);
                 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);
+                // Stale row (different body_hash for this path). Delete the old row by
+                // its OLD body_hash; child rows cascade, but explicit DELETE keeps the
+                // order deterministic and is safe regardless of the FK pragma.
+                deleteEntities.run(graph.stashRoot, existing.file_path, existing.body_hash);
+                deleteRelations.run(graph.stashRoot, existing.file_path, existing.body_hash);
+                deleteFile.run(graph.stashRoot, existing.file_path, existing.body_hash);
             }
-            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);
+            insertFile.run(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(entryId, entityOrder, graph.stashRoot, normalizeEntity(entity), entity);
+                insertEntity.run(graph.stashRoot, node.path, bodyHash, entityOrder, normalizeEntity(entity), entity);
             }
             for (const [relationOrder, relation] of node.relations.entries()) {
-                insertRelation.run(entryId, relationOrder, normalizeEntity(relation.from), relation.from, normalizeEntity(relation.to), relation.to, relation.type ?? null, relation.confidence ?? null);
+                insertRelation.run(graph.stashRoot, node.path, bodyHash, 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.
+        // tables CASCADE on the composite key; explicit DELETE keeps it determinstic.
         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 (!presentPaths.has(row.file_path)) {
+                deleteEntities.run(graph.stashRoot, row.file_path, row.body_hash);
+                deleteRelations.run(graph.stashRoot, row.file_path, row.body_hash);
+                deleteFile.run(graph.stashRoot, row.file_path, row.body_hash);
             }
         }
-        if (orphanCount > 0) {
-            warn(`[graph] replaceStoredGraph: skipped ${orphanCount} file(s) with no resolvable entry under ${graph.stashRoot}.`);
-        }
     })();
 }
 export function deleteStoredGraph(db, stashPath) {
     db.transaction(() => {
-        // Child rows cascade via entry_id; deleting graph_files clears them.
+        // Child rows cascade via the composite (stash_root, file_path, body_hash)
+        // FK; deleting graph_files clears them. This is the explicit full-clear
+        // path for a stash (entries-delete no longer wipes graph data — see #624-P1).
         db.prepare("DELETE FROM graph_files WHERE stash_root = ?").run(stashPath);
         db.prepare("DELETE FROM graph_meta WHERE stash_root = ?").run(stashPath);
     })();
 }
+/**
+ * #624-P1 — does any graph data exist for a file_path under a stash root?
+ * Consumed by show/curate flows (P3) but defined here so the schema and its
+ * accessors land together.
+ */
+export function hasGraphData(db, stashRoot, filePath) {
+    try {
+        const row = db
+            .prepare("SELECT 1 AS present FROM graph_files WHERE stash_root = ? AND file_path = ? LIMIT 1")
+            .get(stashRoot, filePath);
+        return row !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * #624-P3 — enqueue a file for lazy graph extraction. Idempotent on the
+ * (stash_root, file_path) PK: a second enqueue refreshes body_hash + queued_at
+ * and keeps the HIGHER priority. Non-blocking, no LLM call — the queued row is
+ * drained later by the graph-extraction pass. Tolerant of a missing table /
+ * db error (best-effort), but never masks the bun-test isolation guard.
+ */
+export function enqueueGraphExtraction(db, stashRoot, filePath, bodyHash, priority = 0) {
+    try {
+        db.prepare(`INSERT INTO graph_extraction_queue (stash_root, file_path, body_hash, priority)
+         VALUES (?, ?, ?, ?)
+       ON CONFLICT(stash_root, file_path) DO UPDATE SET
+         body_hash = excluded.body_hash,
+         priority  = MAX(graph_extraction_queue.priority, excluded.priority),
+         queued_at = datetime('now')`).run(stashRoot, filePath, bodyHash, priority);
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+    }
+}
+/**
+ * #624-P3 — drain up to `limit` queued files for a stash, highest-priority
+ * first (then oldest queued_at). The returned rows are DELETED from the queue
+ * in the SAME transaction (SELECT-then-DELETE-by-PK), so a drain is exactly
+ * once. Tolerant of a missing table / db error (returns []), but never masks
+ * the bun-test isolation guard.
+ */
+export function drainExtractionQueue(db, stashRoot, limit) {
+    try {
+        return db.transaction(() => {
+            const rows = db
+                .prepare(`SELECT file_path, body_hash, priority
+             FROM graph_extraction_queue
+             WHERE stash_root = ?
+             ORDER BY priority DESC, queued_at ASC
+             LIMIT ?`)
+                .all(stashRoot, limit);
+            const del = db.prepare("DELETE FROM graph_extraction_queue WHERE stash_root = ? AND file_path = ?");
+            for (const row of rows)
+                del.run(stashRoot, row.file_path);
+            return rows.map((row) => ({ filePath: row.file_path, bodyHash: row.body_hash, priority: row.priority }));
+        })();
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return [];
+    }
+}
 /**
  * Scoped loader — only the graph_meta row for a stash. Used by callers that
  * only need summary numbers (e.g. `akm graph summary`).
@@ -195,13 +231,12 @@ export function loadGraphFilesOnly(stashPath, db) {
         return withReadableGraphDb(db, (readDb) => {
             try {
                 const rows = readDb
-                    .prepare(`SELECT entry_id, file_path, file_type, body_hash, confidence, status, reason
+                    .prepare(`SELECT 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,
@@ -222,13 +257,16 @@ export function loadGraphFilesOnly(stashPath, db) {
     }
 }
 /**
- * Scoped loader — entities for a single entry_id. Used by per-asset lookups.
+ * Scoped loader — entities for a single file, keyed on the #624-P1 composite
+ * (stash_root, file_path, body_hash). Used by per-asset show/curate lookups.
  */
-export function loadGraphEntitiesByEntry(db, entryId) {
+export function loadGraphEntitiesByPath(db, stashRoot, filePath, bodyHash) {
     try {
         const rows = db
-            .prepare("SELECT entity FROM graph_file_entities WHERE entry_id = ? ORDER BY entity_order")
-            .all(entryId);
+            .prepare(`SELECT entity FROM graph_file_entities
+          WHERE stash_root = ? AND file_path = ? AND body_hash = ?
+          ORDER BY entity_order`)
+            .all(stashRoot, filePath, bodyHash);
         return rows.map((r) => r.entity);
     }
     catch {
@@ -314,27 +352,32 @@ export function loadStoredGraphSnapshot(stashPath, db) {
                 return null;
             try {
                 const fileRows = readDb
-                    .prepare(`SELECT entry_id, file_path, file_type, body_hash, confidence, status, reason, extraction_run_id
+                    .prepare(`SELECT 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 gfe.entry_id AS entry_id, gf.file_path AS file_path, gfe.entity AS entity
+                    .prepare(`SELECT 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
+             JOIN graph_files gf
+               ON gf.stash_root = gfe.stash_root
+              AND gf.file_path = gfe.file_path
+              AND gf.body_hash = gfe.body_hash
              WHERE gf.stash_root = ?
              ORDER BY gf.file_order, gfe.entity_order`)
                     .all(stashPath);
                 const relationRows = readDb
-                    .prepare(`SELECT gfr.entry_id AS entry_id,
-                    gf.file_path AS file_path,
+                    .prepare(`SELECT 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
+             JOIN graph_files gf
+               ON gf.stash_root = gfr.stash_root
+              AND gf.file_path = gfr.file_path
+              AND gf.body_hash = gfr.body_hash
              WHERE gf.stash_root = ?
              ORDER BY gf.file_order, gfr.relation_order`)
                     .all(stashPath);

package/dist/indexer/db/llm-cache.js

@@ -26,8 +26,8 @@ import { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } from "./db.js"
  *                          the wrapper skips its internal hashing — callers that
  *                          already hashed the body (e.g. to reuse it elsewhere)
  *                          should pass this to avoid the redundant work.
- * @param cacheVariant  - Namespace token for the cache row (e.g. staleness-detect
- *                        sets one so its rows do not collide with memory-inference).
+ * @param cacheVariant  - Namespace token for the cache row so different passes'
+ *                        rows do not collide (e.g. memory-inference vs graph).
  * @param hooks         - Optional event sink for telemetry (see {@link WithLlmCacheHooks}).
  */
 export async function withLlmCache(db, cacheKey, body, reEnrich, llmFn, validate, precomputedHash, cacheVariant = "", hooks) {