gitnexus 1.6.13-rc.72 → 1.6.13-rc.74

package/dist/cli/embeddings-sync.js

@@ -4,7 +4,7 @@ import { LBUG_DIRECTORY } from '../storage/storage-constants.js';
 import path from 'node:path';
 import { cliInfo } from './cli-message.js';
 import { getGitRoot } from '../storage/git.js';
-import { acquireIndexLock, requireExclusiveIndexLock } from '../storage/index-lock.js';
+import { acquireIndexLock, requireExclusiveIndexLock, sweepStagingArtifacts, } from '../storage/index-lock.js';
 import { getStoragePaths, loadMeta, saveMeta } from '../storage/repo-manager.js';
 import { closeLbug, executeQuery, executeWithReusedStatement, fetchExistingEmbeddingHashes, initLbug, } from '../core/lbug/lbug-adapter.js';
 import { decideEmbeddingResume, mintInterruptedCheckpoint, mintPartialCheckpoint, mintUnverifiedCountCheckpoint, } from '../core/embedding-checkpoint.js';
@@ -24,9 +24,17 @@ export const embeddingsSyncCommand = async (inputPath) => {
     // Writes go to the slot's own graph. A shared-store checkout that reads an
     // immutable commit graph (#3352) takes a private copy first.
     const lbugPath = path.join(metaDir, LBUG_DIRECTORY);
-    const lock = await acquireIndexLock(metaDir);
+    const lock = await acquireIndexLock(metaDir, { sweep: false });
     try {
         requireExclusiveIndexLock(lock, `Cannot acquire the index lock at ${metaDir}; refusing an unlocked embeddings sync.`);
+        // Sync writes the published graph and cannot recover a staged generation.
+        // Reject even malformed receipts before sweeping staging files or writing.
+        const recoveryCheckpoint = (await loadMeta(metaDir))?.embeddingCheckpoint;
+        if (recoveryCheckpoint && Object.hasOwn(recoveryCheckpoint, 'recovery')) {
+            throw new Error('Cannot sync embeddings: the index checkpoint references staged embeddings. ' +
+                'Run `gitnexus analyze` to recover them first.');
+        }
+        sweepStagingArtifacts(metaDir);
         if (!(await ensurePrivateSharedGraph(metaDir, (m) => console.log(`  ${m}`)))) {
             throw new Error('The shared graph this checkout reads is gone. Run gitnexus analyze first.');
         }

package/dist/core/embeddings/staged-embedding-recovery-child.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/embeddings/staged-embedding-recovery-child.js

@@ -0,0 +1,170 @@
+/** Isolated strict native reader. Never import this entrypoint into analyze. */
+import fs from 'node:fs';
+import path from 'node:path';
+import lbug from '@ladybugdb/core';
+import { createLbugDatabase, toNativeSafePath } from '../lbug/lbug-config.js';
+import { FAMILY_SUFFIXES } from '../../storage/embedding-recovery.js';
+import { abortCachedEmbeddingsBuilder, createCachedEmbeddingsBuilder, finalizeCachedEmbeddingsSnapshot, ingestCachedEmbeddingRow, } from './embedding-restore-spill.js';
+/** Native replay and close may checkpoint; only give them disposable copies. */
+function copyRecoveryFamily(dbPath, exportDir) {
+    const replayDir = fs.mkdtempSync(path.join(exportDir, 'replay-'));
+    const replayPath = path.join(replayDir, path.basename(dbPath));
+    const noFollow = fs.constants.O_NOFOLLOW ?? 0;
+    const flags = fs.constants.O_RDONLY | noFollow | (fs.constants.O_NONBLOCK ?? 0);
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    for (const suffix of FAMILY_SUFFIXES) {
+        const sourcePath = dbPath + suffix;
+        let entry;
+        try {
+            entry = fs.lstatSync(sourcePath, { bigint: true });
+        }
+        catch (error) {
+            if (suffix && error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        if (!entry.isFile())
+            throw new Error('staged embedding family is not a regular file');
+        const source = fs.openSync(sourcePath, flags);
+        let destination;
+        try {
+            const opened = fs.fstatSync(source, { bigint: true });
+            const current = fs.lstatSync(sourcePath, { bigint: true });
+            if (!opened.isFile() ||
+                !current.isFile() ||
+                (noFollow === 0 && opened.ino === 0n) ||
+                opened.dev !== entry.dev ||
+                opened.ino !== entry.ino ||
+                opened.dev !== current.dev ||
+                opened.ino !== current.ino) {
+                throw new Error('staged embedding family changed while opening');
+            }
+            destination = fs.openSync(replayPath + suffix, 'wx', 0o600);
+            let copied = 0n;
+            for (;;) {
+                const bytesRead = fs.readSync(source, buffer, 0, buffer.length, null);
+                if (bytesRead === 0)
+                    break;
+                fs.writeFileSync(destination, buffer.subarray(0, bytesRead));
+                copied += BigInt(bytesRead);
+            }
+            const after = fs.fstatSync(source, { bigint: true });
+            if (copied !== opened.size ||
+                after.size !== opened.size ||
+                after.mtimeNs !== opened.mtimeNs ||
+                after.ctimeNs !== opened.ctimeNs) {
+                throw new Error('staged embedding family changed while copying');
+            }
+        }
+        finally {
+            try {
+                if (destination !== undefined)
+                    fs.closeSync(destination);
+            }
+            finally {
+                fs.closeSync(source);
+            }
+        }
+    }
+    return replayPath;
+}
+async function extract() {
+    const [dbPath, exportDir, dimensionsArg] = process.argv.slice(2);
+    const dimensions = Number(dimensionsArg);
+    if (!dbPath || !exportDir || !Number.isInteger(dimensions) || dimensions <= 0) {
+        throw new Error('invalid staged embedding extraction arguments');
+    }
+    // The parent owns exportDir and reclaims it even after killing this child.
+    const replayPath = copyRecoveryFamily(dbPath, exportDir);
+    const builder = createCachedEmbeddingsBuilder({ inMemoryRowLimit: 0, spillDir: exportDir });
+    const rejectedNodeIds = new Set();
+    let db;
+    let conn;
+    try {
+        // Avoid openLbugConnection's test-fixture lock sweep: a recovery source must
+        // never have its WAL removed, even when an external slot resembles a fixture.
+        db = createLbugDatabase(lbug, toNativeSafePath(replayPath), { throwOnWalReplayFailure: true });
+        conn = new lbug.Connection(db);
+        const queried = await conn.query('MATCH (e:CodeEmbedding) 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');
+        const results = Array.isArray(queried) ? queried : [queried];
+        try {
+            if (results.length !== 1)
+                throw new Error('unexpected staged embedding query result');
+            const result = results[0];
+            while (await result.hasNext()) {
+                const raw = await result.getNext();
+                const rec = raw;
+                const nodeId = rec.nodeId ?? rec[0];
+                if (typeof nodeId !== 'string' || !nodeId)
+                    throw new Error('invalid staged embedding node id');
+                const chunkIndex = rec.chunkIndex ?? rec[1];
+                const startLine = rec.startLine ?? rec[2];
+                const endLine = rec.endLine ?? rec[3];
+                const embedding = rec.embedding ?? rec[4];
+                const contentHash = rec.contentHash ?? rec[5];
+                const vector = Array.isArray(embedding) ||
+                    (ArrayBuffer.isView(embedding) && !(embedding instanceof DataView))
+                    ? Array.from(embedding)
+                    : undefined;
+                if (!Number.isInteger(chunkIndex) ||
+                    Number(chunkIndex) < 0 ||
+                    !Number.isInteger(startLine) ||
+                    Number(startLine) < 0 ||
+                    !Number.isInteger(endLine) ||
+                    Number(endLine) < Number(startLine) ||
+                    typeof contentHash !== 'string' ||
+                    !contentHash ||
+                    !vector ||
+                    vector.length !== dimensions ||
+                    vector.some((value) => typeof value !== 'number' ||
+                        !Number.isFinite(value) ||
+                        !Number.isFinite(Math.fround(value)))) {
+                    rejectedNodeIds.add(nodeId);
+                    continue;
+                }
+                ingestCachedEmbeddingRow(builder, { nodeId, chunkIndex, startLine, endLine, embedding: vector, contentHash }, true);
+            }
+        }
+        finally {
+            for (const result of results)
+                await result.close();
+        }
+        // Both closes must succeed. Suppressed native teardown errors are unsafe.
+        await conn.close();
+        await db.close();
+        const snapshot = finalizeCachedEmbeddingsSnapshot(builder);
+        if (snapshot.spill)
+            fs.renameSync(snapshot.spill.path, path.join(exportDir, 'vectors.bin'));
+        const manifest = {
+            version: 1,
+            dimensions,
+            rows: snapshot.rows,
+            rejectedNodeIds: [...rejectedNodeIds],
+        };
+        fs.writeFileSync(path.join(exportDir, 'manifest.json'), JSON.stringify(manifest), {
+            flag: 'wx',
+            mode: 0o600,
+        });
+    }
+    catch (err) {
+        abortCachedEmbeddingsBuilder(builder);
+        // Cleanup is best effort on a rejected source, never used to approve output.
+        try {
+            await conn?.close();
+        }
+        catch {
+            /* rejected */
+        }
+        try {
+            await db?.close();
+        }
+        catch {
+            /* rejected */
+        }
+        throw err;
+    }
+}
+extract().catch((err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/core/embeddings/staged-embedding-recovery.d.ts

@@ -0,0 +1,23 @@
+import { type CachedEmbeddingMeta, type CachedEmbeddingsSnapshot } from './embedding-restore-spill.js';
+export interface StagedEmbeddingRecoveryOptions {
+    dimensions: number;
+    /** Active checkpoint window and any incomplete inherited restore groups. */
+    excludedNodeIds?: Iterable<string>;
+    timeoutMs?: number;
+}
+export interface StagedEmbeddingExport {
+    version: 1;
+    dimensions: number;
+    rows: CachedEmbeddingMeta[];
+    rejectedNodeIds: string[];
+}
+/** A contiguous prefix is safe only when its node is outside every unsafe window. */
+export declare function validateRecoveredNodeGroups(rows: readonly CachedEmbeddingMeta[], excludedNodeIds?: ReadonlySet<string>): Set<string>;
+/** Whole recovered nodes replace whole published groups; vectors stay in bounded batches. */
+export declare function mergeRecoveredEmbeddings(live: CachedEmbeddingsSnapshot, recovered: CachedEmbeddingsSnapshot): CachedEmbeddingsSnapshot;
+/**
+ * Caller must validate checkpoint identity, schema, exact generation, and hold the
+ * index lock. A subprocess contains native WAL replay/query/destructor failures.
+ * A failed strict open is never retried with WAL removed or validation disabled.
+ */
+export declare function recoverStagedEmbeddings(dbPath: string, options: StagedEmbeddingRecoveryOptions): Promise<CachedEmbeddingsSnapshot>;

package/dist/core/embeddings/staged-embedding-recovery.js

@@ -0,0 +1,183 @@
+/** Recover paid embedding rows without opening an interrupted native DB in analyze. */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { abortCachedEmbeddingsBuilder, createCachedEmbeddingsBuilder, EmbeddingSpillReader, emptyCachedEmbeddingsSnapshot, finalizeCachedEmbeddingsSnapshot, ingestCachedEmbeddingRow, materializeCachedEmbeddings, } from './embedding-restore-spill.js';
+const RESTORE_BATCH_SIZE = 200;
+const DEFAULT_EXTRACTION_TIMEOUT_MS = 120_000;
+/** A contiguous prefix is safe only when its node is outside every unsafe window. */
+export function validateRecoveredNodeGroups(rows, excludedNodeIds = new Set()) {
+    const groups = new Map();
+    for (const row of rows) {
+        let group = groups.get(row.nodeId);
+        if (!group) {
+            group = { hash: row.contentHash, ordinals: new Set(), invalid: false };
+            groups.set(row.nodeId, group);
+        }
+        if (typeof row.nodeId !== 'string' ||
+            !row.nodeId ||
+            typeof row.contentHash !== 'string' ||
+            !row.contentHash ||
+            row.contentHash !== group.hash ||
+            !Number.isInteger(row.chunkIndex) ||
+            row.chunkIndex < 0 ||
+            group.ordinals.has(row.chunkIndex) ||
+            !Number.isInteger(row.startLine) ||
+            row.startLine < 0 ||
+            !Number.isInteger(row.endLine) ||
+            row.endLine < row.startLine)
+            group.invalid = true;
+        group.ordinals.add(row.chunkIndex);
+    }
+    const accepted = new Set();
+    for (const [nodeId, group] of groups) {
+        if (group.invalid || excludedNodeIds.has(nodeId))
+            continue;
+        // Unique ordinals with max n-1 and zero present have no holes.
+        if (!group.ordinals.has(0))
+            continue;
+        if ([...group.ordinals].some((ordinal) => ordinal >= group.ordinals.size))
+            continue;
+        accepted.add(nodeId);
+    }
+    return accepted;
+}
+/** Whole recovered nodes replace whole published groups; vectors stay in bounded batches. */
+export function mergeRecoveredEmbeddings(live, recovered) {
+    const builder = createCachedEmbeddingsBuilder({ inMemoryRowLimit: 0 });
+    try {
+        appendSnapshotRows(live, live.rows.filter((row) => !recovered.embeddingNodeIds.has(row.nodeId)), builder);
+        appendSnapshotRows(recovered, recovered.rows, builder);
+        return finalizeCachedEmbeddingsSnapshot(builder);
+    }
+    catch (err) {
+        abortCachedEmbeddingsBuilder(builder);
+        throw err;
+    }
+}
+function appendSnapshotRows(snapshot, rows, builder) {
+    const reader = snapshot.spill ? new EmbeddingSpillReader(snapshot.spill) : undefined;
+    try {
+        for (let i = 0; i < rows.length; i += RESTORE_BATCH_SIZE) {
+            const batch = materializeCachedEmbeddings(snapshot, rows.slice(i, i + RESTORE_BATCH_SIZE), reader);
+            for (const row of batch)
+                ingestCachedEmbeddingRow(builder, row, true);
+        }
+    }
+    finally {
+        reader?.close();
+    }
+}
+/**
+ * Caller must validate checkpoint identity, schema, exact generation, and hold the
+ * index lock. A subprocess contains native WAL replay/query/destructor failures.
+ * A failed strict open is never retried with WAL removed or validation disabled.
+ */
+export async function recoverStagedEmbeddings(dbPath, options) {
+    if (!Number.isInteger(options.dimensions) || options.dimensions <= 0) {
+        throw new Error('invalid staged embedding dimensions');
+    }
+    const dbStat = fs.lstatSync(dbPath);
+    if (!dbStat.isFile() || dbStat.isSymbolicLink())
+        throw new Error('staged embedding DB is not a regular file');
+    const exportDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-stage-export-'));
+    try {
+        await runExtractionChild(dbPath, exportDir, options);
+        const manifestPath = path.join(exportDir, 'manifest.json');
+        const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        if (manifest.version !== 1 ||
+            manifest.dimensions !== options.dimensions ||
+            !Array.isArray(manifest.rows) ||
+            !Array.isArray(manifest.rejectedNodeIds) ||
+            manifest.rejectedNodeIds.some((id) => typeof id !== 'string') ||
+            manifest.rows.some((row, i) => !row || row.vectorIndex !== i))
+            throw new Error('invalid staged embedding export manifest');
+        if (manifest.rows.length === 0)
+            return emptyCachedEmbeddingsSnapshot();
+        const spill = {
+            path: path.join(exportDir, 'vectors.bin'),
+            dims: options.dimensions,
+            rowCount: manifest.rows.length,
+        };
+        const vectorStat = fs.lstatSync(spill.path);
+        if (!vectorStat.isFile() ||
+            vectorStat.isSymbolicLink() ||
+            vectorStat.size !== 12 + spill.rowCount * spill.dims * 4) {
+            throw new Error('invalid staged embedding export size');
+        }
+        const excluded = new Set(options.excludedNodeIds ?? []);
+        for (const nodeId of manifest.rejectedNodeIds)
+            excluded.add(nodeId);
+        const accepted = validateRecoveredNodeGroups(manifest.rows, excluded);
+        const exported = {
+            rows: manifest.rows,
+            embeddings: [],
+            embeddingNodeIds: accepted,
+            spill,
+        };
+        const builder = createCachedEmbeddingsBuilder({ inMemoryRowLimit: 0 });
+        const reader = new EmbeddingSpillReader(spill);
+        try {
+            const rows = manifest.rows.filter((row) => accepted.has(row.nodeId));
+            for (let i = 0; i < rows.length; i += RESTORE_BATCH_SIZE) {
+                for (const row of materializeCachedEmbeddings(exported, rows.slice(i, i + RESTORE_BATCH_SIZE), reader)) {
+                    if (row.embedding.length !== options.dimensions ||
+                        row.embedding.some((value) => !Number.isFinite(value))) {
+                        throw new Error('invalid staged embedding vector');
+                    }
+                    ingestCachedEmbeddingRow(builder, row, true);
+                }
+            }
+            return finalizeCachedEmbeddingsSnapshot(builder);
+        }
+        catch (err) {
+            abortCachedEmbeddingsBuilder(builder);
+            throw err;
+        }
+        finally {
+            reader.close();
+        }
+    }
+    finally {
+        fs.rmSync(exportDir, { recursive: true, force: true });
+    }
+}
+function runExtractionChild(dbPath, exportDir, options) {
+    const compiledPath = fileURLToPath(new URL('./staged-embedding-recovery-child.js', import.meta.url));
+    const sourcePath = compiledPath.replace(/\.js$/, '.ts');
+    const childPath = fs.existsSync(compiledPath) ? compiledPath : sourcePath;
+    const args = childPath.endsWith('.ts')
+        ? ['--import', import.meta.resolve('tsx'), childPath]
+        : [childPath];
+    args.push(dbPath, exportDir, String(options.dimensions));
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, args, {
+            stdio: ['ignore', 'ignore', 'pipe'],
+            windowsHide: true,
+        });
+        let stderr = '';
+        let timedOut = false;
+        child.stderr.on('data', (chunk) => {
+            if (stderr.length < 4096)
+                stderr += chunk.toString().slice(0, 4096 - stderr.length);
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            // A process boundary is safe to kill even while native code is executing.
+            child.kill('SIGKILL');
+        }, options.timeoutMs ?? DEFAULT_EXTRACTION_TIMEOUT_MS);
+        child.once('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.once('close', (code, signal) => {
+            clearTimeout(timer);
+            if (code === 0 && !signal && !timedOut)
+                resolve();
+            else
+                reject(new Error(`staged embedding extraction failed${timedOut ? ' (timeout)' : ` (${signal ?? code})`}${stderr ? `: ${stderr.trim()}` : ''}`));
+        });
+    });
+}

package/dist/core/run-analyze.js

@@ -17,7 +17,8 @@ import fs from 'fs/promises';
 import { constants as fsConstants, existsSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { retryRename } from '../storage/fs-atomic.js';
-import { acquireIndexLock, requireExclusiveIndexLock } from '../storage/index-lock.js';
+import { acquireIndexLock, requireExclusiveIndexLock, sweepStagingArtifacts, } from '../storage/index-lock.js';
+import { resolveEmbeddingRecovery } from '../storage/embedding-recovery.js';
 import { invalidateNodeWorkspacePackages } from './ingestion/import-resolvers/node-workspace-packages.js';
 import { logNameFallbackSummary, summarizeNameFallback, countCallsByLanguage, } from './ingestion/scope-resolution/name-fallback-summary.js';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
@@ -657,6 +658,8 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
     const log = (msg) => callbacks.onLog?.(stripControlCharacters(msg));
     const acquireOpts = {
         log,
+        // Resolve and validate the canonical slot under the lock before cleanup.
+        sweep: false,
         onWaitStart: () => callbacks.onProgress('lock', 0, 'Waiting for another analyze to finish on this index…'),
     };
     let writeTarget = await resolveWriteTarget(repoPath, options);
@@ -702,6 +705,7 @@ export async function runFullAnalysis(repoPath, options, callbacks, runnerIdenti
             const flatShared = writeTarget.placement.branch ? undefined : writeTarget.sharedStore;
             if (flatShared)
                 await seedSharedSlot(flatShared, repoPath, log);
+            sweepStagingArtifacts(writeTarget.metaDir, log);
             const slotToLeave = options.noShare ? await optedInSlotToLeave(repoPath) : undefined;
             const result = await runFullAnalysisInner(repoPath, options, callbacks, writeTarget, contentRetention, runnerIdentityAtBootstrap);
             if (flatShared) {
@@ -1144,7 +1148,11 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
         }
         if (decision.action === 'abort')
             throw new Error(decision.error);
-        log(decision.log);
+        log(decision.action === 'resume' && checkpoint.recovery
+            ? `Previous analyze recorded an embedding checkpoint (${checkpoint.nodesProcessed}/` +
+                `${checkpoint.totalNodes} nodes); validating staged vectors before retrying ` +
+                `${decision.pendingNodeIds.size} pending node(s).`
+            : decision.log);
         if (options.dropEmbeddings) {
             // --drop-embeddings has always implied a rebuild here; the decision only
             // covers the marker.
@@ -1877,6 +1885,68 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
             }
         }
     }
+    // A checkpoint's pending decision and its paid, complete vectors are
+    // independent: --force discards the former but can still reuse the latter.
+    // Select only the explicitly referenced generation, never an orphan by age.
+    const stagedRecovery = resolveEmbeddingRecovery(metaDir, existingMeta?.embeddingCheckpoint);
+    const stagedCheckpoint = existingMeta?.embeddingCheckpoint;
+    const inheritedUnsafeNodeIds = new Set([
+        ...pendingEmbeddingNodeIds,
+        ...(stagedRecovery?.unsafeNodeIds ?? []),
+    ]);
+    if (shouldLoadCache && !options.dropEmbeddings && stagedRecovery && stagedCheckpoint) {
+        if (!embeddingIdentityForRun) {
+            const { resolveEmbeddingIdentity } = await import('./embeddings/embedding-identity.js');
+            embeddingIdentityForRun = resolveEmbeddingIdentity();
+        }
+        const marker = stagedCheckpoint;
+        const matchesIdentity = marker.model === embeddingIdentityForRun.model &&
+            marker.dimensions === embeddingIdentityForRun.dimensions &&
+            marker.provider === embeddingIdentityForRun.provider;
+        if (matchesIdentity && stagedRecovery.schemaFingerprint === SCHEMA_FINGERPRINT) {
+            // A force-discarded pending decision must not turn a known incomplete
+            // inherited group into a reusable cache merely because its hash matches.
+            if (inheritedUnsafeNodeIds.size > 0) {
+                const rows = cachedSnapshot.rows.filter((row) => !inheritedUnsafeNodeIds.has(row.nodeId));
+                cachedSnapshot = {
+                    ...cachedSnapshot,
+                    rows,
+                    embeddingNodeIds: new Set(rows.map((row) => row.nodeId)),
+                };
+            }
+            let recovered;
+            try {
+                const { recoverStagedEmbeddings, mergeRecoveredEmbeddings } = await import('./embeddings/staged-embedding-recovery.js');
+                recovered = await recoverStagedEmbeddings(stagedRecovery.dbPath, {
+                    dimensions: embeddingIdentityForRun.dimensions,
+                    excludedNodeIds: stagedRecovery.unsafeNodeIds,
+                });
+                const liveCacheDims = snapshotEmbeddingDims(cachedSnapshot);
+                if (liveCacheDims !== undefined && liveCacheDims !== embeddingIdentityForRun.dimensions) {
+                    log(`Embedding dimensions changed (${liveCacheDims}d -> ` +
+                        `${embeddingIdentityForRun.dimensions}d), discarding published cache`);
+                    discardCachedEmbeddings();
+                }
+                if (recovered.rows.length > 0) {
+                    const merged = mergeRecoveredEmbeddings(cachedSnapshot, recovered);
+                    disposeEmbeddingSpill(cachedSnapshot.spill);
+                    adoptCachedEmbeddings(merged);
+                }
+                log(`Recovered ${recovered.rows.length} complete staged embedding chunk(s) ` +
+                    `for ${recovered.embeddingNodeIds.size} node(s); unchanged content can reuse them.`);
+            }
+            catch (err) {
+                log(`Warning: could not recover staged embeddings (${err.message}); ` +
+                    'the retry will regenerate missing chunks.');
+            }
+            finally {
+                disposeEmbeddingSpill(recovered?.spill);
+            }
+        }
+        else {
+            log('Staged embedding identity or schema changed; its vectors will not be reused.');
+        }
+    }
     // ── Load incremental parse cache ──────────────────────────────────
     // Content-addressed: `--force` reuses parser shards; `useParseCache: false`
     // stages a new generation under a run-unique parse-rebuild.* dir and publishes
@@ -3516,6 +3586,14 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                 embeddingIdentityForRun = resolveEmbeddingIdentity();
             }
             const embeddingIdentity = embeddingIdentityForRun;
+            const stagedRecoveryEnabled = useAtomicSwap && isManualCheckpointEnabled();
+            if (useAtomicSwap && !stagedRecoveryEnabled) {
+                log('Manual WAL checkpoints are disabled; new staged work cannot be recovered after interruption. ' +
+                    'Any previous durable recovery source is retained until publication.');
+            }
+            const unsafeRecoveryNodeIds = new Set([...inheritedUnsafeNodeIds, ...restoreFailedNodeIds]);
+            let activeWindowNodeIds = [];
+            let recoveryGenerationDurable = false;
             // Build a Map<nodeId, contentHash> from cached embeddings for incremental mode
             let existingEmbeddings;
             if (cachedSnapshot.embeddingNodeIds.size > 0) {
@@ -3560,6 +3638,13 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                     stagedCheckpointEmbeddingCount = embeddings;
                 }
                 const latestMeta = (await loadMeta(metaDir)) ?? existingMeta;
+                // An in-place write or manual-checkpoint opt-out cannot create a new
+                // recoverable staged generation. Keep the complete previous receipt:
+                // updated progress or unsafe nodes would describe different source bytes.
+                const preservedRecoveryCheckpoint = !stagedRecoveryEnabled &&
+                    resolveEmbeddingRecovery(metaDir, latestMeta?.embeddingCheckpoint)
+                    ? latestMeta?.embeddingCheckpoint
+                    : undefined;
                 // First-ever analyze of this repo: no meta exists on disk yet (the
                 // pre-wipe dirty stamp only fires when one does). Mint the minimum
                 // RepoMeta requires, with `lastCommit: ''` — never `currentCommit` —
@@ -3570,6 +3655,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                     lastCommit: '',
                     indexedAt: new Date().toISOString(),
                 };
+                const interrupted = mintInterruptedCheckpoint(embeddingIdentity, checkpoint, pendingNodeIds);
                 await saveMeta(metaDir, {
                     ...base,
                     ...(embeddings === undefined || buildPath !== lbugPath
@@ -3577,7 +3663,18 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                         : { stats: { ...base.stats, embeddings } }),
                     // Written by a run that is still IN FLIGHT — see the `kind` doc in
                     // repo-manager.ts.
-                    embeddingCheckpoint: mintInterruptedCheckpoint(embeddingIdentity, checkpoint, pendingNodeIds),
+                    embeddingCheckpoint: preservedRecoveryCheckpoint ?? {
+                        ...interrupted,
+                        ...(stagedRecoveryEnabled
+                            ? {
+                                recovery: {
+                                    stagingFile: path.basename(buildPath),
+                                    schemaFingerprint: SCHEMA_FINGERPRINT,
+                                    unsafeNodeIds: [...unsafeRecoveryNodeIds],
+                                },
+                            }
+                            : {}),
+                    },
                 });
             };
             embeddingResult = await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
@@ -3591,7 +3688,21 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
             }, {}, cachedSnapshot.embeddingNodeIds.size > 0 ? cachedSnapshot.embeddingNodeIds : undefined, existingEmbeddings, {
                 forceReembedNodeIds: pendingEmbeddingNodeIds,
                 onCheckpointWindowStart: async ({ nodeIds, ...checkpoint }) => {
+                    const handoff = stagedRecoveryEnabled && !recoveryGenerationDurable;
+                    if (handoff) {
+                        if (!(await checkpointOnce())) {
+                            throw new Error('Could not checkpoint restored embeddings before recovery handoff.');
+                        }
+                        recoveryGenerationDurable = true;
+                    }
+                    activeWindowNodeIds = nodeIds;
+                    for (const id of nodeIds)
+                        unsafeRecoveryNodeIds.add(id);
                     await saveEmbeddingCheckpoint(checkpoint, nodeIds);
+                    // Reclaim the old source only after the new durable generation's
+                    // reference is saved. Later windows retain this same generation.
+                    if (handoff)
+                        sweepStagingArtifacts(metaDir, log);
                 },
                 // ── The mid-run count is a DIAGNOSTIC, not a gate (#2790) ──────
                 // This used to run the count query bare. THIS callback's rejection
@@ -3605,7 +3716,13 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
                 // touch stats.embeddings" signal — so the checkpoint still lands,
                 // with whatever count is already on disk left alone.
                 onCheckpoint: async (checkpoint) => {
-                    await checkpointOnce();
+                    const durable = await checkpointOnce();
+                    if (stagedRecoveryEnabled && !durable) {
+                        throw new Error('Could not checkpoint the completed embedding window for recovery.');
+                    }
+                    for (const id of activeWindowNodeIds)
+                        unsafeRecoveryNodeIds.delete(id);
+                    activeWindowNodeIds = [];
                     const measured = await measurePersistedEmbeddingCount(executeQuery);
                     if (measured.kind === 'unknown') {
                         log(`Warning: could not measure persisted embeddings at the embedding checkpoint ` +
@@ -4022,6 +4139,7 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
         // is a crash-safety improvement: a failed swap leaves the previous index
         // live and the next run recovers via the full-rebuild path.
         await saveMeta(metaDir, meta);
+        sweepStagingArtifacts(metaDir, log);
         // Registry freshness is published only after the graph and its metadata.
         // A failed close, swap, or metadata save must leave the previous registry
         // receipt intact, just as it leaves the cache unpublished.
@@ -4217,7 +4335,11 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
         // rethrow below is the surface, and the lock's sweep remains the backstop.
         if (useAtomicSwap && buildPath !== lbugPath) {
             try {
-                await wipeLbugDbFiles(buildPath);
+                const recovery = resolveEmbeddingRecovery(metaDir, (await loadMeta(metaDir))?.embeddingCheckpoint);
+                // Both paths belong to this locked slot. The validated generation
+                // basename identifies the same file even through a directory alias.
+                if (recovery?.stagingFile !== path.basename(buildPath))
+                    await wipeLbugDbFiles(buildPath);
             }
             catch {
                 /* swallow — orphan reclamation must never mask the real failure */
@@ -4230,6 +4352,10 @@ async function runFullAnalysisInner(repoPath, options, callbacks, writeTarget, c
             // IndexLockTimeoutError and other domain failures with `instanceof`.
             recordLiveIndexMutationRisk(err);
         }
+        if (/max(?:imum)?(?: database| db)? size|database size limit|maxDBSize/i.test(String(err))) {
+            log('The database size limit was reached. Set GITNEXUS_LBUG_MAX_DB_SIZE to a larger ' +
+                'byte limit before retrying analyze; retained complete embeddings can be reused.');
+        }
         throw err;
     }
 }

package/dist/mcp/local/aop-metadata.d.ts

@@ -72,6 +72,7 @@ export interface SpringAopMetadata {
  * shared decoder. Other DECLARES edges (for example Spring Bean factories)
  * and malformed/forward-version evidence are ignored. Query failures are
  * fail-soft because older or partially upgraded indexes must remain readable.
+ * Corrupt identities propagate to the context/impact integrity error boundary.
  */
 export declare function querySpringAopMetadata(lbugPath: string, symbolId: string, symbolType: string): Promise<SpringAopMetadata | undefined>;
 export {};