akm-cli 0.9.0-rc.1 → 0.9.0-rc.13

package/dist/indexer/indexer.js

@@ -3,42 +3,64 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { SCRIPT_EXTENSIONS } from "../core/asset/asset-spec.js";
-import { isHttpUrl, resolveStashDir, toErrorMessage } from "../core/common.js";
+import { detectAdapterId } from "../core/adapter/detect-adapter.js";
+import { adapterForId } from "../core/adapter/registry.js";
+import { isHttpUrl, toErrorMessage } from "../core/common.js";
 import { concurrentMap } from "../core/concurrent.js";
 import { getDbPath } from "../core/paths.js";
+import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
+import { withStateDb } from "../core/state-db.js";
 import { isVerbose, warn, warnVerbose } from "../core/warn.js";
 import { resolveIndexPassLLM } from "../llm/index-passes.js";
+import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
+import { closeDatabase, openExistingDatabase, openIndexDatabase } from "../storage/repositories/index-connection.js";
+import { deleteEntriesByDirAndStash, deleteEntriesByDirExceptKeys, deleteEntriesByIds, deleteEntriesByStashDir, deleteUsageEventsByEntryIds, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedDirPathsByStashDir, getIndexedStashDirsByDir, relinkUsageEvents, upsertEntry, upsertWorkflowDocument, } from "../storage/repositories/index-entries-repository.js";
+import { rebuildFts } from "../storage/repositories/index-fts-repository.js";
+import { clearStaleCacheEntries } from "../storage/repositories/index-llm-cache-repository.js";
+import { deleteIndexDirState, deleteIndexDirStatesByStashDir, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
+import { upsertUtilityScore } from "../storage/repositories/index-utility-repository.js";
+import { getAllEntriesForEmbedding, getEmbeddingCount, isVecAvailable, purgeEmbeddings, setVecFastPathReady, upsertEmbedding, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
 import { takeWorkflowDocument } from "../workflows/runtime/document-cache.js";
-import { clearStaleCacheEntries, closeDatabase, deleteEntriesByDir, deleteEntriesByIds, deleteEntriesByStashDir, deleteIndexDirStatesByStashDir, getAllEntriesForEmbedding, getEmbeddableEntryCount, getEmbeddingCount, getEntryCount, getMeta, isVecAvailable, openExistingDatabase, openIndexDatabase, purgeEmbeddings, rebuildFts, relinkUsageEvents, setMeta, upsertEmbedding, upsertEntry, upsertIndexDirState, upsertUtilityScore, upsertWorkflowDocument, warnIfVecMissing, } from "./db/db.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
 import { withIndexWriterLease } from "./index-writer-lock.js";
+import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { canUseIncrementalSkip, computeDirFingerprint, getCachedZeroRowDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
-import { applyCuratedFrontmatter, applyWikiFrontmatter, generateMetadataFlat, isEnrichmentComplete, isWorkflowSkipWarning, loadStashFile, shouldIndexStashFile, } from "./passes/metadata.js";
+import { isEnrichmentComplete, isWorkflowSkipWarning } from "./passes/metadata.js";
+import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildSearchText } from "./search/search-fields.js";
 import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./search/semantic-status.js";
-import { ensureUsageEventsSchema, purgeOldUsageEvents } from "./usage/usage-events.js";
-import { walkStashFlat } from "./walk/walker.js";
+import { purgeOldUsageEvents } from "./usage/usage-events.js";
+import { walkStashFlatWithStatus } from "./walk/walker.js";
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw signal.reason instanceof Error ? signal.reason : new Error("index interrupted");
     }
 }
-function getDefaultLlmConcurrency(llmConfig) {
+export function getDefaultLlmConcurrency(llmConfig) {
     if (typeof llmConfig?.concurrency === "number")
         return llmConfig.concurrency;
     if (!llmConfig?.endpoint)
         return 1;
     try {
         const url = new URL(llmConfig.endpoint);
-        const host = url.hostname.toLowerCase();
+        // URL.hostname keeps IPv6 brackets ("[::1]") — strip them so the loopback
+        // comparison actually matches.
+        const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
         if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host.endsWith(".localhost"))
             return 1;
     }
     catch {
         return 1;
     }
-    return 4;
+    // Remote endpoints default to a modest 2-wide pool (owner ruling 2026-07-21):
+    // enough to overlap request latency without hammering rate-limited APIs.
+    // Local model servers stay at 1 (single loaded model; parallel requests
+    // trigger reload thrash). The explicit-override branch above only fires for
+    // callers that put `concurrency` on the connection themselves —
+    // `engines.<name>.concurrency` is a valid schema field but `resolveLlmEngineUse`
+    // does NOT copy it into the resolved connection, so on the enrichment path the
+    // auto-derived 1/2 is what runs (see docs/architecture/internals/indexing.md).
+    return 2;
 }
 // ── Phase functions ──────────────────────────────────────────────────────────
 /**
@@ -69,9 +91,7 @@ async function runSourceCachePhase(ctx) {
             for (const dir of prevStashDirs) {
                 if (!currentSet.has(dir)) {
                     ctx.hadRemovedSources = true;
-                    deleteEntriesByStashDir(db, dir);
-                    deleteIndexDirStatesByStashDir(db, dir);
-                    deleteStoredGraph(db, dir);
+                    ctx.removedSourceDirs.push(dir);
                 }
             }
         }
@@ -80,6 +100,15 @@ async function runSourceCachePhase(ctx) {
     // further to do here. The flag is exposed on ctx for runWalkPhase().
     void config;
 }
+function applyRemovedSources(ctx) {
+    if (!ctx.scanComplete)
+        return;
+    for (const dir of ctx.removedSourceDirs) {
+        deleteEntriesByStashDir(ctx.db, dir);
+        deleteIndexDirStatesByStashDir(ctx.db, dir);
+        deleteStoredGraph(ctx.db, dir);
+    }
+}
 /**
  * Walk phase: scan the filesystem, generate metadata, and persist entries to
  * the database. Also kicks off LLM enrichment for directories that need it.
@@ -88,16 +117,17 @@ async function runSourceCachePhase(ctx) {
  * `ctx.walkWarnings`, and `ctx.dirsNeedingLlm` for downstream phases.
  */
 async function runWalkPhase(ctx) {
-    const { db, sources, isIncremental, builtAtMs, hadRemovedSources, full, reEnrich, signal, onProgress, config } = ctx;
+    const { db, sources, isIncremental, builtAtMs, hadRemovedSources, full, clean, signal, onProgress, config } = ctx;
     throwIfAborted(signal);
     ctx.timing.tWalkStart = Date.now();
     const doFullDelete = full || !isIncremental;
-    const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings } = await indexEntries(db, sources, isIncremental, builtAtMs, hadRemovedSources, doFullDelete, onProgress);
+    const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings, complete } = await indexEntries(db, sources, isIncremental, builtAtMs, hadRemovedSources, doFullDelete, onProgress, !clean);
     ctx.scannedDirs = scannedDirs;
     ctx.skippedDirs = skippedDirs;
     ctx.generatedCount = generatedCount;
     ctx.walkWarnings = warnings;
     ctx.dirsNeedingLlm = dirsNeedingLlm;
+    ctx.scanComplete = complete;
     onProgress({
         phase: "scan",
         message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
@@ -118,7 +148,7 @@ async function runWalkPhase(ctx) {
     ctx.timing.tWalkEnd = Date.now();
     throwIfAborted(signal);
     // LLM enrichment for directories that need it
-    await enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal, reEnrich);
+    await enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal);
     onProgress({
         phase: "llm",
         message: resolveIndexPassLLM("enrichment", config)
@@ -153,11 +183,20 @@ async function runFinalizePhase(ctx) {
         message: isIncremental ? "Rebuilt full-text search index (dirty rows only)." : "Rebuilt full-text search index.",
     });
     ctx.timing.tFtsEnd = Date.now();
-    // Re-link detached usage_events and recompute utility scores.
-    onProgress({ phase: "finalize", message: "Relinking usage events." });
-    relinkUsageEvents(db);
-    onProgress({ phase: "finalize", message: "Recomputing utility scores." });
-    recomputeUtilityScores(db);
+    // Re-link detached usage_events and recompute utility scores. The one-time
+    // §11.4 legacy→item_ref re-key is owned by the migration cutover
+    // (020-three-db-cutover) now, so index finalize only re-resolves entry_ids
+    // (idempotent) — every stored `entry_ref` is already the item_ref spelling.
+    //
+    // Chunk-8 WI-8.3: usage_events lives in state.db now (index.db no longer holds
+    // it), so these cross-DB passes take both handles — entries in `db` (index.db),
+    // usage_events in the loaned state.db.
+    withStateDb((stateDb) => {
+        onProgress({ phase: "finalize", message: "Relinking usage events." });
+        relinkUsageEvents(db, stateDb, { sources, defaultStashDir: stashDir });
+        onProgress({ phase: "finalize", message: "Recomputing utility scores." });
+        recomputeUtilityScores(db, stateDb);
+    });
     // Purge LLM cache entries for assets that no longer exist in the index.
     try {
         onProgress({ phase: "finalize", message: "Clearing stale LLM cache entries." });
@@ -166,22 +205,22 @@ async function runFinalizePhase(ctx) {
     catch {
         /* ignore */
     }
-    // Regenerate each wiki's index.md from its pages' frontmatter. Best-effort.
-    try {
-        onProgress({ phase: "finalize", message: "Regenerating wiki indexes." });
-        const { regenerateAllWikiIndexes } = await import("../wiki/wiki.js");
-        regenerateAllWikiIndexes(stashDir);
-    }
-    catch {
-        /* best-effort */
-    }
     throwIfAborted(signal);
-    // Update index metadata
+    // An incomplete run preserves the prior freshness watermark. Advancing it
+    // could make a recovered source look unchanged even though this run never
+    // persisted its files.
     const embeddingResult = ctx.embeddingResult ?? { success: false };
-    setMeta(db, "builtAt", new Date().toISOString());
-    setMeta(db, "stashDir", stashDir);
-    setMeta(db, "stashDirs", JSON.stringify(sourceDirs));
+    if (ctx.scanComplete) {
+        setMeta(db, "builtAt", new Date().toISOString());
+        setMeta(db, "stashDir", stashDir);
+        setMeta(db, "stashDirs", JSON.stringify(sourceDirs));
+    }
     setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
+    // Stash-organization conventions (SPEC-8): track which `index.indexBodyOpening`
+    // state the index was built with, and warn while the flag diverges from it.
+    const bodyOpeningWarning = reconcileBodyOpeningIndexState(db, config.index?.indexBodyOpening === true, (ctx.full || !isIncremental) && ctx.scanComplete);
+    if (bodyOpeningWarning)
+        warn(bodyOpeningWarning);
     warnIfVecMissing(db);
     const totalEntries = getEntryCount(db);
     const semanticEntryCount = getEmbeddableEntryCount(db);
@@ -209,6 +248,41 @@ async function runFinalizePhase(ctx) {
     // suppress unused warning — sources was previously used inline
     void sources;
 }
+/**
+ * Stash-organization conventions (SPEC-8): reconcile the `index.indexBodyOpening`
+ * flag with the state the index was last FULLY built with (index_meta key
+ * `indexBodyOpening`), returning a warning message while they diverge.
+ *
+ * Incremental runs re-extract only changed files (and embeddings are only
+ * generated for rows lacking one), so a flag toggle leaves the index MIXED
+ * until a full rebuild — `akm index --full` re-extracts every entry and wipes
+ * embeddings so they regenerate from the new text. The warning therefore
+ * repeats on every incremental run until a full walk records the flag state
+ * as applied.
+ *
+ * A missing meta key on an incremental run means the index predates this
+ * feature, i.e. it was necessarily built with the flag OFF — so the absent
+ * key reads (and is seeded) as "0", never as the current flag value. This
+ * keeps the most likely real toggle scenario — upgrade, enable the flag, run
+ * a plain `akm index` — warning until `--full` runs (review finding).
+ *
+ * Exported for tests; production's only caller is the finalize phase above.
+ */
+export function reconcileBodyOpeningIndexState(db, flagEnabled, isFullWalk) {
+    const bodyOpeningFlag = flagEnabled ? "1" : "0";
+    const prevBodyOpeningFlag = getMeta(db, "indexBodyOpening") ?? "0";
+    // Only a full walk (which includes the first build ever) may record the
+    // current flag as the applied state; incremental runs preserve — or, for a
+    // pre-feature index, seed — the state of the last full build.
+    setMeta(db, "indexBodyOpening", isFullWalk ? bodyOpeningFlag : prevBodyOpeningFlag);
+    if (isFullWalk || prevBodyOpeningFlag === bodyOpeningFlag)
+        return undefined;
+    return (`index.indexBodyOpening is ${flagEnabled ? "enabled" : "disabled"} but the index was built with it ` +
+        `${flagEnabled ? "disabled" : "enabled"}. Incremental runs only re-extract changed files, so ` +
+        "indexed text and embeddings are stale for unchanged entries. Run `akm index --full` to apply the new " +
+        "setting everywhere (embeddings regenerate), and re-mint collapse-detector canary baselines via " +
+        "`bun scripts/refresh-canary-set.ts --refresh` if you use them.");
+}
 // ── Clean pass ───────────────────────────────────────────────────────────────
 /**
  * Post-index clean pass: scan the `entries` table for rows whose source file
@@ -245,7 +319,82 @@ export async function akmIndex(options) {
         return akmIndexOverride(options);
     return akmIndexReal(options);
 }
+/**
+ * Detect an adapter for every resolvable source that does not declare one, and
+ * persist each detection into `config.json`.
+ *
+ * R-056: this config write previously had zero disclosure — it appeared in no
+ * result, on no stream, and in no doc. The returned `persistedAdapters` records
+ * exactly which bundle→adapter pairs the mutate callback actually applied, so
+ * the caller can surface them in the result envelope; a stderr notice is
+ * emitted here. The map is cleared at the top of every callback invocation
+ * because `mutateConfig` may retry optimistically, and a retry must not report
+ * a superseded attempt.
+ *
+ * Extracted from `akmIndexReal` as one self-contained named pass, both to keep
+ * that function under the src-wide function-size bar and because the detection
+ * and its disclosure belong together.
+ */
+function detectAndPersistBundleAdapters(allSourceEntries, config, mutateConfig, opts) {
+    const detectedByBundle = new Map();
+    for (const source of allSourceEntries) {
+        if (source.adapterId || source.unresolved)
+            continue;
+        if (allSourceRootsReadable([source.path])) {
+            source.adapterId = detectAdapterId(source.path);
+            if (source.registryId)
+                detectedByBundle.set(source.registryId, source.adapterId);
+        }
+    }
+    const persistedAdapters = {};
+    if (detectedByBundle.size === 0)
+        return { config, persistedAdapters };
+    const nextConfig = mutateConfig((current) => {
+        if (!current.bundles)
+            return current;
+        let changed = false;
+        const bundles = { ...current.bundles };
+        for (const key of Object.keys(persistedAdapters))
+            delete persistedAdapters[key];
+        for (const [bundleId, adapter] of detectedByBundle) {
+            const bundle = bundles[bundleId];
+            if (!bundle)
+                continue;
+            const componentEntries = Object.entries(bundle.components ?? {});
+            const [componentId, component] = componentEntries[0] ?? ["main", {}];
+            if (component.adapter)
+                continue;
+            bundles[bundleId] = { ...bundle, components: { [componentId]: { ...component, adapter } } };
+            changed = true;
+            persistedAdapters[bundleId] = adapter;
+        }
+        return changed ? { ...current, bundles } : current;
+    }, { absentNoop: true }).config;
+    const persistedCount = Object.keys(persistedAdapters).length;
+    if (persistedCount > 0 && opts.announce) {
+        const summary = Object.entries(persistedAdapters)
+            .map(([bundleId, adapter]) => `${bundleId} → ${adapter}`)
+            .join(", ");
+        warn(`[index] Detected adapter${persistedCount === 1 ? "" : "s"} for ${summary}; persisted to config.json ` +
+            "(bundles.<id>.components.<component>.adapter).");
+    }
+    return { config: nextConfig, persistedAdapters };
+}
 async function akmIndexReal(options) {
+    // R-022: `dryRun` only ever gated the `--clean` stale-entry removal pass
+    // (see `runCleanPass` below) — every other phase (walk, LLM enrichment,
+    // embeddings, FTS, the adapter-detection config write) ran for real
+    // regardless, so `akm index --dry-run` alone silently performed a full,
+    // real index. The flag's own docs (`IndexOptions.dryRun` above, and the
+    // CLI help in stash-cli.ts) already scope it to `--clean`; reject the
+    // combination that was never implemented instead of quietly doing
+    // something other than what "dry run" promised. Checked before the writer
+    // lease is even requested so a bad invocation fails instantly.
+    if (options?.dryRun === true && options?.clean !== true) {
+        const { UsageError } = await import("../core/errors.js");
+        throw new UsageError("`--dry-run` only applies together with `--clean` (it previews which stale entries `--clean` would remove). " +
+            "Pass `akm index --clean --dry-run`, or drop `--dry-run` to run a real index.", "INVALID_FLAG_VALUE", "Run `akm index --clean --dry-run` to preview, or `akm index --clean` to apply.");
+    }
     const requestedAt = Date.now();
     let acquiredAt = requestedAt;
     return withIndexWriterLease({
@@ -261,30 +410,28 @@ async function akmIndexReal(options) {
             acquiredAt = requestedAt + waitedMs;
         },
     }, async () => {
-        const stashDir = options?.stashDir || resolveStashDir();
+        const stashDir = options.stashDir;
         const onProgress = options?.onProgress ?? (() => { });
         const signal = options?.signal;
-        const reEnrich = options?.reEnrich === true;
         const full = options?.full === true;
         const clean = options?.clean === true;
         const dryRun = options?.dryRun === true;
         // Load config and resolve all stash sources
-        const { loadConfig } = await import("../core/config/config.js");
-        const config = loadConfig();
-        // One-time, read-only guard: warn if the writable stash still holds an
-        // un-migrated `vaults/` directory. In 0.9.0 the indexer skips `vaults/`
-        // entirely, so an unmigrated vault's `.env` data would silently never be
-        // indexed. Non-destructive — only stats, never reads/writes/deletes.
-        const { warnOnUnmigratedVaults } = await import("./usage/unmigrated-vaults-guard.js");
-        warnOnUnmigratedVaults(stashDir);
+        const { loadConfig, mutateConfig } = await import("../core/config/config.js");
+        let 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 sourceCacheStart = Date.now();
         onProgress({ phase: "preflight", message: "Hydrating source caches." });
         const { ensureSourceCaches, resolveSourceEntries } = await import("./search/search-source.js");
-        await ensureSourceCaches(config, { force: full });
+        await ensureSourceCaches(config, { force: full, materialize: options.hydrateSources !== false });
         const sourceCacheEnd = Date.now();
         const allSourceEntries = resolveSourceEntries(stashDir, config);
+        const detected = detectAndPersistBundleAdapters(allSourceEntries, config, mutateConfig, {
+            announce: options.implicit !== true,
+        });
+        config = detected.config;
+        const persistedAdapters = detected.persistedAdapters;
         const allSourceDirs = allSourceEntries.map((s) => s.path);
         onProgress({
             phase: "preflight",
@@ -308,7 +455,7 @@ async function akmIndexReal(options) {
                 sources: allSourceEntries,
                 sourceDirs: allSourceDirs,
                 full,
-                reEnrich,
+                clean,
                 stashDir,
                 onProgress,
                 signal,
@@ -325,6 +472,8 @@ async function akmIndexReal(options) {
                 isIncremental,
                 builtAtMs,
                 hadRemovedSources: false,
+                removedSourceDirs: [],
+                scanComplete: true,
                 scannedDirs: 0,
                 skippedDirs: 0,
                 generatedCount: 0,
@@ -346,6 +495,7 @@ async function akmIndexReal(options) {
             // ── Phase sequence ───────────────────────────────────────────────────────
             await runSourceCachePhase(ctx);
             await runWalkPhase(ctx);
+            applyRemovedSources(ctx);
             await runEmbeddingPhase(ctx);
             await runFinalizePhase(ctx);
             // ────────────────────────────────────────────────────────────────────────
@@ -363,7 +513,13 @@ async function akmIndexReal(options) {
                     phase: "finalize",
                     message: dryRun ? "Scanning for stale index entries (dry run)." : "Removing stale index entries.",
                 });
-                cleanResult = runCleanPass(db, dryRun);
+                if (ctx.scanComplete) {
+                    cleanResult = runCleanPass(db, dryRun);
+                }
+                else {
+                    warn("[index] --clean skipped because one or more configured sources were not scanned completely.");
+                    cleanResult = { checked: 0, removed: 0, removedRefs: [], dryRun };
+                }
             }
             const cleanEnd = Date.now();
             // ────────────────────────────────────────────────────────────────────────
@@ -376,6 +532,9 @@ async function akmIndexReal(options) {
                 directoriesScanned: ctx.scannedDirs,
                 directoriesSkipped: ctx.skippedDirs,
                 ...(ctx.walkWarnings.length > 0 ? { warnings: ctx.walkWarnings } : {}),
+                ...(Object.keys(persistedAdapters).length > 0
+                    ? { configUpdated: { detectedAdapters: persistedAdapters } }
+                    : {}),
                 verification,
                 timing: {
                     totalMs: Date.now() - timing.t0,
@@ -398,32 +557,183 @@ async function akmIndexReal(options) {
         }
     });
 }
+function removalsFirst(records) {
+    return [...records.filter((record) => record.remove), ...records.filter((record) => !record.remove)];
+}
+function addEntryIds(target, ids) {
+    for (const id of ids)
+        target.add(id);
+}
+/**
+ * Map each source root → its durable `BundleComponent` (`deriveInstallations`,
+ * batch-unique bundle ids, source order preserved). The per-dir document drain
+ * dispatches `adapterForId(component.adapter).recognize` for this component. The
+ * component id only surfaces on `IndexDocument.ref`, which the persist layer
+ * re-derives independently — so a source missing from the map (never happens: the
+ * map is built from the same sources) is harmless.
+ */
+function buildComponentBySource(sources) {
+    const map = new Map();
+    const installations = deriveInstallations(sources);
+    sources.forEach((source, i) => {
+        const component = installations[i]?.components[0];
+        if (component)
+            map.set(source.path, component);
+    });
+    return map;
+}
+function componentForSource(components, sourcePath) {
+    return (components.get(sourcePath) ?? {
+        id: sourcePath,
+        adapter: "akm",
+        root: sourcePath,
+        writable: false,
+    });
+}
+function groupFileContextsByDir(fileContexts) {
+    const groups = new Map();
+    for (const ctx of fileContexts) {
+        const group = groups.get(ctx.parentDirAbs);
+        if (group)
+            group.push(ctx);
+        else
+            groups.set(ctx.parentDirAbs, [ctx]);
+    }
+    return groups;
+}
+function sourceSnapshotRemovals(db, currentStashDir, currentDirs, allIndexedDirsBySource) {
+    const indexedDirs = allIndexedDirsBySource?.get(path.resolve(currentStashDir)) ?? getIndexedDirPathsByStashDir(db, currentStashDir);
+    return [...indexedDirs]
+        .map((dirPath) => path.resolve(dirPath))
+        .filter((dirPath) => !currentDirs.has(dirPath))
+        .map((dirPath) => ({
+        dirPath,
+        currentStashDir,
+        files: [],
+        stash: null,
+        skip: false,
+        remove: true,
+        reason: { kind: "not-in-source-snapshot" },
+    }));
+}
+function buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMissingDirs) {
+    const componentBySource = buildComponentBySource(allSourceEntries);
+    const handoffDirs = new Set();
+    const plans = allSourceEntries.map((sourceAdded) => {
+        const currentStashDir = sourceAdded.path;
+        const component = componentForSource(componentBySource, currentStashDir);
+        if (sourceAdded.unresolved) {
+            return {
+                currentStashDir,
+                component,
+                adapter: undefined,
+                indexVariant: undefined,
+                dirGroups: new Map(),
+                removals: [],
+                walkComplete: false,
+            };
+        }
+        const walked = walkStashFlatWithStatus(currentStashDir, {
+            includeAllDirectories: component.adapter === "okf",
+        });
+        const dirGroups = groupFileContextsByDir(walked.files);
+        const adapter = adapterForId(component.adapter);
+        return {
+            currentStashDir,
+            component,
+            adapter,
+            indexVariant: adapter ? `${adapter.id}@${adapter.version}` : undefined,
+            dirGroups,
+            removals: [],
+            walkComplete: walked.complete,
+        };
+    });
+    const removalKeys = new Set();
+    const addRemoval = (plan, dirPath, stashDir) => {
+        const resolvedDir = path.resolve(dirPath);
+        const key = `${resolvedDir}\0${path.resolve(stashDir)}`;
+        if (removalKeys.has(key))
+            return;
+        removalKeys.add(key);
+        plan.removals.push({
+            dirPath,
+            currentStashDir: stashDir,
+            files: [],
+            stash: null,
+            skip: false,
+            remove: true,
+            reason: { kind: "not-in-source-snapshot" },
+        });
+        handoffDirs.add(resolvedDir);
+    };
+    const allComplete = plans.every((plan) => plan.walkComplete && plan.adapter !== undefined);
+    // A full, globally-complete run uses the atomic table wipe below. Every
+    // other run reconciles only sources that produced trustworthy snapshots.
+    if (reconcileMissingDirs && (isIncremental || !allComplete)) {
+        const allIndexedDirsBySource = !isIncremental ? new Map() : undefined;
+        if (allIndexedDirsBySource) {
+            for (const entry of getAllEntries(db)) {
+                const sourceRoot = path.resolve(entry.stashDir);
+                const dirs = allIndexedDirsBySource.get(sourceRoot) ?? new Set();
+                dirs.add(path.resolve(entry.dirPath));
+                allIndexedDirsBySource.set(sourceRoot, dirs);
+            }
+        }
+        for (const plan of plans) {
+            if (!plan.walkComplete || !plan.adapter)
+                continue;
+            const currentDirs = new Set([...plan.dirGroups.keys()].map((dirPath) => path.resolve(dirPath)));
+            for (const removal of sourceSnapshotRemovals(db, plan.currentStashDir, currentDirs, allIndexedDirsBySource)) {
+                addRemoval(plan, removal.dirPath, removal.currentStashDir);
+            }
+        }
+    }
+    // Cross-source ownership handoffs can delete another source's rows, so they
+    // still require every possible owner to have completed its scan.
+    if (!allComplete)
+        return { plans, handoffDirs };
+    // The first configured source that exposes a physical directory owns it.
+    // Remove rows left by a prior owner even when both adapters are identical.
+    const claimedDirs = new Set();
+    for (const plan of plans) {
+        for (const dirPath of plan.dirGroups.keys()) {
+            const resolvedDir = path.resolve(dirPath);
+            if (claimedDirs.has(resolvedDir))
+                continue;
+            claimedDirs.add(resolvedDir);
+            for (const priorOwner of getIndexedStashDirsByDir(db, dirPath)) {
+                if (path.resolve(priorOwner) !== path.resolve(plan.currentStashDir)) {
+                    addRemoval(plan, dirPath, priorOwner);
+                }
+            }
+        }
+    }
+    return { plans, handoffDirs };
+}
 /**
  * Phase 1 (async): walk every source directory and pre-generate all metadata
  * outside any transaction, producing the per-directory scan records that
  * {@link persistDirRecords} later writes.
  *
- * generateMetadataFlat is async (uses dynamic import for the matcher/renderer
- * registry), so it cannot run inside a db.transaction() callback — hence the
- * split into a pure-ish scan pass and a synchronous persist pass.
+ * The per-dir document drain (`drainDirDocuments` × the component's dispatched
+ * `adapter.recognize`, F4a M-core-2) is synchronous, but the walk still runs
+ * outside `db.transaction()` so the persist pass can be a single synchronous
+ * transaction.
  */
-async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, onProgress) {
+function reportSourceScanProgress(onProgress, processed, total, message) {
+    onProgress?.({ phase: "scan", message, processed, total });
+}
+async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, onProgress, reconcileMissingDirs = true) {
     let scannedDirs = 0;
     let skippedDirs = 0;
     let generatedCount = 0;
     const warnings = [];
     const seenPaths = new Set();
+    const { plans, handoffDirs } = buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMissingDirs);
     const dirRecords = [];
     let processedDirs = 0;
     let priorDirsChanged = hadRemovedSources;
-    const reportScanProgress = (message) => {
-        onProgress?.({
-            phase: "scan",
-            message,
-            processed: processedDirs,
-            total: allSourceEntries.length,
-        });
-    };
+    const reportScanProgress = (message) => reportSourceScanProgress(onProgress, processedDirs, allSourceEntries.length, message);
     const reportDirDecision = (kind, dirPath, currentStashDir, reason, persistedRowCount) => {
         if (!isVerbose())
             return;
@@ -432,10 +742,7 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
         reportScanProgress(`${kind === "scan" ? "Rescanning" : "Skipping"} ${path.relative(currentStashDir, dirPath) || "."} ` +
             `from ${currentStashDir}: ${reason.kind}${detail}${rowInfo}`);
     };
-    // Duplicate-directory guard shared by the wiki-root and normal branches. A
-    // dir may surface via multiple stash roots; only the first occurrence is
-    // indexed, and the later ones are recorded as skips. Returns true when the
-    // dir was already seen (caller should skip further processing).
+    // Only the first source that exposes a physical directory may index it.
     const markSeenOrSkipDuplicate = (dirPath, currentStashDir, files) => {
         const resolved = path.resolve(dirPath);
         if (seenPaths.has(resolved)) {
@@ -450,9 +757,9 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
     // Incremental freshness gate shared by both branches: consult the persisted
     // dir state and record either a skip (unchanged + eligible for incremental
     // skip) or a scan record carrying the candidate stash.
-    const recordFreshnessDecision = (dirPath, currentStashDir, stateFiles, stash) => {
-        const previousState = getDirIndexState(db, dirPath, stateFiles, builtAtMs);
-        if (isIncremental && !previousState.stale && canUseIncrementalSkip(previousState, priorDirsChanged)) {
+    const recordFreshnessDecision = (dirPath, currentStashDir, stateFiles, stash, hashByFile, conceptIdByFile, indexVariant, forceScan, pruneMissing) => {
+        const previousState = getDirIndexState(db, dirPath, stateFiles, builtAtMs, indexVariant);
+        if (isIncremental && !forceScan && !previousState.stale && canUseIncrementalSkip(previousState, priorDirsChanged)) {
             skippedDirs++;
             dirRecords.push({
                 dirPath,
@@ -461,6 +768,7 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
                 stash: null,
                 skip: true,
                 reason: previousState.reason,
+                indexVariant,
             });
             reportDirDecision("skip", dirPath, currentStashDir, previousState.reason, previousState.persistedRowCount);
             return;
@@ -476,63 +784,46 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
             skip: false,
             reason,
             persistedRowCount: previousState.persistedRowCount,
+            hashByFile,
+            conceptIdByFile,
+            indexVariant,
+            pruneMissing,
         });
         reportDirDecision("scan", dirPath, currentStashDir, reason, previousState.persistedRowCount);
     };
-    for (const sourceAdded of allSourceEntries) {
-        const currentStashDir = sourceAdded.path;
-        const fileContexts = walkStashFlat(currentStashDir);
+    for (const plan of plans) {
+        const { currentStashDir, component, adapter, dirGroups, removals, walkComplete } = plan;
         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;
-            const wikiDirGroups = new Map();
-            for (const ctx of fileContexts) {
-                if (ctx.ext !== ".md")
-                    continue;
-                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,
-                    quality: "generated",
-                    confidence: 0.55,
-                    source: "filename",
-                };
-                applyCuratedFrontmatter(entry, frontmatter);
-                applyWikiFrontmatter(entry, frontmatter);
-                const dir = ctx.parentDirAbs;
-                const group = wikiDirGroups.get(dir);
-                if (group) {
-                    group.files.push(ctx.absPath);
-                    group.entries.push(entry);
-                }
-                else {
-                    wikiDirGroups.set(dir, { files: [ctx.absPath], entries: [entry] });
-                }
-            }
-            for (const [dirPath, { files, entries }] of wikiDirGroups) {
-                if (markSeenOrSkipDuplicate(dirPath, currentStashDir, files))
-                    continue;
-                recordFreshnessDecision(dirPath, currentStashDir, files, { entries });
-            }
+        if (!walkComplete) {
+            for (const dirPath of dirGroups.keys())
+                seenPaths.add(path.resolve(dirPath));
+            warn(`[index] source "${component.id}" was not scanned completely; preserving its last-known-good rows.`);
             continue;
         }
-        const dirGroups = new Map();
-        for (const ctx of fileContexts) {
-            const dir = ctx.parentDirAbs;
-            const group = dirGroups.get(dir);
-            if (group)
-                group.push(ctx.absPath);
-            else
-                dirGroups.set(dir, [ctx.absPath]);
+        // Owner ruling 2026-07-21: dispatch each component's DETECTED adapter (§4).
+        // An unknown adapter id has no `adapterForId` match → skip the whole
+        // component with a warning (one bundle = one component = one adapter).
+        if (!adapter) {
+            for (const dirPath of dirGroups.keys())
+                seenPaths.add(path.resolve(dirPath));
+            warn(`Skipping component "${component.id}": unknown adapter id "${component.adapter}".`);
+            continue;
+        }
+        const indexVariant = plan.indexVariant ?? `${adapter.id}@${adapter.version}`;
+        for (const removal of removals) {
+            dirRecords.push(removal);
+            scannedDirs++;
+            priorDirsChanged = true;
+            reportDirDecision("scan", removal.dirPath, currentStashDir, removal.reason);
         }
-        for (const [dirPath, files] of dirGroups) {
-            const indexableFiles = files.filter((file) => shouldIndexStashFile(currentStashDir, file));
+        for (const [dirPath, ctxs] of dirGroups) {
+            // Adapter-owned filtering (owner ruling 2026-07-21): the drain no longer
+            // pre-filters with AKM-stash policy — each adapter's `recognize` claims or
+            // abstains on its own bundle's walked files. The core walk keeps only the
+            // universal hygiene `walkStashFlat` already applies (.git/dot-dirs/etc.).
+            const indexableFiles = ctxs.map((ctx) => ctx.absPath);
+            const forceScan = handoffDirs.has(path.resolve(dirPath));
             if (markSeenOrSkipDuplicate(dirPath, currentStashDir, indexableFiles))
                 continue;
             if (indexableFiles.length === 0) {
@@ -542,7 +833,9 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
                 reportDirDecision("skip", dirPath, currentStashDir, reason);
                 continue;
             }
-            const cachedZeroRowState = isIncremental && getCachedZeroRowDirState(db, dirPath, indexableFiles, builtAtMs, priorDirsChanged);
+            const cachedZeroRowState = isIncremental &&
+                !forceScan &&
+                getCachedZeroRowDirState(db, dirPath, indexableFiles, builtAtMs, priorDirsChanged, indexVariant);
             if (cachedZeroRowState) {
                 skippedDirs++;
                 dirRecords.push({
@@ -552,40 +845,100 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
                     stash: null,
                     skip: true,
                     reason: cachedZeroRowState.reason,
+                    indexVariant,
                 });
                 reportDirDecision("skip", dirPath, currentStashDir, cachedZeroRowState.reason, cachedZeroRowState.persistedRowCount);
                 continue;
             }
-            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);
+            // F4a M-core-2 (the flip): drain the dir's `IndexDocument` stream via the
+            // component's dispatched `adapter.recognize` (broken workflows dropped-with-
+            // warning at the drain layer) and reconstruct the durable `IndexDocument`s.
+            const drained = drainDirDocuments(adapter, component, ctxs);
+            if (drained.warnings.length)
+                warnings.push(...drained.warnings);
+            const generated = drained.warnings.length
+                ? { entries: drained.entries, warnings: drained.warnings }
+                : { entries: drained.entries };
+            // `.stash.json` sidecar overrides retired (#39): the cutover's content
+            // migration folded sidecar metadata into frontmatter and deleted the
+            // files; the runtime no longer reads them.
+            const { stash, staleFiles } = buildIndexedDirCandidate(dirPath, indexableFiles, generated);
             if (generated.entries.length > 0) {
                 generatedCount += generated.entries.length;
             }
-            recordFreshnessDecision(dirPath, currentStashDir, staleFiles, stash);
+            recordFreshnessDecision(dirPath, currentStashDir, staleFiles, stash, drained.hashByFile, drained.conceptIdByFile, indexVariant, forceScan, walkComplete);
         }
     }
-    return { dirRecords, scannedDirs, skippedDirs, generatedCount, warnings };
+    return {
+        dirRecords: removalsFirst(dirRecords),
+        scannedDirs,
+        skippedDirs,
+        generatedCount,
+        warnings,
+        complete: plans.every((plan) => plan.walkComplete && plan.adapter !== undefined),
+    };
+}
+function preserveExistingIndex(doFullDelete, dirRecords, sourceRoots) {
+    if (!doFullDelete)
+        return false;
+    const incomingDocCount = dirRecords.reduce((n, record) => n + (record.skip ? 0 : (record.stash?.entries.length ?? 0)), 0);
+    if (incomingDocCount > 0 || allSourceRootsReadable(sourceRoots))
+        return false;
+    warn("[index] --full produced zero documents while one or more source roots are missing or unreadable — " +
+        "preserving the existing index (last-known-good) rather than wiping it. Re-run once the sources are available.");
+    return true;
+}
+/**
+ * #624-P1 zero-document preflight probe. A source root counts as "readable"
+ * when it exists on disk as a directory whose listing can be read. A root that
+ * is missing or unreadable (a transient mount failure, a permission race, or a
+ * source that vanished mid-run) makes a zero-document scan untrustworthy: the
+ * walk saw nothing not because the stash is empty but because it could not be
+ * read. Returns true only when EVERY root is readable, so a single unreadable
+ * root blocks the full-rebuild wipe.
+ */
+function allSourceRootsReadable(roots) {
+    for (const root of roots) {
+        try {
+            const st = fs.statSync(root);
+            if (!st.isDirectory())
+                return false;
+            fs.readdirSync(root); // probe readability, not just existence
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
 }
 /**
  * Phase 2 (sync): write all pre-generated scan records inside a single
  * transaction, returning the directories that still need LLM enrichment.
  */
-function persistDirRecords(db, dirRecords, doFullDelete, warnings) {
+function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots, scanComplete, bundleByRoot) {
     const dirsNeedingLlm = [];
-    // Cross-stash dedup: track indexed assets by content identity
-    // (type + filename + description) so the same asset from a lower-priority
-    // stash root is skipped when a higher-priority root already covers it.
-    // Sources are ordered by priority (primary stash first), so the first
-    // occurrence wins.
+    const fullDelete = doFullDelete && scanComplete;
+    // #624-P1 zero-document preflight (spec §4). A full-rebuild wipe is a
+    // legitimate mass-delete ONLY when the scan legitimately found nothing. If
+    // the walk produced zero documents AND any configured source root is missing
+    // or unreadable, the empty result is almost certainly a transient scan
+    // failure, not an emptied stash — wiping here would cascade-destroy the
+    // last-known-good index (entries + embeddings + utility/usage). Preserve it
+    // and warn instead; the next successful run reconciles. A genuinely empty
+    // stash whose roots ARE readable still wipes, as before.
+    if (preserveExistingIndex(fullDelete, dirRecords, sourceRoots))
+        return { dirsNeedingLlm };
+    // Per-source dedup: the same logical asset can appear more than once within
+    // one owning source, where source order still makes the first occurrence win.
+    // The owner is part of the key so identical concepts in different bundles
+    // remain distinct indexed rows.
     const indexedAssetIdentities = new Set();
+    const deletedUsageEntryIds = new Set();
     const insertTransaction = db.transaction(() => {
         // Perform the full-rebuild wipe as the FIRST step of the insert
         // transaction so delete and re-insert are atomic — a concurrent reader
         // never observes an empty database between the two operations.
-        if (doFullDelete) {
+        if (fullDelete) {
             try {
                 db.exec("DELETE FROM embeddings");
             }
@@ -603,20 +956,22 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings) {
             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 {
-                db.exec("UPDATE usage_events SET entry_id = NULL WHERE entry_id IS NOT NULL");
-            }
-            catch {
-                /* ignore if table doesn't exist */
-            }
+            // Chunk-8 WI-8.3: usage_events lives in state.db now (not index.db), so the
+            // wipe no longer detaches it here. The finalize pass's relinkUsageEvents
+            // (cross-DB) nulls entry_ids that no longer resolve to a rebuilt entry and
+            // re-resolves the rest by entry_ref — subsuming the old detach.
             db.exec("DELETE FROM entries");
         }
-        for (const { dirPath, currentStashDir, files, stash, skip, reason } of dirRecords) {
+        for (const { dirPath, currentStashDir, files, stash, skip, reason, hashByFile, conceptIdByFile, indexVariant, remove, pruneMissing, } of dirRecords) {
+            if (remove) {
+                const removedIds = deleteEntriesByDirAndStash(db, dirPath, currentStashDir, { cleanupUsageEvents: false });
+                addEntryIds(deletedUsageEntryIds, removedIds);
+                deleteIndexDirState(db, dirPath);
+                continue;
+            }
             if (skip) {
                 if (reason?.kind === "unchanged") {
-                    const fingerprint = computeDirFingerprint(dirPath, files);
+                    const fingerprint = computeDirFingerprint(dirPath, files, indexVariant);
                     upsertIndexDirState(db, {
                         dirPath,
                         fileSetHash: fingerprint.fileSetHash,
@@ -626,30 +981,49 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings) {
                 }
                 continue;
             }
-            // Delete old entries for this dir (will be re-inserted)
-            deleteEntriesByDir(db, dirPath);
+            // Diff-persist (F4a M-core-2, spec §14.2): upsert the current file set
+            // FIRST (ON CONFLICT preserving `entries.id` so embeddings / utility /
+            // usage stay attached to unchanged rows), tracking every upserted
+            // `entry_key`, then prune only the DEPARTED rows below. Replaces the old
+            // `deleteEntriesByDir` truncate-and-reinsert (which discarded ids).
+            const keptEntryKeys = new Set();
             let persistedRows = 0;
             let dedupedRows = 0;
             if (stash) {
+                const bundle = bundleByRoot.get(path.resolve(currentStashDir));
+                if (!bundle)
+                    throw new Error(`Missing bundle provenance for indexed source ${currentStashDir}`);
+                const ownerIdentity = bundle.bundleId;
                 for (const entry of stash.entries) {
                     const entryPath = entry.filename ? path.join(dirPath, entry.filename) : null;
                     if (!entryPath) {
                         warn(`Skipping entry with no resolvable path in ${dirPath}`);
                         continue;
                     }
-                    if (!shouldIndexStashFile(currentStashDir, entryPath))
+                    const adapterConceptId = conceptIdByFile?.get(entryPath);
+                    if (!adapterConceptId) {
+                        warn(`Skipping entry without adapter-owned concept identity: ${entryPath}`);
                         continue;
-                    // Skip if a higher-priority stash root already indexed this asset
-                    const identityKey = `${entry.type}\0${entry.name}`;
+                    }
+                    // Adapter-owned concept identity is path-based and cannot be replaced
+                    // by presentation fields such as type/title.
+                    const identityKey = `${ownerIdentity}\0${adapterConceptId}`;
                     if (indexedAssetIdentities.has(identityKey)) {
                         dedupedRows++;
                         continue;
                     }
                     indexedAssetIdentities.add(identityKey);
-                    const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
+                    const entryKey = bundle?.adapterId !== "akm" && adapterConceptId
+                        ? `${currentStashDir}:concept:${adapterConceptId}`
+                        : `${currentStashDir}:${entry.type}:${entry.name}`;
+                    keptEntryKeys.add(entryKey);
                     const searchText = buildSearchText(entry);
                     const entryWithSize = attachFileSize(entry, entryPath);
-                    const entryId = upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entryWithSize, searchText);
+                    // content_hash = doc.hash from the drain, keyed by the recognized
+                    // file's path. A missing hash preserves the existing value on upsert.
+                    const contentHash = hashByFile?.get(entryPath);
+                    const provenance = deriveEntryProvenance(bundle, entry.type, entry.name, adapterConceptId);
+                    const entryId = upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, entryWithSize, searchText, provenance, contentHash);
                     persistedRows++;
                     if (entry.type === "workflow") {
                         const doc = takeWorkflowDocument(entry);
@@ -659,13 +1033,19 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings) {
                     }
                 }
                 // Collect dirs needing LLM enhancement during the first walk.
-                // Only dirs with "generated" entries need enrichment (unless reEnrich
-                // forces re-processing of already-enriched entries).
+                // Only dirs with "generated" entries need enrichment.
                 if (stash.entries.some((e) => e.quality === "generated")) {
                     dirsNeedingLlm.push({ dirPath, files, currentStashDir, stash });
                 }
             }
-            const fingerprint = computeDirFingerprint(dirPath, files);
+            // Prune the departed rows: everything under this dir NOT re-upserted above
+            // (files deleted, deduped away, or abstained on by the adapter). With
+            // an empty kept-set this deletes every row for the dir — the exact net
+            // effect of the old unconditional `deleteEntriesByDir`, minus the id churn.
+            if (pruneMissing !== false) {
+                addEntryIds(deletedUsageEntryIds, deleteEntriesByDirExceptKeys(db, dirPath, currentStashDir, keptEntryKeys, { cleanupUsageEvents: false }));
+            }
+            const fingerprint = computeDirFingerprint(dirPath, files, indexVariant);
             const persistedReason = persistedRows === 0
                 ? inferZeroRowReason(stash, reason, warnings, dirPath, dedupedRows)
                 : reason?.kind === "full-rebuild"
@@ -696,17 +1076,55 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings) {
         }
     });
     insertTransaction();
+    deleteUsageEventsByEntryIds([...deletedUsageEntryIds]);
     return { dirsNeedingLlm };
 }
-async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, doFullDelete = false, onProgress) {
+async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, doFullDelete = false, onProgress, reconcileMissingDirs = true) {
     // Phase 1 (async): walk directories and pre-generate all metadata outside the
     // transaction.
-    const { dirRecords, scannedDirs, skippedDirs, generatedCount, warnings } = await scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, onProgress);
+    const { dirRecords, scannedDirs, skippedDirs, generatedCount, warnings, complete } = await scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, onProgress, reconcileMissingDirs);
     // Phase 2 (sync): write all pre-generated metadata inside a single transaction.
-    const { dirsNeedingLlm } = persistDirRecords(db, dirRecords, doFullDelete, warnings);
-    return { scannedDirs, skippedDirs, generatedCount, warnings, dirsNeedingLlm };
+    // Source roots feed the #624-P1 zero-document preflight (a full-rebuild wipe
+    // is suppressed when the scan is empty because roots are unreadable).
+    const sourceRoots = allSourceEntries.map((s) => s.path);
+    // Chunk-5 Step 2 (spec §14.4): map each source root → its durable bundle id so
+    // the writer can persist `item_ref = <bundle>//<conceptId>` and the component/
+    // adapter provenance alongside the legacy columns. `deriveInstallations`
+    // preserves source order, so a positional zip yields the SAME bundle id the
+    // dispatched `adapter.recognize` emits as `IndexDocument.ref` for that root.
+    const installations = deriveInstallations(allSourceEntries);
+    const bundleByRoot = new Map();
+    allSourceEntries.forEach((source, i) => {
+        const inst = installations[i];
+        if (!inst)
+            return;
+        const component = inst.components[0];
+        bundleByRoot.set(path.resolve(source.path), {
+            bundleId: inst.id,
+            componentId: component?.id ?? inst.id,
+            adapterId: component?.adapter ?? "akm",
+        });
+    });
+    const { dirsNeedingLlm } = persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots, complete, bundleByRoot);
+    return { scannedDirs, skippedDirs, generatedCount, warnings, dirsNeedingLlm, complete };
 }
-async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal, reEnrich = false) {
+function indexedProvenanceForFile(db, filePath) {
+    const row = db
+        .prepare("SELECT item_ref AS itemRef, bundle_id AS bundleId, component_id AS componentId, " +
+        "concept_id AS conceptId, adapter_id AS adapterId FROM entries WHERE file_path = ? LIMIT 1")
+        .get(filePath);
+    if (!row?.itemRef || !row.bundleId || !row.componentId || !row.conceptId || !row.adapterId) {
+        throw new Error(`Missing indexed provenance for ${filePath}`);
+    }
+    return {
+        itemRef: row.itemRef,
+        bundleId: row.bundleId,
+        componentId: row.componentId,
+        conceptId: row.conceptId,
+        adapterId: row.adapterId,
+    };
+}
+async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal) {
     // 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)
@@ -716,27 +1134,29 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
     // Aggregate per-entry failures so a misconfigured LLM endpoint surfaces
     // as a single visible warning instead of silently degrading every entry
     // and leaving the user wondering why nothing got enhanced.
-    const summary = { attempted: 0, succeeded: 0, failureSamples: [] };
+    const summary = { attempted: 0, succeeded: 0, skipped: 0, failureSamples: [] };
     let completedDirs = 0;
     let completedEntries = 0;
     const totalDirs = dirsNeedingLlm.length;
     const totalEntries = dirsNeedingLlm.reduce((sum, { stash }) => {
         const entriesToEnhance = stash.entries.filter((e) => {
-            if (e.quality !== "generated" && !(reEnrich && e.quality === "enriched"))
+            if (e.quality !== "generated")
                 return false;
-            if (!reEnrich && isEnrichmentComplete(e))
+            if (isEnrichmentComplete(e))
                 return false;
             return true;
         });
         return sum + entriesToEnhance.length;
     }, 0);
-    // P3 — wall-clock budget for the enrichment pass. Defaults to llm.timeoutMs
-    // (or 10 minutes if not set). Users can extend this via llm.timeoutMs in
-    // config — no separate knob needed.
-    const budgetMs = (llmConfig.timeoutMs ?? 10 * 60 * 1000) * Math.max(totalEntries, 1);
-    const enrichDeadline = AbortSignal.timeout(budgetMs);
+    // P3 — wall-clock budget for the enrichment pass. Defaults to the resolved
+    // engine's timeoutMs (or 10 minutes if not set). Users can extend it via
+    // `index.enrichment.timeoutMs` (or `index.defaults.timeoutMs`, or the
+    // engine's own `engines.<name>.timeoutMs`) — no separate knob needed.
+    const enrichDeadline = createEnrichmentDeadline(llmConfig.timeoutMs, totalEntries);
     let deadlineHit = false;
     const enrichSignal = (() => {
+        if (!enrichDeadline)
+            return signal ?? new AbortController().signal;
         if (!signal)
             return enrichDeadline;
         // Combine: abort when either fires.
@@ -780,14 +1200,13 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
         await concurrentMap(dirsNeedingLlm, async ({ dirPath, files, currentStashDir, stash: originalStash }) => {
             if (enrichSignal.aborted)
                 return undefined;
-            // Only enhance generated entries (or all when reEnrich=true);
-            // user-provided overrides should not be overwritten.
-            // Skip entries that are already fully enriched (description + tags + searchHints)
-            // unless the caller explicitly requests re-enrichment via reEnrich=true.
+            // Only enhance generated entries; user-provided overrides should not
+            // be overwritten. Skip entries that are already fully enriched
+            // (description + tags + searchHints).
             const entriesToEnhance = originalStash.entries.filter((e) => {
-                if (e.quality !== "generated" && !(reEnrich && e.quality === "enriched"))
+                if (e.quality !== "generated")
                     return false;
-                if (!reEnrich && isEnrichmentComplete(e)) {
+                if (isEnrichmentComplete(e)) {
                     warnVerbose(`[akm] skipping LLM enrichment for "${e.name}" — entry already complete`);
                     return false;
                 }
@@ -806,7 +1225,7 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
             lastProgressAt = Date.now();
             const targetStash = { entries: entriesToEnhance };
             const entryKeys = entriesToEnhance.map((e) => `${currentStashDir}:${e.type}:${e.name}`);
-            const enhanced = await enhanceStashWithLlm(llmConfig, targetStash, files, summary, enrichSignal, db, entryKeys, reEnrich, config, (event) => {
+            const enhanced = await enhanceStashWithLlm(llmConfig, targetStash, files, summary, enrichSignal, db, entryKeys, config, (event) => {
                 completedEntries++;
                 lastProgressAt = Date.now();
                 onProgress?.({
@@ -827,7 +1246,8 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
                     const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
                     const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
                     const searchText = buildSearchText(entry);
-                    upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, attachFileSize(entry, entryPath), searchText);
+                    const provenance = indexedProvenanceForFile(db, entryPath);
+                    upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, attachFileSize(entry, entryPath), searchText, provenance);
                 }
             })();
             completedDirs++;
@@ -841,10 +1261,10 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
             });
             return undefined;
         }, 
-        // Default concurrency of 4 works well for cloud LLM APIs. Local model
-        // servers (LM Studio, Ollama) run one inference at a time — set
-        // `llm.concurrency: 1` in config.json to avoid "Model reloaded" / 500
-        // errors from concurrent request overload.
+        // Defaults: 2 for remote LLM APIs, 1 for local model servers (LM
+        // Studio, Ollama run one inference at a time — parallel requests cause
+        // "Model reloaded" / 500 errors). No config override reaches this path:
+        // `resolveLlmEngineUse` does not forward `engines.<name>.concurrency`.
         getDefaultLlmConcurrency(llmConfig));
     }
     finally {
@@ -852,19 +1272,25 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
             clearInterval(heartbeatTimer);
     }
     if (deadlineHit) {
-        warn("[akm] LLM enrichment budget exceeded. Re-run `akm index` to continue. Increase llm.timeoutMs for a larger budget.");
+        warn("[akm] LLM enrichment budget exceeded. Re-run `akm index` to continue. Increase index.enrichment.timeoutMs for a larger budget.");
     }
-    if (summary.attempted > 0 && summary.succeeded === 0) {
+    // Gate-closed (`skipped`) entries are not failures — exclude them so a
+    // deliberately disabled feature never surfaces as an enrichment error.
+    const failed = summary.attempted - summary.succeeded - summary.skipped;
+    if (failed > 0 && summary.succeeded === 0) {
         const sample = summary.failureSamples.length ? ` Example: ${summary.failureSamples[0]}` : "";
-        warn(`LLM enhancement failed for all ${summary.attempted} attempted entries — index built without LLM enrichment.` +
+        warn(`LLM enhancement failed for all ${failed} attempted entries — index built without LLM enrichment.` +
             ` Check llm.endpoint and llm.model in your config.${sample}`);
     }
-    else if (summary.attempted > 0 && summary.succeeded < summary.attempted) {
-        const failed = summary.attempted - summary.succeeded;
+    else if (failed > 0) {
         const sample = summary.failureSamples.length ? ` Examples: ${summary.failureSamples.join("; ")}` : "";
         warn(`LLM enhancement failed for ${failed}/${summary.attempted} entries — they were left un-enhanced.${sample}`);
     }
 }
+export function createEnrichmentDeadline(timeoutMs, totalEntries) {
+    const perEntryTimeoutMs = timeoutMs === undefined ? 10 * 60 * 1000 : timeoutMs;
+    return perEntryTimeoutMs === null ? undefined : AbortSignal.timeout(perEntryTimeoutMs * Math.max(totalEntries, 1));
+}
 async function generateEmbeddingsForDb(db, config, onProgress, signal) {
     throwIfAborted(signal);
     if (config.semanticSearchMode === "off") {
@@ -922,25 +1348,39 @@ async function generateEmbeddingsForDb(db, config, onProgress, signal) {
             // state is rolled back on failure rather than leaving the table half-filled.
             let storedCount = 0;
             let skippedCount = 0;
+            let vecFailedCount = 0;
             db.transaction(() => {
                 for (let i = 0; i < allEntries.length; i++) {
-                    if (upsertEmbedding(db, allEntries[i].id, embeddings[i])) {
+                    const res = upsertEmbedding(db, allEntries[i].id, embeddings[i]);
+                    if (res.stored) {
                         storedCount++;
                     }
                     else {
                         skippedCount++;
                     }
+                    if (res.vec === "failed")
+                        vecFailedCount++;
                 }
             })();
             if (skippedCount > 0) {
                 warn(`[embed] ${skippedCount} embedding${skippedCount === 1 ? "" : "s"} skipped (entry deleted between queue and write)`);
             }
+            // Record the ACTUAL vec-insert outcome so semantic search reflects it
+            // instead of inferring readiness from stored-BLOB counts. Any failure
+            // marks the fast path degraded, routing search to the JS-cosine fallback
+            // over the (complete) BLOB table — honest degradation, not a hard failure.
+            setVecFastPathReady(db, vecFailedCount === 0);
+            if (vecFailedCount > 0) {
+                warn(`[embed] ${vecFailedCount} sqlite-vec fast-path insert${vecFailedCount === 1 ? "" : "s"} failed — ` +
+                    "semantic search will use the slower JS-cosine fallback over stored embeddings. " +
+                    "Rebuild with 'akm index --full' after resolving the vec table (often a vector-dimension mismatch).");
+            }
             onProgress({
                 phase: "embeddings",
                 message: `Stored ${storedCount} embedding${storedCount === 1 ? "" : "s"}.`,
             });
             setMeta(db, "embeddingFingerprint", currentFingerprint);
-            return { success: true };
+            return { success: true, vecInsertFailures: vecFailedCount };
         }
         finally {
             if (heartbeatTimer)
@@ -1032,7 +1472,7 @@ function verifyIndexState(db, config, embeddableEntries, embeddingResult) {
             `Semantic search verification failed (${embeddingCount}/${embeddableEntries} embeddings available).`,
         guidance: embeddingProvider === "remote"
             ? "Check your embedding endpoint and credentials, then retry `akm index --full --verbose`."
-            : "Retry `akm index --full --verbose`. If it still fails, confirm local model downloads are permitted and see docs/configuration.md for local embedding dependency setup.",
+            : "Retry `akm index --full --verbose`. If it still fails, confirm local model downloads are permitted and see docs/reference/configuration.md for local embedding dependency setup.",
         semanticSearchEnabled: true,
         semanticSearchMode: config.semanticSearchMode,
         semanticStatus: "blocked",
@@ -1042,29 +1482,22 @@ function verifyIndexState(db, config, embeddableEntries, embeddingResult) {
         vecAvailable,
     };
 }
-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;
+function buildIndexedDirCandidate(dirPath, indexableFiles, generated) {
+    const stash = generated.entries.length > 0 ? { entries: generated.entries } : null;
     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);
-        if (entryPath)
-            resolved.add(entryPath);
+        if (entry.filename)
+            resolved.add(path.join(dirPath, entry.filename));
     }
     return resolved.size > 0 ? [...resolved] : files;
 }
-async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db, entryKeys, reEnrich, akmConfig, onEntryDone) {
+async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db, entryKeys, akmConfig, onEntryDone) {
     const { enhanceMetadata } = await import("../llm/metadata-enhance.js");
-    const { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } = await import("./db/db.js");
+    const { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } = await import("../storage/repositories/index-llm-cache-repository.js");
     const results = await concurrentMap(stash.entries, async (entry, idx) => {
         if (signal?.aborted)
             return entry;
@@ -1082,13 +1515,13 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db,
                     warn(`Could not read file for LLM enrichment: ${entry.filename ?? entry.name}`);
                 }
             }
-            // Incremental cache: skip LLM call when file body is unchanged and
-            // --re-enrich was not requested. The cache key is the entry_key
-            // (stashDir:type:name) which is stable across index runs.
+            // Incremental cache: skip LLM call when file body is unchanged. The
+            // cache key is the entry_key (stashDir:type:name) which is stable
+            // across index runs.
             const cacheBody = fileContent ?? `${entry.name}\n${entry.description ?? ""}`;
             const bodyHash = computeBodyHash(cacheBody);
             const cacheKey = entryKeys?.[idx] ?? `${entry.type}:${entry.name}`;
-            if (db && !reEnrich) {
+            if (db) {
                 const cached = getLlmCacheEntry(db, cacheKey, bodyHash);
                 if (cached) {
                     try {
@@ -1110,7 +1543,27 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db,
                     }
                 }
             }
-            const improvements = await enhanceMetadata(llmConfig, entry, fileContent, signal, akmConfig);
+            const outcome = await enhanceMetadata(llmConfig, entry, fileContent, signal, akmConfig);
+            if (outcome.status !== "enriched") {
+                // Not a genuine LLM success: the gate was closed (`skipped`) or the
+                // call errored/timed out (`failed`). Do NOT mark the entry enriched
+                // and do NOT write the LLM cache — caching here would poison the
+                // entry into a permanent enrichment skip even though nothing was
+                // enhanced. Surface failures honestly; stay silent on gated-off skips.
+                if (outcome.status === "failed") {
+                    const msg = outcome.error ?? "metadata enrichment failed";
+                    if (summary.failureSamples.length < 3 && !summary.failureSamples.includes(msg)) {
+                        summary.failureSamples.push(msg);
+                    }
+                    onEntryDone?.({ entryName: entry.name, outcome: "failed" });
+                }
+                else {
+                    summary.skipped++;
+                    onEntryDone?.({ entryName: entry.name, outcome: "skipped" });
+                }
+                return entry;
+            }
+            const improvements = outcome.metadata;
             const updated = { ...entry };
             if (improvements.description)
                 updated.description = improvements.description;
@@ -1118,7 +1571,11 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db,
                 updated.searchHints = improvements.searchHints;
             if (improvements.tags?.length)
                 updated.tags = improvements.tags;
-            // Mark as enriched so subsequent index runs skip re-enrichment (P2)
+            // Mark as enriched so subsequent index runs skip re-enrichment (P2).
+            // An empty-but-successful response is still cached: the LLM was paid
+            // for this body_hash and produced no improvements, so re-running would
+            // only re-pay for the same no-op. (The cache protects against re-paying
+            // for the LLM call when the file body is unchanged.)
             updated.quality = "enriched";
             // Persist to cache so the next run can skip the LLM call when the
             // file body has not changed.
@@ -1144,8 +1601,8 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db,
             return entry;
         }
     }, 
-    // Default concurrency of 4 works well for cloud LLM APIs. Set
-    // `llm.concurrency: 1` in config.json for local model servers.
+    // Defaults: 2 for remote LLM APIs, 1 for local model servers. No config
+    // override reaches this path (see getDefaultLlmConcurrency).
     getDefaultLlmConcurrency(llmConfig));
     // concurrentMap returns Array<T | undefined>; filter out undefined slots
     // (which can only occur if the callback itself returned undefined, which
@@ -1153,54 +1610,68 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db,
     const enhanced = results.map((r, i) => r ?? stash.entries[i]);
     return { entries: enhanced };
 }
-/**
- * Build a map from base filename (without extension) to full path for quick lookups.
- */
-export function buildFileBasenameMap(files) {
-    const map = new Map();
-    for (const file of files) {
-        const base = path.basename(file, path.extname(file));
-        // Only keep first match per base name to avoid ambiguity
-        if (!map.has(base))
-            map.set(base, file);
-    }
-    return map;
+// ── lookup ─────────────────────────────────────────────────────────────────
+import { makeBundleRef } from "../core/asset/asset-ref.js";
+import { conceptIdFromTypeName } from "../core/asset/resolve-ref.js";
+async function resolveLookupSources() {
+    const { loadConfig } = await import("../core/config/config.js");
+    const { resolveSourceEntries } = await import("./search/search-source.js");
+    return resolveSourceEntries(undefined, loadConfig());
 }
-/**
- * Try to match a filename-less entry to an actual file in the directory.
- *
- * Matching strategy (in priority order):
- *   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. No implicit file fallback: ambiguous legacy entries are skipped
- */
-export function matchEntryToFile(entryName, fileMap) {
-    // Exact match on entry name
-    const exact = fileMap.get(entryName);
-    if (exact)
-        return exact;
-    // Try last segment for hierarchical names (e.g. "corpus/agentic-patterns/foo")
-    const lastSegment = entryName.split("/").pop() ?? entryName;
-    if (lastSegment !== entryName) {
-        const segmentMatch = fileMap.get(lastSegment);
-        if (segmentMatch)
-            return segmentMatch;
-    }
-    return null;
+function resolveLookupScope(bundle, sources) {
+    if (!bundle)
+        return { candidateDirs: sources.map((source) => source.path), qualified: false };
+    return { candidateDirs: resolveSourcesForOrigin(bundle, sources).map((source) => source.path), qualified: true };
 }
-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,
-    };
+/** Resolve an adapter-owned `[bundle//]conceptId` without interpreting its path as an AKM type. */
+export async function lookupBundleRef(ref) {
+    const sources = await resolveLookupSources();
+    if (sources.length === 0)
+        return null;
+    const { candidateDirs, qualified } = resolveLookupScope(ref.bundle, sources);
+    if (candidateDirs.length === 0)
+        return null;
+    const db = openExistingDatabase(getDbPath());
+    try {
+        const inputRef = makeBundleRef(qualified ? ref.bundle : undefined, ref.conceptId);
+        for (const dir of candidateDirs) {
+            const id = findEntryIdByRef(db, inputRef, dir);
+            if (id === undefined)
+                continue;
+            const row = db
+                .prepare("SELECT entry_key AS entryKey, file_path AS filePath, stash_dir AS stashDir, entry_type AS type, " +
+                "entry_json AS entryJson, item_ref AS itemRef, bundle_id AS bundleId, concept_id AS conceptId, " +
+                "adapter_id AS adapterId FROM entries WHERE id = ?")
+                .get(id);
+            if (!row)
+                continue;
+            let document;
+            try {
+                document = JSON.parse(row.entryJson);
+            }
+            catch {
+                // Corrupt optional projection does not erase the durable path identity.
+            }
+            if (!row.itemRef || !row.bundleId || !row.conceptId || !row.adapterId)
+                continue;
+            return {
+                entryKey: row.entryKey,
+                filePath: row.filePath,
+                stashDir: row.stashDir,
+                type: row.type,
+                name: document?.name ?? ref.conceptId.split("/").pop() ?? ref.conceptId,
+                adapterId: row.adapterId,
+                document,
+                itemRef: row.itemRef,
+                bundleId: row.bundleId,
+                conceptId: row.conceptId,
+            };
+        }
+        return null;
+    }
+    finally {
+        closeDatabase(db);
+    }
 }
 /**
  * Look up a single asset by ref. Spec §6.2 — `akm show` queries this and
@@ -1208,70 +1679,11 @@ function mergeLegacyEntry(entry, legacyEntries) {
  * file corresponds to which ref; the indexer walks `provider.path()` for
  * every configured source, so this query covers all source kinds.
  *
- * Match rules:
- *   - `ref.origin === undefined` → first match across all sources (primary
- *     source first, then in declared order — same priority as the indexer's
- *     write order).
- *   - `ref.origin === "local"`   → primary source only (entry_key prefix is
- *     the primary stash dir).
- *   - `ref.origin === <name>`    → restrict to the matching source name. We
- *     resolve the source's directory and match on `entry_key` prefix.
- *
  * Returns `null` when no row matches — callers translate that into a
  * `NotFoundError` with their own messaging.
  */
 export async function lookup(ref) {
-    const { loadConfig } = await import("../core/config/config.js");
-    const { resolveSourceEntries } = await import("./search/search-source.js");
-    const config = loadConfig();
-    const sources = resolveSourceEntries(undefined, config);
-    if (sources.length === 0)
-        return null;
-    const dbPath = getDbPath();
-    const db = openExistingDatabase(dbPath);
-    try {
-        const escapeLike = (value) => value.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
-        // Canonical names strip .md for markdown assets, but users often pass
-        // refs with .md (e.g. command:release.md). Normalize by trying both.
-        const nameVariants = [ref.name];
-        if (ref.name.endsWith(".md")) {
-            nameVariants.push(ref.name.slice(0, -3));
-        }
-        const candidateDirs = (() => {
-            if (!ref.origin)
-                return sources.map((s) => s.path);
-            if (ref.origin === "local")
-                return [sources[0].path];
-            const named = sources.find((s) => s.registryId === ref.origin);
-            return named ? [named.path] : [];
-        })();
-        if (candidateDirs.length === 0)
-            return null;
-        for (const name of nameVariants) {
-            const suffix = `:${ref.type}:${name}`;
-            const escapedSuffix = escapeLike(suffix);
-            for (const dir of candidateDirs) {
-                const escapedDir = escapeLike(dir);
-                const row = db
-                    .prepare("SELECT entry_key AS entryKey, file_path AS filePath, stash_dir AS stashDir, entry_type AS type FROM entries " +
-                    "WHERE entry_key LIKE ? ESCAPE '\\' AND entry_type = ? LIMIT 1")
-                    .get(`${escapedDir}${escapedSuffix}`, ref.type);
-                if (row) {
-                    return {
-                        entryKey: row.entryKey,
-                        filePath: row.filePath,
-                        stashDir: row.stashDir,
-                        type: row.type,
-                        name: ref.name,
-                    };
-                }
-            }
-        }
-        return null;
-    }
-    finally {
-        closeDatabase(db);
-    }
+    return lookupBundleRef({ bundle: ref.origin, conceptId: conceptIdFromTypeName(ref.type, ref.name) });
 }
 // ── Utility score recomputation ──────────────────────────────────────────────
 /** Retention window for usage events: events older than this are purged. */
@@ -1292,12 +1704,11 @@ const USAGE_EVENT_RETENTION_DAYS = 90;
  *
  * Called during `akm index` after FTS rebuild.
  */
-export function recomputeUtilityScores(db) {
+export function recomputeUtilityScores(db, stateDb) {
     const EMA_DECAY = 0.7;
-    // Ensure usage_events table exists before querying
-    ensureUsageEventsSchema(db);
-    // Purge stale usage events (90-day retention)
-    purgeOldUsageEvents(db, USAGE_EVENT_RETENTION_DAYS);
+    // Purge stale usage events (90-day retention). usage_events lives in state.db
+    // (Chunk-8 WI-8.3); its table is created by state migration 020.
+    purgeOldUsageEvents(stateDb, USAGE_EVENT_RETENTION_DAYS);
     // Time-proportional decay: apply one round of EMA per elapsed day so
     // indexing frequency doesn't affect how fast scores decay.
     const lastComputedAt = getMeta(db, "last_utility_computed_at");
@@ -1308,15 +1719,14 @@ export function recomputeUtilityScores(db) {
     }
     const emaDecay = EMA_DECAY ** elapsedDays;
     const emaNew = 1 - emaDecay; // complement so weights still sum to 1
-    // Single aggregate query instead of N+1 per-entry queries.
-    // Only processes entries that actually have usage events AND still exist
-    // in `entries`. The latter check is critical: usage_events has no FK to
-    // entries, so its entry_id can become stale (entry deleted, re-keyed,
-    // moved between sources). Without the JOIN, writing the derived row to
-    // utility_scores (which DOES have an FK) raises "FOREIGN KEY constraint
-    // failed" and rolls back the whole finalize transaction — failing every
-    // index run.
-    const usageRows = db
+    // Aggregate explicit user demand per entry_id from state.db's usage_events, then keep only entries
+    // that STILL EXIST in index.db's `entries` (the former in-SQL JOIN is now a
+    // cross-DB filter). This latter check is critical: usage_events has no FK to
+    // entries, so its entry_id can become stale (entry deleted, re-keyed, moved
+    // between sources). Without it, writing the derived row to utility_scores
+    // (which DOES have an FK) raises "FOREIGN KEY constraint failed" and rolls
+    // back the whole finalize transaction — failing every index run.
+    const aggregatedRows = stateDb
         .prepare(`
       SELECT u.entry_id,
              SUM(CASE WHEN u.event_type = 'search' THEN 1 ELSE 0 END) AS search_count,
@@ -1325,15 +1735,13 @@ export function recomputeUtilityScores(db) {
              SUM(CASE WHEN u.event_type = 'feedback' AND u.signal = 'negative' THEN 1 ELSE 0 END) AS negative_feedback_count,
              MAX(u.created_at) AS last_used_at
       FROM usage_events u
-      JOIN entries e ON e.id = u.entry_id
       WHERE u.entry_id IS NOT NULL
+        AND u.source = 'user'
       GROUP BY u.entry_id
     `)
         .all();
-    if (usageRows.length === 0) {
-        setMeta(db, "last_utility_computed_at", new Date().toISOString());
-        return;
-    }
+    const entryExists = db.prepare("SELECT 1 FROM entries WHERE id = ?");
+    const usageByEntry = new Map(aggregatedRows.filter((row) => entryExists.get(row.entry_id) != null).map((row) => [row.entry_id, row]));
     // Batch-load existing utility scores
     const existingScores = new Map();
     const scoreRows = db.prepare("SELECT entry_id, utility, last_used_at FROM utility_scores").all();
@@ -1341,7 +1749,16 @@ export function recomputeUtilityScores(db) {
         existingScores.set(row.entry_id, { utility: row.utility, lastUsedAt: row.last_used_at ?? undefined });
     }
     const now = new Date().toISOString();
-    for (const row of usageRows) {
+    const entryIds = new Set([...existingScores.keys(), ...usageByEntry.keys()]);
+    for (const entryId of entryIds) {
+        const row = usageByEntry.get(entryId) ?? {
+            entry_id: entryId,
+            search_count: 0,
+            show_count: 0,
+            positive_feedback_count: 0,
+            negative_feedback_count: 0,
+            last_used_at: null,
+        };
         const selectRate = row.search_count > 0 ? Math.min(1, row.show_count / row.search_count) : 0;
         const feedbackTotal = row.positive_feedback_count + row.negative_feedback_count;
         const feedbackRate = feedbackTotal > 0 ? Math.max(0, row.positive_feedback_count - row.negative_feedback_count) / feedbackTotal : 0;