gitnexus 1.6.10-rc.147 → 1.6.10-rc.149

package/dist/cli/analyze.js

@@ -14,6 +14,8 @@ import v8 from 'v8';
 import cliProgress from 'cli-progress';
 import { isLbugReady, LbugWipeError } from '../core/lbug/lbug-adapter.js';
 import { boundedCheckpointBeforeExit } from '../core/lbug/shutdown-helpers.js';
+import { findUndeclaredRelationPairError } from '../core/lbug/rel-pair-routing.js';
+import { causeChain } from '../lib/utils.js';
 import { getOsPageSize, isLbugCheckpointIoError, isLbugCheckpointBusyError, isLbugPageSizeFrameError, isPageSizeAwareLadybug, isWalCorruptionError, parseWalCheckpointThreshold, WAL_RECOVERY_SUGGESTION, } from '../core/lbug/lbug-config.js';
 import { getStoragePaths, getGlobalRegistryPath, RegistryNameCollisionError, AnalysisNotFinalizedError, assertAnalysisFinalized, } from '../storage/repo-manager.js';
 import { getGitRoot, hasGitDir, getDefaultBranch, selfCommitContextFiles, snapshotSelfCommitSafety, } from '../storage/git.js';
@@ -54,15 +56,13 @@ const writeFatalToStderr = (label, err) => {
     // #2068) is only reachable via `.cause`. Without this the user sees the
     // wrapper's main-thread stack and never the real frame. `cause.stack` already
     // begins with the cause's message, so we print the stack alone (not message +
-    // stack) to avoid repeating it. Depth-bounded so a cyclic `cause` can't loop
-    // (the phase runner wraps one level; the bound leaves headroom for future
-    // nesting); uses realStderrWrite so the redirected console.error's ANSI
-    // clear-line wrapping can't erase it (#1169).
-    const MAX_CAUSE_DEPTH = 5;
-    let cause = isErr ? err.cause : undefined;
-    for (let depth = 0; depth < MAX_CAUSE_DEPTH && cause instanceof Error; depth++) {
+    // stack) to avoid repeating it. `causeChain` owns the traversal and the depth
+    // bound that stops a cyclic `cause` looping — this used to be one of four
+    // hand-rolled copies that had already drifted apart on both. Uses
+    // realStderrWrite so the redirected console.error's ANSI clear-line wrapping
+    // can't erase it (#1169). The head is skipped: it was just printed above.
+    for (const cause of causeChain(isErr ? err.cause : undefined)) {
         realStderrWrite(`\n  Caused by: ${cause.stack ?? cause.message}\n`);
-        cause = cause.cause;
     }
 };
 let fatalHandlersInstalled = false;
@@ -1314,6 +1314,35 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             process.exitCode = 1;
             return;
         }
+        // An extracted edge whose FROM→TO label pair is missing from GitNexus's own
+        // relation DDL (#2789). `assertDeclaredPair` aborts the run rather than let
+        // the bulk COPY fail late and silently drop the edge, so the user sees a
+        // mid-run crash inside GitNexus internals with nothing to act on. Name the
+        // pair, the relationship and the file that produced it, and say plainly that
+        // a re-run cannot help — this is deterministic for the same input.
+        // Checked by TYPE (repo norm, #2385) BEFORE the message-text heuristics
+        // below, and through the `cause` chain because the ingestion phase runner
+        // rewraps every phase failure as `Phase 'X' failed: …`.
+        const undeclaredPair = findUndeclaredRelationPairError(err);
+        if (undeclaredPair !== undefined) {
+            // Render the error's OWN message indented — same idiom as the
+            // `LbugWipeError` and page-size branches below. `UndeclaredRelationPairError`
+            // builds a fully self-contained message (pair, relationship type, both node
+            // ids, source file, issue URL, `.gitnexusignore` workaround) precisely
+            // because `gitnexus serve` forwards only `err.message` over worker IPC.
+            // Re-rendering those fields here would be a second copy of one string, free
+            // to drift from the first — and the actionable half would reach CLI users
+            // only. `undeclaredPair.message`, not the outer `msg`: the real error may be
+            // several `cause` levels below the phase wrapper `msg` came from.
+            cliError(`  ${undeclaredPair.message.replace(/\n/g, '\n  ')}\n`, {
+                recoveryHint: 'undeclared-relation-pair',
+                labelPair: undeclaredPair.pairKey,
+                relationType: undeclaredPair.relationType,
+                sourceFile: undeclaredPair.sourceFile,
+            });
+            process.exitCode = 1;
+            return;
+        }
         // WAL corruption — the index file is unreadable. Give a clear recovery
         // path without a confusing stack trace (the native error message alone
         // is enough signal).

package/dist/cli/cli-message.d.ts

@@ -12,7 +12,7 @@ import { type CliMessageKey, type CliMessageVars } from './i18n/index.js';
  * Consumers can import this type to narrow log-record `recoveryHint`
  * fields without restating the literal list.
  */
-export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'lbug-wipe-failed' | 'lbug-page-size' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid' | 'index-lock-timeout';
+export type RecoveryHint = 'wal-corruption' | 'wal-checkpoint-threshold' | 'lbug-wipe-failed' | 'lbug-page-size' | 'heap-oom-respawn' | 'native-worker-abort' | 'hf-endpoint-unreachable' | 'http-embedding-endpoint-error' | 'embedding-dims-invalid' | 'local-embedding-unsupported' | 'local-embedding-stack-missing' | 'large-repo' | 'npm-resolution' | 'module-not-found' | 'gitnexusrc-invalid' | 'default-branch-invalid' | 'index-lock-timeout' | 'undeclared-relation-pair';
 /**
  * Common shape for the optional structured-field bag passed to
  * `cliError`/`cliWarn`/`cliInfo`. Typed so the `recoveryHint` slot is

package/dist/cli/group.js

@@ -213,12 +213,31 @@ export function registerGroupCommands(program) {
             else {
                 const summary = raw?.summary;
                 const risk = raw?.risk;
+                // A truncated fan-out under-reports risk (mergeRisk only grows with
+                // traversed crossings), and the default human output used to print a
+                // bare `risk=` indistinguishable from a complete run — the JSON
+                // already carried `truncated`, but nobody reading the terminal saw it.
+                const riskFloor = raw?.riskEpistemic === 'lower-bound' ? '+' : '';
                 const boundaryOnly = raw?.cross?.filter((entry) => entry.fanout_status === 'not_attempted').length ?? 0;
-                console.log(`Group impact for "${name}" (${String(opts.repo)}): risk=${risk ?? '?'}`);
+                console.log(`Group impact for "${name}" (${String(opts.repo)}): risk=${risk ?? '?'}${riskFloor}`);
                 if (summary) {
                     const boundaryNote = boundaryOnly > 0 ? ` (${boundaryOnly} boundary-only)` : '';
                     console.log(`  direct=${summary.direct ?? 0} processes=${summary.processes_affected ?? 0} cross=${summary.cross_repo_hits ?? 0}${boundaryNote}`);
                 }
+                if (riskFloor) {
+                    // `truncated` has two independent causes that point at different
+                    // subsystems, so the note must name the one that actually fired:
+                    // dropped crossings, or a local walk that never finished (most
+                    // often the impact chunk cap, which any symbol with more than a
+                    // thousand locally-impacted nodes hits on every run). `dropped` is
+                    // deduped to distinct repos before it reaches here, so it counts
+                    // repos — reporting it as crossings understates a fan-out cap the
+                    // same way #2787's totals did.
+                    const dropped = raw?.truncatedRepos ?? [];
+                    console.log(dropped.length > 0
+                        ? `  risk is a LOWER BOUND — fan-out stopped early; crossings to ${dropped.length} repo(s) not traversed: ${dropped.join(', ')}`
+                        : '  risk is a LOWER BOUND — the local impact walk did not complete (every bridge crossing was traversed)');
+                }
             }
         }
         finally {

package/dist/core/augmentation/engine.js

@@ -108,6 +108,7 @@ export async function augment(pattern, cwd) {
           MATCH (n) WHERE n.filePath = '${escaped}'
           AND n.name CONTAINS '${patternFirstWord}'
           RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
+          ORDER BY id
           LIMIT 3
         `);
                 for (const sym of symbols) {
@@ -131,6 +132,7 @@ export async function augment(pattern, cwd) {
         MATCH (n)
         WHERE n.name CONTAINS '${patternFirstWord}'
         RETURN n.id AS id, n.name AS name, labels(n)[0] AS type, n.filePath AS filePath
+        ORDER BY id
         LIMIT 5
       `).catch(() => []);
             for (const sym of fallbackRows) {
@@ -153,99 +155,112 @@ export async function augment(pattern, cwd) {
         if (uniqueSymbols.length === 0)
             return '';
         const idList = uniqueSymbols.map((s) => `'${escapeCypherString(s.nodeId)}'`).join(', ');
-        // Batch fetch callers
-        const callersMap = new Map();
-        try {
+        // Callers/callees are windowed PER SYMBOL, not out of one shared budget.
+        // A single `n.id IN [...] ... ORDER BY targetId LIMIT 15` sorts by the very
+        // column the rows are grouped by, which turns the cap into a single-bucket
+        // prefix: the alphabetically-first target takes every row (the hottest
+        // symbol in this repo's own index has 2163 callers) and the other four
+        // render with no callers at all. Raising the cap does not bound that, and
+        // ordering caller-major only moves the bucket. A per-target window is not
+        // expressible in one statement either — LadybugDB does not preserve a
+        // per-branch ORDER BY through UNION ALL — so fan out one bounded query per
+        // symbol (#2787).
+        //
+        // `id STARTS WITH 'File:'` sorts container nodes last: node ids are
+        // `Label:path:name`, so a bare `ORDER BY id` puts `File:` ahead of
+        // `Function:`/`Method:` and the "Called by" line renders bare filenames
+        // instead of the calling symbols the hint exists to name.
+        const NEIGHBOUR_CAP = 3;
+        const neighbourNames = async (nodeId, incoming) => {
+            const edge = incoming
+                ? `(other)-[:CodeRelation {type: 'CALLS'}]->(n)`
+                : `(n)-[:CodeRelation {type: 'CALLS'}]->(other)`;
             const rows = await executeQuery(repoId, `
-        MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(n)
-        WHERE n.id IN [${idList}]
-        RETURN n.id AS targetId, caller.name AS name
-        LIMIT 15
-      `);
-            for (const r of rows) {
-                const tid = r.targetId || r[0];
-                const name = r.name || r[1];
-                if (tid && name) {
-                    if (!callersMap.has(tid))
-                        callersMap.set(tid, []);
-                    callersMap.get(tid).push(name);
-                }
-            }
-        }
-        catch {
-            /* skip */
-        }
-        // Batch fetch callees
-        const calleesMap = new Map();
-        try {
-            const rows = await executeQuery(repoId, `
-        MATCH (n)-[:CodeRelation {type: 'CALLS'}]->(callee)
-        WHERE n.id IN [${idList}]
-        RETURN n.id AS sourceId, callee.name AS name
-        LIMIT 15
-      `);
+        MATCH ${edge}
+        WHERE n.id = '${escapeCypherString(nodeId)}'
+        RETURN other.name AS name
+        ORDER BY other.id STARTS WITH 'File:', other.id
+        LIMIT ${NEIGHBOUR_CAP}
+      `).catch(() => []);
+            const names = [];
             for (const r of rows) {
-                const sid = r.sourceId || r[0];
-                const name = r.name || r[1];
-                if (sid && name) {
-                    if (!calleesMap.has(sid))
-                        calleesMap.set(sid, []);
-                    calleesMap.get(sid).push(name);
-                }
+                const name = r.name || r[0];
+                if (name)
+                    names.push(name);
             }
-        }
-        catch {
-            /* skip */
-        }
+            return names;
+        };
+        // Keyed by nodeId, like the process/cohesion enrichments below — positional
+        // arrays would put two lookup disciplines in one object literal and make
+        // "stays index-aligned with uniqueSymbols" an unenforced invariant.
+        const neighbourMap = async (incoming) => new Map(await Promise.all(uniqueSymbols.map(async (s) => [s.nodeId, await neighbourNames(s.nodeId, incoming)])));
         // Batch fetch processes
-        const processesMap = new Map();
-        try {
-            const rows = await executeQuery(repoId, `
+        const fetchProcesses = async () => {
+            const byNode = new Map();
+            try {
+                const rows = await executeQuery(repoId, `
         MATCH (n)-[r:CodeRelation {type: 'STEP_IN_PROCESS'}]->(p:Process)
         WHERE n.id IN [${idList}]
         RETURN n.id AS nodeId, p.heuristicLabel AS label, r.step AS step, p.stepCount AS stepCount
       `);
-            for (const r of rows) {
-                const nid = r.nodeId || r[0];
-                const label = r.label || r[1];
-                const step = r.step || r[2];
-                const stepCount = r.stepCount || r[3];
-                if (nid && label) {
-                    if (!processesMap.has(nid))
-                        processesMap.set(nid, []);
-                    processesMap.get(nid).push(`${label} (step ${step}/${stepCount})`);
+                for (const r of rows) {
+                    const nid = r.nodeId || r[0];
+                    const label = r.label || r[1];
+                    const step = r.step || r[2];
+                    const stepCount = r.stepCount || r[3];
+                    if (nid && label) {
+                        if (!byNode.has(nid))
+                            byNode.set(nid, []);
+                        byNode.get(nid).push(`${label} (step ${step}/${stepCount})`);
+                    }
                 }
             }
-        }
-        catch {
-            /* skip */
-        }
+            catch {
+                /* skip */
+            }
+            return byNode;
+        };
         // Batch fetch cohesion
-        const cohesionMap = new Map();
-        try {
-            const rows = await executeQuery(repoId, `
+        const fetchCohesion = async () => {
+            const byNode = new Map();
+            try {
+                const rows = await executeQuery(repoId, `
         MATCH (n)-[:CodeRelation {type: 'MEMBER_OF'}]->(c:Community)
         WHERE n.id IN [${idList}]
         RETURN n.id AS nodeId, c.cohesion AS cohesion
       `);
-            for (const r of rows) {
-                const nid = r.nodeId || r[0];
-                const coh = r.cohesion ?? r[1] ?? 0;
-                if (nid)
-                    cohesionMap.set(nid, coh);
+                for (const r of rows) {
+                    const nid = r.nodeId || r[0];
+                    const coh = r.cohesion ?? r[1] ?? 0;
+                    if (nid)
+                        byNode.set(nid, coh);
+                }
             }
-        }
-        catch {
-            /* skip */
-        }
+            catch {
+                /* skip */
+            }
+            return byNode;
+        };
+        // One wave, not three. `augment` runs from the Claude Code PreToolUse hook
+        // in a cold process against a <500ms budget, so nothing amortizes — and the
+        // process/cohesion queries depend only on `idList`, never on the neighbour
+        // results, so serializing them behind the fan-out bought nothing. Each query
+        // keeps its own try/catch, so one failing still degrades to an empty map
+        // instead of taking the others down.
+        const [callerMap, calleeMap, processesMap, cohesionMap] = await Promise.all([
+            neighbourMap(true),
+            neighbourMap(false),
+            fetchProcesses(),
+            fetchCohesion(),
+        ]);
         // Assemble enriched results
         const enriched = [];
         for (const sym of uniqueSymbols) {
             enriched.push({
                 name: sym.name,
                 filePath: sym.filePath,
-                callers: (callersMap.get(sym.nodeId) || []).slice(0, 3),
-                callees: (calleesMap.get(sym.nodeId) || []).slice(0, 3),
+                callers: callerMap.get(sym.nodeId) || [],
+                callees: calleeMap.get(sym.nodeId) || [],
                 processes: processesMap.get(sym.nodeId) || [],
                 cohesion: cohesionMap.get(sym.nodeId) || 0,
             });

package/dist/core/group/cross-impact.d.ts

@@ -4,10 +4,30 @@
  */
 import type { BridgeHandle, CrossRepoImpact, GroupImpactResult } from './types.js';
 import type { GroupToolPort } from './service.js';
+import { compareCodeUnits } from '../../lib/utils.js';
 /** Cross-boundary hops beyond this value are clamped (multi-hop reserved for future work). */
 export declare const MAX_SUPPORTED_CROSS_DEPTH = 1;
 /** Default wall-clock budget for the Phase 1 `impact` leg when callers omit `timeoutMs`. */
 export declare const DEFAULT_LOCAL_IMPACT_TIMEOUT_MS = 30000;
+/**
+ * Cap on neighbour fan-outs attempted per group-impact request.
+ *
+ * The bound used to be the wall clock alone, which made the cutoff a function
+ * of machine load: an idle host traversed more crossings and `mergeRisk`
+ * escalated to CRITICAL at three, while a loaded host stopped at two and
+ * reported HIGH or lower — same graph, same arguments, different verdict
+ * (#2787). A count is deterministic, and the neighbour list carries a total
+ * order over the full crossing identity (confidence DESC, then repo, uid,
+ * contract), so the cap keeps the strongest crossings rather than an arbitrary
+ * prefix.
+ *
+ * 50 is borrowed from `MAX_CROSSINGS_TO_TRY` (cross-trace.ts) on cost, not on
+ * scope — that one caps ContractLinks per repo pair inside a trace, this one
+ * caps the total across all neighbour repos in one impact call, and group impact
+ * had no numeric cap at all before #2787. The wall clock stays as a hang
+ * backstop below; this is the bound that normally binds.
+ */
+export declare const MAX_NEIGHBOR_FANOUT = 50;
 export type BridgeNeighborRow = {
     neighborRepo: string;
     neighborUid: string;
@@ -117,3 +137,4 @@ export declare function runGroupImpact(deps: RunGroupImpactDeps, params: Record<
     error: string;
 }>;
 export { normalizeServicePrefix, fileMatchesServicePrefix } from './group-path-utils.js';
+export { compareCodeUnits };

package/dist/core/group/cross-impact.js

@@ -9,6 +9,7 @@ import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } fro
 import { getGroupDir } from './storage.js';
 import { closeBridgeDb, getCachedBridgeReadOnly, queryBridge, readBridgeMeta, } from './bridge-db.js';
 import { BRIDGE_SCHEMA_VERSION } from './bridge-schema.js';
+import { compareCodeUnits } from '../../lib/utils.js';
 // High limit for the local phase of group impact so collectImpactSymbolUids
 // sees (nearly) all symbols. Bypasses the MCP-facing default of 100.
 const GROUP_LOCAL_PHASE_LIMIT = 10000;
@@ -16,6 +17,25 @@ const GROUP_LOCAL_PHASE_LIMIT = 10000;
 export const MAX_SUPPORTED_CROSS_DEPTH = 1;
 /** Default wall-clock budget for the Phase 1 `impact` leg when callers omit `timeoutMs`. */
 export const DEFAULT_LOCAL_IMPACT_TIMEOUT_MS = 30_000;
+/**
+ * Cap on neighbour fan-outs attempted per group-impact request.
+ *
+ * The bound used to be the wall clock alone, which made the cutoff a function
+ * of machine load: an idle host traversed more crossings and `mergeRisk`
+ * escalated to CRITICAL at three, while a loaded host stopped at two and
+ * reported HIGH or lower — same graph, same arguments, different verdict
+ * (#2787). A count is deterministic, and the neighbour list carries a total
+ * order over the full crossing identity (confidence DESC, then repo, uid,
+ * contract), so the cap keeps the strongest crossings rather than an arbitrary
+ * prefix.
+ *
+ * 50 is borrowed from `MAX_CROSSINGS_TO_TRY` (cross-trace.ts) on cost, not on
+ * scope — that one caps ContractLinks per repo pair inside a trace, this one
+ * caps the total across all neighbour repos in one impact call, and group impact
+ * had no numeric cap at all before #2787. The wall clock stays as a hang
+ * backstop below; this is the bound that normally binds.
+ */
+export const MAX_NEIGHBOR_FANOUT = 50;
 const CY_NEIGHBORS_UPSTREAM = `
 MATCH (consumer:Contract)-[l:ContractLink]->(provider:Contract)
 WHERE provider.repo = $localRepo
@@ -268,6 +288,24 @@ export function mergeRisk(localRisk, cross) {
         return 'MEDIUM';
     return localRisk;
 }
+/**
+ * Build the truncation fields every `runGroupImpact` return path shares.
+ *
+ * `riskEpistemic` must follow `truncated` mechanically: it is the marker that
+ * tells a caller the `risk` value is a floor rather than a verdict, and
+ * `mergeRisk` can only under-report once a crossing is dropped. Attaching it at
+ * each return let two of the four paths set `truncated` without it, so a
+ * truncated result read as complete — deriving it in one place is what keeps
+ * the invariant from drifting again (#2787).
+ */
+function truncationFields(truncated, 
+// Only read on the truncated branch, so the not-truncated call sites omit it
+// rather than passing a reason that is thrown away.
+reasonIfTruncated = 'partial') {
+    if (!truncated)
+        return { truncated: false };
+    return { truncated: true, truncationReason: reasonIfTruncated, riskEpistemic: 'lower-bound' };
+}
 function addCrossImpact(cross, candidate) {
     const sameBoundary = (entry) => entry.repo_path === candidate.repo_path && entry.contract.id === candidate.contract.id;
     if (candidate.fanout_status === 'not_attempted') {
@@ -351,7 +389,15 @@ export async function resolveBridgeNeighbors(handle, opts) {
         if (n)
             neighbors.push(n);
     }
-    neighbors.sort((a, b) => b.confidence - a.confidence);
+    // Sort on the FULL crossing identity — the same triple the fan-out dedups on
+    // below (`repo\0uid\0contractId`). Two links that share (confidence, repo,
+    // uid) but differ in contract both survive that dedup, so leaving contractId
+    // out of the comparator makes them compare 0 and fall back to raw bridge row
+    // order, which is what decides who lands past MAX_NEIGHBOR_FANOUT (#2787).
+    neighbors.sort((a, b) => b.confidence - a.confidence ||
+        compareCodeUnits(a.neighborRepo, b.neighborRepo) ||
+        compareCodeUnits(a.neighborUid, b.neighborUid) ||
+        compareCodeUnits(a.contractId, b.contractId));
     return neighbors;
 }
 export async function runGroupImpact(deps, params) {
@@ -390,7 +436,7 @@ export async function runGroupImpact(deps, params) {
             group: name,
             cross: [],
             outOfScope: [],
-            truncated: true,
+            ...truncationFields(true, 'timeout'),
             truncatedRepos: [],
             summary: {
                 direct: 0,
@@ -400,7 +446,6 @@ export async function runGroupImpact(deps, params) {
             },
             risk: 'UNKNOWN',
             timeoutMs,
-            truncationReason: 'timeout',
             crossDepthWarning,
         };
     }
@@ -422,7 +467,7 @@ export async function runGroupImpact(deps, params) {
                 group: name,
                 cross: [],
                 outOfScope: [],
-                truncated: false,
+                ...truncationFields(false),
                 truncatedRepos: [],
                 summary: {
                     direct: 0,
@@ -444,7 +489,7 @@ export async function runGroupImpact(deps, params) {
             group: name,
             cross: [],
             outOfScope: [],
-            truncated: Boolean(local.partial),
+            ...truncationFields(Boolean(local.partial), 'partial'),
             truncatedRepos: [],
             summary: {
                 direct: s.direct ?? 0,
@@ -454,7 +499,6 @@ export async function runGroupImpact(deps, params) {
             },
             risk: String(local.risk ?? 'LOW'),
             timeoutMs,
-            truncationReason: local.partial ? 'partial' : undefined,
             crossDepthWarning,
         };
     }
@@ -465,6 +509,10 @@ export async function runGroupImpact(deps, params) {
     const cross = [];
     const outOfScope = [];
     const truncatedRepos = [];
+    /** Real `impactByUid` fan-outs issued — what MAX_NEIGHBOR_FANOUT bounds. */
+    let attemptedFanouts = 0;
+    /** True when the wall-clock backstop, not the count cap, cut the fan-out. */
+    let fanoutTimedOut = false;
     try {
         const neighbors = await resolveBridgeNeighbors(handle, {
             localRepo: repoPath,
@@ -492,7 +540,18 @@ export async function runGroupImpact(deps, params) {
             if (seen.has(key))
                 continue;
             seen.add(key);
+            // Deterministic bound first: the count decides the cutoff on every host.
+            // Manifest-only crossings are exempt because they cost no `impactByUid`
+            // and dropping them regresses #2784.
+            if (!manifestOnly && attemptedFanouts >= MAX_NEIGHBOR_FANOUT) {
+                truncatedRepos.push(n.neighborRepo);
+                continue;
+            }
+            // Wall clock second, as a hang backstop only. It is load-dependent by
+            // construction, so when it is what fired the response must say `timeout`,
+            // not the generic `partial` it used to report.
             if (!manifestOnly && deadline - Date.now() <= 0) {
+                fanoutTimedOut = true;
                 truncatedRepos.push(n.neighborRepo);
                 continue;
             }
@@ -540,6 +599,7 @@ export async function runGroupImpact(deps, params) {
             // single hung neighbor would pin the request past the clamped
             // timeout, which Codex's adversarial review on PR #1331 flagged
             // as the still-open half of CodeQL #184 / js/resource-exhaustion.
+            attemptedFanouts += 1;
             const { value: fan, timedOut: neighborTimedOut } = await safeNeighborImpact(deps.port, neighborHandle.id, n.neighborUid, direction, {
                 maxDepth,
                 relationTypes: relationTypes ?? [],
@@ -547,6 +607,8 @@ export async function runGroupImpact(deps, params) {
                 includeTests,
             }, remainingMs);
             if (neighborTimedOut || fan == null) {
+                if (neighborTimedOut)
+                    fanoutTimedOut = true;
                 truncatedRepos.push(n.neighborRepo);
                 continue;
             }
@@ -576,7 +638,12 @@ export async function runGroupImpact(deps, params) {
         group: name,
         cross,
         outOfScope,
-        truncated,
+        // The risk VALUE is never clamped down. `mergeRisk` is monotone increasing
+        // in the traversed-crossing count, so truncation can only under-report —
+        // and under-reporting a blast radius is the unsafe direction (an agent told
+        // LOW proceeds; told CRITICAL it stops). Marking the floor keeps the
+        // warning intact while making the incompleteness legible.
+        ...truncationFields(truncated, fanoutTimedOut ? 'timeout' : 'partial'),
         truncatedRepos: [...new Set(truncatedRepos)],
         summary: {
             direct: localSum.direct ?? 0,
@@ -586,9 +653,11 @@ export async function runGroupImpact(deps, params) {
         },
         risk: mergeRisk(localRisk, cross),
         timeoutMs,
-        truncationReason: truncated ? 'partial' : undefined,
         crossDepthWarning,
     };
     return result;
 }
 export { normalizeServicePrefix, fileMatchesServicePrefix } from './group-path-utils.js';
+// Re-exported, not redefined: the single definition lives in lib/utils.ts, but
+// this module's own surface is what the #2787 regression test imports it from.
+export { compareCodeUnits };

package/dist/core/group/cross-trace.js

@@ -25,6 +25,7 @@
 import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
 import { getGroupDir } from './storage.js';
 import { ensureBridgeReady, MAX_SUPPORTED_CROSS_DEPTH } from './cross-impact.js';
+import { compareCodeUnits } from '../../lib/utils.js';
 import { closeBridgeDb, queryBridge } from './bridge-db.js';
 /**
  * Centralized degraded-state messages so wording stays consistent and
@@ -115,7 +116,7 @@ RETURN consumer.symbolUid AS consumerUid,
        l.confidence AS confidence,
        l.contractId AS contractId,
        consumer.type AS contractType
-ORDER BY l.confidence DESC
+ORDER BY l.confidence DESC, contractId, consumerUid, providerUid
 LIMIT ${MAX_CROSSINGS_TO_TRY + 1}
 `;
 // Destination trace: every ContractLink leaving a consumer repo, to ANY provider
@@ -136,7 +137,7 @@ RETURN consumer.symbolUid AS consumerUid,
        l.confidence AS confidence,
        l.contractId AS contractId,
        consumer.type AS contractType
-ORDER BY l.confidence DESC
+ORDER BY l.confidence DESC, contractId, consumerUid, providerUid
 LIMIT ${MAX_CROSSINGS_TO_TRY + 1}
 `;
 function rowToCrossing(r) {
@@ -164,6 +165,28 @@ function rowToCrossing(r) {
         contractType: String(r.contractType ?? r[7] ?? 'custom'),
     };
 }
+/**
+ * Sort a crossing list on the full crossing identity, then apply
+ * `MAX_CROSSINGS_TO_TRY`.
+ *
+ * Both bridge queries already order by confidence DESC; this re-sorts
+ * defensively so the cap keeps the strongest candidates even if a tuple-mode
+ * driver reorders rows. The comparator mirrors BOTH queries' `ORDER BY`
+ * key-for-key — a shorter comparator reproduces less than the order it is
+ * defending, leaving ties on raw row order (#2787) — so it lives in one place
+ * rather than being hand-synced across the two callers and two Cypher clauses.
+ */
+function capCrossings(all) {
+    all.sort((a, b) => b.confidence - a.confidence ||
+        compareCodeUnits(a.contractId, b.contractId) ||
+        compareCodeUnits(a.consumerUid, b.consumerUid) ||
+        compareCodeUnits(a.providerUid, b.providerUid));
+    const truncated = all.length > MAX_CROSSINGS_TO_TRY;
+    return {
+        crossings: truncated ? all.slice(0, MAX_CROSSINGS_TO_TRY) : all,
+        truncated,
+    };
+}
 async function listCrossingsBetween(handle, fromRepo, toRepo) {
     const rows = await queryBridge(handle, CY_CROSSINGS_BETWEEN, {
         fromRepo,
@@ -175,14 +198,7 @@ async function listCrossingsBetween(handle, fromRepo, toRepo) {
         if (c)
             all.push(c);
     }
-    // The query already orders by confidence DESC; re-sort defensively so the cap
-    // keeps the strongest candidates even if a tuple-mode driver reorders rows.
-    all.sort((a, b) => b.confidence - a.confidence);
-    const truncated = all.length > MAX_CROSSINGS_TO_TRY;
-    return {
-        crossings: truncated ? all.slice(0, MAX_CROSSINGS_TO_TRY) : all,
-        truncated,
-    };
+    return capCrossings(all);
 }
 function destRowToCrossing(r) {
     const consumerUid = String(r.consumerUid ?? r[0] ?? '');
@@ -212,12 +228,7 @@ async function listCrossingsFrom(handle, fromRepo) {
         if (c)
             all.push(c);
     }
-    all.sort((a, b) => b.confidence - a.confidence);
-    const truncated = all.length > MAX_CROSSINGS_TO_TRY;
-    return {
-        crossings: truncated ? all.slice(0, MAX_CROSSINGS_TO_TRY) : all,
-        truncated,
-    };
+    return capCrossings(all);
 }
 /**
  * Resolve a symbol query across every member repo. Exactly one `ok` match and

package/dist/core/group/extractors/http-route-extractor.js

@@ -89,6 +89,10 @@ RETURN sym.id AS uid, sym.name AS name, sym.filePath AS filePath,
 // degenerate edge-less node NOR inflates the uniqueness count and masks the real
 // handler. `LIMIT 2` bounds materialization: distinguishing unique (1) from
 // ambiguous (>=2) never needs more than two rows (the count guard stays exact).
+//
+// determinism: probe — uniqueness discriminator, not a window. `toResolvedSymbol`
+// reads row 0 only when `rows.length === 1`; a 2-row result is discarded whole,
+// so WHICH two rows came back can never reach a caller.
 export const RESOLVE_BY_NAME_QUERY = `
 MATCH (n) WHERE labels(n) IN ['Function','Method','CodeElement']
   AND n.name = $name AND n.filePath <> ''
@@ -100,6 +104,10 @@ LIMIT 2`;
 // the precise rung — it survives aliases and local same-name collisions that a
 // repo-wide name lookup cannot, and only resolves on a unique match within that
 // module. `LIMIT 2` keeps the uniqueness count exact (see RESOLVE_BY_NAME_QUERY).
+//
+// determinism: probe — uniqueness discriminator, not a window. Same consumer as
+// RESOLVE_BY_NAME_QUERY: `toResolvedSymbol` reads row 0 only when exactly one row
+// came back, and discards a 2-row result whole.
 export const RESOLVE_IN_MODULE_QUERY = `
 MATCH (n) WHERE labels(n) IN ['Function','Method','CodeElement']
   AND n.name = $name AND (n.filePath STARTS WITH $fileDot OR n.filePath STARTS WITH $fileSlash)