scriptoriumadmin/GitNexus
1
0
Fork 0
mirror of https://github.com/abhigyanpatwari/GitNexus.git synced 2026-10-11 03:38:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

Merge branch 'main' into docs/mcp-http-multi-client

Browse source
This commit is contained in:
Gergő Magyar 2026-10-04 10:52:31 +01:00 • committed by GitHub
commit 2f7bff0447
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
33 changed files with 5419 additions and 135 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

45
docker-server.test.mjs
View file

@ -331,8 +331,8 @@ const respondOk = (_req, res) => {
//
// upstream request handler, replaceable mid-test via `ctx.handler`;
// null points the proxy at a port nothing ever listens on
// listenAfterMs bind the upstream this late, so the first attempt(s) hit
// ECONNREFUSED (a single-instance restart window)
// listenAfterMs bind the upstream this late after the first refused attempt
// (a single-instance restart window)
// schemeless drop http:// from GITNEXUS_UPSTREAM_URL, the way Render's
// `fromService: { property: hostport }` yields it
// env extra environment for docker-server.mjs
@ -366,18 +366,15 @@ async function withProxy(
})
: null;
// A late (or never) bind needs its port reserved up front; otherwise let the
// OS assign one at listen time.
const upstreamPort =
server && listenAfterMs === 0
? await new Promise((r) => server.listen(0, '127.0.0.1', () => r(server.address().port)))
: await getFreePort();
const bindTimer =
server && listenAfterMs > 0
? setTimeout(() => server.listen(upstreamPort, '127.0.0.1'), listenAfterMs)
: null;
// Keep the upstream port bound until the proxy port is chosen. Releasing it
// sooner lets the OS assign both services the same port and proxy to itself.
const reservation = server ?? createServer();
const upstreamPort = await new Promise((r) =>
reservation.listen(0, '127.0.0.1', () => r(reservation.address().port)),
);
const port = await getFreePort();
let bindTimer = null;
const target = `127.0.0.1:${upstreamPort}`;
const proc = spawnServerWithEnv(dir, port, {
GITNEXUS_UPSTREAM_URL: schemeless ? target : `http://${target}`,
@ -390,18 +387,25 @@ async function withProxy(
...env,
});
proc.stderr.setEncoding('utf8');
proc.stderr.on('data', (chunk) => {
const collectStderr = (chunk) => {
ctx.stderr += chunk;
});
// Process startup must not consume the restart window or skip the retry.
if (server && listenAfterMs > 0 && !bindTimer && ctx.stderr.includes('ECONNREFUSED; retry')) {
bindTimer = setTimeout(() => server.listen(upstreamPort, '127.0.0.1'), listenAfterMs);
}
};
proc.stderr.on('data', collectStderr);
try {
await waitForServer(port);
if (!server || listenAfterMs > 0) await new Promise((r) => reservation.close(r));
await fn(port, ctx);
} finally {
proc.stderr.off('data', collectStderr);
if (bindTimer) clearTimeout(bindTimer);
await killAndWait(proc);
if (server?.listening) {
server.closeAllConnections?.();
await new Promise((r) => server.close(r));
if (reservation.listening) {
reservation.closeAllConnections?.();
await new Promise((r) => reservation.close(r));
}
await rm(dir, { recursive: true, force: true });
}
@ -661,8 +665,8 @@ it('returns 502 when the upstream is unreachable', async () => {
// -- Connection-retry across an upstream restart window ---------------------
//
// `listenAfterMs: 400` binds the upstream late, so the first attempt hits
// ECONNREFUSED and must be retried — a single-instance restart. The default 3
// `listenAfterMs: 400` binds the upstream 400ms after the first ECONNREFUSED,
// so the request must be retried — a single-instance restart. The default 3
// attempts (backoff 250ms, 500ms) span ~750ms, so a retry lands after the bind.
it('retries a connection-refused POST and succeeds once the upstream is up', async () => {
@ -676,6 +680,7 @@ it('retries a connection-refused POST and succeeds once the upstream is up', asy
assert.match(res.body, /"ok":true/);
assert.equal(ctx.calls, 1, 'upstream must run the job exactly once (no double-execute)');
assert.equal(ctx.body, '{"repo":"x"}', 'buffered body replayed intact');
assert.match(ctx.stderr, /ECONNREFUSED; retry/, 'the restart gap must exercise a retry');
});
});

18
gitnexus/src/cli/embeddings-sync.ts
View file

@ -4,7 +4,11 @@ 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,
@ -50,12 +54,22 @@ export const embeddingsSyncCommand = async (inputPath?: string): Promise<void> =
// 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.');
}

181
gitnexus/src/core/embeddings/staged-embedding-recovery-child.ts Normal file
View file

@ -0,0 +1,181 @@
/** 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';
import type { StagedEmbeddingExport } from './staged-embedding-recovery.js';
/** Native replay and close may checkpoint; only give them disposable copies. */
function copyRecoveryFamily(dbPath: string, exportDir: string): string {
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: fs.BigIntStats;
try {
entry = fs.lstatSync(sourcePath, { bigint: true });
} catch (error) {
if (suffix && (error as NodeJS.ErrnoException).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: number | undefined;
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(): Promise<void> {
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<string>();
let db: lbug.Database | undefined;
let conn: lbug.Connection | undefined;
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 as Record<string, unknown> & unknown[];
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 as ArrayLike<number>)
: 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: StagedEmbeddingExport = {
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: unknown) => {
process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
process.exitCode = 1;
});

244
gitnexus/src/core/embeddings/staged-embedding-recovery.ts Normal file
View file

@ -0,0 +1,244 @@
/** 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,
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[];
}
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: readonly CachedEmbeddingMeta[],
excludedNodeIds: ReadonlySet<string> = new Set(),
): Set<string> {
const groups = new Map<string, { hash: string; ordinals: Set<number>; invalid: boolean }>();
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<string>();
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: CachedEmbeddingsSnapshot,
recovered: CachedEmbeddingsSnapshot,
): CachedEmbeddingsSnapshot {
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: CachedEmbeddingsSnapshot,
rows: readonly CachedEmbeddingMeta[],
builder: ReturnType<typeof createCachedEmbeddingsBuilder>,
): void {
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 as unknown as Record<string, unknown>, 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: string,
options: StagedEmbeddingRecoveryOptions,
): Promise<CachedEmbeddingsSnapshot> {
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')) as StagedEmbeddingExport;
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: CachedEmbeddingsSnapshot = {
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 as unknown as Record<string, unknown>, true);
}
}
return finalizeCachedEmbeddingsSnapshot(builder);
} catch (err) {
abortCachedEmbeddingsBuilder(builder);
throw err;
} finally {
reader.close();
}
} finally {
fs.rmSync(exportDir, { recursive: true, force: true });
}
}
function runExtractionChild(
dbPath: string,
exportDir: string,
options: StagedEmbeddingRecoveryOptions,
): Promise<void> {
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: Buffer) => {
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()}` : ''}`,
),
);
});
});
}

162
gitnexus/src/core/run-analyze.ts
View file

@ -36,7 +36,12 @@ 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,
@ -1287,6 +1292,8 @@ export async function runFullAnalysis(
const log = (msg: string) => 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…'),
};
@ -1345,6 +1352,7 @@ export async function runFullAnalysis(
}
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,
@ -1842,7 +1850,13 @@ async function runFullAnalysisInner(
decision = decideEmbeddingResume(checkpoint, embeddingIdentityForRun, resumeOptions);
}
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.
@ -2671,6 +2685,74 @@ async function runFullAnalysisInner(
}
}
// 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: CachedEmbeddingsSnapshot | undefined;
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 as Error).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
@ -4487,6 +4569,16 @@ async function runFullAnalysisInner(
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: string[] = [];
let recoveryGenerationDurable = false;
// Build a Map<nodeId, contentHash> from cached embeddings for incremental mode
let existingEmbeddings: Map<string, string> | undefined;
if (cachedSnapshot.embeddingNodeIds.size > 0) {
@ -4540,6 +4632,14 @@ async function runFullAnalysisInner(
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` —
@ -4550,6 +4650,11 @@ async function runFullAnalysisInner(
lastCommit: '',
indexedAt: new Date().toISOString(),
};
const interrupted = mintInterruptedCheckpoint(
embeddingIdentity,
checkpoint,
pendingNodeIds,
);
await saveMeta(metaDir, {
...base,
...(embeddings === undefined || buildPath !== lbugPath
@ -4557,11 +4662,18 @@ async function runFullAnalysisInner(
: { 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],
},
}
: {}),
},
});
};
@ -4584,7 +4696,21 @@ async function runFullAnalysisInner(
{
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
@ -4598,7 +4724,12 @@ async function runFullAnalysisInner(
// 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(
@ -5085,6 +5216,7 @@ async function runFullAnalysisInner(
// 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
@ -5294,7 +5426,13 @@ async function runFullAnalysisInner(
// 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 */
}
@ -5306,6 +5444,12 @@ async function runFullAnalysisInner(
// 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;
}
}

27
gitnexus/src/mcp/local/aop-metadata.ts
View file

@ -1,4 +1,9 @@
import { executeParameterized } from '../../core/lbug/pool-adapter.js';
import {
assertSymbolIdentity,
assertIdentityFields,
rethrowSymbolIdentityError,
} from './query-result-integrity.js';
import {
decodeSpringAopReason,
type SpringAopReason,
@ -151,6 +156,7 @@ const DETERMINISTIC_RELATIONSHIP_ORDER = 'ORDER BY sourceId, targetId, reason, s
* 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 async function querySpringAopMetadata(
lbugPath: string,
@ -204,6 +210,24 @@ export async function querySpringAopMetadata(
),
]);
for (const rows of [
outgoingAdviceRows,
incomingAdviceRows,
outgoingPointcutRows,
incomingPointcutRows,
]) {
for (const row of rows) {
assertSymbolIdentity(readRowValue(row, 'sourceId', 0));
assertSymbolIdentity(readRowValue(row, 'targetId', 3));
assertIdentityFields(
readRowValue(row, 'sourceName', 1),
readRowValue(row, 'sourceFilePath', 2),
readRowValue(row, 'targetName', 4),
readRowValue(row, 'targetFilePath', 5),
);
}
}
const behaviors: SpringAopBehaviorMetadata[] = [];
const advices: SpringAopAdviceMetadata[] = [];
const resolvedPointcuts: SpringAopResolvedPointcutMetadata[] = [];
@ -346,7 +370,8 @@ export async function querySpringAopMetadata(
resolvedPointcuts: dedupedResolvedPointcuts,
unresolvedPointcuts: dedupedPointcuts,
};
} catch {
} catch (error) {
rethrowSymbolIdentityError(error);
return undefined;
}
}

222
gitnexus/src/mcp/local/local-backend.ts
View file

@ -28,6 +28,15 @@ import {
} from '../../core/lbug/pool-adapter.js';
import { queryClassBeanMetadata } from './bean-metadata.js';
import { querySpringAopMetadata } from './aop-metadata.js';
import {
SYMBOL_IDENTITY_RECOVERY_SUGGESTION,
SymbolIdentityError,
assertSymbolIdentity,
queryRowValue,
assertIdentityFields,
assertQueryIdentity,
rethrowSymbolIdentityError,
} from './query-result-integrity.js';
import { queryConvexDispatchMetadata } from './convex-metadata.js';
import { isValidQueryParams } from '../../core/lbug/query-params.js';
import { toDisplayLine } from './line-display.js';
@ -324,25 +333,67 @@ function nonBlankUid(value: unknown): string | undefined {
return typeof value === 'string' ? value.trim() || undefined : undefined;
}
const SYMBOL_IDENTITY_RECOVERY_SUGGESTION =
'Run gitnexus analyze --force from the affected repository root to rebuild the index.';
function assertSymbolRowIdentity(row: unknown): void {
assertQueryIdentity(row, 'id', 0, [
['name', 1],
['type', 2],
['filePath', 3],
]);
}
class SymbolIdentityError extends Error {
constructor() {
super('The index returned an invalid symbol identity. ' + SYMBOL_IDENTITY_RECOVERY_SUGGESTION);
this.name = 'SymbolIdentityError';
function assertContextRefs(rows: unknown[]): void {
for (const row of rows) {
assertQueryIdentity(row, 'uid', 1, [
['name', 2],
['filePath', 3],
['kind', 4],
]);
assertSymbolIdentity(queryRowValue(row, 'relType', 0));
}
}
/** Validate database identities before using them as graph traversal anchors. */
function assertSymbolIdentity(id: unknown, expectedUid?: string): asserts id is string {
if (
typeof id !== 'string' ||
!id.trim() ||
id.includes('\0') ||
(expectedUid !== undefined && id !== expectedUid)
) {
throw new SymbolIdentityError();
const RESPONSE_IDENTITY_FIELDS = new Set([
'id',
'uid',
'name',
'filePath',
'label',
'kind',
'type',
'relationType',
'processType',
'url',
'method',
'sourceId',
'targetId',
'symbolId',
'symbolName',
'symbolFilePath',
'adviceId',
'adviceName',
'adviceFilePath',
'advisedId',
'advisedName',
'advisedFilePath',
'evidenceId',
]);
/** Cover nested additive identity fields while leaving source/metadata text alone. */
function assertResponseIdentities(value: unknown): void {
if (Array.isArray(value)) {
for (const item of value) assertResponseIdentities(item);
} else if (value !== null && typeof value === 'object') {
for (const [key, field] of Object.entries(value)) {
if (key === 'seedBlocks' || key === 'reachableBlocks' || key === 'intraReachableBlocks') {
if (!Array.isArray(field)) throw new SymbolIdentityError();
for (const id of field) assertSymbolIdentity(id);
continue;
}
if (RESPONSE_IDENTITY_FIELDS.has(key)) assertIdentityFields(field);
if (key !== 'content' && key !== 'methodMetadata' && key !== 'bean') {
assertResponseIdentities(field);
}
}
}
}
@ -4393,9 +4444,10 @@ export class LocalBackend {
* "unknown kind" and, worse, makes the `kind` disambiguation hint unable to
* filter it out (#2687).
*
* Failures are swallowed: label enrichment is an optimisation for
* Ordinary query failures are swallowed: label enrichment is an optimisation for
* downstream scoring and #480 Class/Interface BFS seeding; if it fails
* the symbol still resolves, just without the kind-priority bonus.
* Corrupt identities propagate to the context/impact error envelope.
*/
private async enrichCandidateLabels(
repo: RepoHandle,
@ -4429,6 +4481,7 @@ export class LocalBackend {
);
const labelById = new Map<string, string>();
for (const r of rows as any[]) {
assertQueryIdentity(r, 'id', 0, [['label', 1]]);
const id = (r.id ?? r[0]) as string;
const label = (r.label ?? r[1]) as string;
if (id && label && !labelById.has(id)) labelById.set(id, label);
@ -4436,7 +4489,8 @@ export class LocalBackend {
for (const c of candidates) {
if (c.type === '' && labelById.has(c.id)) c.type = labelById.get(c.id) as string;
}
} catch {
} catch (error) {
rethrowSymbolIdentityError(error);
/* best-effort — downstream resolvers still work without the label */
}
}
@ -4561,6 +4615,7 @@ export class LocalBackend {
{ uid },
);
if (rows.length === 0) return { kind: 'not_found' };
assertSymbolRowIdentity(rows[0]);
const r = rows[0] as any;
const symbol = {
id: (r.id ?? r[0]) as string,
@ -4695,6 +4750,10 @@ export class LocalBackend {
if (rows.length === 0) return { kind: 'not_found' };
// Reject every raw candidate before narrowing/scoring can hide a corrupt row.
for (const row of rows) {
assertSymbolRowIdentity(row);
}
// Normalise row shape across object / tuple returns from LadybugDB.
let normalized = rows.map((r: any) => ({
id: (r.id ?? r[0]) as string,
@ -4705,10 +4764,6 @@ export class LocalBackend {
endLine: (r.endLine ?? r[5]) as number,
...(include_content ? { content: (r.content ?? r[6]) as string | undefined } : {}),
}));
// Reject the whole result before narrowing or scoring: dropping a corrupt
// candidate could make an unrelated surviving symbol look unambiguous.
for (const candidate of normalized) assertSymbolIdentity(candidate.id);
// An exact File path wins over anchored suffix candidates. Without this,
// `lib/a.ts` and `src/lib/a.ts` both score as File candidates and turn an
// otherwise unambiguous exact target into `ambiguous` (#3084 review P2).
@ -4858,7 +4913,9 @@ export class LocalBackend {
},
): Promise<any> {
try {
return await this._contextImpl(repo, params);
const result = await this._contextImpl(repo, params);
if (!result.error) assertResponseIdentities(result);
return result;
} catch (err: any) {
const msg = (err instanceof Error ? err.message : String(err)) || 'Context query failed';
if (err instanceof SymbolIdentityError) {
@ -4978,6 +5035,8 @@ export class LocalBackend {
{ symId },
),
]);
assertContextRefs(incomingRows);
assertContextRefs(incomingAdvisedRows);
incomingRows.push(...incomingAdvisedRows);
let typedPropertyRows: any[] = [];
@ -5082,6 +5141,16 @@ export class LocalBackend {
},
),
]);
assertContextRefs(ctorIncoming);
assertContextRefs(fileIncoming);
assertContextRefs(typedPropertyIncoming);
for (const row of typedProperties) {
assertQueryIdentity(row, 'uid', 0, [
['name', 1],
['filePath', 2],
['kind', 3],
]);
}
typedPropertyRows = typedProperties;
// Deduplicate by (relType, uid) — a caller can have multiple relation
@ -5098,6 +5167,7 @@ export class LocalBackend {
}
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('context:class-incoming-expansion', e);
}
}
@ -5128,6 +5198,8 @@ export class LocalBackend {
{ symId },
),
]);
assertContextRefs(outgoingRows);
assertContextRefs(outgoingAdvisedRows);
outgoingRows.push(...outgoingAdvisedRows);
// Process participation.
@ -5151,7 +5223,14 @@ export class LocalBackend {
`,
{ symId },
);
for (const row of processRows) {
assertQueryIdentity(row, 'pid', 0, [
['label', 1],
['entryPointId', 4],
]);
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('context:process-participation', e);
}
@ -5188,6 +5267,7 @@ export class LocalBackend {
// (GET/POST pair). URL-only dedup would drop the second endpoint.
const seenRoutes = new Set<string>();
for (const r of routeRows) {
assertIdentityFields(queryRowValue(r, 'url', 0), queryRowValue(r, 'method', 1));
const url = r.url ?? r[0];
const method = r.method ?? r[1];
const dedupKey = routeEnrichmentKey(method ? String(method) : undefined, url);
@ -5197,7 +5277,8 @@ export class LocalBackend {
}
}
} catch (e) {
// Best-effort enrichment — never fail the context call.
rethrowSymbolIdentityError(e);
// Ordinary query failures leave this best-effort enrichment unavailable.
logQueryError('context:route-lookup', e);
}
@ -5247,6 +5328,7 @@ export class LocalBackend {
);
const beanMetadataPromise = queryClassBeanMetadata(repo.lbugPath, symId, epistemicSymType);
const aopMetadataPromise = querySpringAopMetadata(repo.lbugPath, symId, epistemicSymType);
void aopMetadataPromise.catch(() => undefined);
// R3-1. A `Property` whose name the analyzer declined to link — because
// every definition of it lives in another language — otherwise returns an
@ -5341,6 +5423,7 @@ export class LocalBackend {
try {
chain = await this._computeContextChain(repo, symId, requestedDepth);
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('context:chain-bfs', e);
}
}
@ -5381,8 +5464,8 @@ export class LocalBackend {
processes: processRows.map((r: any) => ({
id: r.pid || r[0],
name: r.label || r[1],
step_index: r.step || r[2],
step_count: r.stepCount || r[3],
step_index: r.step ?? r[2],
step_count: r.stepCount ?? r[3],
})),
};
}
@ -5463,6 +5546,13 @@ export class LocalBackend {
visited: Array.from(visited),
});
if (rows.length === 0) return { nextFrontier: [] };
for (const row of rows) {
assertQueryIdentity(row, 'uid', 0, [
['name', 1],
['filePath', 2],
['kind', 3],
]);
}
// MATCH is one row per CALLS edge. Cypher `WITH DISTINCT` applies
// LIMIT 50 to unique neighbors; this second pass still collapses
// twins if a driver/engine ever returns duplicate rows.
@ -5482,6 +5572,7 @@ export class LocalBackend {
for (const r of fresh) visited.add(r.uid);
return { nodes, nextFrontier: fresh.map((r: any) => r.uid) };
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError(logLabel, e);
return { nextFrontier: [] };
}
@ -7163,7 +7254,9 @@ export class LocalBackend {
private async impact(repo: RepoHandle, params: ImpactParams): Promise<any> {
try {
return await this._impactImpl(repo, params);
const result = await this._impactImpl(repo, params);
if (!result.error) assertResponseIdentities(result);
return result;
} catch (err: any) {
// Return structured error instead of crashing (#321)
const message =
@ -7481,6 +7574,7 @@ export class LocalBackend {
} catch (e) {
probeFailed = true;
candidateProbeFailed = true;
rethrowSymbolIdentityError(e);
logQueryError('impact:ambiguous-candidate', e);
}
return {
@ -7738,6 +7832,7 @@ export class LocalBackend {
});
return composeUnifiedPdgImpactResult(pdgResult, interproceduralResult);
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:pdg-interprocedural-reach', e);
return composeUnifiedPdgImpactResult(pdgResult, null, e);
}
@ -7775,10 +7870,12 @@ export class LocalBackend {
{ ids: blockIds },
);
for (const r of rows as any[]) {
assertIdentityFields(r.callees ?? r[0]);
const raw = String(r.callees ?? r[0] ?? '');
for (const n of raw.split(' ')) if (n) names.add(n);
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:pdg-slice-callees', e);
}
return names;
@ -7814,6 +7911,7 @@ export class LocalBackend {
for (const id of splitCalleeIds(r.calleeIds ?? r[0])) ids.add(id);
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:pdg-slice-callee-ids', e);
}
return ids;
@ -7967,7 +8065,10 @@ export class LocalBackend {
ORDER BY id
LIMIT 25`,
{ symId, heritage: HERITAGE_TYPES },
).catch(() => []);
).catch((error) => {
rethrowSymbolIdentityError(error);
return [];
});
const undecidedSummary = meta?.undecidedInterfaceSatisfaction;
const undecidedDrops =
undecidedSummary === undefined
@ -8006,6 +8107,10 @@ export class LocalBackend {
}
const ifaceRows = await interfaceRowsPromise;
for (const r of ifaceRows) {
assertQueryIdentity(r, 'id', 0, [
['name', 1],
['label', 2],
]);
const id = (r.id ?? r[0]) as string;
if (id && !boundary.has(id)) {
boundary.set(id, {
@ -8031,7 +8136,10 @@ export class LocalBackend {
WHERE iface.id = $ifaceId AND r.type IN $types
RETURN COUNT(DISTINCT other.id) AS cnt`,
{ ifaceId, types },
).catch(() => []);
).catch((error) => {
rethrowSymbolIdentityError(error);
return [];
});
const cnt =
rows.length > 0 ? Number((rows[0] as any).cnt ?? (rows[0] as any)[0] ?? 0) : 0;
m.set(ifaceId, cnt);
@ -8090,7 +8198,8 @@ export class LocalBackend {
callableValueReferences: droppedBoundaries.callableValueReferences,
},
};
} catch {
} catch (error) {
rethrowSymbolIdentityError(error);
// Never let the heritage probe's failure suppress a drop we already know
// about — the whole point is that silence must not read as certainty.
return epistemicFrom(droppedBoundaries);
@ -8182,6 +8291,7 @@ export class LocalBackend {
`Impact target '${sym.name || sym[1] || '?'}' resolved without a node id; refusing to report a blast radius`,
);
}
assertSymbolRowIdentity(sym);
// #1858 — kick off the epistemic boundary probe concurrently with the BFS.
// It depends only on symId/symType/symName (all known now) and touches no
@ -8217,6 +8327,7 @@ export class LocalBackend {
opts.skipEpistemic || summaryOnly
? Promise.resolve(undefined)
: querySpringAopMetadata(repo.lbugPath, symId, symType);
void aopMetadataPromise.catch(() => undefined);
const impacted: any[] = [];
const visited = new Set<string>([symId]);
const pdgBridgeEvidenceById = new Map<string, PdgBridgeEvidenceInfo>();
@ -8261,6 +8372,7 @@ export class LocalBackend {
]);
for (const r of ctorRows) {
assertSymbolRowIdentity(r);
const rid = r.id || r[0];
if (rid && !visited.has(rid)) {
visited.add(rid);
@ -8268,6 +8380,7 @@ export class LocalBackend {
}
}
for (const r of fileRows) {
assertSymbolRowIdentity(r);
const rid = r.id || r[0];
if (rid && !visited.has(rid)) {
visited.add(rid);
@ -8292,6 +8405,7 @@ export class LocalBackend {
);
for (const r of typedPropertyRows) {
assertSymbolRowIdentity(r);
const rid = r.id || r[0];
if (rid && !visited.has(rid)) {
visited.add(rid);
@ -8299,6 +8413,7 @@ export class LocalBackend {
}
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:class-node-expansion', e);
traversalComplete = false;
}
@ -8336,6 +8451,9 @@ export class LocalBackend {
`,
{ symId },
);
for (const row of memberRows) {
assertSymbolRowIdentity(row);
}
memberRows.sort((a, b) => compareCodeUnits(String(a.id ?? a[0]), String(b.id ?? b[0])));
if (memberRows.length > OBJECT_CALLABLE_MEMBER_CAP) traversalComplete = false;
for (const row of memberRows.slice(0, OBJECT_CALLABLE_MEMBER_CAP)) {
@ -8355,6 +8473,7 @@ export class LocalBackend {
}
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:object-callable-expansion', e);
traversalComplete = false;
}
@ -8411,6 +8530,17 @@ export class LocalBackend {
relTypes: relationTypes,
...(safeMinConfidence > 0 ? { minConfidence: safeMinConfidence } : {}),
});
// Validate before filtering/deduplication; a discarded corrupt edge is
// still evidence that this result's counts cannot be trusted.
for (const row of related) {
assertQueryIdentity(row, 'id', 1, [
['sourceId', 0],
['name', 2],
['type', 3],
['filePath', 4],
]);
assertSymbolIdentity(queryRowValue(row, 'relType', 5));
}
const edges: ImpactFrontierEdge[] = related.map((rel) => ({
id: rel.id || rel[1],
@ -8510,6 +8640,7 @@ export class LocalBackend {
});
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:depth-traversal', e);
// Break out of depth loop on query failure but return partial results
// collected so far, rather than silently swallowing the error (#321)
@ -8635,6 +8766,7 @@ export class LocalBackend {
`,
{ ids },
).catch((err) => {
rethrowSymbolIdentityError(err);
processQueryFailed = true;
enrichmentDegraded = true;
logQueryError('impact:process-chunk', err);
@ -8642,6 +8774,14 @@ export class LocalBackend {
});
for (const row of rows) {
assertQueryIdentity(row, 'pId', 0, [
['name', 1],
['processType', 2],
['entryPointId', 3],
['epName', 7],
['epType', 8],
['epFilePath', 9],
]);
const pId = row.pId ?? row[0];
const epId = row.entryPointId ?? row[3] ?? row.pId ?? row[0];
// Track mapping from process -> entryPoint so we can backfill missing minStep
@ -8690,6 +8830,7 @@ export class LocalBackend {
ep.earliest_broken_step = Math.min(ep.earliest_broken_step, minStep ?? Infinity);
}
} catch (e) {
rethrowSymbolIdentityError(e);
processQueryFailed = true;
enrichmentDegraded = true;
logQueryError('impact:process-chunk', e);
@ -8712,12 +8853,14 @@ export class LocalBackend {
`,
{ pIds, ids: allImpactedIds },
).catch((err) => {
rethrowSymbolIdentityError(err);
enrichmentDegraded = true;
logQueryError('impact:process-chunk-backfill', err);
return [];
});
for (const mr of missingRows) {
assertQueryIdentity(mr, 'pid', 0, []);
const pid = mr.pid ?? mr[0];
const minStep = mr.minStep ?? mr[1];
const epId = processToEntryPoint.get(String(pid));
@ -8729,6 +8872,7 @@ export class LocalBackend {
}
}
} catch (e) {
rethrowSymbolIdentityError(e);
enrichmentDegraded = true;
logQueryError('impact:process-chunk-backfill', e);
}
@ -8791,6 +8935,7 @@ export class LocalBackend {
`,
{ ids: idsChunk },
).catch((err) => {
rethrowSymbolIdentityError(err);
moduleQueryFailed = true;
enrichmentDegraded = true;
logQueryError('impact:module-chunk', err);
@ -8798,12 +8943,14 @@ export class LocalBackend {
});
for (const r of rows) {
assertIdentityFields(queryRowValue(r, 'name', 0));
const name = r.name ?? r[0] ?? null;
const hits = (r.hits ?? r[1]) || 0;
if (!name) continue;
moduleHitsMap.set(name, (moduleHitsMap.get(name) || 0) + hits);
}
} catch (e) {
rethrowSymbolIdentityError(e);
moduleQueryFailed = true;
enrichmentDegraded = true;
logQueryError('impact:module-chunk', e);
@ -8832,16 +8979,19 @@ export class LocalBackend {
`,
{ ids: idsChunk },
).catch((err) => {
rethrowSymbolIdentityError(err);
enrichmentDegraded = true;
moduleClassificationFailed = true;
logQueryError('impact:direct-module-chunk', err);
return [];
});
for (const r of rows) {
assertIdentityFields(queryRowValue(r, 'name', 0));
const name = r.name ?? r[0] ?? null;
if (name) directModuleSet.add(name);
}
} catch (e) {
rethrowSymbolIdentityError(e);
enrichmentDegraded = true;
moduleClassificationFailed = true;
logQueryError('impact:direct-module-chunk', e);
@ -8903,11 +9053,14 @@ export class LocalBackend {
`,
{ ids: chunkIds },
).catch((err) => {
rethrowSymbolIdentityError(err);
enrichmentDegraded = true;
logQueryError('impact:route-chunk', err);
return [];
});
for (const row of rows) {
assertSymbolIdentity(queryRowValue(row, 'hid', 0));
assertIdentityFields(queryRowValue(row, 'url', 1), queryRowValue(row, 'method', 2));
const hid = String(row.hid ?? row[0] ?? '');
const url = row.url ?? row[1];
if (!hid || typeof url !== 'string') continue;
@ -9064,8 +9217,16 @@ export class LocalBackend {
p.processType AS pType, MIN(r.step) AS step
`,
{ ids: chunkIds },
).catch(() => []);
).catch((err) => {
rethrowSymbolIdentityError(err);
return [];
});
for (const row of rows) {
assertQueryIdentity(row, 'sid', 0, []);
assertQueryIdentity(row, 'pid', 1, [
['pName', 2],
['pType', 3],
]);
const sid = row.sid ?? row[0];
if (!sid) continue;
const procEntry = {
@ -9079,6 +9240,7 @@ export class LocalBackend {
else perSymbolProcesses.set(String(sid), [procEntry]);
}
} catch (e) {
rethrowSymbolIdentityError(e);
logQueryError('impact:per-symbol-process-chunk', e);
}
}

27
gitnexus/src/mcp/local/pdg-impact.ts
View file

@ -27,6 +27,11 @@ import { toDisplayLine } from './line-display.js';
import { toOneBasedLine } from '../../core/ingestion/utils/line-base.js';
import { decodeCallSummary } from '../../core/ingestion/taint/call-summary-codec.js';
import { decodeReachingDefReason } from '../../core/ingestion/cfg/reaching-def-reason-codec.js';
import {
assertSymbolIdentity,
assertIdentityFields,
assertQueryIdentity,
} from './query-result-integrity.js';
/**
* Parse the `<fnLine>` segment out of a `BasicBlock` id (1-based function start
@ -90,14 +95,19 @@ const INTERPROC_NODE_BUDGET = 5000;
* `classifyPdgBridgeEvidence`); this is the same fact, read at the descent side.
*/
function parseCalleeIdsCell(raw: unknown): { ids: string[]; truncated: boolean } {
assertIdentityFields(raw);
const ids: string[] = [];
let truncated = false;
if (!String(raw ?? '').trim()) return { ids, truncated };
// Split on the SHARED CALLEE_ID_SEP (tab) — ids embed file paths / multi-word
// C++ type tokens that can contain a space, so a space split would fragment
// them. Producer (calleeIdsOfBlock) joins with the same constant.
for (const id of String(raw ?? '').split(CALLEE_ID_SEP)) {
if (id === CALLEES_TRUNCATED_SENTINEL) truncated = true;
else if (id) ids.push(id);
else {
assertSymbolIdentity(id);
ids.push(id);
}
}
return { ids, truncated };
}
@ -218,6 +228,7 @@ async function selfReachingDefEdgesByBlock(
{ ids: blockIds },
);
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0);
const id = String(r['id'] ?? '');
if (!id) continue;
const decoded = decodeReachingDefReason(r['reason']);
@ -297,6 +308,7 @@ async function pdgStatementsForBlocks(
// Narrow the awaited rows ONCE at the boundary to a typed record shape; read
// the aliased cells via bracket access with String()/Number() coercion.
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0);
const id = String(r['id'] ?? '');
const line = Number(r['line'] ?? 0);
if (!id || !Number.isFinite(line) || line <= 0) continue;
@ -501,6 +513,10 @@ async function projectBlocksToSymbols(deps: {
// non-aliased row shape) — no per-field `as any`, matching the typed-row
// pattern used elsewhere in this file (e.g. lines ~264, ~1309, ~1386).
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0, [
['name', 1],
['label', 2],
]);
resolved.push({
id: String(r['id'] ?? r['0'] ?? ''),
name: String(r['name'] ?? r['1'] ?? ''),
@ -1718,6 +1734,7 @@ async function bfsReachableBlocks(input: {
// Narrow the awaited rows ONCE at the boundary (executeParameterized returns
// any[]) to a typed record shape, then read the aliased `id` via bracket
// access — no `as any` sprayed per field.
for (const row of rawRows) assertQueryIdentity(row, 'id', 0);
const rows = rawRows.slice(0, stepLimit) as Array<Record<string, unknown>>;
depthReached = depth + 1;
if (rawRows.length > stepLimit) truncatedByLimit = true;
@ -1796,6 +1813,10 @@ async function calleeIdsByBlock(
// Narrow the awaited rows ONCE at the boundary to a typed record shape; read
// the aliased cells via bracket access — no per-field `as any`.
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0, [
['calleeIds', 1],
['callees', 2],
]);
const blockId = String(r['id'] ?? '');
if (!blockId) continue;
// ONE pass over the cell classifies BOTH facts — a second full split just to
@ -1877,6 +1898,7 @@ async function calleesWithReturnFlow(
{ ids: calleeIds },
);
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0);
const id = String(r['id'] ?? '');
if (!id) continue;
const decoded = decodeCallSummary(r['reason']);
@ -1931,6 +1953,7 @@ async function resolveCalleeSpans(
// the aliased columns via bracket access with Number()/String() coercion —
// no per-field `as any` (the same boundary-narrowing the typed helpers use).
for (const r of rows as Array<Record<string, unknown>>) {
assertQueryIdentity(r, 'id', 0, [['filePath', 1]]);
const id = String(r['id'] ?? '');
const filePath = String(r['filePath'] ?? '');
const startLine = Number(r['startLine']);
@ -2168,6 +2191,7 @@ async function interproceduralDescent(input: {
seedBlockQuery(anchorClause, probeLimit),
queryParams,
);
for (const row of rawSeedRows) assertQueryIdentity(row, 'id', 0);
const exceeded = rawSeedRows.length > stepLimit;
const seeds = rawSeedRows
.slice(0, stepLimit)
@ -2353,6 +2377,7 @@ export async function runImpactPDG(deps: RunPdgImpactDeps): Promise<PdgImpactRes
seedBlockQuery(anchorClause, probeLimit),
queryParams,
);
for (const row of rawSeedRows) assertQueryIdentity(row, 'id', 0);
const seedRows = rawSeedRows.slice(0, stepLimit) as Array<Record<string, unknown>>;
let seedBlocks: string[] = seedRows
.map((r) => String(r['id'] ?? ''))

57
gitnexus/src/mcp/local/query-result-integrity.ts Normal file
View file

@ -0,0 +1,57 @@
/** Shared integrity boundary for identities returned by impact/context queries. */
export const SYMBOL_IDENTITY_RECOVERY_SUGGESTION =
'Run gitnexus analyze --force from the affected repository root to rebuild the index.';
export class SymbolIdentityError extends Error {
constructor() {
super('The index returned an invalid symbol identity. ' + SYMBOL_IDENTITY_RECOVERY_SUGGESTION);
this.name = 'SymbolIdentityError';
}
}
/** Validate database identities before using them as graph traversal anchors. */
export function assertSymbolIdentity(id: unknown, expectedUid?: string): asserts id is string {
if (
typeof id !== 'string' ||
!id.trim() ||
id.includes('\0') ||
(expectedUid !== undefined && id !== expectedUid)
) {
throw new SymbolIdentityError();
}
}
/** Read either native row shape without turning an absent row into a TypeError. */
export function queryRowValue(row: unknown, key: string, index: number): unknown {
if (typeof row !== 'object' || row === null) return undefined;
const value = row as Record<string, unknown>;
return value[key] ?? value[index];
}
/** Optional labels/paths may be empty or NULL; NUL is never a usable identity. */
export function assertIdentityFields(...values: unknown[]): void {
for (const value of values) {
if (
value !== null &&
value !== undefined &&
(typeof value !== 'string' || value.includes('\0'))
) {
throw new SymbolIdentityError();
}
}
}
export function assertQueryIdentity(
row: unknown,
idKey: string,
idIndex: number,
fields: ReadonlyArray<readonly [string, number]> = [],
): void {
assertSymbolIdentity(queryRowValue(row, idKey, idIndex));
for (const [key, index] of fields) assertIdentityFields(queryRowValue(row, key, index));
}
/** Ordinary query failures may degrade; corrupt identities must reach the outer error envelope. */
export function rethrowSymbolIdentityError(error: unknown): void {
if (error instanceof SymbolIdentityError) throw error;
}

13
gitnexus/src/server/api.ts
View file

@ -12,6 +12,7 @@ import {
acquireIndexLock,
IndexLockTimeoutError,
requireExclusiveIndexLock,
sweepStagingArtifacts,
type IndexLockHandle,
} from '../storage/index-lock.js';
import { ensurePrivateSharedGraph } from '../core/shared-store-analyze.js';
@ -2152,11 +2153,21 @@ export const createServer = async (port: number, host: string = '127.0.0.1') =>
// for the whole embedding write, released in the finally below.
let slotLock: IndexLockHandle | undefined;
try {
slotLock = await acquireIndexLock(storagePath);
slotLock = await acquireIndexLock(storagePath, { sweep: false });
requireExclusiveIndexLock(
slotLock,
`Cannot acquire the index lock at ${storagePath}; refusing an unlocked embedding run.`,
);
// This writer cannot recover staged generations. Preserve their
// receipts, including malformed ones, before sweeping or writing.
const recoveryCheckpoint = (await loadMeta(storagePath))?.embeddingCheckpoint;
if (recoveryCheckpoint && Object.hasOwn(recoveryCheckpoint, 'recovery')) {
throw new Error(
'Cannot generate embeddings: the index checkpoint references staged embeddings. ' +
'Run `gitnexus analyze` to recover them first.',
);
}
sweepStagingArtifacts(storagePath);
// Writes go to the slot's own graph; a shared-store checkout
// reading an immutable commit graph (#3352) takes a private copy.
if (!(await ensurePrivateSharedGraph(storagePath, () => {}))) {

167
gitnexus/src/storage/embedding-recovery.ts Normal file
View file

@ -0,0 +1,167 @@
/**
* Filesystem-only staged embedding provenance. Keep this independent of native
* and model imports: every index-lock caller needs the retention decision.
*/
import {
closeSync,
constants,
fstatSync,
lstatSync,
openSync,
readFileSync,
realpathSync,
} from 'node:fs';
import path from 'node:path';
import type { EmbeddingRecoveryReference } from './repo-meta.js';
import { INDEX_METADATA_FILE, LEGACY_METADATA_FILE } from './storage-constants.js';
const STAGING_FILENAME =
/^lbug\.staging\.[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
export const FAMILY_SUFFIXES = [
'',
'.wal',
'.shadow',
'.wal.checkpoint',
'.lock',
'.checkpoint.intent.lock',
'.checkpoint.apply.lock',
] as const;
export interface ResolvedEmbeddingRecovery extends EmbeddingRecoveryReference {
dbPath: string;
/** Exact basenames, never a prefix match that can preserve another generation. */
familyFiles: string[];
}
const isRecord = (value: unknown): value is Record<string, unknown> =>
value !== null && typeof value === 'object' && !Array.isArray(value);
const isNonemptyString = (value: unknown): value is string =>
typeof value === 'string' && value.length > 0;
const isNodeIds = (value: unknown): value is string[] =>
Array.isArray(value) && value.every(isNonemptyString);
const isCount = (value: unknown): value is number =>
typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
/**
* Resolve only an explicit interrupted-generation receipt in this canonical
* slot. This validates provenance, not native contents or current identity;
* those checks must pass separately before any rows can be reused.
*/
export const resolveEmbeddingRecovery = (
lockDir: string,
checkpoint: unknown,
): ResolvedEmbeddingRecovery | undefined => {
if (!isRecord(checkpoint) || !isRecord(checkpoint.recovery)) return undefined;
if (checkpoint.kind !== undefined && checkpoint.kind !== 'interrupted') return undefined;
if (
!isNonemptyString(checkpoint.at) ||
!Number.isFinite(Date.parse(checkpoint.at)) ||
!isCount(checkpoint.nodesProcessed) ||
!isCount(checkpoint.totalNodes) ||
checkpoint.nodesProcessed > checkpoint.totalNodes ||
!isCount(checkpoint.chunksProcessed) ||
!isNonemptyString(checkpoint.model) ||
!isCount(checkpoint.dimensions) ||
checkpoint.dimensions === 0 ||
!isNonemptyString(checkpoint.provider) ||
(checkpoint.pendingNodeIds !== undefined && !isNodeIds(checkpoint.pendingNodeIds))
) {
return undefined;
}
const recovery = checkpoint.recovery;
if (
!isNonemptyString(recovery.stagingFile) ||
!STAGING_FILENAME.test(recovery.stagingFile) ||
!isNonemptyString(recovery.schemaFingerprint) ||
!isNodeIds(recovery.unsafeNodeIds)
) {
return undefined;
}
const unsafeNodeIds = new Set(recovery.unsafeNodeIds);
if (
isNodeIds(checkpoint.pendingNodeIds) &&
checkpoint.pendingNodeIds.some((nodeId) => !unsafeNodeIds.has(nodeId))
) {
return undefined;
}
try {
const canonicalDir = realpathSync(lockDir);
if (!lstatSync(canonicalDir).isDirectory()) return undefined;
const familyFiles = FAMILY_SUFFIXES.map((suffix) => recovery.stagingFile + suffix);
for (const [index, filename] of familyFiles.entries()) {
try {
// lstat refuses both live and dangling symlinks, without following one
// to a database outside the slot. The base file must exist.
if (!lstatSync(path.join(canonicalDir, filename)).isFile()) return undefined;
} catch (error) {
if (index > 0 && (error as NodeJS.ErrnoException).code === 'ENOENT') continue;
return undefined;
}
}
return {
dbPath: path.join(canonicalDir, recovery.stagingFile),
stagingFile: recovery.stagingFile,
schemaFingerprint: recovery.schemaFingerprint,
unsafeNodeIds: [...unsafeNodeIds],
familyFiles,
};
} catch {
return undefined;
}
};
/** Synchronous mirror of loadMeta's primary-first, absent-only fallback rule. */
export const readEmbeddingRecovery = (lockDir: string): ResolvedEmbeddingRecovery | undefined => {
let metadataPath = path.join(lockDir, INDEX_METADATA_FILE);
let descriptor: number | undefined;
const noFollow = constants.O_NOFOLLOW ?? 0;
const flags = constants.O_RDONLY | noFollow | (constants.O_NONBLOCK ?? 0);
try {
try {
descriptor = openSync(metadataPath, flags);
} catch (error) {
const code = (error as NodeJS.ErrnoException).code;
if (code !== 'ENOENT' && code !== 'ENOTDIR') return undefined;
// Windows cannot open with O_NOFOLLOW: an open of a dangling symlink
// reports ENOENT, but that existing primary entry must prevent fallback.
try {
lstatSync(metadataPath);
return undefined;
} catch (statError) {
const statCode = (statError as NodeJS.ErrnoException).code;
if (statCode !== 'ENOENT' && statCode !== 'ENOTDIR') return undefined;
}
metadataPath = path.join(lockDir, LEGACY_METADATA_FILE);
descriptor = openSync(metadataPath, flags);
}
const opened = fstatSync(descriptor, { bigint: true });
const entry = lstatSync(metadataPath, { bigint: true });
// Check the opened file itself and match the current non-symlink entry.
// This also refuses replacement on platforms without O_NOFOLLOW.
if (
!opened.isFile() ||
!entry.isFile() ||
(noFollow === 0 && opened.ino === 0n) ||
opened.dev !== entry.dev ||
opened.ino !== entry.ino
) {
return undefined;
}
const meta: unknown = JSON.parse(readFileSync(descriptor, 'utf8'));
if (!isRecord(meta)) return undefined;
// storagePath describes the flat/cache root, including in branch-slot
// metadata. The current locked directory is the generation boundary.
return resolveEmbeddingRecovery(lockDir, meta.embeddingCheckpoint);
} catch {
return undefined;
} finally {
if (descriptor !== undefined) {
try {
closeSync(descriptor);
} catch {
/* best-effort */
}
}
}
};

9
gitnexus/src/storage/index-lock.ts
View file

@ -62,6 +62,7 @@ import path from 'node:path';
import os from 'node:os';
import { randomBytes, randomUUID, createHash } from 'node:crypto';
import { isProcessAlive } from '../utils/process-identity.js';
import { readEmbeddingRecovery } from './embedding-recovery.js';
const LOCK_FILENAME = 'analyze.lock';
const LOCK_RECORD_VERSION = 1 as const;
@ -433,8 +434,9 @@ const deniedCreateHandle = (
/**
* Delete orphaned build/staging artifacts left in the lock directory by a
* crashed prior writer. Safe precisely because we hold the exclusive lock: no
* other writer can be creating these here right now, so anything present is a
* crash orphan. Matches this slot's staging files ONLY — never `lbug` itself,
* other writer can be creating these here right now. A checkpoint-referenced
* generation is retained for embedding recovery; all other stages are orphans.
* Matches this slot's staging files ONLY — never `lbug` itself,
* never `lbug.wal`/`lbug.shadow` (the LIVE index's own sidecars), and never a
* `branches/<slug>/` sub-slot (which owns its own lock + sweep). Non-recursive.
*/
@ -442,6 +444,7 @@ export const sweepStagingArtifacts = (lockDir: string, log?: (msg: string) => vo
// Matches `lbug.new`, `lbug.new.wal`, `lbug.staging.<id>`, `lbug.staging.<id>.wal`, …
// Does NOT match `lbug`, `lbug.wal`, `lbug.shadow`.
const stagingRe = /^lbug\.(staging\..+|new(\..+)?)$/;
const retained = new Set(readEmbeddingRecovery(lockDir)?.familyFiles ?? []);
let removed = 0;
let entries: string[];
try {
@ -450,7 +453,7 @@ export const sweepStagingArtifacts = (lockDir: string, log?: (msg: string) => vo
return;
}
for (const name of entries) {
if (!stagingRe.test(name)) continue;
if (!stagingRe.test(name) || retained.has(name)) continue;
try {
unlinkSync(path.join(lockDir, name));
removed++;

14
gitnexus/src/storage/repo-meta.ts
View file

@ -43,6 +43,15 @@ export type ContentRetention = 'full' | 'symbol' | 'none';
export type FtsProfile = 'full' | 'symbol-no-file-content' | 'name-only';
export const CONTENT_RETENTION_SCHEMA_VERSION = 1;
/** Exact staged generation whose completed embedding groups can survive a retry. */
export interface EmbeddingRecoveryReference {
/** A run-minted basename within this metadata file's index slot. */
stagingFile: string;
schemaFingerprint: string;
/** Active-window and inherited incomplete groups: never reusable until completed. */
unsafeNodeIds: string[];
}
/**
* Versioned receipt for the analyzer process that produced an index.
*
@ -521,6 +530,11 @@ export interface RepoMeta {
* subset of their chunks; for `'partial'` they hold none.
*/
pendingNodeIds?: string[];
/**
* Interrupted atomic builds only. This does not publish the staged graph
* or advance live embedding statistics; it identifies a recovery source.
*/
recovery?: EmbeddingRecoveryReference;
};
/**
* Name of the git branch this index represents (#2106). Absent for the

52
gitnexus/test/fixtures/staged-embedding-recovery/seed.mjs vendored Normal file
View file

@ -0,0 +1,52 @@
import lbug from '@ladybugdb/core';
import fs from 'node:fs';
import { createLbugDatabase } from '../../../src/core/lbug/lbug-config.ts';
const [dbPath, mode] = process.argv.slice(2);
const db = createLbugDatabase(lbug, dbPath);
const conn = new lbug.Connection(db);
async function query(cypher) {
const queried = await conn.query(cypher);
for (const result of Array.isArray(queried) ? queried : [queried]) {
await result.getAll();
await result.close();
}
}
await query('CREATE NODE TABLE CodeEmbedding (id STRING, nodeId STRING, chunkIndex INT32, startLine INT64, endLine INT64, embedding FLOAT[2], contentHash STRING, PRIMARY KEY(id))');
async function row(id, nodeId, chunkIndex, hash = 'same', startLine = 1, endLine = 3) {
await query(`CREATE (:CodeEmbedding {id: '${id}', nodeId: '${nodeId}', chunkIndex: ${chunkIndex}, startLine: ${startLine}, endLine: ${endLine}, embedding: [1.0, 2.0], contentHash: ${hash === null ? 'NULL' : `'${hash}'`}})`);
}
await row('complete-0', 'complete', 0);
await row('complete-1', 'complete', 1);
await row('other', 'other', 0);
await query('CHECKPOINT');
if (mode === 'interrupted-checkpoint') {
await row('checkpoint-only', 'checkpoint-only', 0);
const main = fs.readFileSync(dbPath);
const wal = fs.readFileSync(`${dbPath}.wal`);
await conn.close();
await db.close();
// Restore the pre-close bytes: writable close has already checkpointed them.
fs.writeFileSync(dbPath, main);
fs.writeFileSync(`${dbPath}.wal.checkpoint`, wal);
fs.writeFileSync(`${dbPath}.wal`, '');
fs.writeFileSync(`${dbPath}.shadow`, '');
fs.writeFileSync(`${dbPath}.checkpoint.intent.lock`, '');
fs.writeFileSync(`${dbPath}.checkpoint.apply.lock`, '');
} else if (mode === 'hard-kill') {
await row('unsafe', 'unsafe-prefix', 0);
process.kill(process.pid, 'SIGKILL');
} else {
await row('gap', 'gap', 1);
await row('duplicate-0', 'duplicate', 0);
await row('duplicate-1', 'duplicate', 0);
await row('mixed-0', 'mixed', 0, 'old');
await row('mixed-1', 'mixed', 1, 'new');
await row('missing-hash-0', 'missing-hash', 0);
await row('missing-hash-1', 'missing-hash', 1, null);
await row('bad-line', 'bad-line', 0, 'same', -1, 3);
await row('nan-0', 'nan', 0);
await query("CREATE (:CodeEmbedding {id: 'nan-1', nodeId: 'nan', chunkIndex: 1, startLine: 1, endLine: 3, embedding: [CAST('NaN', 'FLOAT'), 2.0], contentHash: 'same'})");
await conn.close();
await db.close();
}

449
gitnexus/test/integration/analyze-staged-embedding-recovery.test.ts Normal file
View file

@ -0,0 +1,449 @@
/**
* Exercise the CLI -> native staged DB -> durable checkpoint -> SIGKILL ->
* isolated recovery -> graph rebuild -> publication chain. The endpoint is
* local and deterministic; request text is the billing/reuse oracle.
*/
import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
import fs from 'node:fs';
import http from 'node:http';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
import { CLI_SPAWN_PREFIX, tsxLoaderUrl } from '../helpers/cli-entry.js';
const DIMS = 8;
const NODE_COUNT = 5_128;
const DEADLINE = process.env.CI ? 180_000 : 120_000;
const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
const adapterUrl = pathToFileURL(path.join(packageRoot, 'src/core/lbug/lbug-adapter.ts')).href;
interface CheckpointMeta {
repoPath: string;
stats?: { embeddings?: number };
embeddingCheckpoint?: {
nodesProcessed: number;
chunksProcessed: number;
pendingNodeIds?: string[];
recovery?: { stagingFile: string; schemaFingerprint: string; unsafeNodeIds: string[] };
};
}
interface Run {
child: ChildProcess;
output: () => string;
done: Promise<{ code: number | null; signal: NodeJS.Signals | null; output: string }>;
}
let root: string;
let stoppedRepo: string;
let server: http.Server;
let endpoint: string;
let submitted: string[] = [];
let completed: string[] = [];
let durableTexts: string[] = [];
const activeWindowCompleted: string[] = [];
let held: string[] = [];
let stopAfterCheckpoint = false;
let currentRepo: string;
let gateResolve: (() => void) | undefined;
const running = new Set<ChildProcess>();
function readMeta(repo: string): CheckpointMeta {
return JSON.parse(fs.readFileSync(path.join(repo, '.gitnexus', 'gitnexus.json'), 'utf8'));
}
function cliEnv(repo: string): NodeJS.ProcessEnv {
const env = { ...process.env };
for (const key of Object.keys(env)) {
if (key.startsWith('GITNEXUS_EMBEDDING_') || key.startsWith('GITNEXUS_STORAGE_'))
delete env[key];
}
return {
...env,
GITNEXUS_HOME: path.join(root, `home-${path.basename(repo)}`),
GITNEXUS_SHARED_STORE: 'off',
GITNEXUS_LBUG_EXTENSION_INSTALL: 'never',
GITNEXUS_LBUG_BUFFER_POOL_SIZE: String(256 * 1024 * 1024),
GITNEXUS_EMBEDDING_URL: endpoint,
GITNEXUS_EMBEDDING_MODEL: 'staged-recovery-fixture',
GITNEXUS_EMBEDDING_DIMS: String(DIMS),
GITNEXUS_EMBEDDING_BATCH_SIZE: '5000',
GITNEXUS_EMBEDDING_SUB_BATCH_SIZE: '64',
GITNEXUS_EMBEDDING_MAX_ATTEMPTS: '1',
GITNEXUS_EMBEDDING_CACHE_IN_MEMORY_LIMIT: '0',
GITNEXUS_MEMORY: 'off',
// SIGKILL skips process exit hooks; keep orphaned cache/export spills in
// this suite's owned directory so afterAll can remove them as well.
TMPDIR: path.join(root, 'tmp'),
NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=2048`.trim(),
CI: '1',
};
}
function runAnalyze(repo: string, flags: string[] = [], onOutput?: (output: string) => void): Run {
let output = '';
const child = spawn(
process.execPath,
[
...CLI_SPAWN_PREFIX,
'analyze',
repo,
'--no-share',
'--skip-skills',
'--skip-fts',
'--workers',
'1',
...flags,
],
{ cwd: repo, env: cliEnv(repo), stdio: ['ignore', 'pipe', 'pipe'] },
);
running.add(child);
const timeout = setTimeout(() => child.kill('SIGKILL'), DEADLINE);
const collect = (chunk: Buffer) => {
output += chunk.toString();
onOutput?.(output);
};
child.stdout?.on('data', collect);
child.stderr?.on('data', collect);
const done = new Promise<{ code: number | null; signal: NodeJS.Signals | null; output: string }>(
(resolve, reject) => {
child.once('error', reject);
child.once('close', (code, signal) => {
clearTimeout(timeout);
running.delete(child);
resolve({ code, signal, output });
});
},
);
return { child, done, output: () => output };
}
async function successfulAnalyze(repo: string, flags: string[] = []): Promise<string[]> {
submitted = [];
stopAfterCheckpoint = false;
currentRepo = repo;
const result = await runAnalyze(repo, flags).done;
expect(result.output, `CLI exited ${result.code}, signal ${result.signal}`).not.toContain(
'SIGABRT',
);
expect(result.code, result.output).toBe(0);
return [...submitted];
}
function cloneStoppedRepo(name: string): string {
const repo = path.join(root, name);
fs.cpSync(stoppedRepo, repo, { recursive: true });
for (const filename of ['gitnexus.json', 'meta.json']) {
const target = path.join(repo, '.gitnexus', filename);
const meta = JSON.parse(fs.readFileSync(target, 'utf8'));
meta.repoPath = repo;
meta.storagePath = path.join(repo, '.gitnexus');
fs.writeFileSync(target, JSON.stringify(meta));
}
return repo;
}
function readPublishedRows(
repo: string,
): Array<{ nodeId: string; chunkIndex: number; embedding: number[] }> {
// Keep native handles out of the vitest fork, and wait for clean teardown
// before accepting the receipt. Every read opens only a published DB.
const receiptPath = path.join(root, `rows-${path.basename(repo)}.json`);
const script = `
const adapter = await import(${JSON.stringify(adapterUrl)});
const fs = await import('node:fs');
await adapter.initLbug(${JSON.stringify(path.join(repo, '.gitnexus', 'lbug'))});
try {
const rows = await adapter.executeQuery('MATCH (e:CodeEmbedding) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex, e.embedding AS embedding');
fs.writeFileSync(${JSON.stringify(receiptPath)}, JSON.stringify(rows));
console.log('ROWS_RECEIPT:' + rows.length);
} finally { await adapter.closeLbug(); }
`;
const result = spawnSync(
process.execPath,
['--import', tsxLoaderUrl(), '--input-type=module', '-e', script],
{
cwd: packageRoot,
env: cliEnv(repo),
encoding: 'utf8',
timeout: 30_000,
},
);
try {
const diagnostic =
`${result.error ?? ''} ${result.signal ?? ''}\n${result.stderr}\n${result.stdout}`.slice(
0,
4096,
);
expect(result.status, diagnostic).toBe(0);
expect(result.stdout).toMatch(/ROWS_RECEIPT:\d+/);
return JSON.parse(fs.readFileSync(receiptPath, 'utf8'));
} finally {
fs.rmSync(receiptPath, { force: true });
}
}
function expectPublishedComplete(repo: string, expectedNodes: number): void {
const meta = readMeta(repo);
expect(meta.embeddingCheckpoint).toBeUndefined();
const rows = readPublishedRows(repo);
expect(new Set(rows.map((row) => row.nodeId)).size).toBe(expectedNodes);
expect(meta.stats?.embeddings).toBe(rows.length);
const byNode = new Map<string, number[]>();
for (const row of rows) {
expect(row.embedding).toHaveLength(DIMS);
expect(row.embedding.every(Number.isFinite)).toBe(true);
const indices = byNode.get(row.nodeId) ?? [];
indices.push(row.chunkIndex);
byNode.set(row.nodeId, indices);
}
for (const indices of byNode.values()) {
expect(indices.sort((a, b) => a - b)).toEqual(
Array.from({ length: indices.length }, (_, index) => index),
);
}
expect(
fs.readdirSync(path.join(repo, '.gitnexus')).filter((name) => name.startsWith('lbug.staging.')),
).toEqual([]);
}
beforeAll(async () => {
if (process.platform === 'win32') return;
root = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-staged-recovery-e2e-'));
fs.mkdirSync(path.join(root, 'tmp'));
stoppedRepo = path.join(root, 'interrupted');
currentRepo = stoppedRepo;
fs.mkdirSync(stoppedRepo);
const shortFunctions = Array.from(
{ length: NODE_COUNT - 1 },
(_, index) => `export function recoverable${index}() { return ${index}; }`,
);
// Multi-chunk nodes must be reused as a complete group, including their tail.
const longFunction = `export function longRecoverable() {\n${Array.from({ length: 80 }, (_, index) => ` // retained chunk marker ${index} ${'x'.repeat(80)}`).join('\n')}\n return 42;\n}`;
fs.writeFileSync(
path.join(stoppedRepo, 'functions.ts'),
`${longFunction}\n${shortFunctions.join('\n')}\n`,
);
const gitEnv = {
...process.env,
GIT_AUTHOR_NAME: 'test',
GIT_AUTHOR_EMAIL: 'test@test',
GIT_COMMITTER_NAME: 'test',
GIT_COMMITTER_EMAIL: 'test@test',
};
for (const args of [['init'], ['add', 'functions.ts'], ['commit', '-m', 'recovery fixture']]) {
const result = spawnSync('git', args, { cwd: stoppedRepo, env: gitEnv, encoding: 'utf8' });
expect(result.status, result.stderr).toBe(0);
}
server = http.createServer((request, response) => {
let body = '';
request.on('data', (chunk) => {
body += chunk;
});
request.on('end', () => {
const { input } = JSON.parse(body) as { input: string[] };
submitted.push(...input);
if (
stopAfterCheckpoint &&
(readMeta(currentRepo).embeddingCheckpoint?.nodesProcessed ?? 0) >= 5000
) {
if (activeWindowCompleted.length > 0) {
held = [...input];
gateResolve?.();
// One sub-batch has already inserted rows inside the unsafe window.
// Awaiting the next real request gates a crash before it completes.
return;
}
durableTexts = [...completed];
activeWindowCompleted.push(...input);
}
completed.push(...input);
response.writeHead(200, { 'content-type': 'application/json' });
response.end(
JSON.stringify({
data: input.map((text, index) => ({
index,
embedding: Array.from(
{ length: DIMS },
(_, dimension) => ((text.length + dimension * 17) % 101) / 101,
),
})),
}),
);
});
});
await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
const address = server.address() as { port: number };
endpoint = `http://127.0.0.1:${address.port}/v1`;
await successfulAnalyze(stoppedRepo, ['--index-only']);
expect(readMeta(stoppedRepo).stats?.embeddings ?? 0).toBe(0);
completed = [];
held = [];
stopAfterCheckpoint = true;
const gate = new Promise<void>((resolve) => {
gateResolve = resolve;
});
const first = runAnalyze(stoppedRepo, ['--force', '--embeddings']);
await Promise.race([
gate,
first.done.then((result) => {
throw new Error(`CLI exited before recovery gate: ${result.output}`);
}),
]);
first.child.kill('SIGKILL');
expect((await first.done).signal).toBe('SIGKILL');
const interrupted = readMeta(stoppedRepo);
expect(interrupted.embeddingCheckpoint?.nodesProcessed).toBe(5000);
expect(interrupted.embeddingCheckpoint?.recovery?.stagingFile).toMatch(/^lbug\.staging\./);
expect(interrupted.stats?.embeddings ?? 0).toBe(0);
expect(completed.length).toBeGreaterThanOrEqual(5000);
expect(completed.filter((text) => text.includes('longRecoverable')).length).toBeGreaterThan(1);
expect(activeWindowCompleted).toHaveLength(64);
expect(held.length).toBeGreaterThan(0);
gateResolve = undefined;
stopAfterCheckpoint = false;
}, DEADLINE * 2);
afterAll(async () => {
for (const child of running) child.kill('SIGKILL');
await Promise.all(
[...running].map(
(child) => new Promise<void>((resolve) => child.once('close', () => resolve())),
),
);
if (server) {
server.closeAllConnections();
await new Promise<void>((resolve) => server.close(() => resolve()));
}
if (root) fs.rmSync(root, { recursive: true, force: true });
});
// Atomic publication is POSIX-specific; Windows uses the in-place path.
describe
.skipIf(process.platform === 'win32')
.sequential('interrupted staged embedding recovery (real CLI and native DB)', () => {
it.each([
['plain', []],
['forced', ['--force', '--embeddings']],
] as const)(
'%s retry bills only unfinished groups and publishes an honest count',
async (name, flags) => {
const repo = cloneStoppedRepo(name);
const texts = await successfulAnalyze(repo, [...flags]);
const durable = new Set(durableTexts);
expect(texts.filter((text) => durable.has(text))).toEqual([]);
for (const text of held) expect(texts).toContain(text);
for (const text of activeWindowCompleted) expect(texts).toContain(text);
expect(texts.length).toBe(128);
expectPublishedComplete(repo, NODE_COUNT);
},
DEADLINE,
);
it(
'manual checkpoint opt-out completes a staged retry without resubmitting durable chunks',
async () => {
const repo = cloneStoppedRepo('manual-checkpoint-opt-out');
const previous = process.env.GITNEXUS_WAL_MANUAL_CHECKPOINT;
process.env.GITNEXUS_WAL_MANUAL_CHECKPOINT = '0';
try {
const texts = await successfulAnalyze(repo, ['--force', '--embeddings']);
expect(texts.filter((text) => new Set(durableTexts).has(text))).toEqual([]);
expect(texts.length).toBe(128);
expectPublishedComplete(repo, NODE_COUNT);
} finally {
if (previous === undefined) delete process.env.GITNEXUS_WAL_MANUAL_CHECKPOINT;
else process.env.GITNEXUS_WAL_MANUAL_CHECKPOINT = previous;
}
},
DEADLINE,
);
it(
'survives another crash after harvesting but before the replacement is durable',
async () => {
const repo = cloneStoppedRepo('crash-again');
const source = readMeta(repo).embeddingCheckpoint?.recovery?.stagingFile;
expect(source).toBeDefined();
if (!source) throw new Error('fixture has no retained generation');
submitted = [];
currentRepo = repo;
let killed = false;
const retry = runAnalyze(repo, [], (output) => {
if (!killed && /Recovered \d+ complete staged embedding chunk/.test(output)) {
killed = true;
retry.child.kill('SIGKILL');
}
});
const result = await retry.done;
expect(killed, result.output).toBe(true);
expect(result.signal).toBe('SIGKILL');
expect(submitted).toEqual([]);
expect(readMeta(repo).embeddingCheckpoint?.recovery?.stagingFile).toBe(source);
expect(fs.existsSync(path.join(repo, '.gitnexus', source))).toBe(true);
const finalTexts = await successfulAnalyze(repo);
expect(finalTexts.filter((text) => new Set(durableTexts).has(text))).toEqual([]);
expect(finalTexts.length).toBe(128);
expectPublishedComplete(repo, NODE_COUNT);
},
DEADLINE * 2,
);
it(
'regenerates changed content and removes deleted nodes while reusing the other complete groups',
async () => {
const repo = cloneStoppedRepo('changed');
const source = path.join(repo, 'functions.ts');
const content = fs
.readFileSync(source, 'utf8')
.replace(
'export function recoverable5() { return 5; }',
'export function recoverable5() { return 999999; }',
)
.replace(
'export function recoverable6() { return 6; }',
'// deleted function retains line offsets',
);
fs.writeFileSync(source, content);
const texts = await successfulAnalyze(repo);
expect(texts.some((text) => text.includes('recoverable5') && text.includes('999999'))).toBe(
true,
);
expect(texts.some((text) => text.includes('recoverable6'))).toBe(false);
expect(texts.filter((text) => new Set(durableTexts).has(text))).toEqual([]);
expect(texts.length).toBe(129);
expectPublishedComplete(repo, NODE_COUNT - 1);
},
DEADLINE,
);
it(
'a forced retry with a different model does not import the staged cache',
async () => {
const repo = cloneStoppedRepo('different-model');
const texts = await successfulAnalyze(repo, [
'--force',
'--embeddings',
'--embedding-model',
'different-model',
]);
for (const text of durableTexts) expect(texts).toContain(text);
expect(texts.length).toBeGreaterThanOrEqual(NODE_COUNT);
expectPublishedComplete(repo, NODE_COUNT);
},
DEADLINE,
);
it(
'explicit drop abandons staged vectors without contacting the provider',
async () => {
const repo = cloneStoppedRepo('drop');
expect(await successfulAnalyze(repo, ['--force', '--drop-embeddings'])).toEqual([]);
expect(readMeta(repo).embeddingCheckpoint).toBeUndefined();
expect(readMeta(repo).stats?.embeddings ?? 0).toBe(0);
expect(readPublishedRows(repo)).toEqual([]);
},
DEADLINE,
);
});

758
gitnexus/test/integration/impact-context-integrity.test.ts Normal file
View file

@ -0,0 +1,758 @@
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
import fs from 'node:fs/promises';
import path from 'node:path';
import lbug from '@ladybugdb/core';
import * as adapter from '../../src/core/lbug/lbug-adapter.js';
import { executeParameterized } from '../../src/core/lbug/pool-adapter.js';
import { closeQueryResults } from '../../src/core/lbug/query-result-utils.js';
import { LocalBackend } from '../../src/mcp/local/local-backend.js';
import { retryRename } from '../../src/storage/fs-atomic.js';
import { getStoragePaths, registerRepo, saveMeta } from '../../src/storage/repo-manager.js';
import { createTempDir } from '../helpers/test-db.js';
const REPO = 'query-integrity';
const nodes = {
alpha: { id: 'Function:src/alpha.ts:runSweep', name: 'runSweep', filePath: 'src/alpha.ts' },
alphaCaller: {
id: 'Function:src/α/caller.ts:appelÉ',
name: 'appelÉ',
filePath: 'src/α/caller.ts',
},
alphaOtherCaller: {
id: 'Function:src/other.ts:runOther',
name: 'runOther',
filePath: 'src/other.ts',
},
alphaRoot: { id: 'Function:src/root.ts:startSweep', name: 'startSweep', filePath: 'src/root.ts' },
alphaReader: {
id: 'Function:src/reader.ts:readSweep',
name: 'readSweep',
filePath: 'src/reader.ts',
},
beta: {
id: 'Function:src/beta.ts:extractLeadingNumber',
name: 'extractLeadingNumber',
filePath: 'src/beta.ts',
},
betaCaller: {
id: 'Function:src/number.ts:parseNumber',
name: 'parseNumber',
filePath: 'src/number.ts',
},
betaReader: {
id: 'Function:src/number-view.ts:readNumber',
name: 'readNumber',
filePath: 'src/number-view.ts',
},
} as const;
const processes = {
alpha: {
id: 'process:alpha',
label: 'Sweep flow',
entry: nodes.alphaRoot,
terminal: nodes.alpha,
stepCount: 3,
},
alphaOther: {
id: 'process:alpha-other',
label: 'Other sweep flow',
entry: nodes.alphaOtherCaller,
terminal: nodes.alpha,
stepCount: 2,
},
beta: {
id: 'process:beta',
label: 'Number flow',
entry: nodes.betaCaller,
terminal: nodes.beta,
stepCount: 2,
},
} as const;
type NodeIdentity = { id: string; name: string; filePath: string };
type Membership = { id: string; label: string; processType: string; step: number };
type ImpactRow = NodeIdentity & {
relationType: string;
confidence: number;
processes: Membership[];
};
type ContextRef = { uid: string; name: string; filePath: string };
type Target = 'alpha' | 'beta';
const membership = (
process: (typeof processes)[keyof typeof processes],
step: number,
): Membership => ({
id: process.id,
label: process.label,
processType: 'intra_community',
step,
});
const affectedProcess = (process: (typeof processes)[keyof typeof processes], hits: number) => ({
name: process.entry.name,
type: 'Function',
filePath: process.entry.filePath,
affected_process_count: 1,
total_hits: hits,
earliest_broken_step: 0,
});
const oracle = {
alpha: {
count: 3,
direct: 2,
byDepth: {
1: [
{
...nodes.alphaOtherCaller,
relationType: 'CALLS',
confidence: 1,
processes: [membership(processes.alphaOther, 0)],
},
{
...nodes.alphaCaller,
relationType: 'CALLS',
confidence: 1,
processes: [membership(processes.alpha, 1)],
},
],
2: [
{
...nodes.alphaRoot,
relationType: 'CALLS',
confidence: 1,
processes: [membership(processes.alpha, 0)],
},
],
},
callers: [nodes.alphaOtherCaller, nodes.alphaCaller],
accesses: [nodes.alphaReader],
processes: [
{ id: processes.alpha.id, name: processes.alpha.label, step_index: 2, step_count: 3 },
{
id: processes.alphaOther.id,
name: processes.alphaOther.label,
step_index: 1,
step_count: 2,
},
],
affectedProcesses: [
affectedProcess(processes.alpha, 2),
affectedProcess(processes.alphaOther, 1),
],
},
beta: {
count: 1,
direct: 1,
byDepth: {
1: [
{
...nodes.betaCaller,
relationType: 'CALLS',
confidence: 1,
processes: [membership(processes.beta, 0)],
},
],
},
callers: [nodes.betaCaller],
accesses: [nodes.betaReader],
processes: [
{ id: processes.beta.id, name: processes.beta.label, step_index: 1, step_count: 2 },
],
affectedProcesses: [affectedProcess(processes.beta, 1)],
},
} as const;
// Compare the values returned by the native engine with a hand-written graph
// oracle, rather than accepting a repeated (and potentially wrong) first result.
function expectImpact(
result: Awaited<ReturnType<LocalBackend['callTool']>>,
target: Target,
summaryOnly: boolean,
): void {
const expected = oracle[target];
expect(result).not.toHaveProperty('error');
expect(result).not.toHaveProperty('partial');
expect(result.target).toMatchObject(nodes[target]);
expect(result.direction).toBe('upstream');
expect(result.impactedCount).toBe(expected.count);
expect(result.risk).toBe('LOW');
expect(result.epistemic).toBe('exact');
expect(result.summary).toEqual({
direct: expected.direct,
processes_affected: expected.affectedProcesses.length,
modules_affected: 0,
});
expect(result.byDepthCounts).toEqual(target === 'alpha' ? { 1: 2, 2: 1 } : { 1: 1 });
expect(result.affected_processes).toEqual(expected.affectedProcesses);
expect(result.affected_modules).toEqual([]);
expect(result.affected_routes).toEqual([]);
if (summaryOnly) {
expect(result).not.toHaveProperty('byDepth');
} else {
const byDepth = Object.fromEntries(
Object.entries(result.byDepth).map(([depth, rows]) => [
depth,
(rows as ImpactRow[]).map(
({ id, name, filePath, relationType, confidence, processes: memberships }) => ({
id,
name,
filePath,
relationType,
confidence,
processes: memberships,
}),
),
]),
);
expect(byDepth).toEqual(expected.byDepth);
}
}
function expectContext(
result: Awaited<ReturnType<LocalBackend['callTool']>>,
target: Target,
): void {
const expected = oracle[target];
expect(result).not.toHaveProperty('error');
expect(result.status).toBe('found');
expect(result.symbol).toMatchObject({
uid: nodes[target].id,
name: nodes[target].name,
filePath: nodes[target].filePath,
});
expect(result.epistemic).toBe('exact');
const incoming = Object.fromEntries(
Object.entries(result.incoming).map(([type, refs]) => [
type,
(refs as ContextRef[]).map(({ uid, name, filePath }) => ({ id: uid, name, filePath })),
]),
);
expect(incoming).toEqual({ calls: expected.callers, accesses: expected.accesses });
expect(result.outgoing).toEqual({});
expect(result.processes).toEqual(expected.processes);
}
function edge(source: NodeIdentity, target: NodeIdentity, type: 'CALLS' | 'ACCESSES'): string {
return `MATCH (a:Function {id: '${source.id}'}), (b:Function {id: '${target.id}'}) CREATE (a)-[:CodeRelation {type: '${type}', confidence: 1.0, reason: 'direct', step: 0}]->(b)`;
}
function processStep(
node: NodeIdentity,
process: (typeof processes)[keyof typeof processes],
step: number,
): string {
return `MATCH (n:Function {id: '${node.id}'}), (p:Process {id: '${process.id}'}) CREATE (n)-[:CodeRelation {type: 'STEP_IN_PROCESS', confidence: 1.0, reason: 'trace-detection', step: ${step}}]->(p)`;
}
describe('native impact/context result integrity (#3354)', () => {
let temp: Awaited<ReturnType<typeof createTempDir>>;
let backend: LocalBackend;
let lbugPath: string;
beforeAll(async () => {
temp = await createTempDir();
vi.stubEnv('GITNEXUS_HOME', path.join(temp.dbPath, 'home'));
vi.stubEnv('GITNEXUS_STORAGE_PATH', path.join(temp.dbPath, 'index'));
vi.stubEnv('GITNEXUS_SHARED_STORE', 'off');
const paths = getStoragePaths(temp.dbPath);
lbugPath = paths.lbugPath;
// Close the writer before LocalBackend opens its ordinary read pool. No
// mocked registry or injected writable Database bypasses the read path.
await adapter.initLbug(lbugPath);
try {
const seed = [
...Object.values(nodes).map(
(node) =>
`CREATE (:Function {id: '${node.id}', name: '${node.name}', filePath: '${node.filePath}', startLine: 1, endLine: 3})`,
),
...Object.values(processes).map(
(process) =>
`CREATE (:Process {id: '${process.id}', label: '${process.label}', heuristicLabel: '${process.label}', processType: 'intra_community', stepCount: ${process.stepCount}, communities: [], entryPointId: '${process.entry.id}', terminalId: '${process.terminal.id}'})`,
),
edge(nodes.alphaCaller, nodes.alpha, 'CALLS'),
edge(nodes.alphaOtherCaller, nodes.alpha, 'CALLS'),
edge(nodes.alphaRoot, nodes.alphaCaller, 'CALLS'),
edge(nodes.alphaReader, nodes.alpha, 'ACCESSES'),
edge(nodes.betaCaller, nodes.beta, 'CALLS'),
edge(nodes.betaReader, nodes.beta, 'ACCESSES'),
processStep(nodes.alphaRoot, processes.alpha, 0),
processStep(nodes.alphaCaller, processes.alpha, 1),
processStep(nodes.alpha, processes.alpha, 2),
processStep(nodes.alphaOtherCaller, processes.alphaOther, 0),
processStep(nodes.alpha, processes.alphaOther, 1),
processStep(nodes.betaCaller, processes.beta, 0),
processStep(nodes.beta, processes.beta, 1),
];
for (const query of seed) await adapter.executeQuery(query);
await adapter.flushWAL();
} finally {
await adapter.closeLbug();
}
const meta = {
repoPath: temp.dbPath,
storagePath: paths.storagePath,
lastCommit: 'integrity-fixture',
indexedAt: new Date().toISOString(),
scopeExtractionReceipt: 1 as const,
stats: { files: 8, nodes: 11, processes: 3, communities: 0 },
};
await saveMeta(paths.storagePath, meta);
await registerRepo(temp.dbPath, meta, { name: REPO });
backend = new LocalBackend();
expect(await backend.init()).toBe(true);
});
afterAll(async () => {
try {
await backend?.dispose();
} finally {
await adapter.closeLbug();
vi.unstubAllEnvs();
await temp?.cleanup();
}
});
const impact = (target: Target, summaryOnly = false) =>
backend.callTool('impact', {
repo: REPO,
target: nodes[target].name,
direction: 'upstream',
summaryOnly,
});
const context = (target: Target) =>
backend.callTool('context', { repo: REPO, uid: nodes[target].id });
it('returns exact values across identical sequential requests', async () => {
for (let repeat = 0; repeat < 6; repeat++) {
expectImpact(await impact('alpha', true), 'alpha', true);
expectContext(await context('alpha'), 'alpha');
expectImpact(await impact('alpha'), 'alpha', false);
}
});
it('keeps unrelated targets isolated across mixed requests', async () => {
for (const target of ['alpha', 'beta', 'beta', 'alpha'] as const) {
expectImpact(await impact(target, true), target, true);
expectContext(await context(target), target);
expectImpact(await impact(target), target, false);
}
});
it('keeps mixed concurrent prepared reads symbol-specific', async () => {
for (let repeat = 0; repeat < 3; repeat++) {
const results = await Promise.all([
impact('alpha', true),
context('beta'),
impact('beta'),
impact('beta', true),
context('alpha'),
impact('alpha'),
]);
expectImpact(results[0], 'alpha', true);
expectContext(results[1], 'beta');
expectImpact(results[2], 'beta', false);
expectImpact(results[3], 'beta', true);
expectContext(results[4], 'alpha');
expectImpact(results[5], 'alpha', false);
}
});
it('returns exact relation rows directly from the pooled prepared adapter', async () => {
// Warm the pool through the same backend, then check the native row
// boundary independently of the tool's normalization and aggregation.
expectContext(await context('alpha'), 'alpha');
const read = (target: Target) =>
executeParameterized(
lbugPath,
`
MATCH (caller:Function)-[r:CodeRelation]->(target:Function {id: $id})
WHERE r.type IN ['CALLS', 'ACCESSES']
RETURN caller.id AS id, caller.name AS name, caller.filePath AS filePath, r.type AS relationType
ORDER BY id
`,
{ id: nodes[target].id },
);
const expectedRows = (target: Target) =>
[
...oracle[target].callers.map((caller) => ({ ...caller, relationType: 'CALLS' })),
...oracle[target].accesses.map((reader) => ({ ...reader, relationType: 'ACCESSES' })),
].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
for (let repeat = 0; repeat < 4; repeat++) {
expect(await read('alpha')).toEqual(expectedRows('alpha'));
const [beta, alpha] = await Promise.all([read('beta'), read('alpha')]);
expect(beta).toEqual(expectedRows('beta'));
expect(alpha).toEqual(expectedRows('alpha'));
}
});
});
describe('native string projections after checkpointed deletion (#3354)', () => {
it('keeps long symbol identities associated with their source rows across segments', async () => {
const temp = await createTempDir();
const db = new lbug.Database(path.join(temp.dbPath, 'scan.lbug'), 128 * 1024 * 1024);
const conn = new lbug.Connection(db, 4);
const source = Array.from({ length: 10_000 }, (_, startLine) => ({
id: `Function:src/generated/rené-${String(startLine).padStart(5, '0')}.ts:fn${startLine}`,
name: `generated_function_${startLine}_é`,
filePath: `src/generated/rené-${String(startLine).padStart(5, '0')}.ts`,
startLine,
}));
const projection =
'RETURN n.id AS id, n.name AS name, n.filePath AS filePath, n.startLine AS startLine';
const read = async (query: string) => {
const result = await conn.query(query);
try {
const cursor = Array.isArray(result) ? result[0] : result;
return await cursor.getAll();
} finally {
await closeQueryResults(result);
}
};
try {
await read(
'CREATE NODE TABLE Function(id STRING, name STRING, filePath STRING, startLine INT64, PRIMARY KEY(id))',
);
// Separate checkpoints create segment boundaries inside scan vectors.
// LadybugDB 0.18.3's filtered STRING scan could retain another row's
// printable identities here (LadybugDB/ladybug#678, fixed by #737).
for (let batch = 0; batch < 4; batch++) {
const csvPath = path.join(temp.dbPath, `rows-${batch}.csv`);
const csv = source
.slice(batch * 2500, (batch + 1) * 2500)
.map((row) =>
Object.values(row)
.map((value) => JSON.stringify(value))
.join(','),
)
.join('\n');
await fs.writeFile(csvPath, `${csv}\n`);
await read(
`COPY Function FROM ${JSON.stringify(csvPath.replaceAll('\\', '/'))} (HEADER=false)`,
);
await read('CHECKPOINT');
}
expect(await read(`MATCH (n:Function) ${projection} ORDER BY n.startLine`)).toEqual(source);
await read(
'MATCH (n:Function) WHERE n.startLine >= 3000 AND n.startLine < 3400 DETACH DELETE n',
);
await read('CHECKPOINT');
const surviving = source.filter((row) => row.startLine < 3000 || row.startLine >= 3400);
for (let repeat = 0; repeat < 3; repeat++) {
for (const order of ['', ' ORDER BY n.startLine']) {
const rows = await read(`MATCH (n:Function) ${projection}${order}`);
expect(new Set(rows.map((row) => row.id)).size).toBe(surviving.length);
expect(rows.sort((a, b) => a.startLine - b.startLine)).toEqual(surviving);
}
}
// Point lookups independently verify values in the affected segments;
// a repeatably wrong scan must never become the test's reference answer.
for (const startLine of [1600, 7486]) {
expect(
await read(`MATCH (n:Function {id: '${source[startLine].id}'}) ${projection}`),
).toEqual([source[startLine]]);
}
expect(await read(`MATCH (n:Function {id: '${source[3000].id}'}) ${projection}`)).toEqual([]);
} finally {
try {
await conn.close();
} finally {
try {
await db.close();
} finally {
await temp.cleanup();
}
}
}
});
});
// Windows graph replacement is opt-in in production. The repeated-read
// characterization above remains enabled there; only this POSIX swap is skipped.
describe.skipIf(process.platform === 'win32')('warm backend index replacement (#3354)', () => {
it('reads changed callers, processes and a new symbol through the real freshness window', async () => {
const temp = await createTempDir();
let backend: LocalBackend | undefined;
vi.stubEnv('GITNEXUS_HOME', path.join(temp.dbPath, 'home'));
vi.stubEnv('GITNEXUS_STORAGE_PATH', path.join(temp.dbPath, 'index'));
vi.stubEnv('GITNEXUS_SHARED_STORE', 'off');
const paths = getStoragePaths(temp.dbPath);
const stagedPath = `${paths.lbugPath}.replacement`;
const replacement = {
entry: {
id: 'Function:src/replacement-entry.ts:startReplacement',
name: 'startReplacement',
filePath: 'src/replacement-entry.ts',
},
caller: {
id: 'Function:src/replacement-caller.ts:callReplacement',
name: 'callReplacement',
filePath: 'src/replacement-caller.ts',
},
reader: {
id: 'Function:src/replacement-reader.ts:readReplacement',
name: 'readReplacement',
filePath: 'src/replacement-reader.ts',
},
};
const nextProcess = { id: 'process:replacement', label: 'Replacement flow' };
const oldProcess = processes.alphaOther;
const seed = async (dbPath: string, next: boolean) => {
await adapter.initLbug(dbPath);
try {
const caller = next ? replacement.caller : nodes.alphaOtherCaller;
const reader = next ? replacement.reader : nodes.alphaReader;
const process = next ? nextProcess : oldProcess;
const entry = next ? replacement.entry : caller;
for (const node of [nodes.alpha, caller, reader, ...(next ? [entry] : [])]) {
await adapter.executeQuery(
`CREATE (:Function {id: '${node.id}', name: '${node.name}', filePath: '${node.filePath}', startLine: 1, endLine: 3})`,
);
}
await adapter.executeQuery(
`CREATE (:Process {id: '${process.id}', label: '${process.label}', heuristicLabel: '${process.label}', processType: 'intra_community', stepCount: ${next ? 3 : 2}, communities: [], entryPointId: '${entry.id}', terminalId: '${nodes.alpha.id}'})`,
);
await adapter.executeQuery(edge(caller, nodes.alpha, 'CALLS'));
await adapter.executeQuery(edge(reader, nodes.alpha, 'ACCESSES'));
if (next) await adapter.executeQuery(edge(entry, caller, 'CALLS'));
const steps = next ? [entry, caller, nodes.alpha] : [caller, nodes.alpha];
for (const [step, node] of steps.entries()) {
await adapter.executeQuery(
`MATCH (n:Function {id: '${node.id}'}), (p:Process {id: '${process.id}'}) CREATE (n)-[:CodeRelation {type: 'STEP_IN_PROCESS', confidence: 1.0, reason: 'trace-detection', step: ${step}}]->(p)`,
);
}
await adapter.flushWAL();
} finally {
await adapter.closeLbug();
}
};
const processMembership = (next: boolean, step: number) => ({
...(next ? nextProcess : { id: oldProcess.id, label: oldProcess.label }),
processType: 'intra_community',
step,
});
const expectedCaller = (node: NodeIdentity, next: boolean, step: number) => ({
...node,
relationType: 'CALLS',
confidence: 1,
processes: [processMembership(next, step)],
});
const expectGeneration = (
impact: Awaited<ReturnType<LocalBackend['callTool']>>,
context: Awaited<ReturnType<LocalBackend['callTool']>>,
next: boolean,
) => {
const caller = next ? replacement.caller : nodes.alphaOtherCaller;
const reader = next ? replacement.reader : nodes.alphaReader;
const entry = next ? replacement.entry : caller;
const process = next ? nextProcess : oldProcess;
expect(impact).not.toHaveProperty('error');
expect(impact).not.toHaveProperty('partial');
expect(impact.target).toMatchObject(nodes.alpha);
expect(impact.risk).toBe('LOW');
expect(impact.epistemic).toBe('exact');
expect(impact.impactedCount).toBe(next ? 2 : 1);
expect(impact.summary).toEqual({ direct: 1, processes_affected: 1, modules_affected: 0 });
expect(impact.byDepthCounts).toEqual(next ? { 1: 1, 2: 1 } : { 1: 1 });
const byDepth = Object.fromEntries(
Object.entries(impact.byDepth).map(([depth, rows]) => [
depth,
(rows as ImpactRow[]).map(
({ id, name, filePath, relationType, confidence, processes: memberships }) => ({
id,
name,
filePath,
relationType,
confidence,
processes: memberships,
}),
),
]),
);
expect(byDepth).toEqual({
1: [expectedCaller(caller, next, next ? 1 : 0)],
...(next ? { 2: [expectedCaller(entry, true, 0)] } : {}),
});
expect(impact.affected_processes).toEqual([
{
name: entry.name,
type: 'Function',
filePath: entry.filePath,
affected_process_count: 1,
total_hits: next ? 2 : 1,
earliest_broken_step: 0,
},
]);
expect(impact.affected_modules).toEqual([]);
expect(impact.affected_routes).toEqual([]);
expect(context).not.toHaveProperty('error');
expect(context.status).toBe('found');
expect(context.epistemic).toBe('exact');
expect(context.symbol).toMatchObject({
uid: nodes.alpha.id,
name: nodes.alpha.name,
filePath: nodes.alpha.filePath,
});
expect(
Object.fromEntries(
Object.entries(context.incoming).map(([type, refs]) => [
type,
(refs as ContextRef[]).map(({ uid, name, filePath }) => ({ id: uid, name, filePath })),
]),
),
).toEqual({ calls: [caller], accesses: [reader] });
expect(context.outgoing).toEqual({});
expect(context.processes).toEqual([
{
id: process.id,
name: process.label,
step_index: next ? 2 : 1,
step_count: next ? 3 : 2,
},
]);
};
try {
await seed(paths.lbugPath, false);
const meta = {
repoPath: temp.dbPath,
storagePath: paths.storagePath,
lastCommit: 'graph-a',
indexedAt: new Date().toISOString(),
scopeExtractionReceipt: 1 as const,
stats: { files: 3, nodes: 4, processes: 1, communities: 0 },
};
await saveMeta(paths.storagePath, meta);
await registerRepo(temp.dbPath, meta, { name: REPO });
const heldBackend = new LocalBackend();
backend = heldBackend;
expect(await heldBackend.init()).toBe(true);
const impact = () =>
heldBackend.callTool('impact', {
repo: REPO,
target: nodes.alpha.name,
direction: 'upstream',
});
const context = () => heldBackend.callTool('context', { repo: REPO, uid: nodes.alpha.id });
expectGeneration(await impact(), await context(), false);
expect(
await heldBackend.callTool('context', { repo: REPO, uid: replacement.entry.id }),
).toHaveProperty('error');
// Keep this backend and its read pool alive. Publish only after the
// separate staged writer has closed, exactly as run-analyze does.
await seed(stagedPath, true);
for (const suffix of ['.wal', '.shadow', '.wal.checkpoint']) {
await expect(fs.stat(`${stagedPath}${suffix}`)).rejects.toMatchObject({ code: 'ENOENT' });
}
await retryRename(stagedPath, paths.lbugPath);
const nextMeta = {
...meta,
lastCommit: 'graph-b',
indexedAt: new Date(Date.now() + 1).toISOString(),
stats: { files: 4, nodes: 5, processes: 1, communities: 0 },
};
await saveMeta(paths.storagePath, nextMeta);
await registerRepo(temp.dbPath, nextMeta, { name: REPO });
// An independent native read-only Database opens the published path.
// It does not share LocalBackend's pool or trigger its reinitialization.
const freshDb = new lbug.Database(paths.lbugPath, 128 * 1024 * 1024, true, true);
const freshConn = new lbug.Connection(freshDb);
try {
const read = async (query: string) => {
const result = await freshConn.query(query);
try {
const cursor = Array.isArray(result) ? result[0] : result;
return await cursor.getAll();
} finally {
await closeQueryResults(result);
}
};
expect(
await read(`
MATCH (n:Function)
RETURN n.id AS id, n.name AS name, n.filePath AS filePath
ORDER BY id
`),
).toEqual(
[nodes.alpha, ...Object.values(replacement)].sort((a, b) =>
a.id < b.id ? -1 : a.id > b.id ? 1 : 0,
),
);
expect(
await read(`
MATCH (n:Function)-[r:CodeRelation]->(target:Function {id: '${nodes.alpha.id}'})
WHERE r.type IN ['CALLS', 'ACCESSES']
RETURN n.id AS id, n.name AS name, n.filePath AS filePath, r.type AS relationType
ORDER BY id
`),
).toEqual([
{ ...replacement.caller, relationType: 'CALLS' },
{ ...replacement.reader, relationType: 'ACCESSES' },
]);
expect(
await read(`
MATCH (n:Function)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
RETURN n.id AS id, p.id AS processId, p.heuristicLabel AS label,
r.step AS step, p.stepCount AS stepCount, p.entryPointId AS entryPointId
ORDER BY step
`),
).toEqual(
[replacement.entry, replacement.caller, nodes.alpha].map((node, step) => ({
id: node.id,
processId: nextProcess.id,
label: nextProcess.label,
step,
stepCount: 3,
entryPointId: replacement.entry.id,
})),
);
} finally {
await freshConn.close();
await freshDb.close();
}
// Poll the SAME backend through its unchanged five-second throttle.
// No private watermark override, poolInit, reset or restart is used.
const deadline = Date.now() + 15_000;
let refreshed = await context();
while (refreshed.processes?.[0]?.id !== nextProcess.id && Date.now() < deadline) {
await new Promise((resolve) => setTimeout(resolve, 300));
refreshed = await context();
}
expectGeneration(await impact(), refreshed, true);
for (let repeat = 0; repeat < 3; repeat++) {
expectGeneration(await impact(), await context(), true);
const introduced = await heldBackend.callTool('context', {
repo: REPO,
name: replacement.entry.name,
});
expect(introduced).not.toHaveProperty('error');
expect(introduced.status).toBe('found');
expect(introduced.symbol).toMatchObject({
uid: replacement.entry.id,
name: replacement.entry.name,
filePath: replacement.entry.filePath,
});
expect(introduced.processes).toEqual([
{ id: nextProcess.id, name: nextProcess.label, step_index: 0, step_count: 3 },
]);
}
} finally {
try {
await backend?.dispose();
} finally {
await adapter.closeLbug();
vi.unstubAllEnvs();
await temp.cleanup();
}
}
});
});

208
gitnexus/test/integration/staged-embedding-recovery.test.ts Normal file
View file

@ -0,0 +1,208 @@
import { spawnSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { afterEach, describe, expect, it } from 'vitest';
import {
disposeEmbeddingSpill,
materializeCachedEmbeddings,
type CachedEmbeddingsSnapshot,
} from '../../src/core/embeddings/embedding-restore-spill.js';
import { recoverStagedEmbeddings } from '../../src/core/embeddings/staged-embedding-recovery.js';
describe('isolated native staged embedding recovery', () => {
let tmp: string | undefined;
let recovered: CachedEmbeddingsSnapshot | undefined;
afterEach(() => {
disposeEmbeddingSpill(recovered?.spill);
recovered = undefined;
if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
tmp = undefined;
});
function stagePath() {
tmp ??= fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-stage-native-'));
return path.join(tmp, `lbug.staging.${randomUUID()}`);
}
function seed(dbPath: string, mode = 'clean') {
const result = spawnSync(
process.execPath,
[
'--import',
'tsx',
fileURLToPath(new URL('../fixtures/staged-embedding-recovery/seed.mjs', import.meta.url)),
dbPath,
mode,
],
{
encoding: 'utf8',
timeout: 20_000,
env: { ...process.env, GITNEXUS_LBUG_BUFFER_POOL_SIZE: String(128 * 1024 * 1024) },
},
);
expect(result.error, result.stderr).toBeUndefined();
if (mode === 'hard-kill') expect(result.signal, result.stderr).toBe('SIGKILL');
else expect(result.status, result.stderr).toBe(0);
}
function snapshotSourceFamily(dbPath: string) {
const basename = path.basename(dbPath);
return Object.fromEntries(
fs
.readdirSync(path.dirname(dbPath))
.filter((name) => name === basename || name.startsWith(`${basename}.`))
.sort()
.map((name) => [name, fs.readFileSync(path.join(path.dirname(dbPath), name))]),
);
}
it('streams complete same-hash groups and rejects malformed whole nodes', async () => {
const dbPath = stagePath();
seed(dbPath);
recovered = await recoverStagedEmbeddings(dbPath, { dimensions: 2 });
expect([...recovered.embeddingNodeIds].sort()).toEqual(['complete', 'other']);
expect(recovered.rows).toHaveLength(3);
expect(recovered.embeddings).toEqual([]);
expect(materializeCachedEmbeddings(recovered, recovered.rows)).toEqual(
expect.arrayContaining([
expect.objectContaining({
nodeId: 'complete',
chunkIndex: 0,
embedding: [1, 2],
contentHash: 'same',
}),
expect.objectContaining({
nodeId: 'complete',
chunkIndex: 1,
embedding: [1, 2],
contentHash: 'same',
}),
]),
);
expect(fs.existsSync(dbPath)).toBe(true);
}, 30_000);
it('replays a hard-killed native writer strictly and excludes the incomplete active window', async () => {
const dbPath = stagePath();
seed(dbPath, 'hard-kill');
const sourceBefore = snapshotSourceFamily(dbPath);
recovered = await recoverStagedEmbeddings(dbPath, {
dimensions: 2,
excludedNodeIds: ['unsafe-prefix', 'other'],
});
expect([...recovered.embeddingNodeIds]).toEqual(['complete']);
expect(recovered.rows).toHaveLength(2);
expect(
materializeCachedEmbeddings(recovered, recovered.rows)
.map((row) => row.chunkIndex)
.sort(),
).toEqual([0, 1]);
expect(snapshotSourceFamily(dbPath)).toEqual(sourceBefore);
}, 30_000);
it('rejects vectors from a different dimension instead of coercing them', async () => {
const dbPath = stagePath();
seed(dbPath);
recovered = await recoverStagedEmbeddings(dbPath, { dimensions: 3 });
expect(recovered.rows).toEqual([]);
}, 30_000);
it('strictly replays an interrupted checkpoint copy with both checkpoint locks retained', async (ctx) => {
const version = JSON.parse(
fs.readFileSync(
new URL('../../node_modules/@ladybugdb/core/package.json', import.meta.url),
'utf8',
),
).version as string;
const [major, minor] = version.split('.').map(Number);
// Older pins do not support the deterministic interrupted-checkpoint plant.
if (Number.isFinite(major) && Number.isFinite(minor) && major === 0 && minor < 19) ctx.skip();
const dbPath = stagePath();
seed(dbPath, 'interrupted-checkpoint');
const sourceBefore = snapshotSourceFamily(dbPath);
expect(fs.statSync(`${dbPath}.wal.checkpoint`).size).toBeGreaterThan(0);
expect(fs.existsSync(`${dbPath}.checkpoint.intent.lock`)).toBe(true);
expect(fs.existsSync(`${dbPath}.checkpoint.apply.lock`)).toBe(true);
recovered = await recoverStagedEmbeddings(dbPath, { dimensions: 2 });
expect([...recovered.embeddingNodeIds].sort()).toEqual([
'checkpoint-only',
'complete',
'other',
]);
expect(recovered.rows).toHaveLength(4);
expect(snapshotSourceFamily(dbPath)).toEqual(sourceBefore);
}, 30_000);
it('contains a malformed native source in a subprocess and preserves it', async () => {
const dbPath = stagePath();
fs.writeFileSync(dbPath, 'not a ladybug database');
await expect(recoverStagedEmbeddings(dbPath, { dimensions: 2 })).rejects.toThrow(
/extraction failed/,
);
expect(fs.readFileSync(dbPath, 'utf8')).toBe('not a ladybug database');
}, 30_000);
it('rejects a malformed WAL without deleting or quarantining it to reopen the source', async () => {
const dbPath = stagePath();
seed(dbPath, 'hard-kill');
const walPath = `${dbPath}.wal`;
fs.writeFileSync(walPath, Buffer.alloc(128, 0xff));
const sourceBefore = snapshotSourceFamily(dbPath);
await expect(recoverStagedEmbeddings(dbPath, { dimensions: 2 })).rejects.toThrow(
/extraction failed/,
);
expect(fs.existsSync(walPath)).toBe(true);
expect(fs.readdirSync(path.dirname(dbPath)).some((name) => /bad|quarantine/i.test(name))).toBe(
false,
);
expect(snapshotSourceFamily(dbPath)).toEqual(sourceBefore);
}, 30_000);
it('does not create a missing source and refuses a symlink', async () => {
const dbPath = stagePath();
await expect(recoverStagedEmbeddings(dbPath, { dimensions: 2 })).rejects.toThrow(/ENOENT/);
expect(fs.existsSync(dbPath)).toBe(false);
const realPath = path.join(path.dirname(dbPath), 'real');
fs.writeFileSync(realPath, 'fixture');
fs.symlinkSync(realPath, dbPath);
await expect(recoverStagedEmbeddings(dbPath, { dimensions: 2 })).rejects.toThrow(
/regular file/,
);
});
it('can kill a timed out native subprocess without aborting analyze', async () => {
const dbPath = stagePath();
seed(dbPath);
const sourceBefore = snapshotSourceFamily(dbPath);
await expect(recoverStagedEmbeddings(dbPath, { dimensions: 2, timeoutMs: 1 })).rejects.toThrow(
/timeout/,
);
expect(fs.existsSync(dbPath)).toBe(true);
expect(snapshotSourceFamily(dbPath)).toEqual(sourceBefore);
}, 30_000);
it('loads the source child when analyze runs in another repository directory', () => {
const dbPath = stagePath();
seed(dbPath);
const result = spawnSync(
process.execPath,
[
'--import',
import.meta.resolve('tsx'),
'--input-type=module',
'-e',
'const { recoverStagedEmbeddings } = await import(process.argv[1]); const { disposeEmbeddingSpill } = await import(process.argv[2]); const recovered = await recoverStagedEmbeddings(process.argv[3], {dimensions: 2}); process.stdout.write(String(recovered.rows.length)); disposeEmbeddingSpill(recovered.spill);',
new URL('../../src/core/embeddings/staged-embedding-recovery.ts', import.meta.url).href,
new URL('../../src/core/embeddings/embedding-restore-spill.ts', import.meta.url).href,
dbPath,
],
{ cwd: path.dirname(dbPath), encoding: 'utf8', timeout: 20_000 },
);
expect(result.error, result.stderr).toBeUndefined();
expect(result.status, result.stderr).toBe(0);
expect(result.stdout).toBe('3');
}, 30_000);
});

172
gitnexus/test/unit/api-fts-mode.test.ts
View file

@ -7,7 +7,12 @@ import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi }
const mocks = vi.hoisted(() => ({
loadMeta: vi.fn(),
saveMeta: vi.fn(),
listRegisteredRepos: vi.fn(),
acquireIndexLock: vi.fn(),
releaseIndexLock: vi.fn(),
ensurePrivateSharedGraph: vi.fn(),
runEmbeddingPipeline: vi.fn(),
withLbugDb: vi.fn(),
search: vi.fn(),
updateJob: vi.fn(),
@ -16,8 +21,19 @@ const mocks = vi.hoisted(() => ({
vi.mock('../../src/storage/repo-manager.js', async (importOriginal) => ({
...(await importOriginal<typeof import('../../src/storage/repo-manager.js')>()),
loadMeta: mocks.loadMeta,
saveMeta: mocks.saveMeta,
listRegisteredRepos: mocks.listRegisteredRepos,
}));
vi.mock('../../src/storage/index-lock.js', async (importOriginal) => ({
...(await importOriginal<typeof import('../../src/storage/index-lock.js')>()),
acquireIndexLock: mocks.acquireIndexLock,
}));
vi.mock('../../src/core/shared-store-analyze.js', () => ({
ensurePrivateSharedGraph: mocks.ensurePrivateSharedGraph,
}));
vi.mock('../../src/core/embeddings/embedding-pipeline.js', () => ({
runEmbeddingPipeline: mocks.runEmbeddingPipeline,
}));
vi.mock('../../src/storage/storage-resolver.js', async (importOriginal) => ({
...(await importOriginal<typeof import('../../src/storage/storage-resolver.js')>()),
requireRegisteredStoragePath: vi.fn(async (entry: { storagePath: string }) => entry.storagePath),
@ -116,6 +132,19 @@ afterAll(() => {
beforeEach(() => {
vi.clearAllMocks();
mocks.acquireIndexLock.mockResolvedValue({
release: mocks.releaseIndexLock,
record: {
v: 1,
pid: process.pid,
hostname: 'test-host',
startTime: null,
token: 'test-lock',
invocationId: 'test-run',
acquiredAt: '',
},
});
mocks.ensurePrivateSharedGraph.mockResolvedValue(true);
mocks.listRegisteredRepos.mockResolvedValue([entry]);
mocks.withLbugDb.mockImplementation(async (_path, callback) => callback());
mocks.search.mockImplementation(async (_query, _limit, _exec, reason) => ({
@ -124,6 +153,145 @@ beforeEach(() => {
}));
});
describe('POST /api/embed staged recovery preflight', () => {
afterEach(() => {
vi.unstubAllEnvs();
fs.rmSync(entry.storagePath, { recursive: true, force: true });
fs.mkdirSync(entry.storagePath, { recursive: true });
});
async function useRealIndexLock() {
vi.stubEnv('GITNEXUS_INDEX_LOCK_BACKEND', 'file');
const actual = await vi.importActual<typeof import('../../src/storage/index-lock.js')>(
'../../src/storage/index-lock.js',
);
mocks.acquireIndexLock.mockImplementation(
async (...args: Parameters<typeof actual.acquireIndexLock>) => {
const lock = await actual.acquireIndexLock(...args);
return {
...lock,
release: () => {
lock.release();
mocks.releaseIndexLock();
},
};
},
);
}
it.each([
{
name: 'valid staged receipt',
recovery: {
stagingFile: 'lbug.staging.12345678-1234-4123-8123-123456789abc',
schemaFingerprint: 'test-schema',
unsafeNodeIds: ['n2', 'inherited-window-node'],
},
},
{ name: 'null receipt', recovery: null },
{ name: 'malformed receipt', recovery: { stagingFile: 'invalid' } },
{ name: 'false receipt', recovery: false },
])('preserves a $name and releases the job locks', async ({ recovery }) => {
await useRealIndexLock();
const lockPath = path.join(entry.storagePath, 'analyze.lock');
const lbugPath = path.join(entry.storagePath, 'lbug');
const metaPath = path.join(entry.storagePath, 'gitnexus.json');
const sourcePath = path.join(
entry.storagePath,
'lbug.staging.12345678-1234-4123-8123-123456789abc',
);
fs.writeFileSync(lbugPath, 'published graph');
fs.writeFileSync(sourcePath, 'completed paid vectors');
fs.writeFileSync(`${sourcePath}.wal`, 'unfinished window');
const metadataBytes = JSON.stringify({
repoPath: entry.path,
lastCommit: 'abc123',
indexedAt: '2026-01-01T00:00:00.000Z',
stats: { embeddings: 7 },
embeddingCheckpoint: {
at: '2026-01-01T00:00:00.000Z',
nodesProcessed: 1,
totalNodes: 2,
chunksProcessed: 1,
model: 'test-model',
dimensions: 768,
provider: 'local',
kind: 'interrupted',
pendingNodeIds: ['n2'],
recovery,
},
});
fs.writeFileSync(metaPath, metadataBytes);
mocks.loadMeta.mockImplementation(async () => {
expect(fs.existsSync(lockPath)).toBe(true);
return JSON.parse(fs.readFileSync(metaPath, 'utf8'));
});
mocks.withLbugDb.mockResolvedValue(undefined);
await invoke('/api/embed');
await vi.waitFor(() => expect(mocks.releaseIndexLock).toHaveBeenCalledTimes(1));
expect(mocks.updateJob).toHaveBeenCalledWith(
'embed-job',
expect.objectContaining({
status: 'failed',
error: expect.stringMatching(
/staged embeddings.*Run `gitnexus analyze` to recover them first/,
),
}),
);
expect(mocks.acquireIndexLock).toHaveBeenCalledWith(entry.storagePath, { sweep: false });
expect(mocks.loadMeta.mock.invocationCallOrder[0]).toBeGreaterThan(
mocks.acquireIndexLock.mock.invocationCallOrder[0]!,
);
expect(mocks.ensurePrivateSharedGraph).not.toHaveBeenCalled();
expect(mocks.withLbugDb).not.toHaveBeenCalled();
expect(mocks.runEmbeddingPipeline).not.toHaveBeenCalled();
expect(mocks.saveMeta).not.toHaveBeenCalled();
expect(fs.existsSync(lockPath)).toBe(false);
expect(fs.readFileSync(metaPath, 'utf8')).toBe(metadataBytes);
expect(fs.readFileSync(lbugPath, 'utf8')).toBe('published graph');
expect(fs.readFileSync(sourcePath, 'utf8')).toBe('completed paid vectors');
expect(fs.readFileSync(`${sourcePath}.wal`, 'utf8')).toBe('unfinished window');
// A second accepted job proves the in-memory repo lock was also released.
await invoke('/api/embed');
await vi.waitFor(() => expect(mocks.releaseIndexLock).toHaveBeenCalledTimes(2));
expect(fs.existsSync(lockPath)).toBe(false);
});
it('sweeps orphaned staging files before a writable job without a recovery receipt', async () => {
await useRealIndexLock();
const metaPath = path.join(entry.storagePath, 'gitnexus.json');
fs.writeFileSync(metaPath, JSON.stringify({ repoPath: entry.path }));
const sourcePath = path.join(
entry.storagePath,
'lbug.staging.12345678-1234-4123-8123-123456789abc',
);
fs.writeFileSync(sourcePath, 'orphaned database');
fs.writeFileSync(`${sourcePath}.wal`, 'orphaned WAL');
mocks.loadMeta.mockImplementation(async () => JSON.parse(fs.readFileSync(metaPath, 'utf8')));
mocks.ensurePrivateSharedGraph.mockImplementation(async () => {
expect(fs.existsSync(path.join(entry.storagePath, 'analyze.lock'))).toBe(true);
expect(fs.existsSync(sourcePath)).toBe(false);
expect(fs.existsSync(`${sourcePath}.wal`)).toBe(false);
return true;
});
mocks.withLbugDb.mockResolvedValue(undefined);
await invoke('/api/embed');
await vi.waitFor(() => expect(mocks.releaseIndexLock).toHaveBeenCalledTimes(1));
expect(mocks.updateJob).toHaveBeenCalledWith(
'embed-job',
expect.objectContaining({ status: 'complete' }),
);
expect(mocks.ensurePrivateSharedGraph).toHaveBeenCalledTimes(1);
expect(mocks.withLbugDb).toHaveBeenCalledTimes(1);
expect(fs.existsSync(path.join(entry.storagePath, 'analyze.lock'))).toBe(false);
});
});
async function invoke(route: string, query: Record<string, unknown> = {}) {
const layer = app.router.stack.find((item: any) => item.route?.path === route);
expect(layer, route).toBeDefined();
@ -257,7 +425,9 @@ describe('serve uses one metadata-derived FTS mode on every DB-open path', () =>
expect.any(Function),
skip ? { skipFts: true } : {},
);
expect(mocks.loadMeta).toHaveBeenCalledExactlyOnceWith(entry.storagePath);
expect(mocks.loadMeta).toHaveBeenCalledTimes(2);
expect(mocks.loadMeta).toHaveBeenNthCalledWith(1, entry.storagePath);
expect(mocks.loadMeta).toHaveBeenNthCalledWith(2, entry.storagePath);
},
);
});

17
gitnexus/test/unit/calltool-dispatch-id-bridge.test.ts
View file

@ -159,9 +159,8 @@ describe('LocalBackend PDG impact — resolved-callee-id bridge (U6)', () => {
if (query.includes('r.type IN $relTypes') && !query.includes('STEP_IN_PROCESS')) {
return [frontierRow('func:callee-A', 'callee')];
}
if (query.includes('COUNT(DISTINCT s.id)') || query.includes('RETURN s.id AS sid')) return [];
// Target resolution (WHERE n.name = $symName) and any other read.
return [TARGET_ROW];
if (query.includes('WHERE n.name = $symName')) return [TARGET_ROW];
return [];
});
const result = await backend.callTool('impact', {
@ -195,8 +194,8 @@ describe('LocalBackend PDG impact — resolved-callee-id bridge (U6)', () => {
if (query.includes('r.type IN $relTypes') && !query.includes('STEP_IN_PROCESS')) {
return [frontierRow('func:callee-A', 'callee')];
}
if (query.includes('COUNT(DISTINCT s.id)') || query.includes('RETURN s.id AS sid')) return [];
return [TARGET_ROW];
if (query.includes('WHERE n.name = $symName')) return [TARGET_ROW];
return [];
});
const result = await backend.callTool('impact', {
@ -230,8 +229,8 @@ describe('LocalBackend PDG impact — resolved-callee-id bridge (U6)', () => {
if (query.includes('r.type IN $relTypes') && !query.includes('STEP_IN_PROCESS')) {
return [frontierRow('func:callee-A', 'callee'), frontierRow('func:callee-B', 'callee')];
}
if (query.includes('COUNT(DISTINCT s.id)') || query.includes('RETURN s.id AS sid')) return [];
return [TARGET_ROW];
if (query.includes('WHERE n.name = $symName')) return [TARGET_ROW];
return [];
});
const result = await backend.callTool('impact', {
@ -266,8 +265,8 @@ describe('LocalBackend PDG impact — resolved-callee-id bridge (U6)', () => {
if (query.includes('r.type IN $relTypes') && !query.includes('STEP_IN_PROCESS')) {
return [frontierRow('func:callee-A', 'callee'), frontierRow('*', 'callee')];
}
if (query.includes('COUNT(DISTINCT s.id)') || query.includes('RETURN s.id AS sid')) return [];
return [TARGET_ROW];
if (query.includes('WHERE n.name = $symName')) return [TARGET_ROW];
return [];
});
const result = await backend.callTool('impact', {

104
gitnexus/test/unit/calltool-dispatch.test.ts
View file

@ -183,6 +183,16 @@ function setupNoRepos() {
(listRegisteredRepos as any).mockResolvedValue([]);
}
/** Seed resolver rows without inventing relationship/process rows for other projections. */
function mockSymbolRows(rows: Record<string, unknown>[]) {
(executeParameterized as any).mockImplementation(
async (_repo: string, query: string, params: Record<string, unknown>) => {
if (query.includes('COUNT(*) AS total')) return [{ total: rows.length }];
return params?.symName || params?.uid ? rows : [];
},
);
}
const duplicateFixtureDirs: string[] = [];
function makeDuplicateNameFixture() {
@ -1321,7 +1331,7 @@ describe('LocalBackend.callTool', () => {
});
it('dispatches context tool', async () => {
(executeParameterized as any).mockResolvedValue([
mockSymbolRows([
{
id: 'func:main',
name: 'main',
@ -1663,27 +1673,22 @@ describe('LocalBackend.callTool', () => {
});
it('exact File path wins over suffixed matches during qualified resolution (#3084 review P2)', async () => {
(executeParameterized as any).mockImplementation(async (_repo: string, query: string) => {
if (query.startsWith('MATCH (n)')) {
return [
{
id: 'File:src/lib/a.ts',
name: 'a.ts',
filePath: 'src/lib/a.ts',
kind: 'File',
total_hits: 1,
},
{
id: 'File:lib/a.ts',
name: 'a.ts',
filePath: 'lib/a.ts',
kind: 'File',
total_hits: 1,
},
];
}
return [{ total: 2 }];
});
mockSymbolRows([
{
id: 'File:src/lib/a.ts',
name: 'a.ts',
filePath: 'src/lib/a.ts',
kind: 'File',
total_hits: 1,
},
{
id: 'File:lib/a.ts',
name: 'a.ts',
filePath: 'lib/a.ts',
kind: 'File',
total_hits: 1,
},
]);
const result = await backend.callTool('context', { name: 'lib/a.ts' });
expect(result).toMatchObject({
@ -2005,7 +2010,7 @@ describe('LocalBackend.callTool', () => {
});
it('context tool ranks file_path match higher than non-match (#470)', async () => {
(executeParameterized as any).mockResolvedValue([
mockSymbolRows([
{
id: 'func:handleConnect:1',
name: 'handleConnect',
@ -2044,7 +2049,7 @@ describe('LocalBackend.callTool', () => {
// review): both candidates satisfy the file_path hint (so DB
// pre-filter would return both in production), and promotion is
// determined purely by the combined file_path + kind score.
(executeParameterized as any).mockResolvedValue([
mockSymbolRows([
{
id: 'fn:App:1',
name: 'render',
@ -2135,7 +2140,7 @@ describe('LocalBackend.callTool', () => {
it('impact tool returns ambiguous shape with ranked candidates when target has multiple matches (#470)', async () => {
// resolveSymbolCandidates issues a single name query; mock it to return
// two Function rows in different files with no hints.
(executeParameterized as any).mockResolvedValue([
mockSymbolRows([
{
id: 'func:login:1',
name: 'login',
@ -2222,7 +2227,7 @@ describe('LocalBackend.callTool', () => {
// Resolver returns target; BFS returns one frontier caller; no STEP_IN_PROCESS rows.
(executeParameterized as any).mockImplementation((_repoId: string, cypher: string) => {
// BFS frontier query is now parameterized (#1907 U3).
if (cypher.includes('r.type IN') && !cypher.includes('STEP_IN_PROCESS')) {
if (cypher.includes('$frontierIds')) {
return Promise.resolve([
{
id: 'func:caller',
@ -2234,10 +2239,12 @@ describe('LocalBackend.callTool', () => {
},
]);
}
// Symbol resolution.
return Promise.resolve([
{ id: 'func:main', name: 'main', type: 'Function', filePath: 'src/index.ts' },
]);
// Symbol resolution; unseeded enrichment queries return no rows.
return Promise.resolve(
cypher.includes('$symName')
? [{ id: 'func:main', name: 'main', type: 'Function', filePath: 'src/index.ts' }]
: [],
);
});
(executeQuery as any).mockResolvedValue([]);
@ -2974,7 +2981,7 @@ describe('LocalBackend.callTool', () => {
});
it('dispatches "explore" as alias for context', async () => {
(executeParameterized as any).mockResolvedValue([
mockSymbolRows([
{
id: 'func:main',
name: 'main',
@ -3007,9 +3014,7 @@ describe('LocalBackend impact mode (KTD1/KTD5/KTD12)', () => {
// dispatch (callgraph BFS or the PDG traversal). The callgraph BFS then issues
// executeQuery for its frontier; the PDG path delegates to runImpactPDG.
function resolveSingleTarget() {
(executeParameterized as any).mockResolvedValue([
{ id: 'func:main', name: 'main', type: 'Function', filePath: 'src/index.ts' },
]);
mockSymbolRows([{ id: 'func:main', name: 'main', type: 'Function', filePath: 'src/index.ts' }]);
(executeQuery as any).mockResolvedValue([]);
}
@ -3266,18 +3271,13 @@ describe('LocalBackend impact mode (KTD1/KTD5/KTD12)', () => {
it("mode:'pdg' + downstream line:8 routes to the PDG traversal and seeds bridge evidence", async () => {
resolveSingleTarget();
// The target-resolution row doubles as the calleesOfBlocks row: `callees`
// ('callee') is the leaf name persisted on the slice's BasicBlock, the
// statement-precise substrate the bridge keys on.
(executeParameterized as any).mockResolvedValue([
{
id: 'func:main',
name: 'main',
type: 'Function',
filePath: 'src/index.ts',
callees: 'callee',
},
]);
// BasicBlock callees and symbol lookup use distinct native projections.
vi.mocked(executeParameterized).mockImplementation(async (_repo, query) => {
if (query.includes('RETURN b.callees')) return [{ callees: 'callee' }];
return query.includes('$symName')
? [{ id: 'func:main', name: 'main', type: 'Function', filePath: 'src/index.ts' }]
: [];
});
// A line-seeded downstream slice with one reachable block → the dispatch
// queries that block's callees and seeds the bridge with them.
const pdgSpy = vi.spyOn(backend as any, '_runImpactPDG').mockResolvedValueOnce({
@ -3402,11 +3402,13 @@ describe('LocalBackend impact mode (KTD1/KTD5/KTD12)', () => {
// is not built and the inter-procedural reach falls back to callgraph-equal —
// never surfacing the error or producing a partial proven/unproven labeling.
resolveSingleTarget();
// The slice-callees query (RETURN b.callees) throws; every other query (target
// resolution) returns the resolved symbol row.
// The slice-callees query throws; lookup returns the target and unseeded
// relationship/process projections return no rows.
vi.mocked(executeParameterized).mockImplementation(async (_repo, query) => {
if (query.includes('RETURN b.callees')) throw new Error('slice-callees query failed');
return [{ id: 'func:main', name: 'main', type: 'Function', filePath: 'src/index.ts' }];
return query.includes('$symName')
? [{ id: 'func:main', name: 'main', type: 'Function', filePath: 'src/index.ts' }]
: [];
});
// A line-seeded downstream slice so calleesOfBlocks is attempted.
vi.spyOn(backend as any, '_runImpactPDG').mockResolvedValueOnce({
@ -3461,7 +3463,9 @@ describe('LocalBackend impact mode (KTD1/KTD5/KTD12)', () => {
resolveSingleTarget();
vi.mocked(executeParameterized).mockImplementation(async (_repo, query) => {
if (query.includes('RETURN b.callees')) throw new Error('Table BasicBlock does not exist');
return [{ id: 'func:main', name: 'main', type: 'Function', filePath: 'src/index.ts' }];
return query.includes('$symName')
? [{ id: 'func:main', name: 'main', type: 'Function', filePath: 'src/index.ts' }]
: [];
});
vi.spyOn(backend as any, '_runImpactPDG').mockResolvedValueOnce({
mode: 'pdg',

199
gitnexus/test/unit/embedding-recovery-race.test.ts Normal file
View file

@ -0,0 +1,199 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import * as fs from 'node:fs';
import { execFileSync } from 'node:child_process';
import os from 'node:os';
import path from 'node:path';
import { readEmbeddingRecovery } from '../../src/storage/embedding-recovery.js';
vi.mock('node:fs', async (importOriginal) => {
const actual = await importOriginal<typeof import('node:fs')>();
return {
...actual,
constants: { ...actual.constants },
lstatSync: vi.fn(actual.lstatSync),
openSync: vi.fn(actual.openSync),
fstatSync: vi.fn(actual.fstatSync),
readFileSync: vi.fn(actual.readFileSync),
closeSync: vi.fn(actual.closeSync),
};
});
const actual = await vi.importActual<typeof import('node:fs')>('node:fs');
const stagingFile = 'lbug.staging.6e34c761-bf58-46cc-8b54-78d11607bc46';
const receipt = {
embeddingCheckpoint: {
kind: 'interrupted',
at: '2026-10-03T12:00:00.000Z',
nodesProcessed: 1,
totalNodes: 2,
chunksProcessed: 1,
model: 'test-model',
dimensions: 2,
provider: 'local',
recovery: { stagingFile, schemaFingerprint: 'test-schema', unsafeNodeIds: [] },
},
};
let dir: string;
let metadataPath: string;
beforeEach(() => {
vi.mocked(fs.lstatSync).mockImplementation(actual.lstatSync);
vi.mocked(fs.openSync).mockImplementation(actual.openSync);
vi.mocked(fs.fstatSync).mockImplementation(actual.fstatSync);
vi.mocked(fs.readFileSync).mockImplementation(actual.readFileSync);
vi.mocked(fs.closeSync).mockImplementation(actual.closeSync);
Object.assign(fs.constants, actual.constants);
vi.clearAllMocks();
dir = actual.mkdtempSync(path.join(os.tmpdir(), 'gnx-recovery-metadata-race-'));
metadataPath = path.join(dir, 'gitnexus.json');
actual.writeFileSync(path.join(dir, stagingFile), 'stage');
});
afterEach(() => actual.rmSync(dir, { recursive: true, force: true }));
describe('readEmbeddingRecovery metadata races', () => {
it('does not read replacement metadata after checking the original file', () => {
actual.writeFileSync(metadataPath, JSON.stringify({ embeddingCheckpoint: null }));
let replaced = false;
vi.mocked(fs.lstatSync).mockImplementation((...args) => {
const stat = actual.lstatSync(...args);
if (args[0] === metadataPath && !replaced) {
replaced = true;
actual.renameSync(metadataPath, path.join(dir, 'original-metadata.json'));
actual.writeFileSync(metadataPath, JSON.stringify(receipt));
}
return stat;
});
expect(readEmbeddingRecovery(dir)).toBeUndefined();
expect(replaced).toBe(true);
const descriptor = vi.mocked(fs.openSync).mock.results[0]?.value;
expect(typeof descriptor).toBe('number');
expect(fs.readFileSync).toHaveBeenCalledWith(descriptor, 'utf8');
expect(fs.closeSync).toHaveBeenCalledWith(descriptor);
});
it('rejects a file replaced between opening and checking its identity', () => {
actual.writeFileSync(metadataPath, JSON.stringify(receipt));
let replaced = false;
vi.mocked(fs.openSync).mockImplementation((...args) => {
const descriptor = actual.openSync(...args);
if (args[0] === metadataPath && !replaced) {
replaced = true;
actual.renameSync(metadataPath, path.join(dir, 'original-metadata.json'));
actual.writeFileSync(metadataPath, JSON.stringify(receipt));
}
return descriptor;
});
expect(readEmbeddingRecovery(dir)).toBeUndefined();
expect(replaced).toBe(true);
expect(fs.readFileSync).not.toHaveBeenCalled();
expect(fs.closeSync).toHaveBeenCalledOnce();
});
it('reads regular metadata when no-follow opens are unavailable', () => {
Object.assign(fs.constants, { O_NOFOLLOW: 0, O_NONBLOCK: 0 });
actual.writeFileSync(metadataPath, JSON.stringify(receipt));
expect(readEmbeddingRecovery(dir)?.stagingFile).toBe(stagingFile);
expect(fs.closeSync).toHaveBeenCalledOnce();
});
it('refuses unverifiable file identity when no-follow opens are unavailable', () => {
Object.assign(fs.constants, { O_NOFOLLOW: 0, O_NONBLOCK: 0 });
actual.writeFileSync(metadataPath, JSON.stringify(receipt));
vi.mocked(fs.fstatSync).mockImplementation((...args) => {
const stat = actual.fstatSync(...args);
Object.defineProperty(stat, 'ino', { value: 0n });
return stat;
});
vi.mocked(fs.lstatSync).mockImplementation((...args) => {
const stat = actual.lstatSync(...args);
Object.defineProperty(stat, 'ino', { value: 0n });
return stat;
});
expect(readEmbeddingRecovery(dir)).toBeUndefined();
expect(fs.readFileSync).not.toHaveBeenCalled();
expect(fs.closeSync).toHaveBeenCalledOnce();
});
it('rejects a symlink introduced before opening without no-follow support', () => {
Object.assign(fs.constants, { O_NOFOLLOW: 0, O_NONBLOCK: 0 });
actual.writeFileSync(metadataPath, JSON.stringify({ embeddingCheckpoint: null }));
const target = path.join(dir, 'foreign-metadata.json');
actual.writeFileSync(target, JSON.stringify(receipt));
let replaced = false;
vi.mocked(fs.openSync).mockImplementation((...args) => {
if (args[0] === metadataPath && !replaced) {
replaced = true;
actual.rmSync(metadataPath);
actual.symlinkSync(target, metadataPath);
}
return actual.openSync(...args);
});
expect(readEmbeddingRecovery(dir)).toBeUndefined();
expect(replaced).toBe(true);
expect(fs.readFileSync).not.toHaveBeenCalled();
expect(fs.closeSync).toHaveBeenCalledOnce();
});
it('never falls back from a dangling primary symlink without no-follow support', () => {
Object.assign(fs.constants, { O_NOFOLLOW: 0, O_NONBLOCK: 0 });
actual.symlinkSync(path.join(dir, 'missing-metadata.json'), metadataPath);
actual.writeFileSync(path.join(dir, 'meta.json'), JSON.stringify(receipt));
expect(readEmbeddingRecovery(dir)).toBeUndefined();
expect(fs.readFileSync).not.toHaveBeenCalled();
});
it('rejects a symlinked legacy receipt when the primary is absent', () => {
Object.assign(fs.constants, { O_NOFOLLOW: 0, O_NONBLOCK: 0 });
const target = path.join(dir, 'foreign-metadata.json');
actual.writeFileSync(target, JSON.stringify(receipt));
actual.symlinkSync(target, path.join(dir, 'meta.json'));
expect(readEmbeddingRecovery(dir)).toBeUndefined();
expect(fs.readFileSync).not.toHaveBeenCalled();
expect(fs.closeSync).toHaveBeenCalledOnce();
});
it('closes a descriptor when fstat fails without falling back to legacy metadata', () => {
actual.writeFileSync(metadataPath, JSON.stringify(receipt));
actual.writeFileSync(path.join(dir, 'meta.json'), JSON.stringify(receipt));
vi.mocked(fs.fstatSync).mockImplementationOnce(() => {
throw Object.assign(new Error('stat failed'), { code: 'EIO' });
});
expect(readEmbeddingRecovery(dir)).toBeUndefined();
expect(fs.readFileSync).not.toHaveBeenCalled();
expect(fs.closeSync).toHaveBeenCalledOnce();
});
it('closes a descriptor when JSON parsing fails without falling back', () => {
actual.writeFileSync(metadataPath, '{');
actual.writeFileSync(path.join(dir, 'meta.json'), JSON.stringify(receipt));
expect(readEmbeddingRecovery(dir)).toBeUndefined();
expect(fs.closeSync).toHaveBeenCalledOnce();
});
it.skipIf(process.platform === 'win32')('rejects a substituted FIFO without blocking', () => {
actual.writeFileSync(metadataPath, JSON.stringify(receipt));
let replaced = false;
vi.mocked(fs.openSync).mockImplementation((...args) => {
if (args[0] === metadataPath && !replaced) {
replaced = true;
actual.rmSync(metadataPath);
execFileSync('mkfifo', [metadataPath]);
}
return actual.openSync(...args);
});
expect(readEmbeddingRecovery(dir)).toBeUndefined();
expect(replaced).toBe(true);
expect(fs.readFileSync).not.toHaveBeenCalled();
expect(fs.closeSync).toHaveBeenCalledOnce();
});
});

175
gitnexus/test/unit/embedding-recovery.test.ts Normal file
View file

@ -0,0 +1,175 @@
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { mkdtempSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import {
readEmbeddingRecovery,
resolveEmbeddingRecovery,
} from '../../src/storage/embedding-recovery.js';
const stagingFile = 'lbug.staging.6e34c761-bf58-46cc-8b54-78d11607bc46';
const familySuffixes = [
'',
'.wal',
'.shadow',
'.wal.checkpoint',
'.lock',
'.checkpoint.intent.lock',
'.checkpoint.apply.lock',
];
const checkpoint = () => ({
kind: 'interrupted',
at: '2026-10-03T12:00:00.000Z',
nodesProcessed: 1,
totalNodes: 3,
chunksProcessed: 2,
model: 'test-model',
dimensions: 2,
provider: 'local',
pendingNodeIds: ['active'],
recovery: {
stagingFile,
schemaFingerprint: 'test-schema',
unsafeNodeIds: ['active', 'incomplete-restore'],
},
});
let dir: string;
beforeEach(() => {
dir = mkdtempSync(path.join(os.tmpdir(), 'gnx-embedding-recovery-'));
writeFileSync(path.join(dir, stagingFile), 'stage');
});
afterEach(() => rmSync(dir, { recursive: true, force: true }));
describe('resolveEmbeddingRecovery', () => {
it('resolves the exact staged generation and carries all unsafe node IDs', () => {
expect(resolveEmbeddingRecovery(dir, checkpoint())).toEqual({
...checkpoint().recovery,
dbPath: path.join(dir, stagingFile),
familyFiles: familySuffixes.map((suffix) => stagingFile + suffix),
});
});
it.each([
'../lbug.staging.6e34c761-bf58-46cc-8b54-78d11607bc46',
'/tmp/lbug.staging.6e34c761-bf58-46cc-8b54-78d11607bc46',
'branches/foreign/lbug.staging.6e34c761-bf58-46cc-8b54-78d11607bc46',
'..\\lbug.staging.6e34c761-bf58-46cc-8b54-78d11607bc46',
'lbug',
'lbug.new',
'lbug.staging.orphan',
`${stagingFile}.wal`,
'lbug.staging.00000000-0000-4000-8000-000000000000',
])('rejects a foreign, unrecognized or missing generation: %s', (filename) => {
const marker = checkpoint();
marker.recovery.stagingFile = filename;
expect(resolveEmbeddingRecovery(dir, marker)).toBeUndefined();
});
it.each([
null,
[],
{ recovery: checkpoint().recovery },
{ ...checkpoint(), kind: 'partial' },
{ ...checkpoint(), kind: 'unverified-count' },
{ ...checkpoint(), kind: 'unknown' },
{ ...checkpoint(), at: 'invalid-time' },
{ ...checkpoint(), nodesProcessed: -1 },
{ ...checkpoint(), nodesProcessed: 4 },
{ ...checkpoint(), totalNodes: 1.5 },
{ ...checkpoint(), chunksProcessed: Number.NaN },
{ ...checkpoint(), model: '' },
{ ...checkpoint(), provider: null },
{ ...checkpoint(), dimensions: 0 },
{ ...checkpoint(), pendingNodeIds: [42] },
{ ...checkpoint(), pendingNodeIds: ['unexcluded'] },
{ ...checkpoint(), recovery: { ...checkpoint().recovery, schemaFingerprint: '' } },
{ ...checkpoint(), recovery: { ...checkpoint().recovery, unsafeNodeIds: undefined } },
{ ...checkpoint(), recovery: { ...checkpoint().recovery, unsafeNodeIds: [''] } },
])('rejects malformed or incompatible checkpoint shape %#', (marker) => {
expect(resolveEmbeddingRecovery(dir, marker)).toBeUndefined();
});
it('accepts a durable restored stage even before a new embedding window completes', () => {
expect(
resolveEmbeddingRecovery(dir, {
...checkpoint(),
nodesProcessed: 0,
chunksProcessed: 0,
pendingNodeIds: [],
}),
).toBeDefined();
});
it('rejects a directory in place of the staged database', () => {
rmSync(path.join(dir, stagingFile));
mkdirSync(path.join(dir, stagingFile));
expect(resolveEmbeddingRecovery(dir, checkpoint())).toBeUndefined();
});
it.each(familySuffixes)('rejects a symlink in the staged family: %s', (suffix) => {
const target = path.join(dir, 'external-file');
writeFileSync(target, 'external');
const candidate = path.join(dir, stagingFile + suffix);
rmSync(candidate, { force: true });
symlinkSync(target, candidate);
expect(resolveEmbeddingRecovery(dir, checkpoint())).toBeUndefined();
});
it.each(familySuffixes.slice(1))('rejects a dangling staged sidecar symlink: %s', (suffix) => {
symlinkSync(path.join(dir, 'missing'), path.join(dir, stagingFile + suffix));
expect(resolveEmbeddingRecovery(dir, checkpoint())).toBeUndefined();
});
it.each(familySuffixes.slice(1))('rejects a non-file staged sidecar: %s', (suffix) => {
mkdirSync(path.join(dir, stagingFile + suffix));
expect(resolveEmbeddingRecovery(dir, checkpoint())).toBeUndefined();
});
});
describe('readEmbeddingRecovery', () => {
const writeMeta = (filename: string, marker: unknown = checkpoint()): void => {
writeFileSync(path.join(dir, filename), JSON.stringify({ embeddingCheckpoint: marker }));
};
it('prefers the primary metadata file over a stale legacy reference', () => {
writeMeta('gitnexus.json');
writeMeta('meta.json', null);
expect(readEmbeddingRecovery(dir)?.stagingFile).toBe(stagingFile);
});
it('loads the legacy mirror only when the primary metadata file is absent', () => {
writeMeta('meta.json');
expect(readEmbeddingRecovery(dir)?.stagingFile).toBe(stagingFile);
});
it('does not resurrect a legacy reference when the primary file is malformed', () => {
writeFileSync(path.join(dir, 'gitnexus.json'), '{');
writeMeta('meta.json');
expect(readEmbeddingRecovery(dir)).toBeUndefined();
});
it('does not fall back from valid primary metadata with no recovery reference', () => {
writeMeta('gitnexus.json', null);
writeMeta('meta.json');
expect(readEmbeddingRecovery(dir)).toBeUndefined();
});
it('rejects symlinked primary metadata rather than reading a foreign receipt', () => {
writeMeta('meta.json');
symlinkSync(path.join(dir, 'meta.json'), path.join(dir, 'gitnexus.json'));
expect(readEmbeddingRecovery(dir)).toBeUndefined();
});
it('resolves branch-slot provenance within that slot despite a flat storagePath', () => {
const branchSlot = path.join(dir, 'branches', 'feature');
mkdirSync(branchSlot, { recursive: true });
writeFileSync(path.join(branchSlot, stagingFile), 'branch-stage');
writeFileSync(
path.join(branchSlot, 'gitnexus.json'),
JSON.stringify({ storagePath: dir, embeddingCheckpoint: checkpoint() }),
);
expect(readEmbeddingRecovery(branchSlot)?.dbPath).toBe(path.join(branchSlot, stagingFile));
expect(readEmbeddingRecovery(dir)).toBeUndefined();
});
});

116
gitnexus/test/unit/embeddings-sync-command.test.ts
View file

@ -3,13 +3,15 @@
* index lock, missing-DB preflight, identity fail-closed, tri-state count,
* closeLbug masking, and hash-only cache load.
*/
import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
const {
acquireIndexLockMock,
ensurePrivateSharedGraphMock,
releaseMock,
getStoragePathsMock,
loadMetaMock,
@ -27,6 +29,7 @@ const {
reapEmbeddingSidecarMock,
} = vi.hoisted(() => ({
acquireIndexLockMock: vi.fn(),
ensurePrivateSharedGraphMock: vi.fn(),
releaseMock: vi.fn(),
getStoragePathsMock: vi.fn(),
loadMetaMock: vi.fn(),
@ -48,6 +51,10 @@ vi.mock('../../src/storage/git.js', () => ({
getGitRoot: () => '/tmp/emb-sync-repo',
}));
vi.mock('../../src/core/shared-store-analyze.js', () => ({
ensurePrivateSharedGraph: (...args: unknown[]) => ensurePrivateSharedGraphMock(...args),
}));
vi.mock('../../src/storage/index-lock.js', async (importOriginal) => ({
...(await importOriginal<typeof import('../../src/storage/index-lock.js')>()),
acquireIndexLock: (...args: unknown[]) => acquireIndexLockMock(...args),
@ -113,6 +120,25 @@ async function run(inputPath = '/tmp/emb-sync-repo') {
await embeddingsSyncCommand(inputPath);
}
async function useRealIndexLock() {
vi.stubEnv('GITNEXUS_INDEX_LOCK_BACKEND', 'file');
const actual = await vi.importActual<typeof import('../../src/storage/index-lock.js')>(
'../../src/storage/index-lock.js',
);
acquireIndexLockMock.mockImplementation(
async (...args: Parameters<typeof actual.acquireIndexLock>) => {
const lock = await actual.acquireIndexLock(...args);
return {
...lock,
release: () => {
lock.release();
releaseMock();
},
};
},
);
}
describe('embeddingsSyncCommand writer safety (#3065)', () => {
const tmpDirs: string[] = [];
const originalEmbeddingUrl = process.env.GITNEXUS_EMBEDDING_URL;
@ -132,6 +158,7 @@ describe('embeddingsSyncCommand writer safety (#3065)', () => {
beforeEach(() => {
vi.resetModules();
acquireIndexLockMock.mockReset().mockResolvedValue(lockHandle());
ensurePrivateSharedGraphMock.mockReset().mockResolvedValue(true);
releaseMock.mockReset();
getStoragePathsMock.mockReset();
loadMetaMock.mockReset().mockResolvedValue({ ...BASE_META });
@ -156,6 +183,7 @@ describe('embeddingsSyncCommand writer safety (#3065)', () => {
});
afterEach(async () => {
vi.unstubAllEnvs();
if (originalEmbeddingUrl === undefined) delete process.env.GITNEXUS_EMBEDDING_URL;
else process.env.GITNEXUS_EMBEDDING_URL = originalEmbeddingUrl;
if (originalEmbeddingModel === undefined) delete process.env.GITNEXUS_EMBEDDING_MODEL;
@ -183,7 +211,7 @@ describe('embeddingsSyncCommand writer safety (#3065)', () => {
await run();
expect(acquireIndexLockMock).toHaveBeenCalledWith(dir);
expect(acquireIndexLockMock).toHaveBeenCalledWith(dir, { sweep: false });
expect(order[0]).toBe('lock');
expect(order.indexOf('loadMeta')).toBeGreaterThan(order.indexOf('lock'));
expect(order.indexOf('init')).toBeGreaterThan(order.indexOf('loadMeta'));
@ -299,6 +327,90 @@ describe('embeddingsSyncCommand writer safety (#3065)', () => {
expect(releaseMock).toHaveBeenCalled();
});
it.each([
{
name: 'valid staged receipt',
recovery: {
stagingFile: 'lbug.staging.12345678-1234-4123-8123-123456789abc',
schemaFingerprint: 'test-schema',
unsafeNodeIds: ['n2', 'inherited-window-node'],
},
},
{ name: 'null receipt', recovery: null },
{ name: 'malformed receipt', recovery: { stagingFile: 'invalid' } },
{ name: 'false receipt', recovery: false },
])('preserves a $name before any writable sync work', async ({ recovery }) => {
const { dir, lbugPath, metaPath } = await store();
await useRealIndexLock();
const lockPath = path.join(dir, 'analyze.lock');
const sourcePath = path.join(dir, 'lbug.staging.12345678-1234-4123-8123-123456789abc');
await writeFile(sourcePath, 'completed paid vectors');
await writeFile(`${sourcePath}.wal`, 'unfinished window');
const metadataBytes = JSON.stringify({
...BASE_META,
embeddingCheckpoint: {
...IDENTITY,
at: '2026-01-01T00:00:00.000Z',
nodesProcessed: 1,
totalNodes: 2,
chunksProcessed: 1,
kind: 'interrupted',
pendingNodeIds: ['n2'],
recovery,
},
});
await writeFile(metaPath, metadataBytes);
loadMetaMock.mockImplementation(async () => {
expect(existsSync(lockPath)).toBe(true);
return JSON.parse(await readFile(metaPath, 'utf8'));
});
resolveEmbeddingRuntimeMock.mockReturnValue(null);
await expect(run()).rejects.toThrow(
/staged embeddings.*Run `gitnexus analyze` to recover them first/,
);
expect(acquireIndexLockMock).toHaveBeenCalledWith(dir, { sweep: false });
expect(loadMetaMock.mock.invocationCallOrder[0]).toBeGreaterThan(
acquireIndexLockMock.mock.invocationCallOrder[0]!,
);
expect(ensurePrivateSharedGraphMock).not.toHaveBeenCalled();
expect(resolveEmbeddingIdentityMock).not.toHaveBeenCalled();
expect(installEmbeddingRuntimeMock).not.toHaveBeenCalled();
expect(initLbugMock).not.toHaveBeenCalled();
expect(runEmbeddingPipelineMock).not.toHaveBeenCalled();
expect(saveMetaMock).not.toHaveBeenCalled();
expect(releaseMock).toHaveBeenCalledTimes(1);
expect(existsSync(lockPath)).toBe(false);
expect(await readFile(metaPath, 'utf8')).toBe(metadataBytes);
expect(await readFile(lbugPath, 'utf8')).toBe('db');
expect(await readFile(sourcePath, 'utf8')).toBe('completed paid vectors');
expect(await readFile(`${sourcePath}.wal`, 'utf8')).toBe('unfinished window');
});
it('sweeps orphaned staging files before writable sync work without a recovery receipt', async () => {
const { dir, metaPath } = await store();
await useRealIndexLock();
await writeFile(metaPath, JSON.stringify(BASE_META));
const sourcePath = path.join(dir, 'lbug.staging.12345678-1234-4123-8123-123456789abc');
await writeFile(sourcePath, 'orphaned database');
await writeFile(`${sourcePath}.wal`, 'orphaned WAL');
loadMetaMock.mockImplementation(async () => JSON.parse(await readFile(metaPath, 'utf8')));
ensurePrivateSharedGraphMock.mockImplementation(async () => {
expect(existsSync(path.join(dir, 'analyze.lock'))).toBe(true);
expect(existsSync(sourcePath)).toBe(false);
expect(existsSync(`${sourcePath}.wal`)).toBe(false);
return true;
});
await run();
expect(ensurePrivateSharedGraphMock).toHaveBeenCalledTimes(1);
expect(runEmbeddingPipelineMock).toHaveBeenCalledTimes(1);
expect(releaseMock).toHaveBeenCalledTimes(1);
expect(existsSync(path.join(dir, 'analyze.lock'))).toBe(false);
});
it('persists an interrupted checkpoint from the pipeline checkpoint callbacks', async () => {
// The resume contract lives in these callbacks; a mock that never invokes
// them leaves the whole save path unexecuted.

21
gitnexus/test/unit/impact-batching-grouping.test.ts
View file

@ -79,6 +79,8 @@ describe('impact: batching and grouping', () => {
// Handle parameterized calls (including chunked STEP_IN_PROCESS queries)
executeParameterizedMock.mockImplementation(async (...args: any[]) => {
const query = typeof args[1] === 'string' ? args[1] : String(args[0] ?? '');
if (query.includes('RETURN h.id AS hid')) return [];
if (query.includes('RETURN s.id AS sid')) return [];
const params = args[2] || {};
// Match only the aggregation chunk (which uses COUNT(DISTINCT s.id)),
// not the per-symbol enrichment pass added by impact byDepth processes
@ -91,6 +93,7 @@ describe('impact: batching and grouping', () => {
const idx = chunkCallIndex++;
return [
{
pId: 'proc-' + idx,
entryPointId: `ep-${Math.floor(idx)}`,
epName: `epName-${idx}`,
epType: 'Function',
@ -148,6 +151,8 @@ describe('impact: batching and grouping', () => {
executeParameterizedMock.mockImplementation(async (...args: any[]) => {
const query = typeof args[1] === 'string' ? args[1] : String(args[0] ?? '');
if (query.includes('RETURN h.id AS hid')) return [];
if (query.includes('RETURN s.id AS sid')) return [];
// BFS frontier query (parameterized #1907 U3): return 6 impacted nodes.
if (query.includes('r.type IN') && !query.includes('STEP_IN_PROCESS')) {
const res: any[] = [];
@ -166,6 +171,7 @@ describe('impact: batching and grouping', () => {
// For STEP_IN_PROCESS in this test, return grouping rows
return [
{
pId: 'proc-1a',
entryPointId: 'ep-1',
epName: 'EP1',
epType: 'Function',
@ -174,6 +180,7 @@ describe('impact: batching and grouping', () => {
minStep: 1,
},
{
pId: 'proc-2',
entryPointId: 'ep-2',
epName: 'EP2',
epType: 'Function',
@ -182,6 +189,7 @@ describe('impact: batching and grouping', () => {
minStep: 2,
},
{
pId: 'proc-1b',
entryPointId: 'ep-1',
epName: 'EP1',
epType: 'Function',
@ -190,6 +198,7 @@ describe('impact: batching and grouping', () => {
minStep: 3,
},
{
pId: 'proc-3',
entryPointId: 'ep-3',
epName: 'EP3',
epType: 'Function',
@ -245,6 +254,8 @@ describe('impact: batching and grouping', () => {
executeParameterizedMock.mockImplementation(async (...args: any[]) => {
const query = typeof args[1] === 'string' ? args[1] : String(args[0] ?? '');
if (query.includes('RETURN h.id AS hid')) return [];
if (query.includes('RETURN s.id AS sid')) return [];
const params = args[2] || {};
// Match only the aggregation chunk (which uses COUNT(DISTINCT s.id)),
// not the per-symbol enrichment pass added by impact byDepth processes
@ -254,6 +265,7 @@ describe('impact: batching and grouping', () => {
chunkSizes.push(ids.length);
return [
{
pId: 'proc-x-' + chunkSizes.length,
entryPointId: 'ep-x',
epName: 'EPX',
epType: 'Function',
@ -351,6 +363,7 @@ describe('impact: batching and grouping', () => {
executeQueryMock.mockImplementation(async () => []);
executeParameterizedMock.mockImplementation(async (...args: any[]) => {
const query = typeof args[1] === 'string' ? args[1] : String(args[0] ?? '');
if (query.includes('RETURN h.id AS hid')) return [];
if (query.includes('r.type IN') && !query.includes('STEP_IN_PROCESS')) {
return [
{
@ -394,6 +407,7 @@ describe('impact: batching and grouping', () => {
executeQueryMock.mockImplementation(async () => []);
executeParameterizedMock.mockImplementation(async (...args: any[]) => {
const query = typeof args[1] === 'string' ? args[1] : String(args[0] ?? '');
if (query.includes('RETURN h.id AS hid')) return [];
if (query.includes('STEP_IN_PROCESS')) {
throw new Error('process chunk failed');
}
@ -443,6 +457,8 @@ describe('impact: batching and grouping', () => {
executeQueryMock.mockImplementation(async () => []);
executeParameterizedMock.mockImplementation(async (...args: any[]) => {
const query = typeof args[1] === 'string' ? args[1] : String(args[0] ?? '');
if (query.includes('RETURN h.id AS hid')) return [];
if (query.includes('RETURN s.id AS sid')) return [];
if (query.includes('MEMBER_OF')) throw new Error('module chunk failed');
if (query.includes('STEP_IN_PROCESS') && query.includes('COUNT(DISTINCT s.id)')) {
return [
@ -500,6 +516,8 @@ describe('impact: batching and grouping', () => {
executeQueryMock.mockImplementation(async () => []);
executeParameterizedMock.mockImplementation(async (...args: any[]) => {
const query = typeof args[1] === 'string' ? args[1] : String(args[0] ?? '');
if (query.includes('RETURN h.id AS hid')) return [];
if (query.includes('RETURN s.id AS sid')) return [];
if (query.includes('MIN(r.step) AS minStep') && !query.includes('COUNT(DISTINCT s.id)')) {
throw new Error('minStep backfill failed');
}
@ -559,6 +577,8 @@ describe('impact: batching and grouping', () => {
let processChunk = 0;
executeParameterizedMock.mockImplementation(async (...args: any[]) => {
const query = typeof args[1] === 'string' ? args[1] : String(args[0] ?? '');
if (query.includes('RETURN h.id AS hid')) return [];
if (query.includes('RETURN s.id AS sid')) return [];
if (query.includes('STEP_IN_PROCESS') && query.includes('COUNT(DISTINCT s.id)')) {
processChunk += 1;
if (processChunk === 2) throw new Error('later process chunk failed');
@ -615,6 +635,7 @@ describe('impact: batching and grouping', () => {
executeQueryMock.mockImplementation(async () => []);
executeParameterizedMock.mockImplementation(async (...args: any[]) => {
const query = typeof args[1] === 'string' ? args[1] : String(args[0] ?? '');
if (query.includes('RETURN h.id AS hid')) return [];
if (query.includes('MEMBER_OF') && query.includes('RETURN DISTINCT c.heuristicLabel')) {
throw new Error('module classification failed');
}

847
gitnexus/test/unit/impact-context-integrity.test.ts Normal file
View file

@ -0,0 +1,847 @@
/** Corrupt detail rows must not become usable context/impact answers (#3354). */
import { beforeEach, describe, expect, it, vi } from 'vitest';
const { db, aop } = vi.hoisted(() => ({
db: {
initLbug: vi.fn().mockResolvedValue(undefined),
executeQuery: vi.fn().mockResolvedValue([]),
executeParameterized: vi.fn().mockResolvedValue([]),
closeLbug: vi.fn().mockResolvedValue(undefined),
isLbugReady: vi.fn().mockReturnValue(true),
},
aop: vi.fn().mockResolvedValue(undefined),
}));
vi.mock('../../src/core/lbug/pool-adapter.js', async (importOriginal) => ({
...(await importOriginal()),
...db,
}));
vi.mock('../../src/mcp/core/lbug-adapter.js', async (importOriginal) => ({
...(await importOriginal()),
...db,
}));
vi.mock('../../src/storage/repo-manager.js', async (importOriginal) => ({
...(await importOriginal<typeof import('../../src/storage/repo-manager.js')>()),
listRegisteredRepos: vi.fn().mockResolvedValue([
{
name: 'integrity-fixture',
path: '/tmp/integrity-fixture',
storagePath: '/tmp/integrity-fixture/.gitnexus',
indexedAt: '2026-10-03T12:00:00Z',
lastCommit: 'fixture',
stats: { files: 2, nodes: 2, edges: 1, communities: 0, processes: 1 },
},
]),
cleanupOldKuzuFiles: vi.fn().mockResolvedValue({ found: false, needsReindex: false }),
findSiblingClones: vi.fn().mockResolvedValue([]),
loadMeta: vi.fn().mockResolvedValue({
pdg: { maxCdgEdgesPerFunction: 0, maxReachingDefEdgesPerFunction: 0 },
}),
}));
vi.mock('../../src/core/git-staleness.js', () => ({
checkStalenessAsync: vi.fn().mockResolvedValue({ isStale: false, commitsBehind: 0 }),
checkStaleness: vi.fn().mockReturnValue({ isStale: false, commitsBehind: 0 }),
checkCwdMatch: vi.fn().mockResolvedValue({ match: 'none' }),
}));
vi.mock('../../src/storage/git.js', async (importOriginal) => ({
...(await importOriginal<typeof import('../../src/storage/git.js')>()),
getGitRoot: vi.fn().mockReturnValue(null),
}));
vi.mock('../../src/mcp/local/aop-metadata.js', () => ({ querySpringAopMetadata: aop }));
import { LocalBackend } from '../../src/mcp/local/local-backend.js';
import { SymbolIdentityError } from '../../src/mcp/local/query-result-integrity.js';
const TARGET = {
id: 'func:target',
name: 'target',
type: 'Function',
filePath: 'src/target.ts',
startLine: 1,
endLine: 4,
};
const REF = {
relType: 'CALLS',
uid: 'func:caller',
name: 'caller',
filePath: 'src/caller.ts',
kind: 'Function',
};
const EDGE = {
sourceId: TARGET.id,
id: REF.uid,
name: REF.name,
type: REF.kind,
filePath: REF.filePath,
relType: 'CALLS',
confidence: 1,
};
const PROCESS = {
pId: 'proc:caller',
name: 'Caller flow',
processType: 'intra_community',
entryPointId: REF.uid,
hits: 1,
minStep: 0,
stepCount: 2,
epName: REF.name,
epType: REF.kind,
epFilePath: REF.filePath,
};
const BAD = 'corrupt\0persisted-value';
type Seam =
| 'target'
| 'targetLabels'
| 'aopRows'
| 'pdgSeed'
| 'pdgNeighbor'
| 'pdgOwner'
| 'pdgStatement'
| 'pdgSelf'
| 'pdgCalleeBlocks'
| 'pdgSummary'
| 'pdgSpans'
| 'incoming'
| 'classIncoming'
| 'outgoing'
| 'typedProperties'
| 'contextProcess'
| 'contextRoute'
| 'interfaceBoundary'
| 'interfaceCount'
| 'chain'
| 'seeds'
| 'members'
| 'frontier'
| 'process'
| 'backfill'
| 'membership'
| 'modules'
| 'impactRoute'
| 'metadata';
let backend: LocalBackend;
let rows: Partial<Record<Seam, unknown[]>>;
let failedSeam: Seam | undefined;
function fixture(seam: Seam): unknown[] {
if (failedSeam === seam) throw new Error('ordinary unavailable query');
return rows[seam] ?? [];
}
function querySeam(query: string, params: Record<string, any> | undefined): Seam | undefined {
if (params?.symName || params?.uid) return 'target';
if (query.includes("RETURN n.id AS id, 'Class' AS label")) return 'targetLabels';
if (query.includes("r.reason STARTS WITH 'spring-aop:v1:'")) return 'aopRows';
if (query.includes('RETURN s.id AS id, s.name AS name')) return 'pdgOwner';
if (query.includes('RETURN s.id AS id, s.filePath AS filePath')) return 'pdgSpans';
if (query.includes('RETURN c.id AS id, r.reason AS reason')) return 'pdgSummary';
if (query.includes('RETURN a.id AS id, r.reason AS reason')) return 'pdgSelf';
if (query.includes('RETURN a.id AS id ORDER BY a.startLine')) return 'pdgSeed';
if (query.includes('RETURN b.id AS id')) {
if (query.includes('b.calleeIds AS calleeIds')) return 'pdgCalleeBlocks';
if (query.includes('b.text AS text')) return 'pdgStatement';
return 'pdgSeed';
}
if (query.includes('BasicBlock') && query.includes('RETURN DISTINCT')) return 'pdgNeighbor';
if (query.includes('WITH DISTINCT caller') || query.includes('WITH DISTINCT target'))
return 'chain';
if (query.includes('caller.id AS uid'))
return query.includes('(ctor:Constructor)') ? 'classIncoming' : 'incoming';
if (query.includes('target.id AS uid')) return 'outgoing';
if (query.includes('RETURN p.id AS uid')) return 'typedProperties';
if (query.includes('RETURN p.id AS pid, p.heuristicLabel AS label')) return 'contextProcess';
if (query.includes('RETURN route.name AS url')) return 'contextRoute';
if (query.includes('RETURN DISTINCT iface.id AS id')) return 'interfaceBoundary';
if (query.includes('RETURN COUNT(DISTINCT other.id) AS cnt')) return 'interfaceCount';
if (
query.includes('RETURN c.id AS id') ||
query.includes('RETURN f.id AS id') ||
query.includes('RETURN p.id AS id')
)
return 'seeds';
if (query.includes('RETURN DISTINCT member.id AS id')) return 'members';
if (query.includes('AS sourceId')) return 'frontier';
if (query.includes('RETURN p.id AS pId')) return 'process';
if (query.includes('RETURN p.id AS pid, MIN(r.step) AS minStep')) return 'backfill';
if (query.includes('RETURN s.id AS sid')) return 'membership';
if (query.includes('c.heuristicLabel AS name')) return 'modules';
if (query.includes('RETURN h.id AS hid')) return 'impactRoute';
if (query.includes('n.visibility AS visibility')) return 'metadata';
return undefined;
}
async function context(extra = {}) {
return backend.callTool('context', { name: TARGET.name, ...extra });
}
async function impact(extra = {}) {
return backend.callTool('impact', {
target: TARGET.name,
direction: 'upstream',
maxDepth: 1,
...extra,
});
}
function expectIntegrityError(result: any, isImpact = false) {
expect(result.error).toMatch(/invalid symbol identity/i);
expect(result.recoverySuggestion).toMatch(/analyze.*--force/);
expect(JSON.stringify(result)).not.toContain('persisted-value');
expect(result).not.toHaveProperty('symbol');
expect(result).not.toHaveProperty('incoming');
if (isImpact) {
expect(result.risk).toBe('UNKNOWN');
expect(result.impactedCount).toBeNull();
expect(result.epistemic).not.toBe('exact');
}
}
function tuple(value: Record<string, unknown>, keys: string[]): unknown[] {
return keys.map((key) => value[key]);
}
beforeEach(async () => {
vi.clearAllMocks();
aop.mockResolvedValue(undefined);
failedSeam = undefined;
rows = { target: [{ ...TARGET }], frontier: [{ ...EDGE }] };
db.executeParameterized.mockImplementation(async (_db, query, params) => {
const seam = querySeam(query, params);
return seam ? fixture(seam) : [];
});
backend = new LocalBackend();
await backend.init();
vi.spyOn(backend as any, 'ensureInitialized').mockResolvedValue(undefined);
vi.spyOn(backend as any, 'computeEpistemicBoundary').mockResolvedValue({ epistemic: 'exact' });
});
describe('identity corruption before target selection', () => {
for (const corrupt of [true, false]) {
it('distinguishes corrupt and ordinary ambiguous candidate failures: ' + corrupt, async () => {
rows.target = [
{ ...TARGET, id: 'func:one', filePath: 'src/one.ts' },
{ ...TARGET, id: 'func:two', filePath: 'src/two.ts' },
];
vi.spyOn(backend as any, '_runImpactBFS').mockRejectedValue(
corrupt ? new SymbolIdentityError() : new Error('ordinary candidate failure'),
);
const result = await impact();
if (corrupt) {
expectIntegrityError(result, true);
} else {
expect(result.error).toBeUndefined();
expect(result.status).toBe('ambiguous');
expect(result.partialProbe).toBe(true);
}
});
}
for (const tool of ['context', 'impact']) {
for (const badRow of [
{ id: BAD, label: 'Class' },
{ id: '', label: 'Class' },
{ id: 42, label: 'Class' },
{ id: TARGET.id, label: BAD },
]) {
it('rejects corrupt label enrichment for ' + tool + JSON.stringify(badRow), async () => {
rows.target = [{ ...TARGET, type: '' }];
rows.targetLabels = [badRow, { id: TARGET.id, label: 'Class' }];
expectIntegrityError(
tool === 'context' ? await context() : await impact(),
tool === 'impact',
);
});
}
}
for (const shape of ['object', 'tuple']) {
for (const field of ['name', 'filePath']) {
for (const tool of ['context', 'impact', 'pdg impact']) {
it('rejects NUL in target ' + field + ' from ' + shape + ' rows for ' + tool, async () => {
const target = { ...TARGET, [field]: BAD };
rows.target = [
shape === 'tuple'
? tuple(target, ['id', 'name', 'type', 'filePath', 'startLine', 'endLine'])
: target,
];
expectIntegrityError(
tool === 'context'
? await context()
: await impact(tool === 'pdg impact' ? { mode: 'pdg' } : {}),
tool !== 'context',
);
});
}
}
}
it('rejects corrupt exact-UID metadata before expansion', async () => {
rows.target = [{ ...TARGET, filePath: BAD }];
expectIntegrityError(await context({ uid: TARGET.id }));
expectIntegrityError(await impact({ target_uid: TARGET.id }), true);
});
for (const field of ['name', 'filePath']) {
it('rejects non-string target ' + field, async () => {
rows.target = [{ ...TARGET, [field]: 42 }];
expectIntegrityError(await context());
});
}
it('validates every candidate before exact File narrowing', async () => {
rows.target = [
{ ...TARGET, id: 'File:src/target.ts', name: 'target.ts', type: 'File' },
{ ...TARGET, id: 'func:other', filePath: BAD },
];
expectIntegrityError(await context({ name: TARGET.filePath }));
});
});
describe('context detail row integrity', () => {
for (const seam of ['incoming', 'outgoing'] as const) {
for (const shape of ['object', 'tuple']) {
for (const field of ['uid', 'name', 'filePath']) {
it('rejects NUL in ' + seam + ' ' + field + ' from ' + shape + ' rows', async () => {
const ref = { ...REF, [field]: BAD };
rows[seam] = [
shape === 'tuple' ? tuple(ref, ['relType', 'uid', 'name', 'filePath', 'kind']) : ref,
];
expectIntegrityError(await context());
});
}
for (const badRow of [null, {}, [], { ...REF, uid: '' }, { ...REF, relType: '' }]) {
it(
'rejects incomplete ' +
seam +
' row ' +
JSON.stringify(badRow) +
' in ' +
shape +
' response',
async () => {
rows[seam] = [
shape === 'tuple' && badRow !== null
? tuple(badRow, ['relType', 'uid', 'name', 'filePath', 'kind'])
: badRow,
];
expectIntegrityError(await context());
},
);
}
}
}
for (const badRow of [
null,
{},
[''],
{ pid: '' },
{ pid: 'proc:target', label: BAD },
['proc:target', BAD, 0, 0],
]) {
it('rejects corrupt context process ' + JSON.stringify(badRow), async () => {
rows.contextProcess = [badRow];
expectIntegrityError(await context());
});
}
it('does not swallow corrupt class expansion or typed property rows', async () => {
rows.target = [{ ...TARGET, type: 'Class' }];
rows.typedProperties = [{ uid: 'prop:target', name: 'prop', filePath: BAD, kind: 'Property' }];
expectIntegrityError(await context());
});
it('rejects corrupt class refs before deduplication can discard them', async () => {
rows.target = [{ ...TARGET, type: 'Class' }];
rows.incoming = [REF];
rows.classIncoming = [{ ...REF, filePath: BAD }];
expectIntegrityError(await context());
});
for (const badRow of [{}, { ...REF, filePath: BAD }, { ...REF, uid: '' }]) {
it('does not swallow corrupt chain rows ' + JSON.stringify(badRow), async () => {
rows.chain = [badRow];
expectIntegrityError(await context({ chain_depth: 1 }));
});
}
it('rejects NUL in route names', async () => {
rows.contextRoute = [{ url: BAD, method: 'GET' }];
expectIntegrityError(await context());
});
it('rejects nested AOP identity fields while keeping the shared error envelope', async () => {
aop.mockResolvedValue({
framework: 'spring',
advices: [{ adviceId: 'advice:1', adviceName: BAD }],
});
expectIntegrityError(await context());
});
});
describe('epistemic boundary row integrity', () => {
const iface = { id: 'iface:target', name: 'Target contract', label: 'Interface' };
function prepareBoundary() {
vi.mocked((backend as any).computeEpistemicBoundary).mockRestore();
rows.interfaceBoundary = [iface];
rows.interfaceCount = [{ cnt: 2 }];
}
for (const tool of ['context', 'impact']) {
for (const shape of ['object', 'tuple']) {
for (const badRow of [
{ ...iface, id: undefined },
{ ...iface, id: '' },
{ ...iface, id: BAD },
{ ...iface, id: 42 },
{ ...iface, name: BAD },
{ ...iface, name: 42 },
{ ...iface, label: BAD },
{ ...iface, label: 42 },
]) {
it(
'rejects corrupt ' +
tool +
' boundary before deduplication: ' +
shape +
JSON.stringify(badRow),
async () => {
prepareBoundary();
rows.interfaceBoundary = [iface, badRow].map((row) =>
shape === 'tuple' ? tuple(row, ['id', 'name', 'label']) : row,
);
expectIntegrityError(
tool === 'context' ? await context() : await impact(),
tool === 'impact',
);
},
);
}
}
for (const seam of ['interfaceBoundary', 'interfaceCount'] as const) {
for (const corrupt of [true, false]) {
it(
'distinguishes ' + tool + ' boundary query failure: ' + seam + ' ' + corrupt,
async () => {
prepareBoundary();
db.executeParameterized.mockImplementation(async (_db, query, params) => {
const currentSeam = querySeam(query, params);
if (currentSeam === seam) {
throw corrupt ? new SymbolIdentityError() : new Error('ordinary boundary failure');
}
return currentSeam ? fixture(currentSeam) : [];
});
const result = tool === 'context' ? await context() : await impact();
if (corrupt) {
expectIntegrityError(result, tool === 'impact');
} else {
expect(result.error).toBeUndefined();
expect(result.recoverySuggestion).toBeUndefined();
expect(result.epistemic).toBe('lower-bound');
if (tool === 'impact') expect(result.impactedCount).toBe(1);
}
},
);
}
}
it('preserves healthy ' + tool + ' boundary descriptions', async () => {
prepareBoundary();
const result = tool === 'context' ? await context() : await impact();
expect(result.error).toBeUndefined();
expect(result.epistemic).toBe('lower-bound');
expect(result.boundaries).toContainEqual(
expect.stringContaining('Target contract is an interface'),
);
expect(result.causes.dispatchBoundary).toBe(4);
});
}
});
describe('impact detail row integrity', () => {
for (const seam of ['frontier', 'process'] as const) {
it(
'PDG detail integrity rejects corrupt ' + seam + ' rows through the outer envelope',
async () => {
rows[seam] = [
seam === 'frontier' ? { ...EDGE, filePath: BAD } : { ...PROCESS, epName: BAD },
];
expectIntegrityError(await impact({ mode: 'pdg' }), true);
},
);
}
for (const shape of ['object', 'tuple']) {
for (const field of ['id', 'name', 'filePath', 'sourceId']) {
it('rejects NUL in frontier ' + field + ' from ' + shape + ' rows', async () => {
const edge = { ...EDGE, [field]: BAD };
rows.frontier = [
shape === 'tuple'
? tuple(edge, [
'sourceId',
'id',
'name',
'type',
'filePath',
'relType',
'confidence',
'staticGated',
])
: edge,
];
expectIntegrityError(await impact(), true);
});
}
}
for (const badRow of [null, {}, [], { ...EDGE, id: '' }]) {
it('rejects incomplete frontier rows ' + JSON.stringify(badRow), async () => {
rows.frontier = [badRow];
expectIntegrityError(await impact(), true);
});
}
it('validates corrupt rows before test filtering', async () => {
rows.frontier = [{ ...EDGE, filePath: 'test/corrupt\0.test.ts' }];
expectIntegrityError(await impact({ includeTests: false }), true);
});
for (const shape of ['object', 'tuple']) {
for (const field of ['pId', 'name', 'entryPointId', 'epName', 'epFilePath']) {
it('rejects NUL in process ' + field + ' from ' + shape + ' rows', async () => {
const process = { ...PROCESS, [field]: BAD };
rows.process = [
shape === 'tuple'
? tuple(process, [
'pId',
'name',
'processType',
'entryPointId',
'hits',
'minStep',
'stepCount',
'epName',
'epType',
'epFilePath',
])
: process,
];
expectIntegrityError(await impact({ summaryOnly: true }), true);
});
}
}
for (const badRow of [null, {}, [], { ...PROCESS, pId: '' }]) {
it('does not aggregate incomplete processes ' + JSON.stringify(badRow), async () => {
rows.process = [badRow];
expectIntegrityError(await impact(), true);
});
}
for (const badRow of [{}, { pid: BAD, minStep: 1 }]) {
it(
'does not swallow corrupt backfill process identities ' + JSON.stringify(badRow),
async () => {
rows.process = [{ ...PROCESS, minStep: null }];
rows.backfill = [badRow];
expectIntegrityError(await impact(), true);
},
);
}
for (const badRow of [
{},
{ sid: REF.uid, pid: '' },
{ sid: REF.uid, pid: 'proc:caller', pName: BAD },
]) {
it(
'does not swallow corrupt per-symbol process identities ' + JSON.stringify(badRow),
async () => {
rows.process = [PROCESS];
rows.membership = [badRow];
expectIntegrityError(await impact(), true);
},
);
}
for (const type of ['Class', 'Const']) {
for (const badRow of [{}, { ...TARGET, id: 'seed:1', filePath: BAD }]) {
it('rejects corrupt ' + type + ' seeds ' + JSON.stringify(badRow), async () => {
rows.target = [{ ...TARGET, type }];
rows[type === 'Class' ? 'seeds' : 'members'] = [badRow];
expectIntegrityError(await impact({ direction: 'downstream' }), true);
});
}
}
it('rejects NUL in module names before aggregation', async () => {
rows.modules = [{ name: BAD, hits: 1 }];
expectIntegrityError(await impact(), true);
});
it('rejects NUL in route names', async () => {
rows.impactRoute = [{ hid: REF.uid, url: BAD }];
expectIntegrityError(await impact(), true);
});
for (const shape of ['object', 'tuple']) {
for (const hid of [undefined, null, '', ' ', BAD, 42, {}]) {
it(
'rejects corrupt route handler IDs from ' + shape + ' rows: ' + JSON.stringify(hid),
async () => {
const route = { hid, url: '/target', method: 'GET' };
rows.impactRoute = [shape === 'tuple' ? tuple(route, ['hid', 'url', 'method']) : route];
expectIntegrityError(await impact(), true);
},
);
}
}
it('rejects nested AOP paths', async () => {
aop.mockResolvedValue({
framework: 'spring',
advices: [{ adviceId: 'advice:1', adviceFilePath: BAD }],
});
expectIntegrityError(await impact(), true);
});
});
describe('healthy and ordinary-failure compatibility', () => {
it('preserves Unicode, opaque IDs, optional NULL metadata and source NUL', async () => {
const content = 'const value = "actual\0source";';
rows.target = [{ ...TARGET, name: 'café<66>', filePath: '源/café<66>.ts', content }];
rows.incoming = [{ ...REF, name: '呼び出し<E587BA>', filePath: null, kind: '' }];
rows.contextProcess = [
{ pid: 'legacy:proc ', label: '', step: 0, stepCount: 0, entryPointId: null },
];
rows.metadata = [{ annotations: ['@Text("source\0value")'], parameterTypes: null }];
const result = await context({ include_content: true });
expect(result.error).toBeUndefined();
expect(result.symbol).toMatchObject({
uid: TARGET.id,
name: 'café<66>',
filePath: '源/café<66>.ts',
content,
});
expect(result.symbol.methodMetadata).toEqual({ annotations: ['@Text("source\0value")'] });
expect(result.incoming.calls[0]).toMatchObject({ uid: REF.uid, name: '呼び出し<E587BA>' });
expect(result.processes).toEqual([
{ id: 'legacy:proc ', name: undefined, step_index: 0, step_count: 0 },
]);
});
it('preserves tuple zero steps and empty process labels', async () => {
rows.contextProcess = [['proc:0', '', 0, 0, null]];
expect((await context()).processes).toEqual([
{ id: 'proc:0', name: '', step_index: 0, step_count: 0 },
]);
});
it('allows absent OPTIONAL MATCH entry-point fields and missing legacy sourceId', async () => {
rows.frontier = [{ ...EDGE, sourceId: undefined }];
rows.process = [
{ ...PROCESS, name: '', entryPointId: null, epName: null, epType: null, epFilePath: null },
];
const result = await impact();
expect(result.error).toBeUndefined();
expect(result.impactedCount).toBe(1);
expect(result.affected_processes).toEqual([
{
name: 'unknown',
type: 'Function',
filePath: '',
affected_process_count: 1,
total_hits: 1,
earliest_broken_step: 0,
},
]);
});
it('keeps missing optional route fields as ordinary skipped enrichment', async () => {
rows.contextRoute = [{}];
rows.impactRoute = [{ hid: REF.uid }];
expect((await context()).error).toBeUndefined();
expect((await impact()).error).toBeUndefined();
});
it('does not misdiagnose an unmatched user-supplied NUL as index corruption', async () => {
rows.target = [];
const contextResult = await context({ name: 'client\0input' });
const impactResult = await impact({ target: 'client\0input' });
expect(contextResult.error).toContain('not found');
expect(impactResult.error).toContain('not found');
expect(contextResult.recoverySuggestion).toBeUndefined();
expect(impactResult.recoverySuggestion).toBeUndefined();
});
it('keeps ordinary process query failures degraded rather than integrity errors', async () => {
failedSeam = 'process';
const result = await impact();
expect(result.error).toBeUndefined();
expect(result.partial).toBe(true);
expect(result.impactedCount).toBe(1);
expect(result.affected_processes).toEqual([]);
});
it('keeps ordinary PDG interprocedural failures as degraded results', async () => {
vi.spyOn(backend as any, '_runImpactBFS').mockRejectedValue(
new Error('ordinary bridge failure'),
);
const result = await impact({ mode: 'pdg' });
expect(result.error).toBeUndefined();
expect(result.partial).toBe(true);
expect(result.interproceduralError).toBe('ordinary bridge failure');
expect(result.recoverySuggestion).toBeUndefined();
});
it('keeps ordinary context process query failures as unavailable enrichment', async () => {
failedSeam = 'contextProcess';
const result = await context();
expect(result.error).toBeUndefined();
expect(result.processes).toEqual([]);
});
});
describe('raw PDG identities before coercion, caps, and projection', () => {
const seed = 'BasicBlock:src/target.ts:2:0:0';
const reached = 'BasicBlock:src/caller.ts:1:0:0';
function preparePdg() {
rows.pdgSeed = [{ id: seed }];
rows.pdgNeighbor = [{ id: reached }];
rows.pdgOwner = [{ id: REF.uid, name: REF.name, label: 'Function', startLine: 0 }];
rows.pdgStatement = [{ id: reached, line: 1, endLine: 1, text: 'value = 1;' }];
}
for (const seam of ['pdgSeed', 'pdgNeighbor', 'pdgOwner', 'pdgStatement'] as const) {
for (const bad of [BAD, '', null, 42]) {
it('rejects raw ' + seam + ' identity ' + JSON.stringify(bad), async () => {
preparePdg();
rows[seam] = [{ id: bad, name: 'caller', label: 'Function', line: 1, startLine: 0 }];
expectIntegrityError(
await impact({ mode: 'pdg', ...(seam === 'pdgStatement' ? { line: 2 } : {}) }),
true,
);
});
}
}
for (const seam of ['pdgSeed', 'pdgNeighbor'] as const) {
it('validates ' + seam + ' cap probe rows', async () => {
preparePdg();
rows[seam] = [{ id: seam === 'pdgSeed' ? seed : reached }, { id: BAD }];
expectIntegrityError(await impact({ mode: 'pdg', limit: 1 }), true);
});
}
for (const field of ['name', 'label']) {
it('rejects raw owner ' + field + ' before String coercion', async () => {
preparePdg();
rows.pdgOwner = [{ id: REF.uid, name: 'caller', label: 'Function', [field]: BAD }];
expectIntegrityError(await impact({ mode: 'pdg' }), true);
});
}
for (const field of ['seedBlocks', 'reachableBlocks', 'intraReachableBlocks']) {
for (const bad of [BAD, '', null, 42]) {
it('rejects malformed final ' + field + ' members ' + JSON.stringify(bad), async () => {
const healthy = await impact({ mode: 'pdg' });
vi.spyOn(backend as any, '_runImpactPDG').mockResolvedValue({
...healthy,
[field]: [bad],
});
expectIntegrityError(await impact({ mode: 'pdg' }), true);
});
}
}
it('allows a generated unresolved owner marker', async () => {
preparePdg();
rows.pdgOwner = [];
const result = await impact({ mode: 'pdg' });
expect(result.error).toBeUndefined();
expect(result.unresolvedBlockCount).toBe(1);
});
it('preserves Unicode owner tuples and source NUL', async () => {
preparePdg();
rows.pdgOwner = [[REF.uid, '呼び出し<E587BA>', 'Function', 0]];
expect((await impact({ mode: 'pdg' })).error).toBeUndefined();
rows.pdgStatement = [{ id: reached, line: 1, endLine: 1, text: 'value = "source\0text";' }];
const result = await impact({ mode: 'pdg', line: 2 });
expect(result.error).toBeUndefined();
expect(result.affectedStatements.some((s: any) => s.text.includes('\0'))).toBe(true);
});
for (const field of ['callees', 'calleeIds']) {
it('does not swallow a corrupt statement bridge ' + field, async () => {
preparePdg();
const original = db.executeParameterized.getMockImplementation()!;
db.executeParameterized.mockImplementation(async (...args) => {
if (args[1].includes('RETURN b.' + field + ' AS ' + field)) {
return [{ [field]: BAD }];
}
return original(...args);
});
expectIntegrityError(await impact({ mode: 'pdg', direction: 'downstream' }), true);
});
}
});
describe('real AOP helper identities before deduplication', () => {
const reason =
'spring-aop:v1:' +
JSON.stringify({
kind: 'advice',
annotation: 'org.aspectj.lang.annotation.Around',
advice: 'around',
pointcut: 'execution(*)',
match: 'static',
activation: 'unknown',
proxy: 'possible',
});
const advice = {
sourceId: TARGET.id,
sourceName: 'target',
sourceFilePath: TARGET.filePath,
targetId: 'advice:1',
targetName: 'audit',
targetFilePath: 'src/audit.ts',
reason,
};
async function useRealAop() {
const actual = await vi.importActual<typeof import('../../src/mcp/local/aop-metadata.js')>(
'../../src/mcp/local/aop-metadata.js',
);
aop.mockImplementation(actual.querySpringAopMetadata);
rows.target = [{ ...TARGET, type: 'Method' }];
}
for (const tool of ['context', 'impact']) {
for (const field of ['sourceId', 'targetId']) {
for (const bad of [BAD, '', null, 42]) {
it('rejects raw AOP ' + field + ' for ' + tool + JSON.stringify(bad), async () => {
await useRealAop();
rows.aopRows = [{ ...advice, [field]: bad }, advice];
expectIntegrityError(
tool === 'context' ? await context() : await impact(),
tool === 'impact',
);
});
}
}
for (const field of ['sourceName', 'sourceFilePath', 'targetName', 'targetFilePath']) {
it('rejects corrupt duplicate AOP ' + field + ' for ' + tool, async () => {
await useRealAop();
rows.aopRows = [{ ...advice, [field]: BAD }, advice];
expectIntegrityError(
tool === 'context' ? await context() : await impact(),
tool === 'impact',
);
});
}
}
it('validates the AOP cap-probe row', async () => {
await useRealAop();
rows.aopRows = [...Array.from({ length: 1000 }, () => advice), { ...advice, targetId: BAD }];
expectIntegrityError(await context());
});
it('preserves Unicode and optional NULL metadata', async () => {
await useRealAop();
rows.aopRows = [
{ ...advice, sourceName: '源<>', sourceFilePath: null, targetName: '', targetFilePath: null },
];
const result = await context();
expect(result.error).toBeUndefined();
expect(result.symbol.aop.advices[0]).toMatchObject({
adviceId: advice.targetId,
advisedId: advice.sourceId,
advisedName: '源<>',
});
});
it('keeps ordinary AOP query failures fail-soft', async () => {
await useRealAop();
failedSeam = 'aopRows';
expect((await context()).error).toBeUndefined();
expect((await impact()).error).toBeUndefined();
});
it('handles early AOP rejection while the frontier is pending', async () => {
const unhandled = vi.fn();
process.on('unhandledRejection', unhandled);
aop.mockRejectedValue(new SymbolIdentityError());
const original = db.executeParameterized.getMockImplementation()!;
db.executeParameterized.mockImplementation(async (...args) => {
if (querySeam(args[1], args[2]) === 'frontier') {
await new Promise((resolve) => setTimeout(resolve, 30));
}
return original(...args);
});
try {
expectIntegrityError(await impact(), true);
expect(unhandled).not.toHaveBeenCalled();
} finally {
process.off('unhandledRejection', unhandled);
}
});
});

2
gitnexus/test/unit/impact-pagination.test.ts
View file

@ -56,6 +56,7 @@ function setupMultiDepthHub(d1Count: number, d2Count: number) {
const query = typeof args[1] === 'string' ? args[1] : String(args[0] ?? '');
if (query.includes('STEP_IN_PROCESS')) return [];
if (query.includes('MEMBER_OF')) return [];
if (query.includes('RETURN h.id AS hid')) return [];
// The #1858 epistemic-boundary probe (computeEpistemicBoundary) runs
// concurrently with the BFS and also matches `r.type IN`, but targets the
// `iface` alias. Return empty so it stays `epistemic: 'exact'` and does not
@ -99,6 +100,7 @@ function setupHubSymbol(count: number) {
const query = typeof args[1] === 'string' ? args[1] : String(args[0] ?? '');
if (query.includes('STEP_IN_PROCESS')) return [];
if (query.includes('MEMBER_OF')) return [];
if (query.includes('RETURN h.id AS hid')) return [];
// See setupMultiDepthHub — keep the #1858 epistemic probe from matching the
// `r.type IN` caller branch below.
if (query.includes('iface')) return [];

5
gitnexus/test/unit/impact-route-enrichment.test.ts
View file

@ -80,7 +80,10 @@ async function runImpact(routeRows: readonly RouteRow[], routeQueryFails = false
: [];
}
if (query.includes('STEP_IN_PROCESS') || query.includes('MEMBER_OF')) return [];
return [{ id: 'svc', name: 'UnfinalizeRound', filePath: 'svc.go', type: 'Method' }];
if (query.includes('n.id AS id')) {
return [{ id: 'svc', name: 'UnfinalizeRound', filePath: 'svc.go', type: 'Method' }];
}
return [];
});
const backend = new LocalBackend();

104
gitnexus/test/unit/index-lock.test.ts
View file

@ -17,6 +17,7 @@ import {
existsSync,
chmodSync,
symlinkSync,
mkdirSync,
} from 'node:fs';
import os from 'node:os';
import path from 'node:path';
@ -178,6 +179,109 @@ describe('release', () => {
});
describe('sweepStagingArtifacts', () => {
const recoveryStage = 'lbug.staging.6e34c761-bf58-46cc-8b54-78d11607bc46';
const seedRecovery = (stagingFile = recoveryStage): void => {
writeFileSync(
path.join(dir, 'gitnexus.json'),
JSON.stringify({
embeddingCheckpoint: {
kind: 'interrupted',
at: '2026-10-03T12:00:00.000Z',
nodesProcessed: 1,
totalNodes: 2,
chunksProcessed: 1,
model: 'test-model',
dimensions: 2,
provider: 'local',
pendingNodeIds: ['node-2'],
recovery: {
stagingFile,
schemaFingerprint: 'schema-v1',
unsafeNodeIds: ['node-2'],
},
},
}),
);
};
it('retains the checkpoint-referenced family while reclaiming unrelated orphans', () => {
const family = [
'',
'.wal',
'.shadow',
'.wal.checkpoint',
'.lock',
'.checkpoint.intent.lock',
'.checkpoint.apply.lock',
].map((suffix) => recoveryStage + suffix);
for (const name of [...family, `${recoveryStage}.unexpected`, 'lbug.staging.orphan']) {
writeFileSync(path.join(dir, name), 'x');
}
seedRecovery();
sweepStagingArtifacts(dir);
for (const name of family) expect(existsSync(path.join(dir, name))).toBe(true);
expect(existsSync(path.join(dir, `${recoveryStage}.unexpected`))).toBe(false);
expect(existsSync(path.join(dir, 'lbug.staging.orphan'))).toBe(false);
});
it('preserves a referenced generation when a shared caller acquires the lock', async () => {
writeFileSync(path.join(dir, recoveryStage), 'x');
seedRecovery();
const lock = await acquireIndexLock(dir);
try {
expect(existsSync(path.join(dir, recoveryStage))).toBe(true);
} finally {
lock.release();
}
});
it('retains only the referenced family in a branch sub-slot', async () => {
const branchDir = path.join(dir, 'branches', 'feature');
mkdirSync(branchDir, { recursive: true });
seedRecovery();
const metadata = JSON.parse(readFileSync(path.join(dir, 'gitnexus.json'), 'utf8'));
writeFileSync(
path.join(branchDir, 'gitnexus.json'),
JSON.stringify({ ...metadata, storagePath: dir }),
);
writeFileSync(path.join(branchDir, recoveryStage), 'stage');
writeFileSync(path.join(branchDir, 'lbug.staging.orphan'), 'orphan');
writeFileSync(path.join(dir, 'lbug.staging.orphan'), 'other-slot');
const lock = await acquireIndexLock(branchDir);
try {
expect(existsSync(path.join(branchDir, recoveryStage))).toBe(true);
expect(existsSync(path.join(branchDir, 'lbug.staging.orphan'))).toBe(false);
expect(existsSync(path.join(dir, 'lbug.staging.orphan'))).toBe(true);
} finally {
lock.release();
}
});
it('rejects a symlinked reference and never follows it while reclaiming the stage', () => {
const external = path.join(dir, 'foreign-database');
writeFileSync(external, 'external');
symlinkSync(external, path.join(dir, recoveryStage));
seedRecovery();
sweepStagingArtifacts(dir);
expect(existsSync(path.join(dir, recoveryStage))).toBe(false);
expect(readFileSync(external, 'utf8')).toBe('external');
});
it('does not sweep any generation when acquisition explicitly defers cleanup', async () => {
writeFileSync(path.join(dir, 'lbug.staging.orphan'), 'x');
const lock = await acquireIndexLock(dir, { sweep: false });
try {
expect(existsSync(path.join(dir, 'lbug.staging.orphan'))).toBe(true);
} finally {
lock.release();
}
});
it('removes only staging files, never the live index or its sidecars', () => {
const files = [
'lbug',

83
gitnexus/test/unit/pdg-impact-engine.test.ts
View file

@ -1,12 +1,95 @@
import { describe, expect, it } from 'vitest';
import { IMPACT_MAX_DEPTH } from '../../src/mcp/tools.js';
import { CALLEES_TRUNCATED_SENTINEL } from '../../src/core/ingestion/cfg/callee-cell-format.js';
import {
pdgLayerStatus,
runImpactPDG,
splitCalleeIds,
type RunPdgImpactDeps,
} from '../../src/mcp/local/pdg-impact.js';
import { SymbolIdentityError } from '../../src/mcp/local/query-result-integrity.js';
describe('splitCalleeIds', () => {
const firstId = 'Function:src/my dir/rené.cpp:unsigned char';
const secondId = 'Function:src/my dir/rené.cpp:long double';
it.each([undefined, null, '', ' ', '\t', '\t \t'])(
'preserves an entirely empty optional cell (%j)',
(cell) => {
expect(splitCalleeIds(cell)).toEqual([]);
},
);
it('preserves spaces and Unicode within healthy callee identities', () => {
expect(splitCalleeIds(`${firstId}\t${secondId}`)).toEqual([firstId, secondId]);
});
it('drops the generated truncation sentinel without changing resolved identities', () => {
expect(splitCalleeIds(CALLEES_TRUNCATED_SENTINEL)).toEqual([]);
expect(splitCalleeIds(`${firstId}\t${CALLEES_TRUNCATED_SENTINEL}\t${secondId}`)).toEqual([
firstId,
secondId,
]);
});
it.each([
['leading', `\t${firstId}`],
['interior', `${firstId}\t\t${secondId}`],
['trailing', `${firstId}\t`],
['whitespace-only token', `${firstId}\t \t${secondId}`],
['before a sentinel', `\t${CALLEES_TRUNCATED_SENTINEL}`],
['after a sentinel', `${CALLEES_TRUNCATED_SENTINEL}\t`],
['mixed with a sentinel', `${firstId}\t\t${CALLEES_TRUNCATED_SENTINEL}\t${secondId}`],
])('rejects a populated cell with an empty identity (%s)', (_case, cell) => {
expect(() => splitCalleeIds(cell)).toThrow(SymbolIdentityError);
});
});
describe('runImpactPDG', () => {
it.each([
['leading', '\tFunction:src/hot.ts:callee'],
['interior', 'Function:src/hot.ts:a\t\tFunction:src/hot.ts:b'],
['trailing', 'Function:src/hot.ts:callee\t'],
['sentinel-adjacent', `Function:src/hot.ts:callee\t${CALLEES_TRUNCATED_SENTINEL}\t`],
])(
'rejects an empty callee identity before interprocedural descent (%s)',
async (_case, cell) => {
const seed = 'BasicBlock:src/hot.ts:1:0:0';
const queries: string[] = [];
const exec: RunPdgImpactDeps['executeParameterized'] = async (_repo, query) => {
queries.push(query);
if (query.includes('MATCH (a:BasicBlock) WHERE')) return [{ id: seed }];
if (query.includes('RETURN b.id AS id, b.calleeIds AS calleeIds')) {
return [{ id: seed, calleeIds: cell, callees: 'callee' }];
}
return [];
};
await expect(
runImpactPDG({
repo: { lbugPath: 'repo' },
sym: {
id: 'Function:src/hot.ts:hot',
name: 'hot',
filePath: 'src/hot.ts',
startLine: 0,
endLine: 3,
},
symType: 'Function',
direction: 'downstream',
maxDepth: 2,
limit: 50,
line: 1,
executeParameterized: exec,
}),
).rejects.toBeInstanceOf(SymbolIdentityError);
expect(
queries.some((query) => query.includes('RETURN b.id AS id, b.calleeIds AS calleeIds')),
).toBe(true);
expect(queries.some((query) => query.includes("r.type = 'CALL_SUMMARY'"))).toBe(false);
},
);
it('clamps huge maxDepth values to the documented impact traversal cap', async () => {
let bfsQueries = 0;
const exec = async (_repo: string, query: string) => {

659
gitnexus/test/unit/run-analyze-fts-repair.test.ts
View file

@ -1,13 +1,18 @@
import { execSync } from 'child_process';
import fs from 'fs/promises';
import { afterEach, describe, expect, it, vi, type Mock } from 'vitest';
import { basename } from 'node:path';
import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest';
import {
getStoragePaths,
loadMeta,
saveMeta,
type RepoMeta,
} from '../../src/storage/repo-manager.js';
import { EMBEDDING_DIMS, STALE_HASH_SENTINEL } from '../../src/core/lbug/schema.js';
import {
EMBEDDING_DIMS,
STALE_HASH_SENTINEL,
SCHEMA_FINGERPRINT,
} from '../../src/core/lbug/schema.js';
import { getIndexIncompleteReasons } from '../../src/core/index-freshness.js';
import type {
EmbeddingPipelineOptions,
@ -2382,12 +2387,20 @@ describe('runFullAnalysis embedding-checkpoint meta write (#2790)', () => {
incrementalInProgress: { phase: 'full-rebuild' },
stats: { embeddings: 7 },
});
expect(snapshots.postWindow?.embeddingCheckpoint?.recovery).toMatchObject({
stagingFile: expect.stringMatching(/^lbug\.staging\.[a-f0-9-]+$/),
schemaFingerprint: SCHEMA_FINGERPRINT,
unsafeNodeIds: [],
});
// ── Window 2: the published count remains unchanged ────────────────
expect(snapshots.secondWindow).toMatchObject({
lastCommit: STALE_COMMIT,
stats: { embeddings: 7 },
embeddingCheckpoint: { pendingNodeIds: ['node-3', 'node-4'] },
embeddingCheckpoint: {
pendingNodeIds: ['node-3', 'node-4'],
recovery: { unsafeNodeIds: ['node-3', 'node-4'] },
},
});
// Only the finalize write — after the index is published — advances
@ -2427,6 +2440,14 @@ describe('runFullAnalysis embedding-checkpoint meta write (#2790)', () => {
* NEXT run does with it).
*/
describe('runFullAnalysis embedding-checkpoint resilience (#2790 review)', () => {
const actualPlatformDescriptor = Object.getOwnPropertyDescriptor(process, 'platform');
beforeEach(() => {
// These mocked checkpoint tests exercise the atomic rebuild used on POSIX.
// Select that same path on Windows; the in-place case below opts out.
vi.stubEnv('GITNEXUS_ATOMIC_WINDOWS_SWAP', '1');
});
const RESILIENCE_NODE_ID = 'Function:src/app.ts:handler:1';
const stubNode = {
id: RESILIENCE_NODE_ID,
@ -2461,7 +2482,7 @@ describe('runFullAnalysis embedding-checkpoint resilience (#2790 review)', () =>
const mockResilienceHarness = (
controls: ResilienceControls,
): { runEmbeddingPipeline: Mock; loadCachedEmbeddings: Mock } => {
): { runEmbeddingPipeline: Mock; loadCachedEmbeddings: Mock; batchInsertEmbeddings: Mock } => {
const loadCachedEmbeddings = vi.fn(async () => ({
embeddingNodeIds: new Set<string>(),
embeddings: [],
@ -2530,11 +2551,13 @@ describe('runFullAnalysis embedding-checkpoint resilience (#2790 review)', () =>
pipelineOptions: EmbeddingPipelineOptions,
): Promise<EmbeddingPipelineResult> => controls.pipeline(pipelineOptions),
);
const batchInsertEmbeddings = vi.fn(async () => undefined);
vi.doMock('../../src/core/embeddings/embedding-pipeline.js', () => ({
runEmbeddingPipeline,
batchInsertEmbeddings,
buildVectorIndex: vi.fn(async () => false),
}));
return { runEmbeddingPipeline, loadCachedEmbeddings };
return { runEmbeddingPipeline, loadCachedEmbeddings, batchInsertEmbeddings };
};
/** A checkpoint shaped exactly as `RepoMeta` declares it. */
@ -2583,12 +2606,17 @@ describe('runFullAnalysis embedding-checkpoint resilience (#2790 review)', () =>
};
afterEach(() => {
if (actualPlatformDescriptor) {
Object.defineProperty(process, 'platform', actualPlatformDescriptor);
}
vi.doUnmock('../../src/core/lbug/lbug-adapter.js');
vi.doUnmock('../../src/core/search/fts-indexes.js');
vi.doUnmock('../../src/core/ingestion/pipeline.js');
vi.doUnmock('../../src/storage/repo-manager.js');
vi.doUnmock('../../src/core/embeddings/embedding-identity.js');
vi.doUnmock('../../src/core/embeddings/embedding-pipeline.js');
vi.doUnmock('../../src/core/embeddings/staged-embedding-recovery.js');
vi.restoreAllMocks();
vi.resetModules();
vi.clearAllMocks();
vi.unstubAllEnvs();
@ -3040,4 +3068,625 @@ describe('runFullAnalysis embedding-checkpoint resilience (#2790 review)', () =>
await tmpRepo.cleanup();
}
});
const mockStagedFiles = async (): Promise<void> => {
const adapter = await import('../../src/core/lbug/lbug-adapter.js');
vi.mocked(adapter.initLbug).mockImplementation(async (dbPath) => {
if (dbPath.includes('.staging.')) await fs.writeFile(dbPath, 'staged fixture');
});
vi.mocked(adapter.wipeLbugDbFiles).mockImplementation(async (dbPath) => {
await fs.rm(dbPath, { force: true });
});
};
it.each([
{ mode: 'staged', atomicSwap: '1', checkpointCount: 7 },
{ mode: 'in-place', atomicSwap: '0', checkpointCount: 42 },
])(
'keeps Windows $mode checkpoint counts consistent with the live index',
async ({ mode, atomicSwap, checkpointCount }) => {
const tmpRepo = await createTempDir('gitnexus-2790-checkpoint-meta-');
try {
const { storagePath, lbugPath } = getStoragePaths(tmpRepo.dbPath);
await seedMeta(storagePath, tmpRepo.dbPath, { stats: { nodes: 2, embeddings: 7 } });
await fs.writeFile(lbugPath, 'published fixture');
const snapshots: Array<RepoMeta | null> = [];
mockResilienceHarness({
count: [{ cnt: 42 }],
pipeline: async (options) => {
await options.onCheckpointWindowStart?.({
nodesProcessed: 0,
totalNodes: 3,
chunksProcessed: 0,
nodeIds: [RESILIENCE_NODE_ID],
});
snapshots.push(await loadMeta(storagePath));
await options.onCheckpoint?.({ nodesProcessed: 3, totalNodes: 3, chunksProcessed: 3 });
snapshots.push(await loadMeta(storagePath));
return cleanResult();
},
});
await mockStagedFiles();
// Load modules on the actual host before changing only the platform
// branch exercised by runFullAnalysis; all native DB work is mocked.
const { runFullAnalysis } = await import('../../src/core/run-analyze.js');
vi.stubEnv('GITNEXUS_ATOMIC_WINDOWS_SWAP', atomicSwap);
Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
await runFullAnalysis(
tmpRepo.dbPath,
{ force: true, embeddings: true, skipAgentsMd: true, skipSkills: true },
{ onProgress: () => {}, onLog: () => {} },
);
expect(snapshots[0]?.stats?.embeddings).toBe(7);
expect(snapshots[1]?.stats?.embeddings).toBe(checkpointCount);
const adapter = await import('../../src/core/lbug/lbug-adapter.js');
const buildPath = vi.mocked(adapter.initLbug).mock.calls.at(-1)?.[0];
if (mode === 'staged') {
expect(buildPath).toMatch(/\.staging\.[a-f0-9-]+$/);
expect(snapshots[1]?.embeddingCheckpoint?.recovery).toMatchObject({
stagingFile: expect.stringMatching(/^lbug\.staging\.[a-f0-9-]+$/),
unsafeNodeIds: [],
});
expect(await fs.readFile(lbugPath, 'utf8')).toBe('staged fixture');
} else {
expect(buildPath).toBe(lbugPath);
expect(snapshots[0]?.embeddingCheckpoint?.recovery).toBeUndefined();
expect(snapshots[1]?.embeddingCheckpoint?.recovery).toBeUndefined();
}
const finalMeta = await loadMeta(storagePath);
expect(finalMeta?.stats?.embeddings).toBe(42);
expect(finalMeta?.embeddingCheckpoint).toBeUndefined();
} finally {
if (actualPlatformDescriptor) {
Object.defineProperty(process, 'platform', actualPlatformDescriptor);
}
await tmpRepo.cleanup();
}
},
);
it.each(['close', 'rename'] as const)(
'keeps the published count and database when %s fails before the staged publish',
async (failure) => {
const tmpRepo = await createTempDir('gitnexus-2790-checkpoint-meta-');
try {
const { storagePath, lbugPath } = getStoragePaths(tmpRepo.dbPath);
await seedMeta(storagePath, tmpRepo.dbPath, { stats: { nodes: 2, embeddings: 7 } });
await fs.writeFile(lbugPath, 'published fixture');
const rename = fs.rename.bind(fs);
let checkpointMeta: RepoMeta | null = null;
let failedPublishRename: Mock | undefined;
mockResilienceHarness({
count: [{ cnt: 42 }],
pipeline: async (options) => {
await options.onCheckpointWindowStart?.({
nodesProcessed: 0,
totalNodes: 3,
chunksProcessed: 0,
nodeIds: [RESILIENCE_NODE_ID],
});
await options.onCheckpoint?.({ nodesProcessed: 3, totalNodes: 3, chunksProcessed: 3 });
checkpointMeta = await loadMeta(storagePath);
if (failure === 'close') {
const adapter = await import('../../src/core/lbug/lbug-adapter.js');
vi.mocked(adapter.closeLbug).mockRejectedValueOnce(
new Error('pre-publish close failed'),
);
} else {
failedPublishRename = vi.fn(async () => {
throw Object.assign(new Error('staged publish rename failed'), { code: 'EIO' });
});
vi.spyOn(fs, 'rename').mockImplementation(async (source, destination) => {
if (
String(source).startsWith(`${lbugPath}.staging.`) &&
String(destination) === lbugPath
) {
return failedPublishRename?.();
}
return rename(source, destination);
});
}
return cleanResult();
},
});
await mockStagedFiles();
expect(
await runAnalyze(
tmpRepo.dbPath,
{ force: true, embeddings: true, skipAgentsMd: true, skipSkills: true },
[],
),
).toMatchObject({
message:
failure === 'close' ? 'pre-publish close failed' : 'staged publish rename failed',
});
expect(checkpointMeta?.stats?.embeddings).toBe(7);
expect((await loadMeta(storagePath))?.stats?.embeddings).toBe(7);
expect(await fs.readFile(lbugPath, 'utf8')).toBe('published fixture');
const recovery = (await loadMeta(storagePath))?.embeddingCheckpoint?.recovery;
if (!recovery) throw new Error('expected durable stage after failed publish');
expect(await fs.readFile(`${storagePath}/${recovery.stagingFile}`, 'utf8')).toBe(
'staged fixture',
);
if (failure === 'rename') expect(failedPublishRename).toHaveBeenCalledTimes(1);
} finally {
vi.restoreAllMocks();
await tmpRepo.cleanup();
}
},
);
const seedRecovery = async (storagePath: string, repoPath: string) => {
const stagingFile = 'lbug.staging.11111111-1111-4111-8111-111111111111';
const checkpoint = checkpointFixture({
kind: 'interrupted',
pendingNodeIds: [],
recovery: { stagingFile, schemaFingerprint: SCHEMA_FINGERPRINT, unsafeNodeIds: [] },
});
await seedMeta(storagePath, repoPath, {
stats: { nodes: 2, embeddings: 7 },
embeddingCheckpoint: checkpoint,
});
await fs.writeFile(`${storagePath}/${stagingFile}`, 'previous durable source');
vi.doMock('../../src/core/embeddings/staged-embedding-recovery.js', () => ({
recoverStagedEmbeddings: vi.fn(async () => ({ rows: [], embeddingNodeIds: new Set() })),
}));
return { checkpoint, stagingFile };
};
it.each(
['1', '0'].flatMap((manualCheckpoint) =>
(
['window-start crash', 'post-window crash', 'final-metadata failure', 'success'] as const
).map((outcome) => ({ manualCheckpoint, outcome })),
),
)(
'preserves the in-place recovery receipt with manual checkpoints=$manualCheckpoint through $outcome',
async ({ manualCheckpoint, outcome }) => {
vi.stubEnv('GITNEXUS_WAL_MANUAL_CHECKPOINT', manualCheckpoint);
vi.stubEnv('GITNEXUS_INDEX_LOCK_BACKEND', 'file');
const tmpRepo = await createTempDir('gitnexus-3456-opt-out-source-');
try {
const { storagePath, lbugPath } = getStoragePaths(tmpRepo.dbPath);
const { checkpoint, stagingFile } = await seedRecovery(storagePath, tmpRepo.dbPath);
const original = {
...checkpoint,
pendingNodeIds: ['original-pending'],
recovery: {
stagingFile,
schemaFingerprint: SCHEMA_FINGERPRINT,
unsafeNodeIds: ['original-pending', 'original-unsafe'],
},
} satisfies NonNullable<RepoMeta['embeddingCheckpoint']>;
await seedMeta(storagePath, tmpRepo.dbPath, {
stats: { nodes: 2, embeddings: 7 },
embeddingCheckpoint: original,
});
const sourceFiles = [
{ filename: stagingFile, contents: 'previous durable source' },
{ filename: `${stagingFile}.wal`, contents: 'previous durable WAL' },
{ filename: `${stagingFile}.shadow`, contents: 'previous durable shadow' },
];
for (const source of sourceFiles) {
await fs.writeFile(`${storagePath}/${source.filename}`, source.contents);
}
await fs.writeFile(lbugPath, 'previous published index');
const { normalizeCachedEmbeddings } =
await import('../../src/core/embeddings/embedding-restore-spill.js');
vi.doMock(
'../../src/core/embeddings/staged-embedding-recovery.js',
async (importActual) => ({
...(await importActual<
typeof import('../../src/core/embeddings/staged-embedding-recovery.js')
>()),
recoverStagedEmbeddings: vi.fn(async () =>
normalizeCachedEmbeddings({
embeddings: [
{
nodeId: RESILIENCE_NODE_ID,
chunkIndex: 0,
startLine: 1,
endLine: 2,
contentHash: 'current-hash',
embedding: new Array(EMBEDDING_DIMS).fill(0),
},
],
}),
),
}),
);
const snapshots: Array<RepoMeta | null> = [];
const rename = fs.rename.bind(fs);
const { batchInsertEmbeddings } = mockResilienceHarness({
count: [{ cnt: 9 }],
pipeline: async (options) => {
await options.onCheckpointWindowStart?.({
nodesProcessed: 0,
totalNodes: 3,
chunksProcessed: 0,
nodeIds: ['current-window'],
});
snapshots.push(await loadMeta(storagePath));
if (outcome === 'window-start crash') throw new Error(outcome);
await options.onCheckpoint?.({ nodesProcessed: 3, totalNodes: 3, chunksProcessed: 9 });
snapshots.push(await loadMeta(storagePath));
if (outcome === 'post-window crash') throw new Error(outcome);
if (outcome === 'final-metadata failure') {
vi.spyOn(fs, 'rename').mockImplementation(async (source, destination) => {
if (basename(String(destination)) === 'gitnexus.json') throw new Error(outcome);
return rename(source, destination);
});
}
return cleanResult();
},
});
await mockStagedFiles();
const adapter = await import('../../src/core/lbug/lbug-adapter.js');
vi.mocked(adapter.loadGraphToLbug).mockImplementation(async () => {
await fs.writeFile(lbugPath, 'in-place replacement');
});
// Import on the host first, then choose the Windows default in-place
// branch. The native adapter is mocked; source files and lock cleanup are real.
await import('../../src/core/run-analyze.js');
vi.stubEnv('GITNEXUS_ATOMIC_WINDOWS_SWAP', '0');
Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
const error = await runAnalyze(
tmpRepo.dbPath,
{ force: true, embeddings: true, skipAgentsMd: true, skipSkills: true },
[],
);
if (actualPlatformDescriptor) {
Object.defineProperty(process, 'platform', actualPlatformDescriptor);
}
expect(batchInsertEmbeddings).toHaveBeenCalled();
expect(vi.mocked(adapter.initLbug).mock.calls.at(-1)?.[0]).toBe(lbugPath);
const finalMeta = await loadMeta(storagePath);
// Reacquiring the real lock performs the next retry's orphan sweep.
// A lost receipt would delete every byte of the proven old generation here.
const { acquireIndexLock } = await import('../../src/storage/index-lock.js');
const lock = await acquireIndexLock(storagePath, { timeoutMs: 1000 });
try {
if (outcome === 'success') {
expect(error).toBeNull();
expect(finalMeta?.embeddingCheckpoint).toBeUndefined();
expect(finalMeta?.stats?.embeddings).toBe(9);
expect(await fs.readFile(lbugPath, 'utf8')).toBe('in-place replacement');
for (const source of sourceFiles) {
await expect(fs.stat(`${storagePath}/${source.filename}`)).rejects.toMatchObject({
code: 'ENOENT',
});
}
} else {
expect(error).toMatchObject({ message: outcome });
for (const source of sourceFiles) {
expect(await fs.readFile(`${storagePath}/${source.filename}`, 'utf8')).toBe(
source.contents,
);
}
expect(finalMeta?.embeddingCheckpoint).toEqual(original);
expect(finalMeta?.stats?.embeddings).toBe(outcome === 'window-start crash' ? 7 : 9);
}
expect(snapshots[0]?.embeddingCheckpoint).toEqual(original);
expect(snapshots[0]?.stats?.embeddings).toBe(7);
if (outcome !== 'window-start crash') {
expect(snapshots[1]?.embeddingCheckpoint).toEqual(original);
expect(snapshots[1]?.stats?.embeddings).toBe(9);
}
} finally {
lock.release();
}
} finally {
if (actualPlatformDescriptor) {
Object.defineProperty(process, 'platform', actualPlatformDescriptor);
}
vi.restoreAllMocks();
await tmpRepo.cleanup();
}
},
);
it('finishes a staged embedding run with manual checkpoints disabled', async () => {
vi.stubEnv('GITNEXUS_WAL_MANUAL_CHECKPOINT', '0');
const tmpRepo = await createTempDir('gitnexus-3456-checkpoint-opt-out-');
try {
const { storagePath } = getStoragePaths(tmpRepo.dbPath);
await seedMeta(storagePath, tmpRepo.dbPath, { stats: { embeddings: 7 } });
mockResilienceHarness({
count: [{ cnt: 9 }],
pipeline: async (options) => {
await options.onCheckpointWindowStart?.({
nodesProcessed: 0,
totalNodes: 3,
chunksProcessed: 0,
nodeIds: ['active-node'],
});
expect((await loadMeta(storagePath))?.embeddingCheckpoint?.recovery).toBeUndefined();
await options.onCheckpoint?.({ nodesProcessed: 3, totalNodes: 3, chunksProcessed: 9 });
const midRun = await loadMeta(storagePath);
expect(midRun?.embeddingCheckpoint?.recovery).toBeUndefined();
expect(midRun?.stats?.embeddings).toBe(7);
return cleanResult();
},
});
await mockStagedFiles();
expect(await runAnalyze(tmpRepo.dbPath, { force: true, embeddings: true }, [])).toBeNull();
expect((await loadMeta(storagePath))?.embeddingCheckpoint).toBeUndefined();
expect((await loadMeta(storagePath))?.stats?.embeddings).toBe(9);
expect(await fs.readFile(getStoragePaths(tmpRepo.dbPath).lbugPath, 'utf8')).toBe(
'staged fixture',
);
} finally {
await tmpRepo.cleanup();
}
});
it('keeps the previous durable source when manual checkpoints are disabled', async () => {
vi.stubEnv('GITNEXUS_WAL_MANUAL_CHECKPOINT', '0');
const tmpRepo = await createTempDir('gitnexus-3456-opt-out-source-');
try {
const { storagePath } = getStoragePaths(tmpRepo.dbPath);
const { checkpoint: original, stagingFile } = await seedRecovery(storagePath, tmpRepo.dbPath);
mockResilienceHarness({
count: [{ cnt: 9 }],
pipeline: async (options) => {
await options.onCheckpointWindowStart?.({
nodesProcessed: 0,
totalNodes: 3,
chunksProcessed: 0,
nodeIds: ['active-node'],
});
await options.onCheckpoint?.({ nodesProcessed: 3, totalNodes: 3, chunksProcessed: 9 });
expect((await loadMeta(storagePath))?.embeddingCheckpoint).toEqual(original);
throw new Error('endpoint failure with manual checkpoints disabled');
},
});
await mockStagedFiles();
expect(await runAnalyze(tmpRepo.dbPath, { force: true, embeddings: true }, [])).toMatchObject(
{ message: 'endpoint failure with manual checkpoints disabled' },
);
expect((await loadMeta(storagePath))?.embeddingCheckpoint).toEqual(original);
expect(await fs.readFile(`${storagePath}/${stagingFile}`, 'utf8')).toBe(
'previous durable source',
);
expect(
(await fs.readdir(storagePath)).filter((name) => name.startsWith('lbug.staging.')),
).toEqual([stagingFile]);
} finally {
await tmpRepo.cleanup();
}
});
it.skipIf(process.platform === 'win32')(
'retains the referenced stage through a symlinked storage directory',
async () => {
const tmpRepo = await createTempDir('gitnexus-3456-storage-alias-');
try {
const { storagePath } = getStoragePaths(tmpRepo.dbPath);
const actualStorage = `${tmpRepo.dbPath}/actual-index`;
await fs.mkdir(actualStorage);
await fs.symlink(actualStorage, storagePath, 'dir');
await seedMeta(storagePath, tmpRepo.dbPath, { stats: { embeddings: 7 } });
mockResilienceHarness({
count: [{ cnt: 9 }],
pipeline: async (options) => {
await options.onCheckpointWindowStart?.({
nodesProcessed: 0,
totalNodes: 3,
chunksProcessed: 0,
nodeIds: ['active-node'],
});
await options.onCheckpoint?.({ nodesProcessed: 1, totalNodes: 3, chunksProcessed: 9 });
throw new Error('endpoint failed after durable window');
},
});
await mockStagedFiles();
expect(
await runAnalyze(tmpRepo.dbPath, { force: true, embeddings: true }, []),
).toMatchObject({ message: 'endpoint failed after durable window' });
const recovery = (await loadMeta(storagePath))?.embeddingCheckpoint?.recovery;
if (!recovery) throw new Error('expected retained recovery generation');
expect(await fs.readFile(`${actualStorage}/${recovery.stagingFile}`, 'utf8')).toBe(
'staged fixture',
);
expect((await loadMeta(storagePath))?.stats?.embeddings).toBe(7);
} finally {
await tmpRepo.cleanup();
}
},
);
it.each(['checkpoint', 'metadata'] as const)(
'keeps the previous source when %s fails before recovery handoff',
async (failure) => {
const tmpRepo = await createTempDir('gitnexus-3456-handoff-failure-');
try {
const { storagePath } = getStoragePaths(tmpRepo.dbPath);
const { checkpoint: original, stagingFile } = await seedRecovery(
storagePath,
tmpRepo.dbPath,
);
const rename = fs.rename.bind(fs);
mockResilienceHarness({
count: [{ cnt: 9 }],
pipeline: async (options) => {
if (failure === 'metadata') {
vi.spyOn(fs, 'rename').mockImplementation(async (source, destination) => {
if (basename(String(destination)) === 'gitnexus.json')
throw new Error('metadata write failed');
return rename(source, destination);
});
} else {
const adapter = await import('../../src/core/lbug/lbug-adapter.js');
vi.mocked(adapter.tryFlushWAL).mockResolvedValue(false);
}
await options.onCheckpointWindowStart?.({
nodesProcessed: 0,
totalNodes: 3,
chunksProcessed: 0,
nodeIds: ['active-node'],
});
return cleanResult();
},
});
await mockStagedFiles();
const error = await runAnalyze(tmpRepo.dbPath, { force: true, embeddings: true }, []);
expect(error).toMatchObject({
message:
failure === 'metadata'
? 'metadata write failed'
: 'Could not checkpoint restored embeddings before recovery handoff.',
});
expect((await loadMeta(storagePath))?.embeddingCheckpoint).toEqual(original);
expect((await loadMeta(storagePath))?.stats?.embeddings).toBe(7);
expect(await fs.readFile(`${storagePath}/${stagingFile}`, 'utf8')).toBe(
'previous durable source',
);
expect(
(await fs.readdir(storagePath)).filter((name) => name.startsWith('lbug.staging.')),
).toEqual([stagingFile]);
} finally {
vi.restoreAllMocks();
await tmpRepo.cleanup();
}
},
);
it('keeps an active window unsafe when its completion checkpoint fails', async () => {
const tmpRepo = await createTempDir('gitnexus-3456-completion-failure-');
try {
const { storagePath } = getStoragePaths(tmpRepo.dbPath);
await seedMeta(storagePath, tmpRepo.dbPath, { stats: { embeddings: 7 } });
mockResilienceHarness({
count: [{ cnt: 9 }],
pipeline: async (options) => {
await options.onCheckpointWindowStart?.({
nodesProcessed: 0,
totalNodes: 3,
chunksProcessed: 0,
nodeIds: ['active-node'],
});
const adapter = await import('../../src/core/lbug/lbug-adapter.js');
vi.mocked(adapter.tryFlushWAL).mockResolvedValue(false);
await options.onCheckpoint?.({ nodesProcessed: 1, totalNodes: 3, chunksProcessed: 9 });
return cleanResult();
},
});
await mockStagedFiles();
expect(await runAnalyze(tmpRepo.dbPath, { force: true, embeddings: true }, [])).toMatchObject(
{ message: 'Could not checkpoint the completed embedding window for recovery.' },
);
const meta = await loadMeta(storagePath);
expect(meta?.stats?.embeddings).toBe(7);
expect(meta?.embeddingCheckpoint?.pendingNodeIds).toEqual(['active-node']);
expect(meta?.embeddingCheckpoint?.recovery?.unsafeNodeIds).toEqual(['active-node']);
if (!meta?.embeddingCheckpoint?.recovery) throw new Error('expected retained active window');
expect(
await fs.readFile(
`${storagePath}/${meta.embeddingCheckpoint.recovery.stagingFile}`,
'utf8',
),
).toBe('staged fixture');
} finally {
await tmpRepo.cleanup();
}
});
it('retains a failed stage and keeps future incomplete restore groups unsafe', async () => {
const tmpRepo = await createTempDir('gitnexus-3456-unsafe-restore-');
try {
const { storagePath } = getStoragePaths(tmpRepo.dbPath);
await seedMeta(storagePath, tmpRepo.dbPath, { stats: { nodes: 2, embeddings: 1 } });
let completedWindow: RepoMeta | null = null;
const { loadCachedEmbeddings, batchInsertEmbeddings } = mockResilienceHarness({
count: [{ cnt: 5 }],
pipeline: async (options) => {
await options.onCheckpointWindowStart?.({
nodesProcessed: 0,
totalNodes: 2,
chunksProcessed: 0,
nodeIds: ['earlier-window-node'],
});
await options.onCheckpoint?.({ nodesProcessed: 1, totalNodes: 2, chunksProcessed: 1 });
completedWindow = await loadMeta(storagePath);
throw new Error('Maximum database size exceeded');
},
});
loadCachedEmbeddings.mockResolvedValue({
embeddingNodeIds: new Set([RESILIENCE_NODE_ID]),
embeddings: [
{
nodeId: RESILIENCE_NODE_ID,
chunkIndex: 0,
startLine: 1,
endLine: 2,
contentHash: 'current-hash',
embedding: new Array(EMBEDDING_DIMS).fill(0),
},
],
});
batchInsertEmbeddings.mockRejectedValue(new Error('restore batch partially inserted'));
const adapter = await import('../../src/core/lbug/lbug-adapter.js');
vi.mocked(adapter.initLbug).mockImplementation(async (dbPath) => {
if (dbPath.includes('.staging.')) await fs.writeFile(dbPath, 'staged fixture');
});
vi.mocked(adapter.wipeLbugDbFiles).mockImplementation(async (dbPath) => {
await fs.rm(dbPath, { force: true });
});
const logs: string[] = [];
expect(
await runAnalyze(
tmpRepo.dbPath,
{ embeddings: true, force: true, skipAgentsMd: true, skipSkills: true },
logs,
),
).toMatchObject({ message: 'Maximum database size exceeded' });
expect(completedWindow?.embeddingCheckpoint?.recovery?.unsafeNodeIds).toEqual([
RESILIENCE_NODE_ID,
]);
expect(completedWindow?.stats?.embeddings).toBe(1);
const recovery = (await loadMeta(storagePath))?.embeddingCheckpoint?.recovery;
if (!recovery) throw new Error('expected retained recovery generation');
expect(await fs.readFile(`${storagePath}/${recovery.stagingFile}`, 'utf8')).toBe(
'staged fixture',
);
expect(logs).toContainEqual(expect.stringContaining('GITNEXUS_LBUG_MAX_DB_SIZE'));
} finally {
await tmpRepo.cleanup();
}
});
it('reclaims a failed current stage before any recovery checkpoint exists', async () => {
const tmpRepo = await createTempDir('gitnexus-3456-no-checkpoint-');
try {
const { storagePath } = getStoragePaths(tmpRepo.dbPath);
await seedMeta(storagePath, tmpRepo.dbPath, {});
mockResilienceHarness({
count: [{ cnt: 0 }],
pipeline: async () => {
throw new Error('failed before first window');
},
});
const adapter = await import('../../src/core/lbug/lbug-adapter.js');
vi.mocked(adapter.initLbug).mockImplementation(async (dbPath) => {
if (dbPath.includes('.staging.')) await fs.writeFile(dbPath, 'staged fixture');
});
vi.mocked(adapter.wipeLbugDbFiles).mockImplementation(async (dbPath) => {
await fs.rm(dbPath, { force: true });
});
expect(
await runAnalyze(
tmpRepo.dbPath,
{ embeddings: true, force: true, skipAgentsMd: true, skipSkills: true },
[],
),
).toMatchObject({ message: 'failed before first window' });
expect(
(await fs.readdir(storagePath)).filter((name) => name.startsWith('lbug.staging.')),
).toEqual([]);
expect((await loadMeta(storagePath))?.embeddingCheckpoint).toBeUndefined();
} finally {
await tmpRepo.cleanup();
}
});
});

300
gitnexus/test/unit/staged-embedding-recovery-child.test.ts Normal file
View file

@ -0,0 +1,300 @@
import fs from 'node:fs';
import { EventEmitter } from 'node:events';
import os from 'node:os';
import path from 'node:path';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
const h = vi.hoisted(() => ({
dbCtor: vi.fn(),
connCtor: vi.fn(),
dbClose: vi.fn<() => Promise<void>>(),
connClose: vi.fn<() => Promise<void>>(),
query: vi.fn(),
abortBuilder: vi.fn(),
spawn: vi.fn(),
}));
vi.mock('node:child_process', () => ({ spawn: h.spawn }));
vi.mock('@ladybugdb/core', () => {
class Database {
constructor(...args: unknown[]) {
h.dbCtor(...args);
}
close = h.dbClose;
}
class Connection {
constructor(db: unknown) {
h.connCtor(db);
}
query = h.query;
close = h.connClose;
}
return { default: { Database, Connection } };
});
vi.mock('../../src/core/embeddings/embedding-restore-spill.js', async (importOriginal) => {
const actual =
await importOriginal<typeof import('../../src/core/embeddings/embedding-restore-spill.js')>();
return {
...actual,
abortCachedEmbeddingsBuilder: (
...args: Parameters<typeof actual.abortCachedEmbeddingsBuilder>
) => {
h.abortBuilder(...args);
return actual.abortCachedEmbeddingsBuilder(...args);
},
};
});
describe('staged embedding recovery child native lifecycle', () => {
const suffixes = [
'',
'.wal',
'.shadow',
'.wal.checkpoint',
'.lock',
'.checkpoint.intent.lock',
'.checkpoint.apply.lock',
];
let tmp: string;
let dbPath: string;
let exportDir: string;
let originalArgv: string[];
let originalExitCode: typeof process.exitCode;
beforeEach(() => {
vi.resetModules();
vi.clearAllMocks();
h.dbCtor.mockReset();
h.connCtor.mockReset();
h.dbClose.mockReset().mockResolvedValue(undefined);
h.connClose.mockReset().mockResolvedValue(undefined);
h.query.mockReset().mockResolvedValue({
hasNext: vi.fn().mockResolvedValue(false),
getNext: vi.fn(),
close: vi.fn().mockResolvedValue(undefined),
});
tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-recovery-child-'));
dbPath = path.join(tmp, 'lbug.stage-test');
exportDir = path.join(tmp, 'export');
fs.writeFileSync(dbPath, 'mock native database');
fs.writeFileSync(`${dbPath}.wal`, 'retained WAL');
fs.mkdirSync(exportDir);
originalArgv = process.argv;
originalExitCode = process.exitCode;
process.argv = [process.execPath, 'staged-embedding-recovery-child', dbPath, exportDir, '2'];
process.exitCode = undefined;
vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
});
afterEach(() => {
vi.useRealTimers();
process.argv = originalArgv;
process.exitCode = originalExitCode;
vi.restoreAllMocks();
fs.rmSync(tmp, { recursive: true, force: true });
});
function sourceFamily() {
return Object.fromEntries(
suffixes.map((suffix) => [suffix, fs.readFileSync(dbPath + suffix, 'utf8')]),
);
}
function seedCompleteFamily() {
for (const suffix of suffixes) fs.writeFileSync(dbPath + suffix, `retained ${suffix}`);
return sourceFamily();
}
async function runRejectedChild(message: string): Promise<void> {
await import('../../src/core/embeddings/staged-embedding-recovery-child.js');
await vi.waitFor(() => {
expect(process.exitCode).toBe(1);
expect(process.stderr.write).toHaveBeenCalledWith(`${message}\n`);
});
expect(fs.existsSync(path.join(exportDir, 'manifest.json'))).toBe(false);
expect(fs.readFileSync(`${dbPath}.wal`, 'utf8')).toBe('retained WAL');
}
it('closes the opened database and aborts the builder when Connection construction fails', async () => {
h.connCtor.mockImplementation(() => {
throw new Error('connection constructor failed');
});
await runRejectedChild('connection constructor failed');
expect(h.dbClose).toHaveBeenCalledOnce();
expect(h.connClose).not.toHaveBeenCalled();
expect(h.abortBuilder).toHaveBeenCalledOnce();
expect(h.query).not.toHaveBeenCalled();
expect(h.dbCtor.mock.calls[0][7]).toBe(true);
});
it('aborts the builder when Database construction fails', async () => {
h.dbCtor.mockImplementation(() => {
throw new Error('database constructor failed');
});
await runRejectedChild('database constructor failed');
expect(h.abortBuilder).toHaveBeenCalledOnce();
expect(h.dbClose).not.toHaveBeenCalled();
expect(h.connCtor).not.toHaveBeenCalled();
});
it('rejects output and closes the database when Connection close fails', async () => {
h.connClose.mockRejectedValue(new Error('connection close failed'));
await runRejectedChild('connection close failed');
expect(h.dbClose).toHaveBeenCalled();
expect(h.abortBuilder).toHaveBeenCalledOnce();
});
it('rejects output when Database close fails', async () => {
h.dbClose.mockRejectedValue(new Error('database close failed'));
await runRejectedChild('database close failed');
expect(h.connClose).toHaveBeenCalled();
expect(h.abortBuilder).toHaveBeenCalledOnce();
});
it('confines writable replay and failed checkpoint close to a separate copied family', async () => {
const sourceBefore = seedCompleteFamily();
h.dbCtor.mockImplementation((openedPath: string) => {
for (const suffix of suffixes) {
expect(fs.readFileSync(openedPath + suffix, 'utf8')).toBe(sourceBefore[suffix]);
fs.writeFileSync(openedPath + suffix, `replayed ${suffix}`);
}
});
h.dbClose.mockImplementation(async () => {
const openedPath = h.dbCtor.mock.calls[0][0] as string;
fs.writeFileSync(openedPath, 'partial checkpoint');
throw new Error('checkpoint close failed');
});
await import('../../src/core/embeddings/staged-embedding-recovery-child.js');
await vi.waitFor(() => expect(process.exitCode).toBe(1));
expect(h.dbCtor.mock.calls[0][0]).not.toBe(dbPath);
expect(path.relative(exportDir, h.dbCtor.mock.calls[0][0] as string)).not.toMatch(/^\.\./);
expect(sourceFamily()).toEqual(sourceBefore);
expect(fs.existsSync(path.join(exportDir, 'manifest.json'))).toBe(false);
expect(process.stderr.write).toHaveBeenCalledWith('checkpoint close failed\n');
});
it('reclaims a timed-out writer copy without changing the retained source', async () => {
const sourceBefore = seedCompleteFamily();
h.query.mockReturnValue(new Promise(() => {}));
h.dbCtor.mockImplementation((openedPath: string) => {
for (const suffix of suffixes) fs.writeFileSync(openedPath + suffix, 'writer opened');
});
let childImport: Promise<unknown> | undefined;
const child = Object.assign(new EventEmitter(), {
stderr: new EventEmitter(),
kill: vi.fn(() => {
queueMicrotask(() => child.emit('close', null, 'SIGKILL'));
return true;
}),
});
h.spawn.mockImplementation((_command: string, args: string[]) => {
process.argv = [process.execPath, 'staged-embedding-recovery-child', ...args.slice(-3)];
childImport = import('../../src/core/embeddings/staged-embedding-recovery-child.js');
return child;
});
const { recoverStagedEmbeddings } =
await import('../../src/core/embeddings/staged-embedding-recovery.js');
vi.useFakeTimers();
const recovering = expect(
recoverStagedEmbeddings(dbPath, { dimensions: 2, timeoutMs: 500 }),
).rejects.toThrow(/timeout/);
await childImport;
expect(h.dbCtor).toHaveBeenCalledOnce();
const openedPath = h.dbCtor.mock.calls[0][0] as string;
await vi.advanceTimersByTimeAsync(500);
await recovering;
expect(child.kill).toHaveBeenCalledWith('SIGKILL');
expect(openedPath).not.toBe(dbPath);
expect(fs.existsSync(path.dirname(openedPath))).toBe(false);
expect(sourceFamily()).toEqual(sourceBefore);
expect(h.dbClose).not.toHaveBeenCalled();
});
it.each(['.wal', '.checkpoint.intent.lock', '.checkpoint.apply.lock'])(
'refuses a dangling family symlink before native open: %s',
async (suffix) => {
fs.rmSync(dbPath + suffix, { force: true });
fs.symlinkSync(path.join(tmp, 'missing-sidecar'), dbPath + suffix);
await import('../../src/core/embeddings/staged-embedding-recovery-child.js');
await vi.waitFor(() => expect(process.exitCode).toBe(1));
expect(h.dbCtor).not.toHaveBeenCalled();
expect(process.stderr.write).toHaveBeenCalledWith(
'staged embedding family is not a regular file\n',
);
expect(fs.existsSync(path.join(exportDir, 'manifest.json'))).toBe(false);
},
);
it('refuses a family entry replaced with a symlink between lstat and open', async () => {
const foreignPath = path.join(tmp, 'foreign-file');
fs.writeFileSync(foreignPath, 'foreign');
const open = fs.openSync;
const read = vi.spyOn(fs, 'readSync');
vi.spyOn(fs, 'openSync').mockImplementation((...args) => {
if (args[0] === dbPath) {
fs.rmSync(dbPath);
fs.symlinkSync(foreignPath, dbPath);
}
return open(...args);
});
await import('../../src/core/embeddings/staged-embedding-recovery-child.js');
await vi.waitFor(() => expect(process.exitCode).toBe(1));
expect(read).not.toHaveBeenCalled();
expect(h.dbCtor).not.toHaveBeenCalled();
expect(fs.readFileSync(foreignPath, 'utf8')).toBe('foreign');
expect(fs.existsSync(path.join(exportDir, 'manifest.json'))).toBe(false);
});
it('fails closed when copying the complete family runs out of space', async () => {
const sourceBefore = seedCompleteFamily();
vi.spyOn(fs, 'writeFileSync').mockImplementation(() => {
throw Object.assign(new Error('copy ran out of space'), { code: 'ENOSPC' });
});
await import('../../src/core/embeddings/staged-embedding-recovery-child.js');
await vi.waitFor(() => expect(process.exitCode).toBe(1));
expect(h.dbCtor).not.toHaveBeenCalled();
expect(sourceFamily()).toEqual(sourceBefore);
expect(fs.existsSync(path.join(exportDir, 'manifest.json'))).toBe(false);
expect(process.stderr.write).toHaveBeenCalledWith('copy ran out of space\n');
});
it('writes the manifest only after both native closes succeed', async () => {
const closed: string[] = [];
h.connClose.mockImplementation(async () => {
expect(fs.existsSync(path.join(exportDir, 'manifest.json'))).toBe(false);
closed.push('connection');
});
h.dbClose.mockImplementation(async () => {
expect(fs.existsSync(path.join(exportDir, 'manifest.json'))).toBe(false);
closed.push('database');
});
await import('../../src/core/embeddings/staged-embedding-recovery-child.js');
await vi.waitFor(() => expect(fs.existsSync(path.join(exportDir, 'manifest.json'))).toBe(true));
expect(closed).toEqual(['connection', 'database']);
expect(h.abortBuilder).not.toHaveBeenCalled();
expect(process.exitCode).toBeUndefined();
expect(fs.readFileSync(`${dbPath}.wal`, 'utf8')).toBe('retained WAL');
});
});

95
gitnexus/test/unit/staged-embedding-recovery.test.ts Normal file
View file

@ -0,0 +1,95 @@
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { afterEach, describe, expect, it } from 'vitest';
import {
createCachedEmbeddingsBuilder,
disposeEmbeddingSpill,
finalizeCachedEmbeddingsSnapshot,
ingestCachedEmbeddingRow,
materializeCachedEmbeddings,
type CachedEmbeddingsSnapshot,
} from '../../src/core/embeddings/embedding-restore-spill.js';
import {
mergeRecoveredEmbeddings,
validateRecoveredNodeGroups,
} from '../../src/core/embeddings/staged-embedding-recovery.js';
describe('staged embedding recovery', () => {
const snapshots: CachedEmbeddingsSnapshot[] = [];
let tmp: string | undefined;
afterEach(() => {
for (const snapshot of snapshots) disposeEmbeddingSpill(snapshot.spill);
snapshots.length = 0;
if (tmp) fs.rmSync(tmp, { recursive: true, force: true });
tmp = undefined;
});
function snapshot(
rows: { nodeId: string; chunkIndex: number; contentHash?: string; embedding?: number[] }[],
) {
tmp ??= fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-stage-test-'));
const builder = createCachedEmbeddingsBuilder({ inMemoryRowLimit: 0, spillDir: tmp });
for (const row of rows) {
ingestCachedEmbeddingRow(
builder,
{ startLine: 1, endLine: 2, embedding: [1, 2], ...row },
true,
);
}
const result = finalizeCachedEmbeddingsSnapshot(builder);
snapshots.push(result);
return result;
}
it('accepts only complete groups with one content hash and unique contiguous chunk ordinals', () => {
const cached = snapshot([
{ nodeId: 'complete', chunkIndex: 1, contentHash: 'same' },
{ nodeId: 'complete', chunkIndex: 0, contentHash: 'same' },
{ nodeId: 'gap', chunkIndex: 1, contentHash: 'same' },
{ nodeId: 'duplicate', chunkIndex: 0, contentHash: 'same' },
{ nodeId: 'duplicate', chunkIndex: 0, contentHash: 'same' },
{ nodeId: 'mixed', chunkIndex: 0, contentHash: 'old' },
{ nodeId: 'mixed', chunkIndex: 1, contentHash: 'new' },
{ nodeId: 'no-hash', chunkIndex: 0 },
{ nodeId: 'unsafe', chunkIndex: 0, contentHash: 'same' },
]);
expect([...validateRecoveredNodeGroups(cached.rows, new Set(['unsafe']))]).toEqual([
'complete',
]);
});
it('replaces an entire published node group and keeps unrelated rows without retaining vector arrays', () => {
const live = snapshot([
{ nodeId: 'changed', chunkIndex: 0, contentHash: 'old' },
{ nodeId: 'changed', chunkIndex: 1, contentHash: 'old' },
{ nodeId: 'other', chunkIndex: 0, contentHash: 'other' },
]);
const recovered = snapshot([
{ nodeId: 'changed', chunkIndex: 0, contentHash: 'new', embedding: [7, 8] },
]);
const merged = mergeRecoveredEmbeddings(live, recovered);
snapshots.push(merged);
expect(merged.embeddings).toEqual([]);
expect(merged.rows).toHaveLength(2);
expect(materializeCachedEmbeddings(merged, merged.rows)).toEqual([
expect.objectContaining({ nodeId: 'other', contentHash: 'other' }),
expect.objectContaining({
nodeId: 'changed',
chunkIndex: 0,
contentHash: 'new',
embedding: [7, 8],
}),
]);
expect(fs.existsSync(live.spill.path)).toBe(true);
expect(fs.existsSync(recovered.spill.path)).toBe(true);
});
it('does not accept missing vector bytes during a merge', () => {
const cached = snapshot([{ nodeId: 'complete', chunkIndex: 0, contentHash: 'same' }]);
fs.truncateSync(cached.spill.path, 12);
expect(() => mergeRecoveredEmbeddings(snapshot([]), cached)).toThrow(
/short embedding spill read/,
);
});
});

2
gitnexus/vitest.config.ts
View file

@ -68,6 +68,7 @@ export default defineConfig({
include: [
'test/integration/skip-fts.test.ts',
'test/integration/impact-callable-value-references.test.ts',
'test/integration/impact-context-integrity.test.ts',
'test/integration/impact-epistemic-lower-bound.test.ts',
'test/integration/impact-scope-omission-persistence.test.ts',
'test/integration/lbug-core-adapter.test.ts',
@ -162,6 +163,7 @@ export default defineConfig({
exclude: [
'test/integration/skip-fts.test.ts',
'test/integration/impact-callable-value-references.test.ts',
'test/integration/impact-context-integrity.test.ts',
'test/integration/impact-epistemic-lower-bound.test.ts',
'test/integration/impact-scope-omission-persistence.test.ts',
'test/integration/lbug-core-adapter.test.ts',