akm-cli 0.7.1 → 0.7.3

package/dist/indexer/indexer.js

@@ -5,25 +5,32 @@ import { getDbPath } from "../core/paths";
 import { isVerbose, warn, warnVerbose } from "../core/warn";
 import { resolveIndexPassLLM } from "../llm/index-passes";
 import { takeWorkflowDocument } from "../workflows/document-cache";
-import { closeDatabase, deleteEntriesByDir, deleteEntriesByStashDir, getEmbeddingCount, getEntriesByDir, getEntryCount, getMeta, isVecAvailable, openDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, upsertUtilityScore, warnIfVecMissing, } from "./db";
+import { closeDatabase, deleteEntriesByDir, deleteEntriesByStashDir, deleteIndexDirStatesByStashDir, getEmbeddingCount, getEntriesByDir, getEntryCount, getIndexDirState, getMeta, isVecAvailable, openDatabase, openExistingDatabase, rebuildFts, setMeta, upsertEmbedding, upsertEntry, upsertIndexDirState, upsertUtilityScore, warnIfVecMissing, } from "./db";
 import { runGraphExtractionPass } from "./graph-extraction";
 import { runMemoryInferencePass } from "./memory-inference";
-import { generateMetadataFlat, isWorkflowSkipWarning, loadStashFile, shouldIndexStashFile, } from "./metadata";
+import { applyCuratedFrontmatter, applyWikiFrontmatter, generateMetadataFlat, isWorkflowSkipWarning, loadStashFile, shouldIndexStashFile, } from "./metadata";
 import { buildSearchText } from "./search-fields";
 import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./semantic-status";
 import { ensureUsageEventsSchema, purgeOldUsageEvents } from "./usage-events";
 import { walkStashFlat } from "./walker";
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw signal.reason instanceof Error ? signal.reason : new Error("index interrupted");
+    }
+}
 // ── Indexer ──────────────────────────────────────────────────────────────────
 export async function akmIndex(options) {
     const stashDir = options?.stashDir || resolveStashDir();
     const onProgress = options?.onProgress ?? (() => { });
+    const signal = options?.signal;
+    const enrich = options?.enrich === true;
     // Load config and resolve all stash sources
     const { loadConfig } = await import("../core/config.js");
     const config = loadConfig();
     // Ensure git stash caches are extracted before resolving stash dirs,
     // so their content directories exist on disk for the walker to discover.
     const { ensureSourceCaches, resolveSourceEntries } = await import("./search-source.js");
-    await ensureSourceCaches(config);
+    await ensureSourceCaches(config, { force: options?.full === true });
     const allSourceEntries = resolveSourceEntries(stashDir, config);
     const allSourceDirs = allSourceEntries.map((s) => s.path);
     const t0 = Date.now();
@@ -44,13 +51,11 @@ export async function akmIndex(options) {
                 sourcesCount: allSourceDirs.length,
                 semanticSearchMode: config.semanticSearchMode,
                 embeddingProvider: getEmbeddingProvider(config.embedding),
-                // Surface "llm enabled" only when at least one pass would actually
-                // run. Today that means the enrichment pass; future passes plug in
-                // via `resolveIndexPassLLM`.
-                llmEnabled: !!resolveIndexPassLLM("enrichment", config),
+                llmEnabled: enrich && !!resolveIndexPassLLM("enrichment", config),
                 vecAvailable: isVecAvailable(db),
             }),
         });
+        let hadRemovedSources = false;
         if (options?.full || !isIncremental) {
             // The delete is now merged into the insert transaction inside
             // indexEntries() so that a reader never sees an empty database between
@@ -77,31 +82,39 @@ export async function akmIndex(options) {
                 const currentSet = new Set(allSourceDirs);
                 for (const dir of prevStashDirs) {
                     if (!currentSet.has(dir)) {
+                        hadRemovedSources = true;
                         deleteEntriesByStashDir(db, dir);
+                        deleteIndexDirStatesByStashDir(db, dir);
                     }
                 }
             }
         }
-        // Memory inference pass (#201). Runs before the walk so any atomic-fact
+        throwIfAborted(signal);
+        // Memory inference pass (#201). Runs before the walk so any derived-memory
         // children that get written are picked up by the walker in this same run
         // and don't have to wait for the next `akm index`. Gated entirely by
         // `resolveIndexPassLLM("memory", config)` — when the user has no
         // `akm.llm` block or has set `index.memory.llm = false`, this is a no-op
         // and existing inferred children are left in place.
-        try {
-            const inferenceResult = await runMemoryInferencePass(config, allSourceEntries);
-            if (inferenceResult.writtenFacts > 0) {
-                onProgress({
-                    phase: "llm",
-                    message: `Memory inference wrote ${inferenceResult.writtenFacts} atomic fact${inferenceResult.writtenFacts === 1 ? "" : "s"} from ${inferenceResult.splitParents} parent memor${inferenceResult.splitParents === 1 ? "y" : "ies"}.`,
-                });
+        if (enrich) {
+            try {
+                const inferenceResult = await runMemoryInferencePass(config, allSourceEntries, signal);
+                if (inferenceResult.writtenFacts > 0) {
+                    onProgress({
+                        phase: "llm",
+                        message: `Memory inference wrote ${inferenceResult.writtenFacts} derived memor${inferenceResult.writtenFacts === 1 ? "y" : "ies"} from ${inferenceResult.splitParents} parent memor${inferenceResult.splitParents === 1 ? "y" : "ies"}.`,
+                    });
+                }
+            }
+            catch (err) {
+                warn(`Memory inference pass aborted: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        catch (err) {
-            // Defensive — runMemoryInferencePass swallows per-memory failures.
-            // A thrown error here would only come from an unexpected programming
-            // bug; surface it as a warning rather than aborting the index run.
-            warn(`Memory inference pass aborted: ${err instanceof Error ? err.message : String(err)}`);
+        else {
+            onProgress({
+                phase: "llm",
+                message: "LLM passes disabled; rerun with --enrich to enable inference and enrichment.",
+            });
         }
         // Graph extraction pass (#207). Runs after memory inference so any
         // atomic-fact children that just got written are visible to the graph
@@ -113,24 +126,27 @@ export async function akmIndex(options) {
         // `llm.features.graph_extraction` feature flag or the per-pass
         // `index.graph.llm` toggle) is off; the existing graph file is
         // preserved on disk in that case.
-        try {
-            const graphResult = await runGraphExtractionPass(config, allSourceEntries);
-            if (graphResult.written) {
-                onProgress({
-                    phase: "llm",
-                    message: `Graph extraction wrote ${graphResult.totalEntities} entit${graphResult.totalEntities === 1 ? "y" : "ies"} and ${graphResult.totalRelations} relation${graphResult.totalRelations === 1 ? "" : "s"} from ${graphResult.extracted} file${graphResult.extracted === 1 ? "" : "s"}.`,
-                });
+        if (enrich) {
+            try {
+                const graphResult = await runGraphExtractionPass(config, allSourceEntries, signal);
+                if (graphResult.written) {
+                    onProgress({
+                        phase: "llm",
+                        message: `Graph extraction wrote ${graphResult.totalEntities} entit${graphResult.totalEntities === 1 ? "y" : "ies"} and ${graphResult.totalRelations} relation${graphResult.totalRelations === 1 ? "" : "s"} from ${graphResult.extracted} file${graphResult.extracted === 1 ? "" : "s"}.`,
+                    });
+                }
+            }
+            catch (err) {
+                warn(`Graph extraction pass aborted: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        catch (err) {
-            warn(`Graph extraction pass aborted: ${err instanceof Error ? err.message : String(err)}`);
-        }
+        throwIfAborted(signal);
         const tWalkStart = Date.now();
         // Walk stash dirs and index entries.
         // doFullDelete=true merges the wipe into the same transaction as the
         // inserts so readers never see an empty database mid-rebuild.
         const doFullDelete = options?.full || !isIncremental;
-        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings } = await indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFullDelete);
+        const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings } = await indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, doFullDelete, onProgress);
         onProgress({
             phase: "scan",
             message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
@@ -150,15 +166,17 @@ export async function akmIndex(options) {
             }
         }
         const tWalkEnd = Date.now();
+        throwIfAborted(signal);
         // Enhance entries with LLM if configured
-        await enhanceDirsWithLlm(db, config, dirsNeedingLlm);
+        await enhanceDirsWithLlm(db, config, dirsNeedingLlm, signal, enrich);
         onProgress({
             phase: "llm",
-            message: resolveIndexPassLLM("enrichment", config)
+            message: enrich && resolveIndexPassLLM("enrichment", config)
                 ? `LLM enhancement reviewed ${dirsNeedingLlm.length} ${dirsNeedingLlm.length === 1 ? "directory" : "directories"}.`
                 : "LLM enhancement disabled.",
         });
         const tLlmEnd = Date.now();
+        throwIfAborted(signal);
         // Rebuild FTS after all inserts. Use incremental mode when this whole
         // index run is incremental — only entries touched by `upsertEntry`
         // since the last rebuild are re-indexed, instead of re-scanning every
@@ -200,6 +218,7 @@ export async function akmIndex(options) {
         catch {
             /* best-effort */
         }
+        throwIfAborted(signal);
         // Generate embeddings if semantic search is enabled
         const embeddingResult = await generateEmbeddingsForDb(db, config, onProgress);
         const tEmbedEnd = Date.now();
@@ -252,7 +271,7 @@ export async function akmIndex(options) {
     }
 }
 // ── Extracted helpers for indexing ────────────────────────────────────────────
-async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFullDelete = false) {
+async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, doFullDelete = false, onProgress) {
     let scannedDirs = 0;
     let skippedDirs = 0;
     let generatedCount = 0;
@@ -260,9 +279,29 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFu
     const seenPaths = new Set();
     const dirsNeedingLlm = [];
     const dirRecords = [];
+    let processedDirs = 0;
+    let priorDirsChanged = hadRemovedSources;
+    const reportScanProgress = (message) => {
+        onProgress?.({
+            phase: "scan",
+            message,
+            processed: processedDirs,
+            total: allSourceEntries.length,
+        });
+    };
+    const reportDirDecision = (kind, dirPath, currentStashDir, reason, persistedRowCount) => {
+        if (!isVerbose())
+            return;
+        const detail = reason.detail ? ` (${reason.detail})` : "";
+        const rowInfo = persistedRowCount !== undefined ? `; previous rows=${persistedRowCount}` : "";
+        reportScanProgress(`${kind === "scan" ? "Rescanning" : "Skipping"} ${path.relative(currentStashDir, dirPath) || "."} ` +
+            `from ${currentStashDir}: ${reason.kind}${detail}${rowInfo}`);
+    };
     for (const sourceAdded of allSourceEntries) {
         const currentStashDir = sourceAdded.path;
         const fileContexts = walkStashFlat(currentStashDir);
+        processedDirs++;
+        reportScanProgress(`Processed ${processedDirs}/${allSourceEntries.length} source${allSourceEntries.length === 1 ? "" : "s"}.`);
         // Wiki-root stashes: all .md files are indexed as wiki pages under wikiName
         if (sourceAdded.wikiName) {
             const wikiName = sourceAdded.wikiName;
@@ -273,13 +312,17 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFu
                 if (!shouldIndexStashFile(currentStashDir, ctx.absPath, { treatStashRootAsWikiRoot: true }))
                     continue;
                 const relNoExt = ctx.relPath.replace(/\.md$/, "");
+                const frontmatter = ctx.frontmatter() ?? {};
                 const entry = {
                     name: `${wikiName}/${relNoExt}`,
                     type: "wiki",
                     filename: ctx.fileName,
-                    description: ctx.frontmatter()?.description,
-                    source: "frontmatter",
+                    quality: "generated",
+                    confidence: 0.55,
+                    source: "filename",
                 };
+                applyCuratedFrontmatter(entry, frontmatter);
+                applyWikiFrontmatter(entry, frontmatter);
                 const dir = ctx.parentDirAbs;
                 const group = wikiDirGroups.get(dir);
                 if (group) {
@@ -292,12 +335,32 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFu
             }
             for (const [dirPath, { files, entries }] of wikiDirGroups) {
                 if (seenPaths.has(path.resolve(dirPath))) {
-                    dirRecords.push({ dirPath, currentStashDir, files, stash: null, skip: true });
+                    const reason = { kind: "duplicate-dir" };
+                    dirRecords.push({ dirPath, currentStashDir, files, stash: null, skip: true, reason });
+                    reportDirDecision("skip", dirPath, currentStashDir, reason);
                     continue;
                 }
                 seenPaths.add(path.resolve(dirPath));
+                const previousState = getDirIndexState(db, dirPath, files, builtAtMs);
+                if (isIncremental && !previousState.stale && canUseIncrementalSkip(previousState, priorDirsChanged)) {
+                    skippedDirs++;
+                    dirRecords.push({ dirPath, currentStashDir, files, stash: null, skip: true, reason: previousState.reason });
+                    reportDirDecision("skip", dirPath, currentStashDir, previousState.reason, previousState.persistedRowCount);
+                    continue;
+                }
                 scannedDirs++;
-                dirRecords.push({ dirPath, currentStashDir, files, stash: { entries }, skip: false });
+                priorDirsChanged = true;
+                const reason = isIncremental ? previousState.reason : { kind: "full-rebuild" };
+                dirRecords.push({
+                    dirPath,
+                    currentStashDir,
+                    files,
+                    stash: { entries },
+                    skip: false,
+                    reason,
+                    persistedRowCount: previousState.persistedRowCount,
+                });
+                reportDirDecision("scan", dirPath, currentStashDir, reason, previousState.persistedRowCount);
             }
             continue;
         }
@@ -311,46 +374,70 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFu
                 dirGroups.set(dir, [ctx.absPath]);
         }
         for (const [dirPath, files] of dirGroups) {
+            const indexableFiles = files.filter((file) => shouldIndexStashFile(currentStashDir, file));
             if (seenPaths.has(path.resolve(dirPath))) {
-                dirRecords.push({ dirPath, currentStashDir, files, stash: null, skip: true });
+                const reason = { kind: "duplicate-dir" };
+                dirRecords.push({ dirPath, currentStashDir, files: indexableFiles, stash: null, skip: true, reason });
+                reportDirDecision("skip", dirPath, currentStashDir, reason);
                 continue;
             }
             seenPaths.add(path.resolve(dirPath));
-            // Incremental: skip directories that haven't changed
-            if (isIncremental) {
-                const prevEntries = getEntriesByDir(db, dirPath);
-                if (prevEntries.length > 0 && !isDirStale(dirPath, files, prevEntries, builtAtMs)) {
-                    skippedDirs++;
-                    dirRecords.push({ dirPath, currentStashDir, files, stash: null, skip: true });
-                    continue;
-                }
+            if (indexableFiles.length === 0) {
+                skippedDirs++;
+                const reason = { kind: "no-indexable-files" };
+                dirRecords.push({ dirPath, currentStashDir, files: indexableFiles, stash: null, skip: true, reason });
+                reportDirDecision("skip", dirPath, currentStashDir, reason);
+                continue;
             }
-            scannedDirs++;
-            // Try loading existing .stash.json (user metadata overrides)
-            let stash = loadStashFile(dirPath);
-            if (stash) {
-                const coveredFiles = new Set(stash.entries.map((e) => (e.filename ? path.basename(e.filename) : "")).filter((e) => !!e));
-                const uncoveredFiles = files.filter((f) => !coveredFiles.has(path.basename(f)));
-                if (uncoveredFiles.length > 0) {
-                    const generated = await generateMetadataFlat(currentStashDir, uncoveredFiles);
-                    if (generated.warnings?.length)
-                        warnings.push(...generated.warnings);
-                    if (generated.entries.length > 0) {
-                        stash = { entries: [...stash.entries, ...generated.entries] };
-                        generatedCount += generated.entries.length;
-                    }
-                }
+            const cachedZeroRowState = isIncremental && getCachedZeroRowDirState(db, dirPath, indexableFiles, builtAtMs, priorDirsChanged);
+            if (cachedZeroRowState) {
+                skippedDirs++;
+                dirRecords.push({
+                    dirPath,
+                    currentStashDir,
+                    files: indexableFiles,
+                    stash: null,
+                    skip: true,
+                    reason: cachedZeroRowState.reason,
+                });
+                reportDirDecision("skip", dirPath, currentStashDir, cachedZeroRowState.reason, cachedZeroRowState.persistedRowCount);
+                continue;
             }
-            if (!stash) {
-                const generated = await generateMetadataFlat(currentStashDir, files);
-                if (generated.warnings?.length)
-                    warnings.push(...generated.warnings);
-                if (generated.entries.length > 0) {
-                    stash = { entries: generated.entries };
-                    generatedCount += generated.entries.length;
-                }
+            const generated = await generateMetadataFlat(currentStashDir, indexableFiles);
+            if (generated.warnings?.length)
+                warnings.push(...generated.warnings);
+            const legacyOverrides = loadStashFile(dirPath, { requireFilename: true });
+            const { stash, staleFiles } = buildIndexedDirCandidate(dirPath, indexableFiles, generated, legacyOverrides);
+            if (generated.entries.length > 0) {
+                generatedCount += generated.entries.length;
             }
-            dirRecords.push({ dirPath, currentStashDir, files, stash, skip: false });
+            const previousState = getDirIndexState(db, dirPath, staleFiles, builtAtMs);
+            if (isIncremental && !previousState.stale && canUseIncrementalSkip(previousState, priorDirsChanged)) {
+                skippedDirs++;
+                dirRecords.push({
+                    dirPath,
+                    currentStashDir,
+                    files: staleFiles,
+                    stash: null,
+                    skip: true,
+                    reason: previousState.reason,
+                });
+                reportDirDecision("skip", dirPath, currentStashDir, previousState.reason, previousState.persistedRowCount);
+                continue;
+            }
+            scannedDirs++;
+            priorDirsChanged = true;
+            const reason = isIncremental ? previousState.reason : { kind: "full-rebuild" };
+            dirRecords.push({
+                dirPath,
+                currentStashDir,
+                files: staleFiles,
+                stash,
+                skip: false,
+                reason,
+                persistedRowCount: previousState.persistedRowCount,
+            });
+            reportDirDecision("scan", dirPath, currentStashDir, reason, previousState.persistedRowCount);
         }
     }
     // Phase 2 (sync): write all pre-generated metadata inside a single transaction.
@@ -382,6 +469,7 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFu
             }
             db.exec("DELETE FROM entries_fts");
             db.exec("DELETE FROM utility_scores");
+            db.exec("DELETE FROM index_dir_state");
             // Detach usage_events from entries about to be deleted — null out entry_id
             // but keep entry_ref so events can be re-linked after entries are rebuilt.
             try {
@@ -392,32 +480,42 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFu
             }
             db.exec("DELETE FROM entries");
         }
-        for (const { dirPath, currentStashDir, files, stash, skip } of dirRecords) {
-            if (skip)
+        for (const { dirPath, currentStashDir, files, stash, skip, reason } of dirRecords) {
+            if (skip) {
+                if (reason?.kind === "unchanged") {
+                    const fingerprint = computeDirFingerprint(dirPath, files);
+                    upsertIndexDirState(db, {
+                        dirPath,
+                        fileSetHash: fingerprint.fileSetHash,
+                        fileMtimeMaxMs: fingerprint.fileMtimeMaxMs,
+                        reason: reason.kind,
+                    });
+                }
                 continue;
+            }
             // Delete old entries for this dir (will be re-inserted)
             deleteEntriesByDir(db, dirPath);
+            let persistedRows = 0;
+            let dedupedRows = 0;
             if (stash) {
-                // Build a lookup for matching filename-less entries to actual files
-                const fileBasenameMap = buildFileBasenameMap(files);
                 for (const entry of stash.entries) {
-                    const entryPath = entry.filename
-                        ? path.join(dirPath, entry.filename)
-                        : matchEntryToFile(entry.name, fileBasenameMap, files);
+                    const entryPath = entry.filename ? path.join(dirPath, entry.filename) : null;
                     if (!entryPath)
                         continue; // skip unresolvable entries
                     if (!shouldIndexStashFile(currentStashDir, entryPath))
                         continue;
                     // Skip if a higher-priority stash root already indexed this asset
-                    const basename = path.basename(entryPath);
-                    const identityKey = `${entry.type}\0${basename}\0${entry.description ?? ""}`;
-                    if (indexedAssetIdentities.has(identityKey))
+                    const identityKey = `${entry.type}\0${entry.name}`;
+                    if (indexedAssetIdentities.has(identityKey)) {
+                        dedupedRows++;
                         continue;
+                    }
                     indexedAssetIdentities.add(identityKey);
                     const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
                     const searchText = buildSearchText(entry);
                     const entryWithSize = attachFileSize(entry, entryPath);
                     const entryId = upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entryWithSize, searchText);
+                    persistedRows++;
                     if (entry.type === "workflow") {
                         const doc = takeWorkflowDocument(entry);
                         if (doc) {
@@ -430,12 +528,121 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, doFu
                     dirsNeedingLlm.push({ dirPath, files, currentStashDir, stash });
                 }
             }
+            const fingerprint = computeDirFingerprint(dirPath, files);
+            const persistedReason = persistedRows === 0
+                ? inferZeroRowReason(stash, reason, warnings, dirPath, dedupedRows)
+                : reason?.kind === "full-rebuild"
+                    ? "full-rebuild"
+                    : (reason?.kind ?? "updated");
+            upsertIndexDirState(db, {
+                dirPath,
+                fileSetHash: fingerprint.fileSetHash,
+                fileMtimeMaxMs: fingerprint.fileMtimeMaxMs,
+                reason: persistedReason,
+            });
+            if (persistedRows === 0) {
+                warnVerbose(`[index] zero-row ${dirPath}: ${persistedReason}`);
+            }
         }
     });
     insertTransaction();
     return { scannedDirs, skippedDirs, generatedCount, warnings, dirsNeedingLlm };
 }
-async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
+function getDirIndexState(db, dirPath, files, builtAtMs) {
+    const prevEntries = getEntriesByDir(db, dirPath);
+    const fingerprint = computeDirFingerprint(dirPath, files);
+    if (prevEntries.length > 0) {
+        const staleReason = getDirStaleReason(dirPath, files, prevEntries, builtAtMs);
+        if (!staleReason) {
+            return { stale: false, reason: { kind: "unchanged" }, persistedRowCount: prevEntries.length };
+        }
+        return { stale: true, reason: staleReason, persistedRowCount: prevEntries.length };
+    }
+    const cachedState = getIndexDirState(db, dirPath);
+    if (cachedState &&
+        cachedState.fileSetHash === fingerprint.fileSetHash &&
+        cachedState.fileMtimeMaxMs === fingerprint.fileMtimeMaxMs) {
+        return {
+            stale: false,
+            reason: { kind: "cached-zero-row-state", detail: cachedState.reason },
+            persistedRowCount: 0,
+        };
+    }
+    return {
+        stale: true,
+        reason: { kind: "no-previous-rows", detail: cachedState ? `cached=${cachedState.reason}` : undefined },
+        persistedRowCount: 0,
+    };
+}
+function getCachedZeroRowDirState(db, dirPath, files, builtAtMs, priorDirsChanged) {
+    const state = getDirIndexState(db, dirPath, files, builtAtMs);
+    if (state.stale || state.reason.kind !== "cached-zero-row-state")
+        return undefined;
+    if (!canUseIncrementalSkip(state, priorDirsChanged))
+        return undefined;
+    return state;
+}
+function canUseIncrementalSkip(state, priorDirsChanged) {
+    return !(priorDirsChanged &&
+        state.reason.kind === "cached-zero-row-state" &&
+        state.reason.detail === "deduped-zero-row");
+}
+function computeDirFingerprint(_dirPath, files) {
+    const normalizedFiles = [...new Set(files.map((file) => path.basename(file)))].sort();
+    let fileMtimeMaxMs = 0;
+    for (const file of files) {
+        try {
+            fileMtimeMaxMs = Math.max(fileMtimeMaxMs, fs.statSync(file).mtimeMs);
+        }
+        catch {
+            fileMtimeMaxMs = Number.POSITIVE_INFINITY;
+            break;
+        }
+    }
+    return {
+        fileSetHash: normalizedFiles.join("\0"),
+        fileMtimeMaxMs,
+    };
+}
+function getDirStaleReason(_dirPath, currentFiles, previousEntries, builtAtMs) {
+    const prevFileNames = new Set(previousEntries
+        .map((ie) => {
+        const fromPath = path.basename(ie.filePath);
+        return fromPath || ie.entry.filename;
+    })
+        .filter((e) => !!e));
+    const currFileNames = new Set(currentFiles.map((f) => path.basename(f)));
+    if (prevFileNames.size !== currFileNames.size) {
+        return { kind: "file-set-changed", detail: `${prevFileNames.size} -> ${currFileNames.size} files` };
+    }
+    for (const name of currFileNames) {
+        if (!prevFileNames.has(name))
+            return { kind: "file-set-changed", detail: name };
+    }
+    for (const file of currentFiles) {
+        try {
+            if (fs.statSync(file).mtimeMs > builtAtMs)
+                return { kind: "mtime-changed", detail: path.basename(file) };
+        }
+        catch {
+            return { kind: "missing-file", detail: path.basename(file) };
+        }
+    }
+    return undefined;
+}
+function inferZeroRowReason(stash, priorReason, warnings, dirPath, dedupedRows) {
+    if (dedupedRows > 0)
+        return "deduped-zero-row";
+    const workflowNoise = warnings.some((warning) => warning.startsWith("Skipped workflow ") && warning.includes(dirPath));
+    if (workflowNoise)
+        return "workflow-noise";
+    if (!stash || stash.entries.length === 0)
+        return "empty-generated-set";
+    return `zero-row:${priorReason?.kind ?? "unknown"}`;
+}
+async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, signal, enrich = false) {
+    if (!enrich)
+        return;
     // Resolve per-pass LLM config via the unified shim. Returns undefined when
     // either no `akm.llm` is configured or the user opted this pass out via
     // `index.enrichment.llm = false`. (#208)
@@ -447,12 +654,13 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
     // and leaving the user wondering why nothing got enhanced.
     const summary = { attempted: 0, succeeded: 0, failureSamples: [] };
     for (const { dirPath, files, currentStashDir, stash: originalStash } of dirsNeedingLlm) {
+        throwIfAborted(signal);
         // Only enhance generated entries; user-provided overrides should not be overwritten
         const generatedEntries = originalStash.entries.filter((e) => e.quality === "generated");
         if (generatedEntries.length === 0)
             continue;
         const generatedStash = { entries: generatedEntries };
-        const enhanced = await enhanceStashWithLlm(llmConfig, generatedStash, files, summary);
+        const enhanced = await enhanceStashWithLlm(llmConfig, generatedStash, files, summary, signal);
         // Re-upsert the enhanced entries in a single transaction so a crash
         // cannot leave half the entries updated and the rest stale.
         db.transaction(() => {
@@ -475,7 +683,8 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm) {
         warn(`LLM enhancement failed for ${failed}/${summary.attempted} entries — they were left un-enhanced.${sample}`);
     }
 }
-async function generateEmbeddingsForDb(db, config, onProgress) {
+async function generateEmbeddingsForDb(db, config, onProgress, signal) {
+    throwIfAborted(signal);
     if (config.semanticSearchMode === "off") {
         onProgress({ phase: "embeddings", message: "Semantic search disabled; skipping embeddings." });
         return { success: false, reason: "index-missing", message: "Semantic search is disabled." };
@@ -504,6 +713,7 @@ async function generateEmbeddingsForDb(db, config, onProgress) {
     try {
         const { embedBatch } = await import("../llm/embedder.js");
         const { estimateTokenCount } = await import("../llm/embedders/remote.js");
+        throwIfAborted(signal);
         const allEntries = getAllEntriesForEmbedding(db);
         if (allEntries.length === 0) {
             onProgress({ phase: "embeddings", message: "Embeddings already up to date." });
@@ -528,7 +738,8 @@ async function generateEmbeddingsForDb(db, config, onProgress) {
                 warnVerbose(`[embed] ${ref} (${chars} chars, est. ${tokens} tokens) → batch ${batchNum}/${totalBatches}`);
             }
         }
-        const embeddings = await embedBatch(texts, config.embedding);
+        const embeddings = await embedBatch(texts, config.embedding, signal);
+        throwIfAborted(signal);
         // Wrap all embedding upserts in a single transaction so partial
         // state is rolled back on failure rather than leaving the table half-filled.
         db.transaction(() => {
@@ -668,41 +879,31 @@ function verifyIndexState(db, config, totalEntries, embeddingResult) {
         vecAvailable,
     };
 }
-function isDirStale(dirPath, currentFiles, previousEntries, builtAtMs) {
-    // Check if file set changed (additions or deletions)
-    const prevFileNames = new Set(previousEntries.map((ie) => ie.entry.filename).filter((e) => !!e));
-    const currFileNames = new Set(currentFiles.map((f) => path.basename(f)));
-    if (prevFileNames.size !== currFileNames.size)
-        return true;
-    for (const name of currFileNames) {
-        if (!prevFileNames.has(name))
-            return true;
-    }
-    // Check modification times of current files
-    for (const file of currentFiles) {
-        try {
-            if (fs.statSync(file).mtimeMs > builtAtMs)
-                return true;
-        }
-        catch {
-            return true;
-        }
-    }
-    // Check .stash.json modification time
-    const stashPath = path.join(dirPath, ".stash.json");
-    try {
-        if (fs.statSync(stashPath).mtimeMs > builtAtMs)
-            return true;
-    }
-    catch {
-        // file doesn't exist, not stale
+function buildIndexedDirCandidate(dirPath, indexableFiles, generated, legacyOverrides) {
+    const mergedEntries = legacyOverrides
+        ? generated.entries.map((entry) => mergeLegacyEntry(entry, legacyOverrides.entries))
+        : generated.entries;
+    const stash = mergedEntries.length > 0 ? { entries: mergedEntries } : legacyOverrides;
+    const staleFiles = stash ? resolveIndexedFiles(dirPath, indexableFiles, stash) : indexableFiles;
+    return { stash, staleFiles };
+}
+function resolveIndexedFiles(dirPath, files, stash) {
+    const fileBasenameMap = buildFileBasenameMap(files);
+    const resolved = new Set();
+    for (const entry of stash.entries) {
+        const entryPath = entry.filename
+            ? path.join(dirPath, entry.filename)
+            : matchEntryToFile(entry.name, fileBasenameMap, files);
+        if (entryPath)
+            resolved.add(entryPath);
     }
-    return false;
+    return resolved.size > 0 ? [...resolved] : files;
 }
-async function enhanceStashWithLlm(llmConfig, stash, files, summary) {
+async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal) {
     const { enhanceMetadata } = await import("../llm/metadata-enhance");
     const enhanced = [];
     for (const entry of stash.entries) {
+        throwIfAborted(signal);
         summary.attempted++;
         try {
             const entryFile = entry.filename
@@ -717,7 +918,7 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary) {
                     /* ignore unreadable files */
                 }
             }
-            const improvements = await enhanceMetadata(llmConfig, entry, fileContent);
+            const improvements = await enhanceMetadata(llmConfig, entry, fileContent, signal);
             const updated = { ...entry };
             if (improvements.description)
                 updated.description = improvements.description;
@@ -760,9 +961,9 @@ export function buildFileBasenameMap(files) {
  *   1. Exact basename match: entry.name === filename without extension
  *   2. Last path segment match: for entries with names like "dir/sub-entry",
  *      try matching the last segment
- *   3. Fallback: first file in the directory, or null if no files are available
+ *   3. No implicit file fallback: ambiguous legacy entries are skipped
  */
-export function matchEntryToFile(entryName, fileMap, files) {
+export function matchEntryToFile(entryName, fileMap, _files) {
     // Exact match on entry name
     const exact = fileMap.get(entryName);
     if (exact)
@@ -774,8 +975,20 @@ export function matchEntryToFile(entryName, fileMap, files) {
         if (segmentMatch)
             return segmentMatch;
     }
-    // Fallback to first file, or null if no files are available
-    return files[0] || null;
+    return null;
+}
+function mergeLegacyEntry(entry, legacyEntries) {
+    const legacy = legacyEntries.find((candidate) => candidate.filename === entry.filename);
+    if (!legacy)
+        return entry;
+    return {
+        ...entry,
+        ...legacy,
+        filename: entry.filename,
+        source: legacy.source ?? entry.source,
+        quality: legacy.quality ?? entry.quality,
+        confidence: legacy.confidence ?? entry.confidence,
+    };
 }
 /**
  * Look up a single asset by ref. Spec §6.2 — `akm show` queries this and
@@ -803,7 +1016,7 @@ export async function lookup(ref) {
     if (sources.length === 0)
         return null;
     const dbPath = getDbPath();
-    const db = openDatabase(dbPath);
+    const db = openExistingDatabase(dbPath);
     try {
         // entry_key shape: `${stashDir}:${type}:${name}`. Suffix-match on
         // `:type:name` so we can scope by source dir as a prefix when origin is