gitnexus 1.6.8-rc.9 → 1.6.8

package/dist/core/lbug/rel-pair-routing.d.ts

@@ -0,0 +1,54 @@
+import { type WriteStream } from 'fs';
+/** Injectable for tests (backpressure/error simulation), mirroring split. */
+export type WriteStreamFactory = (filePath: string) => WriteStream;
+/**
+ * Derive a node's table label from its graph id. Matches the legacy
+ * `getNodeLabel` that lived inline in `loadGraphToLbug`:
+ *   - `comm_*`  → Community
+ *   - `proc_*`  → Process
+ *   - otherwise the prefix before the first `:` (e.g. `Function:…` → Function)
+ */
+export declare const getNodeLabel: (nodeId: string) => string;
+export interface RelPairMeta {
+    csvPath: string;
+    rows: number;
+}
+/**
+ * Routes already-escaped relationship CSV rows to per-FROM→TO-label-pair
+ * files. Filters edges whose endpoint labels are not valid node tables
+ * (counted as `skipped`), exactly as the legacy split did.
+ */
+export declare class RelPairRouter {
+    private readonly csvDir;
+    private readonly header;
+    private readonly validTables;
+    private readonly wsFactory;
+    /** pairKey (`From|To`) → { csvPath, rows } */
+    readonly byPair: Map<string, RelPairMeta>;
+    private readonly streams;
+    skipped: number;
+    total: number;
+    private streamError;
+    private readonly abort;
+    constructor(csvDir: string, header: string, validTables: Set<string>, wsFactory?: WriteStreamFactory);
+    private markError;
+    /**
+     * The first stream error observed, if any. Lets the emit caller rethrow the
+     * real error (EMFILE / disk-full) instead of the generic `AbortError` that a
+     * pending `once(ws,'drain',{signal})` rejects with when the abort fires —
+     * mirroring the retained `splitRelCsvByLabelPair`'s `throw streamError ?? err`.
+     */
+    get lastError(): Error | null;
+    /**
+     * Route one already-escaped CSV row (no trailing newline) to its pair file.
+     * Returns `void` on the synchronous hot path; a `Promise<void>` only when a
+     * stream signals backpressure (or a new pair's header does) — the caller
+     * awaits the promise before routing the next edge.
+     */
+    route(fromId: string, toId: string, row: string): void | Promise<void>;
+    private openAndWrite;
+    /** Flush + close every pair stream. Rejects if any stream errored. */
+    close(): Promise<void>;
+    /** Tear down all streams (no flush) — used on the error path. */
+    destroy(): void;
+}

package/dist/core/lbug/rel-pair-routing.js

@@ -0,0 +1,140 @@
+/**
+ * Relationship per-label-pair routing (#2203 U2).
+ *
+ * LadybugDB's bulk `COPY` into the single `CodeRelation` rel table requires a
+ * separate CSV per FROM→TO node-label pair (the `from=`/`to=` COPY params).
+ * Historically the emit pass wrote one monolithic `relations.csv`, which
+ * `loadGraphToLbug` then RE-READ line-by-line (regex per edge) and re-split
+ * into per-pair files — writing and reading the entire ~1M-edge set twice.
+ *
+ * This router lets the single emit pass route each edge to its per-pair file
+ * directly, so the monolithic write + re-read + per-edge regex are all gone.
+ * The label-derivation + validTables filtering + per-pair-file format here match
+ * the legacy `splitRelCsvByLabelPair`, so the per-pair files are byte-identical
+ * for all quote-free ids — see the differential test in
+ * `test/integration/csv-pipeline.test.ts`. ONE intentional divergence: this
+ * router derives the label from the RAW id, while the oracle re-derives it via a
+ * regex over the ESCAPED row — so for an id containing a `"` the router is the
+ * more-correct path (it routes the edge to the right pair; the oracle's regex
+ * mis-buckets or drops it). `splitRelCsvByLabelPair` is retained as the
+ * differential oracle (the quote-in-id divergence is asserted explicitly).
+ *
+ * Backpressure: at most one stream is awaited at a time (the caller routes
+ * edges sequentially and awaits the returned drain promise before the next),
+ * mirroring the legacy split's `for await` invariant. The hot path (existing
+ * pair, no backpressure) returns `void` — no microtask per edge.
+ */
+import path from 'path';
+import { createWriteStream } from 'fs';
+import { once } from 'events';
+import { finished } from 'stream/promises';
+/**
+ * Derive a node's table label from its graph id. Matches the legacy
+ * `getNodeLabel` that lived inline in `loadGraphToLbug`:
+ *   - `comm_*`  → Community
+ *   - `proc_*`  → Process
+ *   - otherwise the prefix before the first `:` (e.g. `Function:…` → Function)
+ */
+export const getNodeLabel = (nodeId) => {
+    if (nodeId.startsWith('comm_'))
+        return 'Community';
+    if (nodeId.startsWith('proc_'))
+        return 'Process';
+    return nodeId.split(':')[0];
+};
+/**
+ * Routes already-escaped relationship CSV rows to per-FROM→TO-label-pair
+ * files. Filters edges whose endpoint labels are not valid node tables
+ * (counted as `skipped`), exactly as the legacy split did.
+ */
+export class RelPairRouter {
+    csvDir;
+    header;
+    validTables;
+    wsFactory;
+    /** pairKey (`From|To`) → { csvPath, rows } */
+    byPair = new Map();
+    streams = new Map();
+    skipped = 0;
+    total = 0;
+    streamError = null;
+    abort = new AbortController();
+    constructor(csvDir, header, validTables, wsFactory = (p) => createWriteStream(p, 'utf-8')) {
+        this.csvDir = csvDir;
+        this.header = header;
+        this.validTables = validTables;
+        this.wsFactory = wsFactory;
+    }
+    markError = (err) => {
+        this.streamError ??= err;
+        this.abort.abort(err);
+    };
+    /**
+     * The first stream error observed, if any. Lets the emit caller rethrow the
+     * real error (EMFILE / disk-full) instead of the generic `AbortError` that a
+     * pending `once(ws,'drain',{signal})` rejects with when the abort fires —
+     * mirroring the retained `splitRelCsvByLabelPair`'s `throw streamError ?? err`.
+     */
+    get lastError() {
+        return this.streamError;
+    }
+    /**
+     * Route one already-escaped CSV row (no trailing newline) to its pair file.
+     * Returns `void` on the synchronous hot path; a `Promise<void>` only when a
+     * stream signals backpressure (or a new pair's header does) — the caller
+     * awaits the promise before routing the next edge.
+     */
+    route(fromId, toId, row) {
+        if (this.streamError)
+            throw this.streamError;
+        const fromLabel = getNodeLabel(fromId);
+        const toLabel = getNodeLabel(toId);
+        if (!this.validTables.has(fromLabel) || !this.validTables.has(toLabel)) {
+            this.skipped++;
+            return;
+        }
+        const pairKey = `${fromLabel}|${toLabel}`;
+        const ws = this.streams.get(pairKey);
+        if (ws === undefined) {
+            // First edge for this pair: open the stream, write header + row.
+            return this.openAndWrite(pairKey, fromLabel, toLabel, row);
+        }
+        this.byPair.get(pairKey).rows++;
+        this.total++;
+        if (!ws.write(row + '\n')) {
+            return once(ws, 'drain', { signal: this.abort.signal }).then(() => undefined);
+        }
+    }
+    async openAndWrite(pairKey, fromLabel, toLabel, row) {
+        const csvPath = path.join(this.csvDir, `rel_${fromLabel}_${toLabel}.csv`);
+        const ws = this.wsFactory(csvPath);
+        ws.on('error', this.markError);
+        this.streams.set(pairKey, ws);
+        this.byPair.set(pairKey, { csvPath, rows: 1 });
+        this.total++;
+        if (!ws.write(this.header + '\n')) {
+            await once(ws, 'drain', { signal: this.abort.signal });
+        }
+        if (!ws.write(row + '\n')) {
+            await once(ws, 'drain', { signal: this.abort.signal });
+        }
+    }
+    /** Flush + close every pair stream. Rejects if any stream errored. */
+    async close() {
+        if (this.streamError) {
+            this.destroy();
+            throw this.streamError;
+        }
+        await Promise.all(Array.from(this.streams.values()).map(async (ws) => {
+            ws.end();
+            await finished(ws);
+        }));
+        if (this.streamError)
+            throw this.streamError;
+    }
+    /** Tear down all streams (no flush) — used on the error path. */
+    destroy() {
+        for (const ws of this.streams.values())
+            ws.destroy();
+    }
+}

package/dist/core/lbug/schema.d.ts

@@ -39,10 +39,10 @@ export declare const ANNOTATION_SCHEMA: string;
 export declare const CONSTRUCTOR_SCHEMA: string;
 export declare const TEMPLATE_SCHEMA: string;
 export declare const MODULE_SCHEMA: string;
-export declare const ROUTE_SCHEMA = "\nCREATE NODE TABLE Route (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  responseKeys STRING[],\n  errorKeys STRING[],\n  middleware STRING[],\n  PRIMARY KEY (id)\n)";
+export declare const ROUTE_SCHEMA = "\nCREATE NODE TABLE Route (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  responseKeys STRING[],\n  errorKeys STRING[],\n  middleware STRING[],\n  method STRING,\n  PRIMARY KEY (id)\n)";
 export declare const TOOL_SCHEMA = "\nCREATE NODE TABLE Tool (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const SECTION_SCHEMA = "\nCREATE NODE TABLE Section (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  level INT64,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
-export declare const BASICBLOCK_SCHEMA = "\nCREATE NODE TABLE BasicBlock (\n  id STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  text STRING,\n  PRIMARY KEY (id)\n)";
+export declare const BASICBLOCK_SCHEMA = "\nCREATE NODE TABLE BasicBlock (\n  id STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  text STRING,\n  callees STRING,\n  calleeIds STRING,\n  PRIMARY KEY (id)\n)";
 export declare const RELATION_SCHEMA = "\nCREATE REL TABLE CodeRelation (\n  FROM File TO File,\n  FROM File TO Folder,\n  FROM File TO Function,\n  FROM File TO Class,\n  FROM File TO Interface,\n  FROM File TO Method,\n  FROM File TO CodeElement,\n  FROM File TO `Struct`,\n  FROM File TO `Enum`,\n  FROM File TO `Macro`,\n  FROM File TO `Typedef`,\n  FROM File TO `Union`,\n  FROM File TO `Namespace`,\n  FROM File TO `Trait`,\n  FROM File TO `Impl`,\n  FROM File TO `TypeAlias`,\n  FROM File TO `Const`,\n  FROM File TO `Static`,\n  FROM File TO `Variable`,\n  FROM File TO `Property`,\n  FROM File TO `Record`,\n  FROM File TO `Delegate`,\n  FROM File TO `Annotation`,\n  FROM File TO `Constructor`,\n  FROM File TO `Template`,\n  FROM File TO `Module`,\n  FROM File TO Section,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO Function,\n  FROM Function TO Method,\n  FROM Function TO Class,\n  FROM Function TO Community,\n  FROM Function TO `Macro`,\n  FROM Function TO `Struct`,\n  FROM Function TO `Template`,\n  FROM Function TO `Enum`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `TypeAlias`,\n  FROM Function TO `Module`,\n  FROM Function TO `Impl`,\n  FROM Function TO Interface,\n  FROM Function TO `Constructor`,\n  FROM Function TO `Const`,\n  FROM Function TO `Typedef`,\n  FROM Function TO `Union`,\n  FROM Function TO `Property`,\n  FROM Function TO CodeElement,\n  FROM Class TO Method,\n  FROM Class TO Function,\n  FROM Class TO Class,\n  FROM Class TO Interface,\n  FROM Class TO Community,\n  FROM Class TO `Template`,\n  FROM Class TO `TypeAlias`,\n  FROM Class TO `Struct`,\n  FROM Class TO `Enum`,\n  FROM Class TO `Annotation`,\n  FROM Class TO `Constructor`,\n  FROM Class TO `Trait`,\n  FROM Class TO `Macro`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Union`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO `Property`,\n  FROM Method TO Function,\n  FROM Method TO Method,\n  FROM Method TO Class,\n  FROM Method TO Community,\n  FROM Method TO `Template`,\n  FROM Method TO `Struct`,\n  FROM Method TO `TypeAlias`,\n  FROM Method TO `Enum`,\n  FROM Method TO `Macro`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Module`,\n  FROM Method TO `Impl`,\n  FROM Method TO Interface,\n  FROM Method TO `Constructor`,\n  FROM Method TO `Property`,\n  FROM Method TO CodeElement,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO `Module`,\n  FROM Section TO Section,\n  FROM Section TO File,\n  FROM File TO Route,\n  FROM Function TO Route,\n  FROM Method TO Route,\n  FROM File TO Tool,\n  FROM Function TO Tool,\n  FROM Method TO Tool,\n  FROM CodeElement TO Community,\n  FROM Interface TO Community,\n  FROM Interface TO Function,\n  FROM Interface TO Method,\n  FROM Interface TO Class,\n  FROM Interface TO Interface,\n  FROM Interface TO `TypeAlias`,\n  FROM Interface TO `Struct`,\n  FROM Interface TO `Constructor`,\n  FROM Interface TO `Property`,\n  FROM `Struct` TO Community,\n  FROM `Struct` TO `Trait`,\n  FROM `Struct` TO `Struct`,\n  FROM `Struct` TO Class,\n  FROM `Struct` TO `Enum`,\n  FROM `Struct` TO Function,\n  FROM `Struct` TO Method,\n  FROM `Struct` TO Interface,\n  FROM `Struct` TO `Constructor`,\n  FROM `Struct` TO `Property`,\n  FROM `Enum` TO `Enum`,\n  FROM `Enum` TO Community,\n  FROM `Enum` TO Class,\n  FROM `Enum` TO Interface,\n  FROM `Macro` TO Community,\n  FROM `Macro` TO Function,\n  FROM `Macro` TO Method,\n  FROM `Module` TO Function,\n  FROM `Module` TO Method,\n  FROM `Typedef` TO Community,\n  FROM `Union` TO Community,\n  FROM `Namespace` TO Community,\n  FROM `Namespace` TO `Struct`,\n  FROM `Trait` TO Method,\n  FROM `Trait` TO `Constructor`,\n  FROM `Trait` TO `Property`,\n  FROM `Trait` TO Community,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO Community,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `TypeAlias` TO Community,\n  FROM `TypeAlias` TO `Trait`,\n  FROM `TypeAlias` TO Class,\n  FROM `Const` TO Community,\n  FROM `Static` TO Community,\n  FROM `Variable` TO Community,\n  FROM `Property` TO Community,\n  FROM `Record` TO Method,\n  FROM `Record` TO `Constructor`,\n  FROM `Record` TO `Property`,\n  FROM `Record` TO Community,\n  FROM `Delegate` TO Community,\n  FROM `Annotation` TO Community,\n  FROM `Constructor` TO Community,\n  FROM `Constructor` TO Interface,\n  FROM `Constructor` TO Class,\n  FROM `Constructor` TO Method,\n  FROM `Constructor` TO Function,\n  FROM `Constructor` TO `Constructor`,\n  FROM `Constructor` TO `Struct`,\n  FROM `Constructor` TO `Macro`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `TypeAlias`,\n  FROM `Constructor` TO `Enum`,\n  FROM `Constructor` TO `Annotation`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Module`,\n  FROM `Constructor` TO `Property`,\n  FROM `Constructor` TO `Typedef`,\n  FROM `Template` TO Community,\n  FROM `Module` TO Community,\n  FROM Function TO Process,\n  FROM Method TO Process,\n  FROM Class TO Process,\n  FROM Interface TO Process,\n  FROM `Struct` TO Process,\n  FROM `Constructor` TO Process,\n  FROM `Module` TO Process,\n  FROM `Macro` TO Process,\n  FROM `Impl` TO Process,\n  FROM `Typedef` TO Process,\n  FROM `TypeAlias` TO Process,\n  FROM `Enum` TO Process,\n  FROM `Union` TO Process,\n  FROM `Namespace` TO Process,\n  FROM `Trait` TO Process,\n  FROM `Const` TO Process,\n  FROM `Static` TO Process,\n  FROM `Variable` TO Process,\n  FROM `Property` TO Process,\n  FROM `Record` TO Process,\n  FROM `Delegate` TO Process,\n  FROM `Annotation` TO Process,\n  FROM `Template` TO Process,\n  FROM CodeElement TO Process,\n  FROM Route TO Process,\n  FROM Tool TO Process,\n  FROM BasicBlock TO BasicBlock,\n  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
 export declare const EMBEDDING_DIMS: number;
 /** HNSW vector index name for the CodeEmbedding table. */

package/dist/core/lbug/schema.js

@@ -177,6 +177,7 @@ CREATE NODE TABLE Route (
   responseKeys STRING[],
   errorKeys STRING[],
   middleware STRING[],
+  method STRING,
   PRIMARY KEY (id)
 )`;
 // MCP tool definitions
@@ -215,6 +216,8 @@ CREATE NODE TABLE BasicBlock (
   startLine INT64,
   endLine INT64,
   text STRING,
+  callees STRING,
+  calleeIds STRING,
   PRIMARY KEY (id)
 )`;
 // ============================================================================

package/dist/core/logger.d.ts

@@ -46,11 +46,6 @@ export interface CreateLoggerOptions {
  * test mode (tests use an in-memory destination).
  */
 export declare function flushLoggerSync(): void;
-/**
- * @internal Test-only reset for the pino-pretty availability cache. Lets
- * unit tests exercise both resolve outcomes within the same vitest worker.
- */
-export declare function _resetPrettyAvailableCache(): void;
 /**
  * Build the pino-pretty transport options. Internal — exported only so unit
  * tests can exercise the probe path without going through `shouldUsePretty()`

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,52 @@ 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;
+    /** Per-function REACHING_DEF edge cap (#2082 M2). Forwarded to
+     *  `PipelineOptions.pdgMaxReachingDefEdgesPerFunction`. */
+    pdgMaxReachingDefEdgesPerFunction?: number;
+    /** Per-function CDG edge cap (#2085 M5). Forwarded to
+     *  `PipelineOptions.pdgMaxCdgEdgesPerFunction`. No CLI flag or rc key —
+     *  programmatic / server path only, like the other pdg caps. */
+    pdgMaxCdgEdgesPerFunction?: number;
+    /** Per-function taint findings cap (#2083 M3). Forwarded to
+     *  `PipelineOptions.pdgMaxTaintFindingsPerFunction`. No CLI flag or rc key
+     *  (KTD8) — programmatic / server path only, like the other pdg caps. */
+    pdgMaxTaintFindingsPerFunction?: number;
+    /** Per-finding taint hop cap (#2083 M3, KTD6). Forwarded to
+     *  `PipelineOptions.pdgMaxTaintHops`. No CLI flag or rc key (KTD8). */
+    pdgMaxTaintHops?: number;
+    /** Per-run cross-function findings/hops/edges caps (#2084 review P1-3).
+     *  Forwarded to the matching `PipelineOptions.pdgMaxInterproc*`; resolved
+     *  into `RepoMeta.pdg`. No CLI flag or rc key (KTD8). */
+    pdgMaxInterprocFindings?: number;
+    pdgMaxInterprocHops?: number;
+    pdgMaxInterprocEdges?: number;
+    /**
+     * Stream the BasicBlock + intra-file PDG-edge layer to CSV-on-disk during the
+     * emit loop instead of materializing it in the in-memory graph, bounding peak
+     * RSS to O(chunk) for full-kernel-scale repos (#2202). Only engages on a full
+     * rebuild — `resolveStreamPdgEmit` additionally requires `force === true`
+     * (the pre-pipeline guarantee of a full rebuild). May also be enabled via
+     * `GITNEXUS_STREAM_PDG_EMIT`. Memory-only; byte-identical output; not stamped
+     * into `RepoMeta.pdg`. */
+    streamPdgEmit?: boolean;
+    /** Streamed PDG-emit write buffer (rows). `undefined` ⇒
+     *  `DEFAULT_PDG_EMIT_CHUNK_ROWS`. May also be set via
+     *  `GITNEXUS_PDG_EMIT_CHUNK_SIZE`. Memory-only (#2202). */
+    pdgEmitChunkSize?: number;
     /**
      * Default branch threaded into generated AGENTS.md / CLAUDE.md so the
      * regression-compare example uses the configured branch instead of a
@@ -162,4 +209,53 @@ 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' | 'pdgMaxReachingDefEdgesPerFunction' | 'pdgMaxCdgEdgesPerFunction' | 'pdgMaxTaintFindingsPerFunction' | 'pdgMaxTaintHops' | 'pdgMaxInterprocFindings' | 'pdgMaxInterprocHops' | 'pdgMaxInterprocEdges'>;
+export declare const resolvePdgConfig: (options: PdgOptions) => RepoMeta["pdg"];
+/**
+ * Whether streaming/chunked PDG graph emit (#2202) engages this run.
+ *
+ * Streaming flushes the BasicBlock + intra-file PDG-edge layer to CSV-on-disk
+ * during the emit loop and never lands it in the in-memory graph, bounding peak
+ * RSS to O(chunk). It is sound ONLY on a full rebuild: the incremental
+ * writeback (`extractChangedSubgraph`) reads BasicBlock nodes back out of the
+ * in-memory graph, which streaming has already offloaded. `force === true` is
+ * the pre-pipeline guarantee of a full rebuild — `isIncremental` has
+ * `!force` as a necessary condition — so gating on it avoids the deliberately
+ * absent pre-pipeline incremental prediction (see the `isIncremental` note).
+ *
+ * Requires `pdg === true` (nothing to stream otherwise). Enabled by either the
+ * explicit `streamPdgEmit` option or the `GITNEXUS_STREAM_PDG_EMIT` env toggle.
+ * Memory-only — NOT part of {@link resolvePdgConfig}, so toggling it never
+ * trips `pdgModeMismatch`. Read every call (not memoized) so `vi.stubEnv`
+ * works in tests. Pure + exported for testing.
+ */
+export declare const resolveStreamPdgEmit: (options: {
+    pdg?: boolean;
+    force?: boolean;
+    streamPdgEmit?: boolean;
+}) => boolean;
+/**
+ * Resolve the streamed PDG-emit write-buffer size (#2202). Explicit option wins
+ * over `GITNEXUS_PDG_EMIT_CHUNK_SIZE`; `undefined` ⇒ the sink's
+ * `DEFAULT_PDG_EMIT_CHUNK_ROWS`. Memory-only; does not affect emitted bytes.
+ */
+export declare const resolvePdgEmitChunkSize: (options: {
+    pdgEmitChunkSize?: number;
+}) => number | 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 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

@@ -13,11 +13,18 @@ import fs from 'fs/promises';
 import { execFileSync } from 'child_process';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { resetDegradedParseCounter } from './tree-sitter/safe-parse.js';
-import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
+import { initLbug, loadGraphToLbug, getLbugStats, executeQuery, executeWithReusedStatement, closeLbug, loadCachedEmbeddings, deleteNodesForFile, deleteAllCommunitiesAndProcesses, deleteAllInterprocTaintPaths, deleteAllCallSummaries, queryImporters, loadFTSExtension, } from './lbug/lbug-adapter.js';
 import { createSearchFTSIndexes, verifySearchFTSIndexes } from './search/fts-indexes.js';
 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, DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION, DEFAULT_PDG_MAX_CDG_EDGES_PER_FUNCTION, } from './ingestion/cfg/emit.js';
+import { DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION, DEFAULT_PDG_MAX_TAINT_HOPS, } from './ingestion/taint/propagate.js';
+import { DEFAULT_MAX_INTERPROC_HOPS, DEFAULT_PDG_MAX_INTERPROC_FINDINGS, } from './ingestion/taint/interproc-solver.js';
+import { DEFAULT_PDG_MAX_INTERPROC_EDGES } from './ingestion/taint/interproc-emit.js';
+import { taintModelVersion } from './ingestion/taint/typescript-model.js';
+import { parseTruthyEnv, parsePositiveIntEnv } from './ingestion/utils/env.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 +135,123 @@ 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,
+        maxReachingDefEdgesPerFunction: options.pdgMaxReachingDefEdgesPerFunction ??
+            DEFAULT_PDG_MAX_REACHING_DEF_EDGES_PER_FUNCTION,
+        // #2085 M5: control-dependence cap. Absent on any pre-M5 (M2/M3/M4-era)
+        // stamp → the key-union pdgModeMismatch trips the first CDG-aware run
+        // over an existing `--pdg` index and forces the full writeback that
+        // materialises CDG edges for every file without `--force`.
+        maxCdgEdgesPerFunction: options.pdgMaxCdgEdgesPerFunction ?? DEFAULT_PDG_MAX_CDG_EDGES_PER_FUNCTION,
+        // #2083 M3: taint caps + model identity. The key-union comparator in
+        // pdgModeMismatch picks these up structurally — an M2-era stamp lacks
+        // all three, so the first M3 run over an M2 `--pdg` index trips a full
+        // writeback that populates TAINTED/SANITIZES rows without `--force`.
+        maxTaintFindingsPerFunction: options.pdgMaxTaintFindingsPerFunction ?? DEFAULT_PDG_MAX_TAINT_FINDINGS_PER_FUNCTION,
+        maxTaintHops: options.pdgMaxTaintHops ?? DEFAULT_PDG_MAX_TAINT_HOPS,
+        // #2084 review P1-3: cross-function caps. Absent on an M3-era stamp →
+        // pdgModeMismatch trips the first run that adds them (key-union),
+        // forcing the full writeback that re-materialises TAINT_PATH bounded.
+        maxInterprocFindings: options.pdgMaxInterprocFindings ?? DEFAULT_PDG_MAX_INTERPROC_FINDINGS,
+        maxInterprocHops: options.pdgMaxInterprocHops ?? DEFAULT_MAX_INTERPROC_HOPS,
+        maxInterprocEdges: options.pdgMaxInterprocEdges ?? DEFAULT_PDG_MAX_INTERPROC_EDGES,
+        // Built-in model digest (KTD7/R7): persisted findings must never
+        // outlive the model that produced them — ANY model-content change
+        // ships as a new digest and repopulates the taint edges.
+        taintModelVersion,
+        // #2201 review R3: reaching-defs solver identity. The SSA-sparse rewrite
+        // computes full facts for deep-loop functions the dense worklist used to
+        // truncate to empty, so an existing `--pdg` index carries stale-truncated
+        // REACHING_DEF rows. Absent on any pre-#2201 stamp → the key-union
+        // pdgModeMismatch trips on the first upgraded run and forces the full
+        // writeback that recomputes the fuller coverage (no `--force` needed).
+        // Bump this tag on any future change to which facts the solver emits.
+        reachingDefSolver: 'ssa-sparse-v1',
+        // PDG FU-C: this run records CALL_SUMMARY return-value-ascent edges.
+        // Absent on any pre-FU-C (v3) stamp → the key-union pdgModeMismatch trips
+        // the first FU-C-aware run over an existing `--pdg` index and forces the
+        // full writeback that materialises CALL_SUMMARY edges without `--force`;
+        // and `impact`'s PDG mode reads its absence to note "no return-value
+        // ascent (re-index for CALL_SUMMARY)" on a v3 index (intra slice intact).
+        hasCallSummary: true,
+    }
+    : undefined;
+/**
+ * Whether streaming/chunked PDG graph emit (#2202) engages this run.
+ *
+ * Streaming flushes the BasicBlock + intra-file PDG-edge layer to CSV-on-disk
+ * during the emit loop and never lands it in the in-memory graph, bounding peak
+ * RSS to O(chunk). It is sound ONLY on a full rebuild: the incremental
+ * writeback (`extractChangedSubgraph`) reads BasicBlock nodes back out of the
+ * in-memory graph, which streaming has already offloaded. `force === true` is
+ * the pre-pipeline guarantee of a full rebuild — `isIncremental` has
+ * `!force` as a necessary condition — so gating on it avoids the deliberately
+ * absent pre-pipeline incremental prediction (see the `isIncremental` note).
+ *
+ * Requires `pdg === true` (nothing to stream otherwise). Enabled by either the
+ * explicit `streamPdgEmit` option or the `GITNEXUS_STREAM_PDG_EMIT` env toggle.
+ * Memory-only — NOT part of {@link resolvePdgConfig}, so toggling it never
+ * trips `pdgModeMismatch`. Read every call (not memoized) so `vi.stubEnv`
+ * works in tests. Pure + exported for testing.
+ */
+export const resolveStreamPdgEmit = (options) => options.pdg === true &&
+    options.force === true &&
+    (options.streamPdgEmit === true || parseTruthyEnv(process.env.GITNEXUS_STREAM_PDG_EMIT));
+/**
+ * Resolve the streamed PDG-emit write-buffer size (#2202). Explicit option wins
+ * over `GITNEXUS_PDG_EMIT_CHUNK_SIZE`; `undefined` ⇒ the sink's
+ * `DEFAULT_PDG_EMIT_CHUNK_ROWS`. Memory-only; does not affect emitted bytes.
+ */
+export const resolvePdgEmitChunkSize = (options) => {
+    // Only honor a positive-integer explicit option; `0`/negative is NOT nullish
+    // so `?? env` would pass it through and make the sink flush every row.
+    const opt = options.pdgEmitChunkSize;
+    if (opt !== undefined && Number.isInteger(opt) && opt > 0)
+        return opt;
+    return parsePositiveIntEnv(process.env.GITNEXUS_PDG_EMIT_CHUNK_SIZE);
+};
+/**
+ * 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;
+    // Structural comparison over the KEY UNION of both resolved records — not a
+    // hand-maintained field list. Both sides come fully resolved from
+    // resolvePdgConfig, so any new emit-affecting knob added there joins the
+    // comparison automatically (M1's hand-extended comparator was the trap this
+    // closes: a knob it missed would silently strand a stale projection). It is
+    // also what makes the M1→M2 upgrade work with zero extra code: an M1-era
+    // stamp lacks maxReachingDefEdgesPerFunction, so `4000 !== undefined` trips
+    // a full writeback that populates REACHING_DEF rows without `--force`.
+    const reqRecord = requested;
+    const recRecord = recorded;
+    // INVARIANT: every value stamped by resolvePdgConfig MUST be a SCALAR (string /
+    // number / boolean). This comparison is a shallow `!==`, so an OBJECT or ARRAY
+    // value would compare by REFERENCE — two structurally-equal values from
+    // different runs would always be `!==`, tripping pdgModeMismatch on every
+    // re-analyze and forcing a needless full writeback. e.g. do NOT change
+    // `hasCallSummary: true` to a per-language object like `{ ts: true, ... }`; keep
+    // the diagnostic per-language refinement in the impact CONSUMER (see
+    // pdg-impact.ts assemblePdgImpactResult), not in this version discriminator.
+    for (const key of new Set([...Object.keys(reqRecord), ...Object.keys(recRecord)])) {
+        if (reqRecord[key] !== recRecord[key])
+            return true;
+    }
+    return false;
+};
 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 +389,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 +564,23 @@ 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,
+        pdgMaxReachingDefEdgesPerFunction: options.pdgMaxReachingDefEdgesPerFunction,
+        pdgMaxCdgEdgesPerFunction: options.pdgMaxCdgEdgesPerFunction,
+        pdgMaxTaintFindingsPerFunction: options.pdgMaxTaintFindingsPerFunction,
+        pdgMaxTaintHops: options.pdgMaxTaintHops,
+        pdgMaxInterprocFindings: options.pdgMaxInterprocFindings,
+        pdgMaxInterprocHops: options.pdgMaxInterprocHops,
+        pdgMaxInterprocEdges: options.pdgMaxInterprocEdges,
+        // Streaming/chunked PDG emit (#2202) — gated to full-rebuild runs
+        // (force === true) so the incremental writeback never reads back an
+        // offloaded BasicBlock layer. Memory-only; byte-identical output.
+        streamPdgEmit: resolveStreamPdgEmit(options),
+        pdgEmitChunkSize: resolvePdgEmitChunkSize(options),
         fetchWrappers: options.fetchWrappers,
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
@@ -465,6 +630,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) {
@@ -606,6 +784,21 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             //    from the fresh pipeline output below. Required for the
             //    "Leiden runs on the FULL graph" correctness invariant.
             await deleteAllCommunitiesAndProcesses();
+            // 2b. Drop interprocedural TAINT_PATH edges (#2084 M4 U6) when pdg is on
+            //     — their validity is a whole-program property (an A→C flow can be
+            //     invalidated by a change to an intermediate function on a third
+            //     file), so endpoint-writability extraction can't refresh them.
+            //     extractChangedSubgraph re-includes all of them from the fresh
+            //     graph (isGraphWideRelType), mirroring Community/Process.
+            if (options.pdg === true) {
+                await deleteAllInterprocTaintPaths();
+                // 2c. Drop CALL_SUMMARY edges (PDG FU-C) on an incremental `--pdg`
+                //     writeback. They are re-included from the FULL fresh graph
+                //     (isGraphWideRelType) and the callSummaries phase recomputes every
+                //     summary each run, so delete-all-then-rebuild keeps an unchanged
+                //     function's summary from being lost — same contract as TAINT_PATH.
+                await deleteAllCallSummaries();
+            }
             // 3. Extract the changed subgraph from the FULL ctx.graph and write
             //    only that. Unchanged-file rows in the DB stay untouched. Pass
             //    the SAME effectiveWriteSet so the subgraph and the deletes
@@ -619,11 +812,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         }
         else {
             // ── Full rebuild ───────────────────────────────────────────────
+            // Pass the streamed PDG-emit manifest (#2202) so the BasicBlock layer that
+            // was flushed to CSV during the emit loop is COPY'd alongside the
+            // structural CSVs. Only ever set on a full rebuild (streaming is
+            // force-gated), so the incremental branch above never carries it.
             await loadGraphToLbug(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => {
                 lbugMsgCount++;
                 const pct = Math.min(84, 60 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 24));
                 progress('lbug', pct, msg);
-            });
+            }, pipelineResult.pdgEmitManifest);
         }
         // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
         // The analyze (write) path owns building the search indexes, so it uses
@@ -846,6 +1043,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
@@ -938,6 +1141,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                     skipSkills: options.skipSkills,
                     noStats: options.noStats,
                     defaultBranch: options.defaultBranch,
+                    hasPdg: options.pdg === true,
                 });
             }
             catch {