gitnexus 1.6.13-rc.11 → 1.6.13-rc.12

package/dist/core/embeddings/embedding-restore-spill.d.ts

@@ -0,0 +1,89 @@
+import type { CachedEmbedding } from './types.js';
+/** In-RAM vector copies stay below this row count; larger tables use the spill. */
+export declare const DEFAULT_EMBEDDING_CACHE_IN_MEMORY_ROW_LIMIT = 2048;
+export interface CachedEmbeddingMeta {
+    nodeId: string;
+    chunkIndex: number;
+    startLine: number;
+    endLine: number;
+    contentHash?: string;
+    /** Row order in the spill file (and in `embeddings` when in-memory). */
+    vectorIndex: number;
+}
+export interface EmbeddingVectorSpill {
+    path: string;
+    dims: number;
+    rowCount: number;
+}
+export interface CachedEmbeddingsSnapshot {
+    embeddingNodeIds: Set<string>;
+    /** Populated only when the table is at or under the in-memory row limit. */
+    embeddings: CachedEmbedding[];
+    rows: CachedEmbeddingMeta[];
+    spill?: EmbeddingVectorSpill;
+}
+export interface LoadCachedEmbeddingsOptions {
+    /**
+     * Keep full `number[]` vectors in RAM at or below this many rows.
+     * `0` always spills. Default {@link DEFAULT_EMBEDDING_CACHE_IN_MEMORY_ROW_LIMIT}
+     * or `GITNEXUS_EMBEDDING_CACHE_IN_MEMORY_LIMIT`.
+     */
+    inMemoryRowLimit?: number;
+    /** Directory for the spill file (default `os.tmpdir()`). */
+    spillDir?: string;
+}
+export interface CachedEmbeddingsBuilder {
+    embeddingNodeIds: Set<string>;
+    rows: CachedEmbeddingMeta[];
+    /** Float32 vectors kept in RAM until the in-memory row limit is exceeded. */
+    inMemory: Float32Array[] | null;
+    inMemoryRowLimit: number;
+    writer: EmbeddingSpillWriter;
+}
+export declare function emptyCachedEmbeddingsSnapshot(): CachedEmbeddingsSnapshot;
+export declare function resolveEmbeddingCacheInMemoryRowLimit(override?: number): number;
+export declare function normalizeCachedEmbeddings(raw: {
+    embeddingNodeIds?: Set<string>;
+    embeddings?: CachedEmbedding[];
+    rows?: CachedEmbeddingMeta[];
+    spill?: EmbeddingVectorSpill;
+}): CachedEmbeddingsSnapshot;
+export declare function cacheRowCount(snapshot: CachedEmbeddingsSnapshot): number;
+export declare function snapshotEmbeddingDims(snapshot: CachedEmbeddingsSnapshot): number | undefined;
+export declare function coerceEmbeddingToFloat32(embedding: unknown): Float32Array | null;
+export declare function float32ToNumberArray(vec: Float32Array): number[];
+/** Best-effort unlink of every tracked spill. Safe to call more than once. */
+export declare function discardLiveEmbeddingSpills(): void;
+/** Run `fn` so later {@link discardScopedEmbeddingSpills} only unlinks this run. */
+export declare function withEmbeddingSpillScope<T>(fn: () => T): T;
+/** Unlink spills created inside the current {@link withEmbeddingSpillScope}. */
+export declare function discardScopedEmbeddingSpills(): void;
+export declare class EmbeddingSpillWriter {
+    readonly path: string;
+    dims: number;
+    rowCount: number;
+    private fd;
+    private closed;
+    constructor(dir: string);
+    append(vec: Float32Array): void;
+    finish(): EmbeddingVectorSpill | undefined;
+    abort(): void;
+    private unlinkQuiet;
+}
+/** Validates the spill header once and reads vectors without reopening the file. */
+export declare class EmbeddingSpillReader {
+    private fd;
+    private readonly bytesPerVec;
+    readonly dims: number;
+    readonly rowCount: number;
+    constructor(spill: EmbeddingVectorSpill);
+    read(indices: readonly number[]): Float32Array[];
+    close(): void;
+}
+export declare function readSpillVectors(spill: EmbeddingVectorSpill, indices: readonly number[]): Float32Array[];
+export declare function disposeEmbeddingSpill(spill?: EmbeddingVectorSpill): void;
+export declare function createCachedEmbeddingsBuilder(options?: LoadCachedEmbeddingsOptions): CachedEmbeddingsBuilder;
+export declare function ingestCachedEmbeddingRow(builder: CachedEmbeddingsBuilder, row: Record<string, unknown> | unknown[], hasContentHash: boolean): void;
+export declare function finalizeCachedEmbeddingsSnapshot(builder: CachedEmbeddingsBuilder): CachedEmbeddingsSnapshot;
+export declare function abortCachedEmbeddingsBuilder(builder: CachedEmbeddingsBuilder): void;
+export declare function materializeCachedEmbeddings(snapshot: CachedEmbeddingsSnapshot, metas: readonly CachedEmbeddingMeta[], spillReader?: EmbeddingSpillReader): CachedEmbedding[];

package/dist/core/embeddings/embedding-restore-spill.js

@@ -0,0 +1,388 @@
+/**
+ * Disk-backed restore cache for CodeEmbedding rows (#3306).
+ *
+ * `loadCachedEmbeddings` used to `getAll()` the table and `map(Number)` every
+ * vector into a JS `number[]`. On a large already-indexed repo that single
+ * structure OOMs the V8 heap during "Caching embeddings..." even when the
+ * incremental diff is a handful of nodes.
+ *
+ * This module keeps metadata in RAM and writes vectors to a temp Float32
+ * spill. Restore materializes only the rows that Phase 3.5 will re-insert,
+ * in the existing 200-row batches.
+ */
+import { closeSync, openSync, readSync, unlinkSync, writeSync } from 'node:fs';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomBytes } from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+/** In-RAM vector copies stay below this row count; larger tables use the spill. */
+export const DEFAULT_EMBEDDING_CACHE_IN_MEMORY_ROW_LIMIT = 2048;
+const SPILL_MAGIC = 'GNXE';
+const SPILL_VERSION = 1;
+const SPILL_HEADER_BYTES = 12;
+export function emptyCachedEmbeddingsSnapshot() {
+    return { embeddingNodeIds: new Set(), embeddings: [], rows: [] };
+}
+export function resolveEmbeddingCacheInMemoryRowLimit(override) {
+    if (override !== undefined) {
+        if (!Number.isFinite(override) || override < 0) {
+            return DEFAULT_EMBEDDING_CACHE_IN_MEMORY_ROW_LIMIT;
+        }
+        return Math.floor(override);
+    }
+    const raw = process.env.GITNEXUS_EMBEDDING_CACHE_IN_MEMORY_LIMIT;
+    if (raw === undefined || raw === '')
+        return DEFAULT_EMBEDDING_CACHE_IN_MEMORY_ROW_LIMIT;
+    const parsed = parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed >= 0
+        ? parsed
+        : DEFAULT_EMBEDDING_CACHE_IN_MEMORY_ROW_LIMIT;
+}
+export function normalizeCachedEmbeddings(raw) {
+    const embeddings = raw.embeddings ?? [];
+    const embeddingNodeIds = raw.embeddingNodeIds ?? new Set(embeddings.map((row) => row.nodeId));
+    const rows = raw.rows ??
+        embeddings.map((row, vectorIndex) => ({
+            nodeId: row.nodeId,
+            chunkIndex: row.chunkIndex,
+            startLine: row.startLine,
+            endLine: row.endLine,
+            contentHash: row.contentHash,
+            vectorIndex,
+        }));
+    return { embeddingNodeIds, embeddings, rows, spill: raw.spill };
+}
+export function cacheRowCount(snapshot) {
+    return snapshot.rows.length > 0 ? snapshot.rows.length : snapshot.embeddings.length;
+}
+export function snapshotEmbeddingDims(snapshot) {
+    if (snapshot.spill && snapshot.spill.dims > 0)
+        return snapshot.spill.dims;
+    const dims = snapshot.embeddings[0]?.embedding.length;
+    return dims && dims > 0 ? dims : undefined;
+}
+export function coerceEmbeddingToFloat32(embedding) {
+    if (embedding == null)
+        return null;
+    if (embedding instanceof Float32Array) {
+        return embedding.length > 0 ? embedding : null;
+    }
+    if (ArrayBuffer.isView(embedding) && !(embedding instanceof DataView)) {
+        const view = embedding;
+        if (view.length === 0)
+            return null;
+        return Float32Array.from({ length: view.length }, (_, i) => Number(view[i]));
+    }
+    if (typeof embedding === 'object' &&
+        typeof embedding[Symbol.iterator] === 'function') {
+        const arr = Array.isArray(embedding)
+            ? embedding
+            : Array.from(embedding);
+        if (arr.length === 0)
+            return null;
+        return Float32Array.from(arr, (value) => Number(value));
+    }
+    return null;
+}
+export function float32ToNumberArray(vec) {
+    const out = new Array(vec.length);
+    for (let i = 0; i < vec.length; i++)
+        out[i] = vec[i];
+    return out;
+}
+/**
+ * `fs.writeSync` can return a short byte count. Loop until the whole buffer
+ * lands, matching `sync-csv-writer.ts`, so a partial write never advances
+ * `rowCount` on a truncated vector.
+ */
+function writeAllSync(fd, data) {
+    let offset = 0;
+    while (offset < data.length) {
+        const n = writeSync(fd, data, offset, data.length - offset);
+        if (n <= 0) {
+            throw new Error(`embedding spill short write: wrote ${n} of ${data.length - offset} bytes`);
+        }
+        offset += n;
+    }
+}
+function unlinkBestEffort(filePath) {
+    try {
+        unlinkSync(filePath);
+    }
+    catch {
+        /* ENOENT or already removed */
+    }
+}
+const liveSpillPaths = new Set();
+const spillScope = new AsyncLocalStorage();
+let spillExitHookInstalled = false;
+function trackLiveSpillPath(filePath) {
+    liveSpillPaths.add(filePath);
+    spillScope.getStore()?.add(filePath);
+    if (!spillExitHookInstalled) {
+        spillExitHookInstalled = true;
+        process.on('exit', () => {
+            for (const spillPath of liveSpillPaths) {
+                unlinkBestEffort(spillPath);
+            }
+        });
+    }
+}
+function untrackLiveSpillPath(filePath) {
+    liveSpillPaths.delete(filePath);
+}
+/** Best-effort unlink of every tracked spill. Safe to call more than once. */
+export function discardLiveEmbeddingSpills() {
+    for (const spillPath of [...liveSpillPaths]) {
+        unlinkBestEffort(spillPath);
+        liveSpillPaths.delete(spillPath);
+    }
+}
+/** Run `fn` so later {@link discardScopedEmbeddingSpills} only unlinks this run. */
+export function withEmbeddingSpillScope(fn) {
+    return spillScope.run(new Set(), fn);
+}
+/** Unlink spills created inside the current {@link withEmbeddingSpillScope}. */
+export function discardScopedEmbeddingSpills() {
+    const owned = spillScope.getStore();
+    if (!owned)
+        return;
+    for (const spillPath of [...owned]) {
+        unlinkBestEffort(spillPath);
+        liveSpillPaths.delete(spillPath);
+        owned.delete(spillPath);
+    }
+}
+export class EmbeddingSpillWriter {
+    path;
+    dims = 0;
+    rowCount = 0;
+    fd = null;
+    closed = false;
+    constructor(dir) {
+        this.path = path.join(dir, `gitnexus-embed-restore-${process.pid}-${randomBytes(8).toString('hex')}.bin`);
+    }
+    append(vec) {
+        if (this.closed) {
+            throw new Error('embedding spill writer already closed');
+        }
+        if (this.fd === null) {
+            this.dims = vec.length;
+            this.fd = openSync(this.path, 'wx', 0o600);
+            trackLiveSpillPath(this.path);
+            const header = Buffer.alloc(SPILL_HEADER_BYTES);
+            header.write(SPILL_MAGIC, 0, 4, 'ascii');
+            header.writeUInt8(SPILL_VERSION, 4);
+            header.writeUInt32LE(this.dims, 5);
+            writeAllSync(this.fd, header);
+        }
+        else if (vec.length !== this.dims) {
+            throw new Error(`embedding dim mismatch while spilling: got ${vec.length}, expected ${this.dims}`);
+        }
+        writeAllSync(this.fd, Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength));
+        this.rowCount++;
+    }
+    finish() {
+        if (this.fd !== null) {
+            closeSync(this.fd);
+            this.fd = null;
+        }
+        this.closed = true;
+        if (this.rowCount === 0) {
+            this.unlinkQuiet();
+            return undefined;
+        }
+        return { path: this.path, dims: this.dims, rowCount: this.rowCount };
+    }
+    abort() {
+        const opened = this.fd !== null;
+        if (this.fd !== null) {
+            try {
+                closeSync(this.fd);
+            }
+            catch {
+                /* already closed */
+            }
+            this.fd = null;
+        }
+        this.closed = true;
+        if (opened || this.rowCount > 0) {
+            this.unlinkQuiet();
+        }
+    }
+    unlinkQuiet() {
+        unlinkBestEffort(this.path);
+        untrackLiveSpillPath(this.path);
+    }
+}
+/** Validates the spill header once and reads vectors without reopening the file. */
+export class EmbeddingSpillReader {
+    fd = null;
+    bytesPerVec;
+    dims;
+    rowCount;
+    constructor(spill) {
+        this.rowCount = spill.rowCount;
+        const fd = openSync(spill.path, 'r');
+        try {
+            const header = Buffer.alloc(SPILL_HEADER_BYTES);
+            const headerRead = readSync(fd, header, 0, SPILL_HEADER_BYTES, 0);
+            if (headerRead !== SPILL_HEADER_BYTES || header.toString('ascii', 0, 4) !== SPILL_MAGIC) {
+                throw new Error(`invalid embedding spill header: ${spill.path}`);
+            }
+            if (header.readUInt8(4) !== SPILL_VERSION) {
+                throw new Error(`unsupported embedding spill version in ${spill.path}`);
+            }
+            const dims = header.readUInt32LE(5);
+            if (dims !== spill.dims) {
+                throw new Error(`embedding spill dim mismatch: file ${dims}, expected ${spill.dims}`);
+            }
+            this.dims = dims;
+            this.bytesPerVec = dims * 4;
+            this.fd = fd;
+        }
+        catch (err) {
+            closeSync(fd);
+            throw err;
+        }
+    }
+    read(indices) {
+        if (this.fd === null) {
+            throw new Error('embedding spill reader already closed');
+        }
+        const out = [];
+        for (const index of indices) {
+            if (!Number.isInteger(index) || index < 0 || index >= this.rowCount) {
+                throw new Error(`embedding spill index out of range: ${index}`);
+            }
+            const offset = SPILL_HEADER_BYTES + index * this.bytesPerVec;
+            const copy = new Float32Array(this.dims);
+            const bytes = new Uint8Array(copy.buffer, copy.byteOffset, this.bytesPerVec);
+            const n = readSync(this.fd, bytes, 0, this.bytesPerVec, offset);
+            if (n !== this.bytesPerVec) {
+                throw new Error(`short embedding spill read at index ${index}`);
+            }
+            out.push(copy);
+        }
+        return out;
+    }
+    close() {
+        if (this.fd === null)
+            return;
+        closeSync(this.fd);
+        this.fd = null;
+    }
+}
+export function readSpillVectors(spill, indices) {
+    const reader = new EmbeddingSpillReader(spill);
+    try {
+        return reader.read(indices);
+    }
+    finally {
+        reader.close();
+    }
+}
+export function disposeEmbeddingSpill(spill) {
+    if (!spill?.path)
+        return;
+    unlinkBestEffort(spill.path);
+    untrackLiveSpillPath(spill.path);
+}
+export function createCachedEmbeddingsBuilder(options) {
+    const inMemoryRowLimit = resolveEmbeddingCacheInMemoryRowLimit(options?.inMemoryRowLimit);
+    return {
+        embeddingNodeIds: new Set(),
+        rows: [],
+        inMemory: inMemoryRowLimit <= 0 ? null : [],
+        inMemoryRowLimit,
+        writer: new EmbeddingSpillWriter(options?.spillDir ?? os.tmpdir()),
+    };
+}
+export function ingestCachedEmbeddingRow(builder, row, hasContentHash) {
+    const rec = row;
+    const nodeId = String(rec.nodeId ?? rec[0] ?? '');
+    if (!nodeId)
+        return;
+    const embedding = rec.embedding ?? rec[4];
+    const f32 = coerceEmbeddingToFloat32(embedding);
+    if (!f32)
+        return;
+    builder.embeddingNodeIds.add(nodeId);
+    const meta = {
+        nodeId,
+        chunkIndex: Number(rec.chunkIndex ?? rec[1] ?? 0),
+        startLine: Number(rec.startLine ?? rec[2] ?? 0),
+        endLine: Number(rec.endLine ?? rec[3] ?? 0),
+        contentHash: hasContentHash
+            ? (rec.contentHash ?? rec[5] ?? undefined)
+            : undefined,
+        vectorIndex: builder.rows.length,
+    };
+    builder.rows.push(meta);
+    if (builder.inMemory && builder.rows.length <= builder.inMemoryRowLimit) {
+        builder.inMemory.push(f32);
+        return;
+    }
+    if (builder.inMemory) {
+        for (const prior of builder.inMemory) {
+            builder.writer.append(prior);
+        }
+        builder.inMemory = null;
+    }
+    builder.writer.append(f32);
+}
+export function finalizeCachedEmbeddingsSnapshot(builder) {
+    const inMemory = builder.inMemory;
+    if (inMemory) {
+        builder.writer.abort();
+        return {
+            embeddingNodeIds: builder.embeddingNodeIds,
+            embeddings: builder.rows.map((meta, i) => ({
+                nodeId: meta.nodeId,
+                chunkIndex: meta.chunkIndex,
+                startLine: meta.startLine,
+                endLine: meta.endLine,
+                contentHash: meta.contentHash,
+                embedding: float32ToNumberArray(inMemory[i]),
+            })),
+            rows: builder.rows,
+        };
+    }
+    return {
+        embeddingNodeIds: builder.embeddingNodeIds,
+        embeddings: [],
+        rows: builder.rows,
+        spill: builder.writer.finish(),
+    };
+}
+export function abortCachedEmbeddingsBuilder(builder) {
+    builder.writer.abort();
+}
+export function materializeCachedEmbeddings(snapshot, metas, spillReader) {
+    if (metas.length === 0)
+        return [];
+    if (snapshot.spill && snapshot.embeddings.length === 0) {
+        const indices = metas.map((meta) => meta.vectorIndex);
+        const vectors = spillReader
+            ? spillReader.read(indices)
+            : readSpillVectors(snapshot.spill, indices);
+        return metas.map((meta, i) => ({
+            nodeId: meta.nodeId,
+            chunkIndex: meta.chunkIndex,
+            startLine: meta.startLine,
+            endLine: meta.endLine,
+            contentHash: meta.contentHash,
+            embedding: float32ToNumberArray(vectors[i]),
+        }));
+    }
+    if (snapshot.embeddings.length === 0)
+        return [];
+    const byKey = new Map(snapshot.embeddings.map((row) => [`${row.nodeId}:${row.chunkIndex}`, row]));
+    return metas.map((meta) => {
+        const hit = byKey.get(`${meta.nodeId}:${meta.chunkIndex}`) ?? snapshot.embeddings[meta.vectorIndex];
+        if (!hit) {
+            throw new Error(`missing cached embedding ${meta.nodeId}:${meta.chunkIndex}`);
+        }
+        return hit;
+    });
+}

package/dist/core/lbug/lbug-adapter.d.ts

@@ -4,7 +4,7 @@ import { type ContentRetention } from '../../storage/repo-meta.js';
 import { NodeTableName } from './schema.js';
 import type { GraphEmitManifest } from './graph-emit-sink.js';
 import type { PdgEmitManifest } from './pdg-emit-sink.js';
-import { type CachedEmbedding } from '../embeddings/types.js';
+import { type CachedEmbeddingsSnapshot, type LoadCachedEmbeddingsOptions } from '../embeddings/embedding-restore-spill.js';
 import { type ExtensionEnsureOptions } from './extension-loader.js';
 /** Result of splitting the relationship CSV into per-label-pair files. */
 export interface RelCsvSplitResult {
@@ -194,15 +194,16 @@ export declare const getLbugStats: () => Promise<{
 }>;
 /**
  * Load cached embeddings from LadybugDB before a rebuild.
- * Returns all embedding vectors so they can be re-inserted after the graph is reloaded,
- * avoiding expensive re-embedding of unchanged nodes.
+ *
+ * Streams `CodeEmbedding` rows with `hasNext`/`getNext` under `withConnLock`
+ * (#2264, #3306). Vectors are spilled to a temp Float32 file once the table
+ * exceeds the in-memory row limit so incremental analyze cannot OOM the V8
+ * heap by materializing every `number[]` up front. Small tables still return
+ * in-RAM `embeddings` for existing callers/tests.
  *
  * Detects old schema (no chunkIndex column) and returns empty cache to trigger rebuild.
  */
-export declare const loadCachedEmbeddings: () => Promise<{
-    embeddingNodeIds: Set<string>;
-    embeddings: CachedEmbedding[];
-}>;
+export declare const loadCachedEmbeddings: (options?: LoadCachedEmbeddingsOptions) => Promise<CachedEmbeddingsSnapshot>;
 /**
  * Fetch existing embedding hashes from CodeEmbedding table for incremental embedding.
  * Returns a Map<nodeId, contentHash> suitable for passing to `runEmbeddingPipeline`.

package/dist/core/lbug/lbug-adapter.js

@@ -24,6 +24,7 @@ import { streamAllCSVsToDisk } from './csv-generator.js';
 import { PDG_EDGE_TYPES } from './pdg-emit-sink.js';
 import { getNodeLabel as deriveNodeLabel } from './rel-pair-routing.js';
 import { EMBEDDABLE_LABELS } from '../embeddings/types.js';
+import { abortCachedEmbeddingsBuilder, createCachedEmbeddingsBuilder, emptyCachedEmbeddingsSnapshot, finalizeCachedEmbeddingsSnapshot, ingestCachedEmbeddingRow, } from '../embeddings/embedding-restore-spill.js';
 import { extensionManager, getFtsCapability, resolveAnalyzeInstallPolicy, } from './extension-loader.js';
 // Remedy classification for LOAD failures (#2374/#2383). Pure + node:fs only, so
 // this adds no cycle: `extension-loader.ts` already depends on it.
@@ -1785,24 +1786,28 @@ export const getLbugStats = async () => {
 };
 /**
  * Load cached embeddings from LadybugDB before a rebuild.
- * Returns all embedding vectors so they can be re-inserted after the graph is reloaded,
- * avoiding expensive re-embedding of unchanged nodes.
+ *
+ * Streams `CodeEmbedding` rows with `hasNext`/`getNext` under `withConnLock`
+ * (#2264, #3306). Vectors are spilled to a temp Float32 file once the table
+ * exceeds the in-memory row limit so incremental analyze cannot OOM the V8
+ * heap by materializing every `number[]` up front. Small tables still return
+ * in-RAM `embeddings` for existing callers/tests.
  *
  * Detects old schema (no chunkIndex column) and returns empty cache to trigger rebuild.
  */
-export const loadCachedEmbeddings = async () => {
+export const loadCachedEmbeddings = async (options) => {
     const c = conn;
     if (!c) {
-        return { embeddingNodeIds: new Set(), embeddings: [] };
+        return emptyCachedEmbeddingsSnapshot();
     }
     // The whole read runs inside the connection lock (#2264 review P2). It's safe
     // today only by call-ordering (loadCachedEmbeddings runs before the WAL driver
     // starts), but the lock makes it robust to future reordering — a concurrent
     // CHECKPOINT on the singleton connection is the documented corruption trigger.
-    // Leaf read: no nested withConnLock-wrapped helpers inside.
+    // Leaf read: no nested withConnLock-wrapped helpers inside. Do NOT call
+    // `streamQuery` here — that path is unlocked and would race a CHECKPOINT.
     return withConnLock(async () => {
-        const embeddingNodeIds = new Set();
-        const embeddings = [];
+        const builder = createCachedEmbeddingsBuilder(options);
         try {
             // Schema migration detection: query with new columns to verify schema version.
             // Old schema only had (nodeId, embedding); new schema adds (id, chunkIndex, startLine, endLine, contentHash).
@@ -1815,49 +1820,47 @@ export const loadCachedEmbeddings = async () => {
                 await readQueryRows(check);
             }
             catch {
-                return { embeddingNodeIds: new Set(), embeddings: [] };
+                abortCachedEmbeddingsBuilder(builder);
+                return emptyCachedEmbeddingsSnapshot();
             }
-            // Try to read contentHash alongside chunk columns
-            let rows;
+            let queryResult;
             let hasContentHash = true;
             try {
-                rows = await c.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex, e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding, e.contentHash AS contentHash`);
-            }
-            catch (err) {
-                // Fallback for legacy DBs without contentHash column
-                const msg = err?.message ?? '';
-                if (isMissingColumnOrTableError(msg)) {
-                    hasContentHash = false;
-                    rows = await c.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex, e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding`);
+                try {
+                    queryResult = await c.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex, e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding, e.contentHash AS contentHash`);
                 }
-                else {
-                    throw err;
+                catch (err) {
+                    // Fallback for legacy DBs without contentHash column
+                    const msg = err?.message ?? '';
+                    if (isMissingColumnOrTableError(msg)) {
+                        hasContentHash = false;
+                        queryResult = await c.query(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex, e.startLine AS startLine, e.endLine AS endLine, e.embedding AS embedding`);
+                    }
+                    else {
+                        throw err;
+                    }
                 }
-            }
-            for (const row of await readQueryRows(rows)) {
-                const nodeId = String(row.nodeId ?? row[0] ?? '');
-                if (!nodeId)
-                    continue;
-                embeddingNodeIds.add(nodeId);
-                const embedding = row.embedding ?? row[4];
-                if (embedding) {
-                    embeddings.push({
-                        nodeId,
-                        chunkIndex: Number(row.chunkIndex ?? row[1] ?? 0),
-                        startLine: Number(row.startLine ?? row[2] ?? 0),
-                        endLine: Number(row.endLine ?? row[3] ?? 0),
-                        embedding: Array.isArray(embedding)
-                            ? embedding.map(Number)
-                            : Array.from(embedding).map(Number),
-                        contentHash: hasContentHash ? (row.contentHash ?? row[5] ?? undefined) : undefined,
-                    });
+                const results = Array.isArray(queryResult) ? queryResult : [queryResult];
+                const result = results[0];
+                while (await result.hasNext()) {
+                    const row = await result.getNext();
+                    ingestCachedEmbeddingRow(builder, row, hasContentHash);
                 }
+                return finalizeCachedEmbeddingsSnapshot(builder);
+            }
+            catch (err) {
+                abortCachedEmbeddingsBuilder(builder);
+                throw err;
+            }
+            finally {
+                if (queryResult)
+                    await closeQueryResults(queryResult);
             }
         }
-        catch {
-            /* embedding table may not exist */
+        catch (err) {
+            abortCachedEmbeddingsBuilder(builder);
+            throw err;
         }
-        return { embeddingNodeIds, embeddings };
     });
 };
 /**