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

package/dist/indexer/graph/graph-related.js

@@ -0,0 +1,130 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Find graph files that share entities with the given file.
+ *
+ * Implementation: SQL self-join on graph_file_entities, scoped by stash_root,
+ * grouped by file_path, ordered by shared-entity count desc. Touches ~50-200
+ * rows instead of loading the entire snapshot into memory. Cold-call latency
+ * drops from ~30-60ms (full snapshot parse) to ~2-5ms on typical stashes.
+ *
+ * #624-P1: the graph tables are keyed on (stash_root, file_path, body_hash) —
+ * NOT entries.id — so candidates are identified by file_path (the unique index
+ * idx_graph_files_path guarantees one graph_files row per path).
+ *
+ * The returned `ref` field carries the canonical indexed `concept_id`, never a
+ * value re-derived from presentation fields. It is undefined
+ * when the graph row has no matching entry with current indexed provenance.
+ */
+export function listRelatedPathsForFile(stashRoot, filePath, limit = 5, db) {
+    if (!db) {
+        // Fallback: opening a transient DB here is not currently a use case (all
+        // callers pass a handle), so degrade to empty rather than reopening.
+        return [];
+    }
+    // Confirm the target file has a graph row; without it there is nothing to
+    // relate. (Identity is file_path within the stash — one row per path.)
+    const row = db
+        .prepare("SELECT 1 AS present FROM graph_files WHERE stash_root = ? AND file_path = ? LIMIT 1")
+        .get(stashRoot, filePath);
+    if (row === undefined)
+        return [];
+    const effectiveLimit = Math.max(1, limit);
+    // Shared-entity count per candidate file_path. The target's entities are the
+    // rows for `filePath`; candidates are any OTHER file_path in the stash that
+    // shares a normalized entity.
+    const candidateRows = db
+        .prepare(`SELECT gf.file_path   AS file_path,
+              gf.file_type   AS file_type,
+              COUNT(*)       AS shared
+          FROM graph_file_entities target
+          JOIN graph_file_entities e
+            ON e.stash_root = target.stash_root
+           AND e.entity_norm = target.entity_norm
+           AND e.file_path  != target.file_path
+          JOIN graph_files gf
+            ON gf.stash_root = e.stash_root
+           AND gf.file_path = e.file_path
+           AND gf.body_hash = e.body_hash
+        WHERE target.file_path  = ?
+          AND target.stash_root = ?
+        GROUP BY gf.file_path
+        ORDER BY shared DESC, gf.file_path ASC
+        LIMIT ?`)
+        .all(filePath, stashRoot, effectiveLimit);
+    if (candidateRows.length === 0)
+        return [];
+    const candidatePaths = candidateRows.map((r) => r.file_path);
+    const placeholders = candidatePaths.map(() => "?").join(",");
+    // Pull the shared entity names (joined by normalized casing) for display, in
+    // a fixed order so identical calls return identical results.
+    const sharedRows = db
+        .prepare(`SELECT e.file_path AS file_path, e.entity AS entity
+         FROM graph_file_entities e
+         JOIN graph_file_entities target
+           ON target.stash_root = e.stash_root
+           AND target.entity_norm = e.entity_norm
+         WHERE e.file_path IN (${placeholders})
+           AND e.stash_root = ?
+           AND target.file_path = ?
+           AND target.stash_root = ?
+         ORDER BY e.file_path, e.entity`)
+        .all(...candidatePaths, stashRoot, filePath, stashRoot);
+    const sharedByPath = new Map();
+    for (const row of sharedRows) {
+        let bucket = sharedByPath.get(row.file_path);
+        if (!bucket) {
+            bucket = new Set();
+            sharedByPath.set(row.file_path, bucket);
+        }
+        bucket.add(row.entity);
+    }
+    // Relation count for each candidate (relations where either endpoint
+    // matches one of the shared entities).
+    const relationCountByPath = new Map();
+    const relationRows = db
+        .prepare(`SELECT file_path, from_entity, to_entity
+         FROM graph_file_relations
+        WHERE file_path IN (${placeholders})
+          AND stash_root = ?`)
+        .all(...candidatePaths, stashRoot);
+    for (const row of relationRows) {
+        const shared = sharedByPath.get(row.file_path);
+        if (!shared)
+            continue;
+        if (shared.has(row.from_entity) || shared.has(row.to_entity)) {
+            relationCountByPath.set(row.file_path, (relationCountByPath.get(row.file_path) ?? 0) + 1);
+        }
+    }
+    // This related list is scoped to one source root, so the user-facing ref is
+    // the indexed bundle-less conceptId.
+    const refByPath = new Map();
+    try {
+        const entryRows = db
+            .prepare(`SELECT file_path, concept_id FROM entries
+          WHERE file_path IN (${placeholders})
+          ORDER BY file_path, concept_id`)
+            .all(...candidatePaths);
+        // Several entries can index one file; the first concept id wins.
+        for (const row of entryRows) {
+            if (!refByPath.has(row.file_path))
+                refByPath.set(row.file_path, row.concept_id);
+        }
+    }
+    catch {
+        /* ignore — refs are best-effort */
+    }
+    return candidateRows.map((row) => {
+        const sharedSet = sharedByPath.get(row.file_path) ?? new Set();
+        const sharedEntities = [...sharedSet].sort((a, b) => a.localeCompare(b));
+        const ref = refByPath.get(row.file_path);
+        return {
+            ...(ref ? { ref } : {}),
+            path: row.file_path,
+            type: row.file_type,
+            sharedEntities,
+            relationCount: relationCountByPath.get(row.file_path) ?? 0,
+        };
+    });
+}

package/dist/indexer/index-rebuild-lock.js

@@ -20,7 +20,6 @@
  * no-stale-age-window rationale.
  */
 import { releaseLock } from "../core/file-lock.js";
-import { tryWithMaintenanceStartBarrier, withMaintenanceStartBarrier } from "../core/maintenance-barrier.js";
 import { getIndexRebuildLockPath } from "../core/paths.js";
 import { formatLockHolderPid, tryAcquireRunLock } from "../core/run-lock.js";
 import { warn, warnVerbose } from "../core/warn.js";
@@ -49,21 +48,14 @@ export function tryAcquireIndexRebuildLock(skipIfLocked) {
                 `(${info.reason}); that process is no longer running.`);
         },
     });
+    const result = acquire();
+    if (result.state === "acquired")
+        return result;
     if (skipIfLocked) {
-        const result = tryWithMaintenanceStartBarrier(acquire);
-        if (!result) {
-            warn("[index] maintenance barrier held; skipping (--skip-if-locked)");
-            return { state: "skipped", holder: { pid: null, startedAt: null, launcherPid: null } };
-        }
-        if (result.state === "acquired")
-            return result;
         warn(`[index] another index run holds the lock (PID ${formatLockHolderPid(result.holder)}, started ${result.holder.startedAt}); ` +
             "skipping (--skip-if-locked)");
         return { state: "skipped", holder: result.holder };
     }
-    const result = withMaintenanceStartBarrier(acquire);
-    if (result.state === "acquired")
-        return result;
     warn(`[index] another index run is active (pid ${formatLockHolderPid(result.holder)}, started ${result.holder.startedAt}); ` +
         "this run will contend with it — pass --skip-if-locked for scheduled runs");
     return { state: "contended", holder: result.holder };

package/dist/indexer/index-writer-lock.js

@@ -25,8 +25,8 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import fs from "node:fs";
 import path from "node:path";
+import { TransientError } from "../core/errors.js";
 import { createLockPayload, probeLock, reclaimStaleLock, releaseLock, tryAcquireLockSync, } from "../core/file-lock.js";
-import { tryAcquireMaintenanceBarrier } from "../core/maintenance-barrier.js";
 import { getDbPath, getIndexWriterLockPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
 import { sleepSync } from "../runtime.js";
@@ -92,21 +92,12 @@ function createLease(lockPath, ownership) {
 }
 function tryAcquireAssetMutationLease(lockPath, purpose) {
     while (true) {
-        const releaseBarrier = tryAcquireMaintenanceBarrier();
-        if (!releaseBarrier)
+        const ownership = tryAcquireLockSync(lockPath, buildPayload(purpose));
+        if (ownership)
+            return createLease(lockPath, ownership);
+        const probe = probeLock(lockPath);
+        if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
             return undefined;
-        try {
-            const ownership = tryAcquireLockSync(lockPath, buildPayload(purpose));
-            if (ownership)
-                return createLease(lockPath, ownership);
-            // No `staleAfterMs`: only a verifiably dead holder is ever reclaimed.
-            const probe = probeLock(lockPath);
-            if (probe.state !== "stale" || !reclaimStaleLock(lockPath, probe))
-                return undefined;
-        }
-        finally {
-            releaseBarrier();
-        }
     }
 }
 export async function acquireAssetMutationLease(options) {
@@ -129,7 +120,7 @@ export async function acquireAssetMutationLease(options) {
         // attempt, so a caller with maxWaitMs:0 still gets one chance at a free lock
         // instead of throwing before it ever tries.
         if (maxWaitMs >= 0 && Date.now() - startedAt >= maxWaitMs) {
-            throw new Error(`timed out waiting for asset mutation lease for ${options.purpose}`);
+            throw new TransientError(`timed out waiting for asset mutation lease for ${options.purpose}`, "ASSET_MUTATION_LEASE_HELD");
         }
         const waitedMs = Date.now() - startedAt;
         if (waitedMs - lastWaitNoticeMs >= 15000) {
@@ -180,7 +171,7 @@ export function withAssetMutationLeaseSync(purpose, run) {
             if (!lease) {
                 const waitedMs = Date.now() - startedAt;
                 if (waitedMs >= maxWaitMs) {
-                    throw new Error(`timed out waiting for asset mutation lease for ${purpose}`);
+                    throw new TransientError(`timed out waiting for asset mutation lease for ${purpose}`, "ASSET_MUTATION_LEASE_HELD");
                 }
                 // #956: the sync path used to wait up to 10 minutes with zero
                 // progress feedback. Mirror the async path's 15s onWait cadence, but

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

@@ -33,9 +33,8 @@ import { closeDatabase, openExistingDatabase } from "../storage/repositories/ind
 import { deleteEntriesByIds, getEntryCount, upsertEntry } from "../storage/repositories/index-entries-repository.js";
 import { deriveEntryProvenance, deriveInstallations } from "./installations.js";
 import { generateEmbeddingsForDb, publishTargetedEmbeddingMeta } from "./materialize-embeddings.js";
-import { getMarkdownFragmentContent, hasMarkdownFragmentContent, setMarkdownFragmentContent, } from "./passes/metadata.js";
+import { withFileSize } from "./passes/metadata.js";
 import { drainDirDocuments } from "./scan/drain-dir.js";
-import { buildSearchText } from "./search/search-fields.js";
 import { buildFileContext } from "./walk/file-context.js";
 /**
  * Busy-timeout (ms) for write-path index upserts. A real write — unlike the
@@ -66,161 +65,150 @@ export const WRITE_PATH_INDEX_BUSY_TIMEOUT_MS = 5_000;
  */
 export async function indexWrittenAssets(stashDir, filePaths, options = {}) {
     try {
-        return await (async () => {
-            // #956: a live `akm index` rebuild holds index.db under one long
-            // transaction (persistDirRecords), which this fast path's own 5s
-            // busy_timeout would just contend with pointlessly. Interactive
-            // commands (remember, import, extract session assets) must never wait
-            // on it — skip the inline upsert/embedding entirely; the write itself
-            // (file + commit) has already succeeded by the time this runs, and the
-            // rebuild in progress will pick up the change on its own.
-            const rebuildProbe = probeLock(getIndexRebuildLockPath());
-            if (rebuildProbe.state === "held") {
-                // #956: name the launcher pid alongside the holder pid when known —
-                // every process listing and task log shows the launcher's pid, not
-                // the bun/node child's.
-                const holderLabel = formatLockHolderPid({
-                    pid: rebuildProbe.holderPid,
-                    launcherPid: rebuildProbe.launcherPid ?? null,
-                });
-                warn(`index rebuild in progress (pid ${holderLabel}); the next index pass will index ${filePaths.join(", ")}`);
-                return true;
-            }
-            const dbPath = getDbPath();
-            // `true` here means "the index is in the state the caller expects" — and
-            // `acceptProposal` advances its journal to `index-finalized` on the
-            // strength of it. Only a genuinely ABSENT index earns that answer: an
-            // index we cannot read has NOT been updated, so it falls through to
-            // `openExistingDatabase` and surfaces as the honest `false` (#791).
-            if (isPathAbsent(dbPath))
-                return true;
-            // The full walk never descends into dot-directories (for example `.meta/`)
-            // — mirror that dot-segment skip here so this fast path indexes exactly
-            // what a full run would. Sensitive/
-            // infra abstention is the adapter's job now (see the `akmAdapter` note
-            // below), not a path pre-filter.
-            const files = filePaths.filter((f) => {
-                const rel = path.relative(stashDir, f);
-                return !rel.split(/[\\/]+/).some((segment) => segment.startsWith("."));
+        // #956: a live `akm index` rebuild holds index.db under one long
+        // transaction (persistDirRecords), which this fast path's own 5s
+        // busy_timeout would just contend with pointlessly. Interactive
+        // commands (remember, import, extract session assets) must never wait
+        // on it — skip the inline upsert/embedding entirely; the write itself
+        // (file + commit) has already succeeded by the time this runs, and the
+        // rebuild in progress will pick up the change on its own.
+        const rebuildProbe = probeLock(getIndexRebuildLockPath());
+        if (rebuildProbe.state === "held") {
+            // #956: name the launcher pid alongside the holder pid when known —
+            // every process listing and task log shows the launcher's pid, not
+            // the bun/node child's.
+            const holderLabel = formatLockHolderPid({
+                pid: rebuildProbe.holderPid,
+                launcherPid: rebuildProbe.launcherPid ?? null,
             });
-            if (files.length === 0)
-                return true;
-            // Generate metadata BEFORE opening the DB so the write window stays
-            // short. One drain call per file keeps the entry↔path pairing exact and
-            // reuses the full-index recognize engine (F4a M-core-2 item 5): broken
-            // workflows drop, valid workflow docs are cached for the side-table upsert.
-            const component = deriveInstallations([
-                { path: stashDir, writable: true, ...(options.bundleId ? { registryId: options.bundleId } : {}) },
-            ])[0]?.components[0];
-            if (!component)
-                throw new Error(`Could not derive bundle provenance for ${stashDir}`);
-            const pairs = [];
-            const unindexable = new Set();
-            const rejectedConceptIds = new Set();
-            for (const file of files) {
-                if (!fs.existsSync(file)) {
-                    let authoredDanglingSymlink = false;
-                    try {
-                        authoredDanglingSymlink = fs.lstatSync(file).isSymbolicLink();
-                    }
-                    catch {
-                        // A genuinely absent path has no source identity to preflight.
-                    }
-                    if (!authoredDanglingSymlink) {
-                        unindexable.add(file);
-                        continue;
-                    }
+            warn(`index rebuild in progress (pid ${holderLabel}); the next index pass will index ${filePaths.join(", ")}`);
+            return true;
+        }
+        const dbPath = getDbPath();
+        // `true` here means "the index is in the state the caller expects" — and
+        // `acceptProposal` advances its journal to `index-finalized` on the
+        // strength of it. Only a genuinely ABSENT index earns that answer: an
+        // index we cannot read has NOT been updated, so it falls through to
+        // `openExistingDatabase` and surfaces as the honest `false` (#791).
+        if (isPathAbsent(dbPath))
+            return true;
+        // The full walk never descends into dot-directories (for example `.meta/`)
+        // — mirror that dot-segment skip here so this fast path indexes exactly
+        // what a full run would. Sensitive/
+        // infra abstention is the adapter's job now (see the `akmAdapter` note
+        // below), not a path pre-filter.
+        const files = filePaths.filter((f) => {
+            const rel = path.relative(stashDir, f);
+            return !rel.split(/[\\/]+/).some((segment) => segment.startsWith("."));
+        });
+        if (files.length === 0)
+            return true;
+        // Generate metadata BEFORE opening the DB so the write window stays
+        // short. One drain call per file keeps the entry↔path pairing exact and
+        // reuses the full-index recognize engine (F4a M-core-2 item 5): broken
+        // workflows drop, valid workflow docs are cached for the side-table upsert.
+        const component = deriveInstallations([
+            { path: stashDir, writable: true, ...(options.bundleId ? { registryId: options.bundleId } : {}) },
+        ])[0]?.components[0];
+        if (!component)
+            throw new Error(`Could not derive bundle provenance for ${stashDir}`);
+        const pairs = [];
+        const unindexable = new Set();
+        const rejectedConceptIds = new Set();
+        for (const file of files) {
+            if (!fs.existsSync(file)) {
+                let authoredDanglingSymlink = false;
+                try {
+                    authoredDanglingSymlink = fs.lstatSync(file).isSymbolicLink();
+                }
+                catch {
+                    // A genuinely absent path has no source identity to preflight.
                 }
-                const ctx = buildFileContext(stashDir, file);
-                // Hardcoded `akmAdapter` on purpose (owner ruling 2026-07-21): this
-                // write-path fast path only ever runs for assets a first-class akm
-                // mutation command just wrote into a managed akm source, so the akm
-                // adapter is always the right recognizer here — no per-component
-                // dispatch needed.
-                const drained = drainDirDocuments(akmAdapter, component, [ctx]);
-                for (const rejectedPath of drained.rejectedPaths)
-                    unindexable.add(rejectedPath);
-                for (const conceptId of drained.rejectedConceptIds)
-                    rejectedConceptIds.add(conceptId);
-                const entry = drained.entries[0];
-                // A broken workflow drains to zero entries and is treated as
-                // unindexable; valid peer sources have already compiled to source IR.
-                const conceptId = drained.conceptIdByFile.get(ctx.absPath);
-                if (entry && conceptId)
-                    pairs.push({ file, entry, conceptId, contentHash: drained.hashByFile.get(ctx.absPath) });
-                else
+                if (!authoredDanglingSymlink) {
                     unindexable.add(file);
-            }
-            const db = openExistingDatabase(dbPath);
-            try {
-                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) {
-                        const rows = db
-                            .prepare(`SELECT id FROM entries
-                  WHERE file_path = ?
-                    AND bundle_id = ?
-                    AND adapter_id = ?`)
-                            .all(file, component.id, component.adapter);
-                        for (const row of rows)
-                            unindexableEntryIds.add(row.id);
-                    }
-                    for (const conceptId of rejectedConceptIds) {
-                        const itemRef = `${component.id}//${conceptId}`;
-                        const rows = db
-                            .prepare(`SELECT id FROM entries
-                  WHERE bundle_id = ? AND adapter_id = ?
-                    AND type = 'workflow'
-                    AND (concept_id = ? OR item_ref = ?)`)
-                            .all(component.id, component.adapter, conceptId, itemRef);
-                        for (const row of rows)
-                            unindexableEntryIds.add(row.id);
-                    }
-                    deleteEntriesByIds(db, [...unindexableEntryIds]);
-                    mutated ||= unindexableEntryIds.size > 0;
-                    for (const { file, entry, conceptId, contentHash } of pairs) {
-                        let entryWithSize = entry;
-                        try {
-                            entryWithSize = { ...entry, fileSize: fs.statSync(file).size };
-                            if (hasMarkdownFragmentContent(entry)) {
-                                setMarkdownFragmentContent(entryWithSize, getMarkdownFragmentContent(entry));
-                            }
-                        }
-                        catch {
-                            // stat raced a delete — index without the size, like the full walk does.
-                        }
-                        // Real provenance (F4a M-core-2 item 5): populate item_ref/content_hash
-                        // via the SAME derivation the full-index writer uses, so a write-path
-                        // row is never a NULL-item_ref straggler.
-                        const provenance = deriveEntryProvenance({ bundleId: component.id, componentId: component.id, adapterId: component.adapter }, entry.type, entry.name, conceptId);
-                        // A materialized file has one current owner. If a targeted write is
-                        // the ownership handoff (for example an explicitly named bundle
-                        // replacing an earlier path-derived bootstrap identity), remove the
-                        // superseded physical-path row before publishing the canonical ref.
-                        const supersededIds = db
-                            .prepare("SELECT id FROM entries WHERE file_path = ? AND item_ref <> ?")
-                            .all(file, provenance.itemRef);
-                        deleteEntriesByIds(db, supersededIds.map((row) => row.id));
-                        targetEntryIds.add(upsertEntry(db, file, entryWithSize, buildSearchText(entry), provenance, contentHash));
-                        mutated = true;
-                    }
-                })();
-                if (mutated) {
-                    const config = loadConfig();
-                    await generateEmbeddingsForDb(db, config, () => { }, undefined, [...targetEntryIds]);
-                    publishTargetedEmbeddingMeta(db, config);
+                    continue;
                 }
             }
-            finally {
-                closeDatabase(db);
+            const ctx = buildFileContext(stashDir, file);
+            // Hardcoded `akmAdapter` on purpose (owner ruling 2026-07-21): this
+            // write-path fast path only ever runs for assets a first-class akm
+            // mutation command just wrote into a managed akm source, so the akm
+            // adapter is always the right recognizer here — no per-component
+            // dispatch needed.
+            const drained = drainDirDocuments(akmAdapter, component, [ctx]);
+            for (const rejectedPath of drained.rejectedPaths)
+                unindexable.add(rejectedPath);
+            for (const conceptId of drained.rejectedConceptIds)
+                rejectedConceptIds.add(conceptId);
+            const entry = drained.entries[0];
+            // A broken workflow drains to zero entries and is treated as
+            // unindexable; valid peer sources have already compiled to source IR.
+            const conceptId = drained.conceptIdByFile.get(ctx.absPath);
+            if (entry && conceptId)
+                pairs.push({ file, entry, conceptId, contentHash: drained.hashByFile.get(ctx.absPath) });
+            else
+                unindexable.add(file);
+        }
+        const db = openExistingDatabase(dbPath);
+        try {
+            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) {
+                    const rows = db
+                        .prepare(`SELECT id FROM entries
+                WHERE file_path = ?
+                  AND bundle_id = ?
+                  AND adapter_id = ?`)
+                        .all(file, component.id, component.adapter);
+                    for (const row of rows)
+                        unindexableEntryIds.add(row.id);
+                }
+                for (const conceptId of rejectedConceptIds) {
+                    const itemRef = `${component.id}//${conceptId}`;
+                    const rows = db
+                        .prepare(`SELECT id FROM entries
+                WHERE bundle_id = ? AND adapter_id = ?
+                  AND type = 'workflow'
+                  AND (concept_id = ? OR item_ref = ?)`)
+                        .all(component.id, component.adapter, conceptId, itemRef);
+                    for (const row of rows)
+                        unindexableEntryIds.add(row.id);
+                }
+                deleteEntriesByIds(db, [...unindexableEntryIds]);
+                mutated ||= unindexableEntryIds.size > 0;
+                for (const { file, entry, conceptId, contentHash } of pairs) {
+                    const entryWithSize = withFileSize(entry, file);
+                    // Real provenance (F4a M-core-2 item 5): populate item_ref/content_hash
+                    // via the SAME derivation the full-index writer uses, so a write-path
+                    // row is never a NULL-item_ref straggler.
+                    const provenance = deriveEntryProvenance({ bundleId: component.id, componentId: component.id, adapterId: component.adapter }, entry.type, entry.name, conceptId);
+                    // A materialized file has one current owner. If a targeted write is
+                    // the ownership handoff (for example an explicitly named bundle
+                    // replacing an earlier path-derived bootstrap identity), remove the
+                    // superseded physical-path row before publishing the canonical ref.
+                    const supersededIds = db
+                        .prepare("SELECT id FROM entries WHERE file_path = ? AND item_ref <> ?")
+                        .all(file, provenance.itemRef);
+                    deleteEntriesByIds(db, supersededIds.map((row) => row.id));
+                    targetEntryIds.add(upsertEntry(db, file, entryWithSize, provenance, contentHash));
+                    mutated = true;
+                }
+            })();
+            if (mutated) {
+                const config = loadConfig();
+                await generateEmbeddingsForDb(db, config, () => { }, undefined, [...targetEntryIds]);
+                publishTargetedEmbeddingMeta(db, config);
             }
-            return true;
-        })();
+        }
+        finally {
+            closeDatabase(db);
+        }
+        return true;
     }
     catch (error) {
         // A permission fault is the one failure the next full index will NOT heal,