akm-cli 0.9.15 → 0.9.16-alpha.1

package/dist/indexer/indexer.js

@@ -4,75 +4,80 @@
 import fs from "node:fs";
 import path from "node:path";
 import { detectAdapterId } from "../core/adapter/detect-adapter.js";
-import { adapterForId } from "../core/adapter/registry.js";
-import { isHttpUrl, toErrorMessage } from "../core/common.js";
-import { concurrentMap } from "../core/concurrent.js";
-import { ConfigError } from "../core/errors.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 { defaultConcurrencyForEndpoint } from "../core/loopback.js";
-import { classifyPathAccess, describeInaccessiblePath } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
-import { SCRIPT_EXTENSIONS } from "../core/recognition-util.js";
-import { withStateDb } from "../core/state-db.js";
-import { isVerbose, warn, 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 { isSqliteContentionError, withStateDb } from "../core/state-db.js";
+import { warn } from "../core/warn.js";
+import { DEFAULT_REMOTE_BATCH_SIZE } from "../llm/embedders/remote.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
-import { salvageEmbeddingsBeforeDiscard } from "../storage/repositories/embedding-salvage-repository.js";
 import { closeDatabase, openExistingDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
-import { deleteAllEntries, deleteEntriesByBundle, deleteEntriesByDirAndBundle, deleteEntriesByDirExceptRefs, deleteEntriesByIds, deleteUsageEventsByEntryIds, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedBundleIdsByDir, getIndexedDirPathsByBundleId, relinkUsageEvents, upsertEntry, } from "../storage/repositories/index-entries-repository.js";
-import { clearStaleCacheEntries, computeBodyHash, getLlmCacheEntry, } from "../storage/repositories/index-llm-cache-repository.js";
-import { deleteIndexDirState, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
+import { deleteEntriesByBundle, 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 { upsertUtilityScore } from "../storage/repositories/index-utility-repository.js";
-import { getEmbeddingCount, isVecAvailable, isVecFastPathReady, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
+import { isVecAvailable } from "../storage/repositories/index-vec-repository.js";
+import { dropOtherIdentities, unitCoverage } from "../storage/repositories/units-repository.js";
 import { assertIndexedWorkflowSourceIdentity, WorkflowSourceIdentityError } from "../workflows/source-files.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
-import { reclassifyIndexDbContention } from "./index-db-contention.js";
-import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
+import { drainEmbeddingQueue } from "./drain.js";
+import { deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
-import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
-import { canUseIncrementalSkip, computeDirFingerprint, getCachedDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
-import { getMarkdownFragmentContent, hasMarkdownFragmentContent, isEnrichmentComplete, isWorkflowSkipWarning, setMarkdownFragmentContent, } from "./passes/metadata.js";
-import { drainDirDocuments } from "./scan/drain-dir.js";
-import { buildSearchText } from "./search/search-fields.js";
+import { reconcileRoots } from "./reconcile.js";
 import { purgeOldUsageEvents } from "./usage/usage-events.js";
-import { walkStashFlatWithStatus } from "./walk/walker.js";
-function collectLoweringNotices(target, notices) {
-    const keys = new Set(target.map((notice) => JSON.stringify(notice)));
-    for (const notice of notices) {
-        const key = JSON.stringify(notice);
-        if (keys.has(key))
-            continue;
-        keys.add(key);
-        target.push(notice);
-    }
-}
+/**
+ * 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;
 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) }] : [];
+        return installation
+            ? [
+                {
+                    bundleId: installation.id,
+                    sourceRoot: path.resolve(source.path),
+                    ...(source.unresolved ? { unresolved: true } : {}),
+                },
+            ]
+            : [];
     });
 }
 function parseStoredSourceOwners(raw) {
@@ -99,336 +104,28 @@ function parseStoredSourceOwners(raw) {
     }
 }
 /**
- * Source cache phase: ensure git stash caches are up to date and purge orphaned
- * entries from removed sources (incremental only).
- */
-async function runSourceCachePhase(ctx) {
-    const { db, 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.
+ * 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).
  */
-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);
+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);
     }
 }
-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`.
@@ -440,10 +137,6 @@ export function _setDrainObserverForTests(observer) {
  * emitted here. The map is cleared at the top of every callback invocation
  * because `mutateConfig` may retry optimistically, and a retry must not report
  * a superseded attempt.
- *
- * Extracted from `akmIndexReal` as one self-contained named pass, both to keep
- * that function under the src-wide function-size bar and because the detection
- * and its disclosure belong together.
  */
 function detectAndPersistBundleAdapters(allSourceEntries, config, mutateConfig, opts) {
     const detectedByBundle = new Map();
@@ -490,695 +183,10 @@ 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 };
-}
 /**
- * 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.
+ * `detectAndPersistBundleAdapters` only auto-detects an adapter for a source
+ * root that exists and can be listed — an unreadable/missing root gets no
+ * silent guess.
  */
 function allSourceRootsReadable(roots) {
     for (const root of roots) {
@@ -1186,7 +194,7 @@ function allSourceRootsReadable(roots) {
             const st = fs.statSync(root);
             if (!st.isDirectory())
                 return false;
-            fs.readdirSync(root); // probe readability, not just existence
+            fs.readdirSync(root);
         }
         catch {
             return false;
@@ -1194,424 +202,133 @@ 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;
+}
 /**
- * Phase 2 (sync): write all pre-generated scan records inside a single
- * transaction, returning the directories that still need LLM enrichment.
+ * 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.
  */
-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 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;
 }
-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}`);
-    }
-    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);
-    }
+export async function akmIndex(options) {
     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;
+        const override = akmIndexOverride;
+        return override ? await override(options) : await akmIndexReal(options);
+    }
+    catch (error) {
+        const updateDb = options.deferredUpdateTransaction?.db;
+        if (updateDb?.inTransaction) {
             try {
-                enhanced = await enhanceStashWithLlm(llmRunner, targetStash, files, summary, enrichSignal, db, itemRefs, config, (event) => {
-                    completedEntries++;
-                    lastProgressAt = Date.now();
-                    onProgress?.({
-                        phase: "llm",
-                        message: `Enhanced ${completedEntries}/${totalEntries} entr${totalEntries === 1 ? "y" : "ies"}; ` +
-                            `${completedDirs}/${totalDirs} director${totalDirs === 1 ? "y" : "ies"} complete` +
-                            (event.entryName ? `; current ${event.entryName}` : "") +
-                            (currentDirLabel ? ` in ${currentDirLabel}` : "") +
-                            (event.outcome === "cache-hit" ? " (cache hit)" : ""),
-                        processed: completedEntries,
-                        total: totalEntries,
-                    });
-                }, onNotices, lease);
+                updateDb.exec("ROLLBACK");
             }
-            catch (err) {
-                if (err instanceof ConfigError) {
-                    configFailure ??= err;
-                    return undefined;
-                }
-                throw err;
+            catch {
+                // Preserve the indexing error. The update coordinator will retry
+                // rollback before closing its borrowed unified handle.
             }
-            // 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}`);
+        }
+        throw reclassifyIndexDbContention(error);
     }
 }
-export function createEnrichmentDeadline(timeoutMs, totalEntries) {
-    const perEntryTimeoutMs = timeoutMs === undefined ? 10 * 60 * 1000 : timeoutMs;
-    return perEntryTimeoutMs === null ? undefined : AbortSignal.timeout(perEntryTimeoutMs * Math.max(totalEntries, 1));
-}
-// ── Helpers ─────────────────────────────────────────────────────────────────
-function attachFileSize(entry, entryPath) {
-    try {
-        const sized = { ...entry, fileSize: fs.statSync(entryPath).size };
-        if (hasMarkdownFragmentContent(entry))
-            setMarkdownFragmentContent(sized, getMarkdownFragmentContent(entry));
-        return sized;
-    }
-    catch {
-        return entry;
-    }
+/**
+ * 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;
 }
-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"}).`;
+/**
+ * `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));
 }
 function getEmbeddingProvider(embedding) {
     return isHttpUrl(embedding?.endpoint) ? "remote" : "local";
 }
-function getSemanticSearchLabel(semanticSearchMode, embeddingProvider, vecAvailable) {
-    if (semanticSearchMode === "off")
-        return "disabled";
-    return `${embeddingProvider} embeddings, ${vecAvailable ? "sqlite-vec" : "JS fallback"}`;
+function 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 verifyIndexState(db, config, embeddableEntries, embeddingResult) {
-    const embeddingCount = getEmbeddingCount(db);
-    const vecAvailable = isVecAvailable(db);
+/**
+ * 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);
-    if (embeddableEntries === 0) {
+    const vecAvailable = isVecAvailable(db);
+    const totalEntries = getEntryCount(db);
+    const semanticSearchEnabled = config.semanticSearchMode === "auto";
+    if (totalEntries === 0) {
         return {
             ok: true,
             message: "Index ready. No assets were found yet.",
-            semanticSearchEnabled: config.semanticSearchMode === "auto",
+            semanticSearchEnabled,
             semanticSearchMode: config.semanticSearchMode,
             semanticStatus: config.semanticSearchMode === "off" ? "disabled" : "pending",
             embeddingProvider,
-            entryCount: embeddableEntries,
-            embeddingCount,
+            entryCount: 0,
+            embeddingCount: 0,
             vecAvailable,
         };
     }
@@ -1623,190 +340,310 @@ function verifyIndexState(db, config, embeddableEntries, embeddingResult) {
             semanticSearchMode: config.semanticSearchMode,
             semanticStatus: "disabled",
             embeddingProvider,
-            entryCount: embeddableEntries,
-            embeddingCount,
+            entryCount: totalEntries,
+            embeddingCount: 0,
             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);
+    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) {
         return {
             ok: true,
-            message: `Semantic search ready (${embeddingCount}/${embeddableEntries} embeddings, ${vecActive
-                ? "sqlite-vec active"
-                : vecAvailable
-                    ? "JS fallback active — vec fast path degraded, run 'akm index --full' to restore"
-                    : "JS fallback active"}).`,
+            message: `Semantic search ready (${coverage.unitsPresent}/${coverage.unitsTotal} unit embeddings, sqlite-vec active).`,
             semanticSearchEnabled: true,
             semanticSearchMode: config.semanticSearchMode,
-            semanticStatus: vecActive ? "ready-vec" : "ready-js",
+            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",
             embeddingProvider,
-            entryCount: embeddableEntries,
-            embeddingCount,
+            entryCount: totalEntries,
+            embeddingCount: coverage.unitsPresent,
             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: 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.",
+        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.",
+            }
+            : {}),
         semanticSearchEnabled: true,
         semanticSearchMode: config.semanticSearchMode,
-        semanticStatus: "blocked",
+        semanticStatus: madeNoProgress ? "blocked" : "pending",
         embeddingProvider,
-        entryCount: embeddableEntries,
-        embeddingCount,
+        entryCount: totalEntries,
+        embeddingCount: coverage.unitsPresent,
         vecAvailable,
     };
 }
-function buildIndexedDirCandidate(dirPath, indexableFiles, generated) {
-    const stash = generated.entries.length > 0 ? { entries: generated.entries } : null;
-    const staleFiles = stash ? resolveIndexedFiles(dirPath, indexableFiles, stash) : indexableFiles;
-    return { stash, staleFiles };
+/**
+ * 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 resolveIndexedFiles(dirPath, files, stash) {
-    const resolved = new Set();
-    for (const entry of stash.entries) {
-        if (entry.filename)
-            resolved.add(path.join(dirPath, entry.filename));
+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.");
     }
-    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}`);
-                }
-            }
-            // 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 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;
+    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 } : {}),
+                });
             }
-            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,
-                }));
+            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));
             }
-            summary.succeeded++;
-            onEntryDone?.({ entryName: entry.name, outcome: "llm" });
-            return updated;
         }
-        catch (err) {
-            if (err instanceof ConfigError) {
-                configFailure ??= err;
-                return entry;
-            }
-            const msg = toErrorMessage(err);
-            // failureSamples is bounded to 3 items, so a linear scan is cheaper
-            // than maintaining a parallel Set for membership checks (#177 review).
-            if (summary.failureSamples.length < 3 && !summary.failureSamples.includes(msg)) {
-                summary.failureSamples.push(msg);
+        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.");
             }
-            onEntryDone?.({ entryName: entry.name, outcome: "failed" });
-            return entry;
+            mutateState(db, deferred.stateSchema);
+        }
+        else {
+            withStateDb(mutateState);
+        }
+        // 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);
         }
-    }, 
-    // 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 };
+        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);
+    }
 }
-// ── 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");
@@ -1957,7 +794,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 FTS rebuild.
+ * Called during `akm index` after reconcile.
  */
 export function recomputeUtilityScores(db, stateDb, options) {
     const EMA_DECAY = 0.7;