gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

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

@@ -16,8 +16,11 @@
  * router derives the label from the RAW id, while the oracle re-derives it via a
  * regex over the ESCAPED row — so for an id containing a `"` the router is the
  * more-correct path (it routes the edge to the right pair; the oracle's regex
- * mis-buckets or drops it). `splitRelCsvByLabelPair` is retained as the
- * differential oracle (the quote-in-id divergence is asserted explicitly).
+ * mis-buckets or drops it). Unlike the legacy oracle, the router also rejects a
+ * valid node-label pair absent from the relationship DDL. That distinction is
+ * load-bearing: silently writing such a CSV lets COPY fail late and can drop an
+ * otherwise valid edge during fallback. `splitRelCsvByLabelPair` is retained as
+ * the differential oracle (the quote-in-id divergence is asserted explicitly).
  *
  * Backpressure: at most one stream is awaited at a time (the caller routes
  * edges sequentially and awaits the returned drain promise before the next),
@@ -28,6 +31,24 @@ import path from 'path';
 import { createWriteStream } from 'fs';
 import { once } from 'events';
 import { finished } from 'stream/promises';
+import { NODE_TABLES } from '../../_shared/index.js';
+import { findInCauseChain } from '../../lib/utils.js';
+/**
+ * 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 const VALID_NODE_TABLES = new Set(NODE_TABLES);
 /**
  * Derive a node's table label from its graph id. Matches the legacy
  * `getNodeLabel` that lived inline in `loadGraphToLbug`:
@@ -42,6 +63,196 @@ export const getNodeLabel = (nodeId) => {
         return 'Process';
     return nodeId.split(':')[0];
 };
+/**
+ * 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 const relPairKeyFor = (fromId, toId, validTables) => {
+    const fromLabel = getNodeLabel(fromId);
+    const toLabel = getNodeLabel(toId);
+    if (!validTables.has(fromLabel) || !validTables.has(toLabel))
+        return undefined;
+    return `${fromLabel}|${toLabel}`;
+};
+/**
+ * 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 const splitRelPairKey = (key) => {
+    const sep = key.indexOf('|');
+    return sep < 0 ? [key, ''] : [key.slice(0, sep), key.slice(sep + 1)];
+};
+/**
+ * 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 const createRelationPairMatcher = () => /\bFROM\s+`?([A-Za-z][A-Za-z0-9_]*)`?\s+TO\s+`?([A-Za-z][A-Za-z0-9_]*)`?/g;
+/**
+ * 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.
+ */
+export const parseRelationSchemaPairs = (relationSchema) => new Set([...relationSchema.matchAll(createRelationPairMatcher())].map((match) => `${match[1]}|${match[2]}`));
+/**
+ * Best-effort source file for a graph node id.
+ *
+ * Node ids are `<Label>:<repo-relative path>:…` (`comm_*` / `proc_*` synthetic
+ * ids carry no file). Repo-relative paths are POSIX-normalized and never carry
+ * a drive letter, so the segment after the label is the file path. Returns
+ * `undefined` rather than guessing when the id has no path segment — a wrong
+ * file in a crash message is worse than none.
+ */
+const deriveNodeFilePath = (nodeId) => {
+    if (nodeId.startsWith('comm_') || nodeId.startsWith('proc_'))
+        return undefined;
+    const filePath = nodeId.split(':')[1];
+    return filePath === undefined || filePath === '' ? undefined : filePath;
+};
+/** Where a user files the missing pair. Part of the message — see below. */
+const UNDECLARED_PAIR_ISSUE_URL = 'https://github.com/abhigyanpatwari/GitNexus/issues/new';
+/**
+ * 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 class UndeclaredRelationPairError extends Error {
+    /** `From|To` label pair, exactly as keyed against the declared-pair set. */
+    pairKey;
+    /** Relationship type of the edge that could not be routed (e.g. `CALLS`). */
+    relationType;
+    fromId;
+    toId;
+    /** Source file derived from the node ids; `undefined` for synthetic ids. */
+    sourceFile;
+    constructor(pairKey, relationType, fromId, toId) {
+        const sourceFile = deriveNodeFilePath(fromId) ?? deriveNodeFilePath(toId);
+        const [fromLabel, toLabel] = splitRelPairKey(pairKey);
+        super(`GitNexus extracted a relationship its own database schema cannot store.\n` +
+            `Relationship label pair ${fromLabel} → ${toLabel} is not declared in the ` +
+            `LadybugDB relation schema.\n` +
+            `  relationship type: ${relationType}\n` +
+            `  from node:         ${fromId}\n` +
+            `  to node:           ${toId}\n` +
+            `  source file:       ${sourceFile ?? '(none — synthetic node id)'}\n` +
+            `This is a gap in GitNexus's own relation schema, not a problem with the ` +
+            `analyzed code, and re-running the analysis will fail in exactly the same place.\n` +
+            `Suggestions:\n` +
+            `  1. Report the missing pair so it can be declared:\n` +
+            `       ${UNDECLARED_PAIR_ISSUE_URL}\n` +
+            `     Include the label pair, the relationship type, and the source file above.\n` +
+            `  2. To finish indexing the rest meanwhile, add that file (or its directory)\n` +
+            `     to .gitnexusignore and re-run.`);
+        this.name = 'UndeclaredRelationPairError';
+        this.pairKey = pairKey;
+        this.relationType = relationType;
+        this.fromId = fromId;
+        this.toId = toId;
+        this.sourceFile = sourceFile;
+    }
+}
+/**
+ * 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 const findUndeclaredRelationPairError = (err) => findInCauseChain(err, (e) => e instanceof UndeclaredRelationPairError);
+/**
+ * Fail fast on an endpoint-label pair absent from the relationship DDL, the
+ * same guard `RelPairRouter.route` applies to the whole-graph emit. Exported
+ * so the streamed sinks (`GraphEmitSink`, `PdgEmitSink`) can apply it too —
+ * without this, an undeclared pair on a streaming run reaches `COPY`, fails
+ * 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 (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 const assertDeclaredPair = (pairKey, declaredPairs, relationType, fromId, toId) => {
+    if (!declaredPairs.has(pairKey)) {
+        throw new UndeclaredRelationPairError(pairKey, relationType, fromId, toId);
+    }
+};
 /**
  * Routes already-escaped relationship CSV rows to per-FROM→TO-label-pair
  * files. Filters edges whose endpoint labels are not valid node tables
@@ -51,6 +262,7 @@ export class RelPairRouter {
     csvDir;
     header;
     validTables;
+    declaredPairs;
     wsFactory;
     /** pairKey (`From|To`) → { csvPath, rows } */
     byPair = new Map();
@@ -59,10 +271,11 @@ export class RelPairRouter {
     total = 0;
     streamError = null;
     abort = new AbortController();
-    constructor(csvDir, header, validTables, wsFactory = (p) => createWriteStream(p, 'utf-8')) {
+    constructor(csvDir, header, validTables, declaredPairs, wsFactory = (p) => createWriteStream(p, 'utf-8')) {
         this.csvDir = csvDir;
         this.header = header;
         this.validTables = validTables;
+        this.declaredPairs = declaredPairs;
         this.wsFactory = wsFactory;
     }
     markError = (err) => {
@@ -83,21 +296,24 @@ export 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, toId, row) {
+    route(fromId, toId, row, relType) {
         if (this.streamError)
             throw this.streamError;
-        const fromLabel = getNodeLabel(fromId);
-        const toLabel = getNodeLabel(toId);
-        if (!this.validTables.has(fromLabel) || !this.validTables.has(toLabel)) {
+        const pairKey = relPairKeyFor(fromId, toId, this.validTables);
+        if (pairKey === undefined) {
             this.skipped++;
             return;
         }
-        const pairKey = `${fromLabel}|${toLabel}`;
+        assertDeclaredPair(pairKey, this.declaredPairs, relType, fromId, toId);
         const ws = this.streams.get(pairKey);
         if (ws === undefined) {
             // First edge for this pair: open the stream, write header + row.
-            return this.openAndWrite(pairKey, fromLabel, toLabel, row);
+            return this.openAndWrite(pairKey, row);
         }
         this.byPair.get(pairKey).rows++;
         this.total++;
@@ -105,7 +321,9 @@ export class RelPairRouter {
             return once(ws, 'drain', { signal: this.abort.signal }).then(() => undefined);
         }
     }
-    async openAndWrite(pairKey, fromLabel, toLabel, row) {
+    /** Cold: runs once per pair, so decoding the key back is free here. */
+    async openAndWrite(pairKey, row) {
+        const [fromLabel, toLabel] = splitRelPairKey(pairKey);
         const csvPath = path.join(this.csvDir, `rel_${fromLabel}_${toLabel}.csv`);
         const ws = this.wsFactory(csvPath);
         ws.on('error', this.markError);

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

@@ -14,7 +14,7 @@ export type { NodeTableName, RelType } from '../../_shared/index.js';
 export declare const FILE_SCHEMA = "\nCREATE NODE TABLE File (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  content STRING,\n  PRIMARY KEY (id)\n)";
 export declare const FOLDER_SCHEMA = "\nCREATE NODE TABLE Folder (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  PRIMARY KEY (id)\n)";
 export declare const FUNCTION_SCHEMA = "\nCREATE NODE TABLE Function (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
-export declare const CLASS_SCHEMA = "\nCREATE NODE TABLE Class (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
+export declare const CLASS_SCHEMA = "\nCREATE NODE TABLE Class (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  frameworkAnnotations STRING[],\n  PRIMARY KEY (id)\n)";
 export declare const INTERFACE_SCHEMA = "\nCREATE NODE TABLE Interface (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const METHOD_SCHEMA = "\nCREATE NODE TABLE Method (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  parameterCount INT32,\n  returnType STRING,\n  PRIMARY KEY (id)\n)";
 export declare const CODE_ELEMENT_SCHEMA = "\nCREATE NODE TABLE CodeElement (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  isExported BOOLEAN,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
@@ -32,7 +32,7 @@ export declare const TYPE_ALIAS_SCHEMA: string;
 export declare const CONST_SCHEMA: string;
 export declare const STATIC_SCHEMA: string;
 export declare const VARIABLE_SCHEMA: string;
-export declare const PROPERTY_SCHEMA = "\nCREATE NODE TABLE `Property` (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  content STRING,\n  description STRING,\n  declaredType STRING,\n  PRIMARY KEY (id)\n)";
+export declare const PROPERTY_SCHEMA = "\nCREATE NODE TABLE `Property` (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  content STRING,\n  description STRING,\n  declaredType STRING,\n  /*\n   * DETAIL SYMBOL \u2014 true when this property is a member of a shape that has no\n   * independent identity: the keys of an anonymous literal returned from a\n   * function (R3-4).\n   *\n   * It exists because indexing those keys is right for the GRAPH and wrong for\n   * TEXT SEARCH. They are ordinary words (message, value, timestamp) and\n   * there are many of them, so letting them into the FTS result set pushes the\n   * CALLABLES named after the same concept past the row cap the search applies\n   * \u2014 measured: query('message') went from two processes to none on the\n   * mini-repo fixture. A ranking tweak cannot fix that, because the rows never\n   * come back from the FTS call in the first place.\n   *\n   * So the search layer gained a notion it did not have \u2014 a symbol that is\n   * queryable, walkable and impact-analysable, but not a concept a text search\n   * should surface on its own. buildFtsQueryCypher excludes these for the\n   * Property table only; every other consumer sees them normally.\n   */\n  isDetail BOOLEAN,\n  PRIMARY KEY (id)\n)";
 export declare const RECORD_SCHEMA: string;
 export declare const DELEGATE_SCHEMA: string;
 export declare const ANNOTATION_SCHEMA: string;
@@ -43,7 +43,58 @@ export declare const ROUTE_SCHEMA = "\nCREATE NODE TABLE Route (\n  id STRING,\n
 export declare const TOOL_SCHEMA = "\nCREATE NODE TABLE Tool (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const SECTION_SCHEMA = "\nCREATE NODE TABLE Section (\n  id STRING,\n  name STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  level INT64,\n  content STRING,\n  description STRING,\n  PRIMARY KEY (id)\n)";
 export declare const BASICBLOCK_SCHEMA = "\nCREATE NODE TABLE BasicBlock (\n  id STRING,\n  filePath STRING,\n  startLine INT64,\n  endLine INT64,\n  text STRING,\n  callees STRING,\n  calleeIds STRING,\n  PRIMARY KEY (id)\n)";
-export declare const RELATION_SCHEMA = "\nCREATE REL TABLE CodeRelation (\n  FROM File TO File,\n  FROM File TO Folder,\n  FROM File TO Function,\n  FROM File TO Class,\n  FROM File TO Interface,\n  FROM File TO Method,\n  FROM File TO CodeElement,\n  FROM File TO `Struct`,\n  FROM File TO `Enum`,\n  FROM File TO `Macro`,\n  FROM File TO `Typedef`,\n  FROM File TO `Union`,\n  FROM File TO `Namespace`,\n  FROM File TO `Trait`,\n  FROM File TO `Impl`,\n  FROM File TO `TypeAlias`,\n  FROM File TO `Const`,\n  FROM File TO `Static`,\n  FROM File TO `Variable`,\n  FROM File TO `Property`,\n  FROM File TO `Record`,\n  FROM File TO `Delegate`,\n  FROM File TO `Annotation`,\n  FROM File TO `Constructor`,\n  FROM File TO `Template`,\n  FROM File TO `Module`,\n  FROM File TO Section,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO Function,\n  FROM Function TO Method,\n  FROM Function TO Class,\n  FROM Function TO Community,\n  FROM Function TO `Macro`,\n  FROM Function TO `Struct`,\n  FROM Function TO `Template`,\n  FROM Function TO `Enum`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `TypeAlias`,\n  FROM Function TO `Module`,\n  FROM Function TO `Impl`,\n  FROM Function TO Interface,\n  FROM Function TO `Constructor`,\n  FROM Function TO `Const`,\n  FROM Function TO `Typedef`,\n  FROM Function TO `Union`,\n  FROM Function TO `Property`,\n  FROM Function TO CodeElement,\n  FROM Class TO Method,\n  FROM Class TO Function,\n  FROM Class TO Class,\n  FROM Class TO Interface,\n  FROM Class TO Community,\n  FROM Class TO `Template`,\n  FROM Class TO `TypeAlias`,\n  FROM Class TO `Struct`,\n  FROM Class TO `Enum`,\n  FROM Class TO `Annotation`,\n  FROM Class TO `Constructor`,\n  FROM Class TO `Trait`,\n  FROM Class TO `Macro`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Union`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO `Property`,\n  FROM Method TO Function,\n  FROM Method TO Method,\n  FROM Method TO Class,\n  FROM Method TO Community,\n  FROM Method TO `Template`,\n  FROM Method TO `Struct`,\n  FROM Method TO `TypeAlias`,\n  FROM Method TO `Enum`,\n  FROM Method TO `Macro`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Module`,\n  FROM Method TO `Impl`,\n  FROM Method TO Interface,\n  FROM Method TO `Constructor`,\n  FROM Method TO `Property`,\n  FROM Method TO CodeElement,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO `Module`,\n  FROM Section TO Section,\n  FROM Section TO File,\n  FROM File TO Route,\n  FROM Function TO Route,\n  FROM Method TO Route,\n  FROM File TO Tool,\n  FROM Function TO Tool,\n  FROM Method TO Tool,\n  FROM CodeElement TO Community,\n  FROM Interface TO Community,\n  FROM Interface TO Function,\n  FROM Interface TO Method,\n  FROM Interface TO Class,\n  FROM Interface TO Interface,\n  FROM Interface TO `TypeAlias`,\n  FROM Interface TO `Struct`,\n  FROM Interface TO `Constructor`,\n  FROM Interface TO `Property`,\n  FROM `Struct` TO Community,\n  FROM `Struct` TO `Trait`,\n  FROM `Struct` TO `Struct`,\n  FROM `Struct` TO Class,\n  FROM `Struct` TO `Enum`,\n  FROM `Struct` TO Function,\n  FROM `Struct` TO Method,\n  FROM `Struct` TO Interface,\n  FROM `Struct` TO `Constructor`,\n  FROM `Struct` TO `Property`,\n  FROM `Enum` TO `Enum`,\n  FROM `Enum` TO Community,\n  FROM `Enum` TO Class,\n  FROM `Enum` TO Interface,\n  FROM `Macro` TO Community,\n  FROM `Macro` TO Function,\n  FROM `Macro` TO Method,\n  FROM `Module` TO Function,\n  FROM `Module` TO Method,\n  FROM `Typedef` TO Community,\n  FROM `Union` TO Community,\n  FROM `Namespace` TO Community,\n  FROM `Namespace` TO `Struct`,\n  FROM `Trait` TO Method,\n  FROM `Trait` TO `Constructor`,\n  FROM `Trait` TO `Property`,\n  FROM `Trait` TO Community,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO Community,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `TypeAlias` TO Community,\n  FROM `TypeAlias` TO `Trait`,\n  FROM `TypeAlias` TO Class,\n  FROM `Const` TO Community,\n  FROM `Static` TO Community,\n  FROM `Variable` TO Community,\n  FROM `Property` TO Community,\n  FROM `Record` TO Method,\n  FROM `Record` TO `Constructor`,\n  FROM `Record` TO `Property`,\n  FROM `Record` TO Community,\n  FROM `Delegate` TO Community,\n  FROM `Annotation` TO Community,\n  FROM `Constructor` TO Community,\n  FROM `Constructor` TO Interface,\n  FROM `Constructor` TO Class,\n  FROM `Constructor` TO Method,\n  FROM `Constructor` TO Function,\n  FROM `Constructor` TO `Constructor`,\n  FROM `Constructor` TO `Struct`,\n  FROM `Constructor` TO `Macro`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `TypeAlias`,\n  FROM `Constructor` TO `Enum`,\n  FROM `Constructor` TO `Annotation`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Module`,\n  FROM `Constructor` TO `Property`,\n  FROM `Constructor` TO `Typedef`,\n  FROM `Template` TO Community,\n  FROM `Module` TO Community,\n  FROM Function TO Process,\n  FROM Method TO Process,\n  FROM Class TO Process,\n  FROM Interface TO Process,\n  FROM `Struct` TO Process,\n  FROM `Constructor` TO Process,\n  FROM `Module` TO Process,\n  FROM `Macro` TO Process,\n  FROM `Impl` TO Process,\n  FROM `Typedef` TO Process,\n  FROM `TypeAlias` TO Process,\n  FROM `Enum` TO Process,\n  FROM `Union` TO Process,\n  FROM `Namespace` TO Process,\n  FROM `Trait` TO Process,\n  FROM `Const` TO Process,\n  FROM `Static` TO Process,\n  FROM `Variable` TO Process,\n  FROM `Property` TO Process,\n  FROM `Record` TO Process,\n  FROM `Delegate` TO Process,\n  FROM `Annotation` TO Process,\n  FROM `Template` TO Process,\n  FROM CodeElement TO Process,\n  FROM Route TO Process,\n  FROM Tool TO Process,\n  FROM BasicBlock TO BasicBlock,\n  type STRING,\n  confidence DOUBLE,\n  reason STRING,\n  step INT32\n)";
+/**
+ * The 69 pairs NEITHER rule above generates — everything left after the two
+ * cross products are subtracted. Carried by CONTAINMENT, inheritance, imports
+ * and DI: a container label crossed with a contained label. No predicate
+ * describes that surface (any container can hold any definition).
+ *
+ * What survives here is characteristic, not arbitrary. Almost all of it is a
+ * TARGET no rule reaches — `CodeElement`, `Impl`, `Namespace`, `Template`,
+ * `Typedef`, `Union`, `Static`, `Section`, `Folder` are in neither
+ * `SCOPE_BRIDGE_TARGET_LABELS` nor {@link ATTACHMENT_TARGET_LABELS} — plus the
+ * `Impl|*` and `Template|*` member rows (Rust `impl`/`trait` bodies, C++
+ * templates), the two `Route|Process` / `Tool|Process` entry points whose
+ * emitter names both labels as literals, and `BasicBlock|BasicBlock`, the PDG
+ * substrate.
+ *
+ * NOTHING A RULE ALREADY COVERS BELONGS HERE. `generatedRelationPairs` skips
+ * any pair present in this block, so a redundant line does not merely duplicate
+ * — it SUPPRESSES generation, and later narrowing a rule would silently keep
+ * that pair alive with no test failing. 166 such lines now live in the generated
+ * half (161 from #2793, the three `Record` member pairs moved by #2801/#2871,
+ * and the two `TypeAlias` pairs moved by R2-2 here);
+ * `test/unit/schema-pair-coverage.test.ts` now fails if one comes back.
+ *
+ * Those last two arrived by MERGE, and the shape is worth recording because it
+ * is the one this block's warning cannot catch by itself. #2871 and this branch
+ * each deleted their OWN label's hand-written pairs — `Record` there,
+ * `TypeAlias` here — for the identical reason, in the identical region. Git
+ * presents that as one conflict in which each side appears to be deleting the
+ * other's lines, and "keep ours" or "keep theirs" both resolve cleanly, compile,
+ * and silently re-suppress the other label's generation. The correct resolution
+ * is neither: take the UNION of the deletions. Verified by asserting all five
+ * pairs are still present in the emitted DDL — a check that does not read
+ * `LINKABLE_LABELS`, unlike the pair-coverage test, which derives both sides
+ * from it and so moves with any change to it.
+ *
+ * Folding this remainder into a third cross product
+ * (`DEFINITION_ANCHOR_LABELS × {CodeElement, Section, Typedef, Union,
+ * Namespace, Impl, TypeAlias, Static, Template}`) would take the table to 641
+ * pairs and leave only ~29 lines here. `bench/schema-pairs` measures 641 at
+ * 1.22–1.43× on the historical reference box; current production's 461 pairs
+ * remain below their 1.5× Windows budget. Those cross-machine values are not an
+ * ordering, so any proposal must remeasure both sizes on one box. Until then,
+ * the rule stays deferred rather than trading ~40 lines for unmeasured query cost.
+ *
+ * Exported so `test/unit/schema-pair-coverage.test.ts` can subtract it and
+ * assert the GENERATED region of the DDL for exact equality against the two
+ * rules, rather than one-directional containment.
+ * `test/integration/structural-pair-coverage.test.ts` guards this half from a
+ * corpus — that is the guard, not this comment.
+ */
+export declare const STRUCTURAL_PAIR_DDL = "  FROM File TO Folder,\n  FROM File TO CodeElement,\n  FROM File TO `Typedef`,\n  FROM File TO `Union`,\n  FROM File TO `Namespace`,\n  FROM File TO `Impl`,\n  FROM File TO `Static`,\n  FROM File TO `Template`,\n  FROM File TO Section,\n  FROM Folder TO Folder,\n  FROM Folder TO File,\n  FROM Function TO `Template`,\n  FROM Function TO `Namespace`,\n  FROM Function TO `Impl`,\n  FROM Function TO `Typedef`,\n  FROM Function TO `Union`,\n  FROM Function TO CodeElement,\n  FROM Class TO `Template`,\n  FROM Class TO `Impl`,\n  FROM Class TO `Union`,\n  FROM Class TO `Namespace`,\n  FROM Class TO `Typedef`,\n  FROM Class TO CodeElement,\n  FROM Method TO `Template`,\n  FROM Method TO `Namespace`,\n  FROM Method TO `Impl`,\n  FROM Method TO CodeElement,\n  FROM `Template` TO `Template`,\n  FROM `Template` TO Function,\n  FROM `Template` TO Method,\n  FROM `Template` TO Class,\n  FROM `Template` TO `Struct`,\n  FROM `Template` TO `TypeAlias`,\n  FROM `Template` TO `Enum`,\n  FROM `Template` TO `Macro`,\n  FROM `Template` TO Interface,\n  FROM `Template` TO `Constructor`,\n  FROM `Module` TO CodeElement,\n  FROM `Module` TO `Namespace`,\n  FROM `Namespace` TO Function,\n  FROM CodeElement TO CodeElement,\n  FROM CodeElement TO `Module`,\n  FROM CodeElement TO `Property`,\n  FROM Section TO Section,\n  FROM Interface TO CodeElement,\n  FROM `Namespace` TO `Struct`,\n  FROM `Impl` TO Method,\n  FROM `Impl` TO Function,\n  FROM `Impl` TO `Constructor`,\n  FROM `Impl` TO `Property`,\n  FROM `Impl` TO `Trait`,\n  FROM `Impl` TO `Struct`,\n  FROM `Impl` TO `Impl`,\n  FROM `Constructor` TO `Template`,\n  FROM `Constructor` TO `Impl`,\n  FROM `Constructor` TO `Namespace`,\n  FROM `Constructor` TO `Typedef`,\n  FROM Route TO Process,\n  FROM Tool TO Process,\n  FROM BasicBlock TO BasicBlock";
+export declare const RELATION_SCHEMA: string;
 export declare const EMBEDDING_DIMS: number;
 /** HNSW vector index name for the CodeEmbedding table. */
 export declare const EMBEDDING_INDEX_NAME = "code_embedding_idx";
@@ -61,3 +112,111 @@ export declare const CREATE_VECTOR_INDEX_QUERY = "\nCALL CREATE_VECTOR_INDEX('Co
 export declare const NODE_SCHEMA_QUERIES: string[];
 export declare const REL_SCHEMA_QUERIES: string[];
 export declare const SCHEMA_QUERIES: string[];
+/**
+ * Digest of the graph DDL this build creates — the exact statements
+ * {@link runSchemaCreationQueries} (lbug-adapter.ts) executes for the node and
+ * relation tables.
+ *
+ * This REPLACED `INCREMENTAL_SCHEMA_VERSION` (#2798), a hand-incremented
+ * integer in repo-manager.ts that had to PREDICT whether an on-disk database
+ * was created from this build's DDL. It could not: the number collided with
+ * `main` eight times, twice EXACTLY, and an exact clash was the quiet failure —
+ * two builds stamp the same number over different DDL, the strict `===` gate
+ * reads the index as current, every `CREATE … TABLE` is skipped as "already
+ * exists" (suppressed in `runSchemaCreationQueries`), and the edges whose
+ * endpoint pair the live DB cannot persist are dropped by
+ * `fallbackRelationshipInserts`' bare `catch`. A wrong graph, not an error.
+ *
+ * A digest cannot collide BY ACCIDENT at this scale: 12 hex chars is 48 bits,
+ * so even 1,000 distinct DDL variants over the project's whole life put the
+ * birthday probability of any pair matching at ≈1.8e-9. Two builds agree
+ * exactly when their DDL agrees, so concurrent branches never need renumbering.
+ * Do not shorten the slice: the odds double per bit dropped. On mismatch —
+ * including the ABSENT stamp every pre-#2798 index carries — run-analyze warns
+ * and forces a full re-analyze, which wipes the database and recreates the
+ * tables from the DDL below.
+ *
+ * {@link EMBEDDING_SCHEMA} is deliberately EXCLUDED. Its `FLOAT[N]` width comes
+ * from `GITNEXUS_EMBEDDING_DIMS` at module load, so folding it in would make
+ * this a function of the ENVIRONMENT rather than of code: two runs of the same
+ * build under different env would disagree and force alternating full rebuilds.
+ * Vector-column drift is therefore a SEPARATE gate, not an ungated hazard:
+ * {@link embeddingDimsMismatch} compares the width stamped in
+ * `RepoMeta.embeddingDims` against {@link EMBEDDING_DIMS} and run-analyze
+ * forces a rebuild on drift. Do not merge the two — an env-derived value in a
+ * code digest makes the same build disagree with itself. (The older reaction in
+ * run-analyze remains, and is to the CACHE, not the schema: when the cached
+ * vectors' length differs from `EMBEDDING_DIMS` it discards the cache and
+ * re-embeds.)
+ */
+export declare const SCHEMA_FINGERPRINT: string;
+/**
+ * Whether an index built under `recorded` can be reused by this build.
+ *
+ * Lives here rather than in run-analyze so the query side can ask the same
+ * question without importing the analyze pipeline — the reason
+ * `cjkSegmentationModeMismatch` sits in `core/search/` rather than beside its
+ * caller. ABSENT counts as a mismatch: that is the backward-compatibility path
+ * for every index written before the field existed, and grandfathering it would
+ * stamp a fresh fingerprint onto a database whose DDL was never verified.
+ */
+export declare const schemaFingerprintMismatch: (recorded: string | undefined) => boolean;
+/**
+ * Whether a stamped value has the shape {@link SCHEMA_FINGERPRINT} produces —
+ * the lowercase-hex prefix of a sha256 digest. The width is read from the live
+ * constant, so changing the slice above needs no edit here.
+ *
+ * Used to decide whether a stamp is worth NAMING in a diagnostic: an index with
+ * no fingerprint and one carrying a malformed value are both "not this build",
+ * but only the first has an explanation worth printing. Not a comparison gate —
+ * {@link schemaFingerprintMismatch} already rejects every value that is not
+ * exactly this build's.
+ */
+export declare const isSchemaFingerprintShaped: (value: unknown) => value is string;
+/**
+ * Whether the vector-column width an index's `CodeEmbedding` table was created
+ * at (as persisted in `RepoMeta.embeddingDims`) differs from the width this
+ * process would embed at ({@link EMBEDDING_DIMS}). The gate
+ * {@link SCHEMA_FINGERPRINT} deliberately cannot be: `FLOAT[N]` comes from
+ * `GITNEXUS_EMBEDDING_DIMS` at module load, so folding it into a digest of the
+ * DDL would make that digest a function of the ENVIRONMENT. Splitting it out
+ * here keeps the fingerprint purely code-derived and still gates the width —
+ * before this, flipping `GITNEXUS_EMBEDDING_DIMS` on a same-commit clean tree
+ * fired no guard at all: `alreadyUpToDate` returned over a `FLOAT[384]` table
+ * while the process embedded at 768. (The one pre-existing reaction, in
+ * run-analyze, discards the embedding CACHE and re-embeds — into a column whose
+ * width was never revisited.) A single scalar, so plain equality suffices.
+ *
+ * ABSENT does NOT count as a mismatch — the opposite of
+ * {@link schemaFingerprintMismatch}, and deliberately:
+ *
+ *  - Absence carries no signal about the width. A missing fingerprint means
+ *    "DDL this build cannot vouch for", and the field ships WITH a DDL change,
+ *    so absence is itself evidence of drift. A missing dims stamp means only
+ *    "written before the field existed"; the width was whatever that run's env
+ *    resolved, almost always the 384 default, and it was consistent with the
+ *    table it wrote. Drift needs the env to CHANGE, which absence says nothing
+ *    about.
+ *  - Forcing on absence would buy no safety anyway. Every index that lacks this
+ *    stamp also lacks `schemaFingerprint` (both landed together in #2798), and
+ *    that guard already forces a rebuild for exactly those indexes — after
+ *    which the width is stamped and the hazard is closed for good. A second
+ *    trigger for the same one rebuild is dead weight that would keep firing
+ *    forever on any future path that legitimately omits the stamp.
+ *  - The cost of guessing wrong is asymmetric: a fleet-wide full re-analyze
+ *    (minutes to hours per repo) for a hazard that requires a rare, deliberate
+ *    env change.
+ *
+ * Absence is precisely `undefined`. Any other recorded value that is not this
+ * build's width — including a malformed one, since `meta.json` is a schema-less
+ * `JSON.parse` of on-disk state — reads as a mismatch and errs toward a
+ * rebuild, which is the safe direction.
+ *
+ * Pure + exported for testing, and takes `current` explicitly rather than
+ * closing over {@link EMBEDDING_DIMS}: that constant is frozen at module load,
+ * so a parameter is the only way to exercise both sides of the comparison.
+ * Lives here rather than in run-analyze for the reason
+ * `cjkSegmentationModeMismatch` lives in `core/search/` — a caller that only
+ * needs the comparator should not have to pull in the analyze pipeline.
+ */
+export declare const embeddingDimsMismatch: (recorded: number | undefined, current: number) => boolean;