akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/indexer/indexer.js

@@ -7,32 +7,47 @@ 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 { ConfigError } from "../core/errors.js";
 import { isLoopbackEndpoint } from "../core/loopback.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.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 { disposeLoweredExecutionDispatchLease, } from "../integrations/agent/execution-lowering.js";
+import { isLlmFeatureEnabled } from "../llm/feature-gate.js";
+import { resolveIndexPassExecution } from "../llm/index-passes.js";
+import { preflightStructuredLlmRunner } from "../llm/structured-call.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, deleteMeta, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
+import { closeDatabase, openExistingDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
+import { deleteAllEntries, deleteEntriesByBundle, deleteEntriesByDirAndBundle, deleteEntriesByDirExceptRefs, deleteEntriesByIds, deleteUsageEventsByEntryIds, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedBundleIdsByDir, getIndexedDirPathsByBundleId, relinkUsageEvents, upsertEntry, } from "../storage/repositories/index-entries-repository.js";
+import { clearStaleCacheEntries, computeBodyHash, getLlmCacheEntry, } from "../storage/repositories/index-llm-cache-repository.js";
+import { deleteIndexDirState, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
 import { upsertUtilityScore } from "../storage/repositories/index-utility-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 { getEmbeddingCount, isVecAvailable, isVecFastPathReady, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
+import { assertIndexedWorkflowSourceIdentity, WorkflowSourceIdentityError } from "../workflows/source-files.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
 import { withIndexWriterLease } from "./index-writer-lock.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
+import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
+import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
 import { canUseIncrementalSkip, computeDirFingerprint, getCachedZeroRowDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.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 { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus } from "./search/semantic-status.js";
 import { purgeOldUsageEvents } from "./usage/usage-events.js";
 import { walkStashFlatWithStatus } from "./walk/walker.js";
+function collectLoweringNotices(target, notices) {
+    const keys = new Set(target.map((notice) => JSON.stringify(notice)));
+    for (const notice of notices) {
+        const key = JSON.stringify(notice);
+        if (keys.has(key))
+            continue;
+        keys.add(key);
+        target.push(notice);
+    }
+}
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw signal.reason instanceof Error ? signal.reason : new Error("index interrupted");
@@ -56,51 +71,67 @@ export function getDefaultLlmConcurrency(llmConfig) {
     // auto-derived 1/2 is what runs (see docs/architecture/internals/indexing.md).
     return 2;
 }
-// ── Phase functions ──────────────────────────────────────────────────────────
+function sourceOwners(sources) {
+    const installations = deriveInstallations([...sources]);
+    return sources.flatMap((source, index) => {
+        const installation = installations[index];
+        return installation ? [{ bundleId: installation.id, sourceRoot: path.resolve(source.path) }] : [];
+    });
+}
+function parseStoredSourceOwners(raw) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed) ||
+            parsed.some((owner) => typeof owner !== "object" ||
+                owner === null ||
+                typeof owner.bundleId !== "string" ||
+                typeof owner.sourceRoot !== "string")) {
+            warn("index_meta sourceOwners value is invalid — treating as empty");
+            return [];
+        }
+        return parsed.map((owner) => {
+            const stored = owner;
+            return { bundleId: stored.bundleId, sourceRoot: path.resolve(stored.sourceRoot) };
+        });
+    }
+    catch {
+        warn("index_meta sourceOwners value is corrupt JSON — treating as empty");
+        return [];
+    }
+}
 /**
  * Source cache phase: ensure git stash caches are up to date and purge orphaned
  * entries from removed sources (incremental only).
  */
 async function runSourceCachePhase(ctx) {
-    const { db, config, sourceDirs, isIncremental, full } = ctx;
+    const { db, isIncremental, full, sources } = ctx;
     if (isIncremental && !full) {
-        // Purge entries from stash dirs that have been removed since the last run
-        // (e.g. after `akm remove`) so orphaned entries don't linger.
-        const prevStashDirsJson = getMeta(db, "stashDirs");
-        if (prevStashDirsJson) {
-            let prevStashDirs = [];
-            try {
-                const parsed = JSON.parse(prevStashDirsJson);
-                if (Array.isArray(parsed)) {
-                    prevStashDirs = parsed.filter((d) => typeof d === "string");
-                }
-                else {
-                    warn("index_meta stashDirs value is not an array — treating as empty");
-                }
-            }
-            catch {
-                warn("index_meta stashDirs value is corrupt JSON — treating as empty");
-            }
-            const currentSet = new Set(sourceDirs);
-            for (const dir of prevStashDirs) {
-                if (!currentSet.has(dir)) {
-                    ctx.hadRemovedSources = true;
-                    ctx.removedSourceDirs.push(dir);
-                }
+        const currentByBundle = new Map(sourceOwners(sources).map((owner) => [owner.bundleId, owner]));
+        for (const previous of parseStoredSourceOwners(getMeta(db, "sourceOwners"))) {
+            const current = currentByBundle.get(previous.bundleId);
+            if (!current || current.sourceRoot !== previous.sourceRoot) {
+                ctx.hadRemovedSources = true;
+                ctx.removedSources.push({
+                    ...previous,
+                    removeBundleEntries: current === undefined,
+                });
             }
         }
     }
     // Source caches are hydrated before akmIndex() calls this phase; nothing
     // 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);
+    const currentRoots = new Set(sourceOwners(ctx.sources).map((owner) => owner.sourceRoot));
+    for (const removed of ctx.removedSources) {
+        if (removed.removeBundleEntries)
+            deleteEntriesByBundle(ctx.db, removed.bundleId);
+        if (!currentRoots.has(removed.sourceRoot))
+            deleteStoredGraph(ctx.db, removed.sourceRoot);
     }
 }
 /**
@@ -115,7 +146,14 @@ async function runWalkPhase(ctx) {
     throwIfAborted(signal);
     ctx.timing.tWalkStart = Date.now();
     const doFullDelete = full || !isIncremental;
-    const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings, complete } = await indexEntries(db, sources, isIncremental, builtAtMs, hadRemovedSources, doFullDelete, onProgress, !clean);
+    const { scannedDirs, skippedDirs, generatedCount, dirsNeedingLlm, warnings, complete } = await indexEntries(db, sources, isIncremental, builtAtMs, hadRemovedSources, doFullDelete, onProgress, !clean, async (dirRecords, ownersByRoot) => {
+        const runner = ctx.enrichmentExecution.runner;
+        if (runner &&
+            isLlmFeatureEnabled(config, "metadata_enhance") &&
+            dirRecordsNeedMetadataDispatch(db, dirRecords, ownersByRoot)) {
+            ctx.enrichmentLease = await preflightStructuredLlmRunner(runner);
+        }
+    });
     ctx.scannedDirs = scannedDirs;
     ctx.skippedDirs = skippedDirs;
     ctx.generatedCount = generatedCount;
@@ -142,10 +180,10 @@ 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);
+    await enhanceDirsWithLlm(db, config, ctx.enrichmentExecution, dirsNeedingLlm, onProgress, signal, (notices) => collectLoweringNotices(ctx.loweringNotices, notices), ctx.enrichmentLease);
     onProgress({
         phase: "llm",
-        message: resolveIndexPassLLM("enrichment", config)
+        message: ctx.enrichmentExecution.runner
             ? `LLM enhancement reviewed ${dirsNeedingLlm.length} ${dirsNeedingLlm.length === 1 ? "directory" : "directories"}.`
             : "LLM enhancement disabled.",
     });
@@ -167,35 +205,41 @@ async function runEmbeddingPhase(ctx) {
     ctx.timing.tEmbedEnd = Date.now();
 }
 /**
- * Finalize phase: rebuild FTS, re-link usage events, recompute utility scores,
- * regenerate wiki indexes, update index metadata, and emit the verify event.
+ * Finalize phase: confirm transactionally materialized FTS state, re-link
+ * usage events, recompute utility scores, update index metadata, and emit the
+ * verify event.
  */
-async function runFinalizePhase(ctx) {
+async function runFinalizePhase(ctx, deferredUpdateTransaction) {
     const { db, config, sources, sourceDirs, isIncremental, stashDir, signal, onProgress } = ctx;
     ctx.timing.tFinalizeStart = Date.now();
-    // Rebuild FTS after all inserts. Use incremental mode when this whole
-    // index run is incremental — only entries touched by `upsertEntry`
-    // since the last rebuild are re-indexed.
-    rebuildFts(db, { incremental: isIncremental });
+    // `upsertEntry` and every canonical delete own their FTS projection. This is
+    // an observation point, not a second materialization pass.
     onProgress({
         phase: "fts",
-        message: isIncremental ? "Rebuilt full-text search index (dirty rows only)." : "Rebuilt full-text search index.",
+        message: "Full-text search index is current.",
     });
     ctx.timing.tFtsEnd = Date.now();
-    // 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) => {
+    // Re-link state.db usage events to the regenerated index and recompute the
+    // derived utility cache. Stored refs already use the current item-ref grammar,
+    // so this idempotent pass only restores derived entry ids.
+    const mutateState = (stateDb, stateSchema) => {
         onProgress({ phase: "finalize", message: "Relinking usage events." });
-        relinkUsageEvents(db, stateDb, { sources, defaultStashDir: stashDir });
+        relinkUsageEvents(db, stateDb, { sources, defaultStashDir: stashDir, stateSchema });
         onProgress({ phase: "finalize", message: "Recomputing utility scores." });
-        recomputeUtilityScores(db, stateDb);
-    });
+        recomputeUtilityScores(db, stateDb, { stateSchema });
+    };
+    if (deferredUpdateTransaction) {
+        if (deferredUpdateTransaction.db !== db || !db.inTransaction) {
+            throw new Error("Source update index finalization requires its borrowed unified transaction.");
+        }
+        // state.db is ATTACHed to this same index connection before the outer
+        // BEGIN IMMEDIATE. Index and state mutations therefore share one SQLite
+        // commit/rollback decision rather than an unsafe two-connection ordering.
+        mutateState(db, deferredUpdateTransaction.stateSchema);
+    }
+    else {
+        withStateDb(mutateState);
+    }
     // Purge LLM cache entries for assets that no longer exist in the index.
     try {
         onProgress({ phase: "finalize", message: "Clearing stale LLM cache entries." });
@@ -213,22 +257,19 @@ async function runFinalizePhase(ctx) {
         setMeta(db, "builtAt", new Date().toISOString());
         setMeta(db, "stashDir", stashDir);
         setMeta(db, "stashDirs", JSON.stringify(sourceDirs));
+        setMeta(db, "sourceOwners", JSON.stringify(sourceOwners(sources)));
     }
     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);
     onProgress({ phase: "finalize", message: "Verifying semantic search state." });
     const verification = verifyIndexState(db, config, semanticEntryCount, embeddingResult);
-    if (config.semanticSearchMode === "off") {
-        clearSemanticStatus();
-    }
-    else {
+    const persistSemanticStatus = () => {
+        if (config.semanticSearchMode === "off") {
+            clearSemanticStatus();
+            return;
+        }
         writeSemanticStatus({
             status: verification.semanticStatus === "disabled" ? "pending" : verification.semanticStatus,
             ...(embeddingResult.reason ? { reason: embeddingResult.reason } : {}),
@@ -238,6 +279,12 @@ async function runFinalizePhase(ctx) {
             entryCount: verification.entryCount,
             embeddingCount: verification.embeddingCount,
         });
+    };
+    if (deferredUpdateTransaction) {
+        deferredUpdateTransaction.afterCommit = persistSemanticStatus;
+    }
+    else {
+        persistSemanticStatus();
     }
     onProgress({ phase: "verify", message: verification.message });
     // Store verification result and totalEntries on ctx for the caller to use
@@ -247,45 +294,10 @@ 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
- * no longer exists on disk and remove them (unless `dryRun` is true).
+ * Missing-file reconciliation: scan the `entries` table for rows whose source
+ * file no longer exists on disk and remove them (unless `dryRun` is true).
  *
  * Only rows with a non-empty `file_path` are checked — remote/virtual entries
  * that have no local path are always skipped.
@@ -299,7 +311,7 @@ export function reconcileBodyOpeningIndexState(db, flagEnabled, isFullWalk) {
  * reported instead.
  */
 function runCleanPass(db, dryRun) {
-    const allEntries = db.prepare("SELECT id, entry_key AS ref, file_path AS path FROM entries").all();
+    const allEntries = db.prepare("SELECT id, item_ref AS ref, file_path AS path FROM entries").all();
     // Only check entries that have a non-empty local path (skip remote/virtual).
     const localEntries = allEntries.filter((e) => typeof e.path === "string" && e.path.trim() !== "");
     const missing = [];
@@ -335,9 +347,23 @@ export function _setAkmIndexForTests(fake) {
     akmIndexOverride = fake;
 }
 export async function akmIndex(options) {
-    if (akmIndexOverride)
-        return akmIndexOverride(options);
-    return akmIndexReal(options);
+    try {
+        const override = akmIndexOverride;
+        return override ? await override(options) : await akmIndexReal(options);
+    }
+    catch (error) {
+        const updateDb = options.deferredUpdateTransaction?.db;
+        if (updateDb?.inTransaction) {
+            try {
+                updateDb.exec("ROLLBACK");
+            }
+            catch {
+                // Preserve the indexing error. The update coordinator will retry
+                // rollback before closing its borrowed unified handle.
+            }
+        }
+        throw error;
+    }
 }
 let indexTransactionHookForTests;
 /**
@@ -385,7 +411,7 @@ function detectAndPersistBundleAdapters(allSourceEntries, config, mutateConfig,
         }
     }
     const persistedAdapters = {};
-    if (detectedByBundle.size === 0)
+    if (detectedByBundle.size === 0 || !opts.persist)
         return { config, persistedAdapters };
     const nextConfig = mutateConfig((current) => {
         if (!current.bundles)
@@ -418,6 +444,38 @@ function detectAndPersistBundleAdapters(allSourceEntries, config, mutateConfig,
     }
     return { config: nextConfig, persistedAdapters };
 }
+function createIndexRunContext(options) {
+    const prevStashDir = getMeta(options.db, "stashDir");
+    const prevBuiltAt = getMeta(options.db, "builtAt");
+    const isIncremental = !options.full && prevStashDir === options.stashDir && !!prevBuiltAt;
+    const builtAtMs = isIncremental && prevBuiltAt ? new Date(prevBuiltAt).getTime() : 0;
+    const { t0, ...context } = options;
+    return {
+        ...context,
+        loweringNotices: [...options.enrichmentExecution.notices],
+        timing: {
+            t0,
+            tWalkStart: t0,
+            tWalkEnd: t0,
+            tLlmEnd: t0,
+            tFtsEnd: t0,
+            tEmbedEnd: t0,
+            tFinalizeStart: t0,
+            tFinalizeEnd: t0,
+        },
+        isIncremental,
+        builtAtMs,
+        hadRemovedSources: false,
+        removedSources: [],
+        scanComplete: true,
+        scannedDirs: 0,
+        skippedDirs: 0,
+        generatedCount: 0,
+        walkWarnings: [],
+        dirsNeedingLlm: [],
+        embeddingResult: null,
+    };
+}
 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,
@@ -460,7 +518,8 @@ async function akmIndexReal(options) {
         // 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);
+        if (!options.deferredUpdateTransaction)
+            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();
@@ -482,6 +541,7 @@ async function akmIndexReal(options) {
         const allSourceEntries = resolveSourceEntries(stashDir, config);
         const detected = detectAndPersistBundleAdapters(allSourceEntries, config, mutateConfig, {
             announce: options.implicit !== true,
+            persist: options.persistDetectedAdapters !== false,
         });
         config = detected.config;
         const persistedAdapters = detected.persistedAdapters;
@@ -491,20 +551,22 @@ async function akmIndexReal(options) {
             message: `Resolved ${allSourceDirs.length} stash source${allSourceDirs.length === 1 ? "" : "s"}.`,
         });
         const t0 = Date.now();
+        const enrichmentExecution = resolveIndexPassExecution("enrichment", config);
         // Open database — pass embedding dimension from config if available
         const dbPath = getDbPath();
         const embeddingDim = config.embedding?.dimension;
-        const db = openIndexDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
+        const borrowedUpdateDb = options.deferredUpdateTransaction?.db;
+        const db = borrowedUpdateDb ?? openIndexDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
+        if (borrowedUpdateDb && !borrowedUpdateDb.inTransaction) {
+            throw new Error("Source update index requires an active borrowed index transaction.");
+        }
+        let indexRunContext;
         try {
-            // Determine incremental vs full mode
-            const prevStashDir = getMeta(db, "stashDir");
-            const prevBuiltAt = getMeta(db, "builtAt");
-            const isIncremental = !full && prevStashDir === stashDir && !!prevBuiltAt;
-            const builtAtMs = isIncremental && prevBuiltAt ? new Date(prevBuiltAt).getTime() : 0;
             // Assemble the run context
-            const ctx = {
+            const ctx = createIndexRunContext({
                 db,
                 config,
+                enrichmentExecution,
                 sources: allSourceEntries,
                 sourceDirs: allSourceDirs,
                 full,
@@ -512,55 +574,31 @@ async function akmIndexReal(options) {
                 stashDir,
                 onProgress,
                 signal,
-                timing: {
-                    t0,
-                    tWalkStart: t0,
-                    tWalkEnd: t0,
-                    tLlmEnd: t0,
-                    tFtsEnd: t0,
-                    tEmbedEnd: t0,
-                    tFinalizeStart: t0,
-                    tFinalizeEnd: t0,
-                },
-                isIncremental,
-                builtAtMs,
-                hadRemovedSources: false,
-                removedSourceDirs: [],
-                scanComplete: true,
-                scannedDirs: 0,
-                skippedDirs: 0,
-                generatedCount: 0,
-                walkWarnings: [],
-                dirsNeedingLlm: [],
-                embeddingResult: null,
-            };
+                t0,
+            });
+            indexRunContext = ctx;
             onProgress({
                 phase: "summary",
                 message: buildIndexSummaryMessage({
-                    mode: isIncremental ? "incremental" : "full",
+                    mode: ctx.isIncremental ? "incremental" : "full",
                     sourcesCount: allSourceDirs.length,
                     semanticSearchMode: config.semanticSearchMode,
                     embeddingProvider: getEmbeddingProvider(config.embedding),
-                    llmEnabled: !!resolveIndexPassLLM("enrichment", config),
+                    llmEnabled: !!enrichmentExecution.runner,
                     vecAvailable: isVecAvailable(db),
                 }),
             });
+            let cleanResult;
+            let cleanStart = Date.now();
+            let cleanEnd = cleanStart;
             // ── Phase sequence ───────────────────────────────────────────────────────
             await runSourceCachePhase(ctx);
             await runWalkPhase(ctx);
             applyRemovedSources(ctx);
-            await runEmbeddingPhase(ctx);
-            await runFinalizePhase(ctx);
-            // ────────────────────────────────────────────────────────────────────────
-            // runFinalizePhase always populates these before returning.
-            const verification = ctx.verification;
-            const totalEntries = ctx.totalEntries;
-            const { timing } = ctx;
-            // ── Clean pass ───────────────────────────────────────────────────────────
-            // After the normal index completes, remove entries whose source files no
-            // longer exist on disk. Remote entries (empty file_path) are skipped.
-            let cleanResult;
-            const cleanStart = Date.now();
+            // Reconcile explicit missing-file cleanup before embeddings, totals, or
+            // verification describe this generation. Dry-run intentionally leaves
+            // the generation unchanged while still returning the previewed refs.
+            cleanStart = Date.now();
             if (clean) {
                 onProgress({
                     phase: "finalize",
@@ -574,17 +612,25 @@ async function akmIndexReal(options) {
                     cleanResult = { checked: 0, removed: 0, removedRefs: [], dryRun };
                 }
             }
-            const cleanEnd = Date.now();
+            cleanEnd = Date.now();
+            await runEmbeddingPhase(ctx);
+            await runFinalizePhase(ctx, options.deferredUpdateTransaction);
             // ────────────────────────────────────────────────────────────────────────
+            // runFinalizePhase always populates these before returning.
+            const verification = ctx.verification;
+            const totalEntries = ctx.totalEntries;
+            const { timing } = ctx;
             return {
                 stashDir,
                 totalEntries,
                 generatedMetadata: ctx.generatedCount,
                 indexPath: dbPath,
-                mode: isIncremental ? "incremental" : "full",
+                mode: ctx.isIncremental ? "incremental" : "full",
                 directoriesScanned: ctx.scannedDirs,
                 directoriesSkipped: ctx.skippedDirs,
+                scanComplete: ctx.scanComplete,
                 ...(ctx.walkWarnings.length > 0 ? { warnings: ctx.walkWarnings } : {}),
+                ...(ctx.loweringNotices.length > 0 ? { notices: Object.freeze([...ctx.loweringNotices]) } : {}),
                 ...(Object.keys(persistedAdapters).length > 0
                     ? { configUpdated: { detectedAdapters: persistedAdapters } }
                     : {}),
@@ -606,10 +652,69 @@ async function akmIndexReal(options) {
             };
         }
         finally {
-            closeDatabase(db);
+            if (indexRunContext?.enrichmentLease) {
+                disposeLoweredExecutionDispatchLease(indexRunContext.enrichmentLease);
+            }
+            if (!borrowedUpdateDb)
+                closeDatabase(db);
         }
     });
 }
+function buildIndexedSourceOwners(sources) {
+    const installations = deriveInstallations([...sources]);
+    const owners = new Map();
+    sources.forEach((source, index) => {
+        const installation = installations[index];
+        if (!installation)
+            return;
+        const component = installation.components[0];
+        owners.set(path.resolve(source.path), {
+            bundleId: installation.id,
+            componentId: component?.id ?? installation.id,
+            adapterId: component?.adapter ?? "akm",
+        });
+    });
+    return owners;
+}
+/** Read-only mirror of the enrichment cache gate used before entry persistence. */
+function dirRecordsNeedMetadataDispatch(db, records, ownersByRoot) {
+    for (const record of records) {
+        if (record.skip || record.remove || !record.stash)
+            continue;
+        const owner = ownersByRoot.get(path.resolve(record.currentStashDir));
+        if (!owner)
+            throw new Error(`Missing bundle provenance for indexed source ${record.currentStashDir}`);
+        for (const entry of record.stash.entries) {
+            if (entry.quality !== "generated" || isEnrichmentComplete(entry))
+                continue;
+            const entryFile = entry.filename ? path.join(record.dirPath, entry.filename) : undefined;
+            if (!entryFile)
+                continue;
+            const adapterConceptId = record.conceptIdByFile?.get(entryFile);
+            if (!adapterConceptId)
+                continue;
+            let fileContent;
+            try {
+                fileContent = fs.readFileSync(entryFile, "utf8");
+            }
+            catch {
+                // The dispatch path uses the same deterministic metadata fallback.
+            }
+            const bodyHash = computeBodyHash(fileContent ?? `${entry.name}\n${entry.description ?? ""}`);
+            const cacheKey = deriveEntryProvenance(owner, entry.type, entry.name, adapterConceptId).itemRef;
+            const cached = getLlmCacheEntry(db, cacheKey, bodyHash);
+            if (!cached)
+                return true;
+            try {
+                JSON.parse(cached.resultJson);
+            }
+            catch {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 function removalsFirst(records) {
     return [...records.filter((record) => record.remove), ...records.filter((record) => !record.remove)];
 }
@@ -654,8 +759,8 @@ function groupFileContextsByDir(fileContexts) {
     }
     return groups;
 }
-function sourceSnapshotRemovals(db, currentStashDir, currentDirs, allIndexedDirsBySource) {
-    const indexedDirs = allIndexedDirsBySource?.get(path.resolve(currentStashDir)) ?? getIndexedDirPathsByStashDir(db, currentStashDir);
+function sourceSnapshotRemovals(db, currentStashDir, bundleId, currentDirs, allIndexedDirsByBundle) {
+    const indexedDirs = allIndexedDirsByBundle?.get(bundleId) ?? getIndexedDirPathsByBundleId(db, bundleId);
     return [...indexedDirs]
         .map((dirPath) => path.resolve(dirPath))
         .filter((dirPath) => !currentDirs.has(dirPath))
@@ -688,6 +793,9 @@ function buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMiss
         }
         const walked = walkStashFlatWithStatus(currentStashDir, {
             includeAllDirectories: component.adapter === "okf",
+            ...(component.adapter === "akm" || component.adapter === "akm-workflow"
+                ? { workflowSymlinkAdapter: component.adapter }
+                : {}),
         });
         const dirGroups = groupFileContextsByDir(walked.files);
         const adapter = adapterForId(component.adapter);
@@ -723,20 +831,19 @@ function buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMiss
     // 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) {
+        const allIndexedDirsByBundle = !isIncremental ? new Map() : undefined;
+        if (allIndexedDirsByBundle) {
             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);
+                const dirs = allIndexedDirsByBundle.get(entry.bundleId) ?? new Set();
+                dirs.add(path.dirname(path.resolve(entry.filePath)));
+                allIndexedDirsByBundle.set(entry.bundleId, 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)) {
+            for (const removal of sourceSnapshotRemovals(db, plan.currentStashDir, plan.component.id, currentDirs, allIndexedDirsByBundle)) {
                 addRemoval(plan, removal.dirPath, removal.currentStashDir);
             }
         }
@@ -748,15 +855,18 @@ function buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMiss
     // 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();
+    const sourcePathByBundle = new Map(plans.map((plan) => [plan.component.id, plan.currentStashDir]));
     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);
+            for (const priorOwnerBundle of getIndexedBundleIdsByDir(db, dirPath)) {
+                if (priorOwnerBundle !== plan.component.id) {
+                    const priorOwnerPath = sourcePathByBundle.get(priorOwnerBundle);
+                    if (priorOwnerPath)
+                        addRemoval(plan, dirPath, priorOwnerPath);
                 }
             }
         }
@@ -876,7 +986,7 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
             // 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));
+            const forceScan = handoffDirs.has(path.resolve(dirPath)) || requiresWorkflowSourcePreflight(ctxs);
             if (markSeenOrSkipDuplicate(dirPath, currentStashDir, indexableFiles))
                 continue;
             if (indexableFiles.length === 0) {
@@ -931,6 +1041,16 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
         complete: plans.every((plan) => plan.walkComplete && plan.adapter !== undefined),
     };
 }
+function requiresWorkflowSourcePreflight(ctxs) {
+    return ctxs.some((ctx) => {
+        try {
+            return fs.lstatSync(ctx.absPath).isSymbolicLink();
+        }
+        catch {
+            return true;
+        }
+    });
+}
 function preserveExistingIndex(doFullDelete, dirRecords, sourceRoots) {
     if (!doFullDelete)
         return false;
@@ -992,36 +1112,28 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
         // transaction so delete and re-insert are atomic — a concurrent reader
         // never observes an empty database between the two operations.
         if (fullDelete) {
-            try {
-                db.exec("DELETE FROM embeddings");
-            }
-            catch {
-                /* ignore */
-            }
-            if (isVecAvailable(db)) {
-                try {
-                    db.exec("DELETE FROM entries_vec");
-                }
-                catch {
-                    /* ignore */
-                }
-            }
-            db.exec("DELETE FROM entries_fts");
-            db.exec("DELETE FROM utility_scores");
+            // Entries and every child materialization share one deletion authority.
+            // Usage events live in state.db and survive so finalize can relink them
+            // to the replacement generation's row ids.
+            deleteAllEntries(db, { cleanupUsageEvents: false });
             db.exec("DELETE FROM index_dir_state");
             // 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");
             // Atomicity observation point: inside the transaction the tables are now
             // empty, but no other connection may observe that. See
             // tests/integration/indexer/reindex-generation-atomicity.test.ts.
             indexTransactionHook("full-delete-applied");
         }
         for (const { dirPath, currentStashDir, files, stash, skip, reason, hashByFile, conceptIdByFile, indexVariant, remove, pruneMissing, } of dirRecords) {
+            const bundle = bundleByRoot.get(path.resolve(currentStashDir));
+            if (!bundle)
+                throw new Error(`Missing bundle provenance for indexed source ${currentStashDir}`);
             if (remove) {
-                const removedIds = deleteEntriesByDirAndStash(db, dirPath, currentStashDir, { cleanupUsageEvents: false });
+                const removedIds = deleteEntriesByDirAndBundle(db, dirPath, bundle.bundleId, {
+                    cleanupUsageEvents: false,
+                });
                 addEntryIds(deletedUsageEntryIds, removedIds);
                 deleteIndexDirState(db, dirPath);
                 continue;
@@ -1041,15 +1153,12 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
             // 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
+            // durable `item_ref`, then prune only the departed rows below. Replaces the old
             // `deleteEntriesByDir` truncate-and-reinsert (which discarded ids).
-            const keptEntryKeys = new Set();
+            const keptItemRefs = 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;
@@ -1070,24 +1179,15 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
                         continue;
                     }
                     indexedAssetIdentities.add(identityKey);
-                    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. 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);
+                    keptItemRefs.add(provenance.itemRef);
+                    upsertEntry(db, entryPath, entryWithSize, searchText, provenance, contentHash);
                     persistedRows++;
-                    if (entry.type === "workflow") {
-                        const doc = takeWorkflowDocument(entry);
-                        if (doc) {
-                            upsertWorkflowDocument(db, entryId, doc, fs.readFileSync(entryPath));
-                        }
-                    }
                 }
                 // Collect dirs needing LLM enhancement during the first walk.
                 // Only dirs with "generated" entries need enrichment.
@@ -1100,7 +1200,7 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
             // 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 }));
+                addEntryIds(deletedUsageEntryIds, deleteEntriesByDirExceptRefs(db, dirPath, bundle.bundleId, keptItemRefs, { cleanupUsageEvents: false }));
             }
             const fingerprint = computeDirFingerprint(dirPath, files, indexVariant);
             const persistedReason = persistedRows === 0
@@ -1139,32 +1239,21 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
     deleteUsageEventsByEntryIds([...deletedUsageEntryIds]);
     return { dirsNeedingLlm };
 }
-async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, doFullDelete = false, onProgress, reconcileMissingDirs = true) {
+async function indexEntries(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, doFullDelete = false, onProgress, reconcileMissingDirs = true, beforePersist) {
     // Phase 1 (async): walk directories and pre-generate all metadata outside the
     // transaction.
     const { dirRecords, scannedDirs, skippedDirs, generatedCount, warnings, complete } = await scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, onProgress, reconcileMissingDirs);
+    const bundleByRoot = buildIndexedSourceOwners(allSourceEntries);
+    await beforePersist?.(dirRecords, bundleByRoot);
     // 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).
     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`
+    // Map each source root → its durable bundle id so the writer can persist
+    // `item_ref = <bundle>//<conceptId>` and canonical component/adapter
+    // provenance. `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 };
 }
@@ -1184,12 +1273,11 @@ function indexedProvenanceForFile(db, filePath) {
         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)
-    const llmConfig = resolveIndexPassLLM("enrichment", config);
-    if (!llmConfig || dirsNeedingLlm.length === 0)
+async function enhanceDirsWithLlm(db, config, execution, dirsNeedingLlm, onProgress, signal, onNotices, lease) {
+    // The invocation owns one frozen symbolic selection. Summary reporting and
+    // every enrichment dispatch consume this same snapshot.
+    const llmRunner = execution.runner;
+    if (!llmRunner || dirsNeedingLlm.length === 0)
         return;
     // Aggregate per-entry failures so a misconfigured LLM endpoint surfaces
     // as a single visible warning instead of silently degrading every entry
@@ -1212,7 +1300,7 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
     // 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);
+    const enrichDeadline = createEnrichmentDeadline(llmRunner.timeoutMs, totalEntries);
     let deadlineHit = false;
     const enrichSignal = (() => {
         if (!enrichDeadline)
@@ -1233,12 +1321,13 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
         onProgress?.({
             phase: "llm",
             message: `LLM enhancement starting for ${totalEntries} entr${totalEntries === 1 ? "y" : "ies"} ` +
-                `across ${totalDirs} director${totalDirs === 1 ? "y" : "ies"} (concurrency ${getDefaultLlmConcurrency(llmConfig)}).`,
+                `across ${totalDirs} director${totalDirs === 1 ? "y" : "ies"} (concurrency ${getDefaultLlmConcurrency(llmRunner.connection)}).`,
             processed: 0,
             total: totalEntries,
         });
     }
     let currentDirLabel;
+    let configFailure;
     let lastProgressAt = Date.now();
     let heartbeatTimer;
     if (totalEntries > 0 && onProgress) {
@@ -1284,30 +1373,42 @@ 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, config, (event) => {
-                completedEntries++;
-                lastProgressAt = Date.now();
-                onProgress?.({
-                    phase: "llm",
-                    message: `Enhanced ${completedEntries}/${totalEntries} entr${totalEntries === 1 ? "y" : "ies"}; ` +
-                        `${completedDirs}/${totalDirs} director${totalDirs === 1 ? "y" : "ies"} complete` +
-                        (event.entryName ? `; current ${event.entryName}` : "") +
-                        (currentDirLabel ? ` in ${currentDirLabel}` : "") +
-                        (event.outcome === "cache-hit" ? " (cache hit)" : ""),
-                    processed: completedEntries,
-                    total: totalEntries,
-                });
+            const itemRefs = entriesToEnhance.map((entry) => {
+                const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
+                return indexedProvenanceForFile(db, entryPath).itemRef;
             });
+            let enhanced;
+            try {
+                enhanced = await enhanceStashWithLlm(llmRunner, targetStash, files, summary, enrichSignal, db, itemRefs, config, (event) => {
+                    completedEntries++;
+                    lastProgressAt = Date.now();
+                    onProgress?.({
+                        phase: "llm",
+                        message: `Enhanced ${completedEntries}/${totalEntries} entr${totalEntries === 1 ? "y" : "ies"}; ` +
+                            `${completedDirs}/${totalDirs} director${totalDirs === 1 ? "y" : "ies"} complete` +
+                            (event.entryName ? `; current ${event.entryName}` : "") +
+                            (currentDirLabel ? ` in ${currentDirLabel}` : "") +
+                            (event.outcome === "cache-hit" ? " (cache hit)" : ""),
+                        processed: completedEntries,
+                        total: totalEntries,
+                    });
+                }, onNotices, lease);
+            }
+            catch (err) {
+                if (err instanceof ConfigError) {
+                    configFailure ??= err;
+                    return undefined;
+                }
+                throw err;
+            }
             // Re-upsert the enhanced entries in a single transaction so a crash
             // cannot leave half the entries updated and the rest stale.
             db.transaction(() => {
                 for (const entry of enhanced.entries) {
                     const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
-                    const entryKey = `${currentStashDir}:${entry.type}:${entry.name}`;
                     const searchText = buildSearchText(entry);
                     const provenance = indexedProvenanceForFile(db, entryPath);
-                    upsertEntry(db, entryKey, dirPath, entryPath, currentStashDir, attachFileSize(entry, entryPath), searchText, provenance);
+                    upsertEntry(db, entryPath, attachFileSize(entry, entryPath), searchText, provenance);
                 }
             })();
             completedDirs++;
@@ -1325,7 +1426,9 @@ async function enhanceDirsWithLlm(db, config, dirsNeedingLlm, onProgress, signal
         // 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));
+        getDefaultLlmConcurrency(llmRunner.connection));
+        if (configFailure)
+            throw configFailure;
     }
     finally {
         if (heartbeatTimer)
@@ -1351,136 +1454,6 @@ 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") {
-        onProgress({ phase: "embeddings", message: "Semantic search disabled; skipping embeddings." });
-        return { success: false, reason: "index-missing", message: "Semantic search is disabled." };
-    }
-    // Detect embedding model/provider changes and purge stale embeddings
-    // so that incremental reindex regenerates all vectors with the new model.
-    const currentFingerprint = deriveSemanticProviderFingerprint(config.embedding);
-    const storedFingerprint = getMeta(db, "embeddingFingerprint");
-    if (storedFingerprint && storedFingerprint !== currentFingerprint) {
-        // Model/provider changed → stored vectors are incompatible. Clear them;
-        // re-embedded by this index run.
-        //
-        // The vec table goes too. "Same dimension, so keep the vec table" only held
-        // for a same-width model swap: entries_vec is a vec0 virtual table declared
-        // at a FIXED width, so after a dimension-changing model change every insert
-        // failed against the old width, and ensureSchema's dim-change rebuild never
-        // fired because it only runs for callers that pass an explicit
-        // embeddingDim. The stale table survived `--full` — the exact remedy the
-        // warning recommended. Clearing the stored dim lets the next ensureSchema
-        // materialize it at the new width; until then the fast-path flag reads
-        // false (no table) and search uses the complete BLOB table.
-        purgeEmbeddings(db, { dropVecTable: true });
-        deleteMeta(db, "embeddingDim");
-    }
-    try {
-        const { embedBatch } = await import("../llm/embedder.js");
-        const { estimateTokenCount } = await import("../llm/embedders/remote.js");
-        throwIfAborted(signal);
-        const allEntries = getAllEntriesForEmbedding(db);
-        if (allEntries.length === 0) {
-            onProgress({ phase: "embeddings", message: "Embeddings already up to date." });
-            setMeta(db, "embeddingFingerprint", currentFingerprint);
-            return { success: true };
-        }
-        onProgress({
-            phase: "embeddings",
-            message: `Generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}.`,
-        });
-        const texts = allEntries.map((e) => e.searchText);
-        // Verbose: log each document before it is sent to the embedding API so
-        // operators can see exactly where embedding fails without waiting for an error.
-        if (isVerbose()) {
-            const EMBED_BATCH_SIZE = 100; // mirrors REMOTE_BATCH_SIZE in remote.ts
-            const totalBatches = Math.ceil(texts.length / EMBED_BATCH_SIZE);
-            for (let i = 0; i < texts.length; i++) {
-                const batchNum = Math.floor(i / EMBED_BATCH_SIZE) + 1;
-                const chars = texts[i].length;
-                const tokens = estimateTokenCount(texts[i]);
-                const ref = allEntries[i].entryKey.split(":").slice(1).join(":"); // strip stashDir prefix
-                warnVerbose(`[embed] ${ref} (${chars} chars, est. ${tokens} tokens) → batch ${batchNum}/${totalBatches}`);
-            }
-        }
-        let heartbeatTimer;
-        try {
-            heartbeatTimer = setInterval(() => {
-                onProgress({
-                    phase: "embeddings",
-                    message: `Still generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}; waiting on embedding provider.`,
-                });
-            }, 15000);
-            const embeddings = await embedBatch(texts, config.embedding, signal);
-            throwIfAborted(signal);
-            // Wrap all embedding upserts in a single transaction so partial
-            // state is rolled back on failure rather than leaving the table half-filled.
-            let storedCount = 0;
-            let skippedCount = 0;
-            let vecFailedCount = 0;
-            let vecUnavailableCount = 0;
-            db.transaction(() => {
-                for (let i = 0; i < allEntries.length; i++) {
-                    const res = upsertEmbedding(db, allEntries[i].id, embeddings[i]);
-                    if (res.stored) {
-                        storedCount++;
-                    }
-                    else {
-                        skippedCount++;
-                    }
-                    if (res.vec === "failed")
-                        vecFailedCount++;
-                    if (res.vec === "unavailable")
-                        vecUnavailableCount++;
-                }
-            })();
-            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.
-            //
-            // 'unavailable' has to degrade the flag too. It means no vec row was
-            // written at all, so marking the fast path ready left a later open (a
-            // different runtime, or sqlite-vec installed afterwards) trusting an
-            // empty entries_vec and returning zero semantic hits against a fully
-            // populated BLOB table.
-            setVecFastPathReady(db, vecFailedCount === 0 && vecUnavailableCount === 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, vecInsertFailures: vecFailedCount };
-        }
-        finally {
-            if (heartbeatTimer)
-                clearInterval(heartbeatTimer);
-        }
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        warn("Embedding generation failed, continuing without:", message);
-        onProgress({
-            phase: "embeddings",
-            message: `Embedding generation failed: ${message}`,
-        });
-        return {
-            success: false,
-            reason: classifySemanticFailure(message),
-            message: `Semantic search verification failed: ${message}`,
-        };
-    }
-}
 // ── Helpers ─────────────────────────────────────────────────────────────────
 function attachFileSize(entry, entryPath) {
     try {
@@ -1586,9 +1559,10 @@ function resolveIndexedFiles(dirPath, files, stash) {
     }
     return resolved.size > 0 ? [...resolved] : files;
 }
-async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db, entryKeys, akmConfig, onEntryDone) {
+async function enhanceStashWithLlm(llmRunner, stash, files, summary, signal, db, itemRefs, akmConfig, onEntryDone, onNotices, lease) {
     const { enhanceMetadata } = await import("../llm/metadata-enhance.js");
     const { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } = await import("../storage/repositories/index-llm-cache-repository.js");
+    let configFailure;
     const results = await concurrentMap(stash.entries, async (entry, idx) => {
         if (signal?.aborted)
             return entry;
@@ -1607,11 +1581,12 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db,
                 }
             }
             // 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.
+            // Cache metadata enrichment by the canonical durable item ref.
             const cacheBody = fileContent ?? `${entry.name}\n${entry.description ?? ""}`;
             const bodyHash = computeBodyHash(cacheBody);
-            const cacheKey = entryKeys?.[idx] ?? `${entry.type}:${entry.name}`;
+            const cacheKey = itemRefs?.[idx];
+            if (!cacheKey)
+                throw new Error(`Missing canonical item ref for enrichment entry ${entry.name}.`);
             if (db) {
                 const cached = getLlmCacheEntry(db, cacheKey, bodyHash);
                 if (cached) {
@@ -1634,7 +1609,7 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db,
                     }
                 }
             }
-            const outcome = await enhanceMetadata(llmConfig, entry, fileContent, signal, akmConfig);
+            const outcome = await enhanceMetadata(llmRunner, entry, fileContent, signal, akmConfig, onNotices, lease);
             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
@@ -1682,6 +1657,10 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db,
             return updated;
         }
         catch (err) {
+            if (err instanceof ConfigError) {
+                configFailure ??= err;
+                return entry;
+            }
             const msg = toErrorMessage(err);
             // failureSamples is bounded to 3 items, so a linear scan is cheaper
             // than maintaining a parallel Set for membership checks (#177 review).
@@ -1694,7 +1673,9 @@ async function enhanceStashWithLlm(llmConfig, stash, files, summary, signal, db,
     }, 
     // Defaults: 2 for remote LLM APIs, 1 for local model servers. No config
     // override reaches this path (see getDefaultLlmConcurrency).
-    getDefaultLlmConcurrency(llmConfig));
+    getDefaultLlmConcurrency(llmRunner.connection));
+    if (configFailure)
+        throw configFailure;
     // concurrentMap returns Array<T | undefined>; filter out undefined slots
     // (which can only occur if the callback itself returned undefined, which
     // it never does above — but TypeScript needs the filter for type safety).
@@ -1711,58 +1692,111 @@ async function resolveLookupSources() {
 }
 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 };
+        return { candidateSources: sources, qualified: false };
+    return { candidateSources: resolveSourcesForOrigin(bundle, sources), qualified: true };
 }
-/** Resolve an adapter-owned `[bundle//]conceptId` without interpreting its path as an AKM type. */
-export async function lookupBundleRef(ref) {
+async function lookupBundleRefWithResolutionUsing(ref, openLookupDatabase) {
     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());
+        return { entry: null };
+    const bundleBySourcePath = new Map(deriveInstallations(sources).map((installation, index) => [path.resolve(sources[index].path), installation.id]));
+    const { candidateSources, qualified } = resolveLookupScope(ref.bundle, sources);
+    if (candidateSources.length === 0)
+        return { entry: null };
+    let db;
+    let indexError;
     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.
+        db = openLookupDatabase(getDbPath());
+    }
+    catch (error) {
+        indexError = error;
+    }
+    try {
+        for (const source of candidateSources) {
+            const adapterId = source.adapterId ?? detectAdapterId(source.path);
+            const owner = resolveAdapterConceptOwner(source.path, adapterId, ref.conceptId);
+            const lookupConceptId = owner?.conceptId ?? ref.conceptId;
+            const inputRef = makeBundleRef(qualified ? ref.bundle : undefined, lookupConceptId);
+            const sourceBundleId = bundleBySourcePath.get(path.resolve(source.path));
+            const id = db && sourceBundleId ? findEntryIdByRef(db, inputRef, sourceBundleId) : undefined;
+            if (id !== undefined && owner && db) {
+                const entry = readLookupEntry(db, id, ref.conceptId, source.path);
+                if (entry) {
+                    if (owner.workflowSource) {
+                        assertIndexedWorkflowSourceIdentity(inputRef, entry.filePath, owner.workflowSource);
+                        if (entry.adapterId !== adapterId) {
+                            throw new WorkflowSourceIdentityError(inputRef, entry.filePath, owner.path);
+                        }
+                    }
+                    else if (entry.adapterId !== adapterId || !indexedPathMatchesOwner(entry.filePath, owner)) {
+                        return { entry: null, owner, ...(indexError === undefined ? {} : { indexError }) };
+                    }
+                    return { entry, owner, ...(indexError === undefined ? {} : { indexError }) };
+                }
             }
-            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,
-            };
+            // A physical owner with a missing/incomplete index row still owns this
+            // unqualified concept. Stop here so a later source cannot retarget it.
+            if (owner)
+                return { entry: null, owner, ...(indexError === undefined ? {} : { indexError }) };
         }
-        return null;
+        return { entry: null, ...(indexError === undefined ? {} : { indexError }) };
     }
     finally {
-        closeDatabase(db);
+        if (db)
+            closeDatabase(db);
+    }
+}
+export async function lookupBundleRefWithResolution(ref) {
+    return lookupBundleRefWithResolutionUsing(ref, openExistingDatabase);
+}
+/** Resolve an adapter-owned `[bundle//]conceptId` without interpreting its path as an AKM type. */
+export async function lookupBundleRef(ref) {
+    const resolution = await lookupBundleRefWithResolution(ref);
+    if (resolution.indexError !== undefined)
+        throw resolution.indexError;
+    return resolution.entry;
+}
+/**
+ * Resolve one execution source without opening the live index database for
+ * write or allowing SQLite read-lock bookkeeping to touch its SHM file.
+ */
+export async function lookupBundleRefReadonly(ref) {
+    const resolution = await lookupBundleRefWithResolutionUsing(ref, (dbPath) => {
+        const db = openReadonlyExistingDatabase(dbPath, { isolatedSnapshot: true });
+        if (!db)
+            throw new Error(`Index database not found at ${dbPath}. Run 'akm index' to build it.`);
+        return db;
+    });
+    if (resolution.indexError !== undefined)
+        throw resolution.indexError;
+    return resolution.entry;
+}
+function readLookupEntry(db, id, fallbackConceptId, sourceRoot) {
+    const row = db
+        .prepare("SELECT file_path AS filePath, type, document_json AS documentJson, " +
+        "item_ref AS itemRef, bundle_id AS bundleId, concept_id AS conceptId, " +
+        "adapter_id AS adapterId FROM entries WHERE id = ?")
+        .get(id);
+    if (!row)
+        return null;
+    let document;
+    try {
+        document = JSON.parse(row.documentJson);
     }
+    catch {
+        // Corrupt optional projection does not erase the durable path identity.
+    }
+    return {
+        filePath: row.filePath,
+        stashDir: sourceRoot,
+        type: row.type,
+        name: document?.name ?? fallbackConceptId.split("/").pop() ?? fallbackConceptId,
+        adapterId: row.adapterId,
+        document,
+        itemRef: row.itemRef,
+        bundleId: row.bundleId,
+        conceptId: row.conceptId,
+    };
 }
 /**
  * Look up a single asset by ref. Spec §6.2 — `akm show` queries this and
@@ -1795,11 +1829,16 @@ const USAGE_EVENT_RETENTION_DAYS = 90;
  *
  * Called during `akm index` after FTS rebuild.
  */
-export function recomputeUtilityScores(db, stateDb) {
+export function recomputeUtilityScores(db, stateDb, options) {
     const EMA_DECAY = 0.7;
+    const stateSchema = options?.stateSchema;
+    if (stateSchema !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(stateSchema)) {
+        throw new Error("Invalid attached state schema name.");
+    }
+    const usageEvents = stateSchema === undefined ? "usage_events" : `"${stateSchema}".usage_events`;
     // 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);
+    purgeOldUsageEvents(stateDb, USAGE_EVENT_RETENTION_DAYS, { stateSchema });
     // 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");
@@ -1830,7 +1869,7 @@ export function recomputeUtilityScores(db, stateDb) {
                  ELSE NULL
                END
              ) AS last_used_at
-      FROM usage_events u
+      FROM ${usageEvents} u
       WHERE u.entry_id IS NOT NULL
         AND u.source = 'user'
       GROUP BY u.entry_id