akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/indexer/indexer.js

@@ -3,22 +3,23 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
+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 { recoverTxnsForRoot } from "../core/fs-txn.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 { deleteEntriesByDirExceptKeys, deleteEntriesByIds, deleteEntriesByStashDir, getEmbeddableEntryCount, getEntryCount, relinkUsageEvents, upsertEntry, upsertWorkflowDocument, } from "../storage/repositories/index-entries-repository.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 { deleteIndexDirStatesByStashDir, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-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 { getAllEntriesForEmbedding, getEmbeddingCount, isVecAvailable, isVecFastPathReady, purgeEmbeddings, setVecFastPathReady, upsertEmbedding, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
 import { takeWorkflowDocument } from "../workflows/runtime/document-cache.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
 import { withIndexWriterLease } from "./index-writer-lock.js";
@@ -29,7 +30,7 @@ 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 { purgeOldUsageEvents } from "./usage/usage-events.js";
-import { walkStashFlat } from "./walk/walker.js";
+import { walkStashFlatWithStatus } from "./walk/walker.js";
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw signal.reason instanceof Error ? signal.reason : new Error("index interrupted");
@@ -54,7 +55,11 @@ export function getDefaultLlmConcurrency(llmConfig) {
     // 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). `llm.concurrency` in config.json overrides both.
+    // 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 ──────────────────────────────────────────────────────────
@@ -86,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);
                 }
             }
         }
@@ -97,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.
@@ -105,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}.`,
@@ -135,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)
@@ -193,15 +206,19 @@ async function runFinalizePhase(ctx) {
         /* ignore */
     }
     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);
+    const bodyOpeningWarning = reconcileBodyOpeningIndexState(db, config.index?.indexBodyOpening === true, (ctx.full || !isIncremental) && ctx.scanComplete);
     if (bodyOpeningWarning)
         warn(bodyOpeningWarning);
     warnIfVecMissing(db);
@@ -264,7 +281,7 @@ export function reconcileBodyOpeningIndexState(db, flagEnabled, isFullWalk) {
         `${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 " +
-        "`akm improve canary --refresh` if you use them.");
+        "`bun scripts/refresh-canary-set.ts --refresh` if you use them.");
 }
 // ── Clean pass ───────────────────────────────────────────────────────────────
 /**
@@ -302,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({
@@ -321,33 +413,41 @@ async function akmIndexReal(options) {
         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();
+        // Durable state must be runtime-compatible before source hydration,
+        // adapter persistence, or index.db creation can mutate the installation.
+        onProgress({ phase: "preflight", message: "Validating durable state." });
+        withStateDb(() => undefined);
         // 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, materialize: options.hydrateSources !== false });
+        // Inject the store-backed secret resolver from here — a composition root
+        // ABOVE the provider/fetcher import cycle (this module reaches
+        // search-source only via dynamic import). This is what lets a website
+        // source's X fetcher resolve `secrets/x-bearer-token` during
+        // bundle-update / hydrate, not just from the command-layer URL-ingest
+        // path. `secret-seam` is imported here, never from inside the cycle.
+        const { storeSecretResolver } = await import("../sources/snapshot-fetchers/secret-seam.js");
+        await ensureSourceCaches(config, {
+            force: full,
+            materialize: options.hydrateSources !== false,
+            secrets: storeSecretResolver,
+        });
         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);
-        for (const sourceDir of new Set([stashDir, ...allSourceDirs])) {
-            // Unified fs-txn engine (WI-6.3): finish/roll back interrupted mv
-            // transactions for every source root before indexing walks it.
-            await recoverTxnsForRoot(sourceDir, (journal) => journal.kind === "mv");
-        }
         onProgress({
             phase: "preflight",
             message: `Resolved ${allSourceDirs.length} stash source${allSourceDirs.length === 1 ? "" : "s"}.`,
@@ -370,7 +470,7 @@ async function akmIndexReal(options) {
                 sources: allSourceEntries,
                 sourceDirs: allSourceDirs,
                 full,
-                reEnrich,
+                clean,
                 stashDir,
                 onProgress,
                 signal,
@@ -387,6 +487,8 @@ async function akmIndexReal(options) {
                 isIncremental,
                 builtAtMs,
                 hadRemovedSources: false,
+                removedSourceDirs: [],
+                scanComplete: true,
                 scannedDirs: 0,
                 skippedDirs: 0,
                 generatedCount: 0,
@@ -408,6 +510,7 @@ async function akmIndexReal(options) {
             // ── Phase sequence ───────────────────────────────────────────────────────
             await runSourceCachePhase(ctx);
             await runWalkPhase(ctx);
+            applyRemovedSources(ctx);
             await runEmbeddingPhase(ctx);
             await runFinalizePhase(ctx);
             // ────────────────────────────────────────────────────────────────────────
@@ -425,7 +528,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();
             // ────────────────────────────────────────────────────────────────────────
@@ -438,6 +547,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,
@@ -460,6 +572,13 @@ 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
@@ -478,6 +597,134 @@ function buildComponentBySource(sources) {
     });
     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
@@ -488,24 +735,20 @@ function buildComponentBySource(sources) {
  * 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 componentBySource = buildComponentBySource(allSourceEntries);
+    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;
@@ -514,10 +757,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 for the per-source scan. 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)) {
@@ -532,9 +772,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, hashByFile, conceptIdByFile) => {
-        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,
@@ -543,6 +783,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;
@@ -560,46 +801,44 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
             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"}.`);
-        // Group by parent dir, keeping the FileContexts so the drain can hand each
-        // to the component's dispatched `adapter.recognize` (F4a M-core-2). The
-        // freshness gate still keys on the plain path list derived from these.
-        const dirGroups = new Map();
-        for (const ctx of fileContexts) {
-            const dir = ctx.parentDirAbs;
-            const group = dirGroups.get(dir);
-            if (group)
-                group.push(ctx);
-            else
-                dirGroups.set(dir, [ctx]);
+        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 component = componentBySource.get(currentStashDir) ?? {
-            id: currentStashDir,
-            adapter: "akm",
-            root: currentStashDir,
-            writable: false,
-        };
         // 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).
-        const adapter = adapterForId(component.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, 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) {
@@ -609,7 +848,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({
@@ -619,6 +860,7 @@ 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;
@@ -639,10 +881,27 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
             if (generated.entries.length > 0) {
                 generatedCount += generated.entries.length;
             }
-            recordFreshnessDecision(dirPath, currentStashDir, staleFiles, stash, drained.hashByFile, drained.conceptIdByFile);
+            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"
@@ -671,8 +930,9 @@ function allSourceRootsReadable(roots) {
  * 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, sourceRoots, bundleByRoot) {
+function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots, scanComplete, bundleByRoot) {
     const dirsNeedingLlm = [];
+    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
@@ -681,25 +941,19 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
     // 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 (doFullDelete) {
-        const incomingDocCount = dirRecords.reduce((n, r) => n + (r.skip ? 0 : (r.stash?.entries.length ?? 0)), 0);
-        if (incomingDocCount === 0 && !allSourceRootsReadable(sourceRoots)) {
-            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 { dirsNeedingLlm };
-        }
-    }
-    // Cross-stash dedup: track indexed assets by type + entry.name so a
-    // lower-priority stash row with the same logical index identity is skipped
-    // when a higher-priority root already covers it.
-    // Sources are ordered by priority (primary stash first), so the first
-    // occurrence wins.
+    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");
             }
@@ -723,10 +977,16 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
             // re-resolves the rest by entry_ref — subsuming the old detach.
             db.exec("DELETE FROM entries");
         }
-        for (const { dirPath, currentStashDir, files, stash, skip, reason, hashByFile, conceptIdByFile } 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,
@@ -745,36 +1005,39 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
             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;
                     }
-                    // Skip if a higher-priority stash root already indexed this asset
-                    const identityKey = `${entry.type}\0${entry.name}`;
+                    const adapterConceptId = conceptIdByFile?.get(entryPath);
+                    if (!adapterConceptId) {
+                        warn(`Skipping entry without adapter-owned concept identity: ${entryPath}`);
+                        continue;
+                    }
+                    // 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);
                     // content_hash = doc.hash from the drain, keyed by the recognized
-                    // file's path (stable across the legacy-sidecar merge). NULL preserves
-                    // any existing hash (upsert COALESCE) for sidecar-only entries.
+                    // file's path. A missing hash preserves the existing value on upsert.
                     const contentHash = hashByFile?.get(entryPath);
-                    // Chunk-5 Step 2 (spec §14.4): derive the durable bundle identity
-                    // (the D-R2 qualified conceptId + `<bundle>//<conceptId>` item_ref) via
-                    // the shared helper that the write-path fast path also uses. NULL
-                    // provenance when the source root has no bundle mapping (e.g. write-back
-                    // paths) — healed on next index.
-                    const bundle = bundleByRoot?.get(path.resolve(currentStashDir));
-                    const provenance = bundle
-                        ? deriveEntryProvenance(bundle, entry.type, entry.name, conceptIdByFile?.get(entryPath))
-                        : undefined;
+                    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") {
@@ -785,8 +1048,7 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
                     }
                 }
                 // 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 });
                 }
@@ -795,8 +1057,10 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
             // (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.
-            deleteEntriesByDirExceptKeys(db, dirPath, keptEntryKeys);
-            const fingerprint = computeDirFingerprint(dirPath, files);
+            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"
@@ -827,12 +1091,13 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
         }
     });
     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.
     // Source roots feed the #624-P1 zero-document preflight (a full-rebuild wipe
     // is suppressed when the scan is empty because roots are unreadable).
@@ -855,10 +1120,26 @@ async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadR
             adapterId: component?.adapter ?? "akm",
         });
     });
-    const { dirsNeedingLlm } = persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots, bundleByRoot);
-    return { scannedDirs, skippedDirs, generatedCount, warnings, dirsNeedingLlm };
+    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)
@@ -874,17 +1155,18 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
     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.
+    // 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 = (() => {
@@ -933,14 +1215,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;
                 }
@@ -959,7 +1240,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?.({
@@ -980,7 +1261,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++;
@@ -996,7 +1278,8 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
         }, 
         // 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). `llm.concurrency` overrides.
+        // "Model reloaded" / 500 errors). No config override reaches this path:
+        // `resolveLlmEngineUse` does not forward `engines.<name>.concurrency`.
         getDefaultLlmConcurrency(llmConfig));
     }
     finally {
@@ -1004,7 +1287,7 @@ 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.");
     }
     // Gate-closed (`skipped`) entries are not failures — exclude them so a
     // deliberately disabled feature never surfaces as an enrichment error.
@@ -1186,12 +1469,23 @@ function verifyIndexState(db, config, embeddableEntries, embeddingResult) {
         };
     }
     if (embeddingCount >= embeddableEntries) {
+        // "ready-vec" must reflect the path search will ACTUALLY take: the vec
+        // extension being loaded is not enough when the embedding phase recorded
+        // fast-path insert failures (searchVec then routes to the JS-cosine
+        // fallback via isVecFastPathReady). Reporting vec health from
+        // isVecAvailable alone overstated `akm info` after partial vec failures
+        // (§24.2 "Semantic" gate — truthful ready-vec).
+        const vecActive = vecAvailable && isVecFastPathReady(db);
         return {
             ok: true,
-            message: `Semantic search ready (${embeddingCount}/${embeddableEntries} embeddings, ${vecAvailable ? "sqlite-vec active" : "JS fallback active"}).`,
+            message: `Semantic search ready (${embeddingCount}/${embeddableEntries} embeddings, ${vecActive
+                ? "sqlite-vec active"
+                : vecAvailable
+                    ? "JS fallback active — vec fast path degraded, run 'akm index --full' to restore"
+                    : "JS fallback active"}).`,
             semanticSearchEnabled: true,
             semanticSearchMode: config.semanticSearchMode,
-            semanticStatus: vecAvailable ? "ready-vec" : "ready-js",
+            semanticStatus: vecActive ? "ready-vec" : "ready-js",
             embeddingProvider,
             entryCount: embeddableEntries,
             embeddingCount,
@@ -1220,18 +1514,14 @@ function buildIndexedDirCandidate(dirPath, indexableFiles, generated) {
     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("../storage/repositories/index-llm-cache-repository.js");
     const results = await concurrentMap(stash.entries, async (entry, idx) => {
@@ -1251,13 +1541,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 {
@@ -1337,8 +1627,8 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db,
             return entry;
         }
     }, 
-    // Defaults: 2 for remote LLM APIs, 1 for local model servers.
-    // `llm.concurrency` in config.json overrides.
+    // 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
@@ -1346,41 +1636,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;
+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 };
+}
+/** 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);
     }
-    return null;
 }
 /**
  * Look up a single asset by ref. Spec §6.2 — `akm show` queries this and
@@ -1388,70 +1705,11 @@ export function matchEntryToFile(entryName, fileMap) {
  * 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. */