gitnexus 1.6.10-rc.147 → 1.6.10-rc.148

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/core/ingestion/scope-resolution/graph-bridge/ids.d.ts

@@ -19,6 +19,26 @@
 import type { NodeLabel, ParameterTypeClass, ScopeId, SymbolDefinition } from '../../../../_shared/index.js';
 import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js';
 import { type GraphNodeLookup } from '../graph-bridge/node-lookup.js';
+/**
+ * Labels that may legitimately ANCHOR a CALLS/ACCESSES edge as the
+ * source ("caller"). A Variable / Property can be the TARGET of an
+ * edge (e.g., a write-access to `user.name`), but it cannot be a
+ * caller — variables don't execute code, so attributing a call to a
+ * sibling Variable in the same scope produces nonsense edges like
+ * `Variable:create → Function:create` (which the simpleKey fallback
+ * in `resolveDefGraphId` then silently rewrites to
+ * `Function:create → Function:create`, a self-loop that doesn't exist
+ * in the source).
+ *
+ * Module-level call expressions inside a `const X = expr(args)`
+ * declaration are the canonical case where this used to fail: the
+ * walk-up over module scope's ownedDefs (only Variables) would land
+ * on the FIRST Variable, get name-aliased to its sibling Function
+ * with the same simple name, and emit a self-CALLS. With this label
+ * restricted to function/class-likes, those calls correctly fall
+ * through to the File-node fallback at the bottom of the walk.
+ */
+export declare const CALLER_ANCHOR_LABELS: ReadonlySet<NodeLabel>;
 export declare function resolveDefGraphId(filePath: string, def: {
     /** Scope-resolution def id — carries the declaration position (#2699). */
     nodeId?: string;

package/dist/core/ingestion/scope-resolution/graph-bridge/ids.js

@@ -41,15 +41,18 @@ import { definitionIdPosition } from '../utils/definition-id.js';
  * restricted to function/class-likes, those calls correctly fall
  * through to the File-node fallback at the bottom of the walk.
  */
+export const CALLER_ANCHOR_LABELS = new Set([
+    'Function',
+    'Method',
+    'Constructor',
+    'Module',
+    'Class',
+    'Interface',
+    'Struct',
+    'Enum',
+]);
 function isCallerAnchorLabel(label) {
-    return (label === 'Function' ||
-        label === 'Method' ||
-        label === 'Constructor' ||
-        label === 'Module' ||
-        label === 'Class' ||
-        label === 'Interface' ||
-        label === 'Struct' ||
-        label === 'Enum');
+    return CALLER_ANCHOR_LABELS.has(label);
 }
 function rangeContainsPoint(range, at) {
     if (at.startLine < range.startLine || at.startLine > range.endLine)

package/dist/core/ingestion/scope-resolution/graph-bridge/node-lookup.d.ts

@@ -75,4 +75,18 @@ export declare function localNameKey(filePath: string, label: NodeLabel, name: s
 /** Tombstone for a position claimed by two nodes — see `positionKey`. */
 export declare const AMBIGUOUS_POSITION = "";
 export declare function buildGraphNodeLookup(graph: KnowledgeGraph): GraphNodeLookup;
+/**
+ * Every label {@link buildGraphNodeLookup} registers — and therefore the ONLY
+ * labels `resolveDefGraphId` can ever return an id for. Both endpoints of every
+ * scope-resolution edge come from that lookup (the one exception is the File
+ * fallback in `resolveCallerGraphId`), so this set defines the whole FROM/TO
+ * surface those edges can produce.
+ *
+ * That makes it load-bearing for the LadybugDB relation DDL: a label added here
+ * without the matching `FROM x TO y` pairs in `RELATION_SCHEMA` crashes
+ * `analyze` at `assertDeclaredPair` on whichever codebase first emits the pair
+ * (#2792). `test/unit/schema-pair-coverage.test.ts` derives the required pairs
+ * from this set and fails in CI instead.
+ */
+export declare const LINKABLE_LABELS: ReadonlySet<NodeLabel>;
 export declare function isLinkableLabel(label: NodeLabel): boolean;

package/dist/core/ingestion/scope-resolution/graph-bridge/node-lookup.js

@@ -209,36 +209,52 @@ export function buildGraphNodeLookup(graph) {
     }
     return lookup;
 }
+/**
+ * Every label {@link buildGraphNodeLookup} registers — and therefore the ONLY
+ * labels `resolveDefGraphId` can ever return an id for. Both endpoints of every
+ * scope-resolution edge come from that lookup (the one exception is the File
+ * fallback in `resolveCallerGraphId`), so this set defines the whole FROM/TO
+ * surface those edges can produce.
+ *
+ * That makes it load-bearing for the LadybugDB relation DDL: a label added here
+ * without the matching `FROM x TO y` pairs in `RELATION_SCHEMA` crashes
+ * `analyze` at `assertDeclaredPair` on whichever codebase first emits the pair
+ * (#2792). `test/unit/schema-pair-coverage.test.ts` derives the required pairs
+ * from this set and fails in CI instead.
+ */
+export const LINKABLE_LABELS = new Set([
+    'Function',
+    'Method',
+    'Constructor',
+    // Program-like module declarations are provider-gated callable-value
+    // targets and need the same def→graph bridge.
+    'Module',
+    'Class',
+    'Interface',
+    'Struct',
+    'Enum',
+    // Trait nodes are linkable so MRO builders can bridge PHP/Rust trait
+    // defs between scope-resolution DefIds and the graph's node ids.
+    // IMPLEMENTS edges from classes to traits are otherwise invisible to
+    // the scope-resolution MRO pass.
+    'Trait',
+    // Variable / Property are linkable too — receiver-bound write/read
+    // ACCESSES edges target field nodes (e.g. `user.name = "x"` →
+    // ACCESSES edge to User's `name` Variable/Property node).
+    'Variable',
+    'Property',
+    // Const is linkable so the value-receiver-owner bridge in
+    // `receiver-bound-calls.ts` Case 5 can translate the scope-resolution
+    // `Variable` def for `export const fooService = {...}` to the canonical
+    // `Const:filePath:name` graph node id, against which object-literal
+    // method symbols register their `ownerId` (PR #1718 / issue #1358).
+    'Const',
+    // Macro nodes are linkable so a macro invocation (`log!(…)`) resolved
+    // via `MacroRegistry` can bridge its scope-resolution `Macro` def to
+    // the legacy `@definition.macro` graph node and emit the `USES` edge
+    // (Rust #1934 F72; also covers C/C++ `#define` macro defs).
+    'Macro',
+]);
 export function isLinkableLabel(label) {
-    return (label === 'Function' ||
-        label === 'Method' ||
-        label === 'Constructor' ||
-        // Program-like module declarations are provider-gated callable-value
-        // targets and need the same def→graph bridge.
-        label === 'Module' ||
-        label === 'Class' ||
-        label === 'Interface' ||
-        label === 'Struct' ||
-        label === 'Enum' ||
-        // Trait nodes are linkable so MRO builders can bridge PHP/Rust trait
-        // defs between scope-resolution DefIds and the graph's node ids.
-        // IMPLEMENTS edges from classes to traits are otherwise invisible to
-        // the scope-resolution MRO pass.
-        label === 'Trait' ||
-        // Variable / Property are linkable too — receiver-bound write/read
-        // ACCESSES edges target field nodes (e.g. `user.name = "x"` →
-        // ACCESSES edge to User's `name` Variable/Property node).
-        label === 'Variable' ||
-        label === 'Property' ||
-        // Const is linkable so the value-receiver-owner bridge in
-        // `receiver-bound-calls.ts` Case 5 can translate the scope-resolution
-        // `Variable` def for `export const fooService = {...}` to the canonical
-        // `Const:filePath:name` graph node id, against which object-literal
-        // method symbols register their `ownerId` (PR #1718 / issue #1358).
-        label === 'Const' ||
-        // Macro nodes are linkable so a macro invocation (`log!(…)`) resolved
-        // via `MacroRegistry` can bridge its scope-resolution `Macro` def to
-        // the legacy `@definition.macro` graph node and emit the `USES` edge
-        // (Rust #1934 F72; also covers C/C++ `#define` macro defs).
-        label === 'Macro');
+    return LINKABLE_LABELS.has(label);
 }

package/dist/core/lbug/csv-generator.js

@@ -14,8 +14,8 @@
 import fs from 'fs/promises';
 import { createWriteStream } from 'fs';
 import path from 'path';
-import { NODE_TABLES, RELATION_SCHEMA } from './schema.js';
-import { parseRelationSchemaPairs, RelPairRouter } from './rel-pair-routing.js';
+import { RELATION_SCHEMA } from './schema.js';
+import { VALID_NODE_TABLES, parseRelationSchemaPairs, RelPairRouter } from './rel-pair-routing.js';
 import { parseTruthyEnv } from '../ingestion/utils/env.js';
 import { SYMBOL_NODE_LABELS } from '../ingestion/utils/symbol-labels.js';
 import { applyCjkSegmentationIfEnabled } from '../search/cjk-segmentation.js';
@@ -662,11 +662,11 @@ export const streamAllCSVsToDisk = async (graph, repoPath, csvDir, onNodePhaseCo
         // read once instead of twice. The router applies the SAME label-derivation +
         // validTables filter as the legacy splitRelCsvByLabelPair, so the per-pair
         // files are byte-identical (asserted by the differential test).
-        const relRouter = new RelPairRouter(csvDir, REL_CSV_HEADER, new Set(NODE_TABLES), DECLARED_RELATION_PAIRS);
+        const relRouter = new RelPairRouter(csvDir, REL_CSV_HEADER, VALID_NODE_TABLES, DECLARED_RELATION_PAIRS);
         try {
             let emitted = 0;
             for (const rel of orderedRelationships(graph, sortOutput)) {
-                const pending = relRouter.route(rel.sourceId, rel.targetId, buildRelRow(rel));
+                const pending = relRouter.route(rel.sourceId, rel.targetId, buildRelRow(rel), rel.type);
                 if (pending)
                     await pending;
                 // Periodically hand the event loop back so the overlapped node COPY and

package/dist/core/lbug/graph-emit-sink.d.ts

@@ -81,7 +81,6 @@ export declare class GraphEmitSink implements KnowledgeGraph, GraphEmitControl {
     private readonly real;
     private readonly csvDir;
     private readonly chunkRows;
-    private readonly validTables;
     private readonly relWriters;
     /**
      * Ids of relationships already streamed. `KnowledgeGraph.addRelationship`

package/dist/core/lbug/graph-emit-sink.js

@@ -85,17 +85,17 @@
  * ## Correctness contract
  *
  * Structural sibling of {@link PdgEmitSink}, and reuses its row builder
- * (`buildRelRow`), header (`REL_CSV_HEADER`), label derivation (`getNodeLabel`)
- * and `RelPairRouter` validity check, so the streamed row SET equals the
- * whole-graph emit's and the bulk COPY loads the same rows. Set-level, not
+ * (`buildRelRow`), header (`REL_CSV_HEADER`) and pair classification
+ * (`relPairKeyFor`, which is also what `RelPairRouter` routes and skips by), so
+ * the streamed row SET equals the whole-graph emit's and the bulk COPY loads
+ * the same rows. Set-level, not
  * byte-level: rows stream in emit order and are not re-sorted under
  * `GITNEXUS_SORT_GRAPH_OUTPUT`.
  */
 import fs from 'fs';
 import path from 'path';
 import { DECLARED_RELATION_PAIRS, REL_CSV_HEADER, buildRelRow } from './csv-generator.js';
-import { assertDeclaredPair, getNodeLabel } from './rel-pair-routing.js';
-import { NODE_TABLES } from './schema.js';
+import { VALID_NODE_TABLES, assertDeclaredPair, relPairKeyFor, splitRelPairKey, } from './rel-pair-routing.js';
 import { DEFAULT_EMIT_CHUNK_ROWS, SyncCsvWriter } from './sync-csv-writer.js';
 /**
  * Relationship types that MUST stay in the in-memory graph because a phase
@@ -200,7 +200,6 @@ export class GraphEmitSink {
     real;
     csvDir;
     chunkRows;
-    validTables;
     relWriters = new Map();
     /**
      * Ids of relationships already streamed. `KnowledgeGraph.addRelationship`
@@ -272,7 +271,6 @@ export class GraphEmitSink {
         this.real = real;
         this.csvDir = csvDir;
         this.chunkRows = chunkRows;
-        this.validTables = new Set(NODE_TABLES);
         // Own directory, distinct from the PDG sink's: PdgEmitSink wipes and
         // recreates its dir on construction and opens with O_EXCL, so a shared dir
         // would destroy the other sink's manifest on a combined --pdg run.
@@ -367,16 +365,18 @@ export class GraphEmitSink {
             return;
         }
         // Mirror KnowledgeGraph.addRelationship's first-writer-wins dedup.
-        const fromLabel = getNodeLabel(relationship.sourceId);
-        const toLabel = getNodeLabel(relationship.targetId);
-        // Skip edges whose endpoint labels are not valid node tables — mirrors
-        // `RelPairRouter` exactly so the streamed set matches the whole-graph set.
-        if (!this.validTables.has(fromLabel) || !this.validTables.has(toLabel))
+        // Classify + skip via the SHARED `relPairKeyFor`, not a local copy of its
+        // three lines, so the streamed set cannot drift from the whole-graph set
+        // `RelPairRouter` produces. `undefined` = an endpoint label is not a node
+        // table, so the edge is dropped exactly as the router drops it.
+        const pairKey = relPairKeyFor(relationship.sourceId, relationship.targetId, VALID_NODE_TABLES);
+        if (pairKey === undefined)
             return;
-        const pairKey = `${fromLabel}|${toLabel}`;
-        assertDeclaredPair(pairKey, DECLARED_RELATION_PAIRS);
+        assertDeclaredPair(pairKey, DECLARED_RELATION_PAIRS, relationship.type, relationship.sourceId, relationship.targetId);
         let writer = this.relWriters.get(pairKey);
         if (writer === undefined) {
+            // Cold: once per pair, so decoding the key back into its labels is free.
+            const [fromLabel, toLabel] = splitRelPairKey(pairKey);
             try {
                 writer = new SyncCsvWriter(path.join(this.csvDir, `rel_${fromLabel}_${toLabel}.csv`), REL_CSV_HEADER, this.chunkRows);
             }

package/dist/core/lbug/pdg-emit-sink.d.ts

@@ -24,8 +24,8 @@
  * `storage/parsedfile-store.ts`.
  *
  * Byte-identity (issue acceptance): the sink reuses the SAME shared row
- * builders (`buildBasicBlockRow`, `buildRelRow`) and label derivation
- * (`getNodeLabel`) as `streamAllCSVsToDisk`, so the streamed CSV line SET is
+ * builders (`buildBasicBlockRow`, `buildRelRow`) and pair classification
+ * (`relPairKeyFor`) as `streamAllCSVsToDisk`, so the streamed CSV line SET is
  * identical to the whole-graph emit's, and the bulk COPY loads the same rows →
  * the persisted graph is SET-identical and DB-identical. The guarantee is
  * set-level, not byte-level on the CSV file: the sink streams rows in emit
@@ -76,7 +76,6 @@ export declare class PdgEmitSink implements KnowledgeGraph {
     private readonly real;
     private readonly pdgCsvDir;
     private readonly chunkRows;
-    private readonly validTables;
     private bbWriter;
     /** pairKey (`From|To`) → writer. PDG edges are all `BasicBlock|BasicBlock`,
      *  but the map keeps the sink general and the manifest pair-keyed. */

package/dist/core/lbug/pdg-emit-sink.js

@@ -24,8 +24,8 @@
  * `storage/parsedfile-store.ts`.
  *
  * Byte-identity (issue acceptance): the sink reuses the SAME shared row
- * builders (`buildBasicBlockRow`, `buildRelRow`) and label derivation
- * (`getNodeLabel`) as `streamAllCSVsToDisk`, so the streamed CSV line SET is
+ * builders (`buildBasicBlockRow`, `buildRelRow`) and pair classification
+ * (`relPairKeyFor`) as `streamAllCSVsToDisk`, so the streamed CSV line SET is
  * identical to the whole-graph emit's, and the bulk COPY loads the same rows →
  * the persisted graph is SET-identical and DB-identical. The guarantee is
  * set-level, not byte-level on the CSV file: the sink streams rows in emit
@@ -45,9 +45,8 @@
 import fs from 'fs';
 import path from 'path';
 import { BASICBLOCK_CSV_HEADER, DECLARED_RELATION_PAIRS, REL_CSV_HEADER, buildBasicBlockRow, buildRelRow, } from './csv-generator.js';
-import { assertDeclaredPair, getNodeLabel } from './rel-pair-routing.js';
+import { VALID_NODE_TABLES, assertDeclaredPair, relPairKeyFor, splitRelPairKey, } from './rel-pair-routing.js';
 import { DEFAULT_EMIT_CHUNK_ROWS, SyncCsvWriter } from './sync-csv-writer.js';
-import { NODE_TABLES } from './schema.js';
 /**
  * PDG edge types streamed per-file (all intra-block BasicBlock→BasicBlock).
  * `TAINT_PATH` is intentionally excluded — it is the whole-program M4 edge
@@ -76,7 +75,6 @@ export class PdgEmitSink {
     real;
     pdgCsvDir;
     chunkRows;
-    validTables;
     bbWriter;
     /** pairKey (`From|To`) → writer. PDG edges are all `BasicBlock|BasicBlock`,
      *  but the map keeps the sink general and the manifest pair-keyed. */
@@ -105,7 +103,6 @@ export class PdgEmitSink {
         this.real = real;
         this.pdgCsvDir = pdgCsvDir;
         this.chunkRows = chunkRows;
-        this.validTables = new Set(NODE_TABLES);
         // Clear any streamed CSVs left by a previous (possibly crashed) run so a
         // later COPY never picks up stale rows.
         fs.rmSync(pdgCsvDir, { recursive: true, force: true });
@@ -130,16 +127,18 @@ export class PdgEmitSink {
     }
     addRelationship(relationship) {
         if (PDG_EDGE_TYPES.has(relationship.type)) {
-            const fromLabel = getNodeLabel(relationship.sourceId);
-            const toLabel = getNodeLabel(relationship.targetId);
-            // Skip edges whose endpoint labels are not valid node tables — mirrors
-            // `RelPairRouter` exactly so the streamed set matches the whole-graph set.
-            if (!this.validTables.has(fromLabel) || !this.validTables.has(toLabel))
+            // Classify + skip via the SHARED `relPairKeyFor`, not a local copy of its
+            // three lines, so the streamed set cannot drift from the whole-graph set
+            // `RelPairRouter` produces. `undefined` = an endpoint label is not a node
+            // table, so the edge is dropped exactly as the router drops it.
+            const pairKey = relPairKeyFor(relationship.sourceId, relationship.targetId, VALID_NODE_TABLES);
+            if (pairKey === undefined)
                 return;
-            const pairKey = `${fromLabel}|${toLabel}`;
-            assertDeclaredPair(pairKey, DECLARED_RELATION_PAIRS);
+            assertDeclaredPair(pairKey, DECLARED_RELATION_PAIRS, relationship.type, relationship.sourceId, relationship.targetId);
             let writer = this.relWriters.get(pairKey);
             if (writer === undefined) {
+                // Cold: once per pair, so decoding the key back into labels is free.
+                const [fromLabel, toLabel] = splitRelPairKey(pairKey);
                 try {
                     writer = new SyncCsvWriter(path.join(this.pdgCsvDir, `rel_${fromLabel}_${toLabel}.csv`), REL_CSV_HEADER, this.chunkRows);
                 }

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

@@ -1,6 +1,22 @@
 import { type WriteStream } from 'fs';
 /** Injectable for tests (backpressure/error simulation), mirroring split. */
 export type WriteStreamFactory = (filePath: string) => WriteStream;
+/**
+ * Every label LadybugDB has a node table for — the filter that decides whether
+ * an edge is routable at all.
+ *
+ * ONE shared instance, deliberately. `RelPairRouter`, `GraphEmitSink` and
+ * `PdgEmitSink` each used to build their own `new Set(NODE_TABLES)`; three
+ * copies of the same immutable set are three chances to seed one of them from
+ * a different source. Typed `ReadonlySet` because that — not `Object.freeze`,
+ * which does not touch a Set's internal slots — is what actually stops a
+ * consumer mutating the shared instance.
+ *
+ * Imported straight from `gitnexus-shared` rather than `./schema.js`: schema.ts
+ * imports `parseRelationSchemaPairs` from this module, so the reverse import
+ * would close a cycle.
+ */
+export declare const VALID_NODE_TABLES: ReadonlySet<string>;
 /**
  * Derive a node's table label from its graph id. Matches the legacy
  * `getNodeLabel` that lived inline in `loadGraphToLbug`:
@@ -9,18 +25,125 @@ export type WriteStreamFactory = (filePath: string) => WriteStream;
  *   - otherwise the prefix before the first `:` (e.g. `Function:…` → Function)
  */
 export declare const getNodeLabel: (nodeId: string) => string;
+/**
+ * Classify one edge into its `From|To` pair key, or `undefined` when the edge
+ * must be SKIPPED because an endpoint's label is not a real node table.
+ *
+ * THE single definition of "which pair does this edge belong to, and is it
+ * routable at all". `RelPairRouter.route`, `GraphEmitSink.addRelationship`,
+ * `PdgEmitSink.addRelationship` and the `structural-pair-coverage` corpus guard
+ * each used to inline the same three lines (label both ends → drop if either
+ * label is not a node table → join with `|`). The corpus guard's docblock said
+ * it "mirrors `RelPairRouter.route`" — a mirror is a drift marker: change the
+ * skip rule here and the guard would keep classifying by the old one, report
+ * green, and let `analyze` abort on a pair it had already declared covered.
+ *
+ * HOT PATH — called once per edge (~1M on a large repo). Returns the key
+ * string (which every caller needs anyway for its own Map lookup) rather than
+ * a `{ pairKey, fromLabel, toLabel }` object or a tuple, so the success path
+ * allocates nothing beyond what `getNodeLabel` already did. Callers that need
+ * the two labels back — only when opening a new pair's CSV, once per pair —
+ * decode the key with {@link splitRelPairKey}.
+ */
+export declare const relPairKeyFor: (fromId: string, toId: string, validTables: ReadonlySet<string>) => string | undefined;
+/**
+ * Decode a `From|To` pair key back into its two labels.
+ *
+ * Safe because `|` cannot occur inside a node label: every label is a
+ * `NODE_TABLES` identifier (`[A-Za-z][A-Za-z0-9_]*`), so the FIRST `|` is
+ * always the separator. That invariant was documented in one comment and
+ * enforced nowhere while every consumer re-derived it with a bare
+ * `key.split('|')`.
+ *
+ * DECODE ONLY — there is deliberately no matching `encode` helper. The key is
+ * built once per edge inside {@link relPairKeyFor} (~1M edges on a large
+ * repo), where a function call is a real regression risk; every decode site is
+ * cold by construction (once per pair when its CSV is opened, or on the
+ * throw path of {@link assertDeclaredPair}).
+ */
+export declare const splitRelPairKey: (key: string) => readonly [from: string, to: string];
+/**
+ * Build a fresh matcher for the `FROM <label> TO <label>` clauses of a
+ * relationship DDL. Capture group 1 is the FROM label, group 2 the TO label;
+ * backticks quote schema labels and are not part of the graph label.
+ *
+ * THE SINGLE SOURCE OF TRUTH for that pattern. `parseRelationSchemaPairs`
+ * below builds its pair set from it, and `test/unit/schema-pair-coverage.test.ts`
+ * counts raw `FROM…TO` occurrences with it to catch a pair DUPLICATED in the
+ * DDL (a duplicate makes LadybugDB reject `CREATE REL TABLE`, killing every
+ * `analyze` — strictly worse than one missing pair). That guard used to inline
+ * its own copy of the regex: the two matched identically, so it worked, but any
+ * widening here (dotted identifiers, `IF NOT EXISTS`, a multi-target
+ * `FROM x TO y, z` form) would have silently degraded it to the tautology
+ * `declared.size === declared.size`. Consume this factory instead of
+ * re-inlining a copy.
+ *
+ * A FACTORY, not a shared `RegExp`: a module-level `/g` regex carries
+ * `lastIndex` between calls, so one consumer's `exec`/`test` would corrupt
+ * everyone else's next match. Each call returns a private instance.
+ */
+export declare const createRelationPairMatcher: () => RegExp;
 /**
  * Extract the FROM→TO pairs accepted by a relationship DDL.
  *
  * This belongs at the routing boundary: schema.ts owns the DDL, while the CSV
  * router owns the fail-fast check that prevents writing a pair LadybugDB cannot
- * COPY. Backticks quote schema labels and are not part of the graph label.
+ * COPY.
  */
 export declare const parseRelationSchemaPairs: (relationSchema: string) => ReadonlySet<string>;
 export interface RelPairMeta {
     csvPath: string;
     rows: number;
 }
+/**
+ * An edge whose endpoint-label pair is absent from the relationship DDL.
+ *
+ * Carries the context the emit call site already has — relationship type, both
+ * node ids, and the source file derived from them — so a user whose `analyze`
+ * just died mid-run can see WHICH of their files produced the edge and file a
+ * bug report that names the missing pair. The abstract label pair alone is
+ * unactionable outside GitNexus's own source (#2789).
+ *
+ * Classify by TYPE (`err instanceof UndeclaredRelationPairError`, or
+ * {@link findUndeclaredRelationPairError} when the error may be wrapped in a
+ * phase `cause` chain) — the repo norm from #2385 — never by message text.
+ *
+ * THE MESSAGE IS THE ONLY RENDERING. It carries the five context fields AND
+ * the two actionable next steps (report the pair; `.gitnexusignore` the file to
+ * finish the rest of the index), because `gitnexus serve` forwards nothing but
+ * `err.message` over worker IPC — anything a consumer re-renders from the
+ * structured fields instead is invisible to a serve-hosted user. The CLI
+ * branch in `cli/analyze.ts` therefore prints this message indented and adds
+ * only the machine-readable `cliError` fields, the same idiom `LbugWipeError`
+ * uses there. It used to re-render the five fields with its own wording; the
+ * two copies had already drifted on the pair separator, the no-file text and
+ * the closing sentence within a single PR, and each had its own pinning test.
+ */
+export declare class UndeclaredRelationPairError extends Error {
+    /** `From|To` label pair, exactly as keyed against the declared-pair set. */
+    readonly pairKey: string;
+    /** Relationship type of the edge that could not be routed (e.g. `CALLS`). */
+    readonly relationType: string;
+    readonly fromId: string;
+    readonly toId: string;
+    /** Source file derived from the node ids; `undefined` for synthetic ids. */
+    readonly sourceFile: string | undefined;
+    constructor(pairKey: string, relationType: string, fromId: string, toId: string);
+}
+/**
+ * Find an {@link UndeclaredRelationPairError} in `err` or its `cause` chain.
+ *
+ * The guard throws deep inside an ingestion phase, and the phase runner rewraps
+ * every phase failure as `new Error("Phase 'X' failed: …", { cause })` — so a
+ * bare `instanceof` at the CLI boundary would miss it and fall through to the
+ * generic stack dump.
+ *
+ * The traversal and its depth bound come from `lib/utils.ts` rather than being
+ * re-rolled here: this was the fourth hand-written copy in the repo and the
+ * only one that used `depth <= MAX` (six levels) while claiming to mirror
+ * `cli/analyze.ts`'s `depth < 5`.
+ */
+export declare const findUndeclaredRelationPairError: (err: unknown) => UndeclaredRelationPairError | undefined;
 /**
  * Fail fast on an endpoint-label pair absent from the relationship DDL, the
  * same guard `RelPairRouter.route` applies to the whole-graph emit. Exported
@@ -29,14 +152,19 @@ export interface RelPairMeta {
  * the bulk insert, and is silently dropped by the per-edge fallback instead
  * of failing loudly like the non-streaming path does.
  *
- * Takes the already-built `From|To` pairKey rather than the two labels — every
- * caller needs that same key immediately after for its own Map/stream lookup,
- * and this is on the per-edge hot path, so building it twice would be a
- * needless allocation per edge. `|` cannot appear inside a label (node labels
- * are `NODE_TABLES` identifiers), so splitting it back apart for the error
- * message is safe.
+ * Takes the already-built `From|To` pairKey (from {@link relPairKeyFor})
+ * rather than the two labels — every caller needs that same key immediately
+ * after for its own Map/stream lookup, and this is on the per-edge hot path,
+ * so building it twice would be a needless allocation per edge. The error
+ * splits it back apart with {@link splitRelPairKey}, which only the throw path
+ * reaches. The edge context is passed POSITIONALLY for the same reason: a
+ * `{ relationType, fromId, toId }` context object would allocate on every
+ * edge, including the ~1M that never fail.
+ *
+ * The success path must stay allocation-free: no object literal, no template
+ * string, no closure, no `Error` constructed before the failure branch.
  */
-export declare const assertDeclaredPair: (pairKey: string, declaredPairs: ReadonlySet<string>) => void;
+export declare const assertDeclaredPair: (pairKey: string, declaredPairs: ReadonlySet<string>, relationType: string, fromId: string, toId: string) => void;
 /**
  * Routes already-escaped relationship CSV rows to per-FROM→TO-label-pair
  * files. Filters edges whose endpoint labels are not valid node tables
@@ -55,7 +183,7 @@ export declare class RelPairRouter {
     total: number;
     private streamError;
     private readonly abort;
-    constructor(csvDir: string, header: string, validTables: Set<string>, declaredPairs: ReadonlySet<string>, wsFactory?: WriteStreamFactory);
+    constructor(csvDir: string, header: string, validTables: ReadonlySet<string>, declaredPairs: ReadonlySet<string>, wsFactory?: WriteStreamFactory);
     private markError;
     /**
      * The first stream error observed, if any. Lets the emit caller rethrow the
@@ -69,8 +197,13 @@ export declare class RelPairRouter {
      * Returns `void` on the synchronous hot path; a `Promise<void>` only when a
      * stream signals backpressure (or a new pair's header does) — the caller
      * awaits the promise before routing the next edge.
+     *
+     * `relType` is not used for routing — it is carried purely so an undeclared
+     * pair can name the offending relationship in its error (the row is already
+     * CSV-escaped by then, so the type is not recoverable from it).
      */
-    route(fromId: string, toId: string, row: string): void | Promise<void>;
+    route(fromId: string, toId: string, row: string, relType: string): void | Promise<void>;
+    /** Cold: runs once per pair, so decoding the key back is free here. */
     private openAndWrite;
     /** Flush + close every pair stream. Rejects if any stream errored. */
     close(): Promise<void>;