rag-memory-epf-mcp 6.4.2 → 6.4.4

package/dist/src/backfillCoordinator.js

@@ -14,6 +14,7 @@
 // kick() merely triggers a debounced scan. All reconciliation writes are
 // per-row transactions with a CAS re-check so a foreground embed that lands
 // first is never downgraded (6R note 3).
+import { searchableVectorSql, VecSlotError, deleteVector } from './vecSlots.js';
 // A handle closed by the engine's reopen (wal-sidecar-guard), or an I/O error from a sidecar the
 // sync client swapped out: the run was cut, not broken.
 const CONN_LOSS_RERUN_MAX = 3;
@@ -36,6 +37,15 @@ export class BackfillCoordinator {
     shuttingDown = false;
     connLossReruns = 0;
     scanning = false;
+    // vec-slot-reuse: rows whose vec0 slot has validity 0 cannot be rewritten in place (sqlite-vec refuses
+    // to DELETE many of them); the backfill skips them and asks for the verified rebuild instead.
+    repairWanted = false;
+    slotErrors = new Map(); // table -> unresolvable slot map message
+    repairRequestedAt = 0;
+    requestRepair() { if (!this.repairWanted)
+        this.repairRequestedAt = Date.now(); this.repairWanted = true; }
+    takeRepairRequest() { const w = this.repairWanted; this.repairWanted = false; return w; }
+    get repairRequested() { return this.repairWanted; }
     scanPromise = null;
     rerunRequested = false;
     snapshot = null;
@@ -43,6 +53,8 @@ export class BackfillCoordinator {
         this.deps = deps;
     }
     get reconState() { return this.recon; }
+    // vec-slot-reuse D1b: the idle vector rebuild must not overlap a backfill scan or a reconciliation pass.
+    get busy() { return this.scanning || !!this.scanPromise || this.reconActive || this.recon === 'running'; }
     get reconLastError() { return this.reconError; }
     // Shared eligibility barrier (spec §3): vector search AND automatic backfill.
     // 'n/a' (fresh DB — nothing to reconcile) counts as satisfied (6R note 1).
@@ -54,17 +66,19 @@ export class BackfillCoordinator {
     // non-atomic writes can leave metadata-without-vector and vector-without-
     // metadata split states, and neither must be miscounted as reconciled work.
     countNullWithVector(db) {
-        const ent = db.prepare(`SELECT COUNT(*) c FROM entity_embedding_metadata m JOIN entity_embeddings v ON v.rowid = m.rowid
-       WHERE m.provenance_state IS NULL`).get();
-        const chk = db.prepare(`SELECT COUNT(*) c FROM chunk_metadata m JOIN chunks v ON v.rowid = m.rowid
-       WHERE m.provenance_state IS NULL`).get();
+        const ent = db.prepare(`SELECT COUNT(*) c FROM entity_embedding_metadata m
+       WHERE m.provenance_state IS NULL AND ${searchableVectorSql('entity_embeddings', 'm.rowid')}`).get();
+        const chk = db.prepare(`SELECT COUNT(*) c FROM chunk_metadata m
+       WHERE m.provenance_state IS NULL AND ${searchableVectorSql('chunks', 'm.rowid')}`).get();
         return ent.c + chk.c;
     }
     // Sanitation (beta B3·B4) — runs on EVERY reconciliation entry, even when no
     // NULL rows exist, so profile changes and legacy split states are repaired
     // before vector eligibility can open:
     //   1. entity vectors without metadata (orphans)      -> delete vector
-    //   2. entity metadata without vector (split state)   -> delete metadata (row becomes a backfill target)
+    //   2. stamped entity metadata whose vector row is gone -> normalized to missing, NOT deleted: the row keeps
+    //      its rowid and becomes a backfill target (vec-slot-reuse r3 M2; validity-0 vector rows are repaired
+    //      inline by deleteVector/writeVector or by the idle rebuild, never DELETEd here)
     //   3. provenance-stamped rows whose compatibility profile != current
     //      (old engine/model profile)                     -> delete-to-missing
     //   4. chunk metadata stamped but vectorless          -> normalize to missing (NULL provenance)
@@ -75,12 +89,16 @@ export class BackfillCoordinator {
         const profileId = this.deps.currentProfileId();
         const q = (sql, ...args) => db.prepare(sql).get(...args).c;
         return this.countNullWithVector(db)
-            + q(`SELECT COUNT(*) c FROM entity_embeddings WHERE rowid NOT IN (SELECT rowid FROM entity_embedding_metadata)`)
-            + q(`SELECT COUNT(*) c FROM entity_embedding_metadata WHERE rowid NOT IN (SELECT rowid FROM entity_embeddings)`)
+            // vec-slot-reuse r3 M2: searchable orphans only (validity-0 rows belong to the rebuild); vectorless
+            // metadata counts only while still stamped (it is normalized to missing, not deleted, to keep its rowid).
+            + q(`SELECT COUNT(*) c FROM entity_embeddings_rowids m WHERE m.rowid NOT IN (SELECT rowid FROM entity_embedding_metadata) AND ${searchableVectorSql('entity_embeddings', 'm.rowid')}`)
+            // IN-42: searchable chunk vectors without chunk_metadata (same rule as entity orphans)
+            + q(`SELECT COUNT(*) c FROM chunks_rowids m WHERE m.rowid NOT IN (SELECT rowid FROM chunk_metadata) AND ${searchableVectorSql('chunks', 'm.rowid')}`)
+            + q(`SELECT COUNT(*) c FROM entity_embedding_metadata WHERE provenance_state IS NOT NULL AND rowid NOT IN (SELECT rowid FROM entity_embeddings_rowids)`)
             + q(`SELECT COUNT(*) c FROM entity_embedding_metadata WHERE provenance_state IS NOT NULL AND profile_id IS NOT ?`, profileId)
-            + q(`SELECT COUNT(*) c FROM chunk_metadata m JOIN chunks v ON v.rowid = m.rowid WHERE m.provenance_state IS NOT NULL AND m.profile_id IS NOT ?`, profileId)
+            + q(`SELECT COUNT(*) c FROM chunk_metadata m WHERE m.provenance_state IS NOT NULL AND m.profile_id IS NOT ? AND m.rowid IN (SELECT rowid FROM chunks_rowids)`, profileId)
             // stamped chunk metadata whose vector is gone (beta 3R M3)
-            + q(`SELECT COUNT(*) c FROM chunk_metadata WHERE provenance_state IS NOT NULL AND rowid NOT IN (SELECT rowid FROM chunks)`);
+            + q(`SELECT COUNT(*) c FROM chunk_metadata WHERE provenance_state IS NOT NULL AND rowid NOT IN (SELECT rowid FROM chunks_rowids)`);
     }
     // Batched (beta 2R residual): each batch commits its own transaction and
     // yields the event loop — a large DB or a profile switch must not stall the
@@ -103,13 +121,48 @@ export class BackfillCoordinator {
                 await new Promise(r => setImmediate(r));
             }
         };
-        await batchedRun(`DELETE FROM entity_embeddings WHERE rowid IN (
-         SELECT rowid FROM entity_embeddings WHERE rowid NOT IN (SELECT rowid FROM entity_embedding_metadata) LIMIT ${RECON_BATCH})`);
-        await batchedRun(`DELETE FROM entity_embedding_metadata WHERE rowid IN (
-         SELECT rowid FROM entity_embedding_metadata WHERE rowid NOT IN (SELECT rowid FROM entity_embeddings) LIMIT ${RECON_BATCH})`);
+        // 1. searchable entity vectors without metadata -> delete (validity-0 orphans are left to the rebuild:
+        //    vec0 refuses to DELETE most of them, vec-slot-reuse r3 M2)
+        for (;;) {
+            if (this.shuttingDown)
+                throw new Error('shutdown during sanitation');
+            const orphans = db.prepare(`SELECT m.rowid FROM entity_embeddings_rowids m
+         WHERE m.rowid NOT IN (SELECT rowid FROM entity_embedding_metadata) AND ${searchableVectorSql('entity_embeddings', 'm.rowid')} LIMIT ${RECON_BATCH}`).all();
+            if (orphans.length === 0)
+                break;
+            batchTx(() => { for (const r of orphans) {
+                deleteVector(db, 'entity_embeddings', r.rowid);
+                touched++;
+            } });
+            if (orphans.length < RECON_BATCH)
+                break;
+            await new Promise(r => setImmediate(r));
+        }
+        // 1b. searchable chunk vectors without metadata -> delete (IN-42 · same batching and validity rule as 1)
+        for (;;) {
+            if (this.shuttingDown)
+                throw new Error('shutdown during sanitation');
+            const orphans = db.prepare(`SELECT m.rowid FROM chunks_rowids m
+         WHERE m.rowid NOT IN (SELECT rowid FROM chunk_metadata) AND ${searchableVectorSql('chunks', 'm.rowid')} LIMIT ${RECON_BATCH}`).safeIntegers(true).all();
+            if (orphans.length === 0)
+                break;
+            batchTx(() => { for (const r of orphans) {
+                deleteVector(db, 'chunks', r.rowid);
+                touched++;
+            } });
+            if (orphans.length < RECON_BATCH)
+                break;
+            await new Promise(r => setImmediate(r));
+        }
+        // 2. stamped entity metadata whose vector row is gone -> normalize to missing (was: delete). Keeping the
+        //    row keeps its rowid, so the backfill re-inserts at the same rowid (r3 M2 case C: restart after repair).
+        await batchedRun(`UPDATE entity_embedding_metadata SET input_hash = NULL, profile_id = NULL, provenance_state = NULL
+       WHERE rowid IN (
+         SELECT rowid FROM entity_embedding_metadata
+         WHERE provenance_state IS NOT NULL AND rowid NOT IN (SELECT rowid FROM entity_embeddings_rowids) LIMIT ${RECON_BATCH})`);
         await batchedRun(`UPDATE chunk_metadata SET input_hash = NULL, profile_id = NULL, provenance_state = NULL
        WHERE rowid IN (
-         SELECT rowid FROM chunk_metadata WHERE provenance_state IS NOT NULL AND rowid NOT IN (SELECT rowid FROM chunks) LIMIT ${RECON_BATCH})`);
+         SELECT rowid FROM chunk_metadata WHERE provenance_state IS NOT NULL AND rowid NOT IN (SELECT rowid FROM chunks_rowids) LIMIT ${RECON_BATCH})`);
         // Old-profile rows: row deletes in bounded batches with yields.
         for (;;) {
             if (this.shuttingDown)
@@ -120,8 +173,8 @@ export class BackfillCoordinator {
                 break;
             batchTx(() => {
                 for (const r of staleEnt) {
-                    db.exec(`DELETE FROM entity_embeddings WHERE rowid = ${Number(r.rowid)}`);
-                    db.prepare(`DELETE FROM entity_embedding_metadata WHERE rowid = ?`).run(r.rowid);
+                    deleteVector(db, 'entity_embeddings', r.rowid); // validity-0: left to the rebuild
+                    db.prepare(`UPDATE entity_embedding_metadata SET input_hash = NULL, profile_id = NULL, provenance_state = NULL WHERE rowid = ?`).run(r.rowid);
                     touched++;
                 }
             });
@@ -130,31 +183,37 @@ export class BackfillCoordinator {
         for (;;) {
             if (this.shuttingDown)
                 throw new Error('shutdown during sanitation');
-            const staleChunk = db.prepare(`SELECT m.rowid FROM chunk_metadata m JOIN chunks v ON v.rowid = m.rowid
-         WHERE m.provenance_state IS NOT NULL AND m.profile_id IS NOT ? LIMIT ${RECON_BATCH}`).all(profileId);
+            const staleChunk = db.prepare(`SELECT m.rowid FROM chunk_metadata m
+         WHERE m.provenance_state IS NOT NULL AND m.profile_id IS NOT ? AND m.rowid IN (SELECT rowid FROM chunks_rowids) LIMIT ${RECON_BATCH}`).all(profileId);
             if (staleChunk.length === 0)
                 break;
             batchTx(() => {
                 for (const r of staleChunk) {
-                    db.exec(`DELETE FROM chunks WHERE rowid = ${Number(r.rowid)}`);
+                    deleteVector(db, 'chunks', r.rowid); // validity-0: left to the rebuild
                     db.prepare(`UPDATE chunk_metadata SET input_hash = NULL, profile_id = NULL, provenance_state = NULL WHERE rowid = ?`).run(r.rowid);
                     touched++;
                 }
             });
             await new Promise(r => setImmediate(r));
         }
-        if (touched > 0)
-            console.error(`🧾 provenance sanitation: ${touched} split-state/old-profile rows invalidated`);
+        if (touched > 0) {
+            this.snapshot = null; // cached coverage (incl. orphan_vectors) is stale — also on the legacy=0 early return (2_ r1 R2)
+            console.error(`🧾 provenance sanitation: ${touched} split-state/old-profile/orphan rows invalidated`);
+        }
         return touched;
     }
     // Single-flight, idempotent. off mode defers (spec §9); fresh DBs go straight
     // to 'n/a'. Row-level errors are fail-closed (vector deleted -> missing);
     // systemic errors transition to 'failed' and keep eligibility shut.
     runReconciliation() {
-        if (!this.reconPromise)
-            this.reconPromise = this.reconcileOnce();
+        if (!this.reconPromise) {
+            // r3 M4: busy for the whole pass (sanitize included), not only while recon === 'running'.
+            this.reconActive = true;
+            this.reconPromise = this.reconcileOnce().finally(() => { this.reconActive = false; });
+        }
         return this.reconPromise;
     }
+    reconActive = false;
     async reconcileOnce() {
         const db = this.deps.db();
         if (!db) {
@@ -233,8 +292,7 @@ export class BackfillCoordinator {
             // grandfather candidates — metadata-without-vector was already removed by
             // sanitize().
             const rows = db.prepare(`SELECT m.rowid, m.entity_id, m.embedding_text FROM entity_embedding_metadata m
-         JOIN entity_embeddings v ON v.rowid = m.rowid
-         WHERE m.provenance_state IS NULL LIMIT ${RECON_BATCH}`).all();
+         WHERE m.provenance_state IS NULL AND ${searchableVectorSql('entity_embeddings', 'm.rowid')} LIMIT ${RECON_BATCH}`).all();
             if (rows.length === 0)
                 return;
             for (const row of rows) {
@@ -244,7 +302,7 @@ export class BackfillCoordinator {
                     const cur = db.prepare(`SELECT provenance_state FROM entity_embedding_metadata WHERE rowid = ?`).get(row.rowid);
                     if (!cur || cur.provenance_state !== null)
                         return;
-                    db.exec(`DELETE FROM entity_embeddings WHERE rowid = ${row.rowid}`);
+                    deleteVector(db, 'entity_embeddings', row.rowid);
                     db.prepare(`DELETE FROM entity_embedding_metadata WHERE rowid = ?`).run(row.rowid);
                 });
                 const stampTx = db.transaction((hash) => {
@@ -300,8 +358,8 @@ export class BackfillCoordinator {
         for (;;) {
             if (this.shuttingDown)
                 throw new Error('shutdown during reconciliation');
-            const rows = db.prepare(`SELECT m.rowid, m.text FROM chunk_metadata m JOIN chunks v ON v.rowid = m.rowid
-         WHERE m.provenance_state IS NULL LIMIT ${RECON_BATCH}`).all();
+            const rows = db.prepare(`SELECT m.rowid, m.text FROM chunk_metadata m
+         WHERE m.provenance_state IS NULL AND ${searchableVectorSql('chunks', 'm.rowid')} LIMIT ${RECON_BATCH}`).all();
             if (rows.length === 0)
                 return;
             for (const row of rows) {
@@ -313,7 +371,7 @@ export class BackfillCoordinator {
                     // Vector removed; provenance stays NULL. The barrier only protects
                     // VECTOR-BEARING NULL rows — vectorless rows are always legitimate
                     // backfill targets (spec §6c "벡터 없음").
-                    db.exec(`DELETE FROM chunks WHERE rowid = ${row.rowid}`);
+                    deleteVector(db, 'chunks', row.rowid);
                     db.prepare(`UPDATE chunk_metadata SET input_hash = NULL, profile_id = NULL WHERE rowid = ?`)
                         .run(row.rowid);
                 });
@@ -452,13 +510,32 @@ export class BackfillCoordinator {
                 return consecutive >= 3 ? 'abort' : 'fail';
             };
             // Phase 1: chunks.
-            const chunkRows = db.prepare(`SELECT m.rowid, m.text, m.input_hash, m.profile_id, m.provenance_state,
-                EXISTS(SELECT 1 FROM chunks v WHERE v.rowid = m.rowid) AS has_vec
-         FROM chunk_metadata m WHERE m.text IS NOT NULL`).all();
+            let sawInvalid = false;
+            const errorsBefore = JSON.stringify([...this.slotErrors]);
+            const slotErrorsChanged = () => JSON.stringify([...this.slotErrors]) !== errorsBefore;
+            let chunkRows = [];
+            try {
+                chunkRows = db.prepare(`SELECT m.rowid, m.text, m.input_hash, m.profile_id, m.provenance_state,
+                  ${searchableVectorSql('chunks', 'm.rowid')} AS has_vec,
+                  EXISTS(SELECT 1 FROM chunks_rowids r WHERE r.rowid = m.rowid) AS has_row
+           FROM chunk_metadata m WHERE m.text IS NOT NULL`).all();
+                this.slotErrors.delete('chunks');
+            }
+            catch (e) {
+                if (!(e instanceof VecSlotError) && !String(e.message).includes('vec0 slot'))
+                    throw e;
+                this.slotErrors.set('chunks', e.message);
+                console.error(`⚠️ backfill: chunk slot map unresolvable, chunk phase held: ${e.message}`);
+            }
             let processed = 0;
             for (const row of chunkRows) {
                 if (this.shuttingDown || !this.eligible)
                     return;
+                if (row.has_row && !row.has_vec) {
+                    this.requestRepair();
+                    sawInvalid = true;
+                    continue;
+                } // validity 0 -> rebuild
                 const currentHash = this.deps.chunkInputHash(row.text);
                 const isTarget = !row.has_vec
                     || (row.provenance_state !== null && (row.profile_id !== profileId || row.input_hash !== currentHash));
@@ -475,13 +552,28 @@ export class BackfillCoordinator {
                 if (++processed % 8 === 0)
                     await new Promise(r => setImmediate(r));
             }
-            // Phase 2: entities.
-            const entityRows = db.prepare(`SELECT e.id, m.input_hash, m.profile_id, m.provenance_state, m.rowid AS meta_rowid,
-                CASE WHEN m.rowid IS NOT NULL AND EXISTS(SELECT 1 FROM entity_embeddings v WHERE v.rowid = m.rowid) THEN 1 ELSE 0 END AS has_vec
-         FROM entities e LEFT JOIN entity_embedding_metadata m ON m.entity_id = e.id`).all();
+            let entityRows = [];
+            try {
+                entityRows = db.prepare(`SELECT e.id, m.input_hash, m.profile_id, m.provenance_state, m.rowid AS meta_rowid,
+                  CASE WHEN m.rowid IS NOT NULL AND ${searchableVectorSql('entity_embeddings', 'm.rowid')} THEN 1 ELSE 0 END AS has_vec,
+                  CASE WHEN m.rowid IS NOT NULL AND EXISTS(SELECT 1 FROM entity_embeddings_rowids r WHERE r.rowid = m.rowid) THEN 1 ELSE 0 END AS has_row
+           FROM entities e LEFT JOIN entity_embedding_metadata m ON m.entity_id = e.id`).all();
+                this.slotErrors.delete('entity_embeddings');
+            }
+            catch (e) {
+                if (!(e instanceof VecSlotError) && !String(e.message).includes('vec0 slot'))
+                    throw e;
+                this.slotErrors.set('entity_embeddings', e.message);
+                console.error(`⚠️ backfill: entity slot map unresolvable, entity phase held: ${e.message}`);
+            }
             for (const row of entityRows) {
                 if (this.shuttingDown || !this.eligible)
                     return;
+                if (row.has_row && !row.has_vec) {
+                    this.requestRepair();
+                    sawInvalid = true;
+                    continue;
+                } // validity 0 -> rebuild
                 const currentHash = this.deps.buildEntityInputHash(row.id);
                 if (currentHash === null)
                     continue; // malformed entity: leave to explicit repair
@@ -501,6 +593,8 @@ export class BackfillCoordinator {
                 if (++processed % 8 === 0)
                     await new Promise(r => setImmediate(r));
             }
+            if (sawInvalid || slotErrorsChanged())
+                this.snapshot = null; // r3 M3: coverage reflects what the scan saw
             if (processed > 0) {
                 this.snapshot = null;
                 console.error(`✅ backfill pass complete (${processed} rows examined for re-embedding)`);
@@ -519,12 +613,37 @@ export class BackfillCoordinator {
         if (this.snapshot)
             return this.snapshot;
         const chunkTotal = db.prepare(`SELECT COUNT(*) c FROM chunk_metadata`).get().c;
-        const chunkBy = db.prepare(`SELECT m.provenance_state s, COUNT(*) c FROM chunk_metadata m JOIN chunks v ON v.rowid = m.rowid
-       GROUP BY m.provenance_state`).all();
+        // Searchable only (D1c). A slot map error is reported per table instead of a count.
+        const byState = (sql) => {
+            try {
+                return { rows: db.prepare(sql).all() };
+            }
+            catch (e) {
+                if (!(e instanceof VecSlotError) && !String(e.message).includes('vec0 slot'))
+                    throw e;
+                return { rows: [], error: e.message };
+            }
+        };
+        const chunkQ = byState(`SELECT m.provenance_state s, COUNT(*) c FROM chunk_metadata m
+       WHERE ${searchableVectorSql('chunks', 'm.rowid')} GROUP BY m.provenance_state`);
+        const chunkBy = chunkQ.rows;
         const entTotal = db.prepare(`SELECT COUNT(*) c FROM entities`).get().c;
         // Vector-join (beta B3): metadata without an actual vector is missing, not embedded.
-        const entBy = db.prepare(`SELECT m.provenance_state s, COUNT(*) c FROM entity_embedding_metadata m
-       JOIN entity_embeddings v ON v.rowid = m.rowid GROUP BY m.provenance_state`).all();
+        const entQ = byState(`SELECT m.provenance_state s, COUNT(*) c FROM entity_embedding_metadata m
+       WHERE ${searchableVectorSql('entity_embeddings', 'm.rowid')} GROUP BY m.provenance_state`);
+        const entBy = entQ.rows;
+        const orphanQ = (t, meta) => {
+            try {
+                return db.prepare(`SELECT COUNT(*) c FROM ${t}_rowids m WHERE m.rowid NOT IN (SELECT rowid FROM ${meta}) AND ${searchableVectorSql(t, 'm.rowid')}`).get().c;
+            }
+            catch (e) {
+                if (!(e instanceof VecSlotError) && !String(e.message).includes('vec0 slot'))
+                    throw e;
+                return undefined;
+            }
+        };
+        const chunkOrphans = orphanQ('chunks', 'chunk_metadata');
+        const entOrphans = orphanQ('entity_embeddings', 'entity_embedding_metadata');
         const pick = (rows, s) => rows.find(r => r.s === s)?.c ?? 0;
         // Searchable = verified + legacy_assumed. NULL rows (pre-reconciliation or
         // deferred in off mode) are NOT counted as embedded (6R note 4).
@@ -533,8 +652,10 @@ export class BackfillCoordinator {
         const entVerified = pick(entBy, 'verified');
         const entLegacy = pick(entBy, 'legacy_assumed');
         this.snapshot = {
-            chunk: { total: chunkTotal, embedded: chunkVerified + chunkLegacy, verified: chunkVerified, legacy_assumed: chunkLegacy },
-            entity: { total: entTotal, embedded: entVerified + entLegacy, verified: entVerified, legacy_assumed: entLegacy },
+            chunk: { total: chunkTotal, embedded: chunkVerified + chunkLegacy, verified: chunkVerified, legacy_assumed: chunkLegacy, orphan_vectors: chunkOrphans,
+                ...(chunkQ.error ? { error: chunkQ.error } : {}) },
+            entity: { total: entTotal, embedded: entVerified + entLegacy, verified: entVerified, legacy_assumed: entLegacy, orphan_vectors: entOrphans,
+                ...(entQ.error ? { error: entQ.error } : {}) },
         };
         return this.snapshot;
     }

package/dist/src/observations/projection.js

@@ -1,3 +1,4 @@
+import { deleteVector } from '../vecSlots.js';
 // active 행을 projection_order 순으로 모아 entities.observations 를 재작성한다.
 // 단계 1 에서는 이 배열이 여전히 FTS/벡터의 입력이다 — 그래서 projection 갱신만으로
 // 기존 entity FTS 트리거와 벡터 무효화가 따라온다(spec §4.5).
@@ -23,7 +24,7 @@ export function deleteStaleKgChunks(db, entityId) {
     const chunks = db.prepare(`SELECT rowid FROM chunk_metadata WHERE chunk_type = 'entity' AND entity_id = ?`).all(entityId);
     let n = 0;
     for (const c of chunks) {
-        db.exec(`DELETE FROM chunks WHERE rowid = ${Number(c.rowid)}`);
+        deleteVector(db, 'chunks', Number(c.rowid));
         db.prepare(`DELETE FROM chunk_metadata WHERE rowid = ?`).run(c.rowid);
         n++;
     }
@@ -39,7 +40,7 @@ export function deleteKgRelationshipChunks(db, relationshipIds) {
     for (const rid of relationshipIds) {
         const chunks = db.prepare(`SELECT rowid FROM chunk_metadata WHERE chunk_type = 'relationship' AND relationship_id = ?`).all(rid);
         for (const c of chunks) {
-            db.exec(`DELETE FROM chunks WHERE rowid = ${Number(c.rowid)}`);
+            deleteVector(db, 'chunks', Number(c.rowid));
             db.prepare(`DELETE FROM chunk_metadata WHERE rowid = ?`).run(c.rowid);
             n++;
         }
@@ -60,7 +61,7 @@ export function deleteKgChunkRows(db, rowids) {
         const row = db.prepare(`SELECT chunk_type FROM chunk_metadata WHERE rowid = ?`).get(rowid);
         if (!row || (row.chunk_type !== 'entity' && row.chunk_type !== 'relationship'))
             continue;
-        db.exec(`DELETE FROM chunks WHERE rowid = ${rowid}`);
+        deleteVector(db, 'chunks', rowid);
         db.prepare(`DELETE FROM chunk_entities WHERE chunk_rowid = ?`).run(rowid);
         n += db.prepare(`DELETE FROM chunk_metadata WHERE rowid = ?`).run(rowid).changes;
     }

package/dist/src/vecSimilarity.d.ts

@@ -0,0 +1,17 @@
+/**
+ * vec0 tables (chunks · entity_embeddings) are created without `distance_metric`, so sqlite-vec returns the
+ * default L2 distance. Embeddings are unit-normalized (`normalize: true`), so for unit vectors
+ * ‖a − b‖² = 2 − 2·cos  →  cosine similarity = 1 − d²/2.
+ * The earlier conversion 1 − d/2 treated the L2 value as a cosine distance: right − old = (d − d²)/2, so it
+ * under-reported for d < 1 (cos > 0.5: cos 0.8 showed ≈0.684) and over-reported for d > 1 (orthogonal showed
+ * ≈0.293 instead of 0 · cos 0.3 showed ≈0.408 and passed the 0.4 graph-seed threshold). Clamped to [0, 1].
+ * Guarded by test/vec-similarity.test.mjs (also asserts the metric is still L2).
+ */
+export declare function l2ToCosineSimilarity(distance: number): number;
+/**
+ * The 6.3.2 score, kept ONLY for the legacy paths that are pinned byte-for-byte (engine commit 4ac3155 · test
+ * graph-context-explain): hybridSearch with useGraph:true or summaries on, and the graph-seed `> 0.4` threshold of
+ * explainGraphContext. It is the historical 1 − d/2 conversion of an L2 distance and is NOT a cosine similarity
+ * (its 0.4 threshold equals a real cosine of about 0.28). Default search and searchNodes use l2ToCosineSimilarity.
+ */
+export declare function legacyL2AsCosineScore(distance: number): number;

package/dist/src/vecSimilarity.js

@@ -0,0 +1,23 @@
+/**
+ * vec0 tables (chunks · entity_embeddings) are created without `distance_metric`, so sqlite-vec returns the
+ * default L2 distance. Embeddings are unit-normalized (`normalize: true`), so for unit vectors
+ * ‖a − b‖² = 2 − 2·cos  →  cosine similarity = 1 − d²/2.
+ * The earlier conversion 1 − d/2 treated the L2 value as a cosine distance: right − old = (d − d²)/2, so it
+ * under-reported for d < 1 (cos > 0.5: cos 0.8 showed ≈0.684) and over-reported for d > 1 (orthogonal showed
+ * ≈0.293 instead of 0 · cos 0.3 showed ≈0.408 and passed the 0.4 graph-seed threshold). Clamped to [0, 1].
+ * Guarded by test/vec-similarity.test.mjs (also asserts the metric is still L2).
+ */
+export function l2ToCosineSimilarity(distance) {
+    if (!Number.isFinite(distance))
+        return 0;
+    return Math.min(1, Math.max(0, 1 - (distance * distance) / 2));
+}
+/**
+ * The 6.3.2 score, kept ONLY for the legacy paths that are pinned byte-for-byte (engine commit 4ac3155 · test
+ * graph-context-explain): hybridSearch with useGraph:true or summaries on, and the graph-seed `> 0.4` threshold of
+ * explainGraphContext. It is the historical 1 − d/2 conversion of an L2 distance and is NOT a cosine similarity
+ * (its 0.4 threshold equals a real cosine of about 0.28). Default search and searchNodes use l2ToCosineSimilarity.
+ */
+export function legacyL2AsCosineScore(distance) {
+    return Math.max(0, 1 - distance / 2);
+}

package/dist/src/vecSlots.d.ts

@@ -0,0 +1,51 @@
+import type Database from 'better-sqlite3';
+export type VecTable = 'chunks' | 'entity_embeddings';
+export type SlotState = 'valid' | 'invalid' | 'shared' | 'absent';
+export declare class VecSlotError extends Error {
+    constructor(message: string);
+}
+export declare function bitIsSet(validity: unknown, offset: unknown, size: unknown): boolean;
+export declare function slotState(db: Database.Database, table: VecTable, rowid: number | bigint): SlotState;
+export declare class InvalidSlotError extends VecSlotError {
+    constructor(table: string, rowid: number | bigint);
+}
+export declare function writeVector(db: Database.Database, table: VecTable, rowid: number | bigint, embedding: Buffer): SlotState;
+export declare function deleteVector(db: Database.Database, table: VecTable, rowid: number | bigint): SlotState;
+export declare function registerVecSlotFunctions(db: Database.Database): void;
+export declare function searchableVectorSql(table: VecTable, rowidExpr: string): string;
+export interface SlotSummary {
+    table: VecTable;
+    chunks: number;
+    chunkSize: number;
+    slots: number;
+    valid: number;
+    invalid: number;
+    aliased: number;
+    empty: number;
+    reclaimable: number;
+    reclaimableBytes: number;
+    rewriteBytes: number;
+}
+export declare function slotSummary(db: Database.Database, table: VecTable, dims?: number): SlotSummary;
+export interface RebuildPolicy {
+    minChunks: number;
+    maxLive: number;
+}
+export declare const DEFAULT_REBUILD_POLICY: RebuildPolicy;
+export declare function rebuildReason(s: SlotSummary, policy?: RebuildPolicy): string | null;
+export type RebuildFault = 'after-drop' | 'after-create' | 'after-partial' | 'corrupt-one';
+export interface RebuildResult {
+    table: VecTable;
+    status: 'rebuilt' | 'not-needed' | 'busy' | 'position-error' | 'over-cap' | 'failed';
+    reason?: string;
+    before?: SlotSummary;
+    after?: SlotSummary;
+    ms: number;
+    error?: string;
+}
+export declare function rebuildVecTable(db: Database.Database, table: VecTable, opts?: {
+    policy?: RebuildPolicy;
+    force?: boolean;
+    fault?: RebuildFault;
+    dims?: number;
+}): RebuildResult;