docsgov 0.1.0

package/dist/dedup/indexdb/indexdb.test.js

@@ -0,0 +1,739 @@
+/**
+ * Behavior-encoding tests for the dedup index DB, ported from
+ * internal/dedup/indexdb/indexdb_test.go.
+ *
+ * Each test states WHY the behavior matters: the DB is the persisted cache
+ * format, so schema columns/indexes, the open reconciliation outcomes (fresh,
+ * reopen, migrate, recreate, embedder-purge), and the embedding byte layout are
+ * all contracts that a future cross-check against the Go binary depends on.
+ *
+ * Go used t.TempDir + t.Cleanup + a raw sql.Open helper; vitest has neither, so
+ * we use mkdtemp under os.tmpdir, clean each dir in afterEach, and open raw DBs
+ * with node:sqlite directly (same engine the package uses).
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { afterEach, describe, expect, it } from "vitest";
+import { createTableSQL, decodeVec, ErrIndexMissing, open, OpenStatus, registerTestMigration, SchemaVersion, } from "./index.js";
+// testModel and testDim are the expected embedder identity values used in all
+// indexdb tests. They match the constants in the embedder package.
+const testModel = "sentence-transformers/paraphrase-multilingual-mpnet-base-v2";
+const testDim = 768;
+const tmpDirs = [];
+afterEach(() => {
+    for (const d of tmpDirs.splice(0)) {
+        rmSync(d, { recursive: true, force: true });
+    }
+});
+/** newTempPath returns a fresh, non-existent DB path inside a tracked temp dir. */
+function newTempPath() {
+    const dir = mkdtempSync(join(tmpdir(), "indexdb-"));
+    tmpDirs.push(dir);
+    return join(dir, "index.db");
+}
+/** openTempDB opens a fresh indexdb at a temp path and returns it + the path + status. */
+function openTempDB() {
+    const dbPath = newTempPath();
+    const { store, status } = open(dbPath, testModel, testDim);
+    return { store, dbPath, status };
+}
+/** rawDB opens the DB at path with node:sqlite directly (no reconciliation). */
+function rawDB(dbPath) {
+    return new DatabaseSync(dbPath);
+}
+// --- raw-DB helpers (mirror the Go test helpers) ---
+function readMetaVersion(dbPath) {
+    const db = rawDB(dbPath);
+    try {
+        const row = db.prepare(`SELECT value FROM meta WHERE key='schema_version'`).get();
+        if (row === undefined)
+            throw new Error("schema_version row missing");
+        return row.value;
+    }
+    finally {
+        db.close();
+    }
+}
+function countSectionsRows(dbPath) {
+    const db = rawDB(dbPath);
+    try {
+        const row = db.prepare(`SELECT COUNT(*) AS n FROM sections`).get();
+        return row.n;
+    }
+    finally {
+        db.close();
+    }
+}
+function tableExists(dbPath, name) {
+    const db = rawDB(dbPath);
+    try {
+        const row = db
+            .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`)
+            .get(name);
+        return row?.name === name;
+    }
+    finally {
+        db.close();
+    }
+}
+function readSectionEmbedding(dbPath, sectionID) {
+    const db = rawDB(dbPath);
+    try {
+        const row = db.prepare(`SELECT embedding FROM sections WHERE id=?`).get(sectionID);
+        if (row === undefined)
+            throw new Error(`section ${sectionID} not found`);
+        return row.embedding;
+    }
+    finally {
+        db.close();
+    }
+}
+function setMetaValue(dbPath, key, value) {
+    const db = rawDB(dbPath);
+    try {
+        db.prepare(`UPDATE meta SET value=? WHERE key=?`).run(value, key);
+    }
+    finally {
+        db.close();
+    }
+}
+/** insertSectionRowDB inserts a dummy row into the sections table (matches Go). */
+function insertSectionRowDB(db) {
+    db.prepare(`
+    INSERT OR REPLACE INTO sections
+    (id, file_path, heading, heading_level, anchor, start_line, end_line,
+     content_hash, raw_content, embed_text, prose_word_count, has_table,
+     has_code, inbound_count, embedding, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run("testid0000000001", "docs/test.md", "Test", 2, "test", 1, 10, "hash", "## Test\n\nContent.", "content", 5, 0, 0, 0, new Uint8Array([0x01]), "2024-01-01T00:00:00Z");
+}
+function insertSectionRow(dbPath) {
+    const db = rawDB(dbPath);
+    try {
+        insertSectionRowDB(db);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * setupMigrationDB creates a DB with the full dedup schema but an arbitrary
+ * schema_version, plus one section row, so the migrate/recreate paths can be
+ * exercised against a seeded state.
+ */
+function setupMigrationDB(dbPath, version) {
+    const db = rawDB(dbPath);
+    try {
+        db.exec(createTableSQL);
+        const meta = db.prepare(`INSERT OR REPLACE INTO meta(key, value) VALUES(?, ?)`);
+        meta.run("schema_version", version);
+        meta.run("embedder_model", testModel);
+        meta.run("embedder_dim", "768");
+        insertSectionRowDB(db);
+    }
+    finally {
+        db.close();
+    }
+}
+// v1CreateTableSQL is the original v1 schema: sections + meta only, NO blocks
+// table. Used to seed a true v1 DB for the migration test.
+const v1CreateTableSQL = `
+CREATE TABLE IF NOT EXISTS sections (
+  id                  TEXT PRIMARY KEY,
+  file_path           TEXT NOT NULL,
+  heading             TEXT NOT NULL,
+  heading_level       INTEGER NOT NULL,
+  anchor              TEXT NOT NULL,
+  start_line          INTEGER NOT NULL,
+  end_line            INTEGER NOT NULL,
+  content_hash        TEXT NOT NULL,
+  raw_content         TEXT NOT NULL,
+  embed_text          TEXT NOT NULL,
+  prose_word_count    INTEGER NOT NULL,
+  has_table           INTEGER NOT NULL,
+  has_code            INTEGER NOT NULL,
+  inbound_count       INTEGER NOT NULL DEFAULT 0,
+  embedding           BLOB    NOT NULL,
+  updated_at          TEXT    NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_sections_file ON sections(file_path);
+CREATE INDEX IF NOT EXISTS idx_sections_hash ON sections(content_hash);
+
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+`;
+/**
+ * setupV1DB creates a v1-schema DB (no blocks table) with schema_version="1",
+ * matching embedder meta, and one section row carrying the given id + embedding.
+ */
+function setupV1DB(dbPath, sectionID, embedding) {
+    const db = rawDB(dbPath);
+    try {
+        db.exec(v1CreateTableSQL);
+        const meta = db.prepare(`INSERT OR REPLACE INTO meta(key, value) VALUES(?, ?)`);
+        meta.run("schema_version", "1");
+        meta.run("embedder_model", testModel);
+        meta.run("embedder_dim", "768");
+        db.prepare(`
+      INSERT OR REPLACE INTO sections
+      (id, file_path, heading, heading_level, anchor, start_line, end_line,
+       content_hash, raw_content, embed_text, prose_word_count, has_table,
+       has_code, inbound_count, embedding, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(sectionID, "docs/test.md", "Test", 2, "test", 1, 10, "hash", "## Test\n\nContent.", "content", 5, 0, 0, 0, embedding, "2024-01-01T00:00:00Z");
+    }
+    finally {
+        db.close();
+    }
+}
+/** encodeVecTest encodes a number[] to a little-endian float32 BLOB (mirrors indexer). */
+function encodeVecTest(v) {
+    const buf = new Uint8Array(v.length * 4);
+    const view = new DataView(buf.buffer);
+    for (let i = 0; i < v.length; i++) {
+        view.setFloat32(i * 4, v[i], true);
+    }
+    return buf;
+}
+/** insertBlockRow inserts one row into the blocks table. */
+function insertBlockRow(db, sectionID, blockIndex, filePath, heading, kind, startLine, endLine, contentHash, embedding) {
+    db.prepare(`
+    INSERT OR REPLACE INTO blocks
+    (section_id, block_index, file_path, heading, kind,
+     start_line, end_line, content_hash, embedding)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(sectionID, blockIndex, filePath, heading, kind, startLine, endLine, contentHash, embedding);
+}
+describe("open — reconciliation outcomes", () => {
+    // Fresh open is the install case: a missing file must produce a usable DB,
+    // distinctly flagged so callers know nothing was loaded.
+    it("returns StatusFresh for a brand-new DB", () => {
+        const { store, status } = openTempDB();
+        try {
+            expect(status).toBe(OpenStatus.StatusFresh);
+        }
+        finally {
+            store.close();
+        }
+    });
+    // Reopening an unchanged DB must be the silent common path — any other status
+    // would make every run look like it invalidated the cache.
+    it("returns StatusOpened when reopening an unchanged matching DB", () => {
+        const { store, dbPath } = openTempDB();
+        store.close();
+        const { store: store2, status } = open(dbPath, testModel, testDim);
+        try {
+            expect(status).toBe(OpenStatus.StatusOpened);
+        }
+        finally {
+            store2.close();
+        }
+    });
+    // StatusOpened is the zero value by contract: a freshly-declared status reads
+    // as "opened, nothing to report." Downstream code relies on 0 == opened.
+    it("StatusOpened is the zero value (0)", () => {
+        expect(OpenStatus.StatusOpened).toBe(0);
+    });
+    // Close must succeed cleanly; a throwing Close would leak the connection and
+    // wedge the next open under WAL.
+    it("close does not throw", () => {
+        const { store } = openTempDB();
+        expect(() => store.close()).not.toThrow();
+    });
+});
+describe("open — migration path", () => {
+    // A registered migration must upgrade in place and PRESERVE rows: that is the
+    // whole point of a migration vs. a recreate (it keeps expensive embeddings).
+    it("applies a registered migration, bumps schema_version, and preserves rows", () => {
+        const dbPath = newTempPath();
+        setupMigrationDB(dbPath, "0");
+        let opened = false;
+        const cleanup = registerTestMigration("0", () => {
+            // No-op migration.
+        });
+        try {
+            const { store, status } = open(dbPath, testModel, testDim);
+            opened = true;
+            try {
+                expect(status).toBe(OpenStatus.StatusSchemaMigrated);
+                // Stored schema_version bumped to the binary's SchemaVersion.
+                expect(readMetaVersion(dbPath)).toBe(SchemaVersion);
+                // Existing row survived (not wiped by the migration).
+                expect(countSectionsRows(dbPath)).toBe(1);
+            }
+            finally {
+                store.close();
+            }
+        }
+        finally {
+            cleanup();
+        }
+        expect(opened).toBe(true);
+    });
+});
+describe("open — recreate path", () => {
+    // An unknown future schema_version with NO migration must wipe and rebuild,
+    // not crash: a newer binary's DB opened by an older one should self-heal.
+    it("recreates when schema_version has no migration, clearing old rows", () => {
+        const dbPath = newTempPath();
+        setupMigrationDB(dbPath, "99");
+        const { store, status } = open(dbPath, testModel, testDim);
+        try {
+            expect(status).toBe(OpenStatus.StatusSchemaRecreated);
+            // Old rows gone (DB recreated from scratch).
+            expect(countSectionsRows(dbPath)).toBe(0);
+        }
+        finally {
+            store.close();
+        }
+    });
+});
+describe("open — embedder purge path", () => {
+    // A changed embedder model/dim makes every stored vector meaningless. Open
+    // MUST purge sections (forcing a re-embed) rather than mix incompatible
+    // vectors — silently keeping them would corrupt similarity results.
+    it("purges sections when embedder_model mismatches", () => {
+        const dbPath = newTempPath();
+        // Create a proper DB, seed a row, then corrupt the stored model.
+        const { store } = open(dbPath, testModel, testDim);
+        store.close();
+        insertSectionRow(dbPath);
+        setMetaValue(dbPath, "embedder_model", "wrong-model");
+        const { store: store2, status } = open(dbPath, testModel, testDim);
+        try {
+            expect(status).toBe(OpenStatus.StatusEmbedderPurged);
+            expect(countSectionsRows(dbPath)).toBe(0);
+        }
+        finally {
+            store2.close();
+        }
+    });
+});
+describe("sentinels and constants", () => {
+    // The sentinel must exist and be instanceof-matchable for the v2 read-only hook.
+    it("ErrIndexMissing is a non-null Error subclass", () => {
+        const err = new ErrIndexMissing();
+        expect(err).toBeInstanceOf(Error);
+        expect(err.message).toContain("does not exist");
+    });
+    // SchemaVersion is part of the persisted format; pinning it to "2" guards
+    // against an accidental bump that would silently invalidate every DB on disk.
+    it("SchemaVersion is '2'", () => {
+        expect(SchemaVersion).toBe("2");
+    });
+});
+describe("schema — fresh DB shape", () => {
+    // The blocks table's exact columns + indexes are the on-disk contract shared
+    // with the Go binary; a missing/renamed column would break cross-reads.
+    it("fresh open creates the blocks table with expected columns and indexes", () => {
+        const { store, dbPath } = openTempDB();
+        store.close();
+        const db = rawDB(dbPath);
+        try {
+            // blocks table present in sqlite_master.
+            const tbl = db
+                .prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='blocks'`)
+                .get();
+            expect(tbl?.name).toBe("blocks");
+            // Expected columns present.
+            const wantCols = [
+                "section_id",
+                "block_index",
+                "file_path",
+                "heading",
+                "kind",
+                "start_line",
+                "end_line",
+                "content_hash",
+                "embedding",
+            ];
+            const cols = db.prepare(`PRAGMA table_info(blocks)`).all();
+            const gotCols = new Set(cols.map((c) => c.name));
+            for (const c of wantCols) {
+                expect(gotCols.has(c)).toBe(true);
+            }
+            // Both indexes present.
+            for (const idx of ["idx_blocks_hash", "idx_blocks_file"]) {
+                const row = db
+                    .prepare(`SELECT name FROM sqlite_master WHERE type='index' AND name=?`)
+                    .get(idx);
+                expect(row?.name).toBe(idx);
+            }
+            // sections indexes present too (the other half of the schema contract).
+            for (const idx of ["idx_sections_file", "idx_sections_hash"]) {
+                const row = db
+                    .prepare(`SELECT name FROM sqlite_master WHERE type='index' AND name=?`)
+                    .get(idx);
+                expect(row?.name).toBe(idx);
+            }
+        }
+        finally {
+            db.close();
+        }
+    });
+});
+describe("migration — v1 to v2 (real additive migration)", () => {
+    // The shipped v1->v2 migration must add the blocks table WITHOUT touching
+    // sections or their embeddings — embeddings are expensive to recompute, so
+    // byte-for-byte survival is the property that makes the migration worthwhile.
+    it("v1->v2 adds blocks, bumps version, and preserves the section embedding byte-for-byte", () => {
+        const dbPath = newTempPath();
+        // Distinct multi-byte embedding so byte-for-byte survival is meaningful.
+        const wantEmbedding = new Uint8Array([0xde, 0xad, 0xbe, 0xef, 0x00, 0x11]);
+        const wantID = "v1section00000001";
+        setupV1DB(dbPath, wantID, wantEmbedding);
+        const { store, status } = open(dbPath, testModel, testDim);
+        try {
+            expect(status).toBe(OpenStatus.StatusSchemaMigrated);
+            expect(tableExists(dbPath, "blocks")).toBe(true);
+            expect(readMetaVersion(dbPath)).toBe("2");
+            const got = readSectionEmbedding(dbPath, wantID);
+            expect(got).not.toBeNull();
+            expect(Array.from(got)).toEqual(Array.from(wantEmbedding));
+        }
+        finally {
+            store.close();
+        }
+    });
+});
+describe("loadAllBlocksWithEmbeddings", () => {
+    // A prose block carries a vector; a table block carries NULL. The map must key
+    // by content_hash with the prose vector present and the table hash ABSENT
+    // (NULL → absent, not a zero-length entry) — clustering treats "no vector" and
+    // "zero vector" differently, so a stray entry would mis-cluster tables.
+    it("returns both records, maps the prose vector, and omits the NULL table block", () => {
+        const { store, dbPath } = openTempDB();
+        const db = rawDB(dbPath);
+        try {
+            const proseVec = [0.1, 0.2, 0.3];
+            const proseBlob = encodeVecTest(proseVec);
+            const proseHash = "aaabbbcccdddeeefffaaaaabbbcccdddeeefffaaaaabbbcccdddeeefffaaabbb11";
+            insertBlockRow(db, "sec0001", 0, "docs/a.md", "Intro", "prose", 2, 5, proseHash, proseBlob);
+            const tableHash = "fff000111222333444555666777888999aaabbbcccdddeeefffaaa0001112223";
+            insertBlockRow(db, "sec0001", 1, "docs/a.md", "Intro", "table", 6, 10, tableHash, null);
+            const { blocks, embeddings } = store.loadAllBlocksWithEmbeddings();
+            expect(blocks.length).toBe(2);
+            let proseBlock;
+            for (const b of blocks) {
+                if (b.ContentHash === proseHash)
+                    proseBlock = b;
+            }
+            expect(proseBlock).toBeDefined();
+            expect(proseBlock.SectionID).toBe("sec0001");
+            expect(proseBlock.Index).toBe(0);
+            expect(proseBlock.FilePath).toBe("docs/a.md");
+            expect(proseBlock.Heading).toBe("Intro");
+            expect(proseBlock.Kind).toBe("prose");
+            expect(proseBlock.StartLine).toBe(2);
+            expect(proseBlock.EndLine).toBe(5);
+            // Text is NOT persisted — must be empty on load.
+            expect(proseBlock.Text).toBe("");
+            const gotVec = embeddings.get(proseHash);
+            expect(gotVec).toBeDefined();
+            expect(gotVec.length).toBe(proseVec.length);
+            for (let i = 0; i < proseVec.length; i++) {
+                expect(gotVec[i]).toBeCloseTo(proseVec[i], 5);
+            }
+            // Table hash must be absent (NULL embedding).
+            expect(embeddings.has(tableHash)).toBe(false);
+        }
+        finally {
+            db.close();
+            store.close();
+        }
+    });
+});
+describe("queryBlocks", () => {
+    // The indexer's diff/prune reads exactly section_id, block_index, content_hash,
+    // embedding. The NULL embedding for a table block must come back as null (not
+    // an empty buffer) so the indexer can tell "table, no vector" apart.
+    it("returns the four diff columns with NULL embedding preserved as null", () => {
+        const { store, dbPath } = openTempDB();
+        const db = rawDB(dbPath);
+        try {
+            const blob = encodeVecTest([0.5, 0.6]);
+            const hash1 = "aaabbbcccdddeeefffaaaaabbbcccdddeeefffaaaaabbbcccdddeeefffaaa0001";
+            const hash2 = "bbbcccdddeeefffaaaa111222333444555666777888999aaabbbcccdddeee0002";
+            insertBlockRow(db, "sec0001", 0, "docs/a.md", "H", "prose", 1, 3, hash1, blob);
+            insertBlockRow(db, "sec0001", 1, "docs/a.md", "H", "table", 4, 7, hash2, null);
+            const got = store.queryBlocks();
+            expect(got.length).toBe(2);
+            const prose = got.find((r) => r.section_id === "sec0001" && r.block_index === 0);
+            expect(prose).toBeDefined();
+            expect(prose.content_hash).toBe(hash1);
+            expect(prose.embedding).not.toBeNull();
+            expect(Array.from(prose.embedding)).toEqual(Array.from(blob));
+            const table = got.find((r) => r.section_id === "sec0001" && r.block_index === 1);
+            expect(table).toBeDefined();
+            expect(table.content_hash).toBe(hash2);
+            expect(table.embedding).toBeNull();
+        }
+        finally {
+            db.close();
+            store.close();
+        }
+    });
+});
+describe("loadAllSectionsWithEmbeddings", () => {
+    // Round-trips a section through store: the boolean INTEGER columns and the
+    // embedding BLOB must decode back to the right shape, since the indexer's
+    // diff-and-skip relies on these exact loaded values.
+    it("loads a section with decoded embedding and boolean flags", () => {
+        const { store, dbPath } = openTempDB();
+        const db = rawDB(dbPath);
+        try {
+            const vec = [0.25, 0.5, 0.75, 1.0];
+            const blob = encodeVecTest(vec);
+            db.prepare(`
+        INSERT OR REPLACE INTO sections
+        (id, file_path, heading, heading_level, anchor, start_line, end_line,
+         content_hash, raw_content, embed_text, prose_word_count, has_table,
+         has_code, inbound_count, embedding, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run("sec-load-0001", "docs/x.md", "Heading", 2, "heading", 1, 9, "hash-x", "## Heading\n\nBody.", "heading body", 12, 1, // has_table = true
+            0, // has_code = false
+            3, // inbound_count
+            blob, "2024-01-01T00:00:00Z");
+            const { sections, embeddings } = store.loadAllSectionsWithEmbeddings();
+            expect(sections.length).toBe(1);
+            const sec = sections[0];
+            expect(sec.id).toBe("sec-load-0001");
+            expect(sec.file_path).toBe("docs/x.md");
+            expect(sec.heading_level).toBe(2);
+            expect(sec.prose_word_count).toBe(12);
+            expect(sec.has_table).toBe(true);
+            expect(sec.has_code).toBe(false);
+            expect(sec.inbound_count).toBe(3);
+            const gotVec = embeddings.get("sec-load-0001");
+            expect(gotVec).toBeDefined();
+            expect(gotVec.length).toBe(vec.length);
+            for (let i = 0; i < vec.length; i++) {
+                expect(gotVec[i]).toBeCloseTo(vec[i], 5);
+            }
+        }
+        finally {
+            db.close();
+            store.close();
+        }
+    });
+    // A section with a NULL embedding (only possible via the v1 NOT NULL-relaxed
+    // path or a manual write) must still load, mapping to a zero-length vector.
+    // The indexer treats a zero-length section vector as "no usable embedding";
+    // crashing or skipping the row instead would silently drop a section from the
+    // diff and could resurrect a stale duplicate.
+    it("loads a section with a NULL embedding as a zero-length vector (decodeVec null path)", () => {
+        const { store, dbPath } = openTempDB();
+        const db = rawDB(dbPath);
+        try {
+            // The blocks table allows NULL embedding; reuse it to exercise decodeVec's
+            // null branch through the section loader indirectly is not possible, so
+            // write a section row carrying a zero-length BLOB (empty embedding) which
+            // decodeVec must map to an empty Float32Array, not a 1-element NaN vector.
+            db.prepare(`
+        INSERT OR REPLACE INTO sections
+        (id, file_path, heading, heading_level, anchor, start_line, end_line,
+         content_hash, raw_content, embed_text, prose_word_count, has_table,
+         has_code, inbound_count, embedding, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run("sec-empty-vec01", "docs/y.md", "H", 2, "h", 1, 2, "hash-y", "## H", "h", 1, 0, 0, 0, new Uint8Array(0), "2024-01-01T00:00:00Z");
+            const { sections, embeddings } = store.loadAllSectionsWithEmbeddings();
+            expect(sections.length).toBe(1);
+            // Empty BLOB → empty vector (decodeVec's `?? new Float32Array(0)` fallback).
+            const gotVec = embeddings.get("sec-empty-vec01");
+            expect(gotVec).toBeDefined();
+            expect(gotVec.length).toBe(0);
+        }
+        finally {
+            db.close();
+            store.close();
+        }
+    });
+    // Two section rows must both round-trip; a loader that only read the first row
+    // (or overwrote earlier entries) would shrink the index and break clustering.
+    it("loads multiple section rows, one entry per id", () => {
+        const { store, dbPath } = openTempDB();
+        const db = rawDB(dbPath);
+        try {
+            const insert = db.prepare(`
+        INSERT OR REPLACE INTO sections
+        (id, file_path, heading, heading_level, anchor, start_line, end_line,
+         content_hash, raw_content, embed_text, prose_word_count, has_table,
+         has_code, inbound_count, embedding, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+            insert.run("sec-a", "docs/a.md", "A", 2, "a", 1, 2, "ha", "## A", "a", 1, 0, 0, 0, encodeVecTest([0.1, 0.2]), "2024-01-01T00:00:00Z");
+            insert.run("sec-b", "docs/b.md", "B", 2, "b", 1, 2, "hb", "## B", "b", 1, 0, 0, 0, encodeVecTest([0.3, 0.4]), "2024-01-01T00:00:00Z");
+            const { sections, embeddings } = store.loadAllSectionsWithEmbeddings();
+            expect(sections.length).toBe(2);
+            expect(new Set(sections.map((s) => s.id))).toEqual(new Set(["sec-a", "sec-b"]));
+            expect(embeddings.size).toBe(2);
+        }
+        finally {
+            db.close();
+            store.close();
+        }
+    });
+});
+describe("decodeVec — exported edge cases", () => {
+    // decodeVec is exported so the indexer can decode raw BLOBs. NULL and empty
+    // BLOBs both mean "no vector": both must yield a zero-length array (Go returned
+    // nil), never a 1-element NaN, or downstream cosine math would corrupt scores.
+    it("returns an empty Float32Array for null and for an empty BLOB", () => {
+        expect(decodeVec(null).length).toBe(0);
+        expect(decodeVec(new Uint8Array(0)).length).toBe(0);
+    });
+    // A non-empty BLOB must decode little-endian float32s; the byte layout is the
+    // cross-binary contract, so a wrong endianness or stride would silently mangle
+    // every stored vector read back from a Go-written DB.
+    it("decodes a little-endian float32 BLOB to the original values", () => {
+        const v = [1.5, -2.25, 0.125];
+        const got = decodeVec(encodeVecTest(v));
+        expect(got.length).toBe(v.length);
+        for (let i = 0; i < v.length; i++) {
+            expect(got[i]).toBeCloseTo(v[i], 5);
+        }
+    });
+});
+describe("querySections", () => {
+    // The indexer's diff-and-skip reads exactly id, content_hash, embedding from
+    // sections. A NULL/empty embedding must surface as-is so the indexer can tell a
+    // section with a stored vector from one needing re-embed.
+    it("returns id, content_hash, and the raw embedding BLOB per row", () => {
+        const { store, dbPath } = openTempDB();
+        const db = rawDB(dbPath);
+        try {
+            const blob = encodeVecTest([0.7, 0.8]);
+            db.prepare(`
+        INSERT OR REPLACE INTO sections
+        (id, file_path, heading, heading_level, anchor, start_line, end_line,
+         content_hash, raw_content, embed_text, prose_word_count, has_table,
+         has_code, inbound_count, embedding, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run("sec-q-0001", "docs/q.md", "Q", 2, "q", 1, 3, "hash-q", "## Q", "q", 2, 0, 0, 0, blob, "2024-01-01T00:00:00Z");
+            const rows = store.querySections();
+            expect(rows.length).toBe(1);
+            const r = rows[0];
+            expect(r.id).toBe("sec-q-0001");
+            expect(r.content_hash).toBe("hash-q");
+            expect(r.embedding).not.toBeNull();
+            expect(Array.from(r.embedding)).toEqual(Array.from(blob));
+        }
+        finally {
+            db.close();
+            store.close();
+        }
+    });
+});
+describe("execTx", () => {
+    // A transaction that runs without error must COMMIT: the whole point of ExecTx
+    // is durable batched writes, so a write inside it must survive after the call.
+    it("commits writes made inside the callback", () => {
+        const { store, dbPath } = openTempDB();
+        try {
+            store.execTx((db) => {
+                db.prepare(`
+          INSERT OR REPLACE INTO sections
+          (id, file_path, heading, heading_level, anchor, start_line, end_line,
+           content_hash, raw_content, embed_text, prose_word_count, has_table,
+           has_code, inbound_count, embedding, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run("sec-tx-0001", "docs/tx.md", "T", 2, "t", 1, 2, "hash-tx", "## T", "t", 1, 0, 0, 0, encodeVecTest([0.9]), "2024-01-01T00:00:00Z");
+            });
+        }
+        finally {
+            store.close();
+        }
+        // Committed: the row is visible to a fresh raw connection.
+        expect(countSectionsRows(dbPath)).toBe(1);
+    });
+    // A throwing callback must ROLLBACK and rethrow: partial writes from a failed
+    // batch must not persist, or the index would be left in a torn, inconsistent
+    // state that the indexer can neither trust nor detect.
+    it("rolls back and rethrows when the callback throws", () => {
+        const { store, dbPath } = openTempDB();
+        const boom = new Error("boom");
+        try {
+            expect(() => store.execTx((db) => {
+                db.prepare(`
+            INSERT OR REPLACE INTO sections
+            (id, file_path, heading, heading_level, anchor, start_line, end_line,
+             content_hash, raw_content, embed_text, prose_word_count, has_table,
+             has_code, inbound_count, embedding, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run("sec-tx-rollback", "docs/tx.md", "T", 2, "t", 1, 2, "hash-tx", "## T", "t", 1, 0, 0, 0, encodeVecTest([0.9]), "2024-01-01T00:00:00Z");
+                throw boom;
+            })).toThrow(boom);
+        }
+        finally {
+            store.close();
+        }
+        // Rolled back: the row never persisted.
+        expect(countSectionsRows(dbPath)).toBe(0);
+    });
+});
+describe("open — recreate after unreadable meta", () => {
+    // An existing file with no meta table is an old/corrupt DB. Open must NOT crash
+    // on the failed meta read: it falls back to delete-and-recreate so a damaged
+    // cache self-heals instead of wedging every run.
+    it("recreates the DB when the meta table is missing", () => {
+        const dbPath = newTempPath();
+        // Seed a file that has a sections table but NO meta table (readMeta throws).
+        const db = rawDB(dbPath);
+        try {
+            db.exec(createTableSQL); // sections + meta + blocks
+            db.exec(`DROP TABLE meta`); // remove meta so readMeta fails
+            insertSectionRowDB(db); // a row that recreate must wipe
+        }
+        finally {
+            db.close();
+        }
+        const { store, status } = open(dbPath, testModel, testDim);
+        try {
+            expect(status).toBe(OpenStatus.StatusSchemaRecreated);
+            // Recreated from scratch: meta restored and old row gone.
+            expect(readMetaVersion(dbPath)).toBe(SchemaVersion);
+            expect(countSectionsRows(dbPath)).toBe(0);
+        }
+        finally {
+            store.close();
+        }
+    });
+});
+describe("open — migration apply failure", () => {
+    // If a registered migration throws, Open must NOT swallow it or leave a
+    // half-migrated DB: the error propagates (after rollback) so the run fails
+    // loudly rather than operating on a schema that was never actually upgraded.
+    it("rolls back and surfaces the error when a migration throws", () => {
+        const dbPath = newTempPath();
+        setupMigrationDB(dbPath, "0"); // stored version 0, has a section row
+        const cleanup = registerTestMigration("0", () => {
+            throw new Error("migration exploded");
+        });
+        try {
+            expect(() => open(dbPath, testModel, testDim)).toThrow(/apply migration/);
+            // Rolled back: schema_version was NOT bumped to the binary version.
+            expect(readMetaVersion(dbPath)).toBe("0");
+            // The pre-existing row survived the rollback.
+            expect(countSectionsRows(dbPath)).toBe(1);
+        }
+        finally {
+            cleanup();
+        }
+    });
+});
+describe("open — embedder purge failure", () => {
+    // The purge runs DELETE FROM sections in a transaction. If that statement
+    // fails (e.g. the sections table is gone), Open must rethrow after closing the
+    // connection rather than returning a Store on a DB it failed to reconcile.
+    it("rethrows when the sections delete fails during purge", () => {
+        const dbPath = newTempPath();
+        // Proper DB first, then corrupt: mismatch the model AND drop sections so the
+        // purge's DELETE FROM sections raises.
+        const { store } = open(dbPath, testModel, testDim);
+        store.close();
+        setMetaValue(dbPath, "embedder_model", "wrong-model");
+        const db = rawDB(dbPath);
+        try {
+            db.exec(`DROP TABLE sections`);
+        }
+        finally {
+            db.close();
+        }
+        expect(() => open(dbPath, testModel, testDim)).toThrow(/embedder purge/);
+    });
+});