gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/storage/repo-manager.js

@@ -16,10 +16,10 @@
 import fs from 'fs/promises';
 import { realpathSync } from 'fs';
 import path from 'path';
-import os from 'os';
 import { getInferredRepoName, resolveRepoIdentityRoot, stripUrlCredentials } from './git.js';
 import { stripWindowsLongPathPrefix } from '../lib/utils.js';
 import { writeFileAtomic } from './fs-atomic.js';
+import { getGlobalDir } from './global-dir.js';
 import { logger } from '../core/logger.js';
 import { acquireIndexLock, IndexLockTimeoutError } from './index-lock.js';
 import { branchSlug, BRANCHES_DIR, resolveBranchPlacement, } from './branch-index.js';
@@ -33,6 +33,7 @@ export { branchSlug, resolveBranchPlacement };
 // cycle that made the extraction necessary. `LEGACY_METADATA_FILE` and
 // `tryReadMetaFile` stay module-private here, exactly as before.
 export { getStoragePath, INDEX_METADATA_FILE, isMissingFilesystemError, loadMeta };
+export { getGlobalDir } from './global-dir.js';
 /**
  * Normalise a repo path for registry comparison across platforms
  * (#664 review feedback from @evander-wang).
@@ -436,12 +437,6 @@ const ensureGitInfoExclude = async (repoPath) => {
     }
 };
 // ─── Global Registry (~/.gitnexus/registry.json) ───────────────────────
-/**
- * Get the path to the global GitNexus directory
- */
-export const getGlobalDir = () => {
-    return process.env.GITNEXUS_HOME || path.join(os.homedir(), '.gitnexus');
-};
 /**
  * Get the path to the global registry file
  */
@@ -478,11 +473,9 @@ const REGISTRY_LOCK_TIMEOUT_MS = 5_000;
  * registry-private lock namespace; the handle is kernel-owned on supported
  * platforms and crash-reclaimable by the existing fallback.
  *
- * On timeout the transaction proceeds UNLOCKED rather than throwing: the lock
- * closes a lost-update race that existed unguarded before #2716, so degrading
- * to the old best-effort behaviour is strictly better than failing an
- * `analyze`/`list`/`augment` outright on a wedged lock (a stale pid-reuse
- * ghost on platforms without start-time verification can look live forever).
+ * On timeout the transaction fails closed: continuing unlocked would reintroduce
+ * the lost-update race this lock exists to prevent and can silently discard a
+ * concurrent registration.
  */
 const withRegistryLock = async (operation) => {
     let lock = null;
@@ -496,9 +489,10 @@ const withRegistryLock = async (operation) => {
         });
     }
     catch (err) {
-        if (!(err instanceof IndexLockTimeoutError))
-            throw err;
-        logger.warn({ timeoutMs: REGISTRY_LOCK_TIMEOUT_MS }, 'Timed out waiting for the global registry lock; proceeding without it. A concurrent registry write may be lost.');
+        if (err instanceof IndexLockTimeoutError) {
+            logger.error({ timeoutMs: REGISTRY_LOCK_TIMEOUT_MS }, 'Timed out waiting for the global registry lock; refusing an unlocked registry transaction.');
+        }
+        throw err;
     }
     try {
         return await operation();
@@ -666,14 +660,11 @@ export const readRegistryStrict = async () => readRegistryFile(true);
  * Atomic tmp+rename: a crash mid-write can never leave a truncated
  * registry.json that the next load would treat as empty and silently drop
  * every registered repo (#2106 R9). The tmp path must stay per-write — the
- * registry is the one file every gitnexus process on the machine writes, and
- * `withRegistryLock` degrades to unlocked on timeout, so the write cannot rely
- * on the lock to keep two writers off one staging path (#2888).
- *
- * `attempts` is forwarded to the rename retry; best-effort callers pass `1`.
+ * registry is the one file every gitnexus process on the machine writes (#2888).
  */
 const writeRegistry = async (entries, attempts) => {
-    await fs.mkdir(getGlobalDir(), { recursive: true });
+    const dir = getGlobalDir();
+    await fs.mkdir(dir, { recursive: true });
     await writeFileAtomic(getGlobalRegistryPath(), JSON.stringify(sanitizeEntries(entries), null, 2), attempts);
 };
 /**
@@ -771,7 +762,10 @@ const registerRepoUnlocked = async (repoPath, meta, opts) => {
     // expands macOS /var → /private/var and Windows 8.3 → long-name,
     // falling back to `path.resolve` when the path doesn't exist.
     const canonicalInput = canonicalizePath(repoPath);
-    const entries = await readRegistry();
+    // Mutating writes must not treat an unreadable/truncated registry as empty
+    // (#3094): lenient `readRegistry()` returns `[]` on parse failure and would
+    // replace the machine-wide file with only this entry. ENOENT stays empty.
+    const entries = await readRegistryStrict();
     const existingIdx = entries.findIndex((e) => {
         // Canonicalise the STORED entry too so pre-canonicalisation
         // registries (written by older versions, or paths passed in a
@@ -881,7 +875,7 @@ const registerRepoUnlocked = async (repoPath, meta, opts) => {
     // R9): re-derive THIS run's delta against the FRESHEST snapshot so a
     // concurrent change to the OTHER axis (a branch upsert vs a primary refresh)
     // survives instead of being clobbered by a stale entry-time view.
-    const fresh = await readRegistry();
+    const fresh = await readRegistryStrict();
     const freshIdx = fresh.findIndex((e) => {
         const a = canonicalizePath(e.path);
         return registryPathEquals(a, canonicalInput);
@@ -1301,6 +1295,24 @@ export const resolveRegistryEntry = (entries, target) => {
     const availableNames = entries.map((e) => (nameCounts.get(e.name.toLowerCase()) ?? 0) > 1 ? `${e.name} (${e.path})` : e.name);
     throw new RegistryNotFoundError(target, availableNames);
 };
+/**
+ * Name-only registry match (the name tier of {@link resolveRegistryEntry},
+ * without path matching). Used by `group.yaml` member *values*, which are
+ * registry aliases, not filesystem paths.
+ *
+ * Zero matches → `undefined` (caller treats as missing). One match → that
+ * entry. Two or more → {@link RegistryAmbiguousTargetError}.
+ */
+export const findRegistryEntryByName = (entries, name) => {
+    const targetLower = name.toLowerCase();
+    const nameMatches = entries.filter((e) => e.name.toLowerCase() === targetLower);
+    if (nameMatches.length === 1)
+        return nameMatches[0];
+    if (nameMatches.length > 1) {
+        throw new RegistryAmbiguousTargetError(name, nameMatches);
+    }
+    return undefined;
+};
 /**
  * List all registered repos from the global registry.
  *
@@ -1374,8 +1386,6 @@ export const listRegisteredRepos = async (opts) => {
         try {
             await withRegistryLock(async () => {
                 const fresh = await readRegistry();
-                // attempts: 1 — the catch below discards a failure, so the rename
-                // backoff would only make every other process wait out this lock.
                 await writeRegistry(fresh.filter((entry) => !pruned.has(entry.path)), 1);
             });
         }

package/dist/storage/repo-meta.d.ts

@@ -78,6 +78,35 @@ export interface RepoMeta {
     repoPath: string;
     lastCommit: string;
     indexedAt: string;
+    /**
+     * Runtime enrichment mode plus redacted scan exclusions. Payload data and
+     * absolute/external paths are deliberately excluded from metadata.
+     */
+    springActuator?: {
+        enabled: boolean;
+        /**
+         * Normalized repo-relative inputs that must remain excluded from all future
+         * source scans. The list is empty when every configured input was external.
+         */
+        repoRelativeInputs: string[];
+    };
+    /**
+     * Whether the index was built with AsyncAPI document reading enabled.
+     *
+     * Only the FLAG is recorded, unlike `springActuator` above, because the two
+     * options need different things from this field. Actuator inputs are retained
+     * so future scans keep excluding them; documents are deliberately NOT
+     * excluded from scanning — a committed one wants its real `File` node — so
+     * there is nothing to retain, and recording the configured path would put an
+     * operator's absolute directory layout into index metadata for no consumer.
+     *
+     * The flag alone is what the disable transition needs: without it, dropping
+     * the option leaves document-derived destinations in an index with nothing
+     * able to notice they should go.
+     */
+    asyncApiSpec?: {
+        enabled: boolean;
+    };
     /**
      * Analyzer/runtime receipt for the successful run represented by this
      * metadata. Optional so indexes written by older GitNexus releases remain
@@ -185,6 +214,11 @@ export interface RepoMeta {
      * containing relevant source files.
      */
     analysisFeatures?: Record<string, number>;
+    /**
+     * Canonical registered-prefix list used to resolve vendor Spring mapping
+     * annotations. A changed value invalidates persisted JVM Route evidence.
+     */
+    springVendorPrefixes?: string;
     /**
      * The resolved GITNEXUS_FTS_CJK_SEGMENTATION mode ('none' | 'bigram') the
      * existing index's content/description columns were last written under

package/dist/storage/v8-sidecar.d.ts

@@ -0,0 +1,48 @@
+/** Envelope version — independent of PARSE_CACHE_VERSION / SCHEMA_BUMP. */
+export declare const V8_CACHE_FORMAT = 5;
+/**
+ * Collapse duplicate strings in a live deserialized graph into `pool`, mutating
+ * in place so object identity (shared `SymbolDefinition`s, Maps) is preserved.
+ * Required after `v8.deserialize` of ParsedFile shards: V8 does not recreate
+ * the JSON reviver's cross-shard string intern, and skipping it regresses
+ * retained heap (~+59% measured vs interned JSON).
+ */
+export declare const internGraphStrings: (root: unknown, pool: Map<string, string>) => unknown;
+/** NDJSON listing cannot encode paths that themselves contain CR/LF/NUL. */
+export declare const encodeCachePathListing: (paths: readonly string[]) => Buffer;
+/**
+ * Parse a counted NDJSON path listing. Returns `null` when it must not be
+ * trusted to skip the payload: missing trailing newline, CR/NUL, or a count
+ * that does not match the remaining lines.
+ */
+export declare const parseCachePathListing: (raw: Buffer) => string[] | null;
+export type V8CacheHit = {
+    kind: 'hit';
+    value: unknown;
+    bytes: number;
+};
+export type V8CacheSkip = {
+    kind: 'skip';
+    bytes: number;
+};
+export type V8CacheLoad = V8CacheHit | V8CacheSkip;
+export type V8CacheInspection = {
+    paths: readonly string[];
+};
+/**
+ * Validate the immutable envelope metadata needed by the durable ParsedFile
+ * warm-hit gate without deserializing its payload. Atomic publication means a
+ * runtime-compatible envelope whose exact file length and counted path listing
+ * validate is a stable snapshot candidate; malformed/truncated envelopes miss.
+ */
+export declare const inspectV8Cache: (filePath: string) => Promise<V8CacheInspection | undefined>;
+/**
+ * Load a cache file. When `wantPaths` is set and a digest-verified non-empty
+ * path listing has no intersection, returns `{ kind: 'skip' }` without
+ * deserializing. An authentic listing that does not parse deserializes (fail
+ * closed). Envelope/runtime/digest failure returns undefined (miss).
+ */
+export declare const tryLoadV8Cache: (filePath: string, internPool?: Map<string, string>, wantPaths?: ReadonlySet<string>) => Promise<V8CacheLoad | undefined>;
+export declare const writeV8CacheFile: (filePath: string, graph: unknown, paths?: readonly string[]) => Promise<boolean>;
+export declare const writeV8CacheFileSync: (filePath: string, graph: unknown, paths?: readonly string[]) => boolean;
+export declare const copyV8CacheIfPresent: (srcPath: string, dstPath: string) => Promise<boolean>;

package/dist/storage/v8-sidecar.js

@@ -0,0 +1,347 @@
+/**
+ * One-file V8 cache envelope for parse-cache and ParsedFile shards.
+ *
+ * Each object-graph shard is a single immutable `.v8` file published by
+ * tmp+rename. JSON is not a fallback: a missing, corrupt, runtime-incompatible,
+ * or deserialize-failed envelope is a cache miss (re-extract / re-dispatch).
+ * Tiny JSON manifests (`index.json`) stay outside this module.
+ *
+ * Envelope: magic, format, Node major, V8 version, optional path listing,
+ * `v8.serialize` of the live graph, then SHA-256 of listing||payload. Path
+ * bytes live before the payload so a ParsedFile loader can skip a shard whose
+ * authenticated listing misses `wantPaths` without deserializing. An
+ * unreadable/invalid listing is fail-closed: deserialize, never skip.
+ */
+import { promises as fs } from 'node:fs';
+import { createHash } from 'node:crypto';
+import v8 from 'node:v8';
+import { logger } from '../core/logger.js';
+import { linkOrCopyFile, writeFileAtomicBytes, writeFileAtomicBytesSync } from './fs-atomic.js';
+const MAGIC = Buffer.from('GNXV8CF1', 'ascii');
+/** Envelope version — independent of PARSE_CACHE_VERSION / SCHEMA_BUMP. */
+export const V8_CACHE_FORMAT = 5;
+const U32 = 4;
+const U16 = 2;
+const PAYLOAD_HASH_LEN = 32;
+const MAGIC_LEN = 8;
+const FIXED_PREFIX = MAGIC_LEN + U32 + U16 + U16; // magic + format + nodeMajor + v8len
+const internString = (value, pool) => {
+    const hit = pool.get(value);
+    if (hit !== undefined)
+        return hit;
+    pool.set(value, value);
+    return value;
+};
+/**
+ * Collapse duplicate strings in a live deserialized graph into `pool`, mutating
+ * in place so object identity (shared `SymbolDefinition`s, Maps) is preserved.
+ * Required after `v8.deserialize` of ParsedFile shards: V8 does not recreate
+ * the JSON reviver's cross-shard string intern, and skipping it regresses
+ * retained heap (~+59% measured vs interned JSON).
+ */
+export const internGraphStrings = (root, pool) => {
+    const seen = new WeakSet();
+    const walk = (value) => {
+        if (typeof value === 'string')
+            return internString(value, pool);
+        if (value === null || typeof value !== 'object')
+            return value;
+        if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer)
+            return value;
+        if (seen.has(value))
+            return value;
+        seen.add(value);
+        if (value instanceof Map) {
+            const entries = [...value];
+            value.clear();
+            for (const [k, v] of entries)
+                value.set(walk(k), walk(v));
+            return value;
+        }
+        if (value instanceof Set) {
+            const entries = [...value];
+            value.clear();
+            for (const v of entries)
+                value.add(walk(v));
+            return value;
+        }
+        if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++)
+                value[i] = walk(value[i]);
+            return value;
+        }
+        const rec = value;
+        for (const key of Object.keys(rec)) {
+            rec[key] = walk(rec[key]);
+        }
+        return value;
+    };
+    return walk(root);
+};
+const nodeMajor = () => Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+const isEnoent = (err) => err.code === 'ENOENT';
+const warnCache = (err, filePath, msg) => {
+    logger.warn({ err, filePath }, msg);
+};
+/** NDJSON listing cannot encode paths that themselves contain CR/LF/NUL. */
+export const encodeCachePathListing = (paths) => {
+    if (paths.length === 0)
+        return Buffer.alloc(0);
+    if (paths.some((p) => /[\r\n\0]/.test(p)))
+        return Buffer.alloc(0);
+    return Buffer.from(`${paths.length}\n${paths.join('\n')}\n`, 'utf8');
+};
+/**
+ * Parse a counted NDJSON path listing. Returns `null` when it must not be
+ * trusted to skip the payload: missing trailing newline, CR/NUL, or a count
+ * that does not match the remaining lines.
+ */
+export const parseCachePathListing = (raw) => {
+    if (raw.byteLength === 0)
+        return [];
+    let sidecarRaw;
+    try {
+        sidecarRaw = new TextDecoder('utf-8', { fatal: true }).decode(raw);
+    }
+    catch {
+        return null;
+    }
+    if (sidecarRaw.includes('\0') || sidecarRaw.includes('\r') || !sidecarRaw.endsWith('\n')) {
+        return null;
+    }
+    const nl = sidecarRaw.indexOf('\n');
+    if (nl < 0)
+        return null;
+    const countToken = sidecarRaw.slice(0, nl);
+    if (!/^[0-9]+$/.test(countToken))
+        return null;
+    const count = Number(countToken);
+    const body = sidecarRaw.slice(nl + 1);
+    const listed = body === '' ? [] : body.slice(0, -1).split('\n');
+    if (listed.length !== count)
+        return null;
+    return listed;
+};
+const encodeEnvelope = (graph, paths) => {
+    let payload;
+    try {
+        payload = v8.serialize(graph);
+    }
+    catch (err) {
+        warnCache(err, '', 'v8 cache: serialize failed; treating as miss on next load');
+        return undefined;
+    }
+    const pathListing = encodeCachePathListing(paths);
+    const listed = parseCachePathListing(pathListing);
+    const pathCount = listed === null ? 0 : listed.length;
+    if (payload.byteLength > 0xffff_ffff || pathListing.byteLength > 0xffff_ffff)
+        return undefined;
+    const v8ver = Buffer.from(process.versions.v8, 'utf8');
+    if (v8ver.byteLength > 0xffff)
+        return undefined;
+    const header = Buffer.allocUnsafe(FIXED_PREFIX + v8ver.length + U32 * 3);
+    MAGIC.copy(header, 0);
+    header.writeUInt32LE(V8_CACHE_FORMAT, MAGIC_LEN);
+    header.writeUInt16LE(nodeMajor(), MAGIC_LEN + U32);
+    header.writeUInt16LE(v8ver.length, MAGIC_LEN + U32 + U16);
+    v8ver.copy(header, FIXED_PREFIX);
+    let off = FIXED_PREFIX + v8ver.length;
+    header.writeUInt32LE(pathCount, off);
+    off += U32;
+    header.writeUInt32LE(pathListing.byteLength, off);
+    off += U32;
+    header.writeUInt32LE(payload.byteLength, off);
+    const payloadHash = createHash('sha256').update(pathListing).update(payload).digest();
+    return Buffer.concat([header, pathListing, payload, payloadHash]);
+};
+const decodePrefix = (buf) => {
+    if (buf.byteLength < FIXED_PREFIX)
+        return undefined;
+    if (!buf.subarray(0, MAGIC_LEN).equals(MAGIC))
+        return undefined;
+    if (buf.readUInt32LE(MAGIC_LEN) !== V8_CACHE_FORMAT)
+        return undefined;
+    const recordedNodeMajor = buf.readUInt16LE(MAGIC_LEN + U32);
+    const v8len = buf.readUInt16LE(MAGIC_LEN + U32 + U16);
+    const v8off = FIXED_PREFIX;
+    const countsOff = v8off + v8len;
+    if (buf.byteLength < countsOff + U32 * 3)
+        return undefined;
+    const recordedV8 = buf.subarray(v8off, v8off + v8len).toString('utf8');
+    const pathCount = buf.readUInt32LE(countsOff);
+    const pathBytes = buf.readUInt32LE(countsOff + U32);
+    const payloadLen = buf.readUInt32LE(countsOff + U32 * 2);
+    const pathsOff = countsOff + U32 * 3;
+    const payloadOff = pathsOff + pathBytes;
+    return {
+        recordedNodeMajor,
+        recordedV8,
+        pathCount,
+        pathBytes,
+        payloadLen,
+        pathsOff,
+        payloadOff,
+    };
+};
+const runtimeCompatible = (meta) => meta.recordedNodeMajor === nodeMajor() && meta.recordedV8 === process.versions.v8;
+const readExact = async (fh, offset, length) => {
+    const buf = Buffer.allocUnsafe(length);
+    let got = 0;
+    while (got < length) {
+        const { bytesRead } = await fh.read(buf, got, length - got, offset + got);
+        if (bytesRead === 0)
+            return undefined;
+        got += bytesRead;
+    }
+    return buf;
+};
+const readVerifiedPayload = async (fh, meta, pathRaw) => {
+    const payloadAndHash = await readExact(fh, meta.payloadOff, meta.payloadLen + PAYLOAD_HASH_LEN);
+    if (!payloadAndHash)
+        return undefined;
+    const payload = payloadAndHash.subarray(0, meta.payloadLen);
+    const expected = payloadAndHash.subarray(meta.payloadLen);
+    const digest = createHash('sha256').update(pathRaw).update(payload).digest();
+    return digest.equals(expected) ? payload : undefined;
+};
+/**
+ * Validate the immutable envelope metadata needed by the durable ParsedFile
+ * warm-hit gate without deserializing its payload. Atomic publication means a
+ * runtime-compatible envelope whose exact file length and counted path listing
+ * validate is a stable snapshot candidate; malformed/truncated envelopes miss.
+ */
+export const inspectV8Cache = async (filePath) => {
+    let fh;
+    try {
+        fh = await fs.open(filePath, 'r');
+        const st = await fh.stat();
+        const prefix = await readExact(fh, 0, Math.min(st.size, FIXED_PREFIX + 256 + U32 * 3));
+        if (!prefix)
+            return undefined;
+        const meta = decodePrefix(prefix);
+        if (!meta || !runtimeCompatible(meta))
+            return undefined;
+        if (meta.payloadOff + meta.payloadLen + PAYLOAD_HASH_LEN !== st.size || meta.pathBytes === 0) {
+            return undefined;
+        }
+        const pathRaw = prefix.byteLength >= meta.payloadOff
+            ? Buffer.from(prefix.subarray(meta.pathsOff, meta.payloadOff))
+            : await readExact(fh, meta.pathsOff, meta.pathBytes);
+        if (!pathRaw)
+            return undefined;
+        const listed = parseCachePathListing(pathRaw);
+        if (listed === null || listed.length !== meta.pathCount || listed.length === 0) {
+            return undefined;
+        }
+        if (!(await readVerifiedPayload(fh, meta, pathRaw)))
+            return undefined;
+        return { paths: listed };
+    }
+    catch (err) {
+        if (!isEnoent(err)) {
+            logger.debug({ err, filePath }, 'v8 cache: inspection failed; treating as miss');
+        }
+        return undefined;
+    }
+    finally {
+        await fh?.close().catch(() => { });
+    }
+};
+/**
+ * Load a cache file. When `wantPaths` is set and a digest-verified non-empty
+ * path listing has no intersection, returns `{ kind: 'skip' }` without
+ * deserializing. An authentic listing that does not parse deserializes (fail
+ * closed). Envelope/runtime/digest failure returns undefined (miss).
+ */
+export const tryLoadV8Cache = async (filePath, internPool, wantPaths) => {
+    let fh;
+    try {
+        fh = await fs.open(filePath, 'r');
+        const st = await fh.stat();
+        const prefix = await readExact(fh, 0, Math.min(st.size, FIXED_PREFIX + 256 + U32 * 3));
+        if (!prefix)
+            return undefined;
+        const meta = decodePrefix(prefix);
+        if (!meta)
+            return undefined;
+        if (!runtimeCompatible(meta))
+            return undefined;
+        if (meta.payloadOff + meta.payloadLen + PAYLOAD_HASH_LEN !== st.size)
+            return undefined;
+        let pathRaw = Buffer.alloc(0);
+        if (meta.pathBytes > 0) {
+            if (prefix.byteLength >= meta.payloadOff) {
+                pathRaw = Buffer.from(prefix.subarray(meta.pathsOff, meta.payloadOff));
+            }
+            else {
+                const raw = await readExact(fh, meta.pathsOff, meta.pathBytes);
+                if (!raw)
+                    return undefined;
+                pathRaw = Buffer.from(raw);
+            }
+        }
+        const payload = await readVerifiedPayload(fh, meta, pathRaw);
+        if (!payload)
+            return undefined;
+        if (wantPaths && wantPaths.size > 0 && meta.pathBytes > 0) {
+            const listed = parseCachePathListing(pathRaw);
+            if (listed !== null &&
+                listed.length === meta.pathCount &&
+                listed.length > 0 &&
+                !listed.some((p) => wantPaths.has(p))) {
+                return { kind: 'skip', bytes: st.size };
+            }
+        }
+        const value = v8.deserialize(payload);
+        if (internPool)
+            internGraphStrings(value, internPool);
+        return { kind: 'hit', value, bytes: st.size };
+    }
+    catch (err) {
+        if (!isEnoent(err)) {
+            logger.debug({ err, filePath }, 'v8 cache: load failed; treating as miss');
+        }
+        return undefined;
+    }
+    finally {
+        await fh?.close().catch(() => { });
+    }
+};
+export const writeV8CacheFile = async (filePath, graph, paths) => {
+    const blob = encodeEnvelope(graph, paths ?? []);
+    if (!blob)
+        return false;
+    try {
+        await writeFileAtomicBytes(filePath, blob, 1);
+        return true;
+    }
+    catch (err) {
+        warnCache(err, filePath, 'v8 cache: write failed; treating as miss');
+        return false;
+    }
+};
+export const writeV8CacheFileSync = (filePath, graph, paths) => {
+    const blob = encodeEnvelope(graph, paths ?? []);
+    if (!blob)
+        return false;
+    try {
+        writeFileAtomicBytesSync(filePath, blob);
+        return true;
+    }
+    catch (err) {
+        warnCache(err, filePath, 'v8 cache: write failed; treating as miss');
+        return false;
+    }
+};
+export const copyV8CacheIfPresent = async (srcPath, dstPath) => {
+    try {
+        await linkOrCopyFile(srcPath, dstPath);
+        return true;
+    }
+    catch (copyErr) {
+        if (!isEnoent(copyErr)) {
+            warnCache(copyErr, srcPath, 'v8 cache: copy failed; treating as miss');
+        }
+        return false;
+    }
+};

package/dist/types/pipeline.d.ts

@@ -13,6 +13,18 @@ export interface PipelineResult {
     totalFileCount: number;
     communityResult?: CommunityDetectionResult;
     processResult?: ProcessDetectionResult;
+    /**
+     * Runs the community/process phases that `skipDerivedGraphPhases` held back
+     * (#3016), against the same graph and phase outputs the pipeline already
+     * produced, and populates `communityResult`/`processResult` on this object.
+     *
+     * Present ONLY when those phases were skipped for that reason, so a caller
+     * that optimistically skipped them can still get a byte-identical derived
+     * layer on the paths that turn out to need one (full rebuild, escalated
+     * write, or an incremental run with deleted files). Absent means the phases
+     * either already ran or were disabled for an unrelated reason.
+     */
+    runDeferredDerivedPhases?: () => Promise<void>;
     /**
      * Additive diagnostics for registry-primary resolution decisions that
      * deliberately suppress edge emission. Empty means no diagnostic was
@@ -40,6 +52,8 @@ export interface PipelineResult {
     usedWorkerPool: boolean;
     /** Files actually dispatched to parser workers after parse-cache lookup. */
     reparsedFileCount: number;
+    /** Files restored from parse-cache chunks without parser-worker dispatch. */
+    parseCacheHitFileCount?: number;
     /** Files omitted from scope-resolution while the rest of analysis continued. */
     scopeExtractionFailures: readonly string[];
     /** Files scope resolution could not inspect because their parser was unavailable. */

package/dist/utils/process-identity.d.ts

@@ -0,0 +1,2 @@
+export declare function isProcessAlive(pid: number): boolean;
+export declare function readProcessStartTime(pid: number): string | undefined;

package/dist/utils/process-identity.js

@@ -0,0 +1,35 @@
+import { execFileSync } from 'node:child_process';
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+export function readProcessStartTime(pid) {
+    try {
+        const startedAt = process.platform === 'win32'
+            ? execFileSync('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                `$p = Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}"; if ($p) { $p.CreationDate.ToUniversalTime().ToString("O") }`,
+            ], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+            : // `lstart` is rendered through localtime and the active locale, so the
+                // same live process yields a different string under a different TZ or
+                // LC_TIME. That string is a lock owner's identity, and a mismatch is
+                // read as PID reuse — an unpinned render lets one daemon reclaim a
+                // mutex another still holds. Pin both so the identity is absolute.
+                execFileSync('ps', ['-p', String(pid), '-o', 'lstart='], {
+                    encoding: 'utf-8',
+                    stdio: ['ignore', 'pipe', 'ignore'],
+                    env: { ...process.env, TZ: 'UTC', LC_ALL: 'C' },
+                }).trim();
+        return startedAt || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}