gitnexus 1.6.8-rc.12 → 1.6.8-rc.13

package/dist/core/ingestion/scope-resolution/pipeline/phase.js

@@ -285,6 +285,9 @@ export const scopeResolutionPhase = {
                 prebuiltNodeLookup: sharedNodeLookup,
                 preExtractedParsedFiles: preExtractedByPath,
                 scopeIndexStorePath: parsedFileStorePath,
+                // CFG/PDG emission (#2081 M1) — opt-in; off ⇒ byte-identical graph.
+                pdg: ctx.options?.pdg === true,
+                pdgMaxEdgesPerFunction: ctx.options?.pdgMaxEdgesPerFunction,
                 recordResolutionOutcome: (outcome) => {
                     resolutionOutcomes.push(outcome);
                 },

package/dist/core/ingestion/scope-resolution/pipeline/run.d.ts

@@ -58,6 +58,16 @@ interface RunScopeResolutionInput {
     readonly treeCache?: {
         get(filePath: string): unknown;
     };
+    /**
+     * CFG/PDG opt-in (#2081 M1). When true, emit BasicBlock nodes + CFG edges
+     * from each ParsedFile's worker-built `cfgSideChannel` during Phase-4 graph
+     * emission (while the disk store is still live). Default/false ⇒ no CFG
+     * nodes or edges and a byte-identical graph.
+     */
+    readonly pdg?: boolean;
+    /** Per-function CFG edge cap. `undefined` ⇒ {@link DEFAULT_MAX_CFG_EDGES_PER_FUNCTION};
+     *  `0` ⇒ no cap (unlimited). */
+    readonly pdgMaxEdgesPerFunction?: number;
     /**
      * Optional graph-node lookup built ONCE by the caller and shared across
      * every language pass. `buildGraphNodeLookup` scans the whole graph and is

package/dist/core/ingestion/scope-resolution/pipeline/run.js

@@ -30,6 +30,7 @@ import { extractParsedFile } from '../../scope-extractor-bridge.js';
 import { finalizeScopeModel } from '../../finalize-orchestrator.js';
 import { resolveReferenceSites } from '../../resolve-references.js';
 import { buildGraphNodeLookup } from '../graph-bridge/node-lookup.js';
+import { emitFileCfgs, isEmitSafeCfg, DEFAULT_MAX_CFG_EDGES_PER_FUNCTION } from '../../cfg/emit.js';
 import { resolveDefGraphId } from '../graph-bridge/ids.js';
 import { buildPopulatedMethodDispatch } from '../graph-bridge/method-dispatch.js';
 import { propagateImportedReturnTypes } from '../passes/imported-return-types.js';
@@ -454,6 +455,67 @@ export function runScopeResolution(input, provider) {
             resolutionConfig,
         });
     }
+    // ── CFG/PDG emission (#2081 M1, opt-in via `--pdg`) ──────────────────────
+    // Emit BasicBlock nodes + CFG edges from each ParsedFile's worker-built
+    // `cfgSideChannel`, HERE — the last point inside scope-resolution where the
+    // ParsedFiles are still loaded (`emitParsedFiles` carries the channel; the
+    // disk store is cleared right after this orchestrator returns, see phase.ts).
+    // A post-`mro` phase would read empty data (KTD1). Off by default ⇒ zero
+    // BasicBlock/CFG nodes/edges and a byte-identical graph.
+    if (input.pdg === true) {
+        let cfgBlocks = 0;
+        let cfgEdges = 0;
+        let cfgDroppedEdges = 0;
+        for (const pf of emitParsedFiles) {
+            const cfgs = pf.cfgSideChannel;
+            // Defensive: cfgSideChannel is opaque (`unknown`) and crosses the cache /
+            // durable store. A stale or wrong-shape value (e.g. a pre-SCHEMA_BUMP
+            // shard that slipped the version gate) must skip emission, not throw a
+            // TypeError mid-graph-build and abort scope-resolution for the language.
+            if (!Array.isArray(cfgs) || cfgs.length === 0)
+                continue;
+            try {
+                // Per-element emit-safety filter (mirrors the parsedfile-store
+                // reviver's POLICY: valid elements in a mixed array still emit; junk
+                // is warned and skipped). isEmitSafeCfg lives in cfg/emit.ts next to
+                // the id templating it defends — see its doc for why anchor-field and
+                // endpoint-membership checks are load-bearing. Runs INSIDE the try so
+                // even a predicate-time throw (e.g. a hostile getter) is isolated.
+                const wellFormed = cfgs.filter(isEmitSafeCfg);
+                if (wellFormed.length < cfgs.length) {
+                    logger.warn(`[cfg] ${pf.filePath}: skipped ${cfgs.length - wellFormed.length} malformed ` +
+                        `cfgSideChannel element(s) (bad shape, missing id-anchor fields, or edge ` +
+                        `endpoints matching no block) — CFG for those functions omitted`);
+                }
+                if (wellFormed.length === 0)
+                    continue;
+                const emitted = emitFileCfgs(graph, wellFormed, input.pdgMaxEdgesPerFunction ?? DEFAULT_MAX_CFG_EDGES_PER_FUNCTION, 
+                // Log cap-overflow drops UNCONDITIONALLY (not via input.onWarn, which is
+                // gated behind the semantic-model validator and silent in production) so
+                // the per-function edge cap never truncates the CFG silently (R6/KTD6).
+                (message) => logger.warn(message));
+                cfgBlocks += emitted.blocks;
+                cfgEdges += emitted.edges;
+                cfgDroppedEdges += emitted.droppedEdges;
+            }
+            catch (err) {
+                // Last-resort isolation, mirroring the worker-side per-file try/catch:
+                // a shape the predicate misses must cost this one file's CFG, not
+                // abort the language's whole scope-resolution pass mid-graph-build.
+                // NOTE a mid-emit throw can leave this file's already-inserted
+                // BasicBlock nodes in the graph (addNode is not transactional) —
+                // orphaned but inert; the predicate keeps every JSON-representable
+                // bad shape from reaching this path at all.
+                logger.warn(`[cfg] ${pf.filePath}: CFG emission failed (${err instanceof Error ? err.message : String(err)}) — ` +
+                    `this file's CFG is partial or absent`);
+            }
+        }
+        if (cfgBlocks > 0) {
+            logger.debug(`[scope-resolution] CFG emit (lang=${provider.language}): ` +
+                `${cfgBlocks} BasicBlock nodes, ${cfgEdges} CFG edges` +
+                (cfgDroppedEdges > 0 ? `, ${cfgDroppedEdges} edges dropped (per-function cap)` : ''));
+        }
+    }
     if (PROF) {
         const tEnd = process.hrtime.bigint();
         const ns = (a, b) => Number(b - a) / 1_000_000;

package/dist/core/ingestion/workers/parse-worker.js

@@ -69,6 +69,7 @@ import { extractTemplateArguments, templateArgumentsIdTag, templateConstraintsId
 import { extractParsedFile } from '../scope-extractor-bridge.js';
 import { persistParsedFileShardSync, persistDurableParsedFileShardSync, } from '../../../storage/parsedfile-store.js';
 import { extractLaravelRoutes } from '../route-extractors/laravel.js';
+import { collectFunctionCfgs, DEFAULT_PDG_MAX_FUNCTION_LINES } from '../cfg/collect.js';
 import { logger } from '../../logger.js';
 // ── ParsedFile store (#1983 parallel serialization) ─────────────────────────
 // Read ONCE at worker init from `workerData` (immutable for the run, inherited
@@ -86,6 +87,17 @@ const PARSED_FILE_STORE_STORAGE_PATH = workerData?.parsedFileStoreStoragePath;
 // restores them without re-parsing. `undefined` ⇒ no durable write.
 const DURABLE_PARSED_FILE_STORAGE_PATH = workerData?.durableParsedFileStoragePath;
 let shardSeq = 0;
+// ── PDG/CFG opt-in (#2081 M1) ───────────────────────────────────────────────
+// Read ONCE at worker init from `workerData` (the worker never sees
+// PipelineOptions — config arrives via the pool factory's `workerData`, see
+// KTD7 / U5). When `pdg` is set, the worker builds a per-function control-flow
+// graph from the tree-sitter AST (where it lives) and serializes it onto
+// `ParsedFile.cfgSideChannel`. Off ⇒ no CFG work and no field — the default for
+// every run today. `pdgMaxFunctionLines` bounds per-function CFG cost
+// (0/undefined ⇒ no cap; see collectFunctionCfgs).
+const PDG_ENABLED = workerData?.pdg === true;
+const PDG_MAX_FUNCTION_LINES = workerData?.pdgMaxFunctionLines ??
+    DEFAULT_PDG_MAX_FUNCTION_LINES;
 // ── Bootstrap-stage diagnostics (#1741) ────────────────────────────────────
 // When GITNEXUS_WORKER_BOOTSTRAP=1 (or --verbose sets GITNEXUS_VERBOSE), each
 // worker reports its startup stage timings to stderr — which the pool tees
@@ -833,7 +845,34 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             // copy — scopes/defs are carried by reference) to attach the field rather
             // than mutate the frozen object.
             const sideChannel = provider.collectCaptureSideChannel?.(file.path);
-            result.parsedFiles.push(sideChannel !== undefined ? { ...parsedFile, captureSideChannel: sideChannel } : parsedFile);
+            let withChannels = sideChannel !== undefined ? { ...parsedFile, captureSideChannel: sideChannel } : parsedFile;
+            // CFG side-channel (#2081 M1): build the per-function control-flow graph
+            // here, where the tree-sitter AST is still in hand, and attach it as plain
+            // serializable data. Only on a --pdg run and only for languages with a
+            // cfgVisitor (TS/JS in M1). The same disk-store/warm-cache machinery that
+            // carries captureSideChannel carries this — its coherence rests on the
+            // SCHEMA_BUMP + the pdg-folded chunk-hash key (see parse-cache.ts).
+            if (PDG_ENABLED && provider.cfgVisitor) {
+                // Isolate the CFG build per file: a throw here (an unexpected tree-sitter
+                // node shape, a deep-nesting stack overflow) must NOT propagate — it
+                // would escape processFileGroup to the language-group catch, which treats
+                // any throw as "parser unavailable" and silently drops EVERY remaining
+                // file in the group. Skip CFG for this one file; parsing + scope
+                // resolution proceed unaffected (CFG is a strictly-additive opt-in).
+                try {
+                    const { cfgs } = collectFunctionCfgs(tree.rootNode, provider.cfgVisitor, file.path, PDG_MAX_FUNCTION_LINES);
+                    if (cfgs.length)
+                        withChannels = { ...withChannels, cfgSideChannel: cfgs };
+                }
+                catch (err) {
+                    const message = `CFG build failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`;
+                    if (parentPort)
+                        parentPort.postMessage({ type: 'warning', message });
+                    else
+                        logger.warn(message);
+                }
+            }
+            result.parsedFiles.push(withChannels);
         }
         // Build per-file type environment + constructor bindings in a single AST walk.
         // The legacy heritage pre-pass that seeded a file-local parentMap for

package/dist/core/ingestion/workers/worker-pool.d.ts

@@ -152,6 +152,15 @@ export interface WorkerPoolOptions {
      * `undefined` ⇒ no durable write.
      */
     durableParsedFileStoragePath?: string;
+    /**
+     * CFG/PDG opt-in (#2081 M1). Baked into every spawned worker's `workerData`
+     * (like the store paths above); when `true`, workers build a per-function
+     * control-flow graph from the tree-sitter AST and attach it to
+     * `ParsedFile.cfgSideChannel`. `undefined`/`false` ⇒ no CFG work.
+     */
+    pdg?: boolean;
+    /** Per-function source-line cap for worker-side CFG construction (0 ⇒ no cap). */
+    pdgMaxFunctionLines?: number;
 }
 export declare class WorkerPoolDispatchError extends Error {
     /**

package/dist/core/ingestion/workers/worker-pool.js

@@ -550,8 +550,11 @@ export const createWorkerPool = (workerUrl, poolSize, options) => {
     // signature is unchanged so the zero-arg test factories keep working.
     const parsedFileStoreStoragePath = options?.parsedFileStoreStoragePath;
     const durableParsedFileStoragePath = options?.durableParsedFileStoragePath;
-    const workerStoreData = parsedFileStoreStoragePath || durableParsedFileStoragePath
-        ? { parsedFileStoreStoragePath, durableParsedFileStoragePath }
+    // CFG/PDG opt-in (#2081 M1) — carried in workerData alongside the store paths.
+    const pdg = options?.pdg === true;
+    const pdgMaxFunctionLines = options?.pdgMaxFunctionLines;
+    const workerStoreData = parsedFileStoreStoragePath || durableParsedFileStoragePath || pdg
+        ? { parsedFileStoreStoragePath, durableParsedFileStoragePath, pdg, pdgMaxFunctionLines }
         : undefined;
     const spawnWorker = options?.workerFactory ??
         ((url) => new Worker(url, {

package/dist/core/run-analyze.d.ts

@@ -8,6 +8,7 @@
  * IMPORTANT: This module must NEVER call process.exit(). The caller (CLI
  * wrapper or server worker) is responsible for process lifecycle.
  */
+import { type RepoMeta } from '../storage/repo-manager.js';
 export interface AnalyzeCallbacks {
     onProgress: (phase: string, percent: number, message: string) => void;
     onLog?: (message: string) => void;
@@ -48,6 +49,19 @@ export interface AnalyzeOptions {
     noStats?: boolean;
     /** Skip installing standard GitNexus skill files to .claude/skills/gitnexus/. */
     skipSkills?: boolean;
+    /**
+     * Build the CFG/PDG substrate (#2081 M1). Forwarded to `PipelineOptions.pdg`,
+     * which threads to BOTH the worker (CFG build, via workerData) AND
+     * scope-resolution (BasicBlock/CFG emit gate). Off by default.
+     */
+    pdg?: boolean;
+    /** Per-function source-line cap for worker-side CFG construction (#2081 M1).
+     *  Forwarded to `PipelineOptions.pdgMaxFunctionLines`. No CLI flag in M1 —
+     *  programmatic / server analyze-worker path only; the worker applies
+     *  `DEFAULT_PDG_MAX_FUNCTION_LINES` when unset. */
+    pdgMaxFunctionLines?: number;
+    /** Per-function CFG edge cap. Forwarded to `PipelineOptions.pdgMaxEdgesPerFunction`. */
+    pdgMaxEdgesPerFunction?: number;
     /**
      * Default branch threaded into generated AGENTS.md / CLAUDE.md so the
      * regression-compare example uses the configured branch instead of a
@@ -162,4 +176,22 @@ export declare const collectBranchCacheKeys: (storagePath: string, excludeDir?:
     keys: Set<string>;
     complete: boolean;
 }>;
+/**
+ * Resolve the requested `--pdg` configuration to the shape recorded in
+ * `RepoMeta.pdg`, or `undefined` for a pdg-off run. Caps resolve to their
+ * defaults so an explicit-default run compares equal to a default run
+ * (`0` = unlimited is preserved as `0`). Pure + exported for testing.
+ */
+type PdgOptions = Pick<AnalyzeOptions, 'pdg' | 'pdgMaxFunctionLines' | 'pdgMaxEdgesPerFunction'>;
+export declare const resolvePdgConfig: (options: PdgOptions) => RepoMeta["pdg"];
+/**
+ * Whether the requested `--pdg` configuration differs from the one the
+ * existing index's DB rows were built under (#2099 F1). An absent recorded
+ * stamp means pdg-off (every legacy meta — `--pdg` shipped opt-in). Any
+ * mismatch means the incremental writeback (which only persists changed-file
+ * nodes) cannot produce a coherent index: off→on would silently drop the
+ * freshly built CFG layer, on→off would strand zombie BasicBlocks — so the
+ * caller forces a full writeback. Pure + exported for testing.
+ */
+export declare const pdgModeMismatch: (recorded: RepoMeta["pdg"], options: PdgOptions) => boolean;
 export declare function runFullAnalysis(repoPath: string, options: AnalyzeOptions, callbacks: AnalyzeCallbacks): Promise<AnalyzeResult>;

package/dist/core/run-analyze.js

@@ -18,6 +18,8 @@ import { createSearchFTSIndexes, verifySearchFTSIndexes } from './search/fts-ind
 import { resolveAnalyzeInstallPolicy } from './lbug/extension-loader.js';
 import { startWalCheckpointDriver, } from './lbug/wal-checkpoint-driver.js';
 import { getStoragePaths, resolveBranchPlacement, saveMeta, loadMeta, ensureGitNexusIgnored, registerRepo, cleanupOldKuzuFiles, INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js';
+import { DEFAULT_PDG_MAX_FUNCTION_LINES } from './ingestion/cfg/collect.js';
+import { DEFAULT_MAX_CFG_EDGES_PER_FUNCTION } from './ingestion/cfg/emit.js';
 import { computeFileHashes, diffFileHashes } from '../storage/file-hash.js';
 import { extractChangedSubgraph, computeEffectiveWriteSet, } from './incremental/subgraph-extract.js';
 import { shadowCandidatesFor } from './incremental/shadow-candidates.js';
@@ -128,6 +130,30 @@ export const collectBranchCacheKeys = async (storagePath, excludeDir) => {
     }
     return { keys, complete };
 };
+export const resolvePdgConfig = (options) => options.pdg === true
+    ? {
+        maxFunctionLines: options.pdgMaxFunctionLines ?? DEFAULT_PDG_MAX_FUNCTION_LINES,
+        maxEdgesPerFunction: options.pdgMaxEdgesPerFunction ?? DEFAULT_MAX_CFG_EDGES_PER_FUNCTION,
+    }
+    : undefined;
+/**
+ * Whether the requested `--pdg` configuration differs from the one the
+ * existing index's DB rows were built under (#2099 F1). An absent recorded
+ * stamp means pdg-off (every legacy meta — `--pdg` shipped opt-in). Any
+ * mismatch means the incremental writeback (which only persists changed-file
+ * nodes) cannot produce a coherent index: off→on would silently drop the
+ * freshly built CFG layer, on→off would strand zombie BasicBlocks — so the
+ * caller forces a full writeback. Pure + exported for testing.
+ */
+export const pdgModeMismatch = (recorded, options) => {
+    const requested = resolvePdgConfig(options);
+    if (!requested && !recorded)
+        return false;
+    if (!requested || !recorded)
+        return true;
+    return (requested.maxFunctionLines !== recorded.maxFunctionLines ||
+        requested.maxEdgesPerFunction !== recorded.maxEdgesPerFunction);
+};
 export async function runFullAnalysis(repoPath, options, callbacks) {
     const log = (msg) => callbacks.onLog?.(msg);
     const progress = (phase, percent, message) => callbacks.onProgress(phase, percent, message);
@@ -265,13 +291,37 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // clear it, the on-disk index may be in a half-state. Cheapest path
     // back to a known-good index is to wipe + rebuild from scratch.
     if (existingMeta?.incrementalInProgress) {
-        log('Previous incremental run did not complete cleanly (incrementalInProgress flag set); ' +
+        log(
+        // "analyze run", not "incremental run" — since #2099 F1 the flag is a
+        // generic dirty marker written by BOTH writeback branches.
+        'Previous analyze run did not complete cleanly (incrementalInProgress flag set); ' +
             'forcing full rebuild to restore a known-good index.');
         options = { ...options, force: true };
         // Reload meta after clearing the flag in-memory; we still want fileHashes
         // for the post-rebuild meta carry-over, but force=true ensures the
         // rebuild path executes.
     }
+    // ── pdg-mode flip forces full writeback (#2099 F1) ─────────────────
+    // The incremental writeback persists only changed-file nodes, so a pdg
+    // config differing from the one the DB rows were built under cannot be
+    // reconciled incrementally: off→on silently drops the freshly built CFG
+    // layer ("Incremental: changed=0", zero BasicBlock rows), on→off strands
+    // zombie blocks for unchanged files. MUST sit before the alreadyUpToDate
+    // fast path below — a clean-tree flip would otherwise early-return without
+    // running the pipeline at all. The notice is deliberately NOT gated on
+    // options.force: --skills implies force with no message of its own, and a
+    // mode change deserves a diagnostic regardless of why a rebuild happens.
+    if (existingMeta && pdgModeMismatch(existingMeta.pdg, options)) {
+        const pdgOn = options.pdg === true;
+        const capsOnly = !!existingMeta.pdg && pdgOn; // both-on can only mismatch via caps
+        const was = existingMeta.pdg ? 'with --pdg' : 'without --pdg';
+        const now = pdgOn ? 'with --pdg' : 'without --pdg';
+        log(`pdg mode changed (index built ${was}, this run is ${now}` +
+            `${capsOnly ? ', but with different caps' : ''}); forcing a full ` +
+            `rebuild so the CFG layer is ${pdgOn ? 'fully persisted' : 'fully removed'}. ` +
+            `Tip: set \`pdg: ${pdgOn}\` in .gitnexusrc to pin the mode across runs.`);
+        options = { ...options, force: true };
+    }
     // ── Early-return: already up to date ──────────────────────────────
     if (existingMeta && !options.force && existingMeta.lastCommit === currentCommit) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
@@ -416,6 +466,11 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     }, {
         parseCache,
         workerPoolSize: options.workerPoolSize,
+        // CFG/PDG opt-in (#2081 M1). PipelineOptions.pdg fans out to the worker
+        // build gate (workerData.pdg) and the scope-resolution emit gate.
+        pdg: options.pdg === true,
+        pdgMaxFunctionLines: options.pdgMaxFunctionLines,
+        pdgMaxEdgesPerFunction: options.pdgMaxEdgesPerFunction,
         fetchWrappers: options.fetchWrappers,
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
@@ -465,6 +520,19 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     }
     else {
         // Full rebuild path: wipe DB files first.
+        // Set the dirty flag BEFORE the wipe whenever a prior meta exists,
+        // mirroring the incremental branch above (#2099 F1, KTD2b). Without it a
+        // full rebuild crashing between the wipe and the end-of-run saveMeta
+        // leaves a meta that vouches for a DB it no longer matches — the next
+        // clean-tree run's fast path would certify a destroyed DB (or, after a
+        // pdg flip, certify zombie/missing BasicBlock rows indefinitely).
+        // toWriteCount: 0 is the full-path sentinel (no incremental write set).
+        if (existingMeta) {
+            await saveMeta(metaDir, {
+                ...existingMeta,
+                incrementalInProgress: { startedAt: Date.now(), toWriteCount: 0 },
+            });
+        }
         await closeLbug();
         const lbugFiles = [lbugPath, `${lbugPath}.wal`, `${lbugPath}.lock`];
         for (const f of lbugFiles) {
@@ -846,6 +914,12 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             // so a sibling branch's prune can union it and not evict our shards.
             cacheKeys: [...parseCache.usedKeys],
             incrementalInProgress: undefined,
+            // The effective pdg config this run's DB rows were built under
+            // (#2099 F1). `undefined` on pdg-off runs — this meta is a fresh
+            // literal (no spread of existingMeta), so omission is what CLEARS the
+            // stamp after an on→off flip; the next pdgModeMismatch then compares
+            // off==off and incremental eligibility is restored.
+            pdg: resolvePdgConfig(options),
         };
         await saveMeta(metaDir, meta);
         // Persist the incremental parse cache for the next run. Wraps in

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 = 5; // #2081 M1: ParsedFile gained `cfgSideChannel`
 const GITNEXUS_PKG_VERSION = (() => {
     try {
         // package.json sits at gitnexus/package.json — two levels up from
@@ -92,17 +92,27 @@ 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.
+    const ns = `pdg:1;maxFn=${opts.maxFunctionLines ?? 'def'}`;
+    return sha256Hex(`${ns}\n${joined}`);
 };
 /**
  * JSON replacer that round-trips Map/Set instances through plain JSON.

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

@@ -74,16 +74,18 @@ export interface RepoMeta {
      */
     fileHashes?: Record<string, string>;
     /**
-     * Crash-recovery dirty flag. Written to meta.json BEFORE any
-     * destructive DB mutation in an incremental run; cleared on success
-     * by overwriting meta.json. If a run crashes between, the next run
-     * sees the flag and forces a full rebuild — the cheapest path back
-     * to a known-good index.
+     * Crash-recovery dirty flag — a generic marker written to meta.json
+     * BEFORE any destructive DB mutation by BOTH writeback branches
+     * (incremental since its introduction; full rebuilds over an existing
+     * meta since #2099 F1); cleared on success by overwriting meta.json.
+     * If a run crashes between, the next run sees the flag and forces a
+     * full rebuild — the cheapest path back to a known-good index.
      */
     incrementalInProgress?: {
-        /** When the incremental run started (epoch ms). */
+        /** When the run started (epoch ms). */
         startedAt: number;
-        /** Number of files in the writable set, for diagnostic logs. */
+        /** Number of files in the writable set, for diagnostic logs.
+         *  `0` on the full-rebuild path (no incremental write set exists). */
         toWriteCount: number;
     };
     /**
@@ -103,6 +105,28 @@ export interface RepoMeta {
      * branch's still-live shards. Additive/optional; absent in legacy metas.
      */
     cacheKeys?: string[];
+    /**
+     * The effective `--pdg` configuration this index's DB rows were built
+     * under (#2099 F1). Presence ≡ the BasicBlock/CFG layer exists in the DB;
+     * ABSENT ≡ pdg-off — which covers every legacy meta, since `--pdg`
+     * shipped opt-in. Caps are recorded RESOLVED (defaults applied) so an
+     * explicit-default run compares equal to a default run. run-analyze
+     * compares this against the requested options and forces a full
+     * writeback on any mismatch — the incremental path only persists
+     * changed-file nodes and would otherwise silently drop (or strand) the
+     * CFG layer on a mode flip. Additive/optional, no
+     * INCREMENTAL_SCHEMA_VERSION bump (a bump would force a one-time full
+     * rebuild for every user). NOTE the removal mechanism is load-bearing:
+     * the end-of-run meta is a fresh object literal, NOT a spread of the
+     * prior meta, so omitting this field on a pdg-off run is what clears
+     * the stamp after an on→off flip.
+     */
+    pdg?: {
+        /** Worker-side per-function source-line cap, resolved (0 = unlimited). */
+        maxFunctionLines: number;
+        /** Emit-side per-function CFG edge cap, resolved (0 = unlimited). */
+        maxEdgesPerFunction: number;
+    };
 }
 /**
  * Bumped whenever incremental-indexing invariants change incompatibly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.12",
+  "version": "1.6.8-rc.13",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",