gitnexus 1.6.10-rc.152 → 1.6.10-rc.154

package/dist/core/group/service.js

@@ -9,7 +9,10 @@ import { loadMeta } from '../../storage/repo-manager.js';
 import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
 import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
 import { getDefaultGitnexusDir, getGroupDir, listGroups, readContractRegistry } from './storage.js';
-import { syncGroup } from './sync.js';
+// `./sync.js` is imported LAZILY in `groupSync` — see the comment at its call
+// site. It statically pulls the six contract extractors and, through them, the
+// native tree-sitter binding; a static import here puts all of that on MCP
+// server startup, which never syncs.
 import { logger } from '../logger.js';
 function isStoredContract(raw) {
     if (!raw || typeof raw !== 'object')
@@ -166,6 +169,12 @@ export class GroupService {
                 return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
             throw err;
         }
+        // Lazy: `sync.js` reaches the six contract extractors and the native
+        // tree-sitter binding. `groupSync` is the ONLY consumer — the other seven
+        // group tools never need it — so deferring it here keeps that closure off
+        // MCP server startup entirely and off every non-sync group call. The CLI
+        // already does exactly this at `cli/group.ts`'s sync command.
+        const { syncGroup } = await import('./sync.js');
         const result = await syncGroup(config, {
             groupDir,
             exactOnly: Boolean(params.exactOnly),

package/dist/core/ingestion/cfg/callee-cell-format.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Wire format of the `BasicBlock.callees` / `BasicBlock.calleeIds` cells.
+ *
+ * A LEAF module on purpose: it declares two string constants and imports
+ * nothing. `cfg/emit.ts` produces those cells and `mcp/local/pdg-impact.ts`
+ * parses them, but `emit.ts` is analyze-only and drags the whole CFG closure
+ * (reaching-defs, control-dependence, post-dominators, synthetic-escape,
+ * call-site-harvest) behind it — 8 modules evaluated at every MCP server start
+ * just to read two strings, since ESM evaluates a module to import any binding
+ * from it (#2802 review). Splitting the format constants out deletes that cost
+ * rather than deferring it, which is the same bar #2802 held its own proposals
+ * to.
+ *
+ * `emit.ts` RE-EXPORTS both names, so every existing importer keeps working and
+ * the producer/consumer pair still resolves to one definition — the drift this
+ * shared constant exists to prevent stays impossible.
+ */
+/**
+ * Reserved token placed in `BasicBlock.callees` when a statement's call sites
+ * were truncated at the per-statement site cap: the recorded callee list is then
+ * INCOMPLETE, so over-cap callees are absent. `*` is not a valid identifier
+ * leaf, so it cannot collide with a real callee name. The impact bridge treats a
+ * slice containing this sentinel as "callees unknown" and keeps reach
+ * callgraph-equal (proven), rather than falsely labeling an absent-but-real
+ * callee `unproven-bridge`.
+ */
+export declare const CALLEES_TRUNCATED_SENTINEL = "*";
+/**
+ * Inner separator for the `BasicBlock.calleeIds` cell (resolved callee symbol
+ * ids). A TAB is used — NOT a space — because resolved ids embed `filePath` and
+ * C++ overload shape tags with multi-word primitive types (e.g. `unsigned char`,
+ * `long double`), so an id can legitimately contain a space; a space-joined cell
+ * then fragments on read and silently drops inter-procedural reach to that
+ * callee (#2227 tri-review). A tab cannot appear in a tree-sitter-derived id
+ * token (paths/identifiers/type tokens are tab-free) and round-trips intact
+ * through `escapeCSVField` (tab is in its preserved set) and the RFC-4180 COPY
+ * reader (every cell is quoted). Producer (`calleeIdsOfBlock`) and consumer
+ * (`splitCalleeIds`) both resolve to this single constant so they cannot drift.
+ * The sibling `callees` (leaf-name) cell stays space-joined — leaf names are
+ * bare identifiers and never contain a space.
+ */
+export declare const CALLEE_ID_SEP = "\t";

package/dist/core/ingestion/cfg/callee-cell-format.js

@@ -0,0 +1,42 @@
+/**
+ * Wire format of the `BasicBlock.callees` / `BasicBlock.calleeIds` cells.
+ *
+ * A LEAF module on purpose: it declares two string constants and imports
+ * nothing. `cfg/emit.ts` produces those cells and `mcp/local/pdg-impact.ts`
+ * parses them, but `emit.ts` is analyze-only and drags the whole CFG closure
+ * (reaching-defs, control-dependence, post-dominators, synthetic-escape,
+ * call-site-harvest) behind it — 8 modules evaluated at every MCP server start
+ * just to read two strings, since ESM evaluates a module to import any binding
+ * from it (#2802 review). Splitting the format constants out deletes that cost
+ * rather than deferring it, which is the same bar #2802 held its own proposals
+ * to.
+ *
+ * `emit.ts` RE-EXPORTS both names, so every existing importer keeps working and
+ * the producer/consumer pair still resolves to one definition — the drift this
+ * shared constant exists to prevent stays impossible.
+ */
+/**
+ * Reserved token placed in `BasicBlock.callees` when a statement's call sites
+ * were truncated at the per-statement site cap: the recorded callee list is then
+ * INCOMPLETE, so over-cap callees are absent. `*` is not a valid identifier
+ * leaf, so it cannot collide with a real callee name. The impact bridge treats a
+ * slice containing this sentinel as "callees unknown" and keeps reach
+ * callgraph-equal (proven), rather than falsely labeling an absent-but-real
+ * callee `unproven-bridge`.
+ */
+export const CALLEES_TRUNCATED_SENTINEL = '*';
+/**
+ * Inner separator for the `BasicBlock.calleeIds` cell (resolved callee symbol
+ * ids). A TAB is used — NOT a space — because resolved ids embed `filePath` and
+ * C++ overload shape tags with multi-word primitive types (e.g. `unsigned char`,
+ * `long double`), so an id can legitimately contain a space; a space-joined cell
+ * then fragments on read and silently drops inter-procedural reach to that
+ * callee (#2227 tri-review). A tab cannot appear in a tree-sitter-derived id
+ * token (paths/identifiers/type tokens are tab-free) and round-trips intact
+ * through `escapeCSVField` (tab is in its preserved set) and the RFC-4180 COPY
+ * reader (every cell is quoted). Producer (`calleeIdsOfBlock`) and consumer
+ * (`splitCalleeIds`) both resolve to this single constant so they cannot drift.
+ * The sibling `callees` (leaf-name) cell stays space-joined — leaf names are
+ * bare identifiers and never contain a space.
+ */
+export const CALLEE_ID_SEP = '\t';

package/dist/core/ingestion/cfg/emit.d.ts

@@ -22,30 +22,15 @@ import type { KnowledgeGraph } from '../../graph/types.js';
 import { type ReachingDefsSolver } from './reaching-defs.js';
 import type { BasicBlockData, BindingEntry, FunctionCfg } from './types.js';
 /**
- * Reserved token placed in `BasicBlock.callees` when a statement's call sites
- * were truncated at {@link DEFAULT_PDG_MAX_SITES_PER_STATEMENT}: the recorded
- * callee list is then INCOMPLETE, so over-cap callees are absent. `*` is not a
- * valid identifier leaf, so it cannot collide with a real callee name. The
- * impact bridge treats a slice containing this sentinel as "callees unknown" and
- * keeps reach callgraph-equal (proven), rather than falsely labeling an
- * absent-but-real callee `unproven-bridge`.
+ * Cell-format constants live in the LEAF module `callee-cell-format.ts` and are
+ * re-exported here so every existing importer keeps working. The consumer side
+ * (`mcp/local/pdg-impact.ts`) imports them from the leaf directly: importing any
+ * binding from THIS module evaluates it, and with it the whole analyze-only CFG
+ * closure — 8 modules on every MCP server start to read two strings (#2802
+ * review). Producer and consumer still resolve to one definition, so the drift
+ * these shared constants exist to prevent stays impossible.
  */
-export declare const CALLEES_TRUNCATED_SENTINEL = "*";
-/**
- * Inner separator for the `BasicBlock.calleeIds` cell (resolved callee symbol
- * ids). A TAB is used — NOT a space — because resolved ids embed `filePath` and
- * C++ overload shape tags with multi-word primitive types (e.g. `unsigned char`,
- * `long double`), so an id can legitimately contain a space; a space-joined cell
- * then fragments on read and silently drops inter-procedural reach to that
- * callee (#2227 tri-review). A tab cannot appear in a tree-sitter-derived id
- * token (paths/identifiers/type tokens are tab-free) and round-trips intact
- * through `escapeCSVField` (tab is in its preserved set) and the RFC-4180 COPY
- * reader (every cell is quoted). Producer ({@link calleeIdsOfBlock}) and
- * consumer (`splitCalleeIds`) import this single constant so they cannot drift.
- * The sibling `callees` (leaf-name) cell stays space-joined — leaf names are
- * bare identifiers and never contain a space.
- */
-export declare const CALLEE_ID_SEP = "\t";
+export { CALLEES_TRUNCATED_SENTINEL, CALLEE_ID_SEP } from './callee-cell-format.js';
 /**
  * Default per-function CFG edge cap. A pathological generated function could
  * otherwise emit an unbounded edge set; the cap bounds graph growth and is

package/dist/core/ingestion/cfg/emit.js

@@ -6,31 +6,17 @@ import { augmentForPostDom } from './synthetic-escape.js';
 import { DEFAULT_PDG_MAX_SITES_PER_STATEMENT } from './visitors/call-site-harvest.js';
 import { calleeIdPosKey } from '../scope-resolution/graph-bridge/callee-id-sink.js';
 import { encodeReachingDefReasonPairs } from './reaching-def-reason-codec.js';
+import { CALLEES_TRUNCATED_SENTINEL, CALLEE_ID_SEP } from './callee-cell-format.js';
 /**
- * Reserved token placed in `BasicBlock.callees` when a statement's call sites
- * were truncated at {@link DEFAULT_PDG_MAX_SITES_PER_STATEMENT}: the recorded
- * callee list is then INCOMPLETE, so over-cap callees are absent. `*` is not a
- * valid identifier leaf, so it cannot collide with a real callee name. The
- * impact bridge treats a slice containing this sentinel as "callees unknown" and
- * keeps reach callgraph-equal (proven), rather than falsely labeling an
- * absent-but-real callee `unproven-bridge`.
+ * Cell-format constants live in the LEAF module `callee-cell-format.ts` and are
+ * re-exported here so every existing importer keeps working. The consumer side
+ * (`mcp/local/pdg-impact.ts`) imports them from the leaf directly: importing any
+ * binding from THIS module evaluates it, and with it the whole analyze-only CFG
+ * closure — 8 modules on every MCP server start to read two strings (#2802
+ * review). Producer and consumer still resolve to one definition, so the drift
+ * these shared constants exist to prevent stays impossible.
  */
-export const CALLEES_TRUNCATED_SENTINEL = '*';
-/**
- * Inner separator for the `BasicBlock.calleeIds` cell (resolved callee symbol
- * ids). A TAB is used — NOT a space — because resolved ids embed `filePath` and
- * C++ overload shape tags with multi-word primitive types (e.g. `unsigned char`,
- * `long double`), so an id can legitimately contain a space; a space-joined cell
- * then fragments on read and silently drops inter-procedural reach to that
- * callee (#2227 tri-review). A tab cannot appear in a tree-sitter-derived id
- * token (paths/identifiers/type tokens are tab-free) and round-trips intact
- * through `escapeCSVField` (tab is in its preserved set) and the RFC-4180 COPY
- * reader (every cell is quoted). Producer ({@link calleeIdsOfBlock}) and
- * consumer (`splitCalleeIds`) import this single constant so they cannot drift.
- * The sibling `callees` (leaf-name) cell stays space-joined — leaf names are
- * bare identifiers and never contain a space.
- */
-export const CALLEE_ID_SEP = '\t';
+export { CALLEES_TRUNCATED_SENTINEL, CALLEE_ID_SEP } from './callee-cell-format.js';
 /**
  * Default per-function CFG edge cap. A pathological generated function could
  * otherwise emit an unbounded edge set; the cap bounds graph growth and is

package/dist/core/lbug/lbug-adapter.js

@@ -10,6 +10,12 @@ import { escapeCypherString } from './cypher-escape.js';
 import { withConnLock } from './conn-lock.js';
 import { isWalDriverActive } from './wal-driver-state.js';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, CREATE_VECTOR_INDEX_QUERY, STALE_HASH_SENTINEL, } from './schema.js';
+// Analyze-only, but reached from MCP startup via `pool-adapter.js`. #2802
+// proposed lazy-importing it; rejected — `core/search/bm25-index.ts` statically
+// imports `normalizeFtsText` from `csv-generator.js`, and `local-backend.ts`
+// dynamically imports bm25-index on the FTS query path, so deferring here
+// relocates the startup cost to first query rather than removing it. The
+// measured figures live in #2802; they were environment-bound, this is not.
 import { streamAllCSVsToDisk } from './csv-generator.js';
 import { getNodeLabel as deriveNodeLabel } from './rel-pair-routing.js';
 import { EMBEDDABLE_LABELS } from '../embeddings/types.js';

package/dist/core/run-analyze.js

@@ -382,8 +382,9 @@ export const pdgModeMismatch = (recorded, options) => {
     // 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.
+    // any diagnostic refinement in the impact CONSUMER (see pdg-impact.ts
+    // assemblePdgImpactResult, which reports empty ascent from the persisted
+    // CALL_SUMMARY data), not in this version discriminator.
     for (const key of new Set([...Object.keys(reqRecord), ...Object.keys(recRecord)])) {
         if (reqRecord[key] !== recRecord[key])
             return true;

package/dist/mcp/local/pdg-impact.d.ts

@@ -19,15 +19,10 @@ import { loadMeta } from '../../storage/repo-manager.js';
  */
 export declare function fnLineOf(id: string): number;
 /**
- * Split a tab-joined ({@link CALLEE_ID_SEP}) `BasicBlock.calleeIds` cell into its resolved callee
- * symbol ids, dropping the truncation sentinel (a capped block carries the
- * sentinel to mark an incomplete call-site list; it is NOT a resolved symbol id
- * and must never enter a `has(realId)` set). Empty/whitespace cells yield no ids.
- *
- * Extracted here (U1) so the two callers — `LocalBackend.calleeIdsOfBlocks` (the
- * statement-precise bridge key) and the inter-procedural descent's
- * `calleeIdsFromCalleeRows` — cannot diverge on the split-and-drop-sentinel
- * logic. Both consume rows of `BasicBlock.calleeIds`; this is the single source.
+ * Ids-only view of {@link parseCalleeIdsCell}. Exported (U1) so the two callers —
+ * `LocalBackend.calleeIdsOfBlocks` (the statement-precise bridge key) and the
+ * inter-procedural descent — cannot diverge on the split-and-drop-sentinel logic.
+ * Both consume rows of `BasicBlock.calleeIds`; this is the single source.
  */
 export declare function splitCalleeIds(raw: unknown): string[];
 /**
@@ -76,6 +71,127 @@ export interface PdgImpactParityFields {
     affected_modules: unknown[];
 }
 export type PdgImpactEvidence = 'local-dependence' | 'owner-projection' | 'callgraph-bridge' | 'unproven-bridge' | 'degraded';
+/**
+ * WHY the callee set the descent EXAMINED for `CALL_SUMMARY` return-flows is a
+ * strict PREFIX of the slice's real callee list. A STRUCTURED vocabulary, in the
+ * spirit of `truncatedByReasons: readonly ('depth'|'limit')[]` — the codes are the
+ * contract, the English phrasing is a rendering of them
+ * ({@link ASCENT_INCOMPLETE_PHRASE}). A caller branches on the code; only the note
+ * reads the phrase, so a rewording can never break a consumer.
+ *  - `'traversal-truncated'` — the traversal stopped at its depth/size budget, so
+ *    a callee that DOES carry a return-flow can sit in a hop never reached (the
+ *    same fact the result's `truncated`/`truncatedByReasons` report, read at the
+ *    ascent's granularity).
+ *  - `'callee-list-capped'` — a slice block's `calleeIds` cell was capped at emit;
+ *    `parseCalleeIdsCell` strips the sentinel, so the dropped ids are invisible to
+ *    BOTH the summary scan and the counters.
+ *  - `'callee-ids-unrecorded'` — a slice block records CALL SITES (a non-empty
+ *    `callees` name cell) but NO resolved callee ids. An empty `calleeIds` cell
+ *    carries no sentinel, so those call sites are invisible to the summary scan
+ *    without raising `'callee-list-capped'`. Distinct from the cap: nothing was
+ *    dropped at emit — the ids were never recorded.
+ *
+ *    THREE producer paths yield it, and the consumer cannot tell them apart —
+ *    do not read this code as naming any one of them (`cfg/emit.ts`,
+ *    `calleeIdsOfBlock`):
+ *      1. the file's resolved-id map is absent entirely (`fileMap === undefined`);
+ *      2. a call site has no position anchor;
+ *      3. a call site's position IS in the map but did not RESOLVE.
+ *    (3) is the ordinary one — it is exactly the receiver-resolution gaps this
+ *    repo pins (e.g. #2807's inference-typed field receivers, where `calleeIds`
+ *    empties while `calleesOfBlock` still writes the leaf names). So on a real
+ *    index this fires broadly and is driven by resolution quality, NOT by a
+ *    missing `--pdg` layer: "re-run analyze --pdg" is the wrong remedy for it,
+ *    and `examinedComplete: false` here is a statement about how much of the
+ *    call graph resolved, not about the traversal giving up.
+ *
+ *    Consequence worth knowing before branching on it: because (3) is common,
+ *    `examinedComplete: true` is the strong, rare signal and `false` is close to
+ *    the default on a large repo. Distinguishing the three needs a marker at
+ *    emit time, which would move the persisted cell format — deliberately out of
+ *    scope here, and tracked separately.
+ */
+export type PdgAscentIncompleteReason = 'traversal-truncated' | 'callee-list-capped' | 'callee-ids-unrecorded';
+/**
+ * Return-value-ascent coverage, published on {@link PdgImpactEvidenceSummary} so a
+ * consumer can answer "was the ascent complete, and if not why" WITHOUT parsing
+ * the result `note`. This is MCP output read by agents: the same four facts are
+ * also narrated in the note (see {@link AscentCoverage} for the canonical
+ * rationale, and `assemblePdgImpactResult` for the single site that renders both
+ * from one computation), and the prose is the human surface, not the contract.
+ *
+ * Present iff the inter-procedural descent RAN (a downstream slice that reached
+ * the assembly path). Absent ⇒ nothing was scanned — deliberately not a zeroed
+ * object, which would read as "we looked and found nothing".
+ */
+export interface PdgAscentCoverage {
+    /**
+     * Count of DISTINCT callee ids scanned for a `CALL_SUMMARY` — a distinct-callee
+     * tally, NOT a call-site count: two slice blocks invoking the same callee
+     * contribute 1, and one block invoking it twice also contributes 1. That is the
+     * correct population for the claim `returnFlowFound` makes, because a
+     * `CALL_SUMMARY` is a property of the CALLEE, not of the call site.
+     *
+     * Callee granularity, NOT "callees resolved to a body": a cell's ids that
+     * `resolveCalleeSpans` never matches (out-of-repo target, interface method, the
+     * `Class:` id a `new` expression contributes) are scanned all the same. See
+     * {@link AscentCoverage} POPULATION. (The field NAME is historical — the
+     * published shape is versioned by `pdgResultVersion`, so it is kept while the
+     * prose on both surfaces says "distinct callees".)
+     */
+    referencesScanned: number;
+    /**
+     * Whether ANY scanned callee carried a DECODED non-empty return-flow — i.e.
+     * whether the ascent FIRED anywhere in this slice. `false` with
+     * `referencesScanned > 0` is the structural counterpart of the note's
+     * "no return-value ascent in this slice" sentence.
+     */
+    returnFlowFound: boolean;
+    /**
+     * Scanned callees whose `CALL_SUMMARY` the codec could not decode (version skew
+     * / corruption / NULL reason). Each withholds the ascent exactly like an empty
+     * summary, so a non-zero count means `returnFlowFound: false` is NOT a statement
+     * about what the persisted summaries record — remedy: re-run `analyze --pdg`.
+     */
+    undecodableSummaryCount: number;
+    /**
+     * Whether {@link referencesScanned} ranges over EVERY callee the descent's slice
+     * blocks recorded a resolved id for. `false` ⇒ the counters above range over a
+     * strict subset, so `returnFlowFound: false` is not a whole-slice claim. Reasons
+     * in {@link incompleteReasons}.
+     *
+     * SCOPE — the population is "callees the INDEX recorded resolved ids for on the
+     * blocks the DESCENT visited", never "every call the source text makes". Two
+     * gaps are named structurally rather than assumed away: a block whose ids the
+     * emitter capped raises `'callee-list-capped'`, and a block that records call
+     * sites but no ids at all raises `'callee-ids-unrecorded'`. What is NOT modelled
+     * (and cannot be, from the persisted graph) is a call the CFG never materialised
+     * as a call site — so `true` means "nothing the index recorded was skipped", not
+     * "the program makes no other calls".
+     */
+    examinedComplete: boolean;
+    /** Empty iff {@link examinedComplete}; otherwise every mechanism that fired. */
+    incompleteReasons: readonly PdgAscentIncompleteReason[];
+    /**
+     * Whether the index carries the `CALL_SUMMARY` layer at all. `false` ⇒ a PRE-FU-C
+     * (v3) `--pdg` index, where the scan COULD NOT have found a return-flow — without
+     * this a consumer would read `returnFlowFound: false` as "these callees record no
+     * return-flow" when the truth is "the layer that records it does not exist here"
+     * (the note distinguishes the two in prose; this keeps the structured surface
+     * from being false-safe). Remedy: re-run `analyze --pdg`.
+     *
+     * READING IT WITH THE OTHER FIELDS. `{referencesScanned: N>0, returnFlowFound:
+     * false, callSummaryLayerPresent: false}` is SELF-CONSISTENT and expected on a
+     * v3 index, not a contradiction: the scan really did run over N callees and
+     * really did find nothing, because there was no layer in which a return-flow
+     * could be recorded. Read this field FIRST — while it is `false`,
+     * `returnFlowFound` and `undecodableSummaryCount` say nothing about the callees
+     * themselves and must not be used to conclude "no callee returns a
+     * slice-dependent value". `examinedComplete` is orthogonal to all of this: it
+     * reports coverage of the callee POPULATION, never the presence of the layer.
+     */
+    callSummaryLayerPresent: boolean;
+}
 export interface PdgImpactEvidenceSummary {
     statements?: PdgImpactEvidence;
     localSymbols?: PdgImpactEvidence;
@@ -84,6 +200,12 @@ export interface PdgImpactEvidenceSummary {
     unresolvedBlockCount?: number;
     ambiguousProjectionCount?: number;
     interproceduralEvidenceCounts?: Partial<Record<PdgImpactEvidence, number>>;
+    /**
+     * Return-value-ascent coverage — the same "counts + classification" kind as the
+     * three counters above, scoped to the U-C4 ascent. Optional because the descent
+     * does not run for every slice; see {@link PdgAscentCoverage}.
+     */
+    ascent?: PdgAscentCoverage;
 }
 export interface PdgInterproceduralImpact {
     engine: 'symbol-graph';

package/dist/mcp/local/pdg-impact.js

@@ -8,12 +8,15 @@
 import path from 'path';
 import { loadMeta } from '../../storage/repo-manager.js';
 import { IMPACT_MAX_DEPTH, PDG_QUERY_DEFAULT_LIMIT, PDG_QUERY_MAX_LIMIT } from '../tools.js';
-import { CALLEES_TRUNCATED_SENTINEL, CALLEE_ID_SEP } from '../../core/ingestion/cfg/emit.js';
+// Imported from the LEAF `callee-cell-format.js`, NOT from `cfg/emit.js` which
+// re-exports them: ESM evaluates a module to import any binding from it, and
+// `emit.ts` drags the analyze-only CFG closure (reaching-defs, control-
+// dependence, post-dominators, synthetic-escape, call-site-harvest) with it —
+// 8 modules on every MCP server start, to read two strings (#2802 review).
+import { CALLEES_TRUNCATED_SENTINEL, CALLEE_ID_SEP, } from '../../core/ingestion/cfg/callee-cell-format.js';
 import { toDisplayLine } from './line-display.js';
 import { decodeCallSummary } from '../../core/ingestion/taint/call-summary-codec.js';
 import { decodeReachingDefReason } from '../../core/ingestion/cfg/reaching-def-reason-codec.js';
-import { getProviderForFile } from '../../core/ingestion/languages/index.js';
-import { SupportedLanguages } from '../../_shared/index.js';
 /**
  * Parse the `<fnLine>` segment out of a `BasicBlock` id (1-based function start
  * line). The id template is
@@ -60,26 +63,40 @@ const INTERPROC_DEPTH_BUDGET = 3;
  */
 const INTERPROC_NODE_BUDGET = 5000;
 /**
- * Split a tab-joined ({@link CALLEE_ID_SEP}) `BasicBlock.calleeIds` cell into its resolved callee
- * symbol ids, dropping the truncation sentinel (a capped block carries the
- * sentinel to mark an incomplete call-site list; it is NOT a resolved symbol id
- * and must never enter a `has(realId)` set). Empty/whitespace cells yield no ids.
+ * Parse a tab-joined ({@link CALLEE_ID_SEP}) `BasicBlock.calleeIds` cell in ONE
+ * pass into its resolved callee symbol ids plus whether the cell was CAPPED at
+ * emit. The truncation sentinel is NOT a resolved symbol id and must never enter
+ * a `has(realId)` set, so it is dropped from `ids` — which is exactly why
+ * `truncated` has to come back alongside them: without it a capped block is
+ * indistinguishable from a complete one and the dropped callees are invisible to
+ * every consumer that only reads `ids` (they reach neither the `CALL_SUMMARY`
+ * scan nor the ascent counters). Empty/whitespace cells yield no ids.
  *
- * Extracted here (U1) so the two callers — `LocalBackend.calleeIdsOfBlocks` (the
- * statement-precise bridge key) and the inter-procedural descent's
- * `calleeIdsFromCalleeRows` — cannot diverge on the split-and-drop-sentinel
- * logic. Both consume rows of `BasicBlock.calleeIds`; this is the single source.
+ * The callgraph bridge already treats a capped block as callee-INCOMPLETE (see
+ * `classifyPdgBridgeEvidence`); this is the same fact, read at the descent side.
  */
-export function splitCalleeIds(raw) {
-    const out = [];
+function parseCalleeIdsCell(raw) {
+    const ids = [];
+    let truncated = false;
     // Split on the SHARED CALLEE_ID_SEP (tab) — ids embed file paths / multi-word
     // C++ type tokens that can contain a space, so a space split would fragment
     // them. Producer (calleeIdsOfBlock) joins with the same constant.
     for (const id of String(raw ?? '').split(CALLEE_ID_SEP)) {
-        if (id && id !== CALLEES_TRUNCATED_SENTINEL)
-            out.push(id);
+        if (id === CALLEES_TRUNCATED_SENTINEL)
+            truncated = true;
+        else if (id)
+            ids.push(id);
     }
-    return out;
+    return { ids, truncated };
+}
+/**
+ * Ids-only view of {@link parseCalleeIdsCell}. Exported (U1) so the two callers —
+ * `LocalBackend.calleeIdsOfBlocks` (the statement-precise bridge key) and the
+ * inter-procedural descent — cannot diverge on the split-and-drop-sentinel logic.
+ * Both consume rows of `BasicBlock.calleeIds`; this is the single source.
+ */
+export function splitCalleeIds(raw) {
+    return parseCalleeIdsCell(raw).ids;
 }
 /**
  * Contract version of the mode:'pdg' impact result shape. A stable discriminator
@@ -474,6 +491,56 @@ export function makePdgLayerDegradedResult(input) {
         ...emptyPdgParityFields(),
     };
 }
+/**
+ * Render table for {@link PdgAscentIncompleteReason} — the ONLY place a code
+ * becomes English. Keeping the mapping here (rather than building sentences at
+ * the point the mechanism is detected) is what lets the published vocabulary and
+ * the note's wording move independently: a reworded phrase is invisible to every
+ * consumer branching on the code, and a new code cannot silently change the
+ * joiner the existing sentence uses.
+ */
+const ASCENT_INCOMPLETE_PHRASE = {
+    'traversal-truncated': 'the traversal stopped at its depth/size budget',
+    'callee-list-capped': "a slice block's call-site list was capped at emit",
+    'callee-ids-unrecorded': 'a slice block records call sites but no resolved callee ids',
+};
+/**
+ * The ONE place {@link AscentCoverage} plus the result-level truncation flag
+ * become the published {@link PdgAscentIncompleteReason} codes. Extracted so the
+ * two exits that publish coverage — `assemblePdgImpactResult` (the slice result,
+ * which also renders the codes into the note) and `runImpactPDG`'s empty-slice
+ * return — cannot classify the same descent differently.
+ *
+ * Emission order is the array order below and is part of what the note renders,
+ * so a new code appends rather than inserts.
+ */
+function ascentIncompleteReasonsOf(input) {
+    const reasons = [];
+    if (input.truncated)
+        reasons.push('traversal-truncated');
+    if (input.coverage?.listTruncated === true)
+        reasons.push('callee-list-capped');
+    if (input.coverage?.idlessCallSites === true)
+        reasons.push('callee-ids-unrecorded');
+    return reasons;
+}
+/**
+ * Project the descent's {@link AscentCoverage} onto the published
+ * {@link PdgAscentCoverage}. Shared by both exits that publish `pdgEvidence.ascent`
+ * so the contract sentence "present iff the inter-procedural descent ran" holds on
+ * BOTH — a descent that ran and scanned callees must not go unreported merely
+ * because the slice happened to reach no DISTINCT downstream block.
+ */
+function publishedAscentCoverage(input) {
+    return {
+        referencesScanned: input.coverage.references,
+        returnFlowFound: input.coverage.anyReturnFlow,
+        undecodableSummaryCount: input.coverage.undecodable,
+        examinedComplete: input.incompleteReasons.length === 0,
+        incompleteReasons: input.incompleteReasons,
+        callSummaryLayerPresent: input.callSummaryAvailable,
+    };
+}
 /**
  * Assemble the consumer-safe PDG impact result (U4 / KTD8 parity matrix).
  *
@@ -537,6 +604,20 @@ function assemblePdgImpactResult(input) {
     const impactedCount = resolvedUids.size;
     const byDepth = items.length > 0 ? { 1: items } : {};
     const byDepthCounts = { 1: items.length };
+    // ── Ascent coverage: ONE computation, TWO surfaces ─────────────────────────
+    // The empty-ascent sentence quantifies UNIVERSALLY over the callees the descent
+    // actually EXAMINED, and three mechanisms can make that set a strict
+    // subset of the slice's real callee list (rationale: AscentCoverage
+    // INCOMPLETENESS, vocabulary: PdgAscentIncompleteReason). Classified ONCE by the
+    // shared `ascentIncompleteReasonsOf` and consumed twice — by `pdgEvidence.ascent`
+    // (structured, the contract) and by the note's qualifier clause (prose, rendered
+    // through ASCENT_INCOMPLETE_PHRASE). Deriving both from one array is what stops
+    // an agent branching on the codes and a human reading the note from ever
+    // disagreeing.
+    const ascentIncompleteReasons = ascentIncompleteReasonsOf({
+        truncated: input.truncated,
+        coverage: input.ascentCoverage,
+    });
     const noteParts = statementMode
         ? [
             `mode:'pdg' — intra-procedural slice from line ${input.criterionLine} of ` +
@@ -579,19 +660,57 @@ function assemblePdgImpactResult(input) {
                 `CALL_SUMMARY edges and enable it.`);
         }
         else if (input.callSummaryAvailable === true) {
-            // The CALL_SUMMARY layer is present, but return-value ascent is populated
-            // ONLY for TypeScript/JavaScript today (the formal-index it needs is set
-            // solely by the TS/JS harvester). For a criterion in any other language the
-            // ascent is structurally empty, so say so rather than letting the omission
-            // read as "ascent ran and found nothing". Sound — never claims ascent fired.
-            // Language is derived HERE in mcp/local, which may name languages; the
-            // shared core/ingestion pipeline must not.
-            const lang = getProviderForFile(target.filePath)?.id;
-            const ascentLanguage = lang === SupportedLanguages.TypeScript || lang === SupportedLanguages.JavaScript;
-            if (!ascentLanguage) {
-                noteParts.push(`return-value ascent is currently TypeScript/JavaScript-only (only the TS/JS harvester ` +
-                    `records the formal-index it needs), so a caller statement depending on a non-TS/JS ` +
-                    `callee's RETURN value is not in the slice. Descent and the intra slice are unaffected.`);
+            // The CALL_SUMMARY layer is present, but that only means the index CAN
+            // carry return-flow summaries — not that the callees in THIS slice have
+            // one. When none of them does, the ascent is structurally empty and the
+            // note says so, rather than letting the omission read as "ascent ran and
+            // found nothing". Sound — never claims the ascent fired. Keyed on the
+            // OBSERVED summaries, never on the criterion's language (#2802) — see
+            // {@link AscentCoverage} for why, and for the population the sentence below
+            // quantifies over: DISTINCT CALLEES (a `Set` of callee ids — two call sites
+            // to the same callee count once), NOT callees resolved to a body. Hence the
+            // "distinct callee(s)" wording; a call-SITE count would over-state the set.
+            const coverage = input.ascentCoverage;
+            const references = coverage?.references ?? 0;
+            const undecodable = coverage?.undecodable ?? 0;
+            // When the examined set is a strict prefix (the codes computed once above)
+            // the claim is qualified: the note may describe what was examined, never
+            // assert a property of the whole slice the traversal did not establish. The
+            // codes are mapped to phrases HERE — the note is a rendering of the same
+            // vocabulary `pdgEvidence.ascent.incompleteReasons` publishes.
+            const examinedIncomplete = ascentIncompleteReasons.length > 0;
+            const incompleteClause = examinedIncomplete
+                ? ` (${ascentIncompleteReasons
+                    .map((reason) => ASCENT_INCOMPLETE_PHRASE[reason])
+                    .join(' and ')}, so callees past the examined set were not checked)`
+                : '';
+            if (references > 0 && coverage?.anyReturnFlow !== true) {
+                // ONE head for both arms — a shared gate and a shared opening sentence, so
+                // the two cannot drift on wording or pluralization. When at least one
+                // summary could not be DECODED the note must not assert what the persisted
+                // summaries record: an undecodable `reason` may well encode a return-flow
+                // this reader cannot unpack (`decodeCallSummary` never throws, so a
+                // version-skewed / corrupt / NULL reason is otherwise indistinguishable
+                // from a cleanly-decoded empty one). The ascent is withheld either way;
+                // only the tail that explains it changes.
+                noteParts.push(`no return-value ascent in this slice: none of the ${references} distinct ` +
+                    `${references === 1 ? 'callee carries' : 'callees carry'} a ` +
+                    `${undecodable > 0 ? 'decodable ' : ''}CALL_SUMMARY return-flow${incompleteClause}` +
+                    (undecodable > 0
+                        ? `, and ${undecodable} callee ` +
+                            `${undecodable === 1 ? 'summary' : 'summaries'} could not be decoded (version ` +
+                            `skew or corruption) — re-run gitnexus analyze --pdg to rebuild them. A caller ` +
+                            `statement depending on a callee's RETURN value is not in the slice; descent and ` +
+                            `the intra slice are unaffected.`
+                        : `. So a caller statement depending on a callee's RETURN value is ` +
+                            `not in the slice. ` +
+                            (examinedIncomplete
+                                ? `Every summary examined decoded, so this is a property of those summaries, not `
+                                : `Every summary in this slice decoded, so this is a property of the persisted ` +
+                                    `summaries, not `) +
+                            `of the criterion's language — a callee whose producer records no formal index and ` +
+                            `one with genuinely no return-flow are indistinguishable here. Descent and the ` +
+                            `intra slice are unaffected.`));
             }
         }
     }
@@ -625,6 +744,28 @@ function assemblePdgImpactResult(input) {
             localSymbolCount: impactedCount,
             unresolvedBlockCount: unresolvedCount,
             ambiguousProjectionCount: ambiguousCount,
+            // Structured ascent coverage — the note's facts, published so a caller never
+            // has to regex prose to learn whether the ascent was complete. Emitted iff
+            // the DESCENT RAN (`ascentCoverage` present), which is exactly the contract
+            // sentence on {@link PdgAscentCoverage}: absent ⇒ nothing was scanned because
+            // the descent never ran (an upstream slice), present ⇒ it ran and these are
+            // its counts.
+            //
+            // A zeroed-but-PRESENT record is therefore a real, honest reading — "the
+            // descent ran and the slice's blocks recorded no callee ids to scan" — not a
+            // placeholder. What used to make that reading unsafe was a block carrying
+            // call sites the index left id-less, which vanished from the population with
+            // no signal; that case now raises `'callee-ids-unrecorded'`, so a zero here
+            // with `examinedComplete: true` really does mean there was nothing to scan.
+            ...(input.ascentCoverage
+                ? {
+                    ascent: publishedAscentCoverage({
+                        coverage: input.ascentCoverage,
+                        incompleteReasons: ascentIncompleteReasons,
+                        callSummaryAvailable: input.callSummaryAvailable === true,
+                    }),
+                }
+                : {}),
         },
         // Statement-level slice: the dependent source statements (line + text) the
         // change reaches. This is the primary useful output of statement mode; the
@@ -936,66 +1077,88 @@ async function bfsReachableBlocks(input) {
     return { reachable, depthReached, truncatedByDepth, truncatedByLimit };
 }
 /**
- * Gather the resolved callee symbol ids invoked across a set of slice blocks
- * (`BasicBlock.calleeIds`). Reuses the SHARED `splitCalleeIds` so the descent
- * cannot diverge from `LocalBackend.calleeIdsOfBlocks` on the split/drop-sentinel
- * logic. A pre-namespace-v4 index (no `calleeIds` column → empty cells) yields no
- * ids, so the descent degrades cleanly to intra-only (no inter-procedural hop).
- */
-async function calleeIdsFromBlocks(lbugPath, blockIds, exec) {
-    const ids = new Set();
-    for (const { calleeIds } of await calleeIdsByBlock(lbugPath, blockIds, exec)) {
-        for (const id of calleeIds)
-            ids.add(id);
-    }
-    return ids;
-}
-/**
- * Per-block variant of {@link calleeIdsFromBlocks}: keep the CALL block → its
- * `calleeIds` mapping rather than flattening it. The return-value ascent (U-C4)
- * needs this association — it re-seeds the caller's intra closure FROM the
- * specific call block whose callee's `CALL_SUMMARY` licenses the ascent, so the
- * flattened id-only set is insufficient. Reuses the SHARED `splitCalleeIds` so
- * the split/drop-sentinel logic cannot diverge from the flattening caller. A
- * block with no callee ids (empty/whitespace cell, or a pre-v4 index with no
- * `calleeIds` column) yields an empty `calleeIds` — skipped by the consumer.
+ * Gather the resolved callee ids (`BasicBlock.calleeIds`) invoked across a set of
+ * slice blocks, keeping the CALL block → callees association rather than
+ * flattening it: the return-value ascent (U-C4) re-seeds the caller's intra
+ * closure FROM the specific call block whose callee's `CALL_SUMMARY` licenses the
+ * ascent, so a flat id set is insufficient. Reuses the SHARED
+ * {@link parseCalleeIdsCell} so the split/drop-sentinel logic cannot diverge from
+ * `LocalBackend.calleeIdsOfBlocks`. A block with no callee ids (empty/whitespace
+ * cell, or a pre-namespace-v4 index with no `calleeIds` column) yields an empty
+ * `calleeIds` — skipped by the consumer, so such an index degrades cleanly to
+ * intra-only (no inter-procedural hop).
+ *
+ * `calleeListTruncated` reports whether ANY of the queried blocks carried the
+ * emit-time cap sentinel. It is read from the RAW cell, so a block whose entire
+ * list was capped away (sentinel only ⇒ no ids ⇒ not emitted as a `BlockCallees`
+ * row) still raises it.
+ *
+ * `idlessCallSites` is the OTHER way a block's call sites leave the population
+ * unannounced: `calleeIdsOfBlock` emits an EMPTY `calleeIds` cell for a whole file
+ * whose resolved-id map is absent, and an empty cell carries no sentinel, so the
+ * cap flag cannot see it. The sibling `callees` (leaf NAMES) cell is read purely
+ * to tell that case apart from a block that genuinely calls nothing — names
+ * present + ids absent means the index recorded call sites it could not resolve.
+ * The name cell is never used for the descent itself (the resolved id is the sound
+ * key); it only keeps the coverage claim honest.
  */
 async function calleeIdsByBlock(lbugPath, blockIds, exec) {
     if (blockIds.length === 0)
-        return [];
-    const rows = await exec(lbugPath, `MATCH (b:BasicBlock) WHERE b.id IN $ids RETURN b.id AS id, b.calleeIds AS calleeIds`, { ids: blockIds });
+        return { blocks: [], calleeListTruncated: false, idlessCallSites: false };
+    const rows = await exec(lbugPath, `MATCH (b:BasicBlock) WHERE b.id IN $ids
+       RETURN b.id AS id, b.calleeIds AS calleeIds, b.callees AS callees`, { ids: blockIds });
     const out = [];
+    let calleeListTruncated = false;
+    let idlessCallSites = false;
     // Narrow the awaited rows ONCE at the boundary to a typed record shape; read
     // the aliased cells via bracket access — no per-field `as any`.
     for (const r of rows) {
         const blockId = String(r['id'] ?? '');
         if (!blockId)
             continue;
-        const calleeIds = splitCalleeIds(r['calleeIds']);
+        // ONE pass over the cell classifies BOTH facts — a second full split just to
+        // re-test the sentinel doubled the per-row parse cost.
+        const { ids: calleeIds, truncated } = parseCalleeIdsCell(r['calleeIds']);
+        if (truncated)
+            calleeListTruncated = true;
+        // Ids absent while NAMES are present ⇒ recorded call sites with no resolved
+        // id. Gated on `!truncated` so a capped-to-nothing cell keeps reporting the
+        // cap (the more specific mechanism) rather than both.
+        // `!idlessCallSites` first: the flag is sticky, so once it is set the string
+        // allocation below is pure waste on every remaining row of every later hop.
+        if (!idlessCallSites &&
+            calleeIds.length === 0 &&
+            !truncated &&
+            String(r['callees'] ?? '').trim().length > 0) {
+            idlessCallSites = true;
+        }
         if (calleeIds.length > 0)
             out.push({ blockId, calleeIds });
     }
-    return out;
+    return { blocks: out, calleeListTruncated, idlessCallSites };
 }
 /**
- * Of a set of resolved callee symbol ids, which ones have a persisted
- * `CALL_SUMMARY` self-loop edge recording a NON-EMPTY return-value ascent
- * (≥1 formal parameter flows to the callee's return). This is the FU-C consumer
- * side of the producer's per-callee summary (see `call-summary-codec.ts`).
+ * Scan the persisted `CALL_SUMMARY` self-loops of a set of resolved callee
+ * symbol ids. This is the FU-C consumer side of the producer's per-callee
+ * summary (see `call-summary-codec.ts`).
  *
  * The summary is a self-loop on the Function/Method/Constructor node:
  * `(c)-[r:CodeRelation {type:'CALL_SUMMARY'}]->(c) WHERE c.id IN $ids`. The
  * `reason` carries the param→return bitset; `decodeCallSummary` unpacks it and
- * NEVER throws — a malformed / absent / empty (`r:0`) summary yields NO entry
- * (the sound default: never claim a false return-flow). A PRE-FU-C (v3) `--pdg`
- * index has NO `CALL_SUMMARY` edges, so this returns the empty set and the
- * ascent is a clean no-op (the intra slice is unchanged — the documented
- * "re-index for CALL_SUMMARY" degradation).
+ * NEVER throws. Three outcomes, per {@link CalleeReturnFlowScan}: a non-empty
+ * decoded return-flow, a cleanly-decoded EMPTY (`r:0`) summary, and an
+ * UNDECODABLE reason. Only the first licenses an ascent — the other two yield no
+ * ascent (the sound default: never claim a false return-flow) but are reported
+ * separately so the note never states a fact about summaries it could not read.
+ * A PRE-FU-C (v3) `--pdg` index has NO `CALL_SUMMARY` edges, so both sets come
+ * back empty and the ascent is a clean no-op (the intra slice is unchanged — the
+ * documented "re-index for CALL_SUMMARY" degradation).
  */
 async function calleesWithReturnFlow(lbugPath, calleeIds, exec) {
-    const out = new Set();
+    const returnFlowing = new Set();
+    const undecodable = new Set();
     if (calleeIds.length === 0)
-        return out;
+        return { returnFlowing, undecodable };
     const rows = await exec(lbugPath, `MATCH (c)-[r:CodeRelation]->(c)
        WHERE r.type = 'CALL_SUMMARY' AND c.id IN $ids
        RETURN c.id AS id, r.reason AS reason`, { ids: calleeIds });
@@ -1004,6 +1167,13 @@ async function calleesWithReturnFlow(lbugPath, calleeIds, exec) {
         if (!id)
             continue;
         const decoded = decodeCallSummary(r['reason']);
+        // A typed decode failure is NOT an empty summary — record it separately and
+        // withhold the ascent all the same (the codec's contract: a decode failure
+        // means "no usable ascent fact"). Only the note's wording depends on this.
+        if (!decoded.ok) {
+            undecodable.add(id);
+            continue;
+        }
         // ARG→FORMAL trace precision: the conservative-but-sound default — ascend if
         // ANY formal is return-flowing (the call site's argument is, by construction
         // of the descent, in the slice: the call block is itself a slice block). A
@@ -1012,10 +1182,10 @@ async function calleesWithReturnFlow(lbugPath, calleeIds, exec) {
         // per-arg list), so this never drops a real ascent; it may over-include
         // (bounded — the result still flows to a slice statement). See the descent
         // doc-comment + the result `note` caveat.
-        if (decoded.ok && decoded.returnFlowParams.length > 0)
-            out.add(id);
+        if (decoded.returnFlowParams.length > 0)
+            returnFlowing.add(id);
     }
-    return out;
+    return { returnFlowing, undecodable };
 }
 /**
  * Batch-resolve resolved callee symbol ids → their `{id,filePath,startLine,endLine}`
@@ -1095,13 +1265,35 @@ async function interproceduralDescent(input) {
     // U-C4 return-value ascent: CALL blocks whose callee has a non-empty
     // CALL_SUMMARY return-flow → the call's result depends on the slice.
     const ascentBlocks = new Set();
+    // Ascent-coverage accumulators (rationale: {@link AscentCoverage}). Sets so a
+    // callee invoked from two hops is tallied once; the `Seen` suffix marks them as
+    // accumulators whose `.size` — not the set — is what gets returned.
+    const calleeReferencesSeen = new Set();
+    const calleesUndecodableSeen = new Set();
+    // Sticky across hops. `anyReturnFlow` is the cross-hop union being non-empty,
+    // which holds iff SOME hop's return-flowing set was — so the flag is set inside
+    // the hop's existing non-empty branch rather than accumulating another Set.
+    let anyReturnFlow = false;
+    let calleeListTruncated = false;
+    let idlessCallSites = false;
     hopLoop: for (let hop = 0; hop < depthBudget; hop++) {
         if (sliceBlocks.length === 0)
             break;
+        // Blocks this hop newly reached — the NEXT hop's slice, and therefore the set
+        // whose `calleeIds` cells the next hop gathers. Declared BEFORE the U-C4
+        // ascent below so the ascent's own newly-reached blocks land in it: they are
+        // slice blocks (they are unioned into `reachable` and published in
+        // `reachableBlocks`), so their call sites must reach the CALL_SUMMARY scan and
+        // the coverage counters exactly like a descent-reached block's.
+        const hopReached = new Set();
         // Keep the CALL block → callee association (U-C4 needs it to re-seed the
         // caller's intra closure FROM the specific call block the ascent licenses);
         // the flattened id set still drives the descent's fresh-callee bookkeeping.
-        const blockCallees = await calleeIdsByBlock(lbugPath, sliceBlocks, exec);
+        const { blocks: blockCallees, calleeListTruncated: hopCellCapped, idlessCallSites: hopIdless, } = await calleeIdsByBlock(lbugPath, sliceBlocks, exec);
+        if (hopCellCapped)
+            calleeListTruncated = true;
+        if (hopIdless)
+            idlessCallSites = true;
         const calleeIds = new Set();
         for (const { calleeIds: ids } of blockCallees)
             for (const id of ids)
@@ -1114,8 +1306,17 @@ async function interproceduralDescent(input) {
         // that consumes the result is captured. Monotone: only ADDS to `reachable`,
         // reusing the shared `visited` set, so it stays bounded + terminating. A
         // pre-v4 index (no CALL_SUMMARY) yields no return-flowing callees → no-op.
-        const returnFlowing = await calleesWithReturnFlow(lbugPath, [...calleeIds], exec);
+        const summaryScan = await calleesWithReturnFlow(lbugPath, [...calleeIds], exec);
+        const returnFlowing = summaryScan.returnFlowing;
+        for (const id of calleeIds)
+            calleeReferencesSeen.add(id);
+        // An undecodable summary withholds the ascent exactly like an empty one; it
+        // is tracked only so the note reports "could not read" rather than "records
+        // no return-flow".
+        for (const id of summaryScan.undecodable)
+            calleesUndecodableSeen.add(id);
         if (returnFlowing.size > 0) {
+            anyReturnFlow = true;
             for (const { blockId, calleeIds: ids } of blockCallees) {
                 // Bound the ascent re-seeds the same way the descent bounds its per-span
                 // BFS (line ~1496): a wide fan-out of return-flowing call blocks must not
@@ -1145,10 +1346,26 @@ async function interproceduralDescent(input) {
                     stepLimit,
                     probeLimit,
                 });
+                // BOTH budgets, not just the row budget: the re-seed runs the SAME BFS
+                // under the SAME depth clamp as the top-level intra pass, whose depth
+                // exhaustion is result-level truncation.
+                //
+                // The depth fold here is a CONSISTENCY guard with no independent
+                // observable, and deliberately so — do not go hunting for the test that
+                // pins it. The re-seed shares the caller's `visited` set, so it can only
+                // discover new ground past the depth budget when the traversal that
+                // already covered this closure (the top-level intra BFS, or the callee's
+                // own BFS at a later hop) was ITSELF cut short — which has already raised
+                // one of these flags. Keeping it is what stops that reasoning from
+                // silently becoming load-bearing if the sharing of `visited` ever changes.
                 if (ascent.truncatedByLimit)
                     truncatedByLimit = true;
-                for (const id of ascent.reachable)
+                if (ascent.truncatedByDepth)
+                    truncatedByDepth = true;
+                for (const id of ascent.reachable) {
                     reachable.add(id);
+                    hopReached.add(id);
+                }
             }
         }
         const freshIds = [...calleeIds].filter((id) => !seededCalleeIds.has(id));
@@ -1202,7 +1419,6 @@ async function interproceduralDescent(input) {
                 stepLimit,
                 probeLimit,
             })));
-        const hopReached = new Set();
         for (let si = 0; si < spans.length; si++) {
             // Node budget is checked INSIDE the per-span MERGE (in span order) so the
             // mid-hop short-circuit stays byte-identical: the cumulative reachable size
@@ -1232,6 +1448,14 @@ async function interproceduralDescent(input) {
                 continue;
             if (bfs.truncatedByLimit)
                 truncatedByLimit = true;
+            // A callee whose own dependence chain outruns `intraDepthBudget` is the SAME
+            // kind of incompleteness the top-level intra BFS reports through this flag
+            // (the budget is deliberately the same clamp — see `intraDepthBudget`), so
+            // it folds into the same result-level signal. Without this the slice could
+            // stop mid-callee while `truncated` stayed false and `examinedComplete`
+            // published a false all-clear over the callees past the frontier.
+            if (bfs.truncatedByDepth)
+                truncatedByDepth = true;
             // The per-callee BFS ran against a clone, so fold its discovered blocks
             // into the shared `visited`/`reachable` here (the sequential path did this
             // inside the BFS); Sets dedup, so order across siblings is irrelevant.
@@ -1247,9 +1471,12 @@ async function interproceduralDescent(input) {
         }
         sliceBlocks = [...hopReached];
     }
-    // Frontier of callees still expandable after the hop budget ⇒ depth truncation.
-    // (Conservative: if the last hop reached blocks AND we used the full budget,
-    // deeper callees may exist.)
+    // Frontier of callees still expandable after the FUNCTION-hop budget ⇒ depth
+    // truncation. (Conservative: if the last hop reached blocks AND we used the full
+    // budget, deeper callees may exist.) This is the hop-level source; the per-callee
+    // and ascent BFS passes above fold their own block-hop depth exhaustion into the
+    // same flag, so `truncatedByDepth` means "some dependence frontier was cut by a
+    // depth budget", at either granularity.
     if (hopsReached >= depthBudget && sliceBlocks.length > 0)
         truncatedByDepth = true;
     return {
@@ -1259,6 +1486,13 @@ async function interproceduralDescent(input) {
         truncatedByLimit,
         truncatedByNodeCap,
         ascentBlocks,
+        ascentCoverage: {
+            references: calleeReferencesSeen.size,
+            anyReturnFlow,
+            undecodable: calleesUndecodableSeen.size,
+            listTruncated: calleeListTruncated,
+            idlessCallSites,
+        },
     };
 }
 export async function runImpactPDG(deps) {
@@ -1424,6 +1658,13 @@ export async function runImpactPDG(deps) {
     // call lines (a coalesced call block spans several statements whose results
     // chain through it — the statement-granularity realisation of the ascent).
     let ascentBlocks = new Set();
+    // Observed ascent inputs, plumbed to the note AND to `pdgEvidence.ascent`
+    // (rationale: AscentCoverage). Left UNDEFINED when the descent never ran (an
+    // upstream slice): "nothing was scanned" is a different fact from "we scanned
+    // and found nothing", and a zeroed record would publish the second. The note's
+    // ascent branch is gated on `interproceduralHops > 0`, which only a descent can
+    // produce, so the prose is unaffected either way.
+    let ascentCoverage;
     if (direction === 'downstream') {
         const interproc = await interproceduralDescent({
             lbugPath: repo.lbugPath,
@@ -1450,6 +1691,7 @@ export async function runImpactPDG(deps) {
         });
         interproceduralHops = interproc.hopsReached;
         ascentBlocks = interproc.ascentBlocks;
+        ascentCoverage = interproc.ascentCoverage;
         for (const id of interproc.reachable)
             reachable.add(id);
         if (interproc.truncatedByDepth)
@@ -1582,6 +1824,27 @@ export async function runImpactPDG(deps) {
             ...(truncated ? { truncated: true } : {}),
             ...(truncatedBy ? { truncatedBy } : {}),
             ...(truncatedByReasons ? { truncatedByReasons } : {}),
+            // The descent may well have RUN and scanned callees before the slice turned
+            // out to reach no DISTINCT downstream block (a seed line whose only callee
+            // is invoked directly on it). `pdgEvidence.ascent` is contracted as "present
+            // iff the inter-procedural descent ran", so it must be published here too —
+            // omitting it made the documented "absent ⇒ nothing was scanned" reading
+            // false on exactly this exit. Classified through the SAME shared helpers the
+            // assembled slice result uses, so the two exits cannot disagree.
+            ...(ascentCoverage
+                ? {
+                    pdgEvidence: {
+                        ascent: publishedAscentCoverage({
+                            coverage: ascentCoverage,
+                            incompleteReasons: ascentIncompleteReasonsOf({
+                                truncated,
+                                coverage: ascentCoverage,
+                            }),
+                            callSummaryAvailable,
+                        }),
+                    },
+                }
+                : {}),
             ...emptyPdgParityFields(),
         };
     }
@@ -1611,6 +1874,7 @@ export async function runImpactPDG(deps) {
         truncatedByReasons,
         interproceduralHops,
         callSummaryAvailable,
+        ascentCoverage,
     });
 }
 export function pdgBridgeEvidenceForImpact(input) {

package/dist/mcp/tools.js

@@ -405,7 +405,7 @@ MODE (opt-in): "callgraph" (default) walks symbol→symbol edges (CALLS/IMPORTS/
 
 STATEMENT-ANCHORED PDG SLICE: with mode:'pdg', pass "line" (1-based source line within the target symbol) to seed the dependence slice on the statement at that line and return what depends on it in affectedStatements (line + text). Inter-procedural symbols are still reported through interproceduralByDepth/pdgInterprocedural and the compatibility byDepth bucket. Without "line", pdg returns whole-symbol inter-procedural reach plus local whole-symbol PDG diagnostics.
 
-PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:2 — a stable discriminator for external consumers that bumps on any breaking change to the PDG result shape (distinct from the DB schema version). Successful PDG results include mode:'pdg', a full target envelope (id/name/type/filePath), affectedStatements, affectedStatementCount, interproceduralByDepth/pdgInterprocedural for cross-function reach, compatibility byDepth/byDepthCounts, risk:'UNKNOWN', and a note describing the unified contract. Degraded PDG results (no-layer, sub-layer-missing, unknown) keep mode:'pdg', pdgResultVersion:2, target metadata when the target resolves, risk:'UNKNOWN', note/remediation, and empty byDepth parity fields — never a false-safe zero. If depth and limit both bound the slice, truncatedByReasons reports both causes while truncatedBy remains scalar.
+PDG OUTPUT CONTRACT: every mode:'pdg' result (success, empty, degraded, or error) carries pdgResultVersion:2 — a stable discriminator for external consumers that bumps on any breaking change to the PDG result shape (distinct from the DB schema version). Successful PDG results include mode:'pdg', a full target envelope (id/name/type/filePath), affectedStatements, affectedStatementCount, interproceduralByDepth/pdgInterprocedural for cross-function reach, compatibility byDepth/byDepthCounts, risk:'UNKNOWN', and a note describing the unified contract. Degraded PDG results (no-layer, sub-layer-missing, unknown) keep mode:'pdg', pdgResultVersion:2, target metadata when the target resolves, risk:'UNKNOWN', note/remediation, and empty byDepth parity fields — never a false-safe zero. If depth and limit both bound the slice, truncatedByReasons reports both causes while truncatedBy remains scalar. Return-value-ascent coverage is published structurally at pdgEvidence.ascent — present iff the inter-procedural descent ran, including on an empty slice — with referencesScanned (DISTINCT callees scanned for a CALL_SUMMARY: a distinct-id tally, not a call-site count — two call sites to the same callee count once), returnFlowFound (whether the ascent fired anywhere in the slice), undecodableSummaryCount, examinedComplete (whether that scan covered every callee the index recorded a resolved id for on the visited blocks), incompleteReasons ('traversal-truncated' | 'callee-list-capped' | 'callee-ids-unrecorded'), and callSummaryLayerPresent. Read callSummaryLayerPresent FIRST: false ⇒ a pre-CALL_SUMMARY index, so {referencesScanned:N>0, returnFlowFound:false} is self-consistent and says nothing about the callees — the scan ran, but no layer existed in which a return-flow could be recorded (remedy: re-run gitnexus analyze --pdg). Branch on those fields; the note narrates the same facts in prose for humans and is not a stable contract.
 
 WHEN TO USE: Before making code changes — especially refactoring, renaming, or modifying shared code. Shows what would break.
 AFTER THIS: Review d=1 items (WILL BREAK). Use context() on high-risk symbols.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.10-rc.152",
+  "version": "1.6.10-rc.154",
   "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",

package/scripts/cross-platform-shard.ts

@@ -0,0 +1,136 @@
+/**
+ * Weight-aware partitioning for the cross-platform test matrix.
+ *
+ * WHY THIS EXISTS. `run-cross-platform.ts` used to hand vitest the whole file
+ * list plus `--shard=i/n`, and vitest partitions by file COUNT. Runtime on this
+ * suite is wildly uneven — measured on the Windows runner, `cli-e2e` is 361 s
+ * and `worker-pool` 221 s, while most files are under a second — so a
+ * count-split routinely put several of the heaviest suites on one shard. That
+ * is #2449, and this file's sibling header has documented the symptom ("the
+ * heaviest spawn suites can cluster on one shard") since the watchdog was first
+ * raised from 15 to 20 minutes.
+ *
+ * It went from a latent hazard to a red matrix when three CHEAP files (the
+ * `dist/` module-load closure guards: 448 ms, 53 ms, sub-second) were added to
+ * `SPAWN_CLI`. They cost nothing to run, but a count-split re-partitions on
+ * every insertion, and the reshuffle happened to land `cli-e2e` + `cli-limit-e2e`
+ * + `analyze-heap-oom-e2e` together on shard 1/3 — 32 files against 26 and 29 —
+ * which blew the 20-minute budget with four files still queued. Nothing about
+ * the added files caused it; they were simply the perturbation.
+ *
+ * So the split is done HERE, by weight, and only the chosen shard's files are
+ * handed to vitest. Two properties follow, and both are pinned in
+ * `test/unit/cross-platform-shard.test.ts`:
+ *
+ *  - the heaviest suites are spread across shards by construction, so the
+ *    busiest shard tracks the ideal rather than the luck of the sort order;
+ *  - adding or removing a CHEAP file cannot move a heavy one, so registering a
+ *    new platform-sensitive test is no longer a CI-stability gamble. That is the
+ *    property whose absence caused this.
+ */
+
+/**
+ * Measured wall-clock on the WINDOWS runner (the slowest platform, so it is the
+ * one that decides the budget), in seconds, from the last fully-green matrix run
+ * plus the timed files of the run that failed.
+ *
+ * Only files heavy enough to matter are listed; everything else is carried by
+ * {@link PER_FILE_OVERHEAD_SEC} alone. These are load-balancing hints, NOT
+ * assertions — no
+ * test asserts a runtime, and drift only makes the split slightly less even, so
+ * a stale entry is harmless and refreshing them is optional. Deliberately not
+ * auto-generated: a committed table is reviewable and works offline, and the
+ * alternative (timing files at CI runtime to decide the split) would make the
+ * partition depend on the very machine load it is trying to protect against.
+ */
+export const WINDOWS_WEIGHTS_SEC: Readonly<Record<string, number>> = {
+  'test/integration/cli-e2e.test.ts': 361,
+  'test/integration/worker-pool.test.ts': 222,
+  'test/unit/incremental-vector-extension-ordering.test.ts': 87,
+  'test/integration/cli-limit-e2e.test.ts': 75,
+  'test/unit/hooks.test.ts': 26,
+  'test/integration/analyze-heap-oom-e2e.test.ts': 23,
+  'test/unit/git-utils.test.ts': 18,
+  'test/integration/hooks-e2e.test.ts': 15,
+  'test/integration/tree-sitter-languages.test.ts': 9,
+  'test/unit/repo-manager.test.ts': 9,
+  'test/unit/detect-changes-worktree.test.ts': 9,
+  'test/integration/antigravity-hook-e2e.test.ts': 7,
+  'test/unit/index-lock.test.ts': 5,
+  'test/unit/setup.test.ts': 5,
+};
+
+/**
+ * Fixed cost every file pays regardless of what it asserts: a pool worker start,
+ * module graph evaluation, and (for most of this list) a native addon load.
+ *
+ * Added to EVERY file's weight, not just unmeasured ones, and that is the point.
+ * Calibrated against the last green Windows matrix: its busiest shard ran 736 s
+ * of wall clock over ~511 s of measured file time, so roughly 8 s per file is
+ * unattributed setup. Without this term the balancer treats a light file as
+ * nearly free and, having isolated the two monsters, piles every remaining file
+ * onto the other shards — trading a runtime imbalance for a file-count one that
+ * costs just as much. With it, the split balances runtime AND count together.
+ */
+const PER_FILE_OVERHEAD_SEC = 8;
+
+/**
+ * Scheduling weight for `file`: its measured runtime (0 if it was fast enough
+ * that vitest printed no duration) plus the per-file floor above.
+ */
+export function weightOf(file: string): number {
+  return (WINDOWS_WEIGHTS_SEC[file] ?? 0) + PER_FILE_OVERHEAD_SEC;
+}
+
+/**
+ * Partition `files` into `total` shards and return the 1-based `index` one.
+ *
+ * Longest-processing-time first: sort by weight descending, then repeatedly give
+ * the next file to the lightest shard so far. LPT is the standard greedy for
+ * multiprocessor scheduling and is guaranteed within 4/3 of optimal — far more
+ * than enough here, where the goal is only "no shard gets two monsters".
+ *
+ * Ties break on the file path so the partition is DETERMINISTIC: every shard
+ * computes the same split independently, on a different machine, with no
+ * coordination — which is what lets each runner select its own slice.
+ *
+ * Returns files in the input list's original order, not weight order, so failure
+ * output and reruns stay readable.
+ */
+export function shardFiles(
+  files: readonly string[],
+  index: number,
+  total: number,
+): readonly string[] {
+  if (!Number.isInteger(total) || total < 1) {
+    throw new Error(`shard total must be a positive integer, got ${total}`);
+  }
+  if (!Number.isInteger(index) || index < 1 || index > total) {
+    throw new Error(`shard index must be in 1..${total}, got ${index}`);
+  }
+  if (total === 1) return [...files];
+
+  const byWeightDesc = [...files].sort((a, b) => {
+    const diff = weightOf(b) - weightOf(a);
+    return diff !== 0 ? diff : a.localeCompare(b);
+  });
+
+  const loads = Array.from({ length: total }, () => 0);
+  const assigned = Array.from({ length: total }, () => new Set<string>());
+  for (const file of byWeightDesc) {
+    let lightest = 0;
+    for (let i = 1; i < total; i++) {
+      if (loads[i]! < loads[lightest]!) lightest = i;
+    }
+    assigned[lightest]!.add(file);
+    loads[lightest]! += weightOf(file);
+  }
+
+  const mine = assigned[index - 1]!;
+  return files.filter((f) => mine.has(f));
+}
+
+/** Total weight of a file set — the shard cost this balancer is minimising. */
+export function shardWeight(files: readonly string[]): number {
+  return files.reduce((sum, f) => sum + weightOf(f), 0);
+}

package/scripts/cross-platform-tests.ts

@@ -186,6 +186,33 @@ const SPAWN_CLI = [
   // exposed a file-backend double-admit race here (#2658 review); the reclaim is
   // now judgment-verified so a live holder is never displaced.
   'test/integration/analyze-index-lock-concurrency.test.ts',
+  // The three `dist/` module-load closure guards, all built on the shared
+  // child-process probe in `test/helpers/module-load-probe.ts`. That probe IS
+  // the platform-varying part: it spawns `process.execPath` in array form,
+  // clears NODE_OPTIONS, addresses its target via `pathToFileURL` (Windows needs
+  // the `file:///C:/...` form — a bare absolute path is not a valid ESM
+  // specifier there), and renders every result through a `path.sep`→POSIX
+  // normalisation the anchors and offender regexes depend on. None of that is
+  // proven anywhere else.
+  //
+  // Cheap: measured on the Windows runner at 448 ms, 53 ms and sub-second. An
+  // earlier attempt to register them still turned the matrix red — not from
+  // their own cost, but because vitest sharded by file COUNT, so inserting any
+  // file re-partitioned the list and happened to cluster `cli-e2e` (361 s) with
+  // `cli-limit-e2e` (75 s) on one shard. The split is weight-aware now
+  // (`scripts/cross-platform-shard.ts`), so a cheap file can no longer move a
+  // heavy one.
+  //
+  // #2802: MCP startup must not eagerly load the analyze-only language
+  // provider registry or the group contract extractors.
+  'test/integration/mcp/startup-language-closure.test.ts',
+  // PR #1383: `cli/mcp.js`'s static-import closure must stay leaf-only so no
+  // native binding initialises before the stdout sentinel installs.
+  'test/integration/mcp/import-closure.test.ts',
+  // #2091/#2093/#2116: the scope-resolution registry must not load the optional
+  // tree-sitter grammars at import time. The offender regexes match grammar
+  // paths with either separator, which only the Windows runner proves.
+  'test/integration/optional-grammars/registry-import-closure.test.ts',
 ];
 
 // Worker threads tests — exercise real worker_threads which have

package/scripts/run-cross-platform.ts

@@ -15,6 +15,7 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { ALL_CROSS_PLATFORM } from './cross-platform-tests.js';
 import { parseShardArg } from './shard-arg.js';
+import { shardFiles, shardWeight } from './cross-platform-shard.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -29,8 +30,10 @@ if (missing.length > 0) {
 }
 
 // Optional sharding (CI): `--shard=<i>/<n>` splits the fixed file list across
-// parallel matrix shards so each runner processes ~1/n of it. Passed straight
-// through to vitest, which partitions the *given* files deterministically. The
+// parallel matrix shards. The split is computed HERE, by measured weight, and
+// only this shard's files are handed to vitest — it is NOT passed through,
+// because vitest partitions by file COUNT and this suite's runtimes span three
+// orders of magnitude (see cross-platform-shard.ts). The
 // Windows runner is ~5x slower than macOS/Linux on this spawn-heavy suite (~50
 // CLI/worker process spawns), so a single shard was creeping past the watchdog
 // below; sharding keeps each runner well under it (see ci-tests.yml matrix).
@@ -63,14 +66,22 @@ const timeoutMs =
     ? timeoutMinutes * 60 * 1000
     : DEFAULT_TIMEOUT_MIN * 60 * 1000;
 
+// Resolve the shard to an explicit file list. `--shard=i/n` is consumed here,
+// never forwarded: forwarding it as well would re-partition this slice a second
+// time and silently drop most of it.
+const shardParts = shardArg?.replace('--shard=', '').split('/');
+const shardIndex = shardParts ? Number(shardParts[0]) : 1;
+const shardTotal = shardParts ? Number(shardParts[1]) : 1;
+const files = shardFiles(ALL_CROSS_PLATFORM, shardIndex, shardTotal);
+
 console.log(
-  `Running ${ALL_CROSS_PLATFORM.length} platform-sensitive tests` +
-    `${shardArg ? ` (${shardArg.replace('--shard=', 'shard ')})` : ''}...\n`,
+  `Running ${files.length} of ${ALL_CROSS_PLATFORM.length} platform-sensitive tests` +
+    `${shardArg ? ` (shard ${shardIndex}/${shardTotal}, ~${shardWeight(files)}s measured weight)` : ''}...\n`,
 );
 
 const startedAt = Date.now();
 try {
-  execFileSync('npx', ['vitest', 'run', ...ALL_CROSS_PLATFORM, ...(shardArg ? [shardArg] : [])], {
+  execFileSync('npx', ['vitest', 'run', ...files], {
     cwd: ROOT,
     stdio: 'inherit',
     timeout: timeoutMs,