cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/storage/parse-cache.js

@@ -0,0 +1,650 @@
+"use strict";
+/**
+ * Chunk-level content-addressed parse cache.
+ *
+ * The pipeline always parses every file (correctness invariant: cross-file
+ * resolution and downstream phases need full graph data). What this cache
+ * 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.
+ *
+ * Why not per-file:
+ * - Workers process sub-batches and emit aggregated `ParseWorkerResult`s.
+ *   Splitting back to per-file would require reworking the worker contract.
+ * - 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pruneCache = exports.saveParseCache = exports.loadParseCache = exports.persistParseCacheChunk = exports.loadParseCacheChunk = exports.slimParseWorkerResultsForCache = exports.mapReviver = exports.mapReplacer = exports.computeChunkHash = exports.fileContentHash = exports.PARSE_CACHE_VERSION = void 0;
+const crypto_1 = require("crypto");
+const module_1 = require("module");
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Cache version composed of:
+ *   - A schema bump knob (`SCHEMA_BUMP`) for hand-controlled invalidation
+ *     when ParseWorkerResult shape or upstream parse semantics change.
+ *   - The current `gitnexus` npm package version, read at module load.
+ *     Any release that ships an updated tree-sitter grammar or revised
+ *     extractor logic implies a version bump in package.json, which
+ *     automatically invalidates the on-disk cache. Without this, a user
+ *     running `npm i -g cgraph@latest` after a parser-affecting
+ *     release would silently replay pre-upgrade ParseWorkerResults
+ *     against the new graph schema (Bugbot/Claude review on #1479).
+ *
+ * On version mismatch, `loadParseCache` returns an empty cache and the
+ * next save overwrites the on-disk file with the new version baked in.
+ */
+// Bumped to 4 in #1983: on-disk parse-cache shards omit legacy DAG fields
+// (`calls`, `assignments`, `constructorBindings`) unused after RING4-1 (#942)
+// and the worker `parsedFiles` (the worker writes those to the disk ParsedFile
+// store instead). #2038 added a DURABLE, content-addressed ParsedFile store
+// (`parsedfile-cache/`, see parsedfile-store.ts) keyed by chunk hash that
+// mirrors THIS cache's lifecycle — version-gated by PARSE_CACHE_VERSION, pruned
+// in lockstep to the surviving keys. On a warm parse-cache hit the chunk's
+// ParsedFiles are restored from it, so scope-resolution does NOT re-extract on
+// 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.
+// v35: Java/Kotlin Spring @Bean factory and @Resource side-channel facts
+// (#2413). ParsedFile results are content-addressed and replayed verbatim, so
+// the feature/schema inventory alone cannot invalidate pre-#2413 captures.
+// (Cut as v32 on this branch; `main` took 32 for #2742 and 33/34 for #2747
+// first, so this series is renumbered at merge time — see the v21 note.)
+// v34: the receiver-chain capture is emitted by ALL 14 language emitters, not
+// just TypeScript. v33 landed with the TypeScript-only emission; the rollout to
+// the other 13 languages changed the capture set AGAIN, so a cache stamped 33 by
+// an intermediate build of that series is not equivalent to one stamped at this
+// commit — it would be treated as current while every non-TypeScript file
+// replayed pre-rollout captures, leaving the feature silently inert for 13 of 14
+// languages. Bumped there so the version tracks the FINAL capture set rather
+// than the first divergence.
+// v33: TypeScript call matches carry `@reference.receiver-chain`, a compact
+// encoding of a receiver that is itself an expression.
+// v32: Rust items are qualified by their enclosing `mod` chain (#2742). The
+// qualified name is computed in the parse worker, so a warm cache replays the
+// old unqualified ids verbatim and the collapse persists.
+// v31: Rust `mod_item` gained `@declaration.namespace` and scoped call sites
+// gained `@reference.qualified-name` (#2730). Both are PARSE-TIME captures, so a
+// warm cache replays the old capture set verbatim: `rawQualifiedName` comes back
+// undefined and no Namespace def exists to hang a module prefix on, which turns
+// the whole module-qualified resolution tier into a no-op on unchanged files.
+// Re-checked against origin/main at commit time per the v29 note below.
+// v29: closure-binding declaration rules for PHP/Rust/Kotlin/Ruby/Dart, a Rust
+// graph node for `let f = || …`, a Dart closure scope, and function-local VALUES
+// (Variable/Const/Property/Static) qualified by their enclosing callable plus
+// position (#2699 parts A1 + B). All parse-time, so a warm cache would replay
+// the old captures and the pre-qualification ids verbatim.
+//
+// This is 29 and not 28 because of the exact collision the v21 note below warns
+// about: this branch cut at 27 and bumped to 28, while #2415 bumped 27 -> 28 and
+// merged FIRST. Re-checking against origin/main at merge time — not at branch
+// time — is what caught it; leaving it at 28 would have shipped this change with
+// NO parse-cache invalidation, so every warm cache keeps serving the pre-fix
+// captures and ids.
+// v28: Java/Kotlin capture side-channels persist Spring condition facts and
+// annotation-source line numbers (#2415).
+// v26: the enclosing-callable walk stops at class bodies and anonymous-class
+// construction sites (#2699 follow-up); a v25 cache replays worker results carrying the
+// wrong Java anonymous-class ids. Cached results are replayed verbatim — including
+// across `--force` — so without this bump a warm cache keeps serving them.
+// v25: function-local callables are qualified by their enclosing-callable chain
+// plus their own position, and JS/TS gain block scopes (#2699). Both the node
+// ids AND the scope tree in a cached worker result are therefore stale. Cached
+// results are replayed verbatim — including across `--force` — so without this
+// bump a warm cache keeps serving the colliding ids and the block-less scopes.
+// v24: function scopes carry `Scope.ownsReceivers`, marking the JS/TS forms
+// that bind their own `this` (#2701). The flag lives on the cached `Scope`, so
+// without this bump a warm cache replays scopes that lack it and every `this`
+// inside an ordinary `function` keeps resolving to the enclosing class —
+// verified by probe: `--force` alone does NOT re-derive it.
+// v23: closure bindings emit callable nodes in Dart, Ruby, Java, C# and PHP
+// (plus JS/TS `var`), and Dart/PHP gain the scope declarations and flow
+// captures their forms were missing (#2693). Cached worker results are replayed
+// verbatim, so without this bump a warm cache keeps serving the old labels.
+// v22: `const X = <arrow | function-expression>` emits one `Function` node
+// instead of a `Function` plus an edgeless `Const` twin (#2687). Cached worker
+// results are replayed verbatim — including across `--force` — so without this
+// bump a warm cache keeps serving the old two-node set.
+// v21: TWO changes share this number — a collision, not a typo. #2632
+// (Java/Kotlin Spring DI facts: constructor, field/property and method
+// injection sites plus bean-name and @Primary provider metadata) bumped 20 -> 21
+// and merged first; #2653 (Java local class/enum/record/interface captures using
+// javac-compatible, source-type-relative JLS 13.1 identities and
+// declaration-to-block scopes, #2562) had branched at 20, bumped to 21 as well,
+// and merged second — so it shipped with NO invalidation of its own. An index
+// already stamped 21 by the first change was treated as current by the second
+// and kept serving stale local-class identities from the warm cache. Harmless
+// now (anything below the current value is rejected), and left as-is because
+// both genuinely shipped as 21 — renumbering would misstate history. Read this
+// as the reason to re-check SCHEMA_BUMP against origin/main immediately before
+// merging, not just when the branch is cut; the same collision hit
+// the DB schema version in #2653/#2654 (that constant is gone — the DB side is
+// a derived fingerprint now, see SCHEMA_FINGERPRINT; SCHEMA_BUMP below is still
+// hand-maintained because no declarative artifact describes a capture set).
+// v27: generator EXPRESSIONS bound to a name emit a callable definition capture,
+// and nested-callable caller attribution appends the localIdentity suffix the
+// definition phase already used. Both are parse-time, so a warm cache would
+// otherwise replay the old captures and ids verbatim.
+// v30/schema v22: CommonJS export capture emission (#2723) — new @definition/@declaration
+// captures for exports.X, aliased receivers, module-level `this`, re-export
+// forwarding and `module.exports = fn`, plus prototype/`this` Methods. A warm
+// cache would otherwise replay the pre-fix captures verbatim.
+// v20: Java/Kotlin capture side-channels persist package and class-annotation
+// facts for shared Spring Bean resolution.
+// v19: Java enum constant bodies emit E$N Class nodes; anonymous naming uses
+// JLS 13.1 immediate-host chains (#2555).
+// v18: Worker$N anonymous bodies. v17: callable-value-flow operand identity.
+// v16: direct callee identity.
+// v36: bound-callable graph `startLine` follows the initializer so multi-line
+// closure bindings join the scope channel (#2735). Warm cache would otherwise
+// keep serving wrapper-line startLines and drop the CALLS edge.
+// v37: Java/Kotlin capture side-channels include Spring AOP owner/advice facts
+// (#2416). Warm cache entries at v36 do not carry those facts and would silently
+// omit ADVISED_BY evidence.
+// v38: Swift nested conditional-compilation directives are blanked before the
+// parse (#2771), so a class body that previously error-recovered away now
+// survives. The chunk key hashes raw on-disk bytes and `preprocessSource` runs
+// after it is computed, so unchanged Swift files would otherwise replay their
+// pre-fix `ParseWorkerResult` verbatim — including across `--force`. Allocated
+// on `main`, NOT by this branch — kept so the number is not reused a third time.
+// v39: receiver-chain wire format v2 — the encoded chain gained name-free
+// `await` and `index` step kinds, so the VERSION prefix moved 1 -> 2 and every
+// persisted chain string changed. A v2 decoder REFUSES a v1 payload (that is
+// the point: a chain missing its await or index hop decodes cleanly as a
+// different, shorter chain and would type the receiver against the wrong
+// member), so a stale cache replays chains this build silently discards —
+// the feature degrades to the text cascade with no error anywhere. Bumped so
+// the stale cache is rejected rather than half-read.
+//
+// NUMBERED 39, AFTER TWO REALLOCATIONS. This branch first used 37; `main` took
+// 37 for Spring AOP (#2416) mid-flight, so it moved to 38; `main` then took 38
+// for the Swift directive fix (#2771), landing on the branch's number AGAIN.
+// That is the EIGHTH collision in this series and the SECOND exact clash — two
+// incompatible schemas claiming one number, twice running. The lesson is not
+// "pick a bigger number": it is that the check must happen immediately before
+// merge, because the window between review and merge is exactly when `main`
+// allocates. Re-check against origin/main before merging this.
+// v40: inference-typed class fields emit type-binding captures in SIX languages
+// (#2807) — TypeScript/JavaScript `public_field_definition|field_definition` with a
+// `new_expression` value and `this.<field> = new X()`; Python `self.x = Outer()`;
+// Ruby `@ivar = Foo.new`; Swift optional property annotations; Dart inferred-type
+// and final field declarations plus constructor-body field writes. Every one of
+// these is PARSE-TIME capture emission, so a warm cache replays the pre-fix
+// capture set verbatim for byte-unchanged files and the new receiver edges never
+// appear — silently, with no error, exactly the v27/v30 failure mode. `analyze`
+// skips tree-sitter dispatch for unchanged chunks (GUARDRAILS.md), so a plain
+// re-analyze does NOT surface them without this bump.
+// RE-CHECK AGAINST origin/main IMMEDIATELY BEFORE MERGING — main was also at 39
+// when this was allocated, and this file records eight prior collisions.
+// v41: the v40 Dart field-write binding gained its READ-side mask (#2807 review)
+// — a Dart class-member body that rebinds one of its class's field names now
+// emits `@receiver-owner.shadowed-fields` on its synthesized `@scope.function`
+// match, which becomes `Scope.ownsReceivers`. Parse-time capture emission again,
+// so a v40 warm cache replays scope matches with no marker and the receiver walk
+// still reaches the class field — i.e. it keeps serving the WRONG edge this
+// bump's fix removes, silently. Same bump-or-nothing situation as v40.
+// RE-CHECK AGAINST origin/main IMMEDIATELY BEFORE MERGING.
+// v42: the v40/v41 Python constructor-field arm stopped accepting a DOTTED
+// callee (#2807 review). `self.svc = f.Alpha()` no longer emits a
+// `@type-binding.constructor` capture at all, which is what removes the
+// fabricated edge to the same-named class `Alpha` and what stops
+// `self.conn = Registry.get()` displacing an earlier real `self.conn = Outer()`.
+// A within-PR re-bump, not a collision fix: v41 was allocated by this same
+// unmerged branch, so v41-stamped caches exist only on it — but they exist on
+// every reviewer's and CI runner's checkout of it, and parse-time emission means
+// they replay the pre-fix capture set for byte-unchanged files and keep serving
+// the fabricated edge. main is at 39, so 40/41/42 are all this branch's.
+// RE-CHECK AGAINST origin/main IMMEDIATELY BEFORE MERGING.
+// v43: Go embedded fields now emit `@reference.embedded-pointer` when written
+// as `*T` rather than `T` (#2813 exact method sets). Go's method-set rules make
+// the two forms genuinely different — `struct{ Base }` does NOT get Base's
+// pointer-receiver methods in its value method set while `struct{ *Base }` does
+// — so structural interface satisfaction cannot be exact without the spelling.
+// This is PARSE-TIME capture emission, so a warm cache replays the pre-fix
+// capture set for byte-unchanged files and the distinction never appears:
+// silently, with no error, the v27/v30 failure mode. `analyze` skips tree-sitter
+// dispatch for unchanged chunks (GUARDRAILS.md), so a plain re-analyze does NOT
+// surface it without this bump.
+//
+// 42 -> 43: this branch originally allocated 43 while sitting at 39, because
+// main had already taken 40/41/42 for #2807. main has since merged those and
+// this branch rebased onto it, so 43 remains the next free number and the
+// value is unchanged by the rebase — the reason it was chosen is simply now
+// visible in the history above. RE-CHECK AGAINST origin/main IMMEDIATELY
+// BEFORE MERGING; this file records eight prior collisions, two EXACT.
+// Moved 43 -> 44 for #2842's TypeScript heritage capture, which now emits
+// `@reference.inherits` for `interface_declaration` and
+// `abstract_class_declaration`. That is PARSE-TIME emission, so a v43 warm
+// cache would serve entries that are missing those matches entirely — the
+// exact failure a bump exists to prevent. Verified against origin/main at
+// a857f4c5a, which is still on 43, so 44 is free. RE-CHECK BEFORE MERGE.
+// 44 -> 45: #2837 re-anchors Go's struct/interface captures from the
+// `type_declaration` onto the `type_spec` (`languages/go/query.ts`
+// @scope.class/@declaration.struct/@declaration.interface, and GO_QUERIES
+// @definition.struct/@definition.interface in `tree-sitter-queries.ts`). Every
+// Go file declaring a type therefore emits DIFFERENT capture ranges — measured:
+// 70 fixture digests moved with zero change in capture COUNT — and a grouped
+// `type (...)` block emits nodes it previously did not emit at all. Parse-time,
+// so a warm cache would replay pre-fix ParsedFiles and the fix would be a silent
+// no-op on every incremental analyze while still passing every cold-run test.
+//
+// This branch originally took 44 and it COLLIDED: #2842 above merged first and
+// claimed it. The ninth entry in this ledger, and the third EXACT clash. Worth
+// recording HOW it was caught, because the pin test cannot catch it — both PRs
+// asserted `toBe(44)`, which passes even when main is already 44, so the two
+// capture schemas would have shared one PARSE_CACHE_VERSION and the durable
+// ParsedFile store would have replayed pre-fix ParsedFiles verbatim for one of
+// them. Only comparing against origin/main at MERGE time surfaces it.
+// PR #2840 (Objective-C, draft) still claims 44 as well — it must move too.
+// RE-CHECK AGAINST origin/main IMMEDIATELY BEFORE MERGING.
+//
+// 46 -> 47: method-level Spring `@RequestMapping` now emits wildcard routes
+// and one route per static `RequestMethod.X` value. These decorator routes live
+// in ParseWorkerResult and are replayed verbatim on warm cache hits, so keeping
+// the previous version would make the fix a no-op for every unchanged Java file.
+// PR #2856 claims 46, so this branch owns 47. Verified against upstream/main at
+// 021ac3037 (still 45). RE-CHECK BEFORE MERGE.
+// 47 -> 48: #2833 makes a generic-typed FIELD usable as a call receiver. Three
+// parse-time changes ride on this one value:
+//   - C++ (`languages/cpp/query.ts`) gains `field_declaration` rules whose
+//     `type:` is a `template_type` or a `qualified_identifier` wrapping one.
+//     The rules that existed all required a bare `type_identifier`, so
+//     `Repo<User> repo;` and `std::vector<Item> items;` matched NONE of them and
+//     the member got no type binding at all — new captures where there were none.
+//   - Python (`languages/python/interpret.ts`) reduces a subscripted type its
+//     container allow-lists do not claim to its base name, so `Repo[User]` binds
+//     as `Repo`. That rewrites `TypeRef.rawName`, which is serialized into the
+//     cached ParsedFile.
+//   - `SymbolDefinition.typeParameters` — the DECLARED parameter list
+//     (`template <class T>`, `class Box<T extends Repo>`), captured nowhere
+//     before and on a different axis from the existing `templateArguments`. Six
+//     per-language declaration queries gained `@declaration.type-parameters` and
+//     `scope-extractor.ts` reads it onto every class-like def.
+// A warm cache would replay the pre-fix ParsedFiles, so every file served from
+// it would carry the old captures while passing every cold-run test — the exact
+// failure this constant exists to prevent.
+//
+// WHAT THE BUMP DOES NOT COVER. It invalidates the PARSE half only. v1 is
+// always full-rebuild (no incremental), so the cache has no incremental
+// consumer.
+// `!schemaFingerprintMismatch(...)`, feature parity, non-empty `fileHashes` and
+// a git repo — SCHEMA_BUMP appears in none of them — and an incremental run then
+// writes back only `hashDiff.toWrite`, logging the rest as "unchanged file rows
+// preserved". SCHEMA_FINGERPRINT is a hash of node/relation DDL, which this
+// branch does not touch, so it is byte-identical and moves nothing either.
+// Net: after this bump an incremental analyze re-parses an unchanged file
+// correctly but keeps its existing rows, and the new edges land on the next full
+// rebuild (`--force`, or any run whose runner identity or DDL moved). That is
+// the pre-existing contract for every capture change, not a regression here.
+//
+// THIS BRANCH COLLIDED TWICE, which is why it lands on 48 rather than 46.
+// It first took 46 (the C++/Python captures) and then 47 (typeParameters), both
+// verified free against origin/main at 021ac3037. By merge time main had moved:
+// #2856 claims 46 and #2857 took 47 and merged first. The eleventh entry in this
+// ledger and the FOURTH and FIFTH exact clashes — and note what caught them.
+// Not the pin test: this branch asserted `toBe(47)` and so did #2857, and both
+// pass, because a literal pin cannot see the other side. Only diffing
+// origin/main at the moment of merge surfaces it. Every value this branch
+// published (46, 47) is superseded by 48, so a warm cache stamped with either is
+// correctly invalidated.
+// RE-CHECK AGAINST origin/main IMMEDIATELY BEFORE MERGING.
+const SCHEMA_BUMP = 48;
+const CGRAPH_PKG_VERSION = (() => {
+    try {
+        // package.json sits at cgraph/package.json — two levels up from
+        // cgraph/src/storage/parse-cache.ts (or its dist/ equivalent).
+        const here = __dirname;
+        const candidates = [
+            path_1.default.join(here, '..', '..', '..', '..', 'package.json'), // src|dist/core/code/storage → cgraphx/
+        ];
+        const requireCJS = (0, module_1.createRequire)(__filename);
+        for (const c of candidates) {
+            try {
+                const pkg = requireCJS(c);
+                if (typeof pkg?.version === 'string')
+                    return pkg.version;
+            }
+            catch {
+                /* try next candidate */
+            }
+        }
+    }
+    catch {
+        /* fall through to fallback */
+    }
+    return '0.0.0-unknown';
+})();
+exports.PARSE_CACHE_VERSION = `${SCHEMA_BUMP}+${CGRAPH_PKG_VERSION}`;
+const LEGACY_CACHE_FILENAME = 'parse-cache.json';
+const CACHE_DIRNAME = 'parse-cache';
+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) => (0, crypto_1.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. */
+const fileContentHash = (content) => sha256Hex(content);
+exports.fileContentHash = fileContentHash;
+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');
+    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}`);
+};
+exports.computeChunkHash = computeChunkHash;
+/**
+ * JSON replacer that round-trips Map/Set instances through plain JSON.
+ *
+ * `ParseWorkerResult.parsedFiles[*].scopes[*].typeBindings` is a
+ * `ReadonlyMap<string, TypeRef>`; without this transform it serializes
+ * to `{}` and downstream code that iterates / `.get()`s on it crashes
+ * with "is not iterable". Applied symmetrically by `mapReviver` on
+ * load so the in-memory shape stays Map-typed.
+ */
+const MAP_TAG = '__$mapEntries$__';
+const SET_TAG = '__$setValues$__';
+const mapReplacer = (_key, value) => {
+    if (value instanceof Map)
+        return { [MAP_TAG]: Array.from(value.entries()) };
+    if (value instanceof Set)
+        return { [SET_TAG]: Array.from(value.values()) };
+    return value;
+};
+exports.mapReplacer = mapReplacer;
+const mapReviver = (_key, value) => {
+    if (value && typeof value === 'object') {
+        const v = value;
+        if (Array.isArray(v[MAP_TAG]))
+            return new Map(v[MAP_TAG]);
+        if (Array.isArray(v[SET_TAG]))
+            return new Set(v[SET_TAG]);
+    }
+    return value;
+};
+exports.mapReviver = mapReviver;
+const getLegacyCachePath = (storagePath) => path_1.default.join(storagePath, LEGACY_CACHE_FILENAME);
+const getCacheDirPath = (storagePath) => path_1.default.join(storagePath, CACHE_DIRNAME);
+const getCacheIndexPath = (storagePath) => path_1.default.join(getCacheDirPath(storagePath), CACHE_INDEX_FILENAME);
+const getCacheChunkPath = (storagePath, chunkHash) => path_1.default.join(getCacheDirPath(storagePath), `${chunkHash}.json`);
+/**
+ * Drop fields that are not replayed by `mergeChunkResults` / parse-impl after
+ * RING4-1 (#942). Shrinks on-disk shards and peak RSS during cold runs.
+ */
+const slimParseWorkerResultsForCache = (chunkResults) => {
+    const slim = [];
+    for (const result of chunkResults) {
+        slim.push({
+            ...result,
+            calls: [],
+            assignments: [],
+            constructorBindings: [],
+            parsedFiles: [],
+            // #2112: a clone-safety skip list is per-run telemetry, not graph data —
+            // replay ignores it. Drop it so it doesn't bloat the cached shard.
+            skippedPaths: [],
+        });
+    }
+    return slim;
+};
+exports.slimParseWorkerResultsForCache = slimParseWorkerResultsForCache;
+const readParseCacheChunkFromDisk = async (storagePath, chunkHash) => {
+    if (!isValidChunkCacheKey(chunkHash))
+        return undefined;
+    try {
+        const chunkRaw = await promises_1.default.readFile(getCacheChunkPath(storagePath, chunkHash), 'utf-8');
+        const chunkData = JSON.parse(chunkRaw, exports.mapReviver);
+        return Array.isArray(chunkData) ? chunkData : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Load one chunk shard. Does not retain it in `cache.entries`. */
+const loadParseCacheChunk = async (cache, chunkHash) => {
+    const inMemory = cache.entries.get(chunkHash);
+    if (inMemory !== undefined)
+        return inMemory;
+    if (cache.storagePath && cache.onDiskKeys?.has(chunkHash)) {
+        return readParseCacheChunkFromDisk(cache.storagePath, chunkHash);
+    }
+    return undefined;
+};
+exports.loadParseCacheChunk = loadParseCacheChunk;
+/**
+ * Cache directories already created this process. `persistParseCacheChunk` runs
+ * once per cache-miss chunk; without this guard every miss re-issues a redundant
+ * `mkdir` syscall (hundreds on a large cold repo) (#1983). Storage paths are
+ * process-scoped, so the Set stays bounded.
+ */
+const createdCacheDirs = new Set();
+/**
+ * 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).
+ */
+const persistParseCacheChunk = async (cache, chunkHash, chunkResults) => {
+    const slim = (0, exports.slimParseWorkerResultsForCache)(chunkResults);
+    if (cache.storagePath) {
+        const cacheDir = getCacheDirPath(cache.storagePath);
+        if (!createdCacheDirs.has(cacheDir)) {
+            await promises_1.default.mkdir(cacheDir, { recursive: true });
+            createdCacheDirs.add(cacheDir);
+        }
+        const payload = JSON.stringify(slim, exports.mapReplacer);
+        await promises_1.default.writeFile(getCacheChunkPath(cache.storagePath, chunkHash), payload, 'utf-8');
+        cache.onDiskKeys ??= new Set();
+        cache.onDiskKeys.add(chunkHash);
+        cache.entries.delete(chunkHash);
+        return;
+    }
+    cache.entries.set(chunkHash, slim);
+};
+exports.persistParseCacheChunk = persistParseCacheChunk;
+const loadLegacyParseCache = async (storagePath) => {
+    const cachePath = getLegacyCachePath(storagePath);
+    try {
+        const raw = await promises_1.default.readFile(cachePath, 'utf-8');
+        const data = JSON.parse(raw, exports.mapReviver);
+        if (typeof data !== 'object' ||
+            data === null ||
+            data.version !== exports.PARSE_CACHE_VERSION ||
+            typeof data.entries !== 'object' ||
+            data.entries === null) {
+            return emptyCache(storagePath);
+        }
+        const entries = new Map();
+        for (const [k, v] of Object.entries(data.entries)) {
+            if (Array.isArray(v))
+                entries.set(k, v);
+        }
+        return { version: exports.PARSE_CACHE_VERSION, entries, usedKeys: new Set(), storagePath };
+    }
+    catch {
+        return emptyCache(storagePath);
+    }
+};
+const loadShardedParseCache = async (storagePath) => {
+    const indexPath = getCacheIndexPath(storagePath);
+    try {
+        const raw = await promises_1.default.readFile(indexPath, 'utf-8');
+        const data = JSON.parse(raw);
+        if (typeof data !== 'object' ||
+            data === null ||
+            data.version !== exports.PARSE_CACHE_VERSION ||
+            !Array.isArray(data.keys)) {
+            return emptyCache(storagePath);
+        }
+        const onDiskKeys = new Set();
+        for (const chunkHash of data.keys) {
+            if (typeof chunkHash === 'string' && isValidChunkCacheKey(chunkHash)) {
+                onDiskKeys.add(chunkHash);
+            }
+        }
+        // Lazy: index only — load individual shards on cache hit (#1983).
+        return {
+            version: exports.PARSE_CACHE_VERSION,
+            entries: new Map(),
+            usedKeys: new Set(),
+            storagePath,
+            onDiskKeys,
+        };
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Load the parse cache. Returns an empty cache on any failure (missing
+ * file, corrupt JSON, version mismatch). Never throws on a normal load.
+ */
+const loadParseCache = async (storagePath) => {
+    const sharded = await loadShardedParseCache(storagePath);
+    if (sharded)
+        return sharded;
+    return loadLegacyParseCache(storagePath);
+};
+exports.loadParseCache = loadParseCache;
+/**
+ * Persist the cache to disk using a temp directory + rename.
+ *
+ * Writes shards under `${cacheDir}.tmp`, then removes the old `cacheDir` and
+ * renames the temp directory into place. There is a crash window after
+ * `rm(cacheDir)` and before `rename(tmpDir, cacheDir)` where no cache exists;
+ * that is acceptable — `loadParseCache` yields empty and the next run
+ * reparses. This is not a single atomic swap of the whole tree, but avoids
+ * leaving a half-written shard set visible to readers.
+ */
+const saveParseCache = async (storagePath, cache) => {
+    await promises_1.default.mkdir(storagePath, { recursive: true });
+    const cacheDir = getCacheDirPath(storagePath);
+    const tmpDir = `${cacheDir}.tmp`;
+    await promises_1.default.rm(tmpDir, { recursive: true, force: true });
+    await promises_1.default.mkdir(tmpDir, { recursive: true });
+    const keys = [...cache.usedKeys].filter(isValidChunkCacheKey).sort();
+    // Track hashes whose shard was actually written/copied this save. A hash can
+    // be in `usedKeys` without a backing shard — its in-memory serialize threw, or
+    // its on-disk copy failed/was-absent (e.g. a worker-quarantined chunk added to
+    // usedKeys but never persisted). Writing such a hash into `index.keys` would
+    // make the next load reference a shard that doesn't exist (#1983). Build the
+    // index from what we persisted, not from the raw usedKeys snapshot.
+    const writtenKeys = [];
+    for (const chunkHash of keys) {
+        const chunkPath = path_1.default.join(tmpDir, `${chunkHash}.json`);
+        const inMemory = cache.entries.get(chunkHash);
+        if (inMemory !== undefined) {
+            let payload;
+            try {
+                payload = JSON.stringify(inMemory, exports.mapReplacer);
+            }
+            catch {
+                continue;
+            }
+            await promises_1.default.writeFile(chunkPath, payload, 'utf-8');
+            writtenKeys.push(chunkHash);
+            continue;
+        }
+        const existingPath = getCacheChunkPath(storagePath, chunkHash);
+        try {
+            await promises_1.default.copyFile(existingPath, chunkPath);
+            writtenKeys.push(chunkHash);
+        }
+        catch {
+            /* shard missing — skip; next run treats as cache miss */
+        }
+    }
+    const index = {
+        version: cache.version,
+        keys: writtenKeys,
+    };
+    await promises_1.default.writeFile(path_1.default.join(tmpDir, CACHE_INDEX_FILENAME), JSON.stringify(index), 'utf-8');
+    await promises_1.default.rm(cacheDir, { recursive: true, force: true });
+    await promises_1.default.rename(tmpDir, cacheDir);
+    await promises_1.default.rm(getLegacyCachePath(storagePath), { force: true });
+    // The authoritative final key set actually backed by a shard on disk.
+    // Callers (the durable ParsedFile store) prune to exactly these so the two
+    // content-addressed stores stay coherent — a chunk is cached iff BOTH have it.
+    return writtenKeys;
+};
+exports.saveParseCache = saveParseCache;
+/**
+ * Drop entries whose hashes are not in `usedHashes`. Called at the end
+ * of a run so chunks that no longer correspond to any current chunk
+ * don't keep their stale entries forever.
+ */
+const pruneCache = (cache, usedHashes) => {
+    let removed = 0;
+    for (const k of cache.entries.keys()) {
+        if (!usedHashes.has(k)) {
+            cache.entries.delete(k);
+            removed++;
+        }
+    }
+    if (cache.onDiskKeys) {
+        for (const k of cache.onDiskKeys) {
+            if (!usedHashes.has(k)) {
+                cache.onDiskKeys.delete(k);
+                removed++;
+            }
+        }
+    }
+    return removed;
+};
+exports.pruneCache = pruneCache;
+const emptyCache = (storagePath) => ({
+    version: exports.PARSE_CACHE_VERSION,
+    entries: new Map(),
+    usedKeys: new Set(),
+    storagePath,
+    onDiskKeys: storagePath ? new Set() : undefined,
+});