gitnexus 1.6.8-rc.9 → 1.6.8

package/dist/server/upload-ingest.js

@@ -0,0 +1,276 @@
+/**
+ * Secure ingestion of a browser folder upload (multipart/form-data).
+ *
+ * Replaces the path-injection-prone GET /api/fs/list directory listing. The
+ * client streams the selected files plus a JSON `manifest` of their
+ * webkitRelativePaths; we write each into an mkdtemp staging dir under
+ * UPLOAD_ROOT with PROVABLE containment (resolve-then-contain), hard resource
+ * caps, and guaranteed cleanup on every failure/abort path. No client value
+ * ever reaches a filesystem READ — the server only writes into a sandbox it
+ * created, then hands that sandbox to the analysis pipeline.
+ *
+ * Security references: CodeQL js/path-injection (resolve + startsWith(root+sep)),
+ * OWASP File Upload / Path Traversal.
+ */
+import path from 'path';
+import fs from 'fs';
+import fsp from 'fs/promises';
+import busboy from 'busboy';
+import { UPLOAD_ROOT, STAGING_PREFIX } from './upload-paths.js';
+import { BadRequestError } from './validation.js';
+export const DEFAULT_INGEST_LIMITS = {
+    maxTotalBytes: 250 * 1024 * 1024,
+    maxFileBytes: 25 * 1024 * 1024,
+    maxFiles: 20000,
+    maxParts: 20100,
+    maxDirs: 50000,
+    maxFieldBytes: 2 * 1024 * 1024,
+};
+const MAX_PATH_DEPTH = 64;
+const MAX_PATH_LENGTH = 4096;
+/**
+ * Resolve a client-provided relative path to an absolute destination PROVABLY
+ * contained within `stageRoot`. Throws BadRequestError on any unsafe input.
+ * This is the load-bearing path-traversal-on-write control; keep it pure and
+ * unit-tested.
+ */
+export function resolveContainedDest(stageRoot, rel) {
+    if (typeof rel !== 'string' || rel.length === 0) {
+        throw new BadRequestError('Invalid upload path');
+    }
+    if (rel.length > MAX_PATH_LENGTH) {
+        throw new BadRequestError('Upload path too long');
+    }
+    // webkitRelativePath is always relative; a leading slash is absolute/hostile.
+    if (rel.startsWith('/')) {
+        throw new BadRequestError('Invalid upload path');
+    }
+    // Browsers emit forward slashes only; a NUL byte or backslash is hostile.
+    if (rel.includes('\u0000') || rel.includes('\\')) {
+        throw new BadRequestError('Invalid upload path');
+    }
+    const rawSegments = rel.split('/').filter((s) => s.length > 0);
+    if (rawSegments.length === 0 || rawSegments.length > MAX_PATH_DEPTH) {
+        throw new BadRequestError('Invalid upload path');
+    }
+    const segments = [];
+    for (const seg of rawSegments) {
+        // Normalize so NFC/NFD variants don't collide silently on case/unicode
+        // -folding filesystems (macOS/Windows).
+        const s = seg.normalize('NFC');
+        if (s === '.' || s === '..') {
+            throw new BadRequestError('Upload path must not contain traversal segments');
+        }
+        segments.push(s);
+    }
+    const dest = path.resolve(stageRoot, segments.join(path.sep));
+    // Suffix path.sep so a sibling prefix (/sandbox-evil vs /sandbox) can't pass.
+    if (dest !== stageRoot && !dest.startsWith(stageRoot + path.sep)) {
+        throw new BadRequestError('Upload path escapes the sandbox');
+    }
+    return dest;
+}
+/**
+ * Create the parent directories of `destFile` one segment at a time, asserting
+ * after each `mkdir` that the segment is a real directory (not a symlink
+ * swapped in mid-stream) still inside `stageRoot`. Counts created dirs against
+ * the inode-exhaustion cap.
+ */
+function mkdirContained(stageRoot, destFile, state) {
+    const parent = path.dirname(destFile);
+    const relParent = path.relative(stageRoot, parent);
+    if (relParent === '' || relParent === '.')
+        return;
+    const segs = relParent.split(path.sep).filter(Boolean);
+    let cur = stageRoot;
+    for (const seg of segs) {
+        cur = path.join(cur, seg);
+        let made = false;
+        try {
+            fs.mkdirSync(cur);
+            made = true;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+        const st = fs.lstatSync(cur);
+        if (st.isSymbolicLink() || !st.isDirectory()) {
+            throw new BadRequestError('Upload path escapes the sandbox');
+        }
+        if (made) {
+            state.dirCount++;
+            if (state.dirCount > state.limits.maxDirs) {
+                throw new BadRequestError('Too many directories in upload', 413);
+            }
+        }
+    }
+}
+/**
+ * Parse and securely write a multipart folder upload into a fresh staging
+ * directory under UPLOAD_ROOT. Resolves with the populated staging dir, or
+ * rejects with a BadRequestError (status 400/413) after removing the staging
+ * dir. The caller owns promotion + cleanup of the returned `stageRoot`.
+ */
+export async function ingestUpload(req, limitsOverride, opts = {}) {
+    const limits = { ...DEFAULT_INGEST_LIMITS, ...limitsOverride };
+    const uploadRoot = opts.root ?? UPLOAD_ROOT;
+    await fsp.mkdir(uploadRoot, { recursive: true });
+    // mkdtemp creates the dir mode 0o700 (owner-only); realpath canonicalizes
+    // the root so the containment prefix check is exact.
+    const stageRoot = await fsp.realpath(await fsp.mkdtemp(path.join(uploadRoot, STAGING_PREFIX)));
+    let cleaned = false;
+    const cleanup = async () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        await fsp.rm(stageRoot, { recursive: true, force: true }).catch(() => { });
+    };
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let manifest = null;
+        let fileIndex = 0;
+        let fileCount = 0;
+        let totalBytes = 0;
+        let topLevelName = '';
+        const dirState = { dirCount: 0, limits };
+        const writePromises = [];
+        const bb = busboy({
+            headers: req.headers,
+            limits: {
+                fileSize: limits.maxFileBytes,
+                files: limits.maxFiles,
+                parts: limits.maxParts,
+                fields: 10,
+                fieldNameSize: 200,
+                fieldSize: limits.maxFieldBytes,
+                headerPairs: 2000,
+            },
+        });
+        const fail = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                req.unpipe(bb);
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                req.resume(); // drain remaining body so the socket isn't left hanging
+            }
+            catch {
+                /* ignore */
+            }
+            void cleanup().finally(() => reject(err));
+        };
+        bb.on('field', (name, val) => {
+            if (name !== 'manifest')
+                return;
+            try {
+                const parsed = JSON.parse(val);
+                if (!Array.isArray(parsed) || !parsed.every((p) => typeof p === 'string')) {
+                    return fail(new BadRequestError('Invalid manifest'));
+                }
+                manifest = parsed;
+            }
+            catch {
+                fail(new BadRequestError('Invalid manifest'));
+            }
+        });
+        bb.on('file', (_name, stream, _info) => {
+            if (settled) {
+                stream.resume();
+                return;
+            }
+            if (manifest === null) {
+                // The manifest field MUST arrive before any file part.
+                stream.resume();
+                return fail(new BadRequestError('Manifest must precede file parts'));
+            }
+            const idx = fileIndex++;
+            const rel = manifest[idx];
+            let dest;
+            try {
+                dest = resolveContainedDest(stageRoot, rel);
+                // A folder upload is exactly one top-level directory: every entry must
+                // have ≥2 segments and share the same first segment. This rejects a
+                // bare file at the root (which would make the promote target a file)
+                // and a multi-top manifest (which would silently drop all but the
+                // first folder). Validated here, before any job is created.
+                const segs = String(rel)
+                    .split('/')
+                    .filter((s) => s.length > 0);
+                const firstSeg = (segs[0] ?? '').normalize('NFC');
+                if (!topLevelName) {
+                    topLevelName = firstSeg;
+                }
+                if (segs.length < 2 || firstSeg !== topLevelName) {
+                    throw new BadRequestError('Upload must be a single folder of files');
+                }
+                mkdirContained(stageRoot, dest, dirState);
+            }
+            catch (err) {
+                stream.resume();
+                return fail(err);
+            }
+            fileCount++;
+            const ws = fs.createWriteStream(dest, { flags: 'wx' });
+            const p = new Promise((res, rej) => {
+                stream.on('data', (chunk) => {
+                    totalBytes += chunk.length;
+                    if (totalBytes > limits.maxTotalBytes) {
+                        stream.unpipe(ws);
+                        ws.destroy();
+                        rej(new BadRequestError('Upload exceeds total size limit', 413));
+                    }
+                });
+                stream.on('limit', () => {
+                    ws.destroy();
+                    rej(new BadRequestError('File exceeds size limit', 413));
+                });
+                stream.on('error', rej);
+                ws.on('error', rej);
+                ws.on('finish', () => res());
+                stream.pipe(ws);
+            });
+            writePromises.push(p);
+            p.catch(fail);
+        });
+        bb.on('filesLimit', () => fail(new BadRequestError('Too many files in upload', 413)));
+        bb.on('partsLimit', () => fail(new BadRequestError('Too many parts in upload', 413)));
+        bb.on('fieldsLimit', () => fail(new BadRequestError('Too many fields in upload')));
+        bb.on('error', (err) => fail(err instanceof Error ? err : new BadRequestError('Upload parse error')));
+        bb.on('close', () => {
+            if (settled)
+                return;
+            Promise.all(writePromises)
+                .then(() => {
+                if (settled)
+                    return;
+                if (manifest === null)
+                    return fail(new BadRequestError('Missing manifest'));
+                if (fileCount === 0)
+                    return fail(new BadRequestError('Empty upload'));
+                if (fileCount !== manifest.length) {
+                    return fail(new BadRequestError('Manifest/file count mismatch'));
+                }
+                if (!topLevelName) {
+                    return fail(new BadRequestError('Could not determine upload folder name'));
+                }
+                settled = true;
+                resolve({ stageRoot, fileCount, totalBytes, topLevelName });
+            })
+                .catch(() => {
+                /* a write rejected → fail() already invoked via p.catch */
+            });
+        });
+        req.on('aborted', () => {
+            if (!settled)
+                fail(new BadRequestError('Upload aborted'));
+        });
+        req.on('error', (err) => fail(err instanceof Error ? err : new BadRequestError('Request error')));
+        req.pipe(bb);
+    });
+}

package/dist/server/upload-paths.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Upload working-directory paths.
+ *
+ * Browser folder uploads are written into getGlobalDir()/uploads/{name}/ — a
+ * sibling of the clone root (git-clone.ts CLONE_ROOT) — so an uploaded repo
+ * persists and behaves like a cloned one (the graph UI's /api/file reads its
+ * files after analysis, and DELETE /api/repo removes it). Staging happens in
+ * an mkdtemp dir *under* UPLOAD_ROOT so the promote rename stays on one
+ * filesystem and remains atomic (a rename from os.tmpdir() could trip EXDEV —
+ * the exact Docker case this feature targets; see bridge-db.ts for the same
+ * anchored-staging pattern).
+ */
+/**
+ * Root directory for all uploaded repositories. Targets must resolve inside this.
+ *
+ * Sourced from getGlobalDir() so it honors GITNEXUS_HOME and stays a sibling of
+ * the clone root on the same (in Docker, persistent) volume. Falls back to
+ * ~/.gitnexus when the env var is unset.
+ */
+export declare const UPLOAD_ROOT: string;
+/** Prefix for per-upload staging directories created under UPLOAD_ROOT. */
+export declare const STAGING_PREFIX = ".staging-";
+/**
+ * Get the upload target directory for a repo name.
+ *
+ * Re-validates at the boundary (callers may derive the name from an untrusted
+ * manifest). Rejects `.`, `..`, the `'unknown'` sentinel that sanitizeRepoName
+ * emits for un-nameable inputs, names beginning with `.` (which would collide
+ * with the `.staging-` prefix), and anything outside the safe charset.
+ */
+export declare function getUploadDir(repoName: string): string;
+/**
+ * Derive a filesystem-safe upload directory name from the manifest's
+ * top-level folder. Returns null when the name is un-nameable (so the caller
+ * rejects with 400 rather than colliding everyone on `UPLOAD_ROOT/unknown`).
+ */
+export declare function deriveUploadName(topLevelName: string): string | null;

package/dist/server/upload-paths.js

@@ -0,0 +1,57 @@
+/**
+ * Upload working-directory paths.
+ *
+ * Browser folder uploads are written into getGlobalDir()/uploads/{name}/ — a
+ * sibling of the clone root (git-clone.ts CLONE_ROOT) — so an uploaded repo
+ * persists and behaves like a cloned one (the graph UI's /api/file reads its
+ * files after analysis, and DELETE /api/repo removes it). Staging happens in
+ * an mkdtemp dir *under* UPLOAD_ROOT so the promote rename stays on one
+ * filesystem and remains atomic (a rename from os.tmpdir() could trip EXDEV —
+ * the exact Docker case this feature targets; see bridge-db.ts for the same
+ * anchored-staging pattern).
+ */
+import path from 'path';
+import { sanitizeRepoName } from '../storage/git.js';
+import { REPO_NAME_PATTERN } from './git-clone.js';
+import { getGlobalDir } from '../storage/repo-manager.js';
+/**
+ * Root directory for all uploaded repositories. Targets must resolve inside this.
+ *
+ * Sourced from getGlobalDir() so it honors GITNEXUS_HOME and stays a sibling of
+ * the clone root on the same (in Docker, persistent) volume. Falls back to
+ * ~/.gitnexus when the env var is unset.
+ */
+export const UPLOAD_ROOT = path.resolve(path.join(getGlobalDir(), 'uploads'));
+/** Prefix for per-upload staging directories created under UPLOAD_ROOT. */
+export const STAGING_PREFIX = '.staging-';
+/**
+ * Get the upload target directory for a repo name.
+ *
+ * Re-validates at the boundary (callers may derive the name from an untrusted
+ * manifest). Rejects `.`, `..`, the `'unknown'` sentinel that sanitizeRepoName
+ * emits for un-nameable inputs, names beginning with `.` (which would collide
+ * with the `.staging-` prefix), and anything outside the safe charset.
+ */
+export function getUploadDir(repoName) {
+    if (!repoName ||
+        repoName === '.' ||
+        repoName === '..' ||
+        repoName === 'unknown' ||
+        repoName.startsWith('.') ||
+        !REPO_NAME_PATTERN.test(repoName)) {
+        throw new Error('Invalid repository name');
+    }
+    return path.join(UPLOAD_ROOT, repoName);
+}
+/**
+ * Derive a filesystem-safe upload directory name from the manifest's
+ * top-level folder. Returns null when the name is un-nameable (so the caller
+ * rejects with 400 rather than colliding everyone on `UPLOAD_ROOT/unknown`).
+ */
+export function deriveUploadName(topLevelName) {
+    const safe = sanitizeRepoName(topLevelName);
+    if (safe === 'unknown' || safe === '.' || safe === '..' || safe.startsWith('.')) {
+        return null;
+    }
+    return safe;
+}

package/dist/server/upload-sweep.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Backstop cleanup for abandoned upload staging directories.
+ *
+ * A crashed/killed process can leave a `.staging-*` directory under
+ * UPLOAD_ROOT (the normal path removes it on success/failure/abort). This
+ * sweep, run once at server startup, removes staging dirs older than a
+ * threshold. Promoted upload dirs are persistent registered repos (like
+ * clones) and are NOT touched here — they are removed via DELETE /api/repo.
+ */
+export interface SweepOptions {
+    /** Remove staging dirs older than this (default 6h). */
+    maxAgeMs?: number;
+    /** Override the root to sweep (defaults to UPLOAD_ROOT; for tests). */
+    root?: string;
+    /** Clock injection for tests. */
+    now?: number;
+}
+export declare function sweepStaleUploads(opts?: SweepOptions): Promise<{
+    removed: string[];
+}>;

package/dist/server/upload-sweep.js

@@ -0,0 +1,57 @@
+/**
+ * Backstop cleanup for abandoned upload staging directories.
+ *
+ * A crashed/killed process can leave a `.staging-*` directory under
+ * UPLOAD_ROOT (the normal path removes it on success/failure/abort). This
+ * sweep, run once at server startup, removes staging dirs older than a
+ * threshold. Promoted upload dirs are persistent registered repos (like
+ * clones) and are NOT touched here — they are removed via DELETE /api/repo.
+ */
+import path from 'path';
+import fsp from 'fs/promises';
+import { UPLOAD_ROOT, STAGING_PREFIX } from './upload-paths.js';
+export async function sweepStaleUploads(opts = {}) {
+    const maxAgeMs = opts.maxAgeMs ?? 6 * 60 * 60 * 1000;
+    const root = opts.root ?? UPLOAD_ROOT;
+    const now = opts.now ?? Date.now();
+    const removed = [];
+    let entries;
+    try {
+        entries = await fsp.readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return { removed }; // root does not exist yet — nothing to sweep
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const full = path.join(root, entry.name);
+        try {
+            const st = await fsp.stat(full);
+            if (now - st.mtimeMs <= maxAgeMs)
+                continue; // recent — keep
+            if (entry.name.startsWith(STAGING_PREFIX)) {
+                // Transient staging dir orphaned by a crash — always removable.
+                await fsp.rm(full, { recursive: true, force: true }).catch(() => { });
+                removed.push(full);
+            }
+            else {
+                // Promoted upload dir. A successfully-analyzed (registered) repo always
+                // has a `.gitnexus` index inside it; a stale promoted dir WITHOUT one is
+                // an orphan from an analysis that failed before registering — remove it.
+                const hasIndex = await fsp
+                    .access(path.join(full, '.gitnexus'))
+                    .then(() => true)
+                    .catch(() => false);
+                if (!hasIndex) {
+                    await fsp.rm(full, { recursive: true, force: true }).catch(() => { });
+                    removed.push(full);
+                }
+            }
+        }
+        catch {
+            /* stat race — skip */
+        }
+    }
+    return { removed };
+}

package/dist/storage/git.js

@@ -2,6 +2,7 @@ import { execSync } from 'child_process';
 import { statSync } from 'fs';
 import path from 'path';
 // Git utilities for repository detection, commit tracking, and diff analysis
+const chompGitOutput = (value) => value.toString().replace(/\r?\n$/, '');
 export const isGitRepo = (repoPath) => {
     try {
         execSync('git rev-parse --is-inside-work-tree', {
@@ -99,14 +100,12 @@ export const getRemoteUrl = (repoPath) => {
  */
 export const getGitRoot = (fromPath) => {
     try {
-        const raw = execSync('git rev-parse --show-toplevel', {
+        const raw = chompGitOutput(execSync('git rev-parse --show-toplevel', {
             cwd: fromPath,
             // Suppress stderr -- see getCurrentCommit comment and #1172.
             stdio: ['ignore', 'pipe', 'ignore'],
             windowsHide: true,
-        })
-            .toString()
-            .trim();
+        }));
         // On Windows, git returns /d/Projects/Foo — path.resolve normalizes to D:\Projects\Foo
         return path.resolve(raw);
     }
@@ -143,13 +142,11 @@ export const getGitRoot = (fromPath) => {
  */
 export const getCanonicalRepoRoot = (fromPath) => {
     try {
-        const commonDir = execSync('git rev-parse --path-format=absolute --git-common-dir', {
+        const commonDir = chompGitOutput(execSync('git rev-parse --path-format=absolute --git-common-dir', {
             cwd: fromPath,
             stdio: ['ignore', 'pipe', 'ignore'],
             windowsHide: true,
-        })
-            .toString()
-            .trim();
+        }));
         if (!commonDir)
             return null;
         // Common dir is `<repo>/.git` for both the main checkout and all

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

@@ -53,10 +53,31 @@ export declare const fileContentHash: (content: Buffer | string) => string;
  * in the chunk. We sort by filePath before hashing so chunks composed of
  * the same files in different order produce the same key.
  */
+/** PDG/CFG cache namespace (#2081 M1) — every input that changes the
+ *  WORKER-EMITTED `cfgSideChannel` must be folded into the chunk key, and
+ *  ONLY those. The classification test for a future option: does the worker
+ *  see it (workerData) and does it change the bytes the worker writes to the
+ *  shard? `pdgMaxEdgesPerFunction` famously fails that test — it is applied
+ *  at EMIT time on the main thread (scope-resolution run.ts), the worker
+ *  never receives it, and the cached output is byte-identical across cap
+ *  values; folding it in (as a prior review round did) only forced a
+ *  spurious full re-parse on every cap change (#2099 F3). Options that
+ *  change the PERSISTED GRAPH but not the shard belong in the RepoMeta pdg
+ *  stamp (incremental-eligibility), not here. */
+export interface PdgCacheKey {
+    readonly pdg?: boolean;
+    /** Per-function source-line cap (changes WHICH functions get a CFG —
+     *  applied in the worker, so it shapes the cached shard). Callers must
+     *  pass the RESOLVED value (the production call site in parse-impl.ts
+     *  applies the worker's default before folding) so an explicit-default
+     *  run shares the default run's keys — this function folds whatever it
+     *  is given verbatim. */
+    readonly maxFunctionLines?: number;
+}
 export declare const computeChunkHash: (entries: Array<{
     filePath: string;
     contentHash: string;
-}>) => string;
+}>, pdg?: boolean | PdgCacheKey) => string;
 export declare const mapReplacer: (_key: string, value: unknown) => unknown;
 export declare const mapReviver: (_key: string, value: unknown) => unknown;
 /**

package/dist/storage/parse-cache.js

@@ -52,7 +52,7 @@ import { fileURLToPath } from 'url';
 // the main thread (the #1983 OOM). Because the two stores share this version,
 // any future change to the `ParsedFile` serialization shape MUST bump
 // SCHEMA_BUMP so both invalidate in lockstep.
-const SCHEMA_BUMP = 4;
+const SCHEMA_BUMP = 6; // #2082 M2: cfgSideChannel gained bindings + per-block statement facts
 const GITNEXUS_PKG_VERSION = (() => {
     try {
         // package.json sits at gitnexus/package.json — two levels up from
@@ -92,17 +92,48 @@ const sha256Hex = (input) => createHash('sha256')
     .digest('hex');
 /** Stable hash of a single file's contents — used by callers to compose a chunk hash. */
 export const fileContentHash = (content) => sha256Hex(content);
-/**
- * Compute the canonical cache key for a chunk's contents.
- *
- * `entries` is the list of (filePath, file content hash) for every file
- * in the chunk. We sort by filePath before hashing so chunks composed of
- * the same files in different order produce the same key.
- */
-export const computeChunkHash = (entries) => {
+export const computeChunkHash = (entries, pdg = false) => {
     const sorted = [...entries].sort((a, b) => (a.filePath < b.filePath ? -1 : 1));
     const joined = sorted.map((e) => `${e.filePath}:${e.contentHash}`).join('\n');
-    return sha256Hex(joined);
+    const opts = typeof pdg === 'boolean' ? { pdg } : pdg;
+    // pdg-off path keeps its pre-#2081 chunk-KEY format verbatim. Note this does
+    // NOT mean caches survive the M1 upgrade: SCHEMA_BUMP 4→5 changed
+    // PARSE_CACHE_VERSION, and both loadParseCache (below) and the durable
+    // parsedfile-store index hard-invalidate on it — every user pays one full
+    // cold re-parse on upgrade regardless of --pdg. Keeping the key format
+    // stable only means no SECOND invalidation class is introduced here.
+    if (!opts.pdg)
+        return sha256Hex(joined);
+    // Fold the worker-visible --pdg configuration into the key: the boolean
+    // plus `maxFunctionLines` (decides which functions get a CFG at all, in the
+    // worker). Without it a warm chunk built under one cap is served to a run
+    // with a different cap → a stale/under-built CFG: the #2038-class
+    // option-blind-key trap. `def` marks an unset (default) value so two
+    // default-cap runs share a key. The emit-time edge cap is deliberately
+    // absent — see the PdgCacheKey doc comment.
+    //
+    // NAMESPACE VERSION (`pdg:5`): bumped when the worker-emitted
+    // `cfgSideChannel` SHAPE changes for pdg-mode runs only — pdg:1→2 in #2083
+    // M3 U1 (TsHarvester emits taint `sites` on StatementFacts); pdg:2→3 in the
+    // #2227 follow-up U1 (every C-family / TS harvester now stamps the call-site
+    // anchor `SiteRecord.at`, which the resolved-callee-id join reads); pdg:3→4 in
+    // the #2227 tri-review-2 U4 (the Rust harvester now emits a `kind:'new'` site
+    // for `struct_expression`, a new worker-output site the join consumes); pdg:4→5
+    // in the FU-C call-summary soundness fix (the TS harvester now stamps
+    // `BindingEntry.formalIndex` on param bindings so the PDG call-summary keys
+    // return-flow on the enclosing FORMAL position, not the flattened binding
+    // ordinal — a warm chunk lacking it would route the harvest to its conservative
+    // empty-summary fallback). A warm chunk built by a worker predating the relevant
+    // change carries a stale site shape, so the join skips it and
+    // `BasicBlock.calleeIds` is silently empty (or missing the struct constructor)
+    // even though `callees` is populated — exactly the #2225-class shape skew this
+    // version token exists to prevent. Invalidates pdg-mode chunks and their durable
+    // parsedfile-cache entries; flag-off chunk keys never reach this line and stay
+    // byte-identical, so non-pdg users pay nothing. Deliberately NOT a SCHEMA_BUMP —
+    // that gates the whole cache version and would force a full cold re-parse on
+    // EVERY user (the M1 bump comment above records that cost).
+    const ns = `pdg:5;maxFn=${opts.maxFunctionLines ?? 'def'}`;
+    return sha256Hex(`${ns}\n${joined}`);
 };
 /**
  * JSON replacer that round-trips Map/Set instances through plain JSON.