akm-cli 0.9.17-alpha.3 → 0.9.17-alpha.4

package/dist/indexer/indexer.js

@@ -14,18 +14,18 @@ import { getDbPath } from "../core/paths.js";
 import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
 import { withStateDb } from "../core/state-db.js";
 import { isVerbose, warn, warnOnce, warnVerbose } from "../core/warn.js";
-import { disposeLoweredExecutionDispatchLease, } from "../integrations/agent/execution-lowering.js";
+import { assertRunnerCredentials } from "../integrations/agent/runner-dispatch.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 { salvageEmbeddingsBeforeDiscard } from "../storage/repositories/embedding-salvage-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 { deleteEntriesByBundle, deleteEntriesByDirAndBundle, deleteEntriesByDirExceptRefs, deleteEntriesByIds, deleteUsageEventsByEntryIds, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedBundleIdsByDir, getIndexedDirPathsByBundleId, relinkUsageEvents, upsertEntry, } from "../storage/repositories/index-entries-repository.js";
+import { clearStaleCacheEntries, computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry, } from "../storage/repositories/index-llm-cache-repository.js";
+import { deleteIndexDirState, deleteMeta, getIndexDirState, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
+import { VACUUM_PENDING_META } from "../storage/repositories/index-schema.js";
 import { upsertUtilityScore } from "../storage/repositories/index-utility-repository.js";
-import { getEmbeddingCount, isVecAvailable, isVecFastPathReady, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
+import { getEmbeddingCount } from "../storage/repositories/index-vec-repository.js";
+import { INDEX_DB_VACUUMED_EVENT, readFreelistInfo, vacuumIfReclaimable } from "../storage/state-db-integrity.js";
 import { assertIndexedWorkflowSourceIdentity, WorkflowSourceIdentityError } from "../workflows/source-files.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
 import { reclassifyIndexDbContention } from "./index-db-contention.js";
@@ -33,9 +33,8 @@ import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
 import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
 import { canUseIncrementalSkip, computeDirFingerprint, getCachedDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
-import { getMarkdownFragmentContent, hasMarkdownFragmentContent, isEnrichmentComplete, isWorkflowSkipWarning, setMarkdownFragmentContent, } from "./passes/metadata.js";
+import { isEnrichmentComplete, isWorkflowSkipWarning, withFileSize, } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
-import { buildSearchText } from "./search/search-fields.js";
 import { purgeOldUsageEvents } from "./usage/usage-events.js";
 import { walkStashFlatWithStatus } from "./walk/walker.js";
 function collectLoweringNotices(target, notices) {
@@ -68,12 +67,16 @@ export function getDefaultLlmConcurrency(llmConfig) {
     // is what runs (see docs/architecture/internals/indexing.md).
     return defaultConcurrencyForEndpoint(llmConfig?.endpoint);
 }
+// ── Source ownership ─────────────────────────────────────────────────────────
+/** Each source's durable bundle component (`deriveInstallations`: one per source, source order). */
+function sourceComponents(sources) {
+    return deriveInstallations([...sources]).map((installation) => installation.components[0]);
+}
 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) }] : [];
-    });
+    return sourceComponents(sources).map((component, index) => ({
+        bundleId: component.id,
+        sourceRoot: path.resolve(sources[index].path),
+    }));
 }
 function parseStoredSourceOwners(raw) {
     if (!raw)
@@ -99,102 +102,43 @@ function parseStoredSourceOwners(raw) {
     }
 }
 /**
- * Source cache phase: ensure git stash caches are up to date and purge orphaned
- * entries from removed sources (incremental only).
+ * Sources removed (or moved) since the last complete run. Their entries and
+ * graph rows are purged by {@link applyRemovedSources} once the walk completes.
  */
-async function runSourceCachePhase(ctx) {
-    const { db, isIncremental, full, sources } = ctx;
-    if (isIncremental && !full) {
-        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().
+function findRemovedSources(db, sources) {
+    const currentByBundle = new Map(sourceOwners(sources).map((owner) => [owner.bundleId, owner]));
+    return parseStoredSourceOwners(getMeta(db, "sourceOwners")).flatMap((previous) => {
+        const current = currentByBundle.get(previous.bundleId);
+        if (current && current.sourceRoot === previous.sourceRoot)
+            return [];
+        return [{ ...previous, removeBundleEntries: current === undefined }];
+    });
 }
-function applyRemovedSources(ctx) {
-    if (!ctx.scanComplete)
-        return;
-    const currentRoots = new Set(sourceOwners(ctx.sources).map((owner) => owner.sourceRoot));
-    for (const removed of ctx.removedSources) {
+function applyRemovedSources(db, sources, removedSources, isIncremental) {
+    const owners = sourceOwners(sources);
+    const currentRoots = new Set(owners.map((owner) => owner.sourceRoot));
+    for (const removed of removedSources) {
         if (removed.removeBundleEntries)
-            deleteEntriesByBundle(ctx.db, removed.bundleId);
+            deleteEntriesByBundle(db, removed.bundleId);
         if (!currentRoots.has(removed.sourceRoot))
-            deleteStoredGraph(ctx.db, removed.sourceRoot);
+            deleteStoredGraph(db, removed.sourceRoot);
     }
-}
-/**
- * Walk phase: scan the filesystem, generate metadata, and persist entries to
- * the database. Also kicks off LLM enrichment for directories that need it.
- *
- * Writes `ctx.scannedDirs`, `ctx.skippedDirs`, `ctx.generatedCount`,
- * `ctx.walkWarnings`, and `ctx.dirsNeedingLlm` for downstream phases.
- */
-async function runWalkPhase(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, 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;
-    ctx.walkWarnings = warnings;
-    ctx.dirsNeedingLlm = dirsNeedingLlm;
-    ctx.scanComplete = complete;
-    onProgress({
-        phase: "scan",
-        message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
-    });
-    // Workflow validation noise gate (issue #273): suppress per-spec stderr lines
-    // at default verbosity and emit a single summary instead.
-    // In verbose mode the per-spec lines are already printed by
-    // buildMetadataSkipWarning at generation time — no second pass needed here.
-    if (!isVerbose()) {
-        const workflowSkipWarnings = warnings.filter(isWorkflowSkipWarning);
-        const skippedWorkflowCount = workflowSkipWarnings.length;
-        if (skippedWorkflowCount > 0) {
-            const noun = skippedWorkflowCount === 1 ? "workflow spec" : "workflow specs";
-            warn(`${skippedWorkflowCount} ${noun} skipped due to validation errors; ` +
-                "rerun with --verbose (or AKM_VERBOSE=1) to see details.");
-        }
+    // A full run re-drains every configured source, so any other bundle's rows
+    // are stale even when no stored owner names them.
+    if (isIncremental)
+        return;
+    const currentBundles = new Set(owners.map((owner) => owner.bundleId));
+    const indexed = db.prepare("SELECT DISTINCT bundle_id AS bundleId FROM entries").all();
+    for (const { bundleId } of indexed) {
+        if (!currentBundles.has(bundleId))
+            deleteEntriesByBundle(db, bundleId);
     }
-    ctx.timing.tWalkEnd = Date.now();
-    throwIfAborted(signal);
-    // LLM enrichment for directories that need it
-    await enhanceDirsWithLlm(db, config, ctx.enrichmentExecution, dirsNeedingLlm, onProgress, signal, (notices) => collectLoweringNotices(ctx.loweringNotices, notices), ctx.enrichmentLease);
-    onProgress({
-        phase: "llm",
-        message: ctx.enrichmentExecution.runner
-            ? `LLM enhancement reviewed ${dirsNeedingLlm.length} ${dirsNeedingLlm.length === 1 ? "directory" : "directories"}.`
-            : "LLM enhancement disabled.",
-    });
-    ctx.timing.tLlmEnd = Date.now();
 }
 /**
- * The ONE embedding-phase implementation (#954): generate and
- * store vectors for every entry missing one, then compute the `hasEmbeddings`
- * fact and the semantic-search verification off the result. `akmIndex`'s own
- * (non-deferred) run calls this from {@link runEmbeddingPhase} below; `akm
- * bundle update`'s coordinator calls it directly on its own connection AFTER
- * its unified update transaction commits, since the ambient-transaction drift
- * guard (and the whole point of per-batch commit, #954) requires `db` to have
- * no ambient transaction open.
+ * The embedding phase (#954): generate and store vectors for every entry
+ * missing one, then compute the `hasEmbeddings` fact and the semantic-search
+ * verification off the result. `db` must have no ambient transaction open —
+ * each per-batch commit is its own durable write.
  */
 export async function runEmbeddingPass(params) {
     const { db, config, onProgress, signal, reembed } = params;
@@ -209,69 +153,24 @@ export async function runEmbeddingPass(params) {
     return { embeddingResult, verification };
 }
 /**
- * Embedding phase: generate and store vector embeddings for all unembedded
- * entries. Writes `ctx.embeddingResult` and `ctx.verification` for the
- * finalize phase / caller.
- */
-async function runEmbeddingPhase(ctx) {
-    const { db, config, signal, onProgress, reembed, deferredUpdateTransaction } = ctx;
-    throwIfAborted(signal);
-    if (deferredUpdateTransaction) {
-        // `akm bundle update`'s deferred pass (#954): the embedding
-        // phase runs AFTER the coordinator's own commit, on its own connection,
-        // via the coordinator's direct `runEmbeddingPass` call — never here,
-        // inside the borrowed transaction (the ambient-transaction drift guard
-        // would reject it anyway). `runFinalizePhase` records semantic state as
-        // "pending".
-        ctx.timing.tEmbedEnd = Date.now();
-        return;
-    }
-    // Forward the signal. Without it generateEmbeddingsForDb's abort machinery was
-    // inert — its throwIfAborted checks and the signal it threads into embedBatch
-    // (which RemoteEmbedder passes to every fetch and LocalEmbedder honours between
-    // chunks) never saw a controller. Ctrl-C and the improve budget abort could not
-    // stop the embedding phase, the longest phase of an index run.
-    const { embeddingResult, verification } = await runEmbeddingPass({ db, config, onProgress, signal, reembed });
-    ctx.embeddingResult = embeddingResult;
-    ctx.verification = verification;
-    ctx.timing.tEmbedEnd = Date.now();
-}
-/**
- * Finalize phase: confirm transactionally materialized FTS state, re-link
- * usage events, recompute utility scores, update index metadata, and emit the
- * verify event.
+ * Finalize: re-link usage events, recompute utility scores, clear stale LLM
+ * cache rows and record this run's freshness metadata. `upsertEntry` and every
+ * canonical delete own their FTS projection, so the "fts" event is an
+ * observation point, not a second materialization pass.
  */
-async function runFinalizePhase(ctx) {
-    const { db, config, sources, sourceDirs, stashDir, signal, onProgress, deferredUpdateTransaction } = ctx;
-    ctx.timing.tFinalizeStart = Date.now();
-    // `upsertEntry` and every canonical delete own their FTS projection. This is
-    // an observation point, not a second materialization pass.
-    onProgress({
-        phase: "fts",
-        message: "Full-text search index is current.",
-    });
-    ctx.timing.tFtsEnd = Date.now();
+function finalizeIndex(args) {
+    const { db, sources, sourceDirs, stashDir, signal, onProgress } = args;
+    onProgress({ phase: "fts", message: "Full-text search index is current." });
+    const tFtsEnd = Date.now();
     // 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) => {
+    withStateDb((stateDb) => {
         onProgress({ phase: "finalize", message: "Relinking usage events." });
-        relinkUsageEvents(db, stateDb, { sources, defaultStashDir: stashDir, stateSchema });
+        relinkUsageEvents(db, stateDb);
         onProgress({ phase: "finalize", message: "Recomputing utility scores." });
-        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);
-    }
+        recomputeUtilityScores(db, stateDb);
+    });
     // Purge LLM cache entries for assets that no longer exist in the index.
     try {
         onProgress({ phase: "finalize", message: "Clearing stale LLM cache entries." });
@@ -284,41 +183,34 @@ async function runFinalizePhase(ctx) {
     // 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.
-    if (ctx.scanComplete) {
+    if (args.scanComplete) {
         setMeta(db, "builtAt", new Date().toISOString());
         setMeta(db, "stashDir", stashDir);
         setMeta(db, "stashDirs", JSON.stringify(sourceDirs));
         setMeta(db, "sourceOwners", JSON.stringify(sourceOwners(sources)));
     }
-    warnIfVecMissing(db);
-    const totalEntries = getEntryCount(db);
-    if (deferredUpdateTransaction) {
-        // #954: the embedding phase was skipped for this borrowed
-        // transaction — record semantic state as pending, never ready, until the
-        // coordinator's own post-commit `runEmbeddingPass` call reports the
-        // truth on a fresh connection.
-        setMeta(db, "hasEmbeddings", "0");
-        const semanticEntryCount = getEmbeddableEntryCount(db);
-        const message = "Semantic index update deferred until after the source-update commit.";
-        onProgress({ phase: "verify", message });
-        ctx.verification = {
-            ok: true,
-            message,
-            semanticSearchEnabled: config.semanticSearchMode === "auto",
-            semanticSearchMode: config.semanticSearchMode,
-            semanticStatus: config.semanticSearchMode === "off" ? "disabled" : "pending",
-            embeddingProvider: getEmbeddingProvider(config.embedding),
-            entryCount: semanticEntryCount,
-            embeddingCount: getEmbeddingCount(db),
-            vecAvailable: isVecAvailable(db),
-        };
-    }
-    // Non-deferred: ctx.verification was already populated by runEmbeddingPhase
-    // (via the shared runEmbeddingPass).
-    ctx.totalEntries = totalEntries;
-    ctx.timing.tFinalizeEnd = Date.now();
-    // suppress unused warning — sources was previously used inline
-    void sources;
+    return { tFtsEnd };
+}
+/**
+ * Compact index.db once a layout migration has left tables and columns'
+ * pages free, or whenever more than half its pages are free (the same
+ * threshold improve applies to state.db). Nothing else ever VACUUMs this
+ * file, and a delete-heavy history leaves it mostly free pages.
+ */
+function vacuumIndexDb(db, onProgress) {
+    const migrated = getMeta(db, VACUUM_PENDING_META) === "1";
+    const outcome = vacuumIfReclaimable(db, readFreelistInfo(db), {
+        eventType: INDEX_DB_VACUUMED_EVENT,
+        force: migrated,
+    });
+    if (!outcome.ran)
+        return;
+    if (migrated)
+        deleteMeta(db, VACUUM_PENDING_META);
+    onProgress({
+        phase: "finalize",
+        message: `Compacted index.db with VACUUM: ${outcome.pagesBefore} → ${outcome.pagesAfter} pages.`,
+    });
 }
 // ── Clean pass ───────────────────────────────────────────────────────────────
 /**
@@ -372,29 +264,12 @@ let akmIndexOverride;
 export function _setAkmIndexForTests(fake) {
     akmIndexOverride = fake;
 }
-// Moved to its own module (field follow-up to #956) so
-// `generateEmbeddingsForDb` (materialize-embeddings.ts) can reuse the same
-// classifier without an indexer.ts <-> materialize-embeddings.ts import
-// cycle. Re-exported here for back-compat with existing call sites/tests
-// that import it from `./indexer`. See index-db-contention.ts for the full
-// rationale.
-export { reclassifyIndexDbContention };
 export async function akmIndex(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 reclassifyIndexDbContention(error);
     }
 }
@@ -402,20 +277,16 @@ let indexTransactionHookForTests;
 /**
  * TEST-ONLY. Observe the in-flight reindex transaction; `undefined` restores.
  *
- * Exists because the delete-then-reinsert atomicity guarantee is, by
- * construction, invisible from outside the transaction: by the time
- * `akmIndex()` resolves, the commit has already collapsed both generations
- * into one observable state. Concurrency tests install a hook that opens a
- * SECOND connection at these points and asserts it still sees the previous
- * complete generation. Inert in production (one `undefined?.()` per reindex).
+ * Exists because the persist transaction's atomicity is, by construction,
+ * invisible from outside it: by the time `akmIndex()` resolves, the commit
+ * has already collapsed both generations into one observable state.
+ * Concurrency tests install a hook that opens a SECOND connection at this
+ * point and asserts it still sees the previous complete generation. Inert in
+ * production (one `undefined?.()` per reindex).
  */
 export function _setIndexTransactionHookForTests(hook) {
     indexTransactionHookForTests = hook;
 }
-/** Fire a named in-transaction observation point (no-op outside tests). */
-function indexTransactionHook(point) {
-    indexTransactionHookForTests?.(point);
-}
 let drainObserverForTests;
 /**
  * TEST-ONLY. Observe every directory that actually reaches
@@ -429,6 +300,18 @@ let drainObserverForTests;
 export function _setDrainObserverForTests(observer) {
     drainObserverForTests = observer;
 }
+/** Whether `root` is a directory whose listing can be read (adapter detection only probes such roots). */
+function isReadableDirectory(root) {
+    try {
+        if (!fs.statSync(root).isDirectory())
+            return false;
+        fs.readdirSync(root); // probe readability, not just existence
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Detect an adapter for every resolvable source that does not declare one, and
  * persist each detection into `config.json`.
@@ -440,17 +323,13 @@ export function _setDrainObserverForTests(observer) {
  * 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])) {
+        if (isReadableDirectory(source.path)) {
             source.adapterId = detectAdapterId(source.path);
             if (source.registryId)
                 detectedByBundle.set(source.registryId, source.adapterId);
@@ -490,38 +369,6 @@ 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,
@@ -538,183 +385,209 @@ async function akmIndexReal(options) {
             "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();
-    return (async () => {
-        const stashDir = options.stashDir;
-        const onProgress = options?.onProgress ?? (() => { });
-        const signal = options?.signal;
-        const full = options?.full === true;
-        const clean = options?.clean === true;
-        const dryRun = options?.dryRun === true;
-        const reembed = options?.reembed === true;
-        // Load config and resolve all stash sources
-        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." });
-        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();
-        onProgress({ phase: "preflight", message: "Hydrating source caches." });
-        const { ensureSourceCaches, resolveSourceEntries } = await import("./search/search-source.js");
-        // 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,
-            // Same progress channel as every other phase (#954) — a
-            // stalled clone/fetch here runs BEFORE index.db is even opened, so
-            // without this it looked identical to "no database open, nothing
-            // written".
-            onProgress: (message) => onProgress({ phase: "preflight", message }),
-        });
-        const sourceCacheEnd = Date.now();
-        const allSourceEntries = resolveSourceEntries(stashDir, config);
-        const detected = detectAndPersistBundleAdapters(allSourceEntries, config, mutateConfig, {
-            announce: options.implicit !== true,
-            persist: options.persistDetectedAdapters !== false,
+    const { stashDir, signal } = options;
+    const onProgress = options.onProgress ?? (() => { });
+    const full = options.full === true;
+    const clean = options.clean === true;
+    const dryRun = options.dryRun === true;
+    // Load config and resolve all stash sources
+    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");
+    // 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,
+        // Same progress channel as every other phase (#954) — a
+        // stalled clone/fetch here runs BEFORE index.db is even opened, so
+        // without this it looked identical to "no database open, nothing
+        // written".
+        onProgress: (message) => onProgress({ phase: "preflight", message }),
+    });
+    const sourceCacheEnd = Date.now();
+    const sources = resolveSourceEntries(stashDir, config);
+    const detected = detectAndPersistBundleAdapters(sources, config, mutateConfig, {
+        announce: options.implicit !== true,
+        persist: options.persistDetectedAdapters !== false,
+    });
+    config = detected.config;
+    const { persistedAdapters } = detected;
+    const sourceDirs = sources.map((s) => s.path);
+    onProgress({
+        phase: "preflight",
+        message: `Resolved ${sourceDirs.length} stash source${sourceDirs.length === 1 ? "" : "s"}.`,
+    });
+    const t0 = Date.now();
+    const enrichmentExecution = resolveIndexPassExecution("enrichment", config);
+    const loweringNotices = [...enrichmentExecution.notices];
+    const dbPath = getDbPath();
+    const db = openIndexDatabase(dbPath);
+    try {
+        // `--full` folds into `isIncremental`: a full run drains every directory
+        // through the same diff-persist path as an incremental one.
+        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;
+        const mode = isIncremental ? "incremental" : "full";
+        onProgress({
+            phase: "summary",
+            message: buildIndexSummaryMessage({
+                mode,
+                sourcesCount: sourceDirs.length,
+                semanticSearchMode: config.semanticSearchMode,
+                embeddingProvider: getEmbeddingProvider(config.embedding),
+                llmEnabled: !!enrichmentExecution.runner,
+            }),
         });
-        config = detected.config;
-        const persistedAdapters = detected.persistedAdapters;
-        const allSourceDirs = allSourceEntries.map((s) => s.path);
+        const removedSources = findRemovedSources(db, sources);
+        // ── Walk: scan the filesystem, generate metadata, persist entries ─────
+        throwIfAborted(signal);
+        const tWalkStart = Date.now();
+        // Walk every source and pre-generate all metadata outside any transaction…
+        const { dirRecords, scannedDirs, skippedDirs, generatedCount, warnings, complete } = await scanSourceDirs(db, sources, isIncremental, builtAtMs, removedSources.length > 0, onProgress, !clean);
+        // …fail on a missing enrichment credential before anything is persisted…
+        const bundleByRoot = buildIndexedSourceOwners(sources);
+        const runner = enrichmentExecution.runner;
+        if (runner &&
+            isLlmFeatureEnabled(config, "metadata_enhance") &&
+            dirRecordsNeedMetadataDispatch(db, dirRecords, bundleByRoot)) {
+            assertRunnerCredentials(runner);
+        }
+        // …then write it in one transaction: `item_ref = <bundle>//<conceptId>`
+        // plus canonical component/adapter provenance per source root.
+        const { dirsNeedingLlm } = persistDirRecords(db, dirRecords, warnings, bundleByRoot);
         onProgress({
-            phase: "preflight",
-            message: `Resolved ${allSourceDirs.length} stash source${allSourceDirs.length === 1 ? "" : "s"}.`,
+            phase: "scan",
+            message: `Scanned ${scannedDirs} ${scannedDirs === 1 ? "directory" : "directories"} and skipped ${skippedDirs}.`,
         });
-        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 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.");
+        // Workflow validation noise gate (issue #273): suppress per-spec stderr
+        // lines at default verbosity and emit a single summary instead. In verbose
+        // mode the per-spec lines are already printed by buildMetadataSkipWarning.
+        if (!isVerbose()) {
+            const skippedWorkflowCount = warnings.filter(isWorkflowSkipWarning).length;
+            if (skippedWorkflowCount > 0) {
+                const noun = skippedWorkflowCount === 1 ? "workflow spec" : "workflow specs";
+                warn(`${skippedWorkflowCount} ${noun} skipped due to validation errors; ` +
+                    "rerun with --verbose (or AKM_VERBOSE=1) to see details.");
+            }
         }
-        let indexRunContext;
-        try {
-            // Assemble the run context
-            const ctx = createIndexRunContext({
-                db,
-                config,
-                enrichmentExecution,
-                sources: allSourceEntries,
-                sourceDirs: allSourceDirs,
-                full,
-                clean,
-                reembed,
-                stashDir,
-                onProgress,
-                signal,
-                t0,
-                deferredUpdateTransaction: options.deferredUpdateTransaction,
-            });
-            indexRunContext = ctx;
+        const tWalkEnd = Date.now();
+        // ── LLM enrichment for the directories that need it ───────────────────
+        throwIfAborted(signal);
+        await enhanceDirsWithLlm(db, config, enrichmentExecution, dirsNeedingLlm, onProgress, signal, (notices) => collectLoweringNotices(loweringNotices, notices));
+        onProgress({
+            phase: "llm",
+            message: enrichmentExecution.runner
+                ? `LLM enhancement reviewed ${dirsNeedingLlm.length} ${dirsNeedingLlm.length === 1 ? "directory" : "directories"}.`
+                : "LLM enhancement disabled.",
+        });
+        const tLlmEnd = Date.now();
+        if (complete)
+            applyRemovedSources(db, sources, removedSources, isIncremental);
+        // 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.
+        let cleanResult;
+        const cleanStart = Date.now();
+        if (clean) {
             onProgress({
-                phase: "summary",
-                message: buildIndexSummaryMessage({
-                    mode: ctx.isIncremental ? "incremental" : "full",
-                    sourcesCount: allSourceDirs.length,
-                    semanticSearchMode: config.semanticSearchMode,
-                    embeddingProvider: getEmbeddingProvider(config.embedding),
-                    llmEnabled: !!enrichmentExecution.runner,
-                    vecAvailable: isVecAvailable(db),
-                }),
+                phase: "finalize",
+                message: dryRun ? "Scanning for stale index entries (dry run)." : "Removing stale index entries.",
             });
-            let cleanResult;
-            let cleanStart = Date.now();
-            let cleanEnd = cleanStart;
-            // ── Phase sequence ───────────────────────────────────────────────────────
-            await runSourceCachePhase(ctx);
-            await runWalkPhase(ctx);
-            applyRemovedSources(ctx);
-            // 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",
-                    message: dryRun ? "Scanning for stale index entries (dry run)." : "Removing stale index entries.",
-                });
-                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 };
-                }
+            if (complete) {
+                cleanResult = runCleanPass(db, dryRun);
             }
-            cleanEnd = Date.now();
-            await runEmbeddingPhase(ctx);
-            await runFinalizePhase(ctx);
-            // ────────────────────────────────────────────────────────────────────────
-            // 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: 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 } }
-                    : {}),
-                verification,
-                timing: {
-                    totalMs: Date.now() - timing.t0,
-                    walkMs: timing.tWalkEnd - timing.tWalkStart,
-                    llmMs: timing.tLlmEnd - timing.tWalkEnd,
-                    embedMs: timing.tEmbedEnd - timing.tLlmEnd,
-                    ftsMs: timing.tFtsEnd - timing.tEmbedEnd,
-                    finalizeMs: timing.tFinalizeEnd - timing.tFinalizeStart,
-                    cleanMs: clean ? cleanEnd - cleanStart : 0,
-                    preflightMs: timing.t0 - requestedAt,
-                    sourceCacheMs: sourceCacheEnd - sourceCacheStart,
-                    endToEndMs: Date.now() - requestedAt,
-                },
-                ...(cleanResult !== undefined ? { clean: cleanResult } : {}),
-            };
-        }
-        finally {
-            if (indexRunContext?.enrichmentLease) {
-                disposeLoweredExecutionDispatchLease(indexRunContext.enrichmentLease);
+            else {
+                warn("[index] --clean skipped because one or more configured sources were not scanned completely.");
+                cleanResult = { checked: 0, removed: 0, removedRefs: [], dryRun };
             }
-            if (!borrowedUpdateDb)
-                closeDatabase(db);
         }
-    })();
+        const cleanEnd = Date.now();
+        // ── Embeddings ─────────────────────────────────────────────────────────
+        throwIfAborted(signal);
+        const { verification } = await runEmbeddingPass({
+            db,
+            config,
+            onProgress,
+            signal,
+            reembed: options.reembed === true,
+        });
+        const tEmbedEnd = Date.now();
+        // ── Finalize ──────────────────────────────────────────────────────────
+        const tFinalizeStart = Date.now();
+        const { tFtsEnd } = finalizeIndex({
+            db,
+            sources,
+            sourceDirs,
+            stashDir,
+            scanComplete: complete,
+            signal,
+            onProgress,
+        });
+        vacuumIndexDb(db, onProgress);
+        const totalEntries = getEntryCount(db);
+        const tFinalizeEnd = Date.now();
+        return {
+            stashDir,
+            totalEntries,
+            generatedMetadata: generatedCount,
+            indexPath: dbPath,
+            mode,
+            directoriesScanned: scannedDirs,
+            directoriesSkipped: skippedDirs,
+            scanComplete: complete,
+            ...(warnings.length > 0 ? { warnings } : {}),
+            ...(loweringNotices.length > 0 ? { notices: Object.freeze([...loweringNotices]) } : {}),
+            ...(Object.keys(persistedAdapters).length > 0 ? { configUpdated: { detectedAdapters: persistedAdapters } } : {}),
+            verification,
+            timing: {
+                totalMs: Date.now() - t0,
+                walkMs: tWalkEnd - tWalkStart,
+                llmMs: tLlmEnd - tWalkEnd,
+                embedMs: tEmbedEnd - tLlmEnd,
+                ftsMs: tFtsEnd - tEmbedEnd,
+                finalizeMs: tFinalizeEnd - tFinalizeStart,
+                cleanMs: clean ? cleanEnd - cleanStart : 0,
+                preflightMs: t0 - requestedAt,
+                sourceCacheMs: sourceCacheEnd - sourceCacheStart,
+                endToEndMs: Date.now() - requestedAt,
+            },
+            ...(cleanResult !== undefined ? { clean: cleanResult } : {}),
+        };
+    }
+    finally {
+        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;
+    const components = sourceComponents(sources);
+    return new Map(sources.map((source, index) => {
+        const { id, adapter } = components[index];
+        return [path.resolve(source.path), { bundleId: id, componentId: id, adapterId: adapter }];
+    }));
+}
+/**
+ * The metadata-enrichment cache's body hash (`llm_enrichment_cache`, keyed by
+ * item ref + this hash): the entry file's text, else its name and description.
+ */
+function enrichmentBodyHash(entry, fileContent) {
+    return computeBodyHash(fileContent ?? `${entry.name}\n${entry.description ?? ""}`);
 }
 /** Read-only mirror of the enrichment cache gate used before entry persistence. */
 function dirRecordsNeedMetadataDispatch(db, records, ownersByRoot) {
@@ -740,7 +613,7 @@ function dirRecordsNeedMetadataDispatch(db, records, ownersByRoot) {
             catch {
                 // The dispatch path uses the same deterministic metadata fallback.
             }
-            const bodyHash = computeBodyHash(fileContent ?? `${entry.name}\n${entry.description ?? ""}`);
+            const bodyHash = enrichmentBodyHash(entry, fileContent);
             const cacheKey = deriveEntryProvenance(owner, entry.type, entry.name, adapterConceptId).itemRef;
             const cached = getLlmCacheEntry(db, cacheKey, bodyHash);
             if (!cached)
@@ -762,32 +635,6 @@ function addEntryIds(target, ids) {
     for (const id of ids)
         target.add(id);
 }
-/**
- * Map each source root → its durable `BundleComponent` (`deriveInstallations`,
- * batch-unique bundle ids, source order preserved). The per-dir document drain
- * dispatches `adapterForId(component.adapter).recognize` for this component. The
- * component id only surfaces on `IndexDocument.ref`, which the persist layer
- * re-derives independently — so a source missing from the map (never happens: the
- * map is built from the same sources) is harmless.
- */
-function buildComponentBySource(sources) {
-    const map = new Map();
-    const installations = deriveInstallations(sources);
-    sources.forEach((source, i) => {
-        const component = installations[i]?.components[0];
-        if (component)
-            map.set(source.path, component);
-    });
-    return map;
-}
-function componentForSource(components, sourcePath) {
-    return (components.get(sourcePath) ?? {
-        id: sourcePath,
-        adapter: "akm",
-        root: sourcePath,
-        writable: false,
-    });
-}
 function groupFileContextsByDir(fileContexts) {
     const groups = new Map();
     for (const ctx of fileContexts) {
@@ -876,17 +723,19 @@ function warnIfAdapterSkipsAkmContent(component, files, adapter) {
         `${skippedDirs.map((dir) => `${dir}/`).join(", ")} — set components.<name>.adapter to "akm" to index them`);
 }
 function buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMissingDirs) {
-    const componentBySource = buildComponentBySource(allSourceEntries);
+    // Each source root → its durable `BundleComponent`; the per-dir document
+    // drain dispatches `adapterForId(component.adapter).recognize` for it.
+    const components = sourceComponents(allSourceEntries);
+    const componentBySource = new Map(allSourceEntries.map((source, index) => [source.path, components[index]]));
     const handoffDirs = new Set();
     const plans = allSourceEntries.map((sourceAdded) => {
         const currentStashDir = sourceAdded.path;
-        const component = componentForSource(componentBySource, currentStashDir);
+        const component = componentBySource.get(currentStashDir);
         if (sourceAdded.unresolved) {
             return {
                 currentStashDir,
                 component,
                 adapter: undefined,
-                indexVariant: undefined,
                 dirGroups: new Map(),
                 removals: [],
                 walkComplete: false,
@@ -906,7 +755,6 @@ function buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMiss
             currentStashDir,
             component,
             adapter,
-            indexVariant: adapter ? `${adapter.id}@${adapter.version}` : undefined,
             dirGroups,
             removals: [],
             walkComplete: walked.complete,
@@ -931,9 +779,10 @@ function buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMiss
         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)) {
+    // Reconcile departed directories for every source that produced a
+    // trustworthy snapshot; a source that was not walked completely keeps its
+    // last-known-good rows.
+    if (reconcileMissingDirs) {
         const allIndexedDirsByBundle = !isIncremental ? new Map() : undefined;
         if (allIndexedDirsByBundle) {
             for (const entry of getAllEntries(db)) {
@@ -986,9 +835,6 @@ function buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMiss
  * outside `db.transaction()` so the persist pass can be a single synchronous
  * transaction.
  */
-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;
@@ -999,7 +845,7 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
     const dirRecords = [];
     let processedDirs = 0;
     let priorDirsChanged = hadRemovedSources;
-    const reportScanProgress = (message) => reportSourceScanProgress(onProgress, processedDirs, allSourceEntries.length, message);
+    const reportScanProgress = (message) => onProgress?.({ phase: "scan", message, processed: processedDirs, total: allSourceEntries.length });
     const reportDirDecision = (kind, dirPath, currentStashDir, reason, persistedRowCount) => {
         if (!isVerbose())
             return;
@@ -1020,46 +866,6 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
         seenPaths.add(resolved);
         return false;
     };
-    // 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, fingerprint, stash, hashByFile, conceptIdByFile, indexVariant, forceScan, pruneMissing) => {
-        const previousState = getDirIndexState(db, dirPath, stateFiles, builtAtMs, indexVariant, fingerprint);
-        if (isIncremental && !forceScan && !previousState.stale && canUseIncrementalSkip(previousState, priorDirsChanged)) {
-            skippedDirs++;
-            dirRecords.push({
-                dirPath,
-                currentStashDir,
-                files: stateFiles,
-                fingerprint,
-                stash: null,
-                skip: true,
-                reason: previousState.reason,
-                persistedRowCount: previousState.persistedRowCount,
-                indexVariant,
-            });
-            reportDirDecision("skip", dirPath, currentStashDir, previousState.reason, previousState.persistedRowCount);
-            return;
-        }
-        scannedDirs++;
-        priorDirsChanged = true;
-        const reason = isIncremental ? previousState.reason : { kind: "full-rebuild" };
-        dirRecords.push({
-            dirPath,
-            currentStashDir,
-            files: stateFiles,
-            fingerprint,
-            stash,
-            skip: false,
-            reason,
-            persistedRowCount: previousState.persistedRowCount,
-            hashByFile,
-            conceptIdByFile,
-            indexVariant,
-            pruneMissing,
-        });
-        reportDirDecision("scan", dirPath, currentStashDir, reason, previousState.persistedRowCount);
-    };
     for (const plan of plans) {
         const { currentStashDir, component, adapter, dirGroups, removals, walkComplete } = plan;
         processedDirs++;
@@ -1079,7 +885,7 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
             warn(`Skipping component "${component.id}": unknown adapter id "${component.adapter}".`);
             continue;
         }
-        const indexVariant = plan.indexVariant ?? `${adapter.id}@${adapter.version}`;
+        const indexVariant = `${adapter.id}@${adapter.version}`;
         for (const removal of removals) {
             dirRecords.push(removal);
             scannedDirs++;
@@ -1129,17 +935,53 @@ async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, ha
             const drained = drainDirDocuments(adapter, component, ctxs);
             if (drained.warnings.length)
                 warnings.push(...drained.warnings);
-            const generated = drained.warnings.length
-                ? { entries: drained.entries, warnings: drained.warnings }
-                : { entries: drained.entries };
-            // `.stash.json` sidecar overrides retired (#39): the cutover's content
-            // migration folded sidecar metadata into frontmatter and deleted the
-            // files; the runtime no longer reads them.
-            const { stash, staleFiles } = buildIndexedDirCandidate(dirPath, indexableFiles, generated);
-            if (generated.entries.length > 0) {
-                generatedCount += generated.entries.length;
+            generatedCount += drained.entries.length;
+            const stash = drained.entries.length > 0 ? { entries: drained.entries } : null;
+            // Freshness is judged over the files the entries came from (every walked
+            // file when none was recognized).
+            const entryFiles = new Set(drained.entries.flatMap((entry) => (entry.filename ? [path.join(dirPath, entry.filename)] : [])));
+            const staleFiles = entryFiles.size > 0 ? [...entryFiles] : indexableFiles;
+            // Incremental freshness gate: consult the persisted dir state and record
+            // either a skip (unchanged + eligible) or a scan carrying the drained stash.
+            const previousState = getDirIndexState(db, dirPath, staleFiles, builtAtMs, indexVariant, fingerprint);
+            const { persistedRowCount } = previousState;
+            if (isIncremental &&
+                !forceScan &&
+                !previousState.stale &&
+                canUseIncrementalSkip(previousState, priorDirsChanged)) {
+                skippedDirs++;
+                const reason = previousState.reason;
+                dirRecords.push({
+                    dirPath,
+                    currentStashDir,
+                    files: staleFiles,
+                    fingerprint,
+                    stash: null,
+                    skip: true,
+                    reason,
+                    persistedRowCount,
+                    indexVariant,
+                });
+                reportDirDecision("skip", dirPath, currentStashDir, reason, persistedRowCount);
+                continue;
             }
-            recordFreshnessDecision(dirPath, currentStashDir, staleFiles, fingerprint, stash, drained.hashByFile, drained.conceptIdByFile, indexVariant, forceScan, walkComplete);
+            scannedDirs++;
+            priorDirsChanged = true;
+            const reason = isIncremental ? previousState.reason : { kind: "full-rebuild" };
+            dirRecords.push({
+                dirPath,
+                currentStashDir,
+                files: staleFiles,
+                fingerprint,
+                stash,
+                skip: false,
+                reason,
+                persistedRowCount,
+                hashByFile: drained.hashByFile,
+                conceptIdByFile: drained.conceptIdByFile,
+                indexVariant,
+            });
+            reportDirDecision("scan", dirPath, currentStashDir, reason, persistedRowCount);
         }
     }
     return {
@@ -1161,90 +1003,22 @@ function requiresWorkflowSourcePreflight(ctxs) {
         }
     });
 }
-function preserveExistingIndex(doFullDelete, dirRecords, sourceRoots) {
-    if (!doFullDelete)
-        return false;
-    const incomingDocCount = dirRecords.reduce((n, record) => n + (record.skip ? 0 : (record.stash?.entries.length ?? 0)), 0);
-    if (incomingDocCount > 0 || allSourceRootsReadable(sourceRoots))
-        return false;
-    warn("[index] --full produced zero documents while one or more source roots are missing or unreadable — " +
-        "preserving the existing index (last-known-good) rather than wiping it. Re-run once the sources are available.");
-    return true;
-}
-/**
- * #624-P1 zero-document preflight probe. A source root counts as "readable"
- * when it exists on disk as a directory whose listing can be read. A root that
- * is missing or unreadable (a transient mount failure, a permission race, or a
- * source that vanished mid-run) makes a zero-document scan untrustworthy: the
- * walk saw nothing not because the stash is empty but because it could not be
- * read. Returns true only when EVERY root is readable, so a single unreadable
- * root blocks the full-rebuild wipe.
- */
-function allSourceRootsReadable(roots) {
-    for (const root of roots) {
-        try {
-            const st = fs.statSync(root);
-            if (!st.isDirectory())
-                return false;
-            fs.readdirSync(root); // probe readability, not just existence
-        }
-        catch {
-            return false;
-        }
-    }
-    return true;
-}
 /**
  * Phase 2 (sync): write all pre-generated scan records inside a single
  * transaction, returning the directories that still need LLM enrichment.
  */
-function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots, scanComplete, bundleByRoot) {
+function persistDirRecords(db, dirRecords, warnings, 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
-    // or unreadable, the empty result is almost certainly a transient scan
-    // failure, not an emptied stash — wiping here would cascade-destroy the
-    // last-known-good index (entries + embeddings + utility/usage). Preserve it
-    // and warn instead; the next successful run reconciles. A genuinely empty
-    // stash whose roots ARE readable still wipes, as before.
-    if (preserveExistingIndex(fullDelete, dirRecords, sourceRoots))
-        return { dirsNeedingLlm };
     // Per-source dedup: the same logical asset can appear more than once within
     // one owning source, where source order still makes the first occurrence win.
     // The owner is part of the key so identical concepts in different bundles
     // remain distinct indexed rows.
     const indexedAssetIdentities = new Set();
     const deletedUsageEntryIds = new Set();
+    const findPersisted = db.prepare("SELECT id, content_hash, file_path, adapter_id, json_extract(document_json, '$.quality') AS quality " +
+        "FROM entries WHERE item_ref = ?");
     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 (fullDelete) {
-            // #955: copy every (search_text hash, embedding) pair about to be
-            // discarded wholesale into `embedding_salvage`, tagged with the
-            // fingerprint the discarded vectors were generated under, BEFORE the
-            // wipe below — inside the SAME transaction so the copy and the
-            // discard commit or roll back together. The embedding phase later in
-            // this run hands salvaged vectors back to unchanged content instead
-            // of re-embedding the whole corpus.
-            salvageEmbeddingsBeforeDiscard(db);
-            // 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.
-            // 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, fingerprint, stash, skip, reason, persistedRowCount, hashByFile, conceptIdByFile, indexVariant, remove, pruneMissing, } of dirRecords) {
+        for (const { dirPath, currentStashDir, files, fingerprint, stash, skip, reason, persistedRowCount, hashByFile, conceptIdByFile, indexVariant, remove, } of dirRecords) {
             const bundle = bundleByRoot.get(path.resolve(currentStashDir));
             if (!bundle)
                 throw new Error(`Missing bundle provenance for indexed source ${currentStashDir}`);
@@ -1261,7 +1035,13 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
                 // row_count and the gate skips this directory before draining next
                 // time. "unchanged-precheck" already matched the stored row.
                 if (reason?.kind === "unchanged" && fingerprint) {
-                    upsertIndexDirState(db, { dirPath, ...fingerprint, reason: reason.kind, rowCount: persistedRowCount });
+                    upsertIndexDirState(db, {
+                        dirPath,
+                        ...fingerprint,
+                        reason: reason.kind,
+                        rowCount: persistedRowCount,
+                        indexVariant,
+                    });
                 }
                 continue;
             }
@@ -1271,8 +1051,19 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
             // durable `item_ref`, then prune only the departed rows below. Replaces the old
             // `deleteEntriesByDir` truncate-and-reinsert (which discarded ids).
             const keptItemRefs = new Set();
+            // Per-file cursor: a directory is drained whole (one changed file
+            // re-reads its siblings), but on an incremental run a sibling whose
+            // content hash, path and adapter are unchanged since the last drain
+            // under the same adapter variant is already persisted exactly as this
+            // drain would persist it — including any LLM enrichment layered onto its
+            // row — so it is neither rewritten nor re-enriched. `--full` re-persists
+            // every entry.
+            const sameVariant = reason?.kind !== "full-rebuild" &&
+                indexVariant !== undefined &&
+                getIndexDirState(db, dirPath)?.indexVariant === indexVariant;
             let persistedRows = 0;
             let dedupedRows = 0;
+            const entriesToEnrich = [];
             if (stash) {
                 const ownerIdentity = bundle.bundleId;
                 for (const entry of stash.entries) {
@@ -1294,29 +1085,42 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
                         continue;
                     }
                     indexedAssetIdentities.add(identityKey);
-                    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);
                     keptItemRefs.add(provenance.itemRef);
-                    upsertEntry(db, entryPath, entryWithSize, searchText, provenance, contentHash);
                     persistedRows++;
+                    const previous = sameVariant
+                        ? (findPersisted.get(provenance.itemRef) ?? undefined)
+                        : undefined;
+                    const unchanged = previous !== undefined &&
+                        contentHash !== undefined &&
+                        previous.content_hash === contentHash &&
+                        previous.file_path === entryPath &&
+                        previous.adapter_id === bundle.adapterId;
+                    if (unchanged) {
+                        // An unchanged row that was never enriched still wants the LLM
+                        // pass (the cache decides whether a call is needed).
+                        if (entry.quality === "generated" && previous.quality !== "enriched")
+                            entriesToEnrich.push(entry);
+                        continue;
+                    }
+                    upsertEntry(db, entryPath, withFileSize(entry, entryPath), provenance, contentHash);
+                    if (entry.quality === "generated")
+                        entriesToEnrich.push(entry);
                 }
-                // Collect dirs needing LLM enhancement during the first walk.
-                // Only dirs with "generated" entries need enrichment.
-                if (stash.entries.some((e) => e.quality === "generated")) {
-                    dirsNeedingLlm.push({ dirPath, files, currentStashDir, stash });
+                // Only "generated" entries (never user-curated ones) are enriched.
+                if (entriesToEnrich.length > 0) {
+                    dirsNeedingLlm.push({ dirPath, files, currentStashDir, stash: { entries: entriesToEnrich } });
                 }
             }
             // Prune the departed rows: everything under this dir NOT re-upserted above
             // (files deleted, deduped away, or abstained on by the adapter). With
             // an empty kept-set this deletes every row for the dir — the exact net
             // effect of the old unconditional `deleteEntriesByDir`, minus the id churn.
-            if (pruneMissing !== false) {
-                addEntryIds(deletedUsageEntryIds, deleteEntriesByDirExceptRefs(db, dirPath, bundle.bundleId, keptItemRefs, { cleanupUsageEvents: false }));
-            }
+            // (A source whose walk was incomplete never reaches this point.)
+            addEntryIds(deletedUsageEntryIds, deleteEntriesByDirExceptRefs(db, dirPath, bundle.bundleId, keptItemRefs, { cleanupUsageEvents: false }));
             const persistedFingerprint = fingerprint ?? computeDirFingerprint(dirPath, files, indexVariant);
             const persistedReason = persistedRows === 0
                 ? inferZeroRowReason(stash, reason, warnings, dirPath, dedupedRows)
@@ -1332,6 +1136,7 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
                 // must keep draining every run (as it did before the gate) until a
                 // drain persists it without dedup. NULL keeps the gate closed.
                 rowCount: dedupedRows === 0 ? persistedRows : undefined,
+                indexVariant,
             });
             if (persistedRows === 0) {
                 // Warn only when the dir had files that *could* produce entries (.md or
@@ -1352,30 +1157,12 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
         }
         // Atomicity observation point: the new generation is fully written but
         // uncommitted, so it must still be invisible to other connections.
-        indexTransactionHook("records-persisted");
+        indexTransactionHookForTests?.("records-persisted");
     });
     insertTransaction();
     deleteUsageEventsByEntryIds([...deletedUsageEntryIds]);
     return { dirsNeedingLlm };
 }
-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);
-    // 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 { dirsNeedingLlm } = persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots, complete, bundleByRoot);
-    return { scannedDirs, skippedDirs, generatedCount, warnings, dirsNeedingLlm, complete };
-}
 function indexedProvenanceForFile(db, filePath) {
     const row = db
         .prepare("SELECT item_ref AS itemRef, bundle_id AS bundleId, component_id AS componentId, " +
@@ -1392,7 +1179,7 @@ function indexedProvenanceForFile(db, filePath) {
         adapterId: row.adapterId,
     };
 }
-async function enhanceDirsWithLlm(db, config, execution, dirsNeedingLlm, onProgress, signal, onNotices, lease) {
+async function enhanceDirsWithLlm(db, config, execution, dirsNeedingLlm, onProgress, signal, onNotices) {
     // The invocation owns one frozen symbolic selection. Summary reporting and
     // every enrichment dispatch consume this same snapshot.
     const llmRunner = execution.runner;
@@ -1405,39 +1192,15 @@ async function enhanceDirsWithLlm(db, config, execution, dirsNeedingLlm, onProgr
     let completedDirs = 0;
     let completedEntries = 0;
     const totalDirs = dirsNeedingLlm.length;
-    const totalEntries = dirsNeedingLlm.reduce((sum, { stash }) => {
-        const entriesToEnhance = stash.entries.filter((e) => {
-            if (e.quality !== "generated")
-                return false;
-            if (isEnrichmentComplete(e))
-                return false;
-            return true;
-        });
-        return sum + entriesToEnhance.length;
-    }, 0);
+    const totalEntries = dirsNeedingLlm.reduce((sum, { stash }) => sum + stash.entries.filter((e) => e.quality === "generated" && !isEnrichmentComplete(e)).length, 0);
     // 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(llmRunner.timeoutMs, totalEntries);
-    let deadlineHit = false;
-    const enrichSignal = (() => {
-        if (!enrichDeadline)
-            return signal ?? new AbortController().signal;
-        if (!signal)
-            return enrichDeadline;
-        // Combine: abort when either fires.
-        const controller = new AbortController();
-        const onAbort = () => controller.abort();
-        signal.addEventListener("abort", onAbort, { once: true });
-        enrichDeadline.addEventListener("abort", () => {
-            deadlineHit = true;
-            controller.abort();
-        }, { once: true });
-        return controller.signal;
-    })();
+    const enrichSignal = AbortSignal.any([signal, enrichDeadline].filter((s) => s !== undefined));
     if (totalEntries > 0) {
-        onProgress?.({
+        onProgress({
             phase: "llm",
             message: `LLM enhancement starting for ${totalEntries} entr${totalEntries === 1 ? "y" : "ies"} ` +
                 `across ${totalDirs} director${totalDirs === 1 ? "y" : "ies"} (concurrency ${getDefaultLlmConcurrency(llmRunner.connection)}).`,
@@ -1449,7 +1212,7 @@ async function enhanceDirsWithLlm(db, config, execution, dirsNeedingLlm, onProgr
     let configFailure;
     let lastProgressAt = Date.now();
     let heartbeatTimer;
-    if (totalEntries > 0 && onProgress) {
+    if (totalEntries > 0) {
         heartbeatTimer = setInterval(() => {
             if (Date.now() - lastProgressAt < 15000)
                 return;
@@ -1483,7 +1246,7 @@ async function enhanceDirsWithLlm(db, config, execution, dirsNeedingLlm, onProgr
             if (entriesToEnhance.length === 0)
                 return undefined;
             currentDirLabel = path.relative(currentStashDir, dirPath) || ".";
-            onProgress?.({
+            onProgress({
                 phase: "llm",
                 message: `Enhancing ${currentDirLabel} ` +
                     `(${entriesToEnhance.length} entr${entriesToEnhance.length === 1 ? "y" : "ies"}).`,
@@ -1491,27 +1254,35 @@ async function enhanceDirsWithLlm(db, config, execution, dirsNeedingLlm, onProgr
                 total: totalEntries,
             });
             lastProgressAt = Date.now();
-            const targetStash = { entries: entriesToEnhance };
-            const itemRefs = entriesToEnhance.map((entry) => {
-                const entryPath = entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
-                return indexedProvenanceForFile(db, entryPath).itemRef;
-            });
+            const entryPathOf = (entry) => entry.filename ? path.join(dirPath, entry.filename) : files[0] || dirPath;
+            const itemRefs = entriesToEnhance.map((entry) => indexedProvenanceForFile(db, entryPathOf(entry)).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);
+                enhanced = await enhanceEntriesWithLlm({
+                    llmRunner,
+                    entries: entriesToEnhance,
+                    itemRefs,
+                    files,
+                    db,
+                    config,
+                    summary,
+                    signal: enrichSignal,
+                    onNotices,
+                    onEntryDone: (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,
+                        });
+                    },
+                });
             }
             catch (err) {
                 if (err instanceof ConfigError) {
@@ -1523,16 +1294,15 @@ async function enhanceDirsWithLlm(db, config, execution, dirsNeedingLlm, onProgr
             // 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 searchText = buildSearchText(entry);
+                for (const entry of enhanced) {
+                    const entryPath = entryPathOf(entry);
                     const provenance = indexedProvenanceForFile(db, entryPath);
-                    upsertEntry(db, entryPath, attachFileSize(entry, entryPath), searchText, provenance);
+                    upsertEntry(db, entryPath, withFileSize(entry, entryPath), provenance);
                 }
             })();
             completedDirs++;
             lastProgressAt = Date.now();
-            onProgress?.({
+            onProgress({
                 phase: "llm",
                 message: `Completed ${completedDirs}/${totalDirs} director${totalDirs === 1 ? "y" : "ies"}; ` +
                     `${completedEntries}/${totalEntries} entr${totalEntries === 1 ? "y" : "ies"} processed.`,
@@ -1553,7 +1323,7 @@ async function enhanceDirsWithLlm(db, config, execution, dirsNeedingLlm, onProgr
         if (heartbeatTimer)
             clearInterval(heartbeatTimer);
     }
-    if (deadlineHit) {
+    if (enrichDeadline?.aborted) {
         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
@@ -1574,119 +1344,70 @@ export function createEnrichmentDeadline(timeoutMs, totalEntries) {
     return perEntryTimeoutMs === null ? undefined : AbortSignal.timeout(perEntryTimeoutMs * Math.max(totalEntries, 1));
 }
 // ── Helpers ─────────────────────────────────────────────────────────────────
-function attachFileSize(entry, entryPath) {
-    try {
-        const sized = { ...entry, fileSize: fs.statSync(entryPath).size };
-        if (hasMarkdownFragmentContent(entry))
-            setMarkdownFragmentContent(sized, getMarkdownFragmentContent(entry));
-        return sized;
-    }
-    catch {
-        return entry;
-    }
-}
 function buildIndexSummaryMessage(options) {
     const stashSourceLabel = options.sourcesCount === 1 ? "stash source" : "stash sources";
-    const semanticDetail = getSemanticSearchLabel(options.semanticSearchMode, options.embeddingProvider, options.vecAvailable);
+    const semanticDetail = options.semanticSearchMode === "off" ? "disabled" : `${options.embeddingProvider} embeddings`;
     return `Starting ${options.mode} index (${options.sourcesCount} ${stashSourceLabel}, semantic search: ${semanticDetail}, LLM: ${options.llmEnabled ? "enabled" : "disabled"}).`;
 }
 function getEmbeddingProvider(embedding) {
     return isHttpUrl(embedding?.endpoint) ? "remote" : "local";
 }
-function getSemanticSearchLabel(semanticSearchMode, embeddingProvider, vecAvailable) {
-    if (semanticSearchMode === "off")
-        return "disabled";
-    return `${embeddingProvider} embeddings, ${vecAvailable ? "sqlite-vec" : "JS fallback"}`;
-}
 function verifyIndexState(db, config, embeddableEntries, embeddingResult) {
     const embeddingCount = getEmbeddingCount(db);
-    const vecAvailable = isVecAvailable(db);
     const embeddingProvider = getEmbeddingProvider(config.embedding);
+    const verification = (ok, message, semanticSearchEnabled, semanticStatus, guidance) => ({
+        ok,
+        message,
+        ...(guidance !== undefined ? { guidance } : {}),
+        semanticSearchEnabled,
+        semanticSearchMode: config.semanticSearchMode,
+        semanticStatus,
+        embeddingProvider,
+        entryCount: embeddableEntries,
+        embeddingCount,
+    });
+    const pendingStatus = config.semanticSearchMode === "off" ? "disabled" : "pending";
     if (embeddableEntries === 0) {
-        return {
-            ok: true,
-            message: "Index ready. No assets were found yet.",
-            semanticSearchEnabled: config.semanticSearchMode === "auto",
-            semanticSearchMode: config.semanticSearchMode,
-            semanticStatus: config.semanticSearchMode === "off" ? "disabled" : "pending",
-            embeddingProvider,
-            entryCount: embeddableEntries,
-            embeddingCount,
-            vecAvailable,
-        };
+        return verification(true, "Index ready. No assets were found yet.", config.semanticSearchMode === "auto", pendingStatus);
     }
     if (config.semanticSearchMode === "off") {
-        return {
-            ok: true,
-            message: "Keyword index ready. Semantic search is disabled.",
-            semanticSearchEnabled: false,
-            semanticSearchMode: config.semanticSearchMode,
-            semanticStatus: "disabled",
-            embeddingProvider,
-            entryCount: embeddableEntries,
-            embeddingCount,
-            vecAvailable,
-        };
+        return verification(true, "Keyword index ready. Semantic search is disabled.", false, "disabled");
     }
     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, ${vecActive
-                ? "sqlite-vec active"
-                : vecAvailable
-                    ? "JS fallback active — vec fast path degraded; run 'akm index' to repair valid stored vectors or 'akm index --reembed' to regenerate incompatible ones"
-                    : "JS fallback active"}).`,
-            semanticSearchEnabled: true,
-            semanticSearchMode: config.semanticSearchMode,
-            semanticStatus: vecActive ? "ready-vec" : "ready-js",
-            embeddingProvider,
-            entryCount: embeddableEntries,
-            embeddingCount,
-            vecAvailable,
-        };
-    }
-    return {
-        ok: false,
-        message: embeddingResult.message ??
-            `Semantic search verification failed (${embeddingCount}/${embeddableEntries} embeddings available).`,
-        guidance: embeddingProvider === "remote"
-            ? "Check your embedding endpoint and credentials, then retry `akm index --full --verbose`."
-            : "Retry `akm index --full --verbose`. If it still fails, confirm local model downloads are permitted and see docs/reference/configuration.md for local embedding dependency setup.",
-        semanticSearchEnabled: true,
-        semanticSearchMode: config.semanticSearchMode,
-        semanticStatus: "blocked",
-        embeddingProvider,
-        entryCount: embeddableEntries,
-        embeddingCount,
-        vecAvailable,
-    };
-}
-function buildIndexedDirCandidate(dirPath, indexableFiles, generated) {
-    const stash = generated.entries.length > 0 ? { entries: generated.entries } : null;
-    const staleFiles = stash ? resolveIndexedFiles(dirPath, indexableFiles, stash) : indexableFiles;
-    return { stash, staleFiles };
-}
-function resolveIndexedFiles(dirPath, files, stash) {
-    const resolved = new Set();
-    for (const entry of stash.entries) {
-        if (entry.filename)
-            resolved.add(path.join(dirPath, entry.filename));
+        return verification(true, `Semantic search ready (${embeddingCount}/${embeddableEntries} embeddings).`, true, "ready-js");
     }
-    return resolved.size > 0 ? [...resolved] : files;
+    return verification(false, embeddingResult.message ??
+        `Semantic search verification failed (${embeddingCount}/${embeddableEntries} embeddings available).`, true, "blocked", embeddingProvider === "remote"
+        ? "Check your embedding endpoint and credentials, then retry `akm index --full --verbose`."
+        : "Retry `akm index --full --verbose`. If it still fails, confirm local model downloads are permitted and see docs/reference/configuration.md for local embedding dependency setup.");
 }
-async function enhanceStashWithLlm(llmRunner, stash, files, summary, signal, db, itemRefs, akmConfig, onEntryDone, onNotices, lease) {
+/**
+ * Enrich each entry through the LLM. `llm_enrichment_cache` (keyed by the
+ * canonical item ref + file body hash) skips the call when the body is
+ * unchanged.
+ */
+async function enhanceEntriesWithLlm(args) {
+    const { llmRunner, entries, itemRefs, files, db, config, summary, signal, onEntryDone, onNotices } = args;
     const { enhanceMetadata } = await import("../llm/metadata-enhance.js");
-    const { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } = await import("../storage/repositories/index-llm-cache-repository.js");
+    // failureSamples is bounded to 3 items, so a linear scan is cheaper than a
+    // parallel Set for membership checks (#177 review).
+    const recordFailure = (message) => {
+        if (summary.failureSamples.length < 3 && !summary.failureSamples.includes(message)) {
+            summary.failureSamples.push(message);
+        }
+    };
+    // The non-empty enrichment fields replace the entry's, and the entry is
+    // marked enriched so later runs skip it (P2).
+    const withEnrichment = (entry, metadata) => ({
+        ...entry,
+        ...(metadata.description ? { description: metadata.description } : {}),
+        ...(metadata.searchHints?.length ? { searchHints: metadata.searchHints } : {}),
+        ...(metadata.tags?.length ? { tags: metadata.tags } : {}),
+        quality: "enriched",
+    });
     let configFailure;
-    const results = await concurrentMap(stash.entries, async (entry, idx) => {
-        if (signal?.aborted)
+    const results = await concurrentMap(entries, async (entry, idx) => {
+        if (signal.aborted)
             return entry;
         summary.attempted++;
         try {
@@ -1702,36 +1423,23 @@ async function enhanceStashWithLlm(llmRunner, 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. The
-            // Cache metadata enrichment by the canonical durable item ref.
-            const cacheBody = fileContent ?? `${entry.name}\n${entry.description ?? ""}`;
-            const bodyHash = computeBodyHash(cacheBody);
-            const cacheKey = itemRefs?.[idx];
+            const bodyHash = enrichmentBodyHash(entry, fileContent);
+            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) {
-                    try {
-                        const parsed = JSON.parse(cached.resultJson);
-                        const updated = { ...entry };
-                        if (parsed.description)
-                            updated.description = parsed.description;
-                        if (parsed.searchHints?.length)
-                            updated.searchHints = parsed.searchHints;
-                        if (parsed.tags?.length)
-                            updated.tags = parsed.tags;
-                        updated.quality = "enriched";
-                        summary.succeeded++;
-                        onEntryDone?.({ entryName: entry.name, outcome: "cache-hit" });
-                        return updated;
-                    }
-                    catch {
-                        warn(`LLM enrichment cache entry corrupt for ${entry.name}; re-running enrichment`);
-                    }
+            const cached = getLlmCacheEntry(db, cacheKey, bodyHash);
+            if (cached) {
+                try {
+                    const updated = withEnrichment(entry, JSON.parse(cached.resultJson));
+                    summary.succeeded++;
+                    onEntryDone({ entryName: entry.name, outcome: "cache-hit" });
+                    return updated;
+                }
+                catch {
+                    warn(`LLM enrichment cache entry corrupt for ${entry.name}; re-running enrichment`);
                 }
             }
-            const outcome = await enhanceMetadata(llmRunner, entry, fileContent, signal, akmConfig, onNotices, lease);
+            const outcome = await enhanceMetadata(llmRunner, entry, fileContent, signal, config, onNotices);
             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
@@ -1739,57 +1447,35 @@ async function enhanceStashWithLlm(llmRunner, stash, files, summary, signal, db,
                 // entry into a permanent enrichment skip even though nothing was
                 // enhanced. Surface failures honestly; stay silent on gated-off skips.
                 if (outcome.status === "failed") {
-                    const msg = outcome.error ?? "metadata enrichment failed";
-                    if (summary.failureSamples.length < 3 && !summary.failureSamples.includes(msg)) {
-                        summary.failureSamples.push(msg);
-                    }
-                    onEntryDone?.({ entryName: entry.name, outcome: "failed" });
+                    recordFailure(outcome.error ?? "metadata enrichment failed");
+                    onEntryDone({ entryName: entry.name, outcome: "failed" });
                 }
                 else {
                     summary.skipped++;
-                    onEntryDone?.({ entryName: entry.name, outcome: "skipped" });
+                    onEntryDone({ entryName: entry.name, outcome: "skipped" });
                 }
                 return entry;
             }
-            const improvements = outcome.metadata;
-            const updated = { ...entry };
-            if (improvements.description)
-                updated.description = improvements.description;
-            if (improvements.searchHints?.length)
-                updated.searchHints = improvements.searchHints;
-            if (improvements.tags?.length)
-                updated.tags = improvements.tags;
-            // Mark as enriched so subsequent index runs skip re-enrichment (P2).
             // An empty-but-successful response is still cached: the LLM was paid
             // for this body_hash and produced no improvements, so re-running would
-            // only re-pay for the same no-op. (The cache protects against re-paying
-            // for the LLM call when the file body is unchanged.)
-            updated.quality = "enriched";
-            // Persist to cache so the next run can skip the LLM call when the
-            // file body has not changed.
-            if (db) {
-                upsertLlmCacheEntry(db, cacheKey, bodyHash, JSON.stringify({
-                    description: improvements.description,
-                    searchHints: improvements.searchHints,
-                    tags: improvements.tags,
-                }));
-            }
+            // only re-pay for the same no-op.
+            const improvements = outcome.metadata;
+            upsertLlmCacheEntry(db, cacheKey, bodyHash, JSON.stringify({
+                description: improvements.description,
+                searchHints: improvements.searchHints,
+                tags: improvements.tags,
+            }));
             summary.succeeded++;
-            onEntryDone?.({ entryName: entry.name, outcome: "llm" });
-            return updated;
+            onEntryDone({ entryName: entry.name, outcome: "llm" });
+            return withEnrichment(entry, improvements);
         }
         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).
-            if (summary.failureSamples.length < 3 && !summary.failureSamples.includes(msg)) {
-                summary.failureSamples.push(msg);
-            }
-            onEntryDone?.({ entryName: entry.name, outcome: "failed" });
+            recordFailure(toErrorMessage(err));
+            onEntryDone({ entryName: entry.name, outcome: "failed" });
             return entry;
         }
     }, 
@@ -1798,11 +1484,7 @@ async function enhanceStashWithLlm(llmRunner, stash, files, summary, signal, db,
     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).
-    const enhanced = results.map((r, i) => r ?? stash.entries[i]);
-    return { entries: enhanced };
+    return results.map((result, i) => result ?? entries[i]);
 }
 // ── lookup ─────────────────────────────────────────────────────────────────
 import { makeBundleRef } from "../core/asset/asset-ref.js";
@@ -1812,17 +1494,13 @@ async function resolveLookupSources() {
     const { resolveSourceEntries } = await import("./search/search-source.js");
     return resolveSourceEntries(undefined, loadConfig());
 }
-function resolveLookupScope(bundle, sources) {
-    if (!bundle)
-        return { candidateSources: sources, qualified: false };
-    return { candidateSources: resolveSourcesForOrigin(bundle, sources), qualified: true };
-}
 async function lookupBundleRefWithResolutionUsing(ref, openLookupDatabase) {
     const sources = await resolveLookupSources();
     if (sources.length === 0)
         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);
+    const bundleBySourcePath = new Map(sourceComponents(sources).map((component, index) => [path.resolve(sources[index].path), component.id]));
+    const qualified = Boolean(ref.bundle);
+    const candidateSources = ref.bundle ? resolveSourcesForOrigin(ref.bundle, sources) : sources;
     if (candidateSources.length === 0)
         return { entry: null };
     let db;
@@ -1833,6 +1511,11 @@ async function lookupBundleRefWithResolutionUsing(ref, openLookupDatabase) {
     catch (error) {
         indexError = error;
     }
+    const resolved = (entry, owner) => ({
+        entry,
+        ...(owner ? { owner } : {}),
+        ...(indexError === undefined ? {} : { indexError }),
+    });
     try {
         for (const source of candidateSources) {
             const adapterId = source.adapterId ?? detectAdapterId(source.path);
@@ -1855,21 +1538,21 @@ async function lookupBundleRefWithResolutionUsing(ref, openLookupDatabase) {
                             if (!(error instanceof WorkflowSourceIdentityError))
                                 throw error;
                             warn(`${error.message} Falling back to the physical owner.`);
-                            return { entry: null, owner, ...(indexError === undefined ? {} : { indexError }) };
+                            return resolved(null, owner);
                         }
                     }
                     else if (entry.adapterId !== adapterId || !indexedPathMatchesOwner(entry.filePath, owner)) {
-                        return { entry: null, owner, ...(indexError === undefined ? {} : { indexError }) };
+                        return resolved(null, owner);
                     }
-                    return { entry, owner, ...(indexError === undefined ? {} : { indexError }) };
+                    return resolved(entry, owner);
                 }
             }
             // 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 resolved(null, owner);
         }
-        return { entry: null, ...(indexError === undefined ? {} : { indexError }) };
+        return resolved(null);
     }
     finally {
         if (db)
@@ -1959,16 +1642,11 @@ const USAGE_EVENT_RETENTION_DAYS = 90;
  *
  * Called during `akm index` after FTS rebuild.
  */
-export function recomputeUtilityScores(db, stateDb, options) {
+export function recomputeUtilityScores(db, stateDb) {
     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, { stateSchema });
+    purgeOldUsageEvents(stateDb, USAGE_EVENT_RETENTION_DAYS);
     // Time-proportional decay: apply one round of EMA per elapsed day so
     // indexing frequency doesn't affect how fast scores decay.
     const lastComputedAt = getMeta(db, "last_utility_computed_at");
@@ -1999,7 +1677,7 @@ export function recomputeUtilityScores(db, stateDb, options) {
                  ELSE NULL
                END
              ) AS last_used_at
-      FROM ${usageEvents} u
+      FROM usage_events u
       WHERE u.entry_id IS NOT NULL
         AND u.source = 'user'
       GROUP BY u.entry_id