gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/storage/fs-atomic.js

@@ -6,7 +6,7 @@
  * core/group/ import (the established direction is core/group/ -> storage/,
  * e.g. core/group/service.ts already imports loadMeta from here).
  */
-import fsp from 'fs/promises';
+import { closeSync, openSync, promises as fsp, renameSync, unlinkSync, writeSync } from 'node:fs';
 import { randomBytes } from 'crypto';
 const RETRY_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
 /**
@@ -52,7 +52,7 @@ export async function retryRename(src, dst, attempts = 3) {
  * retry backoff (and, under a lock, make everyone else wait for it).
  */
 export async function writeFileAtomic(targetPath, data, attempts) {
-    const tmpPath = `${targetPath}.tmp.${randomBytes(8).toString('hex')}`;
+    const tmpPath = tmpBeside(targetPath);
     const handle = await fsp.open(tmpPath, 'wx', 0o600);
     try {
         try {
@@ -68,3 +68,87 @@ export async function writeFileAtomic(targetPath, data, attempts) {
         throw err;
     }
 }
+function tmpBeside(targetPath) {
+    return `${targetPath}.tmp.${randomBytes(8).toString('hex')}`;
+}
+/**
+ * Publish `src` at `dst` without ever writing through the inode currently
+ * named by `dst` (#3090). Fast path is `fs.link`. Any failure (EEXIST, EXDEV,
+ * EPERM, unsupported hardlinks) copies into a unique sibling and
+ * {@link retryRename}s over `dst`. POSIX rename of a file over an existing
+ * file unlinks the old name; it does not open or truncate that inode.
+ *
+ * Invariant: may replace the destination directory entry; must never modify
+ * the inode that entry currently references. There is no dest unlink and no
+ * in-place `copyFile(src, dst)`.
+ */
+export async function linkOrCopyFile(src, dst) {
+    try {
+        await fsp.link(src, dst);
+        return;
+    }
+    catch {
+        /* any link failure → publish a new inode via tmp + rename */
+    }
+    const tmp = tmpBeside(dst);
+    try {
+        await fsp.copyFile(src, tmp);
+        await retryRename(tmp, dst);
+    }
+    catch (err) {
+        await fsp.unlink(tmp).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Binary sibling of {@link writeFileAtomic}. Same random tmp + `'wx'` + `0o600`
+ * + rename contract; used for optional V8 cache sidecars that cannot go through
+ * a UTF-8 `writeFile`.
+ */
+export async function writeFileAtomicBytes(targetPath, data, attempts) {
+    const tmpPath = tmpBeside(targetPath);
+    const handle = await fsp.open(tmpPath, 'wx', 0o600);
+    try {
+        try {
+            await handle.writeFile(data);
+        }
+        finally {
+            await handle.close();
+        }
+        await retryRename(tmpPath, targetPath, attempts);
+    }
+    catch (err) {
+        await fsp.unlink(tmpPath).catch(() => { });
+        throw err;
+    }
+}
+/**
+ * Sync binary publish for parse workers. Same exclusive-tmp + mode contract as
+ * {@link writeFileAtomicBytes}; rename is not retried (the worker is not the
+ * Windows multi-reader case `retryRename` exists for).
+ */
+export function writeFileAtomicBytesSync(targetPath, data) {
+    const tmpPath = tmpBeside(targetPath);
+    const fd = openSync(tmpPath, 'wx', 0o600);
+    try {
+        try {
+            let offset = 0;
+            while (offset < data.byteLength) {
+                offset += writeSync(fd, data, offset);
+            }
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmpPath, targetPath);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch {
+            /* leftover tmp is unlinked on the next exclusive create */
+        }
+        throw err;
+    }
+}

package/dist/storage/global-dir.d.ts

@@ -0,0 +1,2 @@
+/** Get the path to the global GitNexus directory. */
+export declare const getGlobalDir: () => string;

package/dist/storage/global-dir.js

@@ -0,0 +1,6 @@
+import os from 'node:os';
+import path from 'node:path';
+/** Get the path to the global GitNexus directory. */
+export const getGlobalDir = () => {
+    return process.env.GITNEXUS_HOME || path.join(os.homedir(), '.gitnexus');
+};

package/dist/storage/parse-cache.d.ts

@@ -6,10 +6,12 @@
  * does is skip the tree-sitter worker dispatch when a chunk's contents
  * haven't changed since the last run.
  *
- * Granularity: chunk-level. The parse phase chunks files into ~20MB byte
- * budgets. The cache key is `sha256(joined(filePath:contentHash for each
- * file in the chunk, sorted))`. A change to a single file invalidates only
- * that file's chunk — typically 1 of ~50 chunks on a 1000-file repo.
+ * Granularity: chunk-level. Files are assigned to a stable
+ * `(language, hash(path) mod 128)` bucket, then packed to a 2 MiB (or
+ * operator) byte budget *inside* that bucket. Membership does not depend
+ * on worker count. The cache key is `sha256(joined(filePath:contentHash
+ * for each file in the chunk, sorted))`. A content edit invalidates only
+ * that file's pack; add/delete/rename only the affected bucket.
  *
  * Why not per-file:
  * - Workers process sub-batches and emit aggregated `ParseWorkerResult`s.
@@ -17,12 +19,43 @@
  * - Chunk-level invalidation gives a useful speedup floor (98% on a single
  *   1-of-50 invalidated chunk) without touching the worker.
  *
- * Survives `--force` because it's content-addressed: the same bytes always
- * produce the same key. `--force` only matters for the LadybugDB writeback;
- * the cache itself is always safe to reuse.
+ * `--force` still reuses content-addressed shards (it only rebuilds graph/FTS).
+ * `useParseCache: false` reparses every file, writes a staging generation, and
+ * publishes onto this cache only after a successful analysis.
  */
 import type { ParseWorkerResult } from '../core/ingestion/workers/parse-worker.js';
 export declare const PARSE_CACHE_VERSION: string;
+/** Stable parse-cache bucket count (#3088). Changing this requires SCHEMA_BUMP. */
+export declare const PARSE_CACHE_BUCKET_COUNT = 128;
+/** Bucket id for cache membership: `sha256(path) mod N` without IEEE-754 truncation. */
+export declare const parseCacheBucketId: (filePath: string) => number;
+export type ParseCachePackFile = {
+    path: string;
+    size: number;
+    language: string;
+};
+/**
+ * Pack files into parse-cache chunks: group by (language, bucket id), sort
+ * paths inside the group, then cut at `byteBudget`. Bucket visit order is
+ * the lexicographic order of `${language}\\0${bucketId}` keys (deterministic,
+ * independent of scan order and worker count).
+ */
+export declare const packParseCacheChunks: (files: readonly ParseCachePackFile[], byteBudget: number) => string[][];
+/**
+ * Per-run staging root for `useParseCache: false`. Parse-cache shards and the
+ * ParsedFile stores write here so a crash cannot mix a new generation into the
+ * live `.gitnexus/parse-cache` / `parsedfile-cache` trees. `saveParseCache`
+ * publishes onto the live `storagePath` only after a successful analysis.
+ */
+export declare const COLD_PARSE_REBUILD_DIRNAME = "parse-rebuild";
+/** Deterministic staging path — tests only. Production uses {@link createColdParseRebuildDir}. */
+export declare const getColdParseRebuildDir: (storagePath: string) => string;
+/**
+ * Unique per analyze process so concurrent `--no-parse-cache` runs on
+ * different branch slots (shared `.gitnexus`, separate index locks) do not
+ * delete each other's staging tree.
+ */
+export declare const createColdParseRebuildDir: (storagePath: string) => Promise<string>;
 /** Runtime view: keyed Map for fast lookup; mutated in place during a run. */
 export interface ParseCache {
     version: string;
@@ -39,6 +72,8 @@ export interface ParseCache {
      * When set, chunk payloads are loaded from / flushed to sharded files on
      * demand instead of retaining every chunk in `entries` for the whole run
      * (#1983 — Linux kernel OOM from duplicate in-memory cache + graph).
+     * May be a per-run staging directory (`getColdParseRebuildDir`) while the
+     * live index root is passed separately to `saveParseCache`.
      */
     storagePath?: string;
     /** Index of chunk hashes known to exist under `storagePath/parse-cache/`. */
@@ -87,6 +122,8 @@ export declare const mapReviver: (_key: string, value: unknown) => unknown;
 export declare const slimParseWorkerResultsForCache: (chunkResults: readonly ParseWorkerResult[]) => ParseWorkerResult[];
 /** Load one chunk shard. Does not retain it in `cache.entries`. */
 export declare const loadParseCacheChunk: (cache: ParseCache, chunkHash: string) => Promise<ParseWorkerResult[] | undefined>;
+/** Drop the mkdir memo after the staging tree is wiped so the next persist recreates it. */
+export declare const forgetCreatedParseCacheDir: (storagePath: string) => void;
 /**
  * Persist one chunk shard and avoid retaining it in RAM for the rest of the
  * run. Falls back to `cache.entries` when `storagePath` is unset (unit tests).
@@ -114,3 +151,4 @@ export declare const saveParseCache: (storagePath: string, cache: ParseCache) =>
  * don't keep their stale entries forever.
  */
 export declare const pruneCache: (cache: ParseCache, usedHashes: ReadonlySet<string>) => number;
+export declare const emptyParseCache: (storagePath?: string) => ParseCache;

package/dist/storage/parse-cache.js

@@ -6,10 +6,12 @@
  * does is skip the tree-sitter worker dispatch when a chunk's contents
  * haven't changed since the last run.
  *
- * Granularity: chunk-level. The parse phase chunks files into ~20MB byte
- * budgets. The cache key is `sha256(joined(filePath:contentHash for each
- * file in the chunk, sorted))`. A change to a single file invalidates only
- * that file's chunk — typically 1 of ~50 chunks on a 1000-file repo.
+ * Granularity: chunk-level. Files are assigned to a stable
+ * `(language, hash(path) mod 128)` bucket, then packed to a 2 MiB (or
+ * operator) byte budget *inside* that bucket. Membership does not depend
+ * on worker count. The cache key is `sha256(joined(filePath:contentHash
+ * for each file in the chunk, sorted))`. A content edit invalidates only
+ * that file's pack; add/delete/rename only the affected bucket.
  *
  * Why not per-file:
  * - Workers process sub-batches and emit aggregated `ParseWorkerResult`s.
@@ -17,15 +19,17 @@
  * - Chunk-level invalidation gives a useful speedup floor (98% on a single
  *   1-of-50 invalidated chunk) without touching the worker.
  *
- * Survives `--force` because it's content-addressed: the same bytes always
- * produce the same key. `--force` only matters for the LadybugDB writeback;
- * the cache itself is always safe to reuse.
+ * `--force` still reuses content-addressed shards (it only rebuilds graph/FTS).
+ * `useParseCache: false` reparses every file, writes a staging generation, and
+ * publishes onto this cache only after a successful analysis.
  */
 import { createHash } from 'crypto';
 import { createRequire } from 'module';
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
+import { compareCodeUnits } from '../lib/utils.js';
+import { copyV8CacheIfPresent, tryLoadV8Cache, writeV8CacheFile } from './v8-sidecar.js';
 /**
  * Cache version composed of:
  *   - A schema bump knob (`SCHEMA_BUMP`) for hand-controlled invalidation
@@ -627,6 +631,16 @@ import { fileURLToPath } from 'url';
 // therefore takes 79, the next free value above origin/main and every open PR
 // found by the contents-API scan at their exact head SHAs.
 //
+// 79 -> 80 for #3088: parse-cache membership is `(language, sha256(path) mod
+// 128)` then the byte budget *inside* that bucket. Worker count is no longer a
+// membership input, so a warm v79 cache keyed sequential scan-order packs (and
+// on multi-worker hosts, pool×2 MiB mega-chunks) must miss. Sidecar-era
+// ParsedFile stores (#3086/#3087) share PARSE_CACHE_VERSION, so both stores
+// invalidate in lockstep. origin/main at allocation is 79; open PRs that still
+// touch gitnexus/src/storage/parse-cache.ts claim 78 (#3060), 71 (#2840), and
+// 2 (#1616) — none claim 80. RE-CHECK AGAINST origin/main AND OPEN PRs
+// IMMEDIATELY BEFORE MERGING.
+//
 // WHY THIS IS STILL A HAND-PICKED NUMBER, when `SCHEMA_FINGERPRINT` next door
 // is a derived sha256 that cannot collide. The derivation exists and already
 // runs: `resolveAnalyzerRunnerIdentity` computes `build.digest` over the
@@ -645,7 +659,78 @@ import { fileURLToPath } from 'url';
 // `route-extractors/` and `workers/` module content — would close the missing-
 // bump axis without invalidating on unrelated churn, and is the real follow-up.
 // RE-CHECK AGAINST origin/main AND OPEN PRs IMMEDIATELY BEFORE MERGING.
-const SCHEMA_BUMP = 79;
+// 80 -> 81: ParsedFile and parse-cache shards are one immutable `.v8` envelope
+// each (no JSON/path/generation siblings). A v80 index still names `.json`
+// keys and would skip workers while scope-resolution found nothing — the
+// #1983 main-thread reparse. origin/main at allocation is 80.
+// 81 -> 82: Java and Kotlin ParsedFile capture side channels now carry
+// programmatic Spring lookup facts. A warm v81 cache has no such facts, so it
+// would skip workers and silently omit the new INJECTS edges. origin/main at
+// allocation is 81.
+// 82 -> 83: Java Lombok @Data/@Getter/@Setter accessor synthesis emits
+// synthetic Method nodes, HAS_METHOD edges, and matching scope captures into
+// ParseWorkerResult / ParsedFile. A warm v82 cache replays pre-Lombok worker
+// output and silently omits those callables. origin/main at allocation is 82.
+// 83 -> 84: Kotlin val/var properties synthesize JVM get/set Method nodes
+// (same provider hook as Java Lombok). A warm v83 cache omits those callables.
+// origin/main at allocation is 83 (Java Lombok on this branch).
+// 84 -> 85: JVM synthetic accessor captures now use the declaration
+// qualified_name key consumed by scope extraction, and Kotlin accessor planning
+// follows JvmAbi naming plus conservative @JvmName suppression. A warm v84
+// cache can replay stale names and declaration metadata.
+// 85 -> 86: Kotlin interface property accessors now record isAbstract on the
+// synthetic Method. A warm v85 cache replays them as concrete.
+// 86 -> 87: ModuleConstants gained wildcardImports (static-import-asterisk
+// materialization) — a warm v86 cache has no wildcard bindings, so folding
+// would skip them and drop wildcard-imported route constants. origin/main at
+// allocation is 86 (#2885).
+// 87 -> 88: Java ModuleConstants now preserves unfoldable declaration names
+// across worker/cache replay so wildcard expansion cannot resurrect an imported
+// member hidden by a local field. A warm v87 cache lacks that shadow metadata.
+// 88 -> 89: the same side channels now carry Spring messaging facts — the
+// arguments of non-HTTP handler annotations (`@KafkaListener(topics = ...)`)
+// and a new `springMessageProducerFacts` list for template publishes
+// (`KafkaTemplate.send`, `RabbitTemplate`/`JmsTemplate.convertAndSend`,
+// `StreamBridge.send`). Both are parse-time worker output replayed verbatim
+// from `ParsedFile.captureSideChannel`, so a warm v88 cache would skip workers
+// and hand the annotation facts back with no `args` and the producer list
+// empty. Measured on the fixture app: a warm all-cache-hit run
+// (`usedWorkerPool=false`, `reparsedFileCount=0`) reproduces 6 Java and 7
+// Kotlin producer facts purely from the store, which is exactly the state a
+// pre-change cache would have served as zero. origin/main at allocation is 88.
+// RE-CHECK AGAINST origin/main AND OPEN PRs IMMEDIATELY BEFORE MERGING — this
+// entry was allocated 83 first, and five bumps landed upstream before it merged.
+// 89 -> 90 (#2865): route decorator captures now carry `handlerName` in
+// `decoratorRoutes`, which is what lets `resolveRouteHandlerSymbols` stamp
+// `handlerSymbolId` and the routes phase emit the definition-level
+// HANDLES_ROUTE edge. The field is minted in the parse WORKER and persisted
+// verbatim, so a warm v89 cache replays handler-less decorator routes: every
+// route loses its definition-level association on incremental analyze while
+// every cold-run test passes — the inert-feature trap the entries above record.
+// 89 is now taken by merged #3128. 90 is the next free value above origin/main
+// (89) and above every in-flight claim found by scanning open PRs'
+// parse-cache.ts at their exact head SHAs (highest other open claim was still
+// ≤88). RE-CHECK AGAINST origin/main AND OPEN PRs IMMEDIATELY BEFORE MERGING.
+// 90 -> 91 (#3130): Kotlin providers now emit Spring decoratorRoutes plus
+// ModuleConstants shadow metadata. A warm v90 cache would replay unchanged
+// Kotlin files with neither route candidates nor the constant declarations
+// needed to fold them, leaving the new ingestion path silently inert.
+// 91 -> 92 (#1432): the shared callable-flow reader (`callable-flow-captures.ts`)
+// no longer names a callee by simple name for a MEMBER call and gates a
+// field-stored-callable invoke on a visible member store — parse-time capture
+// facts for Kotlin / C++ / C# / TypeScript member calls change (the
+// scope-capture bench re-baselined all four), and Zig files are captured for
+// the first time, with rules that changed within the PR (qualified struct
+// literals, enum-variant field bindings, receiver tagging). A warm v91 cache
+// replays the old facts verbatim, `--force` included: a reviewer re-testing a
+// later head of this PR on an index built from an earlier one measured a
+// byte-identical graph until `parse-cache/` and `parsedfile-cache/` were
+// deleted by hand. 92 is the next free value above origin/main (91) at merge
+// time. RE-CHECK AGAINST origin/main AND OPEN PRs IMMEDIATELY BEFORE MERGING.
+// v93: Zig call captures inside a comptime-false branch carry
+// `@reference.static-gated` (feat/zig-static-gated-edges); the site gains
+// `staticGated` and the CALLS edge a BOOLEAN column.
+const SCHEMA_BUMP = 93;
 const GITNEXUS_PKG_VERSION = (() => {
     try {
         // package.json sits at gitnexus/package.json — two levels up from
@@ -673,16 +758,74 @@ const GITNEXUS_PKG_VERSION = (() => {
     return '0.0.0-unknown';
 })();
 export const PARSE_CACHE_VERSION = `${SCHEMA_BUMP}+${GITNEXUS_PKG_VERSION}`;
+/** SHA-256 hex of a string or buffer (paths for bucket ids, contents for cache keys). */
+const sha256Hex = (input) => createHash('sha256')
+    .update(typeof input === 'string' ? Buffer.from(input) : input)
+    .digest('hex');
+/** Stable parse-cache bucket count (#3088). Changing this requires SCHEMA_BUMP. */
+export const PARSE_CACHE_BUCKET_COUNT = 128;
+/** Bucket id for cache membership: `sha256(path) mod N` without IEEE-754 truncation. */
+export const parseCacheBucketId = (filePath) => Number(BigInt(`0x${sha256Hex(filePath)}`) % BigInt(PARSE_CACHE_BUCKET_COUNT));
+/**
+ * Pack files into parse-cache chunks: group by (language, bucket id), sort
+ * paths inside the group, then cut at `byteBudget`. Bucket visit order is
+ * the lexicographic order of `${language}\\0${bucketId}` keys (deterministic,
+ * independent of scan order and worker count).
+ */
+export const packParseCacheChunks = (files, byteBudget) => {
+    const buckets = new Map();
+    for (const file of files) {
+        const key = `${file.language}\0${parseCacheBucketId(file.path)}`;
+        const list = buckets.get(key);
+        if (list)
+            list.push(file);
+        else
+            buckets.set(key, [file]);
+    }
+    const chunks = [];
+    for (const key of [...buckets.keys()].sort()) {
+        const group = buckets.get(key);
+        group.sort((a, b) => compareCodeUnits(a.path, b.path));
+        let current = [];
+        let bytes = 0;
+        for (const file of group) {
+            if (current.length > 0 && bytes + file.size > byteBudget) {
+                chunks.push(current);
+                current = [];
+                bytes = 0;
+            }
+            current.push(file.path);
+            bytes += file.size;
+        }
+        if (current.length > 0)
+            chunks.push(current);
+    }
+    return chunks;
+};
 const LEGACY_CACHE_FILENAME = 'parse-cache.json';
 const CACHE_DIRNAME = 'parse-cache';
+/**
+ * Per-run staging root for `useParseCache: false`. Parse-cache shards and the
+ * ParsedFile stores write here so a crash cannot mix a new generation into the
+ * live `.gitnexus/parse-cache` / `parsedfile-cache` trees. `saveParseCache`
+ * publishes onto the live `storagePath` only after a successful analysis.
+ */
+export const COLD_PARSE_REBUILD_DIRNAME = 'parse-rebuild';
+/** Deterministic staging path — tests only. Production uses {@link createColdParseRebuildDir}. */
+export const getColdParseRebuildDir = (storagePath) => path.join(storagePath, COLD_PARSE_REBUILD_DIRNAME);
+/**
+ * Unique per analyze process so concurrent `--no-parse-cache` runs on
+ * different branch slots (shared `.gitnexus`, separate index locks) do not
+ * delete each other's staging tree.
+ */
+export const createColdParseRebuildDir = async (storagePath) => {
+    await fs.mkdir(storagePath, { recursive: true });
+    return fs.mkdtemp(path.join(storagePath, `${COLD_PARSE_REBUILD_DIRNAME}.`));
+};
 const CACHE_INDEX_FILENAME = 'index.json';
 /** Keys on disk always come from `computeChunkHash` — 64-char lowercase hex. */
 const CHUNK_CACHE_KEY_HEX_RE = /^[a-f0-9]{64}$/;
 const isValidChunkCacheKey = (chunkHash) => CHUNK_CACHE_KEY_HEX_RE.test(chunkHash);
-/** SHA-256 hex of a single string or buffer. */
-const sha256Hex = (input) => createHash('sha256')
-    .update(typeof input === 'string' ? Buffer.from(input) : input)
-    .digest('hex');
 /** Stable hash of a single file's contents — used by callers to compose a chunk hash. */
 export const fileContentHash = (content) => sha256Hex(content);
 export const computeChunkHash = (entries, pdg = false) => {
@@ -759,7 +902,7 @@ export const mapReviver = (_key, value) => {
 const getLegacyCachePath = (storagePath) => path.join(storagePath, LEGACY_CACHE_FILENAME);
 const getCacheDirPath = (storagePath) => path.join(storagePath, CACHE_DIRNAME);
 const getCacheIndexPath = (storagePath) => path.join(getCacheDirPath(storagePath), CACHE_INDEX_FILENAME);
-const getCacheChunkPath = (storagePath, chunkHash) => path.join(getCacheDirPath(storagePath), `${chunkHash}.json`);
+const getCacheChunkPath = (storagePath, chunkHash) => path.join(getCacheDirPath(storagePath), `${chunkHash}.v8`);
 /**
  * Drop fields that are not replayed by `mergeChunkResults` / parse-impl after
  * RING4-1 (#942). Shrinks on-disk shards and peak RSS during cold runs.
@@ -784,9 +927,12 @@ const readParseCacheChunkFromDisk = async (storagePath, chunkHash) => {
     if (!isValidChunkCacheKey(chunkHash))
         return undefined;
     try {
-        const chunkRaw = await fs.readFile(getCacheChunkPath(storagePath, chunkHash), 'utf-8');
-        const chunkData = JSON.parse(chunkRaw, mapReviver);
-        return Array.isArray(chunkData) ? chunkData : undefined;
+        const chunkPath = getCacheChunkPath(storagePath, chunkHash);
+        const v8Hit = await tryLoadV8Cache(chunkPath);
+        if (v8Hit?.kind === 'hit' && Array.isArray(v8Hit.value)) {
+            return v8Hit.value;
+        }
+        return undefined;
     }
     catch {
         return undefined;
@@ -809,6 +955,10 @@ export const loadParseCacheChunk = async (cache, chunkHash) => {
  * process-scoped, so the Set stays bounded.
  */
 const createdCacheDirs = new Set();
+/** Drop the mkdir memo after the staging tree is wiped so the next persist recreates it. */
+export const forgetCreatedParseCacheDir = (storagePath) => {
+    createdCacheDirs.delete(getCacheDirPath(storagePath));
+};
 /**
  * Persist one chunk shard and avoid retaining it in RAM for the rest of the
  * run. Falls back to `cache.entries` when `storagePath` is unset (unit tests).
@@ -821,19 +971,16 @@ export const persistParseCacheChunk = async (cache, chunkHash, chunkResults) =>
             await fs.mkdir(cacheDir, { recursive: true });
             createdCacheDirs.add(cacheDir);
         }
-        const payload = JSON.stringify(slim, mapReplacer);
         const chunkPath = getCacheChunkPath(cache.storagePath, chunkHash);
-        try {
-            await fs.writeFile(chunkPath, payload, 'utf-8');
-        }
-        catch (error) {
-            if (error.code !== 'ENOENT')
-                throw error;
-            // Long-lived analyze --watch processes can replace the sharded cache
-            // directory after this process-local memo recorded it as created.
+        let ok = await writeV8CacheFile(chunkPath, slim);
+        if (!ok) {
             await fs.mkdir(cacheDir, { recursive: true });
             createdCacheDirs.add(cacheDir);
-            await fs.writeFile(chunkPath, payload, 'utf-8');
+            ok = await writeV8CacheFile(chunkPath, slim);
+        }
+        if (!ok) {
+            cache.entries.set(chunkHash, slim);
+            return;
         }
         cache.onDiskKeys ??= new Set();
         cache.onDiskKeys.add(chunkHash);
@@ -930,28 +1077,27 @@ export const saveParseCache = async (storagePath, cache) => {
     // index from what we persisted, not from the raw usedKeys snapshot.
     const writtenKeys = [];
     for (const chunkHash of keys) {
-        const chunkPath = path.join(tmpDir, `${chunkHash}.json`);
+        const chunkPath = path.join(tmpDir, `${chunkHash}.v8`);
         const inMemory = cache.entries.get(chunkHash);
         if (inMemory !== undefined) {
-            let payload;
-            try {
-                payload = JSON.stringify(inMemory, mapReplacer);
+            if (await writeV8CacheFile(chunkPath, inMemory)) {
+                writtenKeys.push(chunkHash);
             }
-            catch {
-                continue;
-            }
-            await fs.writeFile(chunkPath, payload, 'utf-8');
-            writtenKeys.push(chunkHash);
             continue;
         }
-        const existingPath = getCacheChunkPath(storagePath, chunkHash);
-        try {
-            await fs.copyFile(existingPath, chunkPath);
+        // Cold rebuilds persist mid-run under `cache.storagePath` (staging). Prefer
+        // that generation over a same-hash shard still sitting in the live dir so
+        // we never publish a mixed old/new pair. Sibling-branch keys (#2106) that
+        // this run did not rewrite still copy from the live path.
+        const stagedPath = cache.storagePath !== undefined && cache.storagePath !== storagePath
+            ? getCacheChunkPath(cache.storagePath, chunkHash)
+            : undefined;
+        const livePath = getCacheChunkPath(storagePath, chunkHash);
+        const fromStaged = Boolean(stagedPath && cache.onDiskKeys?.has(chunkHash));
+        const sourcePath = fromStaged && stagedPath ? stagedPath : livePath;
+        if (await copyV8CacheIfPresent(sourcePath, chunkPath)) {
             writtenKeys.push(chunkHash);
         }
-        catch {
-            /* shard missing — skip; next run treats as cache miss */
-        }
     }
     const index = {
         version: cache.version,
@@ -989,10 +1135,11 @@ export const pruneCache = (cache, usedHashes) => {
     }
     return removed;
 };
-const emptyCache = (storagePath) => ({
+export const emptyParseCache = (storagePath) => ({
     version: PARSE_CACHE_VERSION,
     entries: new Map(),
     usedKeys: new Set(),
     storagePath,
     onDiskKeys: storagePath ? new Set() : undefined,
 });
+const emptyCache = emptyParseCache;