akm-cli 0.9.16-alpha.1 → 0.9.16

package/dist/indexer/indexer.js

@@ -4,80 +4,75 @@
 import fs from "node:fs";
 import path from "node:path";
 import { detectAdapterId } from "../core/adapter/detect-adapter.js";
-import { makeBundleRef } from "../core/asset/asset-ref.js";
-import { conceptIdFromTypeName } from "../core/asset/resolve-ref.js";
-import { isHttpUrl } from "../core/common.js";
-import { AkmError, TransientError } from "../core/errors.js";
+import { adapterForId } from "../core/adapter/registry.js";
+import { isHttpUrl, toErrorMessage } from "../core/common.js";
+import { concurrentMap } from "../core/concurrent.js";
+import { ConfigError } from "../core/errors.js";
 import { defaultConcurrencyForEndpoint } from "../core/loopback.js";
+import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
-import { isSqliteContentionError, withStateDb } from "../core/state-db.js";
-import { warn } from "../core/warn.js";
-import { DEFAULT_REMOTE_BATCH_SIZE } from "../llm/embedders/remote.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 { 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 { deleteEntriesByBundle, findEntryIdByRef, getEntryCount, relinkUsageEvents, } from "../storage/repositories/index-entries-repository.js";
-import { getMeta, setMeta } from "../storage/repositories/index-meta-repository.js";
-import { EMBEDDING_DIM } from "../storage/repositories/index-schema.js";
+import { deleteAllEntries, deleteEntriesByBundle, deleteEntriesByDirAndBundle, deleteEntriesByDirExceptRefs, deleteEntriesByIds, deleteUsageEventsByEntryIds, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedBundleIdsByDir, getIndexedDirPathsByBundleId, relinkUsageEvents, upsertEntry, } from "../storage/repositories/index-entries-repository.js";
+import { clearStaleCacheEntries, computeBodyHash, getLlmCacheEntry, } from "../storage/repositories/index-llm-cache-repository.js";
+import { deleteIndexDirState, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
 import { upsertUtilityScore } from "../storage/repositories/index-utility-repository.js";
-import { isVecAvailable } from "../storage/repositories/index-vec-repository.js";
-import { dropOtherIdentities, unitCoverage } from "../storage/repositories/units-repository.js";
+import { getEmbeddingCount, isVecAvailable, isVecFastPathReady, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
 import { assertIndexedWorkflowSourceIdentity, WorkflowSourceIdentityError } from "../workflows/source-files.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
-import { drainEmbeddingQueue } from "./drain.js";
-import { deriveInstallations } from "./installations.js";
+import { reclassifyIndexDbContention } from "./index-db-contention.js";
+import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
-import { reconcileRoots } from "./reconcile.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 { drainDirDocuments } from "./scan/drain-dir.js";
+import { buildSearchText } from "./search/search-fields.js";
 import { purgeOldUsageEvents } from "./usage/usage-events.js";
-/**
- * How many units an IMPLICIT (read-path bootstrap) run embeds before leaving
- * the rest of the queue to a later drain — one provider request's worth,
- * reusing `DEFAULT_REMOTE_BATCH_SIZE` (the per-request document cap in
- * `src/llm/embedders/remote.ts`) rather than a number picked here, so the
- * bound means something concrete: a first read waits on roughly one round
- * trip to the provider, not on the corpus.
- */
-const IMPLICIT_DRAIN_UNIT_LIMIT = DEFAULT_REMOTE_BATCH_SIZE;
+import { walkStashFlatWithStatus } from "./walk/walker.js";
+function collectLoweringNotices(target, notices) {
+    const keys = new Set(target.map((notice) => JSON.stringify(notice)));
+    for (const notice of notices) {
+        const key = JSON.stringify(notice);
+        if (keys.has(key))
+            continue;
+        keys.add(key);
+        target.push(notice);
+    }
+}
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw signal.reason instanceof Error ? signal.reason : new Error("index interrupted");
     }
 }
-/**
- * Bounded-pool width for the metadata-enrichment pass (`./enrich.ts`,
- * index-redesign B5e). An explicit `llmConfig.concurrency` wins (schema
- * field, though `resolveLlmEngineUse` never populates it on this path — see
- * AGENTS.md's LLM Defaults section — so this branch is effectively dead in
- * production but kept for direct callers/tests); otherwise it is
- * auto-derived from the endpoint via the ONE shared local-vs-remote
- * classifier (`defaultConcurrencyForEndpoint`, `core/loopback.ts`), also used
- * by the embedding pool (`resolveEmbeddingConcurrency`,
- * `src/llm/embedders/remote.ts`): 1 for a loopback endpoint (a local model
- * server serves one inference at a time; parallel requests cause "Model
- * reloaded" / HTTP 500 errors), 2 for a remote one. `./enrich.ts` calls
- * `defaultConcurrencyForEndpoint` directly rather than this wrapper to avoid
- * an indexer.ts → enrich.ts → indexer.ts import cycle (the same reason
- * `src/llm/embedders/remote.ts` cannot import this wrapper either); the two
- * stay behaviorally identical since the override branch never fires here.
- */
 export function getDefaultLlmConcurrency(llmConfig) {
     if (typeof llmConfig?.concurrency === "number")
         return llmConfig.concurrency;
+    // ONE classifier decides the local-vs-remote default (`core/loopback.ts`'s
+    // `defaultConcurrencyForEndpoint`), shared with the embedding pool
+    // (`resolveEmbeddingConcurrency`, `src/llm/embedders/remote.ts`) and the
+    // workflow engine's frozen concurrency default.
+    //
+    // The explicit-override branch above only fires for callers that put
+    // `concurrency` on the connection themselves — `engines.<name>.concurrency`
+    // is a valid schema field but `resolveLlmEngineUse` does NOT copy it into
+    // the resolved connection, so on the enrichment path the auto-derived 1/2
+    // is what runs (see docs/architecture/internals/indexing.md).
     return defaultConcurrencyForEndpoint(llmConfig?.endpoint);
 }
-/** Every currently-configured source's bundle id + resolved root, in installation-priority order. */
 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),
-                    ...(source.unresolved ? { unresolved: true } : {}),
-                },
-            ]
-            : [];
+        return installation ? [{ bundleId: installation.id, sourceRoot: path.resolve(source.path) }] : [];
     });
 }
 function parseStoredSourceOwners(raw) {
@@ -104,28 +99,336 @@ function parseStoredSourceOwners(raw) {
     }
 }
 /**
- * Delete entries (and their derived rows, via cascade) for any bundle that
- * was configured on the previous run and is not any more, or whose root
- * moved — `reconcileRoots` only walks CURRENT roots, so a removed bundle's
- * rows would otherwise never be revisited. Runs before `reconcileRoots` so
- * its own `pruneOrphanUnitTexts` sweep also collects any unit_texts this
- * orphans. A root no longer claimed by ANY current bundle also drops its
- * stored graph extraction (graph rows are keyed by root, not by entry, so
- * entry deletion above does not reach them).
+ * Source cache phase: ensure git stash caches are up to date and purge orphaned
+ * entries from removed sources (incremental only).
  */
-function removeStaleSourceOwners(db, currentOwners) {
-    const currentByBundle = new Map(currentOwners.map((owner) => [owner.bundleId, owner]));
-    const currentRoots = new Set(currentOwners.map((owner) => owner.sourceRoot));
-    for (const previous of parseStoredSourceOwners(getMeta(db, "sourceOwners"))) {
-        const current = currentByBundle.get(previous.bundleId);
-        if (current && current.sourceRoot === previous.sourceRoot)
-            continue;
-        if (!current)
-            deleteEntriesByBundle(db, previous.bundleId);
-        if (!currentRoots.has(previous.sourceRoot))
-            deleteStoredGraph(db, previous.sourceRoot);
+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 applyRemovedSources(ctx) {
+    if (!ctx.scanComplete)
+        return;
+    const currentRoots = new Set(sourceOwners(ctx.sources).map((owner) => owner.sourceRoot));
+    for (const removed of ctx.removedSources) {
+        if (removed.removeBundleEntries)
+            deleteEntriesByBundle(ctx.db, removed.bundleId);
+        if (!currentRoots.has(removed.sourceRoot))
+            deleteStoredGraph(ctx.db, removed.sourceRoot);
+    }
+}
+/**
+ * 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.");
+        }
+    }
+    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.
+ */
+export async function runEmbeddingPass(params) {
+    const { db, config, onProgress, signal, reembed } = params;
+    const embeddingResult = await generateEmbeddingsForDb(db, config, onProgress, signal, undefined, {
+        forceReembed: reembed,
+    });
+    setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
+    const semanticEntryCount = getEmbeddableEntryCount(db);
+    onProgress({ phase: "finalize", message: "Verifying semantic search state." });
+    const verification = verifyIndexState(db, config, semanticEntryCount, embeddingResult);
+    onProgress({ phase: "verify", message: verification.message });
+    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.
+ */
+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();
+    // Re-link state.db usage events to the regenerated index and recompute the
+    // derived utility cache. Stored refs already use the current item-ref grammar,
+    // so this idempotent pass only restores derived entry ids.
+    const mutateState = (stateDb, stateSchema) => {
+        onProgress({ phase: "finalize", message: "Relinking usage events." });
+        relinkUsageEvents(db, stateDb, { sources, defaultStashDir: stashDir, stateSchema });
+        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);
+    }
+    // Purge LLM cache entries for assets that no longer exist in the index.
+    try {
+        onProgress({ phase: "finalize", message: "Clearing stale LLM cache entries." });
+        clearStaleCacheEntries(db);
+    }
+    catch {
+        /* ignore */
+    }
+    throwIfAborted(signal);
+    // 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) {
+        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;
+}
+// ── Clean pass ───────────────────────────────────────────────────────────────
+/**
+ * Missing-file reconciliation: scan the `entries` table for rows whose source
+ * file no longer exists on disk and remove them (unless `dryRun` is true).
+ *
+ * Only rows with a non-empty `file_path` are checked — remote/virtual entries
+ * that have no local path are always skipped.
+ *
+ * "No longer exists" means ABSENT, never merely unreadable (#791). This pass
+ * DELETES rows, and `fs.existsSync` reported `false` for a file akm lacked
+ * permission to look at exactly as for one that had been removed — so a
+ * bundle temporarily mounted read-restricted (a uid mismatch, a tightened
+ * parent directory) had its whole index wiped, and the run reported the
+ * deletions as a clean success. Unreadable files keep their rows and are
+ * reported instead.
+ */
+function runCleanPass(db, dryRun) {
+    const allEntries = db.prepare("SELECT id, item_ref AS ref, file_path AS path FROM entries").all();
+    // Only check entries that have a non-empty local path (skip remote/virtual).
+    const localEntries = allEntries.filter((e) => typeof e.path === "string" && e.path.trim() !== "");
+    const missing = [];
+    const unreadable = [];
+    for (const entry of localEntries) {
+        const { access, code } = classifyPathAccess(entry.path);
+        if (access === "absent")
+            missing.push(entry);
+        else if (access === "inaccessible")
+            unreadable.push({ path: entry.path, ...(code ? { code } : {}) });
+    }
+    if (unreadable.length > 0) {
+        const shown = unreadable.slice(0, 5).map((u) => describeInaccessiblePath(u.path, u.code));
+        warn(`Index clean pass kept ${unreadable.length} entr${unreadable.length === 1 ? "y" : "ies"} whose file akm cannot ` +
+            `read (unreadable is not deleted): ${shown.join("; ")}${unreadable.length > shown.length ? "; …" : ""}`);
+    }
+    if (!dryRun && missing.length > 0) {
+        deleteEntriesByIds(db, missing.map((e) => e.id));
+    }
+    return {
+        checked: localEntries.length,
+        removed: dryRun ? 0 : missing.length,
+        removedRefs: missing.map((e) => e.ref),
+        dryRun,
+    };
+}
+// ── Indexer ──────────────────────────────────────────────────────────────────
+// ── Test seam ────────────────────────────────────────────────────────────────
+// Swap-and-restore override. Inert in production; only tests call the setter.
+let akmIndexOverride;
+/** TEST-ONLY. Swap the implementation of `akmIndex`; pass undefined to restore. */
+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);
     }
 }
+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).
+ */
+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
+ * `drainDirDocuments` — the per-file read/sha256-hash/frontmatter-parse step
+ * (#900) — with the directory path and its walked file count. `undefined`
+ * restores. A directory the pre-drain gate (`getCachedDirState`) skips never
+ * fires this observer, so it is the
+ * seam #900's own tests use to assert an unchanged directory's files are
+ * never read on a no-op incremental run.
+ */
+export function _setDrainObserverForTests(observer) {
+    drainObserverForTests = observer;
+}
 /**
  * Detect an adapter for every resolvable source that does not declare one, and
  * persist each detection into `config.json`.
@@ -137,6 +440,10 @@ function removeStaleSourceOwners(db, currentOwners) {
  * 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();
@@ -183,10 +490,695 @@ 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,
+    // embeddings, FTS, the adapter-detection config write) ran for real
+    // regardless, so `akm index --dry-run` alone silently performed a full,
+    // real index. The flag's own docs (`IndexOptions.dryRun` above, and the
+    // CLI help in stash-cli.ts) already scope it to `--clean`; reject the
+    // combination that was never implemented instead of quietly doing
+    // something other than what "dry run" promised. Checked before the writer
+    // lease is even requested so a bad invocation fails instantly.
+    if (options?.dryRun === true && options?.clean !== true) {
+        const { UsageError } = await import("../core/errors.js");
+        throw new UsageError("`--dry-run` only applies together with `--clean` (it previews which stale entries `--clean` would remove). " +
+            "Pass `akm index --clean --dry-run`, or drop `--dry-run` to run a real index.", "INVALID_FLAG_VALUE", "Run `akm index --clean --dry-run` to preview, or `akm index --clean` to apply.");
+    }
+    const requestedAt = Date.now();
+    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,
+        });
+        config = detected.config;
+        const persistedAdapters = detected.persistedAdapters;
+        const allSourceDirs = allSourceEntries.map((s) => s.path);
+        onProgress({
+            phase: "preflight",
+            message: `Resolved ${allSourceDirs.length} stash source${allSourceDirs.length === 1 ? "" : "s"}.`,
+        });
+        const t0 = Date.now();
+        const enrichmentExecution = resolveIndexPassExecution("enrichment", config);
+        // Open database — pass embedding dimension from config if available
+        const dbPath = getDbPath();
+        const embeddingDim = config.embedding?.dimension;
+        const borrowedUpdateDb = options.deferredUpdateTransaction?.db;
+        const db = borrowedUpdateDb ?? openIndexDatabase(dbPath, embeddingDim ? { embeddingDim } : undefined);
+        if (borrowedUpdateDb && !borrowedUpdateDb.inTransaction) {
+            throw new Error("Source update index requires an active borrowed index transaction.");
+        }
+        let indexRunContext;
+        try {
+            // 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;
+            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),
+                }),
+            });
+            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 };
+                }
+            }
+            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);
+            }
+            if (!borrowedUpdateDb)
+                closeDatabase(db);
+        }
+    })();
+}
+function buildIndexedSourceOwners(sources) {
+    const installations = deriveInstallations([...sources]);
+    const owners = new Map();
+    sources.forEach((source, index) => {
+        const installation = installations[index];
+        if (!installation)
+            return;
+        const component = installation.components[0];
+        owners.set(path.resolve(source.path), {
+            bundleId: installation.id,
+            componentId: component?.id ?? installation.id,
+            adapterId: component?.adapter ?? "akm",
+        });
+    });
+    return owners;
+}
+/** Read-only mirror of the enrichment cache gate used before entry persistence. */
+function dirRecordsNeedMetadataDispatch(db, records, ownersByRoot) {
+    for (const record of records) {
+        if (record.skip || record.remove || !record.stash)
+            continue;
+        const owner = ownersByRoot.get(path.resolve(record.currentStashDir));
+        if (!owner)
+            throw new Error(`Missing bundle provenance for indexed source ${record.currentStashDir}`);
+        for (const entry of record.stash.entries) {
+            if (entry.quality !== "generated" || isEnrichmentComplete(entry))
+                continue;
+            const entryFile = entry.filename ? path.join(record.dirPath, entry.filename) : undefined;
+            if (!entryFile)
+                continue;
+            const adapterConceptId = record.conceptIdByFile?.get(entryFile);
+            if (!adapterConceptId)
+                continue;
+            let fileContent;
+            try {
+                fileContent = fs.readFileSync(entryFile, "utf8");
+            }
+            catch {
+                // The dispatch path uses the same deterministic metadata fallback.
+            }
+            const bodyHash = computeBodyHash(fileContent ?? `${entry.name}\n${entry.description ?? ""}`);
+            const cacheKey = deriveEntryProvenance(owner, entry.type, entry.name, adapterConceptId).itemRef;
+            const cached = getLlmCacheEntry(db, cacheKey, bodyHash);
+            if (!cached)
+                return true;
+            try {
+                JSON.parse(cached.resultJson);
+            }
+            catch {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function removalsFirst(records) {
+    return [...records.filter((record) => record.remove), ...records.filter((record) => !record.remove)];
+}
+function addEntryIds(target, ids) {
+    for (const id of ids)
+        target.add(id);
+}
+/**
+ * Map each source root → its durable `BundleComponent` (`deriveInstallations`,
+ * batch-unique bundle ids, source order preserved). The per-dir document drain
+ * dispatches `adapterForId(component.adapter).recognize` for this component. The
+ * component id only surfaces on `IndexDocument.ref`, which the persist layer
+ * re-derives independently — so a source missing from the map (never happens: the
+ * map is built from the same sources) is harmless.
+ */
+function buildComponentBySource(sources) {
+    const map = new Map();
+    const installations = deriveInstallations(sources);
+    sources.forEach((source, i) => {
+        const component = installations[i]?.components[0];
+        if (component)
+            map.set(source.path, component);
+    });
+    return map;
+}
+function componentForSource(components, sourcePath) {
+    return (components.get(sourcePath) ?? {
+        id: sourcePath,
+        adapter: "akm",
+        root: sourcePath,
+        writable: false,
+    });
+}
+function groupFileContextsByDir(fileContexts) {
+    const groups = new Map();
+    for (const ctx of fileContexts) {
+        const group = groups.get(ctx.parentDirAbs);
+        if (group)
+            group.push(ctx);
+        else
+            groups.set(ctx.parentDirAbs, [ctx]);
+    }
+    return groups;
+}
+function sourceSnapshotRemovals(db, currentStashDir, bundleId, currentDirs, allIndexedDirsByBundle) {
+    const indexedDirs = allIndexedDirsByBundle?.get(bundleId) ?? getIndexedDirPathsByBundleId(db, bundleId);
+    return [...indexedDirs]
+        .map((dirPath) => path.resolve(dirPath))
+        .filter((dirPath) => !currentDirs.has(dirPath))
+        .map((dirPath) => ({
+        dirPath,
+        currentStashDir,
+        files: [],
+        stash: null,
+        skip: false,
+        remove: true,
+        reason: { kind: "not-in-source-snapshot" },
+    }));
+}
+/**
+ * Warn ONCE per process (#908) when the chosen adapter for a component
+ * entirely skips a top-level directory that holds files the `akm` adapter —
+ * the format-neutral superset — would have indexed. `detectAdapterId` now
+ * corrects this for AUTO-DETECTION (a mixed layout detects as `akm`); this
+ * covers the case detection cannot see, an EXPLICITLY configured narrow
+ * adapter (`components.<name>.adapter: "agent-skills"`, say) sitting next to
+ * ordinary akm content. One line for the whole process — not one per bundle,
+ * not one per directory — naming the count and the directories is enough to
+ * point an operator at the fix.
+ */
+function warnIfAdapterSkipsAkmContent(component, files, adapter) {
+    if (adapter.id === "akm")
+        return;
+    const akm = adapterForId("akm");
+    if (!akm)
+        return;
+    const byTopDir = new Map();
+    for (const file of files) {
+        const top = file.ancestorDirs[0];
+        if (!top)
+            continue; // a root-level file is not a "skipped directory" concern
+        const group = byTopDir.get(top);
+        if (group)
+            group.push(file);
+        else
+            byTopDir.set(top, [file]);
+    }
+    const akmComponent = { ...component, adapter: "akm" };
+    let skippedCount = 0;
+    const skippedDirs = [];
+    for (const [dir, dirFiles] of byTopDir) {
+        const chosenRecognizesAny = dirFiles.some((file) => {
+            try {
+                return adapter.recognize(component, file) !== null;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (chosenRecognizesAny)
+            continue; // the chosen adapter owns this dir; nothing skipped
+        const akmCandidates = dirFiles.filter((file) => {
+            try {
+                return akm.recognize(akmComponent, file) !== null;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (akmCandidates.length === 0)
+            continue; // akm would drop it too — not a shadowing case
+        skippedCount += akmCandidates.length;
+        skippedDirs.push(dir);
+    }
+    if (skippedCount === 0)
+        return;
+    skippedDirs.sort();
+    warnOnce("adapter-skip-akm-content", `${adapter.id} adapter skipped ${skippedCount} file${skippedCount === 1 ? "" : "s"} in ` +
+        `${skippedDirs.map((dir) => `${dir}/`).join(", ")} — set components.<name>.adapter to "akm" to index them`);
+}
+function buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMissingDirs) {
+    const componentBySource = buildComponentBySource(allSourceEntries);
+    const handoffDirs = new Set();
+    const plans = allSourceEntries.map((sourceAdded) => {
+        const currentStashDir = sourceAdded.path;
+        const component = componentForSource(componentBySource, currentStashDir);
+        if (sourceAdded.unresolved) {
+            return {
+                currentStashDir,
+                component,
+                adapter: undefined,
+                indexVariant: undefined,
+                dirGroups: new Map(),
+                removals: [],
+                walkComplete: false,
+            };
+        }
+        const walked = walkStashFlatWithStatus(currentStashDir, {
+            includeAllDirectories: component.adapter === "okf",
+            ...(component.adapter === "akm" || component.adapter === "akm-workflow"
+                ? { workflowSymlinkAdapter: component.adapter }
+                : {}),
+        });
+        const dirGroups = groupFileContextsByDir(walked.files);
+        const adapter = adapterForId(component.adapter);
+        if (adapter)
+            warnIfAdapterSkipsAkmContent(component, walked.files, adapter);
+        return {
+            currentStashDir,
+            component,
+            adapter,
+            indexVariant: adapter ? `${adapter.id}@${adapter.version}` : undefined,
+            dirGroups,
+            removals: [],
+            walkComplete: walked.complete,
+        };
+    });
+    const removalKeys = new Set();
+    const addRemoval = (plan, dirPath, stashDir) => {
+        const resolvedDir = path.resolve(dirPath);
+        const key = `${resolvedDir}\0${path.resolve(stashDir)}`;
+        if (removalKeys.has(key))
+            return;
+        removalKeys.add(key);
+        plan.removals.push({
+            dirPath,
+            currentStashDir: stashDir,
+            files: [],
+            stash: null,
+            skip: false,
+            remove: true,
+            reason: { kind: "not-in-source-snapshot" },
+        });
+        handoffDirs.add(resolvedDir);
+    };
+    const allComplete = plans.every((plan) => plan.walkComplete && plan.adapter !== undefined);
+    // A full, globally-complete run uses the atomic table wipe below. Every
+    // other run reconciles only sources that produced trustworthy snapshots.
+    if (reconcileMissingDirs && (isIncremental || !allComplete)) {
+        const allIndexedDirsByBundle = !isIncremental ? new Map() : undefined;
+        if (allIndexedDirsByBundle) {
+            for (const entry of getAllEntries(db)) {
+                const dirs = allIndexedDirsByBundle.get(entry.bundleId) ?? new Set();
+                dirs.add(path.dirname(path.resolve(entry.filePath)));
+                allIndexedDirsByBundle.set(entry.bundleId, dirs);
+            }
+        }
+        for (const plan of plans) {
+            if (!plan.walkComplete || !plan.adapter)
+                continue;
+            const currentDirs = new Set([...plan.dirGroups.keys()].map((dirPath) => path.resolve(dirPath)));
+            for (const removal of sourceSnapshotRemovals(db, plan.currentStashDir, plan.component.id, currentDirs, allIndexedDirsByBundle)) {
+                addRemoval(plan, removal.dirPath, removal.currentStashDir);
+            }
+        }
+    }
+    // Cross-source ownership handoffs can delete another source's rows, so they
+    // still require every possible owner to have completed its scan.
+    if (!allComplete)
+        return { plans, handoffDirs };
+    // The first configured source that exposes a physical directory owns it.
+    // Remove rows left by a prior owner even when both adapters are identical.
+    const claimedDirs = new Set();
+    const sourcePathByBundle = new Map(plans.map((plan) => [plan.component.id, plan.currentStashDir]));
+    for (const plan of plans) {
+        for (const dirPath of plan.dirGroups.keys()) {
+            const resolvedDir = path.resolve(dirPath);
+            if (claimedDirs.has(resolvedDir))
+                continue;
+            claimedDirs.add(resolvedDir);
+            for (const priorOwnerBundle of getIndexedBundleIdsByDir(db, dirPath)) {
+                if (priorOwnerBundle !== plan.component.id) {
+                    const priorOwnerPath = sourcePathByBundle.get(priorOwnerBundle);
+                    if (priorOwnerPath)
+                        addRemoval(plan, dirPath, priorOwnerPath);
+                }
+            }
+        }
+    }
+    return { plans, handoffDirs };
+}
 /**
- * `detectAndPersistBundleAdapters` only auto-detects an adapter for a source
- * root that exists and can be listed — an unreadable/missing root gets no
- * silent guess.
+ * Phase 1 (async): walk every source directory and pre-generate all metadata
+ * outside any transaction, producing the per-directory scan records that
+ * {@link persistDirRecords} later writes.
+ *
+ * The per-dir document drain (`drainDirDocuments` × the component's dispatched
+ * `adapter.recognize`, F4a M-core-2) is synchronous, but the walk still runs
+ * outside `db.transaction()` so the persist pass can be a single synchronous
+ * transaction.
+ */
+function reportSourceScanProgress(onProgress, processed, total, message) {
+    onProgress?.({ phase: "scan", message, processed, total });
+}
+async function scanSourceDirs(db, allSourceEntries, isIncremental, builtAtMs, hadRemovedSources, onProgress, reconcileMissingDirs = true) {
+    let scannedDirs = 0;
+    let skippedDirs = 0;
+    let generatedCount = 0;
+    const warnings = [];
+    const seenPaths = new Set();
+    const { plans, handoffDirs } = buildSourceScanPlans(db, allSourceEntries, isIncremental, reconcileMissingDirs);
+    const dirRecords = [];
+    let processedDirs = 0;
+    let priorDirsChanged = hadRemovedSources;
+    const reportScanProgress = (message) => reportSourceScanProgress(onProgress, processedDirs, allSourceEntries.length, message);
+    const reportDirDecision = (kind, dirPath, currentStashDir, reason, persistedRowCount) => {
+        if (!isVerbose())
+            return;
+        const detail = reason.detail ? ` (${reason.detail})` : "";
+        const rowInfo = persistedRowCount !== undefined ? `; previous rows=${persistedRowCount}` : "";
+        reportScanProgress(`${kind === "scan" ? "Rescanning" : "Skipping"} ${path.relative(currentStashDir, dirPath) || "."} ` +
+            `from ${currentStashDir}: ${reason.kind}${detail}${rowInfo}`);
+    };
+    // Only the first source that exposes a physical directory may index it.
+    const markSeenOrSkipDuplicate = (dirPath, currentStashDir, files) => {
+        const resolved = path.resolve(dirPath);
+        if (seenPaths.has(resolved)) {
+            const reason = { kind: "duplicate-dir" };
+            dirRecords.push({ dirPath, currentStashDir, files, stash: null, skip: true, reason });
+            reportDirDecision("skip", dirPath, currentStashDir, reason);
+            return true;
+        }
+        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++;
+        reportScanProgress(`Processed ${processedDirs}/${allSourceEntries.length} source${allSourceEntries.length === 1 ? "" : "s"}.`);
+        if (!walkComplete) {
+            for (const dirPath of dirGroups.keys())
+                seenPaths.add(path.resolve(dirPath));
+            warn(`[index] source "${component.id}" was not scanned completely; preserving its last-known-good rows.`);
+            continue;
+        }
+        // Owner ruling 2026-07-21: dispatch each component's DETECTED adapter (§4).
+        // An unknown adapter id has no `adapterForId` match → skip the whole
+        // component with a warning (one bundle = one component = one adapter).
+        if (!adapter) {
+            for (const dirPath of dirGroups.keys())
+                seenPaths.add(path.resolve(dirPath));
+            warn(`Skipping component "${component.id}": unknown adapter id "${component.adapter}".`);
+            continue;
+        }
+        const indexVariant = plan.indexVariant ?? `${adapter.id}@${adapter.version}`;
+        for (const removal of removals) {
+            dirRecords.push(removal);
+            scannedDirs++;
+            priorDirsChanged = true;
+            reportDirDecision("scan", removal.dirPath, currentStashDir, removal.reason);
+        }
+        for (const [dirPath, ctxs] of dirGroups) {
+            // Adapter-owned filtering (owner ruling 2026-07-21): the drain no longer
+            // pre-filters with AKM-stash policy — each adapter's `recognize` claims or
+            // abstains on its own bundle's walked files. The core walk keeps only the
+            // universal hygiene `walkStashFlat` already applies (.git/dot-dirs/etc.).
+            const indexableFiles = ctxs.map((ctx) => ctx.absPath);
+            const forceScan = handoffDirs.has(path.resolve(dirPath)) || requiresWorkflowSourcePreflight(ctxs);
+            if (markSeenOrSkipDuplicate(dirPath, currentStashDir, indexableFiles))
+                continue;
+            if (indexableFiles.length === 0) {
+                skippedDirs++;
+                const reason = { kind: "no-indexable-files" };
+                dirRecords.push({ dirPath, currentStashDir, files: indexableFiles, stash: null, skip: true, reason });
+                reportDirDecision("skip", dirPath, currentStashDir, reason);
+                continue;
+            }
+            // #900: decide from stat data alone whether the directory can be skipped,
+            // before drainDirDocuments reads, hashes, and parses every file.
+            const fingerprint = computeDirFingerprint(dirPath, indexableFiles, indexVariant);
+            const cachedState = isIncremental &&
+                !forceScan &&
+                getCachedDirState(db, dirPath, indexableFiles, builtAtMs, priorDirsChanged, indexVariant, fingerprint);
+            if (cachedState) {
+                skippedDirs++;
+                dirRecords.push({
+                    dirPath,
+                    currentStashDir,
+                    files: indexableFiles,
+                    stash: null,
+                    skip: true,
+                    reason: cachedState.reason,
+                    indexVariant,
+                });
+                reportDirDecision("skip", dirPath, currentStashDir, cachedState.reason, cachedState.persistedRowCount);
+                continue;
+            }
+            // F4a M-core-2 (the flip): drain the dir's `IndexDocument` stream via the
+            // component's dispatched `adapter.recognize` (broken workflows dropped-with-
+            // warning at the drain layer) and reconstruct the durable `IndexDocument`s.
+            drainObserverForTests?.(dirPath, ctxs.length);
+            const drained = drainDirDocuments(adapter, component, ctxs);
+            if (drained.warnings.length)
+                warnings.push(...drained.warnings);
+            const generated = drained.warnings.length
+                ? { entries: drained.entries, warnings: drained.warnings }
+                : { entries: drained.entries };
+            // `.stash.json` sidecar overrides retired (#39): the cutover's content
+            // migration folded sidecar metadata into frontmatter and deleted the
+            // files; the runtime no longer reads them.
+            const { stash, staleFiles } = buildIndexedDirCandidate(dirPath, indexableFiles, generated);
+            if (generated.entries.length > 0) {
+                generatedCount += generated.entries.length;
+            }
+            recordFreshnessDecision(dirPath, currentStashDir, staleFiles, fingerprint, stash, drained.hashByFile, drained.conceptIdByFile, indexVariant, forceScan, walkComplete);
+        }
+    }
+    return {
+        dirRecords: removalsFirst(dirRecords),
+        scannedDirs,
+        skippedDirs,
+        generatedCount,
+        warnings,
+        complete: plans.every((plan) => plan.walkComplete && plan.adapter !== undefined),
+    };
+}
+function requiresWorkflowSourcePreflight(ctxs) {
+    return ctxs.some((ctx) => {
+        try {
+            return fs.lstatSync(ctx.absPath).isSymbolicLink();
+        }
+        catch {
+            return true;
+        }
+    });
+}
+function preserveExistingIndex(doFullDelete, dirRecords, sourceRoots) {
+    if (!doFullDelete)
+        return false;
+    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) {
@@ -194,7 +1186,7 @@ function allSourceRootsReadable(roots) {
             const st = fs.statSync(root);
             if (!st.isDirectory())
                 return false;
-            fs.readdirSync(root);
+            fs.readdirSync(root); // probe readability, not just existence
         }
         catch {
             return false;
@@ -202,133 +1194,424 @@ function allSourceRootsReadable(roots) {
     }
     return true;
 }
-// ── Indexer ──────────────────────────────────────────────────────────────────
-// ── Test seam ────────────────────────────────────────────────────────────────
-// Swap-and-restore override. Inert in production; only tests call the setter.
-let akmIndexOverride;
-/** TEST-ONLY. Swap the implementation of `akmIndex`; pass undefined to restore. */
-export function _setAkmIndexForTests(fake) {
-    akmIndexOverride = fake;
-}
 /**
- * Reclassify a contention-shaped error escaping reconcile or drain into a
- * retryable-shortly `TransientError` (field follow-up to #956): a concurrent
- * writer can make index.db busy, and the raw SQLite driver error ("database is
- * locked") used to escape as exit 70 (internal/unclassified) instead of the
- * "retry shortly" contract exit 75 gives a scheduler to branch on — mirroring
- * `STATE_DB_CONTENDED`'s precedent for state.db (`core/state-db.ts`). Reuses
- * the ONE shared classifier, `isSqliteContentionError`, rather than a second
- * one. An error that is already a classified akm error is never re-wrapped —
- * only a raw, unclassified error matching the shared contention shape is
- * reclassified. Every other error is rethrown unchanged.
- *
- * index-redesign note: under the new design (docs/plans/index-redesign.md,
- * rule 5) every index write is a short immediate transaction under WAL with
- * SQLite's own busy timeout — no rebuild lock, no writer lock on the index
- * path — so genuine contention is rarer, but still possible when two
- * processes race the same file, and the reclassification still matters when
- * it happens.
+ * Phase 2 (sync): write all pre-generated scan records inside a single
+ * transaction, returning the directories that still need LLM enrichment.
  */
-export function reclassifyIndexDbContention(error) {
-    if (error instanceof AkmError || !isSqliteContentionError(error))
-        return error;
-    const contended = new TransientError("akm's index database is busy (another akm process is writing it); retry shortly.", "INDEX_DB_CONTENDED");
-    contended.cause = error;
-    return contended;
+function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots, scanComplete, bundleByRoot) {
+    const dirsNeedingLlm = [];
+    const fullDelete = doFullDelete && scanComplete;
+    // #624-P1 zero-document preflight (spec §4). A full-rebuild wipe is a
+    // legitimate mass-delete ONLY when the scan legitimately found nothing. If
+    // the walk produced zero documents AND any configured source root is missing
+    // or unreadable, the empty result is almost certainly a transient scan
+    // failure, not an emptied stash — wiping here would cascade-destroy the
+    // last-known-good index (entries + embeddings + utility/usage). Preserve it
+    // and warn instead; the next successful run reconciles. A genuinely empty
+    // stash whose roots ARE readable still wipes, as before.
+    if (preserveExistingIndex(fullDelete, dirRecords, sourceRoots))
+        return { dirsNeedingLlm };
+    // Per-source dedup: the same logical asset can appear more than once within
+    // one owning source, where source order still makes the first occurrence win.
+    // The owner is part of the key so identical concepts in different bundles
+    // remain distinct indexed rows.
+    const indexedAssetIdentities = new Set();
+    const deletedUsageEntryIds = new Set();
+    const insertTransaction = db.transaction(() => {
+        // Perform the full-rebuild wipe as the FIRST step of the insert
+        // transaction so delete and re-insert are atomic — a concurrent reader
+        // never observes an empty database between the two operations.
+        if (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) {
+            const bundle = bundleByRoot.get(path.resolve(currentStashDir));
+            if (!bundle)
+                throw new Error(`Missing bundle provenance for indexed source ${currentStashDir}`);
+            if (remove) {
+                const removedIds = deleteEntriesByDirAndBundle(db, dirPath, bundle.bundleId, {
+                    cleanupUsageEvents: false,
+                });
+                addEntryIds(deletedUsageEntryIds, removedIds);
+                deleteIndexDirState(db, dirPath);
+                continue;
+            }
+            if (skip) {
+                // "unchanged" is the post-drain verdict: re-persist so the row carries
+                // 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 });
+                }
+                continue;
+            }
+            // Diff-persist (F4a M-core-2, spec §14.2): upsert the current file set
+            // FIRST (ON CONFLICT preserving `entries.id` so embeddings / utility /
+            // usage stay attached to unchanged rows), tracking every upserted
+            // durable `item_ref`, then prune only the departed rows below. Replaces the old
+            // `deleteEntriesByDir` truncate-and-reinsert (which discarded ids).
+            const keptItemRefs = new Set();
+            let persistedRows = 0;
+            let dedupedRows = 0;
+            if (stash) {
+                const ownerIdentity = bundle.bundleId;
+                for (const entry of stash.entries) {
+                    const entryPath = entry.filename ? path.join(dirPath, entry.filename) : null;
+                    if (!entryPath) {
+                        warn(`Skipping entry with no resolvable path in ${dirPath}`);
+                        continue;
+                    }
+                    const adapterConceptId = conceptIdByFile?.get(entryPath);
+                    if (!adapterConceptId) {
+                        warn(`Skipping entry without adapter-owned concept identity: ${entryPath}`);
+                        continue;
+                    }
+                    // Adapter-owned concept identity is path-based and cannot be replaced
+                    // by presentation fields such as type/title.
+                    const identityKey = `${ownerIdentity}\0${adapterConceptId}`;
+                    if (indexedAssetIdentities.has(identityKey)) {
+                        dedupedRows++;
+                        continue;
+                    }
+                    indexedAssetIdentities.add(identityKey);
+                    const 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++;
+                }
+                // 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 });
+                }
+            }
+            // 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 }));
+            }
+            const persistedFingerprint = fingerprint ?? computeDirFingerprint(dirPath, files, indexVariant);
+            const persistedReason = persistedRows === 0
+                ? inferZeroRowReason(stash, reason, warnings, dirPath, dedupedRows)
+                : reason?.kind === "full-rebuild"
+                    ? "full-rebuild"
+                    : (reason?.kind ?? "updated");
+            upsertIndexDirState(db, {
+                dirPath,
+                ...persistedFingerprint,
+                reason: persistedReason,
+                // A directory that lost rows to per-source dedup depends on the
+                // directories persisted before it, not only on its own files, so it
+                // 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,
+            });
+            if (persistedRows === 0) {
+                // Warn only when the dir had files that *could* produce entries (.md or
+                // known script extensions). Dirs with only non-indexable types (.json,
+                // .yaml, .conf, .env, .gitkeep) or deduped-only rows are expected and
+                // not actionable at normal log level.
+                const hasIndexableExtension = files.some((f) => {
+                    const ext = path.extname(f).toLowerCase();
+                    return ext === ".md" || SCRIPT_EXTENSIONS.has(ext);
+                });
+                if (persistedReason !== "deduped-zero-row" && hasIndexableExtension) {
+                    warn(`[index] zero-row ${dirPath}: ${persistedReason}`);
+                }
+                else {
+                    warnVerbose(`[index] zero-row ${dirPath}: ${persistedReason}`);
+                }
+            }
+        }
+        // Atomicity observation point: the new generation is fully written but
+        // uncommitted, so it must still be invisible to other connections.
+        indexTransactionHook("records-persisted");
+    });
+    insertTransaction();
+    deleteUsageEventsByEntryIds([...deletedUsageEntryIds]);
+    return { dirsNeedingLlm };
 }
-export async function akmIndex(options) {
-    try {
-        const override = akmIndexOverride;
-        return override ? await override(options) : await akmIndexReal(options);
+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, " +
+        "concept_id AS conceptId, adapter_id AS adapterId FROM entries WHERE file_path = ? LIMIT 1")
+        .get(filePath);
+    if (!row?.itemRef || !row.bundleId || !row.componentId || !row.conceptId || !row.adapterId) {
+        throw new Error(`Missing indexed provenance for ${filePath}`);
     }
-    catch (error) {
-        const updateDb = options.deferredUpdateTransaction?.db;
-        if (updateDb?.inTransaction) {
+    return {
+        itemRef: row.itemRef,
+        bundleId: row.bundleId,
+        componentId: row.componentId,
+        conceptId: row.conceptId,
+        adapterId: row.adapterId,
+    };
+}
+async function enhanceDirsWithLlm(db, config, execution, dirsNeedingLlm, onProgress, signal, onNotices, lease) {
+    // The invocation owns one frozen symbolic selection. Summary reporting and
+    // every enrichment dispatch consume this same snapshot.
+    const llmRunner = execution.runner;
+    if (!llmRunner || dirsNeedingLlm.length === 0)
+        return;
+    // Aggregate per-entry failures so a misconfigured LLM endpoint surfaces
+    // as a single visible warning instead of silently degrading every entry
+    // and leaving the user wondering why nothing got enhanced.
+    const summary = { attempted: 0, succeeded: 0, skipped: 0, failureSamples: [] };
+    let completedDirs = 0;
+    let completedEntries = 0;
+    const totalDirs = dirsNeedingLlm.length;
+    const totalEntries = dirsNeedingLlm.reduce((sum, { stash }) => {
+        const entriesToEnhance = stash.entries.filter((e) => {
+            if (e.quality !== "generated")
+                return false;
+            if (isEnrichmentComplete(e))
+                return false;
+            return true;
+        });
+        return sum + entriesToEnhance.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;
+    })();
+    if (totalEntries > 0) {
+        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)}).`,
+            processed: 0,
+            total: totalEntries,
+        });
+    }
+    let currentDirLabel;
+    let configFailure;
+    let lastProgressAt = Date.now();
+    let heartbeatTimer;
+    if (totalEntries > 0 && onProgress) {
+        heartbeatTimer = setInterval(() => {
+            if (Date.now() - lastProgressAt < 15000)
+                return;
+            onProgress({
+                phase: "llm",
+                message: `Still enriching ${completedEntries}/${totalEntries} entr${totalEntries === 1 ? "y" : "ies"}` +
+                    (currentDirLabel ? `; waiting on ${currentDirLabel}` : "") +
+                    ".",
+                processed: completedEntries,
+                total: totalEntries,
+            });
+            lastProgressAt = Date.now();
+        }, 15000);
+    }
+    try {
+        await concurrentMap(dirsNeedingLlm, async ({ dirPath, files, currentStashDir, stash: originalStash }) => {
+            if (enrichSignal.aborted)
+                return undefined;
+            // Only enhance generated entries; user-provided overrides should not
+            // be overwritten. Skip entries that are already fully enriched
+            // (description + tags + searchHints).
+            const entriesToEnhance = originalStash.entries.filter((e) => {
+                if (e.quality !== "generated")
+                    return false;
+                if (isEnrichmentComplete(e)) {
+                    warnVerbose(`[akm] skipping LLM enrichment for "${e.name}" — entry already complete`);
+                    return false;
+                }
+                return true;
+            });
+            if (entriesToEnhance.length === 0)
+                return undefined;
+            currentDirLabel = path.relative(currentStashDir, dirPath) || ".";
+            onProgress?.({
+                phase: "llm",
+                message: `Enhancing ${currentDirLabel} ` +
+                    `(${entriesToEnhance.length} entr${entriesToEnhance.length === 1 ? "y" : "ies"}).`,
+                processed: completedEntries,
+                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;
+            });
+            let enhanced;
             try {
-                updateDb.exec("ROLLBACK");
+                enhanced = await enhanceStashWithLlm(llmRunner, targetStash, files, summary, enrichSignal, db, itemRefs, config, (event) => {
+                    completedEntries++;
+                    lastProgressAt = Date.now();
+                    onProgress?.({
+                        phase: "llm",
+                        message: `Enhanced ${completedEntries}/${totalEntries} entr${totalEntries === 1 ? "y" : "ies"}; ` +
+                            `${completedDirs}/${totalDirs} director${totalDirs === 1 ? "y" : "ies"} complete` +
+                            (event.entryName ? `; current ${event.entryName}` : "") +
+                            (currentDirLabel ? ` in ${currentDirLabel}` : "") +
+                            (event.outcome === "cache-hit" ? " (cache hit)" : ""),
+                        processed: completedEntries,
+                        total: totalEntries,
+                    });
+                }, onNotices, lease);
             }
-            catch {
-                // Preserve the indexing error. The update coordinator will retry
-                // rollback before closing its borrowed unified handle.
+            catch (err) {
+                if (err instanceof ConfigError) {
+                    configFailure ??= err;
+                    return undefined;
+                }
+                throw err;
             }
-        }
-        throw reclassifyIndexDbContention(error);
+            // 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);
+                    const provenance = indexedProvenanceForFile(db, entryPath);
+                    upsertEntry(db, entryPath, attachFileSize(entry, entryPath), searchText, provenance);
+                }
+            })();
+            completedDirs++;
+            lastProgressAt = Date.now();
+            onProgress?.({
+                phase: "llm",
+                message: `Completed ${completedDirs}/${totalDirs} director${totalDirs === 1 ? "y" : "ies"}; ` +
+                    `${completedEntries}/${totalEntries} entr${totalEntries === 1 ? "y" : "ies"} processed.`,
+                processed: completedEntries,
+                total: totalEntries,
+            });
+            return undefined;
+        }, 
+        // Defaults: 2 for remote LLM APIs, 1 for local model servers (LM
+        // Studio, Ollama run one inference at a time — parallel requests cause
+        // "Model reloaded" / 500 errors). No config override reaches this path:
+        // `resolveLlmEngineUse` does not forward `engines.<name>.concurrency`.
+        getDefaultLlmConcurrency(llmRunner.connection));
+        if (configFailure)
+            throw configFailure;
+    }
+    finally {
+        if (heartbeatTimer)
+            clearInterval(heartbeatTimer);
+    }
+    if (deadlineHit) {
+        warn("[akm] LLM enrichment budget exceeded. Re-run `akm index` to continue. Increase index.enrichment.timeoutMs for a larger budget.");
+    }
+    // Gate-closed (`skipped`) entries are not failures — exclude them so a
+    // deliberately disabled feature never surfaces as an enrichment error.
+    const failed = summary.attempted - summary.succeeded - summary.skipped;
+    if (failed > 0 && summary.succeeded === 0) {
+        const sample = summary.failureSamples.length ? ` Example: ${summary.failureSamples[0]}` : "";
+        warn(`LLM enhancement failed for all ${failed} attempted entries — index built without LLM enrichment.` +
+            ` Check llm.endpoint and llm.model in your config.${sample}`);
+    }
+    else if (failed > 0) {
+        const sample = summary.failureSamples.length ? ` Examples: ${summary.failureSamples.join("; ")}` : "";
+        warn(`LLM enhancement failed for ${failed}/${summary.attempted} entries — they were left un-enhanced.${sample}`);
     }
 }
-/**
- * The effective embedding vector width for this db: the config's explicit
- * `embedding.dimension` when set, else the width `index-schema.ts`'s
- * `ensureSchema` already stamped into `index_meta.embeddingDim` (every
- * `openIndexDatabase` call runs `ensureSchema` before this code ever runs),
- * else the static default. Mirrors `ensureSchema`'s own derivation so
- * `dropOtherIdentities` below never recreates `units_vec` at the wrong width.
- */
-function effectiveEmbeddingDim(db, config) {
-    const configured = config.embedding?.dimension;
-    if (typeof configured === "number" && Number.isInteger(configured) && configured > 0)
-        return configured;
-    const stored = Number(getMeta(db, "embeddingDim"));
-    return Number.isInteger(stored) && stored > 0 ? stored : EMBEDDING_DIM;
+export function createEnrichmentDeadline(timeoutMs, totalEntries) {
+    const perEntryTimeoutMs = timeoutMs === undefined ? 10 * 60 * 1000 : timeoutMs;
+    return perEntryTimeoutMs === null ? undefined : AbortSignal.timeout(perEntryTimeoutMs * Math.max(totalEntries, 1));
 }
-/**
- * `akm index --reembed`: drop the active embedding identity's vectors so
- * drain re-embeds every unit from scratch under that same identity. Reuses
- * A2's `dropOtherIdentities(db, keep, dim)` by asking it to keep an identity
- * string no real vector can ever carry — `""`, never produced by
- * `deriveObservedEmbeddingIdentity` — so every row under the real identity is
- * removed and none are spared. `index_meta.embeddingIdentity` is left as-is:
- * re-embedding the same unchanged provider/model reproduces the same identity
- * string, so there is nothing stale to clear.
- */
-function dropActiveIdentityVectors(db, config) {
-    const identity = getMeta(db, "embeddingIdentity");
-    if (!identity)
-        return;
-    dropOtherIdentities(db, "", effectiveEmbeddingDim(db, config));
+// ── 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);
+    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 buildIndexSummaryMessage(options) {
-    const stashSourceLabel = options.sourcesCount === 1 ? "stash source" : "stash sources";
-    const semanticDetail = options.semanticSearchMode === "off"
-        ? "disabled"
-        : `${options.embeddingProvider} embeddings, ${options.vecAvailable ? "sqlite-vec" : "unavailable"}`;
-    return `Starting ${options.mode} index (${options.sourcesCount} ${stashSourceLabel}, semantic search: ${semanticDetail}).`;
+function getSemanticSearchLabel(semanticSearchMode, embeddingProvider, vecAvailable) {
+    if (semanticSearchMode === "off")
+        return "disabled";
+    return `${embeddingProvider} embeddings, ${vecAvailable ? "sqlite-vec" : "JS fallback"}`;
 }
-/**
- * Compute the `IndexResponse.verification` envelope from the current unit
- * coverage for the active embedding identity. `drain` is the just-completed
- * `DrainCounts`, when a drain ran this call (`null` when semantic search is
- * off, the embedding phase was deferred to `akm bundle update`'s post-commit
- * pass, or the drain call itself threw — see `drainFailed`).
- *
- * `drainFailed` is set when `drainEmbeddingQueue` threw outright (a genuine
- * interruption — an abort, a provider crash before its own per-batch
- * retry/circuit-breaker ever engaged) rather than returning normally with
- * some batches skipped. `drain` is `null` in that case too (the counts a
- * completed call would have returned were never produced), so this call
- * cannot tell "threw after embedding half of them" apart from "threw before
- * embedding any" by inspecting `drain` alone — `drainFailed` carries that
- * distinction forward explicitly: this run did not finish its embedding
- * phase, whatever partial progress the DB already durably committed
- * (`coverage.unitsPresent`, read fresh below) notwithstanding.
- */
-function buildIndexVerification(db, config, drain, drainFailed = false) {
-    const embeddingProvider = getEmbeddingProvider(config.embedding);
+function verifyIndexState(db, config, embeddableEntries, embeddingResult) {
+    const embeddingCount = getEmbeddingCount(db);
     const vecAvailable = isVecAvailable(db);
-    const totalEntries = getEntryCount(db);
-    const semanticSearchEnabled = config.semanticSearchMode === "auto";
-    if (totalEntries === 0) {
+    const embeddingProvider = getEmbeddingProvider(config.embedding);
+    if (embeddableEntries === 0) {
         return {
             ok: true,
             message: "Index ready. No assets were found yet.",
-            semanticSearchEnabled,
+            semanticSearchEnabled: config.semanticSearchMode === "auto",
             semanticSearchMode: config.semanticSearchMode,
             semanticStatus: config.semanticSearchMode === "off" ? "disabled" : "pending",
             embeddingProvider,
-            entryCount: 0,
-            embeddingCount: 0,
+            entryCount: embeddableEntries,
+            embeddingCount,
             vecAvailable,
         };
     }
@@ -340,310 +1623,190 @@ function buildIndexVerification(db, config, drain, drainFailed = false) {
             semanticSearchMode: config.semanticSearchMode,
             semanticStatus: "disabled",
             embeddingProvider,
-            entryCount: totalEntries,
-            embeddingCount: 0,
+            entryCount: embeddableEntries,
+            embeddingCount,
             vecAvailable,
         };
     }
-    const identity = getMeta(db, "embeddingIdentity");
-    const coverage = identity
-        ? unitCoverage(db, identity)
-        : { entries: 0, entriesFullyCovered: 0, unitsTotal: 0, unitsPresent: 0 };
-    if (coverage.entries > 0 && coverage.entriesFullyCovered >= coverage.entries && vecAvailable) {
+    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 (${coverage.unitsPresent}/${coverage.unitsTotal} unit embeddings, sqlite-vec active).`,
+            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: "ready-vec",
-            embeddingProvider,
-            entryCount: totalEntries,
-            embeddingCount: coverage.unitsPresent,
-            vecAvailable,
-        };
-    }
-    // sqlite-vec is the only vector store (no BLOB fallback since the index
-    // redesign), so without the extension no drain can ever make progress and
-    // "in progress" would be a status that never resolves. Report it as
-    // blocked, with the fix.
-    if (!vecAvailable) {
-        return {
-            ok: false,
-            message: `Semantic search unavailable: the sqlite-vec extension is not loaded (${coverage.unitsPresent}/${coverage.unitsTotal} unit embeddings).`,
-            guidance: "Install the optional sqlite-vec extension (see docs/reference/configuration.md, sqlite-vec extension), then run `akm index`; keyword search keeps working meanwhile.",
-            semanticSearchEnabled,
-            semanticSearchMode: config.semanticSearchMode,
-            semanticStatus: "blocked",
+            semanticStatus: vecActive ? "ready-vec" : "ready-js",
             embeddingProvider,
-            entryCount: totalEntries,
-            embeddingCount: coverage.unitsPresent,
+            entryCount: embeddableEntries,
+            embeddingCount,
             vecAvailable,
         };
     }
-    // Not fully covered: a fresh index whose queue is still draining ("pending",
-    // not a failure) vs. a drain that ran and made no progress at all, OR
-    // threw outright mid-run ("blocked" either way — matches the guidance the
-    // old materialize-embeddings path gave for the same shape of failure).
-    const madeNoProgress = drainFailed || (drain !== null && drain.pending > 0 && drain.embedded === 0 && drain.failed > 0);
     return {
-        ok: !madeNoProgress,
-        message: madeNoProgress
-            ? `Semantic search verification failed (${coverage.unitsPresent}/${coverage.unitsTotal} unit embeddings available).`
-            : `Semantic search embedding in progress (${coverage.unitsPresent}/${coverage.unitsTotal} unit embeddings).`,
-        ...(madeNoProgress
-            ? {
-                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.",
-            }
-            : {}),
+        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: madeNoProgress ? "blocked" : "pending",
+        semanticStatus: "blocked",
         embeddingProvider,
-        entryCount: totalEntries,
-        embeddingCount: coverage.unitsPresent,
+        entryCount: embeddableEntries,
+        embeddingCount,
         vecAvailable,
     };
 }
-/**
- * The ONE embedding-phase implementation: drain the content-addressed
- * embedding queue (B4's `drainEmbeddingQueue`) and compute the post-drain
- * `IndexVerification` from unit coverage. `akmIndex`'s own (non-deferred) run
- * calls this inline; `akm bundle update`'s coordinator calls it directly on
- * its own connection AFTER its unified update transaction commits, since
- * draining writes per-provider-batch transactions that must not nest inside
- * the coordinator's long-lived one.
- */
-export async function runEmbeddingPass(params) {
-    const { db, config, onProgress, signal } = params;
-    const drainCounts = await drainEmbeddingQueue(db, config, {
-        signal,
-        onProgress: (line) => onProgress({ phase: "embeddings", message: line }),
-    });
-    const verification = buildIndexVerification(db, config, drainCounts);
-    setMeta(db, "hasEmbeddings", verification.semanticStatus === "ready-vec" ? "1" : "0");
-    onProgress({ phase: "verify", message: verification.message });
-    return { drainCounts, verification };
+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 };
 }
-async function akmIndexReal(options) {
-    const requestedAt = Date.now();
-    const stashDir = options.stashDir;
-    const onProgress = options?.onProgress ?? (() => { });
-    const signal = options?.signal;
-    const full = options?.full === true;
-    const reembed = options?.reembed === true;
-    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);
-    // Source hydration: ensure git/website/npm caches are extracted before
-    // resolving stash dirs, so their content directories exist on disk for
-    // reconcile's walk to discover. This is NOT index derivation — it is what
-    // makes derivation possible — so it stays even though the walk/derive
-    // pipeline below it does not.
-    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 fetcher resolve `secrets/x-bearer-token` during bundle-update /
-    // hydrate, not just from the command-layer URL-ingest path.
-    const { storeSecretResolver } = await import("../sources/snapshot-fetchers/secret-seam.js");
-    await ensureSourceCaches(config, {
-        force: full,
-        materialize: options.hydrateSources !== false,
-        secrets: storeSecretResolver,
-        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,
-    });
-    config = detected.config;
-    const persistedAdapters = detected.persistedAdapters;
-    const allSourceDirs = allSourceEntries.map((s) => s.path);
-    onProgress({
-        phase: "preflight",
-        message: `Resolved ${allSourceDirs.length} stash source${allSourceDirs.length === 1 ? "" : "s"}.`,
-    });
-    const t0 = Date.now();
-    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.");
+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));
     }
-    try {
-        const owners = sourceOwners(allSourceEntries);
-        if (full) {
-            onProgress({ phase: "preflight", message: "Forcing full re-derivation for a full reindex." });
-        }
-        if (reembed) {
-            onProgress({ phase: "preflight", message: "Dropping vectors for the active embedding identity." });
-            dropActiveIdentityVectors(db, config);
-        }
-        onProgress({
-            phase: "summary",
-            message: buildIndexSummaryMessage({
-                mode: full ? "full" : "incremental",
-                sourcesCount: allSourceDirs.length,
-                semanticSearchMode: config.semanticSearchMode,
-                embeddingProvider: getEmbeddingProvider(config.embedding),
-                vecAvailable: isVecAvailable(db),
-            }),
-        });
-        removeStaleSourceOwners(db, owners);
-        throwIfAborted(signal);
-        const reconcileStart = Date.now();
-        const reconcileCounts = await reconcileRoots(db, owners
-            .filter((owner) => !owner.unresolved)
-            .map((owner) => ({ path: owner.sourceRoot, bundleId: owner.bundleId })), {
-            signal,
-            onProgress: (line) => onProgress({ phase: "scan", message: line }),
-            forceReparse: full,
-            // #954-precedent (same as the embedding drain skip below): a
-            // borrowed transaction must not hold open across enrichment's LLM
-            // round trip.
-            insideBorrowedTransaction: Boolean(options.deferredUpdateTransaction),
-        });
-        onProgress({
-            phase: "scan",
-            message: `Reconciled ${reconcileCounts.scanned} file${reconcileCounts.scanned === 1 ? "" : "s"} ` +
-                `(${reconcileCounts.added} added, ${reconcileCounts.changed} changed, ${reconcileCounts.removed} removed).`,
-        });
-        const reconcileEnd = Date.now();
-        throwIfAborted(signal);
-        const deferred = options.deferredUpdateTransaction;
-        let drainCounts = null;
-        let drainFailed = false;
-        if (deferred) {
-            // #954-precedent: the embedding phase is SKIPPED entirely for a
-            // borrowed transaction — draining commits per provider batch, which
-            // must not nest inside the coordinator's long-lived transaction.
-            // Finalize below records 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");
-        }
-        else if (config.semanticSearchMode !== "off") {
-            try {
-                drainCounts = await drainEmbeddingQueue(db, config, {
-                    signal,
-                    onProgress: (line) => onProgress({ phase: "embeddings", message: line }),
-                    // An implicit (read-path) run takes a bounded slice — see
-                    // `IndexOptions.implicit`. An explicit `akm index` drains the
-                    // whole queue, as it always has.
-                    ...(options.implicit === true ? { limit: IMPLICIT_DRAIN_UNIT_LIMIT } : {}),
-                });
+    return resolved.size > 0 ? [...resolved] : files;
+}
+async function enhanceStashWithLlm(llmRunner, stash, files, summary, signal, db, itemRefs, akmConfig, onEntryDone, onNotices, lease) {
+    const { enhanceMetadata } = await import("../llm/metadata-enhance.js");
+    const { computeBodyHash, getLlmCacheEntry, upsertLlmCacheEntry } = await import("../storage/repositories/index-llm-cache-repository.js");
+    let configFailure;
+    const results = await concurrentMap(stash.entries, async (entry, idx) => {
+        if (signal?.aborted)
+            return entry;
+        summary.attempted++;
+        try {
+            const entryFile = entry.filename
+                ? (files.find((f) => path.basename(f) === entry.filename) ?? files[0])
+                : files[0];
+            let fileContent;
+            if (entryFile) {
+                try {
+                    fileContent = fs.readFileSync(entryFile, "utf8");
+                }
+                catch {
+                    warn(`Could not read file for LLM enrichment: ${entry.filename ?? entry.name}`);
+                }
             }
-            catch (drainError) {
-                // Best-effort, same contract as the write-path drain
-                // (index-written-assets.ts): the provider can fail outright (a model
-                // download blocked, DNS down, a bad endpoint) before it ever reaches
-                // drainEmbeddingQueue's own per-batch retry/circuit-breaker — an
-                // index run must still finish lexically searchable rather than
-                // crash. The embedding queue is durable: the next run (or the
-                // scheduler) computes the same "no vector yet" query and resumes.
-                // `drainFailed` records that this run's embedding phase did not
-                // finish (verification below reports `ok: false`), independent of
-                // however many batches had already committed durably before the
-                // throw — those are real, already reflected in the next read of
-                // unit coverage, not undone by this catch.
-                throwIfAborted(signal);
-                drainFailed = true;
-                // This catch is non-fatal by design, so `akmIndex`'s outer catch never
-                // sees the error and never classifies it — which is exactly how the
-                // field saw a raw "database is locked" driver string in this warning
-                // under the phase pipeline this replaced. Run it through the same
-                // classifier that path uses, so contention reads as contention.
-                const reportedDrainError = reclassifyIndexDbContention(drainError);
-                warn("[index] Embedding drain failed; the index is lexically searchable and vectors will be attempted on the next run:", reportedDrainError instanceof Error ? reportedDrainError.message : String(reportedDrainError));
+            // 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];
+            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 embedEnd = Date.now();
-        // ── Finalize / meta bookkeeping ───────────────────────────────────────
-        const finalizeStart = Date.now();
-        const mutateState = (stateDb, stateSchema) => {
-            onProgress({ phase: "finalize", message: "Relinking usage events." });
-            relinkUsageEvents(db, stateDb, { sources: allSourceEntries, defaultStashDir: stashDir, stateSchema });
-            onProgress({ phase: "finalize", message: "Recomputing utility scores." });
-            recomputeUtilityScores(db, stateDb, { stateSchema });
-        };
-        if (deferred) {
-            if (deferred.db !== db || !db.inTransaction) {
-                throw new Error("Source update index finalization requires its borrowed unified transaction.");
+            const outcome = await enhanceMetadata(llmRunner, entry, fileContent, signal, akmConfig, onNotices, lease);
+            if (outcome.status !== "enriched") {
+                // Not a genuine LLM success: the gate was closed (`skipped`) or the
+                // call errored/timed out (`failed`). Do NOT mark the entry enriched
+                // and do NOT write the LLM cache — caching here would poison the
+                // entry into a permanent enrichment skip even though nothing was
+                // enhanced. Surface failures honestly; stay silent on gated-off skips.
+                if (outcome.status === "failed") {
+                    const msg = outcome.error ?? "metadata enrichment failed";
+                    if (summary.failureSamples.length < 3 && !summary.failureSamples.includes(msg)) {
+                        summary.failureSamples.push(msg);
+                    }
+                    onEntryDone?.({ entryName: entry.name, outcome: "failed" });
+                }
+                else {
+                    summary.skipped++;
+                    onEntryDone?.({ entryName: entry.name, outcome: "skipped" });
+                }
+                return entry;
             }
-            mutateState(db, deferred.stateSchema);
-        }
-        else {
-            withStateDb(mutateState);
+            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,
+                }));
+            }
+            summary.succeeded++;
+            onEntryDone?.({ entryName: entry.name, outcome: "llm" });
+            return updated;
         }
-        // An incomplete reconcile (a configured source that could not be walked
-        // this run) preserves the prior freshness watermark. Advancing it could
-        // make a source that came back look unchanged even though this run never
-        // saw its files — the same #624-P1 preflight the old walk phase applied
-        // to `builtAt`, now keyed off `reconcileCounts.complete`.
-        if (reconcileCounts.complete) {
-            const builtAt = new Date().toISOString();
-            setMeta(db, "builtAt", builtAt);
-            setMeta(db, "stashDir", stashDir);
-            setMeta(db, "stashDirs", JSON.stringify(owners.map((owner) => owner.sourceRoot)));
-            setMeta(db, "sourceOwners", JSON.stringify(owners));
-            setMeta(db, "lastReconcileAt", builtAt);
+        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" });
+            return entry;
         }
-        const verification = deferred
-            ? {
-                ok: true,
-                message: "Semantic index update deferred until after the source-update commit.",
-                semanticSearchEnabled: config.semanticSearchMode === "auto",
-                semanticSearchMode: config.semanticSearchMode,
-                semanticStatus: config.semanticSearchMode === "off" ? "disabled" : "pending",
-                embeddingProvider: getEmbeddingProvider(config.embedding),
-                entryCount: getEntryCount(db),
-                embeddingCount: 0,
-                vecAvailable: isVecAvailable(db),
-            }
-            : buildIndexVerification(db, config, drainCounts, drainFailed);
-        if (!deferred)
-            setMeta(db, "hasEmbeddings", verification.semanticStatus === "ready-vec" ? "1" : "0");
-        onProgress({ phase: "verify", message: verification.message });
-        const totalEntries = getEntryCount(db);
-        const finalizeEnd = Date.now();
-        return {
-            stashDir,
-            totalEntries,
-            entriesUpserted: reconcileCounts.added + reconcileCounts.changed,
-            indexPath: dbPath,
-            mode: full ? "full" : "incremental",
-            sourcesScanned: owners.length,
-            scanComplete: reconcileCounts.complete,
-            ...(reconcileCounts.warnings.length > 0 ? { warnings: reconcileCounts.warnings } : {}),
-            ...(Object.keys(persistedAdapters).length > 0 ? { configUpdated: { detectedAdapters: persistedAdapters } } : {}),
-            verification,
-            timing: {
-                totalMs: Date.now() - t0,
-                preflightMs: t0 - requestedAt,
-                sourceCacheMs: sourceCacheEnd - sourceCacheStart,
-                reconcileMs: reconcileEnd - reconcileStart,
-                embedMs: embedEnd - reconcileEnd,
-                finalizeMs: finalizeEnd - finalizeStart,
-                endToEndMs: Date.now() - requestedAt,
-            },
-        };
-    }
-    finally {
-        if (!borrowedUpdateDb)
-            closeDatabase(db);
-    }
+    }, 
+    // Defaults: 2 for remote LLM APIs, 1 for local model servers. No config
+    // override reaches this path (see getDefaultLlmConcurrency).
+    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 };
 }
+// ── lookup ─────────────────────────────────────────────────────────────────
+import { makeBundleRef } from "../core/asset/asset-ref.js";
+import { conceptIdFromTypeName } from "../core/asset/resolve-ref.js";
 async function resolveLookupSources() {
     const { loadConfig } = await import("../core/config/config.js");
     const { resolveSourceEntries } = await import("./search/search-source.js");
@@ -794,7 +1957,7 @@ const USAGE_EVENT_RETENTION_DAYS = 90;
  * Also purges usage_events older than 90 days and ensures the M-1
  * usage_events table exists before querying.
  *
- * Called during `akm index` after reconcile.
+ * Called during `akm index` after FTS rebuild.
  */
 export function recomputeUtilityScores(db, stateDb, options) {
     const EMA_DECAY = 0.7;