akm-cli 0.9.2-alpha.1 → 0.9.2-alpha.2

package/dist/commands/sources/installed-stashes.js

@@ -355,9 +355,19 @@ function buildUpdateResponse(stashDir, target, all, processed, opts) {
             totalEntries: index.totalEntries,
             directoriesScanned: index.directoriesScanned,
             directoriesSkipped: index.directoriesSkipped,
+            ...(index.scanComplete !== undefined ? { scanComplete: index.scanComplete } : {}),
         },
     };
 }
+function incompleteFilesystemOutcome(id) {
+    return {
+        id,
+        kind: "filesystem",
+        status: "skipped",
+        code: "SOURCE_SCAN_INCOMPLETE",
+        reason: `Filesystem source "${id}" was not scanned completely; preserving its last-known-good index rows.`,
+    };
+}
 let updateTransactionHookForTests;
 /** TEST-ONLY. Inject faults at source-update transaction boundaries. */
 export function _setUpdateTransactionHookForTests(hook) {
@@ -893,6 +903,22 @@ async function updateWebsiteSource(stashDir, target, all, websiteSource, allowIn
     const synced = await syncWebsitePlainSource(websiteSource, stashDir, allowInsecure);
     return buildUpdateResponse(stashDir, target, all, [], { plainSynced: [synced.item], index: synced.index });
 }
+/** Reconcile a filesystem source's current bytes without provider hydration. */
+async function updateFilesystemSource(stashDir, target, all, filesystemSource) {
+    const id = filesystemSource.name ?? filesystemSource.path ?? target;
+    const ref = filesystemSource.path ?? target;
+    const index = await akmIndex({ stashDir, hydrateSources: false });
+    if (!index.scanComplete) {
+        return buildUpdateResponse(stashDir, target, all, [], {
+            skipped: [incompleteFilesystemOutcome(id)],
+            index,
+        });
+    }
+    return buildUpdateResponse(stashDir, target, all, [], {
+        plainSynced: [{ id, kind: "filesystem", ref }],
+        index,
+    });
+}
 /**
  * A plain (lockless) npm bundle has no deterministic content path — unlike
  * git/website, resolving an npm package requires a registry round-trip to
@@ -1226,6 +1252,15 @@ export async function akmUpdate(input) {
             const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(npmMatch), force, yes, stashDir, allowInsecure);
             return buildUpdateResponse(stashDir, target, all, [updated.item], { index: updated.index });
         }
+        const filesystemMatch = stashes.find((source) => {
+            if (source.type !== "filesystem")
+                return false;
+            if (source.name === target)
+                return true;
+            return resolvedPath !== undefined && source.path !== undefined && path.resolve(source.path) === resolvedPath;
+        });
+        if (filesystemMatch)
+            return updateFilesystemSource(stashDir, target, all, filesystemMatch);
     }
     const enabledManagedInstalls = all
         ? managedInstalls.filter((managed) => config.bundles?.[managed.bundleKey]?.enabled !== false)
@@ -1257,6 +1292,7 @@ export async function akmUpdate(input) {
     if (all) {
         const managedKeys = new Set(managedInstalls.map((m) => m.bundleKey));
         const plainSources = getSources(config).filter((source) => source.enabled !== false && !managedKeys.has(source.name ?? ""));
+        const filesystemSources = [];
         for (const plain of plainSources) {
             const id = plain.name ?? plain.path ?? plain.url ?? "";
             try {
@@ -1276,18 +1312,43 @@ export async function akmUpdate(input) {
                     latestIndex = updated.index;
                 }
                 else {
-                    skipped.push({
-                        id,
-                        kind: plain.type,
-                        status: "skipped",
-                        reason: "reflects your files in place and has no remote to sync; run `akm index` to refresh the search index.",
-                    });
+                    filesystemSources.push(plain);
                 }
             }
             catch (error) {
                 skipped.push(updateFailureOutcome(id, plain.type, error));
             }
         }
+        if (filesystemSources.length > 0) {
+            try {
+                // A remote source may have reconciled before a later source finished
+                // hydrating, so an incomplete intermediate result is not authoritative
+                // for the final `--all` outcome. Retry once after every source update;
+                // a genuinely missing filesystem root remains incomplete and is
+                // reported below without claiming reconciliation.
+                if (!latestIndex?.scanComplete)
+                    latestIndex = await akmIndex({ stashDir, hydrateSources: false });
+                if (latestIndex.scanComplete) {
+                    for (const source of filesystemSources) {
+                        plainSynced.push({
+                            id: source.name ?? source.path ?? "",
+                            kind: "filesystem",
+                            ref: source.path ?? source.name ?? "",
+                        });
+                    }
+                }
+                else {
+                    for (const source of filesystemSources) {
+                        skipped.push(incompleteFilesystemOutcome(source.name ?? source.path ?? ""));
+                    }
+                }
+            }
+            catch (error) {
+                for (const source of filesystemSources) {
+                    skipped.push(updateFailureOutcome(source.name ?? source.path ?? "", "filesystem", error));
+                }
+            }
+        }
     }
     return buildUpdateResponse(stashDir, target, all, processed, {
         plainSynced,
@@ -1326,26 +1387,6 @@ function selectManagedTargets(config, installs, target, all) {
     const found = resolveManagedTarget(config, target);
     if (found)
         return [found];
-    // Give a helpful message when the target names a plain (non-managed) source.
-    const stashes = getSources(config);
-    const isUrl = target.startsWith("http://") || target.startsWith("https://");
-    const resolvedPath = !isUrl ? path.resolve(target) : undefined;
-    const stashMatch = stashes.find((s) => {
-        if (isUrl && s.url === target)
-            return true;
-        if (resolvedPath && s.path && path.resolve(s.path) === resolvedPath)
-            return true;
-        if (s.name === target)
-            return true;
-        return false;
-    });
-    if (stashMatch) {
-        if (stashMatch.type === "website") {
-            throw new UsageError(`"${target}" is a website source — website caching not yet implemented for --all. ` +
-                `Run \`akm bundle update ${target}\` to re-mirror this source individually.`, "TARGET_NOT_UPDATABLE");
-        }
-        throw new UsageError(`"${target}" is a local directory — it reflects your files in place. To refresh the search index, run: akm index`, "TARGET_NOT_UPDATABLE");
-    }
     throw new NotFoundError(`No matching source for target: ${target}`, "SOURCE_NOT_FOUND");
 }
 /**

package/dist/core/adapter/adapters/akm-adapter.js

@@ -179,7 +179,6 @@ const DOCUMENT_JSON_CARRIED_FIELDS = [
     "whenToUse",
     "toc",
     "parameters",
-    "bodyOpening",
     "source",
     "category",
     "supersededBy",
@@ -222,6 +221,8 @@ function indexDocumentFromEntry(entry, base, rendererName) {
         doc.description = entry.description;
     if (entry.tags !== undefined)
         doc.tags = entry.tags;
+    if (entry.content !== undefined)
+        doc.content = entry.content;
     if (entry.aliases !== undefined)
         doc.aliases = entry.aliases;
     if (entry.searchHints !== undefined)

package/dist/core/config/config.js

@@ -347,12 +347,8 @@ export function resolveSecret(value) {
  * filtering out the reserved feature-section keys so callers don't mistake
  * `metadataEnhance` for a pass.
  */
-/**
- * Reserved well-known keys on IndexConfig that are NOT per-pass entries.
- * `indexBodyOpening` (stash-conventions SPEC-8) is a boolean feature flag, not
- * a pass section.
- */
-const INDEX_RESERVED_KEYS = new Set(["metadataEnhance", "indexBodyOpening"]);
+/** Reserved well-known keys on IndexConfig that are NOT per-pass entries. */
+const INDEX_RESERVED_KEYS = new Set(["metadataEnhance"]);
 export function getIndexPassConfig(config, passName) {
     if (!config)
         return undefined;

package/dist/core/config/schema/index-config.js

@@ -99,14 +99,6 @@ const IndexDefaultsSchema = z
  * Index config is a union of reserved feature sections and per-pass entries.
  * Passthrough so per-pass entries (keyed by arbitrary pass names like `graph`,
  * `enrichment`) can live next to the reserved keys.
- *
- * Reserved scalar key `indexBodyOpening` (stash-conventions SPEC-8, default
- * false): when true, the metadata pass captures the first prose paragraph of
- * each markdown asset body into `entry.bodyOpening`, which folds into the
- * lowest-weight `content` FTS column and the embedding text. It is a boolean,
- * not a per-pass object — the preprocess below exempts it from the
- * object-shape check so it never routes into the per-pass catchall.
- *
  * The outer preprocess emits the legacy parser's actionable error messages
  * for the two most common type-shape mistakes:
  *   - An array at the `index` block.
@@ -136,17 +128,6 @@ const IndexConfigRuntimeSchema = z.preprocess((raw, ctx) => {
             });
             return raw;
         }
-        if (passName === "indexBodyOpening") {
-            if (typeof value !== "boolean") {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: "Invalid `index.indexBodyOpening`: expected a boolean (true to index the first body paragraph " +
-                        `of markdown assets into search). Got ${Array.isArray(value) ? "array" : typeof value}.`,
-                });
-                return raw;
-            }
-            continue;
-        }
         if (typeof value !== "object" || value === null || Array.isArray(value)) {
             ctx.addIssue({
                 code: z.ZodIssueCode.custom,
@@ -160,14 +141,6 @@ const IndexConfigRuntimeSchema = z.preprocess((raw, ctx) => {
     .object({
     defaults: IndexDefaultsSchema.optional(),
     metadataEnhance: MetadataEnhanceSchema.optional(),
-    indexBodyOpening: z
-        .boolean()
-        .optional()
-        .describe("Index the first prose paragraph of each markdown asset body (capped at 280 chars) into the " +
-        "lowest-weight `content` search column and the embedding text (default false). Secret/env files " +
-        "and session-kind memories are never captured. Toggling the flag changes indexed text: run " +
-        "`akm index --full` afterwards to re-extract every entry and regenerate embeddings, and re-mint " +
-        "collapse-detector canary baselines via `bun scripts/refresh-canary-set.ts --refresh`."),
 })
     .catchall(IndexPassConfigSchema));
 // The runtime catchall correctly validates arbitrary pass objects, but its

package/dist/indexer/index-written-assets.js

@@ -13,24 +13,25 @@
  * the 2026-07 read-path reindex-contention findings §7).
  *
  * This is NOT a general reindex. It upserts exactly the files the caller just
- * wrote: frontmatter/metadata via the shared matcher pipeline, the `entries`
- * row, and an incremental FTS refresh. Embeddings, index-time LLM passes,
- * graph extraction, `builtAt`, and the per-dir walk cache are all deliberately
- * untouched — the next full run heals them (the opportunistic-recovery
- * strategy of the index-consistency ADR).
+ * wrote: frontmatter/metadata via the shared matcher pipeline, the canonical
+ * row with its transactionally owned FTS projection, and vectors for changed
+ * entry IDs when semantic search is enabled. Index-time LLM passes, graph
+ * extraction, `builtAt`, and the per-dir walk cache remain full-index
+ * responsibilities.
  */
 import fs from "node:fs";
 import path from "node:path";
 import { akmAdapter } from "../core/adapter/adapters/akm-adapter.js";
+import { loadConfig } from "../core/config/config.js";
 import { isDataDirUnreadableError } from "../core/errors.js";
 import { isPathAbsent } from "../core/path-access.js";
 import { getDbPath } from "../core/paths.js";
 import { warn, warnVerbose } from "../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "../storage/repositories/index-connection.js";
 import { deleteEntriesByIds, getEntryCount, upsertEntry } from "../storage/repositories/index-entries-repository.js";
-import { rebuildFts } from "../storage/repositories/index-fts-repository.js";
 import { withIndexWriterLease } from "./index-writer-lock.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
+import { generateEmbeddingsForDb, publishTargetedSemanticStatus } from "./materialize-embeddings.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildSearchText } from "./search/search-fields.js";
 import { buildFileContext } from "./walk/file-context.js";
@@ -127,6 +128,8 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
                 db.exec(`PRAGMA busy_timeout = ${WRITE_PATH_INDEX_BUSY_TIMEOUT_MS}`);
                 if (getEntryCount(db) === 0)
                     return true;
+                const targetEntryIds = new Set();
+                let mutated = false;
                 db.transaction(() => {
                     const unindexableEntryIds = new Set();
                     for (const file of unindexable) {
@@ -151,6 +154,7 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
                             unindexableEntryIds.add(row.id);
                     }
                     deleteEntriesByIds(db, [...unindexableEntryIds]);
+                    mutated ||= unindexableEntryIds.size > 0;
                     for (const { file, entry, conceptId, contentHash } of pairs) {
                         let entryWithSize = entry;
                         try {
@@ -171,11 +175,15 @@ export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
                             .prepare("SELECT id FROM entries WHERE file_path = ? AND item_ref <> ?")
                             .all(file, provenance.itemRef);
                         deleteEntriesByIds(db, supersededIds.map((row) => row.id));
-                        upsertEntry(db, file, entryWithSize, buildSearchText(entry), provenance, contentHash);
+                        targetEntryIds.add(upsertEntry(db, file, entryWithSize, buildSearchText(entry), provenance, contentHash));
+                        mutated = true;
                     }
-                    if (pairs.length > 0 || unindexable.size > 0)
-                        rebuildFts(db, { incremental: true });
                 })();
+                if (mutated) {
+                    const config = loadConfig();
+                    const embeddingResult = await generateEmbeddingsForDb(db, config, () => { }, undefined, [...targetEntryIds]);
+                    publishTargetedSemanticStatus(db, config, embeddingResult);
+                }
             }
             finally {
                 closeDatabase(db);

package/dist/indexer/indexer.js

@@ -20,22 +20,22 @@ import { resolveIndexPassExecution } from "../llm/index-passes.js";
 import { preflightStructuredLlmRunner } from "../llm/structured-call.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { closeDatabase, openExistingDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from "../storage/repositories/index-connection.js";
-import { deleteEntriesByBundle, deleteEntriesByDirAndBundle, deleteEntriesByDirExceptRefs, deleteEntriesByIds, deleteUsageEventsByEntryIds, findEntryIdByRef, getAllEntries, getEmbeddableEntryCount, getEntryCount, getIndexedBundleIdsByDir, getIndexedDirPathsByBundleId, relinkUsageEvents, upsertEntry, } from "../storage/repositories/index-entries-repository.js";
-import { rebuildFts } from "../storage/repositories/index-fts-repository.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, deleteMeta, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
+import { deleteIndexDirState, getMeta, setMeta, upsertIndexDirState, } from "../storage/repositories/index-meta-repository.js";
 import { upsertUtilityScore } from "../storage/repositories/index-utility-repository.js";
-import { getAllEntriesForEmbedding, getEmbeddingCount, isVecAvailable, isVecFastPathReady, purgeEmbeddings, setVecFastPathReady, upsertEmbedding, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
+import { getEmbeddingCount, isVecAvailable, isVecFastPathReady, warnIfVecMissing, } from "../storage/repositories/index-vec-repository.js";
 import { assertIndexedWorkflowSourceIdentity, WorkflowSourceIdentityError } from "../workflows/source-files.js";
 import { deleteStoredGraph } from "./db/graph-db.js";
 import { withIndexWriterLease } from "./index-writer-lock.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { indexedPathMatchesOwner, resolveAdapterConceptOwner, } from "./lookup/adapter-concept-owner.js";
+import { generateEmbeddingsForDb } from "./materialize-embeddings.js";
 import { canUseIncrementalSkip, computeDirFingerprint, getCachedZeroRowDirState, getDirIndexState, inferZeroRowReason, } from "./passes/dir-staleness.js";
 import { isEnrichmentComplete, isWorkflowSkipWarning } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
 import { buildSearchText } from "./search/search-fields.js";
-import { classifySemanticFailure, clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "./search/semantic-status.js";
+import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus } from "./search/semantic-status.js";
 import { purgeOldUsageEvents } from "./usage/usage-events.js";
 import { walkStashFlatWithStatus } from "./walk/walker.js";
 function collectLoweringNotices(target, notices) {
@@ -205,19 +205,18 @@ async function runEmbeddingPhase(ctx) {
     ctx.timing.tEmbedEnd = Date.now();
 }
 /**
- * Finalize phase: rebuild FTS, re-link usage events, recompute utility scores,
- * regenerate wiki indexes, update index metadata, and emit the verify event.
+ * Finalize phase: confirm transactionally materialized FTS state, re-link
+ * usage events, recompute utility scores, update index metadata, and emit the
+ * verify event.
  */
 async function runFinalizePhase(ctx, deferredUpdateTransaction) {
     const { db, config, sources, sourceDirs, isIncremental, stashDir, signal, onProgress } = ctx;
     ctx.timing.tFinalizeStart = Date.now();
-    // Rebuild FTS after all inserts. Use incremental mode when this whole
-    // index run is incremental — only entries touched by `upsertEntry`
-    // since the last rebuild are re-indexed.
-    rebuildFts(db, { incremental: isIncremental });
+    // `upsertEntry` and every canonical delete own their FTS projection. This is
+    // an observation point, not a second materialization pass.
     onProgress({
         phase: "fts",
-        message: isIncremental ? "Rebuilt full-text search index (dirty rows only)." : "Rebuilt full-text search index.",
+        message: "Full-text search index is current.",
     });
     ctx.timing.tFtsEnd = Date.now();
     // Re-link state.db usage events to the regenerated index and recompute the
@@ -261,11 +260,6 @@ async function runFinalizePhase(ctx, deferredUpdateTransaction) {
         setMeta(db, "sourceOwners", JSON.stringify(sourceOwners(sources)));
     }
     setMeta(db, "hasEmbeddings", embeddingResult.success ? "1" : "0");
-    // Stash-organization conventions (SPEC-8): track which `index.indexBodyOpening`
-    // state the index was built with, and warn while the flag diverges from it.
-    const bodyOpeningWarning = reconcileBodyOpeningIndexState(db, config.index?.indexBodyOpening === true, (ctx.full || !isIncremental) && ctx.scanComplete);
-    if (bodyOpeningWarning)
-        warn(bodyOpeningWarning);
     warnIfVecMissing(db);
     const totalEntries = getEntryCount(db);
     const semanticEntryCount = getEmbeddableEntryCount(db);
@@ -300,45 +294,10 @@ async function runFinalizePhase(ctx, deferredUpdateTransaction) {
     // suppress unused warning — sources was previously used inline
     void sources;
 }
-/**
- * Stash-organization conventions (SPEC-8): reconcile the `index.indexBodyOpening`
- * flag with the state the index was last FULLY built with (index_meta key
- * `indexBodyOpening`), returning a warning message while they diverge.
- *
- * Incremental runs re-extract only changed files (and embeddings are only
- * generated for rows lacking one), so a flag toggle leaves the index MIXED
- * until a full rebuild — `akm index --full` re-extracts every entry and wipes
- * embeddings so they regenerate from the new text. The warning therefore
- * repeats on every incremental run until a full walk records the flag state
- * as applied.
- *
- * A missing meta key on an incremental run means the index predates this
- * feature, i.e. it was necessarily built with the flag OFF — so the absent
- * key reads (and is seeded) as "0", never as the current flag value. This
- * keeps the most likely real toggle scenario — upgrade, enable the flag, run
- * a plain `akm index` — warning until `--full` runs (review finding).
- *
- * Exported for tests; production's only caller is the finalize phase above.
- */
-export function reconcileBodyOpeningIndexState(db, flagEnabled, isFullWalk) {
-    const bodyOpeningFlag = flagEnabled ? "1" : "0";
-    const prevBodyOpeningFlag = getMeta(db, "indexBodyOpening") ?? "0";
-    // Only a full walk (which includes the first build ever) may record the
-    // current flag as the applied state; incremental runs preserve — or, for a
-    // pre-feature index, seed — the state of the last full build.
-    setMeta(db, "indexBodyOpening", isFullWalk ? bodyOpeningFlag : prevBodyOpeningFlag);
-    if (isFullWalk || prevBodyOpeningFlag === bodyOpeningFlag)
-        return undefined;
-    return (`index.indexBodyOpening is ${flagEnabled ? "enabled" : "disabled"} but the index was built with it ` +
-        `${flagEnabled ? "disabled" : "enabled"}. Incremental runs only re-extract changed files, so ` +
-        "indexed text and embeddings are stale for unchanged entries. Run `akm index --full` to apply the new " +
-        "setting everywhere (embeddings regenerate), and re-mint collapse-detector canary baselines via " +
-        "`bun scripts/refresh-canary-set.ts --refresh` if you use them.");
-}
 // ── Clean pass ───────────────────────────────────────────────────────────────
 /**
- * Post-index clean pass: scan the `entries` table for rows whose source file
- * no longer exists on disk and remove them (unless `dryRun` is true).
+ * Missing-file reconciliation: scan the `entries` table for rows whose source
+ * file no longer exists on disk and remove them (unless `dryRun` is true).
  *
  * Only rows with a non-empty `file_path` are checked — remote/virtual entries
  * that have no local path are always skipped.
@@ -629,22 +588,17 @@ async function akmIndexReal(options) {
                     vecAvailable: isVecAvailable(db),
                 }),
             });
+            let cleanResult;
+            let cleanStart = Date.now();
+            let cleanEnd = cleanStart;
             // ── Phase sequence ───────────────────────────────────────────────────────
             await runSourceCachePhase(ctx);
             await runWalkPhase(ctx);
             applyRemovedSources(ctx);
-            await runEmbeddingPhase(ctx);
-            await runFinalizePhase(ctx, options.deferredUpdateTransaction);
-            // ────────────────────────────────────────────────────────────────────────
-            // runFinalizePhase always populates these before returning.
-            const verification = ctx.verification;
-            const totalEntries = ctx.totalEntries;
-            const { timing } = ctx;
-            // ── Clean pass ───────────────────────────────────────────────────────────
-            // After the normal index completes, remove entries whose source files no
-            // longer exist on disk. Remote entries (empty file_path) are skipped.
-            let cleanResult;
-            const cleanStart = Date.now();
+            // Reconcile explicit missing-file cleanup before embeddings, totals, or
+            // verification describe this generation. Dry-run intentionally leaves
+            // the generation unchanged while still returning the previewed refs.
+            cleanStart = Date.now();
             if (clean) {
                 onProgress({
                     phase: "finalize",
@@ -658,8 +612,14 @@ async function akmIndexReal(options) {
                     cleanResult = { checked: 0, removed: 0, removedRefs: [], dryRun };
                 }
             }
-            const cleanEnd = Date.now();
+            cleanEnd = Date.now();
+            await runEmbeddingPhase(ctx);
+            await runFinalizePhase(ctx, options.deferredUpdateTransaction);
             // ────────────────────────────────────────────────────────────────────────
+            // runFinalizePhase always populates these before returning.
+            const verification = ctx.verification;
+            const totalEntries = ctx.totalEntries;
+            const { timing } = ctx;
             return {
                 stashDir,
                 totalEntries,
@@ -668,6 +628,7 @@ async function akmIndexReal(options) {
                 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
@@ -1151,28 +1112,15 @@ function persistDirRecords(db, dirRecords, doFullDelete, warnings, sourceRoots,
         // transaction so delete and re-insert are atomic — a concurrent reader
         // never observes an empty database between the two operations.
         if (fullDelete) {
-            try {
-                db.exec("DELETE FROM embeddings");
-            }
-            catch {
-                /* ignore */
-            }
-            if (isVecAvailable(db)) {
-                try {
-                    db.exec("DELETE FROM entries_vec");
-                }
-                catch {
-                    /* ignore */
-                }
-            }
-            db.exec("DELETE FROM entries_fts");
-            db.exec("DELETE FROM utility_scores");
+            // Entries and every child materialization share one deletion authority.
+            // Usage events live in state.db and survive so finalize can relink them
+            // to the replacement generation's row ids.
+            deleteAllEntries(db, { cleanupUsageEvents: false });
             db.exec("DELETE FROM index_dir_state");
             // Chunk-8 WI-8.3: usage_events lives in state.db now (not index.db), so the
             // wipe no longer detaches it here. The finalize pass's relinkUsageEvents
             // (cross-DB) nulls entry_ids that no longer resolve to a rebuilt entry and
             // re-resolves the rest by entry_ref — subsuming the old detach.
-            db.exec("DELETE FROM entries");
             // Atomicity observation point: inside the transaction the tables are now
             // empty, but no other connection may observe that. See
             // tests/integration/indexer/reindex-generation-atomicity.test.ts.
@@ -1506,136 +1454,6 @@ export function createEnrichmentDeadline(timeoutMs, totalEntries) {
     const perEntryTimeoutMs = timeoutMs === undefined ? 10 * 60 * 1000 : timeoutMs;
     return perEntryTimeoutMs === null ? undefined : AbortSignal.timeout(perEntryTimeoutMs * Math.max(totalEntries, 1));
 }
-async function generateEmbeddingsForDb(db, config, onProgress, signal) {
-    throwIfAborted(signal);
-    if (config.semanticSearchMode === "off") {
-        onProgress({ phase: "embeddings", message: "Semantic search disabled; skipping embeddings." });
-        return { success: false, reason: "index-missing", message: "Semantic search is disabled." };
-    }
-    // Detect embedding model/provider changes and purge stale embeddings
-    // so that incremental reindex regenerates all vectors with the new model.
-    const currentFingerprint = deriveSemanticProviderFingerprint(config.embedding);
-    const storedFingerprint = getMeta(db, "embeddingFingerprint");
-    if (storedFingerprint && storedFingerprint !== currentFingerprint) {
-        // Model/provider changed → stored vectors are incompatible. Clear them;
-        // re-embedded by this index run.
-        //
-        // The vec table goes too. "Same dimension, so keep the vec table" only held
-        // for a same-width model swap: entries_vec is a vec0 virtual table declared
-        // at a FIXED width, so after a dimension-changing model change every insert
-        // failed against the old width, and ensureSchema's dim-change rebuild never
-        // fired because it only runs for callers that pass an explicit
-        // embeddingDim. The stale table survived `--full` — the exact remedy the
-        // warning recommended. Clearing the stored dim lets the next ensureSchema
-        // materialize it at the new width; until then the fast-path flag reads
-        // false (no table) and search uses the complete BLOB table.
-        purgeEmbeddings(db, { dropVecTable: true });
-        deleteMeta(db, "embeddingDim");
-    }
-    try {
-        const { embedBatch } = await import("../llm/embedder.js");
-        const { estimateTokenCount } = await import("../llm/embedders/remote.js");
-        throwIfAborted(signal);
-        const allEntries = getAllEntriesForEmbedding(db);
-        if (allEntries.length === 0) {
-            onProgress({ phase: "embeddings", message: "Embeddings already up to date." });
-            setMeta(db, "embeddingFingerprint", currentFingerprint);
-            return { success: true };
-        }
-        onProgress({
-            phase: "embeddings",
-            message: `Generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}.`,
-        });
-        const texts = allEntries.map((e) => e.searchText);
-        // Verbose: log each document before it is sent to the embedding API so
-        // operators can see exactly where embedding fails without waiting for an error.
-        if (isVerbose()) {
-            const EMBED_BATCH_SIZE = 100; // mirrors REMOTE_BATCH_SIZE in remote.ts
-            const totalBatches = Math.ceil(texts.length / EMBED_BATCH_SIZE);
-            for (let i = 0; i < texts.length; i++) {
-                const batchNum = Math.floor(i / EMBED_BATCH_SIZE) + 1;
-                const chars = texts[i].length;
-                const tokens = estimateTokenCount(texts[i]);
-                const ref = allEntries[i].itemRef;
-                warnVerbose(`[embed] ${ref} (${chars} chars, est. ${tokens} tokens) → batch ${batchNum}/${totalBatches}`);
-            }
-        }
-        let heartbeatTimer;
-        try {
-            heartbeatTimer = setInterval(() => {
-                onProgress({
-                    phase: "embeddings",
-                    message: `Still generating embeddings for ${allEntries.length} entr${allEntries.length === 1 ? "y" : "ies"}; waiting on embedding provider.`,
-                });
-            }, 15000);
-            const embeddings = await embedBatch(texts, config.embedding, signal);
-            throwIfAborted(signal);
-            // Wrap all embedding upserts in a single transaction so partial
-            // state is rolled back on failure rather than leaving the table half-filled.
-            let storedCount = 0;
-            let skippedCount = 0;
-            let vecFailedCount = 0;
-            let vecUnavailableCount = 0;
-            db.transaction(() => {
-                for (let i = 0; i < allEntries.length; i++) {
-                    const res = upsertEmbedding(db, allEntries[i].id, embeddings[i]);
-                    if (res.stored) {
-                        storedCount++;
-                    }
-                    else {
-                        skippedCount++;
-                    }
-                    if (res.vec === "failed")
-                        vecFailedCount++;
-                    if (res.vec === "unavailable")
-                        vecUnavailableCount++;
-                }
-            })();
-            if (skippedCount > 0) {
-                warn(`[embed] ${skippedCount} embedding${skippedCount === 1 ? "" : "s"} skipped (entry deleted between queue and write)`);
-            }
-            // Record the ACTUAL vec-insert outcome so semantic search reflects it
-            // instead of inferring readiness from stored-BLOB counts. Any failure
-            // marks the fast path degraded, routing search to the JS-cosine fallback
-            // over the (complete) BLOB table — honest degradation, not a hard failure.
-            //
-            // 'unavailable' has to degrade the flag too. It means no vec row was
-            // written at all, so marking the fast path ready left a later open (a
-            // different runtime, or sqlite-vec installed afterwards) trusting an
-            // empty entries_vec and returning zero semantic hits against a fully
-            // populated BLOB table.
-            setVecFastPathReady(db, vecFailedCount === 0 && vecUnavailableCount === 0);
-            if (vecFailedCount > 0) {
-                warn(`[embed] ${vecFailedCount} sqlite-vec fast-path insert${vecFailedCount === 1 ? "" : "s"} failed — ` +
-                    "semantic search will use the slower JS-cosine fallback over stored embeddings. " +
-                    "Rebuild with 'akm index --full' after resolving the vec table (often a vector-dimension mismatch).");
-            }
-            onProgress({
-                phase: "embeddings",
-                message: `Stored ${storedCount} embedding${storedCount === 1 ? "" : "s"}.`,
-            });
-            setMeta(db, "embeddingFingerprint", currentFingerprint);
-            return { success: true, vecInsertFailures: vecFailedCount };
-        }
-        finally {
-            if (heartbeatTimer)
-                clearInterval(heartbeatTimer);
-        }
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        warn("Embedding generation failed, continuing without:", message);
-        onProgress({
-            phase: "embeddings",
-            message: `Embedding generation failed: ${message}`,
-        });
-        return {
-            success: false,
-            reason: classifySemanticFailure(message),
-            message: `Semantic search verification failed: ${message}`,
-        };
-    }
-}
 // ── Helpers ─────────────────────────────────────────────────────────────────
 function attachFileSize(entry, entryPath) {
     try {