From b5d358f5005fc589e9a6d4165cce739698080530 Mon Sep 17 00:00:00 2001
From: Randy Wilson <phoenixrr2113@gmail.com>
Date: Fri, 21 Aug 2026 19:14:06 -0400
Subject: [PATCH 1/4] Give every symbol a real identity and kill the zombie
 nodes for good

Symbol identity is no longer a line number in disguise. Every Function,
Class, Interface, Variable, Type, and Component now carries an opaque
sym:v1 id hashed from its label, normalized path, lexical scope chain,
declared name, and disambiguator, with length-prefixed encoding so no
name or path can collide. Line numbers become mutable properties:
editing a file no longer changes what a symbol IS.

Scope is part of identity: members carry their owner chain, nested
declarations their lexical chain, overloads a signature hash (class
method overload declarations are now extracted at all, with calls
binding to the one runtime implementation), declaration-merged forms
share one id, and true duplicates fall back to a bounded ordinal.

The pipeline builds a project symbol catalog and resolves every edge to
endpoint ids before writing; unresolved edges are dropped, never
guessed. The graph merges by id, sweeps stale ids from changed files
even when inbound edges pin them, notices deleted files by
set-difference, and deletes projects by ownership stamp instead of
reachability, so force reindex genuinely resets. Ids flow unchanged
through search (including the no-embedding text fallback), references,
file relationships, embeddings, and the dashboard, which no longer
synthesizes ids at all. Legacy idless knowledge entities are backfilled
on write and tolerated on read.

The proof the whole campaign was building toward now passes: shift a
function with inbound CALLS and IMPORTS_SYMBOL edges down the file,
reindex incrementally, and it is still one node with the same id, a new
line number, and both edges intact. Two adversarial review rounds drove
out six defects before merge, four of them integration seams between
individually verified components.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../api/src/__tests__/graph-route.test.ts     |   22 +-
 .../api/src/__tests__/search-route.test.ts    |   57 +-
 packages/api/src/routes/graph.ts              |   32 +-
 packages/api/src/routes/search.ts             |    6 +-
 .../dependency-depth.integration.test.ts      |   18 +-
 .../src/__tests__/embed-pass-node-id.test.ts  |   89 ++
 .../enrich-from-graph.integration.test.ts     |   24 +-
 .../__tests__/enriched-search-node-id.test.ts |   41 +
 .../indexer-deleted-file.integration.test.ts  |  124 ++
 ...r-overload-call-target.integration.test.ts |  102 ++
 ...er-single-file-preserves-file-node.test.ts |    4 +
 .../src/__tests__/linked-knowledge.test.ts    |   14 +-
 .../src/__tests__/neighbor-expansion.test.ts  |   24 +-
 .../__tests__/node-identity-catalog.test.ts   |   50 +
 ...de-identity-final-gate.integration.test.ts |  206 ++++
 .../pipeline-barrel-resolution.test.ts        |   87 +-
 ...e-exports-and-imports-symbol-edges.test.ts |   17 +-
 .../pipeline-python-cross-file-calls.test.ts  |   47 +-
 .../pipeline-python-review-wave-b.test.ts     |   78 +-
 ...peline-tier2-ruby-calls-regression.test.ts |   11 +-
 packages/core/src/__tests__/service.test.ts   |   32 +-
 .../src/__tests__/services-helpers.test.ts    |   17 +-
 packages/core/src/embed-nodes.ts              |   42 +-
 packages/core/src/embed-pass.ts               |   17 +-
 packages/core/src/enrichedSearchV2.ts         |  149 ++-
 packages/core/src/indexer.ts                  |  138 ++-
 packages/core/src/pipeline/pipeline.ts        |  405 ++++++-
 .../core/src/services/graph-data-service.ts   |   34 +-
 packages/core/src/services/helpers.ts         |    5 +-
 .../src/components/dashboard/app-shell.tsx    |   53 +-
 .../components/dashboard/entity-detail.tsx    |    7 +-
 .../dashboard/explorer-navigation.test.tsx    |   42 +-
 .../src/components/dashboard/graph-canvas.tsx |   44 +-
 .../dashboard/graph-explorer.test.tsx         |    4 +-
 .../node-identity-source-guard.test.ts        |   24 +
 .../dashboard/search-panel.test.tsx           |   16 +-
 .../src/components/dashboard/search-panel.tsx |   26 +-
 packages/dashboard/src/lib/references.ts      |   84 +-
 .../src/__tests__/calls-edge-by-class.test.ts |   18 +-
 .../graph/src/__tests__/falkordblite.test.ts  |    3 +
 .../src/__tests__/full-graph-window.test.ts   |   70 +-
 ...legacy-entity-identity.integration.test.ts |   91 ++
 .../node-identity.integration.test.ts         |  465 ++++++++
 .../__tests__/remove-file-contents.test.ts    |   44 +-
 .../symbol-references.integration.test.ts     |  156 +--
 packages/graph/src/drivers/falkordb-shared.ts |    9 +-
 packages/graph/src/knowledge-operations.ts    |   12 +-
 packages/graph/src/operations.ts              | 1019 ++++++++++-------
 packages/graph/src/queries.ts                 |  192 ++--
 packages/graph/src/schema.ts                  |   46 +-
 .../src/__tests__/symbolIdentity.test.ts      |   76 ++
 packages/plugin-common/src/index.ts           |    2 +-
 packages/plugin-common/src/symbolIdentity.ts  |  264 +++++
 packages/plugin-generic/src/index.ts          |  106 +-
 .../plugin-go/__tests__/extractors.test.ts    |   11 +-
 packages/plugin-go/src/index.ts               |  115 +-
 .../plugin-languages/src/configs/csharp.ts    |  152 ++-
 packages/plugin-languages/src/configs/java.ts |   80 +-
 packages/plugin-languages/src/configs/php.ts  |   57 +-
 .../src/configs/symbolIdentity.ts             |   66 ++
 .../__tests__/extractors.test.ts              |    9 +-
 packages/plugin-python/src/index.ts           |  100 +-
 .../plugin-rust/__tests__/extractors.test.ts  |    6 +-
 packages/plugin-rust/src/index.ts             |   99 +-
 .../__tests__/calls-receiver-binding.test.ts  |   72 ++
 .../__tests__/extractors.test.ts              |  180 ++-
 .../plugin-typescript/src/extractors/calls.ts |    4 +
 .../src/extractors/classes.ts                 |  151 ++-
 .../src/extractors/functions.ts               |  123 +-
 .../plugin-typescript/src/extractors/index.ts |   30 +-
 .../src/extractors/inheritance.ts             |    8 +
 .../plugin-typescript/src/extractors/jsx.ts   |   57 +-
 .../src/extractors/renders.ts                 |    4 +
 .../src/extractors/type-aliases.ts            |  140 ++-
 .../plugin-typescript/src/extractors/types.ts |   27 +
 .../src/extractors/variables.ts               |  102 +-
 packages/types/src/edges.ts                   |    8 +
 packages/types/src/nodes.ts                   |   38 +-
 packages/types/src/plugin.ts                  |   12 +
 79 files changed, 4863 insertions(+), 1553 deletions(-)
 create mode 100644 packages/core/src/__tests__/embed-pass-node-id.test.ts
 create mode 100644 packages/core/src/__tests__/enriched-search-node-id.test.ts
 create mode 100644 packages/core/src/__tests__/indexer-deleted-file.integration.test.ts
 create mode 100644 packages/core/src/__tests__/indexer-overload-call-target.integration.test.ts
 create mode 100644 packages/core/src/__tests__/node-identity-catalog.test.ts
 create mode 100644 packages/core/src/__tests__/node-identity-final-gate.integration.test.ts
 create mode 100644 packages/dashboard/src/components/dashboard/node-identity-source-guard.test.ts
 create mode 100644 packages/graph/src/__tests__/legacy-entity-identity.integration.test.ts
 create mode 100644 packages/graph/src/__tests__/node-identity.integration.test.ts
 create mode 100644 packages/plugin-common/src/__tests__/symbolIdentity.test.ts
 create mode 100644 packages/plugin-common/src/symbolIdentity.ts
 create mode 100644 packages/plugin-languages/src/configs/symbolIdentity.ts

diff --git a/packages/api/src/__tests__/graph-route.test.ts b/packages/api/src/__tests__/graph-route.test.ts
index a1b557a4..b8371470 100644
--- a/packages/api/src/__tests__/graph-route.test.ts
+++ b/packages/api/src/__tests__/graph-route.test.ts
@@ -49,6 +49,14 @@ describe('graph route numeric boundaries', () => {
     },
   );
 
+  it('forwards the persisted symbol id as the references lookup identity', async () => {
+    const id = 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
+    const response = await graphRoutes.request(`/api/graph/references?id=${encodeURIComponent(id)}`);
+
+    expect(response.status).toBe(200);
+    expect(mockedReferences).toHaveBeenCalledWith({ id, limit: undefined });
+  });
+
   it('accepts the full graph upper limit', async () => {
     const response = await graphRoutes.request('/api/graph/full?limit=1000');
 
@@ -78,16 +86,12 @@ describe('graph route numeric boundaries', () => {
     },
   );
 
-  it.each(['NaN', 'Infinity', '0', '-1', '1.5', '10000001'])(
-    'rejects reference startLine=%s before touching the graph',
-    async (startLine) => {
-      const result = await errorFor(`/api/graph/references?name=run&startLine=${startLine}`);
+  it('rejects the removed name-based references lookup', async () => {
+    const result = await errorFor('/api/graph/references?name=run');
 
-      expect(result.status).toBe(400);
-      expect(result.error).toBe('startLine must be a positive integer between 1 and 10000000');
-      expect(mockedReferences).not.toHaveBeenCalled();
-    },
-  );
+    expect(result).toEqual({ status: 400, error: 'id parameter is required' });
+    expect(mockedReferences).not.toHaveBeenCalled();
+  });
 });
 
 describe('GET /api/graph/file-relationships', () => {
diff --git a/packages/api/src/__tests__/search-route.test.ts b/packages/api/src/__tests__/search-route.test.ts
index 26761d0b..164fe5e3 100644
--- a/packages/api/src/__tests__/search-route.test.ts
+++ b/packages/api/src/__tests__/search-route.test.ts
@@ -44,9 +44,9 @@ const KNOWN_LABELS = new Set(['Class', 'Interface', 'Function', 'Variable']);
 function threeRawHits(): EnrichedV2Result {
   return {
     hits: [
-      { name: 'GraphClient', nodeType: 'Class' },
-      { name: 'ClientOptions', nodeType: 'Interface' },
-      { name: 'createGraphClient', nodeType: 'Function' },
+      { id: 'sym:v1:' + 'a'.repeat(64), name: 'GraphClient', nodeType: 'Class' },
+      { id: 'sym:v1:' + 'b'.repeat(64), name: 'ClientOptions', nodeType: 'Interface' },
+      { id: 'sym:v1:' + 'c'.repeat(64), name: 'createGraphClient', nodeType: 'Function' },
     ],
     meta: { query: 'graph client', vectorHits: 3, durationMs: 5 },
   };
@@ -148,7 +148,7 @@ describe('GET /api/search: types filter emptying the page', () => {
     mockedSearch.mockResolvedValue(threeRawHits());
     mockedGetGraphClient.mockResolvedValue(
       fakeGraphClient([
-        { name: 'clientCache', nodeType: 'Variable', filePath: '/x.ts', startLine: 1, endLine: 1, isExported: true },
+        { id: 'sym:v1:' + 'd'.repeat(64), name: 'clientCache', nodeType: 'Variable', filePath: '/x.ts', startLine: 1, endLine: 1, isExported: true },
       ]) as never,
     );
 
@@ -190,7 +190,7 @@ describe('GET /api/search: types filter emptying the page', () => {
     });
     mockedGetGraphClient.mockResolvedValue(
       fakeGraphClient([
-        { name: 'clientCache', nodeType: 'Variable', filePath: '/x.ts', startLine: 1, endLine: 1, isExported: true },
+        { id: 'sym:v1:' + 'e'.repeat(64), name: 'clientCache', nodeType: 'Variable', filePath: '/x.ts', startLine: 1, endLine: 1, isExported: true },
       ]) as never,
     );
 
@@ -201,6 +201,53 @@ describe('GET /api/search: types filter emptying the page', () => {
     expect(body.total).toBe(1);
     expect(body.notice).toBeUndefined();
   });
+
+  it('returns persisted ids for every row from the text fallback', async () => {
+    const symbolId = 'sym:v1:' + 'd'.repeat(64);
+    mockedSearch.mockResolvedValue({
+      hits: [],
+      meta: { query: 'shared', vectorHits: 0, durationMs: 2 },
+    });
+    const client = fakeGraphClient([
+      {
+        id: symbolId,
+        name: 'shared',
+        nodeType: 'Function',
+        filePath: '/repo/src/shared.ts',
+        startLine: 4,
+        endLine: 6,
+        isExported: true,
+      },
+      {
+        id: 'File:/repo/src/shared.ts',
+        name: 'shared.ts',
+        nodeType: 'File',
+        filePath: '/repo/src/shared.ts',
+        startLine: null,
+        endLine: null,
+        isExported: null,
+      },
+    ]);
+    mockedGetGraphClient.mockResolvedValue(client as never);
+
+    const { status, body } = await searchJson('q=shared&limit=3');
+
+    expect(status).toBe(200);
+    expect(body.fallback).toBe(true);
+    const results = body.results as Array<Record<string, unknown>>;
+    expect(results).toEqual([
+      expect.objectContaining({ id: symbolId, nodeType: 'Function' }),
+      expect.objectContaining({ id: 'File:/repo/src/shared.ts', nodeType: 'File' }),
+    ]);
+    for (const row of results) {
+      expect(row.id).toEqual(expect.stringMatching(/^(?:sym:v1:[a-f0-9]{64}|File:.+)$/));
+    }
+    expect(client.roQuery).toHaveBeenCalledWith(
+      expect.stringContaining('RETURN n.id AS id'),
+      expect.objectContaining({ params: { q: 'shared', limit: 3 } }),
+    );
+    expect(client.roQuery.mock.calls[0]?.[0]).toContain('AND n.id IS NOT NULL');
+  });
 });
 
 describe('GET /api/search: malformed types values (third adversarial-review finding)', () => {
diff --git a/packages/api/src/routes/graph.ts b/packages/api/src/routes/graph.ts
index b78d1f29..14ee7af4 100644
--- a/packages/api/src/routes/graph.ts
+++ b/packages/api/src/routes/graph.ts
@@ -8,8 +8,8 @@ export const graphRoutes = new Hono();
 const FULL_GRAPH_LIMIT_MAX = 1000;
 const FILE_RELATIONSHIP_LIMIT_MAX = 500;
 const REFERENCE_LIMIT_MAX = 1000;
-const REFERENCE_START_LINE_MAX = 10_000_000;
 const DEPENDENCY_DEPTH_MAX = 10;
+const SYMBOL_ID_PATTERN = /^sym:v1:[a-f0-9]{64}$/;
 
 type BoundedIntegerResult =
   | { valid: true; value?: number }
@@ -108,34 +108,24 @@ graphRoutes.get('/api/graph/file', async (c) => {
 });
 
 /**
- * GET /api/graph/references?name=X&path=Y&startLine=N&limit=M
+ * GET /api/graph/references?id=X&limit=M
  *
- * Where a symbol is used. Matches every node with this name, not just one, so
- * references that land on a type-reference proxy node are included alongside
- * ones that land on the declaration itself. `path` and `startLine` are
- * optional and disambiguate between distinct declarations that share a name;
- * a matched node with no location of its own (a proxy node) is never excluded
- * by them.
+ * Where a symbol is used. The persisted symbol id is the sole declaration
+ * identity accepted by this endpoint.
  */
 graphRoutes.get('/api/graph/references', async (c) => {
   try {
-    const name = c.req.query('name');
-    if (!name) return c.json({ error: 'name parameter is required' }, 400);
-
-    const parsedLine = boundedPositiveInteger(
-      c.req.query('startLine'),
-      'startLine',
-      REFERENCE_START_LINE_MAX,
-    );
-    if (!parsedLine.valid) return c.json({ error: parsedLine.error }, 400);
-
     const parsedLimit = boundedPositiveInteger(c.req.query('limit'), 'limit', REFERENCE_LIMIT_MAX);
     if (!parsedLimit.valid) return c.json({ error: parsedLimit.error }, 400);
 
+    const id = c.req.query('id');
+    if (!id) return c.json({ error: 'id parameter is required' }, 400);
+    if (!SYMBOL_ID_PATTERN.test(id)) {
+      return c.json({ error: 'id must be a persisted sym:v1 identifier' }, 400);
+    }
+
     const data = await codeGraphService.getSymbolReferences({
-      name,
-      filePath: c.req.query('path'),
-      startLine: parsedLine.value,
+      id,
       limit: parsedLimit.value,
     });
     return c.json(data);
diff --git a/packages/api/src/routes/search.ts b/packages/api/src/routes/search.ts
index f70d1f46..1ec4fd11 100644
--- a/packages/api/src/routes/search.ts
+++ b/packages/api/src/routes/search.ts
@@ -249,6 +249,7 @@ searchRoutes.get('/api/search', async (c) => {
       : 'n:Function OR n:Class OR n:Interface OR n:Component OR n:Type OR n:Variable OR n:File';
 
     const rows = await client.roQuery<{
+      id: string;
       name: string;
       nodeType: string;
       filePath: string | null;
@@ -258,8 +259,10 @@ searchRoutes.get('/api/search', async (c) => {
     }>(
       `MATCH (n)
        WHERE (${typeFilter})
+         AND n.id IS NOT NULL
          AND (toLower(n.name) CONTAINS toLower($q) OR toLower(n.filePath) CONTAINS toLower($q))
-       RETURN n.name AS name,
+       RETURN n.id AS id,
+              n.name AS name,
               labels(n)[0] AS nodeType,
               n.filePath AS filePath,
               n.startLine AS startLine,
@@ -278,6 +281,7 @@ searchRoutes.get('/api/search', async (c) => {
 
     return c.json({
       results: rows.data.map(r => ({
+        id: r.id,
         name: r.name,
         nodeType: r.nodeType,
         filePath: r.filePath,
diff --git a/packages/core/src/__tests__/dependency-depth.integration.test.ts b/packages/core/src/__tests__/dependency-depth.integration.test.ts
index fd45b6f8..39626127 100644
--- a/packages/core/src/__tests__/dependency-depth.integration.test.ts
+++ b/packages/core/src/__tests__/dependency-depth.integration.test.ts
@@ -51,7 +51,7 @@ describeIfAvailable('dependency depth enrichment', () => {
     await client.query(
       `UNWIND range(0, $hub - 1) AS i
        MATCH (lib:File {filePath: '/x/lib.ts'})
-       CREATE (f:Function {name: '_parse', filePath: '/x/lib.ts', startLine: i + 1})
+       CREATE (f:Function {id: 'hub-' + toString(i), name: '_parse', filePath: '/x/lib.ts', startLine: i + 1})
        CREATE (lib)-[:CONTAINS]->(f)`,
       { params: { hub: HUB_SIZE } },
     );
@@ -65,7 +65,7 @@ describeIfAvailable('dependency depth enrichment', () => {
     // A genuinely reachable symbol, to pin the values the query returns.
     await client.query(`
       MATCH (other:File {filePath: '/x/other.ts'})
-      CREATE (r:Function {name: 'reachable', filePath: '/x/other.ts', startLine: 1})
+      CREATE (r:Function {id: 'id-reachable', name: 'reachable', filePath: '/x/other.ts', startLine: 1})
       CREATE (other)-[:CONTAINS]->(r)
     `);
   }, 60_000);
@@ -77,9 +77,9 @@ describeIfAvailable('dependency depth enrichment', () => {
 
   it('answers for an unreachable hub symbol well inside the budget', async () => {
     const started = Date.now();
-    const result = await client.roQuery<{ symbolName: string; minDepth: number | null }>(
+    const result = await client.roQuery<{ symbolId: string; minDepth: number | null }>(
       DEPENDENCY_DEPTH_CYPHER,
-      { params: { names: ['_parse'] }, timeout: BUDGET_MS },
+      { params: { ids: ['hub-0'] }, timeout: BUDGET_MS },
     );
     expect(Date.now() - started).toBeLessThan(BUDGET_MS);
     // Unreachable symbols yield no row, which the caller reads as "depth unknown".
@@ -87,9 +87,9 @@ describeIfAvailable('dependency depth enrichment', () => {
   });
 
   it('reports the depth of a reachable symbol', async () => {
-    const result = await client.roQuery<{ symbolName: string; minDepth: number | null }>(
+    const result = await client.roQuery<{ symbolId: string; minDepth: number | null }>(
       DEPENDENCY_DEPTH_CYPHER,
-      { params: { names: ['reachable'] }, timeout: BUDGET_MS },
+      { params: { ids: ['id-reachable'] }, timeout: BUDGET_MS },
     );
     expect(result.data).toHaveLength(1);
     expect(result.data[0]?.minDepth).toBe(1);
@@ -97,11 +97,11 @@ describeIfAvailable('dependency depth enrichment', () => {
 
   it('stays fast when a hub symbol is batched with ordinary ones', async () => {
     const started = Date.now();
-    const result = await client.roQuery<{ symbolName: string; minDepth: number | null }>(
+    const result = await client.roQuery<{ symbolId: string; minDepth: number | null }>(
       DEPENDENCY_DEPTH_CYPHER,
-      { params: { names: ['reachable', '_parse', 'missing'] }, timeout: BUDGET_MS },
+      { params: { ids: ['id-reachable', 'hub-0', 'id-missing'] }, timeout: BUDGET_MS },
     );
     expect(Date.now() - started).toBeLessThan(BUDGET_MS);
-    expect(result.data.map((r) => r.symbolName)).toEqual(['reachable']);
+    expect(result.data.map((r) => r.symbolId)).toEqual(['id-reachable']);
   });
 });
diff --git a/packages/core/src/__tests__/embed-pass-node-id.test.ts b/packages/core/src/__tests__/embed-pass-node-id.test.ts
new file mode 100644
index 00000000..2415b652
--- /dev/null
+++ b/packages/core/src/__tests__/embed-pass-node-id.test.ts
@@ -0,0 +1,89 @@
+import { createHash } from 'node:crypto';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { GraphOperations } from '@codegraph/graph';
+import type { ParsedFileEntities } from '@codegraph/types';
+import { buildFunctionEmbeddingText, generateEmbeddings } from '@codegraph/plugin-nlp';
+import { embedAllParsedEntities } from '../embed-pass';
+
+vi.mock('@codegraph/plugin-nlp', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@codegraph/plugin-nlp')>();
+  return {
+    ...actual,
+    isEmbeddingAvailable: () => true,
+    generateEmbeddings: vi.fn().mockResolvedValue({ embeddings: [[0.1, 0.2]] }),
+  };
+});
+
+const persistedId = `sym:v1:${'a'.repeat(64)}`;
+const functionEntity: ParsedFileEntities['functions'][number] = {
+  id: persistedId,
+  scopeKey: '',
+  disambiguator: '',
+  name: 'stable',
+  filePath: '/project/stable.ts',
+  startLine: 80,
+  endLine: 84,
+  isExported: true,
+  isAsync: false,
+  isArrow: false,
+  params: [],
+  returnType: 'number',
+  bodySnippet: 'return 1;',
+};
+
+const parsed: ParsedFileEntities = {
+  file: {
+    path: '/project/stable.ts',
+    name: 'stable.ts',
+    extension: 'ts',
+    loc: 84,
+    lastModified: new Date(0).toISOString(),
+    hash: 'hash',
+  },
+  functions: [functionEntity],
+  classes: [],
+  interfaces: [],
+  variables: [],
+  types: [],
+  components: [],
+  imports: [],
+  callEdges: [],
+  importsEdges: [],
+  extendsEdges: [],
+  implementsEdges: [],
+  rendersEdges: [],
+  hasMethodEdges: [],
+  hasPropertyEdges: [],
+  typeRefs: [],
+  hasParamEdges: [],
+  returnsEdges: [],
+  usesTypeEdges: [],
+  exportsEdges: [],
+  importsSymbolEdges: [],
+};
+
+describe('embedding cache identity', () => {
+  beforeEach(() => {
+    vi.mocked(generateEmbeddings).mockClear();
+  });
+
+  it('does not re-embed unchanged content when the same persisted id moves lines', async () => {
+    const text = buildFunctionEmbeddingText(functionEntity);
+    const hash = createHash('sha256').update(text).digest('hex');
+    const ops = {
+      getEmbeddingHashesForFiles: vi.fn(),
+      batchUpdateEmbeddings: vi.fn(),
+      updateEmbedding: vi.fn(),
+    } as unknown as GraphOperations;
+
+    const result = await embedAllParsedEntities(
+      [parsed],
+      ops,
+      { provider: 'local' },
+      new Map([[persistedId, hash]]),
+    );
+
+    expect(result).toMatchObject({ embedded: 0, skipped: 1 });
+    expect(generateEmbeddings).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/core/src/__tests__/enrich-from-graph.integration.test.ts b/packages/core/src/__tests__/enrich-from-graph.integration.test.ts
index f4949dd3..33cd71ed 100644
--- a/packages/core/src/__tests__/enrich-from-graph.integration.test.ts
+++ b/packages/core/src/__tests__/enrich-from-graph.integration.test.ts
@@ -28,7 +28,7 @@ import { enrichFromGraph, type Candidate } from '../enrichedSearchV2';
 // The embedded driver ships binaries for darwin-arm64 and linux-x64 only.
 const describeIfAvailable = resolveEmbeddedBinaryPaths() ? describe : describe.skip;
 
-function candidate(over: Partial<Candidate> & { name: string; filePath: string; startLine: number }): Candidate {
+function candidate(over: Partial<Candidate> & { id: string; name: string; filePath: string; startLine: number }): Candidate {
   return {
     nodeType: 'Function',
     properties: {},
@@ -55,8 +55,8 @@ describeIfAvailable('enrichFromGraph', () => {
     // no inbound one at all, so its caller count is genuinely zero.
     await client.query(`
       CREATE (f:File {filePath: '/x/a.ts', name: 'a.ts'})
-      CREATE (callsButNotCalled:Function {name: 'callsButNotCalled', filePath: '/x/a.ts', startLine: 5})
-      CREATE (callee:Function {name: 'calleeOfIt', filePath: '/x/a.ts', startLine: 9})
+      CREATE (callsButNotCalled:Function {id: 'id-caller', name: 'callsButNotCalled', filePath: '/x/a.ts', startLine: 5})
+      CREATE (callee:Function {id: 'id-callee', name: 'calleeOfIt', filePath: '/x/a.ts', startLine: 9})
       CREATE (f)-[:CONTAINS]->(callsButNotCalled)
       CREATE (f)-[:CONTAINS]->(callee)
       CREATE (callsButNotCalled)-[:CALLS]->(callee)
@@ -69,10 +69,10 @@ describeIfAvailable('enrichFromGraph', () => {
     await client.query(`
       CREATE (fb:File {filePath: '/x/b.ts', name: 'b.ts'})
       CREATE (fc:File {filePath: '/x/c.ts', name: 'c.ts'})
-      CREATE (ctorB:Function {name: 'constructor', filePath: '/x/b.ts', startLine: 3})
-      CREATE (ctorC:Function {name: 'constructor', filePath: '/x/c.ts', startLine: 30})
-      CREATE (callerB1:Function {name: 'makeB1', filePath: '/x/b.ts', startLine: 20})
-      CREATE (callerB2:Function {name: 'makeB2', filePath: '/x/b.ts', startLine: 25})
+      CREATE (ctorB:Function {id: 'id-ctor-b', name: 'constructor', filePath: '/x/b.ts', startLine: 3})
+      CREATE (ctorC:Function {id: 'id-ctor-c', name: 'constructor', filePath: '/x/c.ts', startLine: 30})
+      CREATE (callerB1:Function {id: 'id-maker-b1', name: 'makeB1', filePath: '/x/b.ts', startLine: 20})
+      CREATE (callerB2:Function {id: 'id-maker-b2', name: 'makeB2', filePath: '/x/b.ts', startLine: 25})
       CREATE (fb)-[:CONTAINS]->(ctorB)
       CREATE (fc)-[:CONTAINS]->(ctorC)
       CREATE (fb)-[:CONTAINS]->(callerB1)
@@ -90,7 +90,7 @@ describeIfAvailable('enrichFromGraph', () => {
   });
 
   it('reports callees for a symbol that has zero callers (defect 1)', async () => {
-    const hit = candidate({ name: 'callsButNotCalled', filePath: '/x/a.ts', startLine: 5 });
+    const hit = candidate({ id: 'id-caller', name: 'callsButNotCalled', filePath: '/x/a.ts', startLine: 5 });
     const result = await enrichFromGraph(client, [hit]);
     const entries = Array.from(result.values());
     expect(entries).toHaveLength(1);
@@ -103,7 +103,7 @@ describeIfAvailable('enrichFromGraph', () => {
   });
 
   it('still reports callers correctly for an ordinary symbol', async () => {
-    const hit = candidate({ name: 'calleeOfIt', filePath: '/x/a.ts', startLine: 9 });
+    const hit = candidate({ id: 'id-callee', name: 'calleeOfIt', filePath: '/x/a.ts', startLine: 9 });
     const result = await enrichFromGraph(client, [hit]);
     const entries = Array.from(result.values());
     expect(entries[0]?.callerCount).toBe(1);
@@ -111,8 +111,8 @@ describeIfAvailable('enrichFromGraph', () => {
   });
 
   it('does not mix up two declarations that share a name (defect 2)', async () => {
-    const hitB = candidate({ name: 'constructor', filePath: '/x/b.ts', startLine: 3 });
-    const hitC = candidate({ name: 'constructor', filePath: '/x/c.ts', startLine: 30 });
+    const hitB = candidate({ id: 'id-ctor-b', name: 'constructor', filePath: '/x/b.ts', startLine: 3 });
+    const hitC = candidate({ id: 'id-ctor-c', name: 'constructor', filePath: '/x/c.ts', startLine: 30 });
     const result = await enrichFromGraph(client, [hitB, hitC]);
 
     // Both hits must be individually retrievable and keep their own numbers.
@@ -127,7 +127,7 @@ describeIfAvailable('enrichFromGraph', () => {
   });
 
   it('produces no row (not a row of zeros) for a name with no matching node', async () => {
-    const hit = candidate({ name: 'doesNotExistAnywhere', filePath: '/x/nowhere.ts', startLine: 1 });
+    const hit = candidate({ id: 'id-missing', name: 'doesNotExistAnywhere', filePath: '/x/nowhere.ts', startLine: 1 });
     const result = await enrichFromGraph(client, [hit]);
     expect(result.size).toBe(0);
   });
diff --git a/packages/core/src/__tests__/enriched-search-node-id.test.ts b/packages/core/src/__tests__/enriched-search-node-id.test.ts
new file mode 100644
index 00000000..02965595
--- /dev/null
+++ b/packages/core/src/__tests__/enriched-search-node-id.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it, vi } from 'vitest';
+import { enrichFromGraph, enrichmentKey, type Candidate } from '../enrichedSearchV2';
+
+function candidate(id: string): Candidate {
+  return {
+    id,
+    name: 'constructor',
+    nodeType: 'Function',
+    filePath: '/project/widget.ts',
+    startLine: 10,
+    properties: { id },
+    vectorScore: 1,
+    score: 1,
+  };
+}
+
+describe('enrichment identity', () => {
+  it('binds, maps, and returns same-location candidates by persisted id', async () => {
+    const firstId = `sym:v1:${'1'.repeat(64)}`;
+    const secondId = `sym:v1:${'2'.repeat(64)}`;
+    const client = {
+      roQuery: vi.fn()
+        .mockResolvedValueOnce({
+          data: [
+            { symbolId: firstId, callers: 1, calleeNames: [], importers: 0, testRefs: 0 },
+            { symbolId: secondId, callers: 3, calleeNames: [], importers: 0, testRefs: 0 },
+          ],
+        })
+        .mockResolvedValue({ data: [] }),
+    };
+
+    const result = await enrichFromGraph(client as never, [candidate(firstId), candidate(secondId)]);
+
+    expect(client.roQuery).toHaveBeenCalledWith(
+      expect.stringContaining('MATCH (n {id: item.id})'),
+      expect.objectContaining({ params: { items: [{ id: firstId }, { id: secondId }] } }),
+    );
+    expect(result.get(enrichmentKey(firstId))?.callerCount).toBe(1);
+    expect(result.get(enrichmentKey(secondId))?.callerCount).toBe(3);
+  });
+});
diff --git a/packages/core/src/__tests__/indexer-deleted-file.integration.test.ts b/packages/core/src/__tests__/indexer-deleted-file.integration.test.ts
new file mode 100644
index 00000000..deef6a4d
--- /dev/null
+++ b/packages/core/src/__tests__/indexer-deleted-file.integration.test.ts
@@ -0,0 +1,124 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { mkdtemp, rm, unlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createClient, resolveEmbeddedBinaryPaths, type GraphClient } from '@codegraph/graph';
+import { indexProject } from '../indexer';
+
+const describeIfAvailable = resolveEmbeddedBinaryPaths() ? describe : describe.skip;
+
+describeIfAvailable('incremental indexing of deleted files', () => {
+  let client: GraphClient;
+  let dataDir: string;
+  let projectDir: string;
+  let callerPath: string;
+  let doomedPath: string;
+  let previousEmbeddingProvider: string | undefined;
+
+  beforeAll(async () => {
+    previousEmbeddingProvider = process.env['CODEGRAPH_EMBEDDING_PROVIDER'];
+    process.env['CODEGRAPH_EMBEDDING_PROVIDER'] = 'none';
+    dataDir = await mkdtemp(join(tmpdir(), 'cg-deleted-file-db-'));
+    projectDir = await mkdtemp(join(tmpdir(), 'cg-deleted-file-project-'));
+    callerPath = resolve(projectDir, 'caller.ts');
+    doomedPath = resolve(projectDir, 'doomed.ts');
+
+    client = await createClient({
+      driver: 'falkordblite',
+      databasePath: dataDir,
+      graphName: 'deleted_file_incremental',
+    } as never);
+
+    await writeFile(doomedPath, 'export function doomed(): number {\n  return 42;\n}\n');
+    await writeFile(
+      callerPath,
+      [
+        "import { doomed } from './doomed';",
+        '',
+        'export function caller(): number {',
+        '  return doomed();',
+        '}',
+        '',
+      ].join('\n'),
+    );
+  }, 60_000);
+
+  afterAll(async () => {
+    await client?.close();
+    if (dataDir) await rm(dataDir, { recursive: true, force: true });
+    if (projectDir) await rm(projectDir, { recursive: true, force: true });
+    if (previousEmbeddingProvider === undefined) {
+      delete process.env['CODEGRAPH_EMBEDDING_PROVIDER'];
+    } else {
+      process.env['CODEGRAPH_EMBEDDING_PROVIDER'] = previousEmbeddingProvider;
+    }
+  });
+
+  it('removes a vanished File, its symbol id, and both inbound edge kinds in the same pass', async () => {
+    const initial = await indexProject(projectDir, {
+      client,
+      includePatterns: ['*.ts'],
+      embeddings: false,
+      gitSync: false,
+      force: true,
+    });
+    expect(initial).toMatchObject({ success: true, errorMessages: [] });
+
+    const targetBefore = await client.roQuery<{ id: string }>(
+      `MATCH (target:Function {name: 'doomed', filePath: $doomedPath})
+       RETURN target.id AS id`,
+      { params: { doomedPath } },
+    );
+    expect(targetBefore.data).toEqual([{ id: expect.stringMatching(/^sym:v1:[a-f0-9]{64}$/) }]);
+    const doomedId = targetBefore.data[0]!.id;
+
+    const inboundBefore = await client.roQuery<{ calls: number; imports: number }>(
+      `MATCH (target:Function {id: $doomedId})
+       OPTIONAL MATCH (:Function {filePath: $callerPath})-[call:CALLS]->(target)
+       OPTIONAL MATCH (:File {filePath: $callerPath})-[imported:IMPORTS_SYMBOL]->(target)
+       RETURN count(DISTINCT call) AS calls, count(DISTINCT imported) AS imports`,
+      { params: { callerPath, doomedId } },
+    );
+    expect(inboundBefore.data).toEqual([{ calls: 1, imports: 1 }]);
+
+    await unlink(doomedPath);
+
+    const incremental = await indexProject(projectDir, {
+      client,
+      includePatterns: ['*.ts'],
+      embeddings: false,
+      gitSync: false,
+      force: false,
+    });
+    expect(incremental.success).toBe(true);
+
+    const survivors = await client.roQuery<{ files: number; symbols: number; inbound: number }>(
+      `OPTIONAL MATCH (file:File {filePath: $doomedPath})
+       WITH count(file) AS files
+       OPTIONAL MATCH (symbol {id: $doomedId})
+       WITH files, count(symbol) AS symbols
+       OPTIONAL MATCH ()-[edge:CALLS|IMPORTS_SYMBOL]->(target {id: $doomedId})
+       RETURN files, symbols, count(edge) AS inbound`,
+      { params: { doomedId, doomedPath } },
+    );
+    expect(survivors.data).toEqual([{ files: 0, symbols: 0, inbound: 0 }]);
+
+    await unlink(callerPath);
+    const emptyIncremental = await indexProject(projectDir, {
+      client,
+      includePatterns: ['*.ts'],
+      embeddings: false,
+      gitSync: false,
+      force: false,
+    });
+    expect(emptyIncremental).toMatchObject({ success: true, errorMessages: [] });
+
+    const remainingSourceNodes = await client.roQuery<{ count: number }>(
+      `MATCH (node)
+       WHERE node.filePath STARTS WITH $projectDir
+       RETURN count(node) AS count`,
+      { params: { projectDir } },
+    );
+    expect(remainingSourceNodes.data).toEqual([{ count: 0 }]);
+  }, 120_000);
+});
diff --git a/packages/core/src/__tests__/indexer-overload-call-target.integration.test.ts b/packages/core/src/__tests__/indexer-overload-call-target.integration.test.ts
new file mode 100644
index 00000000..a7906af4
--- /dev/null
+++ b/packages/core/src/__tests__/indexer-overload-call-target.integration.test.ts
@@ -0,0 +1,102 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createClient, resolveEmbeddedBinaryPaths, type GraphClient } from '@codegraph/graph';
+import { indexProject } from '../indexer';
+
+const describeIfAvailable = resolveEmbeddedBinaryPaths() ? describe : describe.skip;
+
+describeIfAvailable('indexProject overload call target resolution', () => {
+  let client: GraphClient;
+  let dataDir: string;
+  let projectDir: string;
+  let overPath: string;
+  let callerPath: string;
+  let previousEmbeddingProvider: string | undefined;
+
+  beforeAll(async () => {
+    previousEmbeddingProvider = process.env['CODEGRAPH_EMBEDDING_PROVIDER'];
+    process.env['CODEGRAPH_EMBEDDING_PROVIDER'] = 'none';
+
+    dataDir = await mkdtemp('/private/tmp/cgot-');
+    client = await createClient({
+      driver: 'falkordblite',
+      databasePath: dataDir,
+      graphName: 'overload_call_target',
+    } as never);
+
+    projectDir = mkdtempSync(join(tmpdir(), 'cg-overload-call-project-'));
+    overPath = resolve(projectDir, 'over.ts');
+    callerPath = resolve(projectDir, 'caller.ts');
+    writeFileSync(overPath, [
+      'export class Over {',
+      '  work(value: string): string;',
+      '  work(value: number): number;',
+      '  work(value: string | number): string | number { return value; }',
+      '}',
+      'export class Sibling {',
+      '  work(value: string): string;',
+      '  work(value: number): number;',
+      '  work(value: string | number): string | number { return value; }',
+      '}',
+      '',
+    ].join('\n'));
+    writeFileSync(callerPath, [
+      "import { Over } from './over';",
+      'export function callOver(over: Over): string {',
+      "  return over.work('value');",
+      '}',
+      '',
+    ].join('\n'));
+  }, 60_000);
+
+  afterAll(async () => {
+    await client?.close();
+    if (dataDir) await rm(dataDir, { recursive: true, force: true });
+    if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+    if (previousEmbeddingProvider === undefined) {
+      delete process.env['CODEGRAPH_EMBEDDING_PROVIDER'];
+    } else {
+      process.env['CODEGRAPH_EMBEDDING_PROVIDER'] = previousEmbeddingProvider;
+    }
+  });
+
+  it('persists exactly one cross-file receiver CALLS edge to the implementation', async () => {
+    const result = await indexProject(projectDir, {
+      client,
+      includePatterns: ['*.ts'],
+      embeddings: false,
+      gitSync: false,
+      force: true,
+    });
+    expect(result.success).toBe(true);
+    expect(result.errorMessages).toEqual([]);
+
+    const targets = await client.roQuery<{
+      id: string;
+      scopeKey: string;
+      startLine: number;
+    }>(
+      `MATCH (:Function {name: 'callOver', filePath: $callerPath})-[:CALLS]->(target:Function {name: 'work'})
+       RETURN target.id AS id, target.scopeKey AS scopeKey, target.startLine AS startLine
+       ORDER BY target.startLine`,
+      { params: { callerPath } },
+    );
+
+    expect(targets.data).toEqual([{
+      id: expect.stringMatching(/^sym:v1:[a-f0-9]{64}$/),
+      scopeKey: 'Class:Over',
+      startLine: 4,
+    }]);
+
+    const overloadNodes = await client.roQuery<{ scopeKey: string; startLine: number }>(
+      `MATCH (method:Function {name: 'work', filePath: $overPath})
+       RETURN method.scopeKey AS scopeKey, method.startLine AS startLine
+       ORDER BY method.scopeKey, method.startLine`,
+      { params: { overPath } },
+    );
+    expect(overloadNodes.data).toHaveLength(6);
+  }, 60_000);
+});
diff --git a/packages/core/src/__tests__/indexer-single-file-preserves-file-node.test.ts b/packages/core/src/__tests__/indexer-single-file-preserves-file-node.test.ts
index 4307b373..4f710647 100644
--- a/packages/core/src/__tests__/indexer-single-file-preserves-file-node.test.ts
+++ b/packages/core/src/__tests__/indexer-single-file-preserves-file-node.test.ts
@@ -32,6 +32,8 @@ import type { ExtractedEntities, FileEntity, ParsedFileEntities } from '@codegra
 // ---------------------------------------------------------------------------
 
 const opsMocks = vi.hoisted(() => ({
+  getProjectByRoot: vi.fn().mockResolvedValue(null),
+  sweepStaleFileSymbols: vi.fn().mockResolvedValue(undefined),
   removeFileAndCleanup: vi.fn().mockResolvedValue(undefined),
   removeFileContents: vi.fn().mockResolvedValue(undefined),
   removeDocumentContents: vi.fn().mockResolvedValue(undefined),
@@ -118,6 +120,7 @@ beforeEach(() => {
   writeFileSync(filePath, 'export const x = 1;\n');
   opsMocks.removeFileAndCleanup.mockClear();
   opsMocks.removeFileContents.mockClear();
+  opsMocks.sweepStaleFileSymbols.mockClear();
 });
 
 afterEach(() => {
@@ -130,6 +133,7 @@ describe('indexSingleFile: reindexing a changed file must not destroy the File n
 
     expect(result.success).toBe(true);
     expect(opsMocks.removeFileContents).toHaveBeenCalledWith(filePath);
+    expect(opsMocks.sweepStaleFileSymbols).toHaveBeenCalledWith(filePath, []);
     expect(opsMocks.removeFileAndCleanup).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/core/src/__tests__/linked-knowledge.test.ts b/packages/core/src/__tests__/linked-knowledge.test.ts
index 082bc16d..20ca3204 100644
--- a/packages/core/src/__tests__/linked-knowledge.test.ts
+++ b/packages/core/src/__tests__/linked-knowledge.test.ts
@@ -22,7 +22,7 @@ const MOCK_VECTOR_HIT = {
   filePath: 'src/auth.ts',
   startLine: 10,
   distance: 0.1,
-  properties: {},
+  properties: { id: 'sym:v1:parse-token' },
 };
 
 // ---------------------------------------------------------------------------
@@ -39,7 +39,7 @@ vi.mock('@codegraph/graph', () => ({
         filePath: 'src/auth.ts',
         startLine: 10,
         distance: 0.1,
-        properties: {},
+        properties: { id: 'sym:v1:parse-token' },
       },
     ]),
   }),
@@ -91,7 +91,7 @@ const { enrichedSearchV2, clearEmbeddedLabelCache } = await import('../enrichedS
 
 type RoQueryResponse = { data: unknown[]; metadata: null };
 type LinkedKnowledgeRow = {
-  targetName: string;
+  targetId: string;
   entityText: string;
   entityType: string;
   confidence: number;
@@ -148,7 +148,7 @@ describe('enrichedSearchV2 — linkedKnowledge enrichment via ABOUT edges', () =
   it('attaches linkedKnowledge to hits that have matching ABOUT edges', async () => {
     const client = makeMockClient([
       {
-        targetName: 'parseToken',
+        targetId: 'sym:v1:parse-token',
         entityText: 'JWT authentication decision',
         entityType: 'Decision',
         confidence: 0.95,
@@ -182,14 +182,14 @@ describe('enrichedSearchV2 — linkedKnowledge enrichment via ABOUT edges', () =
   it('attaches multiple knowledge entries when several ABOUT edges exist', async () => {
     const client = makeMockClient([
       {
-        targetName: 'parseToken',
+        targetId: 'sym:v1:parse-token',
         entityText: 'JWT decision',
         entityType: 'Decision',
         confidence: 0.9,
         fact: null,
       },
       {
-        targetName: 'parseToken',
+        targetId: 'sym:v1:parse-token',
         entityText: 'Token expiry policy',
         entityType: 'Policy',
         confidence: 0.8,
@@ -208,7 +208,7 @@ describe('enrichedSearchV2 — linkedKnowledge enrichment via ABOUT edges', () =
   it('does not include fact field when fact is null', async () => {
     const client = makeMockClient([
       {
-        targetName: 'parseToken',
+        targetId: 'sym:v1:parse-token',
         entityText: 'Auth system',
         entityType: 'System',
         confidence: 0.7,
diff --git a/packages/core/src/__tests__/neighbor-expansion.test.ts b/packages/core/src/__tests__/neighbor-expansion.test.ts
index bc007a6e..b225334e 100644
--- a/packages/core/src/__tests__/neighbor-expansion.test.ts
+++ b/packages/core/src/__tests__/neighbor-expansion.test.ts
@@ -6,13 +6,13 @@ describe('fetchSiblingSymbols', () => {
     const mockClient = {
       roQuery: vi.fn().mockResolvedValue({
         data: [
-          { name: 'fnA', startLine: 10, endLine: 20, signature: 'fnA sig', nodeType: 'Function' },
-          { name: 'fnB', startLine: 30, endLine: 40, signature: 'fnB sig', nodeType: 'Function' },
-          { name: 'fnC', startLine: 50, endLine: 60, signature: 'fnC sig', nodeType: 'Function' },
+          { id: 'id-a', name: 'fnA', startLine: 10, endLine: 20, signature: 'fnA sig', nodeType: 'Function' },
+          { id: 'id-b', name: 'fnB', startLine: 30, endLine: 40, signature: 'fnB sig', nodeType: 'Function' },
+          { id: 'id-c', name: 'fnC', startLine: 50, endLine: 60, signature: 'fnC sig', nodeType: 'Function' },
         ],
       }),
     };
-    const siblings = await fetchSiblingSymbols(mockClient as never, '/file.ts', 'fnB', 30);
+    const siblings = await fetchSiblingSymbols(mockClient as never, '/file.ts', 'id-b');
     expect(siblings).toHaveLength(2);
     expect(siblings.map(s => s.name)).toEqual(['fnA', 'fnC']);
   });
@@ -21,12 +21,12 @@ describe('fetchSiblingSymbols', () => {
     const mockClient = {
       roQuery: vi.fn().mockResolvedValue({
         data: [
-          { name: 'fnA', startLine: 10, endLine: 20, nodeType: 'Function' },
-          { name: 'fnB', startLine: 30, endLine: 40, nodeType: 'Function' },
+          { id: 'id-a', name: 'fnA', startLine: 10, endLine: 20, nodeType: 'Function' },
+          { id: 'id-b', name: 'fnB', startLine: 30, endLine: 40, nodeType: 'Function' },
         ],
       }),
     };
-    const siblings = await fetchSiblingSymbols(mockClient as never, '/file.ts', 'fnA', 10);
+    const siblings = await fetchSiblingSymbols(mockClient as never, '/file.ts', 'id-a');
     expect(siblings).toHaveLength(1);
     expect(siblings[0]?.name).toBe('fnB');
   });
@@ -35,12 +35,12 @@ describe('fetchSiblingSymbols', () => {
     const mockClient = {
       roQuery: vi.fn().mockResolvedValue({
         data: [
-          { name: 'fnA', startLine: 10, endLine: 20, nodeType: 'Function' },
-          { name: 'fnB', startLine: 30, endLine: 40, nodeType: 'Function' },
+          { id: 'id-a', name: 'fnA', startLine: 10, endLine: 20, nodeType: 'Function' },
+          { id: 'id-b', name: 'fnB', startLine: 30, endLine: 40, nodeType: 'Function' },
         ],
       }),
     };
-    const siblings = await fetchSiblingSymbols(mockClient as never, '/file.ts', 'fnB', 30);
+    const siblings = await fetchSiblingSymbols(mockClient as never, '/file.ts', 'id-b');
     expect(siblings).toHaveLength(1);
     expect(siblings[0]?.name).toBe('fnA');
   });
@@ -48,10 +48,10 @@ describe('fetchSiblingSymbols', () => {
   it('returns empty array for files with only one symbol', async () => {
     const mockClient = {
       roQuery: vi.fn().mockResolvedValue({
-        data: [{ name: 'lonelyFn', startLine: 10, endLine: 20, nodeType: 'Function' }],
+        data: [{ id: 'id-lonely', name: 'lonelyFn', startLine: 10, endLine: 20, nodeType: 'Function' }],
       }),
     };
-    const siblings = await fetchSiblingSymbols(mockClient as never, '/file.ts', 'lonelyFn', 10);
+    const siblings = await fetchSiblingSymbols(mockClient as never, '/file.ts', 'id-lonely');
     expect(siblings).toEqual([]);
   });
 });
diff --git a/packages/core/src/__tests__/node-identity-catalog.test.ts b/packages/core/src/__tests__/node-identity-catalog.test.ts
new file mode 100644
index 00000000..2fcda7c6
--- /dev/null
+++ b/packages/core/src/__tests__/node-identity-catalog.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildParsedFileEntities,
+  createFileEntityFromContent,
+  extractEntitiesForFile,
+  parseCode,
+  registerPlugins,
+} from '../pipeline';
+import { buildProjectSymbolCatalog, resolveProjectSymbolEdges } from '../pipeline/pipeline';
+
+describe('project symbol catalog', () => {
+  it('resolves a cross-file call to both persisted symbol ids before graph writes', () => {
+    registerPlugins();
+    const targetPath = '/project/target.ts';
+    const callerPath = '/project/caller.ts';
+    const targetContent = 'export function target(): number {\n  return 1;\n}\n';
+    const callerContent = [
+      "import { target } from './target';",
+      'export function caller(): number {',
+      '  return target();',
+      '}',
+      '',
+    ].join('\n');
+
+    const parse = (filePath: string, content: string) => {
+      const tree = parseCode(content, 'typescript', '.ts');
+      const extracted = extractEntitiesForFile(tree.rootNode, filePath);
+      if (filePath === callerPath && extracted.imports[0]) {
+        extracted.imports[0].resolvedPath = targetPath;
+      }
+      const file = createFileEntityFromContent(filePath, content, new Date(0));
+      return {
+        extracted,
+        parsed: buildParsedFileEntities(file, extracted, tree.rootNode, { deepAnalysis: true }),
+      };
+    };
+
+    const target = parse(targetPath, targetContent);
+    const caller = parse(callerPath, callerContent);
+    const catalog = buildProjectSymbolCatalog([target.parsed, caller.parsed]);
+
+    resolveProjectSymbolEdges([target.parsed, caller.parsed], catalog);
+
+    const edge = caller.parsed.callEdges[0];
+    expect(edge?.callerId).toBe(caller.extracted.functions.find(fn => fn.name === 'caller')?.id);
+    expect(edge?.calleeId).toBe(target.extracted.functions.find(fn => fn.name === 'target')?.id);
+    expect(edge?.callerId).toMatch(/^sym:v1:[a-f0-9]{64}$/);
+    expect(edge?.calleeId).toMatch(/^sym:v1:[a-f0-9]{64}$/);
+  });
+});
diff --git a/packages/core/src/__tests__/node-identity-final-gate.integration.test.ts b/packages/core/src/__tests__/node-identity-final-gate.integration.test.ts
new file mode 100644
index 00000000..6736e683
--- /dev/null
+++ b/packages/core/src/__tests__/node-identity-final-gate.integration.test.ts
@@ -0,0 +1,206 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createClient, resolveEmbeddedBinaryPaths, type GraphClient } from '@codegraph/graph';
+import { indexProject } from '../indexer';
+
+const describeIfAvailable = resolveEmbeddedBinaryPaths() ? describe : describe.skip;
+
+describeIfAvailable('node identity final integration gate', () => {
+  let client: GraphClient;
+  let dataDir: string;
+  let projectDir: string;
+  let fileAPath: string;
+  let fileBPath: string;
+  let previousEmbeddingProvider: string | undefined;
+
+  beforeAll(async () => {
+    previousEmbeddingProvider = process.env['CODEGRAPH_EMBEDDING_PROVIDER'];
+    process.env['CODEGRAPH_EMBEDDING_PROVIDER'] = 'none';
+
+    dataDir = await mkdtemp(join(tmpdir(), 'cg-node-identity-final-'));
+    client = await createClient({
+      driver: 'falkordblite',
+      databasePath: dataDir,
+      graphName: 'node_identity_final_gate',
+    } as never);
+
+    projectDir = mkdtempSync(join(tmpdir(), 'cg-node-identity-project-'));
+    fileAPath = resolve(projectDir, 'fileA.ts');
+    fileBPath = resolve(projectDir, 'fileB.ts');
+    writeFileSync(fileAPath, 'export function target(): number {\n  return 42;\n}\n');
+    writeFileSync(
+      fileBPath,
+      [
+        "import { target } from './fileA';",
+        '',
+        'export function caller(): number {',
+        '  return target();',
+        '}',
+        '',
+      ].join('\n'),
+    );
+  }, 60_000);
+
+  afterAll(async () => {
+    await client?.close();
+    if (dataDir) await rm(dataDir, { recursive: true, force: true });
+    if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+    if (previousEmbeddingProvider === undefined) {
+      delete process.env['CODEGRAPH_EMBEDDING_PROVIDER'];
+    } else {
+      process.env['CODEGRAPH_EMBEDDING_PROVIDER'] = previousEmbeddingProvider;
+    }
+  });
+
+  it('preserves target identity and inbound edges across line shift, then removes the prior generation on force reindex', async () => {
+    const initial = await indexProject(projectDir, {
+      client,
+      includePatterns: ['*.ts'],
+      embeddings: false,
+      gitSync: false,
+      force: true,
+    });
+    expect(initial.success).toBe(true);
+
+    const before = await client.roQuery<{ id: string; startLine: number }>(
+      `MATCH (target:Function {name: 'target', filePath: $fileAPath})
+       RETURN target.id AS id, target.startLine AS startLine`,
+      { params: { fileAPath } },
+    );
+    expect(before.data).toEqual([{ id: expect.stringMatching(/^sym:v1:/), startLine: 1 }]);
+    const targetId = before.data[0]!.id;
+
+    const inboundBefore = await client.roQuery<{ calls: number; imports: number }>(
+      `MATCH (target:Function {id: $targetId})
+       OPTIONAL MATCH (:Function {filePath: $fileBPath})-[call:CALLS]->(target)
+       OPTIONAL MATCH (:File {filePath: $fileBPath})-[imported:IMPORTS_SYMBOL]->(target)
+       RETURN count(DISTINCT call) AS calls, count(DISTINCT imported) AS imports`,
+      { params: { targetId, fileBPath } },
+    );
+    expect(inboundBefore.data).toEqual([{ calls: 1, imports: 1 }]);
+
+    writeFileSync(
+      fileAPath,
+      [
+        '// inserted one',
+        '// inserted two',
+        '',
+        'export function target(): number {',
+        '  return 42;',
+        '}',
+        '',
+      ].join('\n'),
+    );
+
+    const querySpy = vi.spyOn(client, 'query');
+    const incremental = await indexProject(projectDir, {
+      client,
+      includePatterns: ['*.ts'],
+      embeddings: false,
+      gitSync: false,
+      force: false,
+    });
+    expect(incremental.success).toBe(true);
+
+    const sweepCall = querySpy.mock.calls.find(([cypher, options]) =>
+      cypher.includes('$currentIds') &&
+      Array.isArray(options?.params?.['currentIds']) &&
+      options.params['currentIds'].includes(targetId),
+    );
+    expect(sweepCall).toBeDefined();
+    querySpy.mockRestore();
+
+    const after = await client.roQuery<{ id: string; startLine: number }>(
+      `MATCH (target:Function {name: 'target', filePath: $fileAPath})
+       RETURN target.id AS id, target.startLine AS startLine`,
+      { params: { fileAPath } },
+    );
+    expect(after.data).toEqual([{ id: targetId, startLine: 4 }]);
+
+    const inboundAfter = await client.roQuery<{ calls: number; imports: number }>(
+      `MATCH (target:Function {id: $targetId})
+       OPTIONAL MATCH (:Function {filePath: $fileBPath})-[call:CALLS]->(target)
+       OPTIONAL MATCH (:File {filePath: $fileBPath})-[imported:IMPORTS_SYMBOL]->(target)
+       RETURN count(DISTINCT call) AS calls, count(DISTINCT imported) AS imports`,
+      { params: { targetId, fileBPath } },
+    );
+    expect(inboundAfter.data).toEqual([{ calls: 1, imports: 1 }]);
+
+    const idIndexes = await client.roQuery<{ label: string; properties: string[] }>(
+      `CALL db.indexes()
+       YIELD label, properties
+       WHERE label IN ['Function', 'Class', 'Interface', 'Variable', 'Type', 'Component', 'Method']
+         AND 'id' IN properties
+       RETURN label, properties`,
+    );
+    expect(new Set(idIndexes.data.map((row) => row.label))).toEqual(
+      new Set(['Function', 'Class', 'Interface', 'Variable', 'Type', 'Component']),
+    );
+
+    const oldGeneration = 'node-identity-final-gate-prior';
+    const staleId = 'sym:v1:stale-final-gate';
+    await client.query(
+      `MATCH (n {projectId: $projectId})
+       SET n.indexGeneration = $oldGeneration
+       WITH count(n) AS stamped
+       CREATE (:Function {
+         id: $staleId,
+         name: 'removedTarget',
+         filePath: $fileAPath,
+         startLine: 999,
+         projectId: $projectId,
+         indexGeneration: $oldGeneration
+       })
+       RETURN stamped`,
+      { params: { projectId: initial.projectId, oldGeneration, staleId, fileAPath } },
+    );
+
+    const forced = await indexProject(projectDir, {
+      client,
+      includePatterns: ['*.ts'],
+      embeddings: false,
+      gitSync: false,
+      force: true,
+    });
+    expect(forced.success).toBe(true);
+    expect(forced.projectId).toBe(initial.projectId);
+
+    const detached = await client.roQuery<{ detachedSymbols: number }>(
+      `MATCH (n)
+       WHERE n.projectId = $projectId
+         AND (n:Function OR n:Class OR n:Interface OR n:Variable OR n:Type OR n:Component)
+       OPTIONAL MATCH (f:File)-[:CONTAINS]->(n)
+       WITH n, f
+       WHERE f IS NULL
+       RETURN count(n) AS detachedSymbols`,
+      { params: { projectId: initial.projectId } },
+    );
+    const duplicates = await client.roQuery<{ label: string; id: string; copies: number }>(
+      `MATCH (n)
+       WHERE n.projectId = $projectId
+         AND (n:Function OR n:Class OR n:Interface OR n:Variable OR n:Type OR n:Component)
+       WITH labels(n)[0] AS label, n.id AS id, count(*) AS copies
+       WHERE copies > 1
+       RETURN label, id, copies`,
+      { params: { projectId: initial.projectId } },
+    );
+    const priorGeneration = await client.roQuery<{ survivors: number }>(
+      `MATCH (n {projectId: $projectId, indexGeneration: $oldGeneration})
+       RETURN count(n) AS survivors`,
+      { params: { projectId: initial.projectId, oldGeneration } },
+    );
+    const staleSymbols = await client.roQuery<{ survivors: number }>(
+      `MATCH (n {projectId: $projectId, id: $staleId})
+       RETURN count(n) AS survivors`,
+      { params: { projectId: initial.projectId, staleId } },
+    );
+
+    expect(detached.data).toEqual([{ detachedSymbols: 0 }]);
+    expect(duplicates.data).toEqual([]);
+    expect(priorGeneration.data).toEqual([{ survivors: 0 }]);
+    expect(staleSymbols.data).toEqual([{ survivors: 0 }]);
+  }, 120_000);
+});
diff --git a/packages/core/src/__tests__/pipeline-barrel-resolution.test.ts b/packages/core/src/__tests__/pipeline-barrel-resolution.test.ts
index cd3f3986..88605e57 100644
--- a/packages/core/src/__tests__/pipeline-barrel-resolution.test.ts
+++ b/packages/core/src/__tests__/pipeline-barrel-resolution.test.ts
@@ -49,6 +49,10 @@ import {
   resolveReExportChain,
 } from '../pipeline';
 import type { ImportEntity } from '@codegraph/types';
+import {
+  buildProjectSymbolCatalog,
+  resolveProjectSymbolEdges,
+} from '../pipeline/pipeline';
 
 describe('resolveReExportChain', () => {
   it('resolves a two-level named re-export chain to the origin file and name', () => {
@@ -413,15 +417,10 @@ describe('buildParsedFileEntities: barrel-aware CALL edges (end-to-end)', () =>
       main.rootNode,
       { deepAnalysis: true, includeExternals: false },
     );
+    resolveProjectSymbolEdges([built], buildProjectSymbolCatalog([built]));
 
-    const methodCall = built.callEdges.find((e) => e.calleeId.includes(':method'));
-    // Bug 1's receiver binding resolves `s.method()` to *some* file for
-    // `Service` (the barrel, since that's what the import's resolvedPath
-    // says) but without barrel-chain resolution, that's the barrel file,
-    // which has no `method` Function node, so this callee id names a file
-    // that doesn't define `method`.
-    expect(methodCall).toBeDefined();
-    expect(methodCall!.calleeId).toBe(`Function:${join(dir, 'barrel.ts')}:method`);
+    const callerId = built.functions.find((fn) => fn.name === 'run')?.id;
+    expect(built.callEdges.find((edge) => edge.callerId === callerId)).toBeUndefined();
   });
 
   it('with a barrelIndex, the receiver call resolves through the two-level barrel chain to service.ts', () => {
@@ -442,10 +441,19 @@ describe('buildParsedFileEntities: barrel-aware CALL edges (end-to-end)', () =>
       main.rootNode,
       { deepAnalysis: true, includeExternals: false, barrelIndex },
     );
+    const serviceBuilt = buildParsedFileEntities(
+      service.fileEntity,
+      service.extracted,
+      service.rootNode,
+      { deepAnalysis: true, includeExternals: false, barrelIndex },
+    );
+    const files = [built, serviceBuilt];
+    resolveProjectSymbolEdges(files, buildProjectSymbolCatalog(files));
 
-    const methodCall = built.callEdges.find((e) => e.calleeId.includes(':method'));
+    const callerId = built.functions.find((fn) => fn.name === 'run')?.id;
+    const methodCall = built.callEdges.find((edge) => edge.callerId === callerId);
     expect(methodCall).toBeDefined();
-    expect(methodCall!.calleeId).toBe(`Function:${join(dir, 'service.ts')}:method`);
+    expect(methodCall!.calleeId).toBe(serviceBuilt.functions.find((fn) => fn.name === 'method')?.id);
 
     // The File-to-File IMPORTS edge stays pointing at the barrel: that edge
     // describes what main.ts actually imports from, which is genuinely the
@@ -470,13 +478,22 @@ describe('buildParsedFileEntities: barrel-aware CALL edges (end-to-end)', () =>
       consumer.rootNode,
       { deepAnalysis: true, includeExternals: false, barrelIndex },
     );
+    const originBuilt = buildParsedFileEntities(
+      origin.fileEntity,
+      origin.extracted,
+      origin.rootNode,
+      { deepAnalysis: true, includeExternals: false, barrelIndex },
+    );
+    const files = [built, originBuilt];
+    resolveProjectSymbolEdges(files, buildProjectSymbolCatalog(files));
 
-    const call = built.callEdges.find((e) => e.callerId.includes(':useAlias'));
+    const callerId = built.functions.find((fn) => fn.name === 'useAlias')?.id;
+    const call = built.callEdges.find((edge) => edge.callerId === callerId);
     expect(call).toBeDefined();
     // The real Function node at origin.ts is named aliasedFn, not renamedFn
     // (the call site's local alias). The callee id must search for the
     // origin-declared name, or this edge silently drops at graph-write time.
-    expect(call!.calleeId).toBe(`Function:${join(dir, 'origin.ts')}:aliasedFn`);
+    expect(call!.calleeId).toBe(originBuilt.functions.find((fn) => fn.name === 'aliasedFn')?.id);
   });
 
   it('reviewer blocker 5 (end-to-end): a mixed barrel resolves its own local export to itself, not the unrelated star target', () => {
@@ -498,10 +515,19 @@ describe('buildParsedFileEntities: barrel-aware CALL edges (end-to-end)', () =>
       consumer.rootNode,
       { deepAnalysis: true, includeExternals: false, barrelIndex, localExportsIndex },
     );
+    const targetBuilt = buildParsedFileEntities(
+      mixedBarrel.fileEntity,
+      mixedBarrel.extracted,
+      mixedBarrel.rootNode,
+      { deepAnalysis: true, includeExternals: false, barrelIndex, localExportsIndex },
+    );
+    const files = [built, targetBuilt];
+    resolveProjectSymbolEdges(files, buildProjectSymbolCatalog(files));
 
-    const call = built.callEdges.find((e) => e.callerId.includes(':useMixed'));
+    const callerId = built.functions.find((fn) => fn.name === 'useMixed')?.id;
+    const call = built.callEdges.find((edge) => edge.callerId === callerId);
     expect(call).toBeDefined();
-    expect(call!.calleeId).toBe(`Function:${join(dir, 'mixedBarrel.ts')}:localOnly`);
+    expect(call!.calleeId).toBe(targetBuilt.functions.find((fn) => fn.name === 'localOnly')?.id);
   });
 
   it('without localExportsIndex, the mixed-barrel local export can be mis-resolved through the unrelated star hop (documents the degraded case)', () => {
@@ -521,13 +547,11 @@ describe('buildParsedFileEntities: barrel-aware CALL edges (end-to-end)', () =>
       consumer.rootNode,
       { deepAnalysis: true, includeExternals: false, barrelIndex },
     );
+    const files = [built];
+    resolveProjectSymbolEdges(files, buildProjectSymbolCatalog(files));
 
-    const call = built.callEdges.find((e) => e.callerId.includes(':useMixed'));
-    expect(call).toBeDefined();
-    // Without the local-exports base case, the chain follows mixedBarrel's
-    // star re-export and searches for `localOnly` at otherThing.ts, where it
-    // doesn't exist, so this callee id names a file that doesn't define it.
-    expect(call!.calleeId).toBe(`Function:${join(dir, 'otherThing.ts')}:localOnly`);
+    const callerId = built.functions.find((fn) => fn.name === 'useMixed')?.id;
+    expect(built.callEdges.find((edge) => edge.callerId === callerId)).toBeUndefined();
   });
 });
 
@@ -734,15 +758,30 @@ describe('buildParsedFileEntities: multi-star barrel end-to-end (reviewer follow
       consumer.rootNode,
       { deepAnalysis: true, includeExternals: false, barrelIndex, localExportsIndex },
     );
+    const moduleABuilt = buildParsedFileEntities(
+      moduleA.fileEntity,
+      moduleA.extracted,
+      moduleA.rootNode,
+      { deepAnalysis: true, includeExternals: false, barrelIndex, localExportsIndex },
+    );
+    const moduleBBuilt = buildParsedFileEntities(
+      moduleB.fileEntity,
+      moduleB.extracted,
+      moduleB.rootNode,
+      { deepAnalysis: true, includeExternals: false, barrelIndex, localExportsIndex },
+    );
+    const files = [built, moduleABuilt, moduleBBuilt];
+    resolveProjectSymbolEdges(files, buildProjectSymbolCatalog(files));
 
+    const callerId = built.functions.find((fn) => fn.name === 'useMultiStar')?.id;
     const callees = built.callEdges
-      .filter((e) => e.callerId.includes(':useMultiStar'))
+      .filter((edge) => edge.callerId === callerId)
       .map((e) => e.calleeId)
       .sort();
     expect(callees).toEqual([
-      `Function:${join(dir, 'moduleA.ts')}:fnA`,
-      `Function:${join(dir, 'moduleB.ts')}:fnB`,
-    ]);
+      moduleABuilt.functions.find((fn) => fn.name === 'fnA')?.id,
+      moduleBBuilt.functions.find((fn) => fn.name === 'fnB')?.id,
+    ].sort());
   });
 
   it('(b) useMultiStarTypes() TypeRefs: TypeA keys on typeA.ts and TypeB keys on typeB.ts', () => {
diff --git a/packages/core/src/__tests__/pipeline-exports-and-imports-symbol-edges.test.ts b/packages/core/src/__tests__/pipeline-exports-and-imports-symbol-edges.test.ts
index 2c580613..25366cae 100644
--- a/packages/core/src/__tests__/pipeline-exports-and-imports-symbol-edges.test.ts
+++ b/packages/core/src/__tests__/pipeline-exports-and-imports-symbol-edges.test.ts
@@ -103,11 +103,14 @@ describe('buildParsedFileEntities: exportsEdges (end-to-end)', () => {
 
     const byName = new Map(built.exportsEdges.map((e) => [e.symbolName, e]));
 
-    expect(byName.get('exportedFn')).toEqual({ filePath, symbolName: 'exportedFn', symbolKind: 'Function' });
-    expect(byName.get('ExportedClass')).toEqual({ filePath, symbolName: 'ExportedClass', symbolKind: 'Class' });
-    expect(byName.get('ExportedInterface')).toEqual({ filePath, symbolName: 'ExportedInterface', symbolKind: 'Interface' });
-    expect(byName.get('exportedVar')).toEqual({ filePath, symbolName: 'exportedVar', symbolKind: 'Variable' });
-    expect(byName.get('ExportedType')).toEqual({ filePath, symbolName: 'ExportedType', symbolKind: 'Type' });
+    expect(byName.get('exportedFn')).toMatchObject({ filePath, symbolName: 'exportedFn', symbolKind: 'Function' });
+    expect(byName.get('ExportedClass')).toMatchObject({ filePath, symbolName: 'ExportedClass', symbolKind: 'Class' });
+    expect(byName.get('ExportedInterface')).toMatchObject({ filePath, symbolName: 'ExportedInterface', symbolKind: 'Interface' });
+    expect(byName.get('exportedVar')).toMatchObject({ filePath, symbolName: 'exportedVar', symbolKind: 'Variable' });
+    expect(byName.get('ExportedType')).toMatchObject({ filePath, symbolName: 'ExportedType', symbolKind: 'Type' });
+    expect(byName.get('exportedFn')?.toId).toBe(
+      built.functions.find((fn) => fn.name === 'exportedFn')?.id,
+    );
 
     // Unexported siblings must not produce an EXPORTS edge.
     expect(byName.has('localFn')).toBe(false);
@@ -201,7 +204,7 @@ describe('buildParsedFileEntities: importsSymbolEdges (end-to-end)', () => {
 
     const edge = built.importsSymbolEdges.find((e) => e.symbolName === 'targetFn' && !e.alias);
     expect(edge).toBeDefined();
-    expect(edge).toEqual({
+    expect(edge).toMatchObject({
       fromFilePath: join(dir, 'consumer.ts'),
       toFilePath: join(dir, 'target.ts'),
       symbolName: 'targetFn',
@@ -219,7 +222,7 @@ describe('buildParsedFileEntities: importsSymbolEdges (end-to-end)', () => {
     // named renamedFn at target.ts, which doesn't exist there).
     const edge = built.importsSymbolEdges.find((e) => e.alias === 'renamedFn');
     expect(edge).toBeDefined();
-    expect(edge).toEqual({
+    expect(edge).toMatchObject({
       fromFilePath: join(dir, 'consumer.ts'),
       toFilePath: join(dir, 'target.ts'),
       symbolName: 'otherFn',
diff --git a/packages/core/src/__tests__/pipeline-python-cross-file-calls.test.ts b/packages/core/src/__tests__/pipeline-python-cross-file-calls.test.ts
index ffc29b5a..f249909a 100644
--- a/packages/core/src/__tests__/pipeline-python-cross-file-calls.test.ts
+++ b/packages/core/src/__tests__/pipeline-python-cross-file-calls.test.ts
@@ -32,6 +32,10 @@ import {
   createFileEntityFromContent,
   buildParsedFileEntities,
 } from '../pipeline';
+import {
+  buildProjectSymbolCatalog,
+  resolveProjectSymbolEdges,
+} from '../pipeline/pipeline';
 
 describe('buildParsedFileEntities: Python cross-file call resolution (end-to-end)', () => {
   let dir: string;
@@ -62,6 +66,17 @@ describe('buildParsedFileEntities: Python cross-file call resolution (end-to-end
     return { rootNode: syntaxTree.rootNode, extracted, fileEntity };
   }
 
+  function build(filePath: string) {
+    const parsed = parseAndExtract(filePath);
+    return buildParsedFileEntities(
+      parsed.fileEntity,
+      parsed.extracted,
+      parsed.rootNode,
+      { deepAnalysis: true, includeExternals: false },
+      dir,
+    );
+  }
+
   it('(e) resolves the IMPORTS edge to the real file on disk (bug 1: no phantom edge for an existing module)', () => {
     const caller = parseAndExtract(join(dir, 'caller.py'));
 
@@ -95,37 +110,27 @@ describe('buildParsedFileEntities: Python cross-file call resolution (end-to-end
   });
 
   it('(e) buildCallEdgesFromRefs keys the CALLS edge on the resolved callee file, not the caller file (bugs 2 + 3 together)', () => {
-    const caller = parseAndExtract(join(dir, 'caller.py'));
-
-    const built = buildParsedFileEntities(
-      caller.fileEntity,
-      caller.extracted,
-      caller.rootNode,
-      { deepAnalysis: true, includeExternals: false },
-      dir,
-    );
+    const built = build(join(dir, 'caller.py'));
+    const target = build(join(dir, 'mod.py'));
+    resolveProjectSymbolEdges([built, target], buildProjectSymbolCatalog([built, target]));
 
-    const call = built.callEdges.find((e) => e.callerId.includes(':caller'));
+    const callerId = built.functions.find((fn) => fn.name === 'caller')?.id;
+    const targetId = target.functions.find((fn) => fn.name === 'fn')?.id;
+    const call = built.callEdges.find((e) => e.callerId === callerId);
     expect(call).toBeDefined();
     // Before the fix: this edge either didn't exist (bug 2 dropped it
     // entirely) or, if it had, would have pointed at
     // Function:<dir>/caller.py:fn (bug 3), a Function node that doesn't
     // exist there since fn is defined in mod.py.
-    expect(call!.calleeId).toBe(`Function:${join(dir, 'mod.py')}:fn`);
+    expect(call!.calleeId).toBe(targetId);
   });
 
   it('(e) a call to an unresolvable cross-file name produces no edge at all, not a wrong same-file one', () => {
-    const phantomCaller = parseAndExtract(join(dir, 'phantom_caller.py'));
-
-    const built = buildParsedFileEntities(
-      phantomCaller.fileEntity,
-      phantomCaller.extracted,
-      phantomCaller.rootNode,
-      { deepAnalysis: true, includeExternals: false },
-      dir,
-    );
+    const built = build(join(dir, 'phantom_caller.py'));
+    resolveProjectSymbolEdges([built], buildProjectSymbolCatalog([built]));
 
-    const call = built.callEdges.find((e) => e.callerId.includes(':caller'));
+    const callerId = built.functions.find((fn) => fn.name === 'caller')?.id;
+    const call = built.callEdges.find((e) => e.callerId === callerId);
     expect(call).toBeUndefined();
   });
 });
diff --git a/packages/core/src/__tests__/pipeline-python-review-wave-b.test.ts b/packages/core/src/__tests__/pipeline-python-review-wave-b.test.ts
index 8247baca..e9a9b96e 100644
--- a/packages/core/src/__tests__/pipeline-python-review-wave-b.test.ts
+++ b/packages/core/src/__tests__/pipeline-python-review-wave-b.test.ts
@@ -40,6 +40,10 @@ import {
   createFileEntityFromContent,
   buildParsedFileEntities,
 } from '../pipeline';
+import {
+  buildProjectSymbolCatalog,
+  resolveProjectSymbolEdges,
+} from '../pipeline/pipeline';
 
 function parseAndExtract(filePath: string) {
   const content = readFileSync(filePath, 'utf-8');
@@ -49,6 +53,23 @@ function parseAndExtract(filePath: string) {
   return { rootNode: syntaxTree.rootNode, extracted, fileEntity };
 }
 
+function buildFile(filePath: string, projectRoot: string) {
+  const parsed = parseAndExtract(filePath);
+  return buildParsedFileEntities(
+    parsed.fileEntity,
+    parsed.extracted,
+    parsed.rootNode,
+    { deepAnalysis: true, includeExternals: false },
+    projectRoot,
+  );
+}
+
+function resolveFiles(filePaths: string[], projectRoot: string) {
+  const built = filePaths.map((filePath) => buildFile(filePath, projectRoot));
+  resolveProjectSymbolEdges(built, buildProjectSymbolCatalog(built));
+  return built;
+}
+
 describe('BLOCKER: aliased cross-file import resolves to the DECLARED name, not the local alias', () => {
   let dir: string;
 
@@ -75,23 +96,16 @@ describe('BLOCKER: aliased cross-file import resolves to the DECLARED name, not
     expect(realFn).toBeDefined();
     expect(realFn!.name).toBe('fn'); // NOT 'f' -- the target has no idea it was aliased on import
 
-    const consumer = parseAndExtract(join(dir, 'pkg', 'consumer_alias.py'));
-    const built = buildParsedFileEntities(
-      consumer.fileEntity,
-      consumer.extracted,
-      consumer.rootNode,
-      { deepAnalysis: true, includeExternals: false },
-      dir,
-    );
+    const [built, target] = resolveFiles([
+      join(dir, 'pkg', 'consumer_alias.py'),
+      join(dir, 'pkg', 'mod.py'),
+    ], dir);
 
-    const call = built.callEdges.find((e) => e.callerId.includes(':caller_alias'));
+    const callerId = built?.functions.find((fn) => fn.name === 'caller_alias')?.id;
+    const call = built?.callEdges.find((e) => e.callerId === callerId);
     expect(call).toBeDefined();
-    // packages/graph/src/operations.ts's CREATE_CALLS_EDGE MATCHes the callee
-    // by {name, filePath} parsed out of this exact string (parseEntityId
-    // splits on ':'). It must name mod.py's REAL function ('fn'), or the
-    // MATCH finds nothing and the edge silently drops at write time.
-    expect(call!.calleeId).toBe(`Function:${join(dir, 'pkg', 'mod.py')}:${realFn!.name}`);
-    expect(call!.calleeId).not.toBe(`Function:${join(dir, 'pkg', 'mod.py')}:f`);
+    const targetId = target?.functions.find((fn) => fn.name === realFn!.name)?.id;
+    expect(call!.calleeId).toBe(targetId);
   });
 
   it('a plain (non-aliased) cross-file import still resolves to the same declared name (regression check)', () => {
@@ -99,18 +113,15 @@ describe('BLOCKER: aliased cross-file import resolves to the DECLARED name, not
       join(dir, 'pkg', 'consumer_rel.py'),
       ['from .mod import fn', '', 'def caller_rel():', '    return fn()', ''].join('\n'),
     );
-    const consumer = parseAndExtract(join(dir, 'pkg', 'consumer_rel.py'));
-    const built = buildParsedFileEntities(
-      consumer.fileEntity,
-      consumer.extracted,
-      consumer.rootNode,
-      { deepAnalysis: true, includeExternals: false },
-      dir,
-    );
+    const [built, target] = resolveFiles([
+      join(dir, 'pkg', 'consumer_rel.py'),
+      join(dir, 'pkg', 'mod.py'),
+    ], dir);
 
-    const call = built.callEdges.find((e) => e.callerId.includes(':caller_rel'));
+    const callerId = built?.functions.find((fn) => fn.name === 'caller_rel')?.id;
+    const call = built?.callEdges.find((e) => e.callerId === callerId);
     expect(call).toBeDefined();
-    expect(call!.calleeId).toBe(`Function:${join(dir, 'pkg', 'mod.py')}:fn`);
+    expect(call!.calleeId).toBe(target?.functions.find((fn) => fn.name === 'fn')?.id);
   });
 });
 
@@ -143,18 +154,15 @@ describe('ADJACENT BUG 1: `import pkgns as p` resolves an attribute call through
   });
 
   it('p.init_fn() resolves to a CALLS edge into pkgns/__init__.py (was zero edges before this fix)', () => {
-    const consumer = parseAndExtract(join(dir, 'consumer.py'));
-    const built = buildParsedFileEntities(
-      consumer.fileEntity,
-      consumer.extracted,
-      consumer.rootNode,
-      { deepAnalysis: true, includeExternals: false },
-      dir,
-    );
+    const [built, target] = resolveFiles([
+      join(dir, 'consumer.py'),
+      join(dir, 'pkgns', '__init__.py'),
+    ], dir);
 
-    const call = built.callEdges.find((e) => e.callerId.includes(':caller'));
+    const callerId = built?.functions.find((fn) => fn.name === 'caller')?.id;
+    const call = built?.callEdges.find((e) => e.callerId === callerId);
     expect(call).toBeDefined();
-    expect(call!.calleeId).toBe(`Function:${join(dir, 'pkgns', '__init__.py')}:init_fn`);
+    expect(call!.calleeId).toBe(target?.functions.find((fn) => fn.name === 'init_fn')?.id);
   });
 });
 
diff --git a/packages/core/src/__tests__/pipeline-tier2-ruby-calls-regression.test.ts b/packages/core/src/__tests__/pipeline-tier2-ruby-calls-regression.test.ts
index 96711371..59b1078c 100644
--- a/packages/core/src/__tests__/pipeline-tier2-ruby-calls-regression.test.ts
+++ b/packages/core/src/__tests__/pipeline-tier2-ruby-calls-regression.test.ts
@@ -25,6 +25,10 @@ import {
   buildParsedFileEntities,
   languageRegistry,
 } from '../pipeline';
+import {
+  buildProjectSymbolCatalog,
+  resolveProjectSymbolEdges,
+} from '../pipeline/pipeline';
 
 describe('buildParsedFileEntities: tier-2 (Ruby) same-file calls unaffected by the context change', () => {
   let dir: string;
@@ -65,9 +69,12 @@ describe('buildParsedFileEntities: tier-2 (Ruby) same-file calls unaffected by t
       { deepAnalysis: true, includeExternals: false },
       dir,
     );
+    resolveProjectSymbolEdges([built], buildProjectSymbolCatalog([built]));
 
-    const call = built.callEdges.find((e) => e.callerId.includes(':caller'));
+    const callerId = built.functions.find((fn) => fn.name === 'caller')?.id;
+    const calleeId = built.functions.find((fn) => fn.name === 'helper')?.id;
+    const call = built.callEdges.find((e) => e.callerId === callerId);
     expect(call).toBeDefined();
-    expect(call!.calleeId).toBe(`Function:${filePath}:helper`);
+    expect(call!.calleeId).toBe(calleeId);
   });
 });
diff --git a/packages/core/src/__tests__/service.test.ts b/packages/core/src/__tests__/service.test.ts
index 0341d6f7..ce907ddf 100644
--- a/packages/core/src/__tests__/service.test.ts
+++ b/packages/core/src/__tests__/service.test.ts
@@ -254,7 +254,7 @@ describe('CodeGraphService', () => {
       // Should NOT contain elementId (removed)
       expect(cypher).not.toContain('elementId');
       // Should use property-based matching
-      expect(cypher).toContain('n.filePath = $id');
+      expect(cypher).toContain('n.id = $id');
     });
   });
 
@@ -290,7 +290,7 @@ describe('CodeGraphService', () => {
         .mockResolvedValueOnce({
           data: [
             { n: { filePath: '/src/app.ts' }, labels: ['File'] },
-            { n: { name: 'render', filePath: '/src/app.ts', startLine: 5 }, labels: ['Function'] },
+            { n: { id: 'sym:v1:render', name: 'render', filePath: '/src/app.ts', startLine: 5 }, labels: ['Function'] },
           ],
           metadata: null,
         });
@@ -298,7 +298,7 @@ describe('CodeGraphService', () => {
       const result = await codeGraphService.getNodesPaginated();
 
       expect(result.nodes[0]!.id).toBe('File:/src/app.ts');
-      expect(result.nodes[1]!.id).toBe('Function:/src/app.ts:render:5');
+      expect(result.nodes[1]!.id).toBe('sym:v1:render');
     });
 
     it('applies type filtering with dialect labelCheckExpr', async () => {
@@ -374,36 +374,34 @@ describe('CodeGraphService', () => {
       expect(result.direction).toBe('both');
     });
 
-    it('parses File: IDs correctly using path match', async () => {
+    it('matches opaque IDs without parsing them', async () => {
       mockClient.roQuery.mockResolvedValueOnce({ data: [], metadata: null });
 
-      await codeGraphService.getNeighbors('File:/src/index.ts');
+      await codeGraphService.getNeighbors('sym:v1:opaque');
 
       const cypher: string = mockClient.roQuery.mock.calls[0][0];
-      expect(cypher).toContain('center.filePath = $actualPath');
+      expect(cypher).toContain('center.id = $id');
       const params = mockClient.roQuery.mock.calls[0][1];
-      expect(params.params.actualPath).toBe('/src/index.ts');
+      expect(params.params.id).toBe('sym:v1:opaque');
     });
 
-    it('parses composite IDs (Label:filePath:name:line)', async () => {
+    it('does not derive source coordinates from opaque IDs', async () => {
       mockClient.roQuery.mockResolvedValueOnce({ data: [], metadata: null });
 
-      await codeGraphService.getNeighbors('Function:/src/app.ts:render:15');
+      await codeGraphService.getNeighbors('sym:v1:opaque');
 
       const params = mockClient.roQuery.mock.calls[0][1];
-      expect(params.params.filePath).toBe('/src/app.ts');
-      expect(params.params.name).toBe('render');
-      expect(params.params.line).toBe(15);
+      expect(params.params).toEqual({ id: 'sym:v1:opaque', limit: 50 });
     });
 
-    it('falls back to simple name/path match for simple IDs', async () => {
+    it('does not fall back to symbol name or path matching', async () => {
       mockClient.roQuery.mockResolvedValueOnce({ data: [], metadata: null });
 
       await codeGraphService.getNeighbors('myFunction');
 
       const cypher: string = mockClient.roQuery.mock.calls[0][0];
-      expect(cypher).toContain('center.name = $simpleId');
-      expect(cypher).toContain('center.filePath = $simpleId');
+      expect(cypher).not.toContain('center.name =');
+      expect(cypher).not.toContain('center.filePath = $id');
     });
 
     it('uses correct match pattern for direction=in', async () => {
@@ -450,7 +448,7 @@ describe('CodeGraphService', () => {
       mockClient.roQuery.mockResolvedValueOnce({
         data: [
           {
-            neighbor: { name: 'helper', filePath: '/src/util.ts', startLine: 5 },
+            neighbor: { id: 'sym:v1:helper', name: 'helper', filePath: '/src/util.ts', startLine: 5 },
             neighborLabels: ['Function'],
             r: { weight: 1 },
             rType: 'CALLS',
@@ -462,7 +460,7 @@ describe('CodeGraphService', () => {
       const result = await codeGraphService.getNeighbors('File:/src/index.ts', 'out');
 
       expect(result.nodes).toHaveLength(1);
-      expect(result.nodes[0]!.id).toBe('Function:/src/util.ts:helper:5');
+      expect(result.nodes[0]!.id).toBe('sym:v1:helper');
       expect(result.nodes[0]!.label).toBe('Function');
       expect(result.nodes[0]!.displayName).toBe('helper');
 
diff --git a/packages/core/src/__tests__/services-helpers.test.ts b/packages/core/src/__tests__/services-helpers.test.ts
index 684e6d20..de063f9d 100644
--- a/packages/core/src/__tests__/services-helpers.test.ts
+++ b/packages/core/src/__tests__/services-helpers.test.ts
@@ -140,10 +140,21 @@ describe('generateNodeId: Entity uses text + type (its real MERGE key), reachabl
   });
 });
 
-describe('generateNodeId: symbol labels keep the existing name/filePath/startLine-or-line scheme', () => {
-  it('still builds ids from name, filePath and startLine for Function/Class/etc.', () => {
+describe('generateNodeId: symbol labels expose persisted opaque ids', () => {
+  it('returns the persisted id without rebuilding it from mutable location fields', () => {
+    const persistedId = `sym:v1:${'a'.repeat(64)}`;
+    const id = generateNodeId('Function', {
+      id: persistedId,
+      name: 'doThing',
+      filePath: '/src/a.ts',
+      startLine: 10,
+    });
+    expect(id).toBe(persistedId);
+  });
+
+  it('does not synthesize a location-based id when persisted identity is absent', () => {
     const id = generateNodeId('Function', { name: 'doThing', filePath: '/src/a.ts', startLine: 10 });
-    expect(id).toBe('Function:/src/a.ts:doThing:10');
+    expect(id).toBe('Function:unknown');
   });
 
   it('still builds the single-key File id', () => {
diff --git a/packages/core/src/embed-nodes.ts b/packages/core/src/embed-nodes.ts
index 41456631..b42d7a2a 100644
--- a/packages/core/src/embed-nodes.ts
+++ b/packages/core/src/embed-nodes.ts
@@ -85,14 +85,14 @@ const QUERIES = {
   FUNCTIONS_NEEDING_EMBEDDING: `
     MATCH (fn:Function)
     WHERE fn.embedding IS NULL
-    RETURN fn.name as name, fn.filePath as filePath, fn.startLine as startLine,
+    RETURN fn.id as id, fn.name as name, fn.filePath as filePath, fn.startLine as startLine,
            fn.endLine as endLine, fn.isExported as isExported, fn.isAsync as isAsync,
            fn.isArrow as isArrow, fn.params as params, fn.returnType as returnType,
            fn.docstring as docstring
   `,
   ALL_FUNCTIONS: `
     MATCH (fn:Function)
-    RETURN fn.name as name, fn.filePath as filePath, fn.startLine as startLine,
+    RETURN fn.id as id, fn.name as name, fn.filePath as filePath, fn.startLine as startLine,
            fn.endLine as endLine, fn.isExported as isExported, fn.isAsync as isAsync,
            fn.isArrow as isArrow, fn.params as params, fn.returnType as returnType,
            fn.docstring as docstring
@@ -102,13 +102,13 @@ const QUERIES = {
   CLASSES_NEEDING_EMBEDDING: `
     MATCH (c:Class)
     WHERE c.embedding IS NULL
-    RETURN c.name as name, c.filePath as filePath, c.startLine as startLine,
+    RETURN c.id as id, c.name as name, c.filePath as filePath, c.startLine as startLine,
            c.endLine as endLine, c.isExported as isExported, c.isAbstract as isAbstract,
            c.extends as extends_, c.implements as implements_, c.docstring as docstring
   `,
   ALL_CLASSES: `
     MATCH (c:Class)
-    RETURN c.name as name, c.filePath as filePath, c.startLine as startLine,
+    RETURN c.id as id, c.name as name, c.filePath as filePath, c.startLine as startLine,
            c.endLine as endLine, c.isExported as isExported, c.isAbstract as isAbstract,
            c.extends as extends_, c.implements as implements_, c.docstring as docstring
   `,
@@ -117,13 +117,13 @@ const QUERIES = {
   INTERFACES_NEEDING_EMBEDDING: `
     MATCH (i:Interface)
     WHERE i.embedding IS NULL
-    RETURN i.name as name, i.filePath as filePath, i.startLine as startLine,
+    RETURN i.id as id, i.name as name, i.filePath as filePath, i.startLine as startLine,
            i.endLine as endLine, i.isExported as isExported,
            i.extends as extends_, i.docstring as docstring
   `,
   ALL_INTERFACES: `
     MATCH (i:Interface)
-    RETURN i.name as name, i.filePath as filePath, i.startLine as startLine,
+    RETURN i.id as id, i.name as name, i.filePath as filePath, i.startLine as startLine,
            i.endLine as endLine, i.isExported as isExported,
            i.extends as extends_, i.docstring as docstring
   `,
@@ -132,12 +132,12 @@ const QUERIES = {
   VARIABLES_NEEDING_EMBEDDING: `
     MATCH (v:Variable)
     WHERE v.embedding IS NULL
-    RETURN v.name as name, v.filePath as filePath, v.line as line,
+    RETURN v.id as id, v.name as name, v.filePath as filePath, v.line as line,
            v.kind as kind, v.type as type_, v.isExported as isExported
   `,
   ALL_VARIABLES: `
     MATCH (v:Variable)
-    RETURN v.name as name, v.filePath as filePath, v.line as line,
+    RETURN v.id as id, v.name as name, v.filePath as filePath, v.line as line,
            v.kind as kind, v.type as type_, v.isExported as isExported
   `,
 
@@ -145,13 +145,13 @@ const QUERIES = {
   TYPES_NEEDING_EMBEDDING: `
     MATCH (t:Type)
     WHERE t.embedding IS NULL
-    RETURN t.name as name, t.filePath as filePath, t.startLine as startLine,
+    RETURN t.id as id, t.name as name, t.filePath as filePath, t.startLine as startLine,
            t.endLine as endLine, t.kind as kind, t.isExported as isExported,
            t.docstring as docstring
   `,
   ALL_TYPES: `
     MATCH (t:Type)
-    RETURN t.name as name, t.filePath as filePath, t.startLine as startLine,
+    RETURN t.id as id, t.name as name, t.filePath as filePath, t.startLine as startLine,
            t.endLine as endLine, t.kind as kind, t.isExported as isExported,
            t.docstring as docstring
   `,
@@ -160,13 +160,13 @@ const QUERIES = {
   COMPONENTS_NEEDING_EMBEDDING: `
     MATCH (comp:Component)
     WHERE comp.embedding IS NULL
-    RETURN comp.name as name, comp.filePath as filePath, comp.startLine as startLine,
+    RETURN comp.id as id, comp.name as name, comp.filePath as filePath, comp.startLine as startLine,
            comp.endLine as endLine, comp.isExported as isExported,
            comp.propsType as propsType, comp.props as props
   `,
   ALL_COMPONENTS: `
     MATCH (comp:Component)
-    RETURN comp.name as name, comp.filePath as filePath, comp.startLine as startLine,
+    RETURN comp.id as id, comp.name as name, comp.filePath as filePath, comp.startLine as startLine,
            comp.endLine as endLine, comp.isExported as isExported,
            comp.propsType as propsType, comp.props as props
   `,
@@ -222,6 +222,7 @@ const rowMappers = {
     loc: r.loc as number,
   }),
   Function: (r: Record<string, unknown>) => ({
+    id: r.id as string,
     name: r.name as string,
     filePath: r.filePath as string,
     startLine: r.startLine as number,
@@ -235,6 +236,7 @@ const rowMappers = {
     docstring: (r.docstring as string) ?? null,
   }),
   Class: (r: Record<string, unknown>) => ({
+    id: r.id as string,
     name: r.name as string,
     filePath: r.filePath as string,
     startLine: r.startLine as number,
@@ -246,6 +248,7 @@ const rowMappers = {
     docstring: (r.docstring as string) ?? null,
   }),
   Interface: (r: Record<string, unknown>) => ({
+    id: r.id as string,
     name: r.name as string,
     filePath: r.filePath as string,
     startLine: r.startLine as number,
@@ -255,6 +258,7 @@ const rowMappers = {
     docstring: (r.docstring as string) ?? null,
   }),
   Variable: (r: Record<string, unknown>) => ({
+    id: r.id as string,
     name: r.name as string,
     filePath: r.filePath as string,
     line: r.line as number,
@@ -263,6 +267,7 @@ const rowMappers = {
     isExported: r.isExported as boolean,
   }),
   Type: (r: Record<string, unknown>) => ({
+    id: r.id as string,
     name: r.name as string,
     filePath: r.filePath as string,
     startLine: r.startLine as number,
@@ -272,6 +277,7 @@ const rowMappers = {
     docstring: (r.docstring as string) ?? null,
   }),
   Component: (r: Record<string, unknown>) => ({
+    id: r.id as string,
     name: r.name as string,
     filePath: r.filePath as string,
     startLine: r.startLine as number,
@@ -285,12 +291,12 @@ const rowMappers = {
 /** Identifier extractors for each node type */
 const identifierExtractors: Record<EmbeddableNodeType, (e: Record<string, unknown>) => Record<string, unknown>> = {
   File: (e) => ({ filePath: e.path }),
-  Function: (e) => ({ name: e.name, filePath: e.filePath, startLine: e.startLine }),
-  Class: (e) => ({ name: e.name, filePath: e.filePath, startLine: e.startLine }),
-  Interface: (e) => ({ name: e.name, filePath: e.filePath, startLine: e.startLine }),
-  Variable: (e) => ({ name: e.name, filePath: e.filePath, line: e.line }),
-  Type: (e) => ({ name: e.name, filePath: e.filePath, startLine: e.startLine }),
-  Component: (e) => ({ name: e.name, filePath: e.filePath, startLine: e.startLine }),
+  Function: (e) => ({ id: e.id }),
+  Class: (e) => ({ id: e.id }),
+  Interface: (e) => ({ id: e.id }),
+  Variable: (e) => ({ id: e.id }),
+  Type: (e) => ({ id: e.id }),
+  Component: (e) => ({ id: e.id }),
 };
 
 /** Embedding text builders for each node type — row mappers produce matching shapes */
diff --git a/packages/core/src/embed-pass.ts b/packages/core/src/embed-pass.ts
index 9e164274..5634779b 100644
--- a/packages/core/src/embed-pass.ts
+++ b/packages/core/src/embed-pass.ts
@@ -89,7 +89,7 @@ function collectEmbeddableItems(parsed: ParsedFileEntities): EmbeddableItem[] {
       nodeType: 'Function',
       text,
       textHash: hashText(text),
-      identifier: { name: fn.name, filePath: fn.filePath, startLine: fn.startLine },
+      identifier: { id: fn.id },
     });
   }
 
@@ -100,7 +100,7 @@ function collectEmbeddableItems(parsed: ParsedFileEntities): EmbeddableItem[] {
       nodeType: 'Class',
       text,
       textHash: hashText(text),
-      identifier: { name: cls.name, filePath: cls.filePath, startLine: cls.startLine },
+      identifier: { id: cls.id },
     });
   }
 
@@ -111,7 +111,7 @@ function collectEmbeddableItems(parsed: ParsedFileEntities): EmbeddableItem[] {
       nodeType: 'Interface',
       text,
       textHash: hashText(text),
-      identifier: { name: iface.name, filePath: iface.filePath, startLine: iface.startLine },
+      identifier: { id: iface.id },
     });
   }
 
@@ -129,7 +129,7 @@ function collectEmbeddableItems(parsed: ParsedFileEntities): EmbeddableItem[] {
       nodeType: 'Type',
       text,
       textHash: hashText(text),
-      identifier: { name: t.name, filePath: t.filePath, startLine: t.startLine },
+      identifier: { id: t.id },
     });
   }
 
@@ -140,7 +140,7 @@ function collectEmbeddableItems(parsed: ParsedFileEntities): EmbeddableItem[] {
       nodeType: 'Component',
       text,
       textHash: hashText(text),
-      identifier: { name: comp.name, filePath: comp.filePath, startLine: comp.startLine },
+      identifier: { id: comp.id },
     });
   }
 
@@ -239,8 +239,11 @@ export async function embedParsedEntities(
  * Build a cache key for an embeddable item (matches the format used by getEmbeddingHashesForFiles).
  */
 function itemCacheKey(item: EmbeddableItem): string {
-  const startLine = item.identifier['startLine'];
-  return `${item.nodeType}:${item.identifier['name']}:${item.identifier['filePath']}:${startLine}`;
+  const id = item.identifier['id'];
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new Error(`Missing persisted id for ${item.nodeType} embedding`);
+  }
+  return id;
 }
 
 /**
diff --git a/packages/core/src/enrichedSearchV2.ts b/packages/core/src/enrichedSearchV2.ts
index 0763a5ed..b4441b12 100644
--- a/packages/core/src/enrichedSearchV2.ts
+++ b/packages/core/src/enrichedSearchV2.ts
@@ -46,6 +46,7 @@ export interface LinkedKnowledgeEntry {
 }
 
 export interface SiblingSymbol {
+  id: string;
   name: string;
   startLine: number;
   endLine: number;
@@ -54,6 +55,7 @@ export interface SiblingSymbol {
 }
 
 export interface EnrichedV2Hit {
+  id: string;
   name: string;
   nodeType: string;
   filePath?: string;
@@ -220,10 +222,10 @@ const ENRICHMENT_TIMEOUT_MS = 5_000;
  * and the rewrite dropped the batch from 240s to 0.4s.
  */
 export const DEPENDENCY_DEPTH_CYPHER = `
-  UNWIND $names AS symbolName
-  MATCH path = (entry:File)-[:CONTAINS|CALLS*1..6]->(n {name: symbolName})
+  UNWIND $ids AS symbolId
+  MATCH path = (entry:File)-[:CONTAINS|CALLS*1..6]->(n {id: symbolId})
   WHERE NOT ()-[:IMPORTS]->(entry)
-  RETURN symbolName, min(length(path)) AS minDepth
+  RETURN symbolId, min(length(path)) AS minDepth
 `;
 
 interface GraphEnrichment {
@@ -236,23 +238,9 @@ interface GraphEnrichment {
   commitCount: number;
 }
 
-/**
- * Composite key for the map `enrichFromGraph` returns, and for looking a hit
- * up in it. Symbol names collide constantly in real codebases (many classes
- * each declare a "constructor", many modules each export a "GraphClient"),
- * so a map keyed on name alone lets one declaration's numbers silently
- * overwrite another's. filePath narrows to one file, startLine narrows
- * further to one declaration for files that declare more than one symbol
- * under the same name (overloads). File nodes carry no startLine, and
- * `Candidate.startLine` is `undefined` for them; the query side normalizes
- * the same way, so both sides still agree on the key.
- */
-export function enrichmentKey(
-  filePath: string | undefined,
-  name: string,
-  startLine: number | undefined | null,
-): string {
-  return `${filePath ?? ''}\x00${name}\x00${startLine ?? ''}`;
+/** Use the persisted opaque identity for enrichment lookups. */
+export function enrichmentKey(id: string): string {
+  return id;
 }
 
 export async function enrichFromGraph(
@@ -261,13 +249,13 @@ export async function enrichFromGraph(
 ): Promise<Map<string, GraphEnrichment>> {
   if (hits.length === 0) return new Map();
 
-  const names = hits.map(h => h.name);
-  const items = hits.map(h => ({ name: h.name, filePath: h.filePath ?? '' }));
+  const ids = hits.map(hit => hit.id);
+  const items = hits.map(hit => ({ id: hit.id }));
 
   // Single batch query: for each hit, count callers, callees, importers,
   // test references (files with test/spec in path), and dependency depth.
   //
-  // `n` is bound by its own MATCH, on (name, filePath), before any OPTIONAL
+  // `n` is bound by its own persisted ID before any OPTIONAL
   // expansion runs. It used to be bound inside the first OPTIONAL MATCH,
   // alongside the caller edge: `OPTIONAL MATCH (n {name: symbolName})<-[:CALLS]-(caller)`.
   // When a symbol had no callers that whole pattern failed to match, so `n`
@@ -278,7 +266,7 @@ export async function enrichFromGraph(
   // A plain MATCH can't hang the way the one in DEPENDENCY_DEPTH_CYPHER
   // could: this is a single-hop exact-property lookup, not a bounded path
   // search over a densely connected hub, so there's no enumeration to blow
-  // up. The one behavior change is that a name with no matching node now
+  // up. The one behavior change is that an ID with no matching node now
   // produces no row at all, instead of a row of zeros. Every call site below
   // that reads this map already treats a missing entry as "no enrichment for
   // this hit" (see the `.get(...)` calls in enrichedSearchV2Impl), so that's
@@ -286,7 +274,7 @@ export async function enrichFromGraph(
   // unreachable symbol.
   const cypher = `
     UNWIND $items AS item
-    MATCH (n {name: item.name, filePath: item.filePath})
+    MATCH (n {id: item.id})
     OPTIONAL MATCH (n)<-[:CALLS]-(caller)
     WITH item, n, count(DISTINCT caller) AS callers
     OPTIONAL MATCH (n)-[:CALLS]->(callee)
@@ -297,9 +285,9 @@ export async function enrichFromGraph(
       WHERE (testFile.filePath CONTAINS '.test.' OR testFile.filePath CONTAINS '.spec.' OR testFile.filePath CONTAINS '__tests__')
         AND ((testFile)-[:CONTAINS]->()-[:CALLS]->(n)
           OR (testFile)-[:IMPORTS]->()-[:CONTAINS]->(n))
-    WITH item.name AS symbolName, n.filePath AS filePath, coalesce(n.startLine, n.line) AS startLine,
+    WITH item.id AS symbolId,
          callers, calleeNames, importers, count(DISTINCT testFile) AS testRefs
-    RETURN symbolName, filePath, startLine, callers, calleeNames, importers, testRefs
+    RETURN symbolId, callers, calleeNames, importers, testRefs
   `;
 
   try {
@@ -310,11 +298,7 @@ export async function enrichFromGraph(
 
     const map = new Map<string, GraphEnrichment>();
     for (const row of result.data) {
-      const key = enrichmentKey(
-        row['filePath'] as string | undefined,
-        row['symbolName'] as string,
-        row['startLine'] as number | null | undefined,
-      );
+      const key = enrichmentKey(row['symbolId'] as string);
       map.set(key, {
         callerCount: (row['callers'] as number) ?? 0,
         callees: (row['calleeNames'] as string[]) ?? [],
@@ -326,25 +310,22 @@ export async function enrichFromGraph(
       });
     }
 
-    // Dependency depth: see DEPENDENCY_DEPTH_CYPHER. That query answers by
-    // name alone (it has no filePath or startLine to key on), so a depth
-    // found for a name applies to every hit sharing that name in this batch,
-    // and gets folded into each hit's own composite-keyed entry below.
+    // Dependency depth is keyed by the same persisted ID as the hit.
     try {
       const depthResult = await client.roQuery<Record<string, unknown>>(DEPENDENCY_DEPTH_CYPHER, {
-        params: { names },
+        params: { ids },
         timeout: ENRICHMENT_TIMEOUT_MS,
       });
-      const depthByName = new Map<string, number>();
+      const depthById = new Map<string, number>();
       for (const row of depthResult.data) {
         if (row['minDepth'] != null) {
-          depthByName.set(row['symbolName'] as string, row['minDepth'] as number);
+          depthById.set(row['symbolId'] as string, row['minDepth'] as number);
         }
       }
       for (const hit of hits) {
-        const depth = depthByName.get(hit.name);
+        const depth = depthById.get(hit.id);
         if (depth == null) continue;
-        const enrichment = map.get(enrichmentKey(hit.filePath, hit.name, hit.startLine));
+        const enrichment = map.get(enrichmentKey(hit.id));
         if (enrichment) enrichment.dependencyDepth = depth;
       }
     } catch (err) {
@@ -377,7 +358,7 @@ export async function enrichFromGraph(
         for (const hit of hits) {
           if (hit.filePath) {
             const gitData = gitByFile.get(hit.filePath);
-            const enrichment = map.get(enrichmentKey(hit.filePath, hit.name, hit.startLine));
+            const enrichment = map.get(enrichmentKey(hit.id));
             if (gitData && enrichment) {
               enrichment.lastModified = gitData.lastModified;
               enrichment.commitCount = gitData.commitCount;
@@ -405,6 +386,7 @@ function distanceToScore(distance: number): number {
 }
 
 export interface Candidate {
+  id: string;
   name: string;
   nodeType: string;
   filePath?: string | undefined;
@@ -416,7 +398,7 @@ export interface Candidate {
 
 /** Key function for rrfFuse when combining retrieval sources */
 export function candidateKey(c: Candidate): string {
-  return `${c.nodeType}:${c.filePath}:${c.name}`;
+  return c.id;
 }
 
 /**
@@ -510,14 +492,17 @@ async function retrieveCandidates(
     for (const r of results) {
       if (!matchesScope(r.filePath, scope, scopePaths)) continue;
 
-      const key = `${r.nodeType}:${r.filePath}:${r.name}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
+      const persistedId = typeof r.properties?.['id'] === 'string'
+        ? r.properties['id']
+        : r.nodeType === 'File' ? `File:${r.filePath}` : undefined;
+      if (!persistedId || seen.has(persistedId)) continue;
+      seen.add(persistedId);
 
       const vScore = distanceToScore(r.distance);
       // r.properties contains the full row from searchByVector (all node fields)
       const props = r.properties ?? {};
       candidates.push({
+        id: persistedId,
         name: r.name,
         nodeType: r.nodeType,
         filePath: r.filePath,
@@ -542,43 +527,43 @@ async function retrieveCandidates(
  */
 async function getLinkedKnowledge(
   client: GraphClient,
-  names: string[],
+  ids: string[],
 ): Promise<Map<string, LinkedKnowledgeEntry[]>> {
   const result = new Map<string, LinkedKnowledgeEntry[]>();
-  if (names.length === 0) return result;
+  if (ids.length === 0) return result;
 
   try {
     // Reverse ABOUT: (Entity)-[ABOUT]->(CodeNode) — find entities pointing at these code nodes
     const rows = await client.roQuery<{
-      targetName: string;
+      targetId: string;
       entityText: string;
       entityType: string;
       confidence: number;
       fact: string | null;
     }>(
-      `UNWIND $names AS targetName
+      `UNWIND $ids AS targetId
        MATCH (e:Entity)-[r:ABOUT]->(t)
-       WHERE t.name = targetName
+       WHERE t.id = targetId
        OPTIONAL MATCH (e)-[rel:RELATES_TO]-()
        WHERE rel.invalid_at IS NULL
-       RETURN targetName, e.text AS entityText, e.type AS entityType,
+       RETURN targetId, e.text AS entityText, e.type AS entityType,
               r.confidence AS confidence, rel.fact AS fact
        LIMIT 100`,
-      { params: { names }, timeout: ENRICHMENT_TIMEOUT_MS },
+      { params: { ids }, timeout: ENRICHMENT_TIMEOUT_MS },
     );
 
     for (const row of rows.data) {
-      const existing = result.get(row.targetName) ?? [];
+      const existing = result.get(row.targetId) ?? [];
       existing.push({
         entityText: row.entityText,
         entityType: row.entityType,
         confidence: row.confidence,
         ...(row.fact != null ? { fact: row.fact } : {}),
       });
-      result.set(row.targetName, existing);
+      result.set(row.targetId, existing);
     }
-  } catch {
-    // ABOUT edges may not exist — non-fatal
+  } catch (error) {
+    logger.debug(`Linked knowledge query failed (non-fatal): ${error}`);
   }
 
   return result;
@@ -596,20 +581,19 @@ const SIBLING_AGGREGATE_CAP = 10_000; // bytes aggregate siblings JSON per hit
  * within the same file, using CONTAINS edges from the File node.
  *
  * Returns an array of 0–2 siblings. Empty when the file has only one symbol
- * or the target isn't found by name+startLine.
+ * or the target ID is not found.
  *
  * NOTE: File nodes use `filePath` as the property key (not `path`).
  */
 export async function fetchSiblingSymbols(
   client: GraphClient,
   filePath: string,
-  symbolName: string,
-  symbolStartLine: number,
+  symbolId: string,
 ): Promise<SiblingSymbol[]> {
   const cypher = `
     MATCH (f:File)-[:CONTAINS]->(s)
     WHERE f.filePath = $filePath AND s.startLine IS NOT NULL
-    RETURN s.name AS name, s.startLine AS startLine, s.endLine AS endLine,
+    RETURN s.id AS id, s.name AS name, s.startLine AS startLine, s.endLine AS endLine,
            s.signature AS signature, labels(s)[0] AS nodeType
     ORDER BY s.startLine
   `;
@@ -626,7 +610,7 @@ export async function fetchSiblingSymbols(
   }
 
   const idx = data.findIndex(
-    s => s['name'] === symbolName && s['startLine'] === symbolStartLine,
+    symbol => symbol['id'] === symbolId,
   );
   if (idx === -1) return [];
 
@@ -641,6 +625,7 @@ export async function fetchSiblingSymbols(
       sig = sig.slice(0, SIBLING_SIGNATURE_CAP);
     }
     out.push({
+      id: row['id'] as string,
       name: row['name'] as string,
       startLine: row['startLine'] as number,
       endLine: row['endLine'] as number,
@@ -654,25 +639,24 @@ export async function fetchSiblingSymbols(
 
 /**
  * Batch-fetch siblings for multiple hits, grouping by unique filePath to
- * minimize graph round-trips. Returns a map of `filePath:name:startLine` → siblings.
+ * minimize graph round-trips. Returns a map of persisted symbol ID to siblings.
  */
 async function fetchSiblingsForHits(
   client: GraphClient,
-  hits: Array<{ name: string; filePath?: string | undefined; startLine?: number | undefined }>,
+  hits: Array<{ id: string; filePath?: string | undefined }>,
 ): Promise<Map<string, SiblingSymbol[]>> {
   const result = new Map<string, SiblingSymbol[]>();
   if (hits.length === 0) return result;
 
   // Group hits by unique filePath
-  const byFile = new Map<string, Array<{ name: string; startLine: number; key: string }>>();
+  const byFile = new Map<string, Array<{ id: string }>>();
   for (const hit of hits) {
-    if (!hit.filePath || hit.startLine == null) continue;
-    const key = `${hit.filePath}:${hit.name}:${hit.startLine}`;
+    if (!hit.filePath) continue;
     const existing = byFile.get(hit.filePath);
     if (existing) {
-      existing.push({ name: hit.name, startLine: hit.startLine, key });
+      existing.push({ id: hit.id });
     } else {
-      byFile.set(hit.filePath, [{ name: hit.name, startLine: hit.startLine, key }]);
+      byFile.set(hit.filePath, [{ id: hit.id }]);
     }
   }
 
@@ -684,7 +668,7 @@ async function fetchSiblingsForHits(
       const cypher = `
         MATCH (f:File)-[:CONTAINS]->(s)
         WHERE f.filePath = $filePath AND s.startLine IS NOT NULL
-        RETURN s.name AS name, s.startLine AS startLine, s.endLine AS endLine,
+        RETURN s.id AS id, s.name AS name, s.startLine AS startLine, s.endLine AS endLine,
                s.signature AS signature, labels(s)[0] AS nodeType
         ORDER BY s.startLine
       `;
@@ -700,10 +684,10 @@ async function fetchSiblingsForHits(
         return;
       }
 
-      for (const { name, startLine, key } of hitsInFile) {
-        const idx = rows.findIndex(r => r['name'] === name && r['startLine'] === startLine);
+      for (const { id } of hitsInFile) {
+        const idx = rows.findIndex(row => row['id'] === id);
         if (idx === -1) {
-          result.set(key, []);
+          result.set(id, []);
           continue;
         }
 
@@ -713,6 +697,7 @@ async function fetchSiblingsForHits(
           let sig = row['signature'] as string | undefined;
           if (sig && sig.length > SIBLING_SIGNATURE_CAP) sig = sig.slice(0, SIBLING_SIGNATURE_CAP);
           siblings.push({
+            id: row['id'] as string,
             name: row['name'] as string,
             startLine: row['startLine'] as number,
             endLine: row['endLine'] as number,
@@ -724,9 +709,9 @@ async function fetchSiblingsForHits(
         // Cap aggregate size
         if (JSON.stringify(siblings).length > SIBLING_AGGREGATE_CAP) {
           // Keep only the first sibling if both together exceed the cap
-          result.set(key, siblings.slice(0, 1));
+          result.set(id, siblings.slice(0, 1));
         } else {
-          result.set(key, siblings);
+          result.set(id, siblings);
         }
       }
     }),
@@ -857,7 +842,7 @@ async function enrichedSearchV2Impl(
       if (c.properties.signature) parts.push(`Signature: ${String(c.properties.signature).slice(0, 200)}`);
       if (c.properties.docstring) parts.push(String(c.properties.docstring).slice(0, 300));
       // Graph signals help the reranker distinguish core code from leaf/UI code
-      const ge = prerankEnrichments.get(enrichmentKey(c.filePath, c.name, c.startLine));
+      const ge = prerankEnrichments.get(enrichmentKey(c.id));
       if (ge) {
         const signals: string[] = [];
         if (ge.callerCount > 0) signals.push(`called by ${ge.callerCount} functions`);
@@ -905,14 +890,14 @@ async function enrichedSearchV2Impl(
 
   // Reuse pre-rank enrichments; fetch any missing (e.g., if reranker was skipped)
   let enrichments = prerankEnrichments;
-  const missingHits = topHits.filter(h => !enrichments.has(enrichmentKey(h.filePath, h.name, h.startLine)));
+  const missingHits = topHits.filter(hit => !enrichments.has(enrichmentKey(hit.id)));
   if (missingHits.length > 0) {
     const extra = await enrichFromGraph(client, missingHits);
     for (const [k, v] of extra) enrichments.set(k, v);
   }
 
   // Enrich with linked knowledge (ABOUT edges: knowledge → code)
-  const knowledgeLinks = await getLinkedKnowledge(client, topHits.map(h => h.name));
+  const knowledgeLinks = await getLinkedKnowledge(client, topHits.map(hit => hit.id));
 
   // Drawer-grep: fetch ±1 sibling symbols per hit, batched by unique filePath
   const siblingMap = await fetchSiblingsForHits(client, topHits);
@@ -929,9 +914,10 @@ async function enrichedSearchV2Impl(
 
   const result: EnrichedV2Result = {
     hits: topHits.map(c => {
-      const graphData = enrichments.get(enrichmentKey(c.filePath, c.name, c.startLine));
+      const graphData = enrichments.get(enrichmentKey(c.id));
       const props = c.properties;
       return {
+        id: c.id,
         name: c.name,
         nodeType: c.nodeType,
         ...(c.filePath && { filePath: c.filePath }),
@@ -958,11 +944,10 @@ async function enrichedSearchV2Impl(
           ...(graphData.commitCount > 0 && { commitCount: graphData.commitCount }),
         }),
         // Knowledge graph enrichment (ABOUT edges)
-        ...(knowledgeLinks.has(c.name) ? { linkedKnowledge: knowledgeLinks.get(c.name)! } : {}),
+        ...(knowledgeLinks.has(c.id) ? { linkedKnowledge: knowledgeLinks.get(c.id)! } : {}),
         // Drawer-grep: ±1 sibling symbols in the same file
         ...((): { siblings?: SiblingSymbol[] } => {
-          const key = `${c.filePath}:${c.name}:${c.startLine}`;
-          const sibs = siblingMap.get(key);
+          const sibs = siblingMap.get(c.id);
           return sibs && sibs.length > 0 ? { siblings: sibs } : {};
         })(),
       };
diff --git a/packages/core/src/indexer.ts b/packages/core/src/indexer.ts
index fc6e7a79..34cdd123 100644
--- a/packages/core/src/indexer.ts
+++ b/packages/core/src/indexer.ts
@@ -28,6 +28,12 @@ import {
   getSupportedExtensions,
   DEFAULT_IGNORE_PATTERNS,
 } from './pipeline';
+import {
+  buildProjectSymbolCatalog,
+  currentSymbolIds,
+  resolveProjectSymbolEdges,
+  type PersistedCatalogSymbol,
+} from './pipeline/pipeline';
 import { extractReExports, extractLocalExportedNames, type ReExportEntity } from '@codegraph/plugin-typescript';
 import { parseMarkdownContent } from '@codegraph/plugin-markdown';
 import { createOperations, type GraphClient } from '@codegraph/graph';
@@ -50,6 +56,81 @@ import { glob } from 'glob';
 const execFileAsync = promisify(execFile);
 const logger = createLogger({ namespace: 'Core:Indexer' });
 
+const SOURCE_SYMBOL_LABELS = new Set<PersistedCatalogSymbol['label']>([
+  'Function',
+  'Class',
+  'Interface',
+  'Variable',
+  'Type',
+  'Component',
+]);
+
+async function loadPersistedCatalogSymbols(
+  client: GraphClient,
+  projectId: string,
+): Promise<PersistedCatalogSymbol[]> {
+  const labelExpression = client.dialect.labelsExpr('symbol');
+  try {
+    const result = await client.roQuery<Record<string, unknown>>(
+      `MATCH (:Project {id: $projectId})-[:HAS_FILE]->(:File)-[:CONTAINS]->(symbol)
+       WHERE symbol.id IS NOT NULL
+       RETURN symbol.id AS id, ${labelExpression} AS labels,
+              symbol.filePath AS filePath, symbol.name AS name,
+              symbol.scopeKey AS scopeKey, symbol.disambiguator AS disambiguator,
+              symbol.isExported AS isExported,
+              coalesce(symbol.startLine, symbol.line, 0) AS startLine`,
+      { params: { projectId } },
+    );
+    const symbols: PersistedCatalogSymbol[] = [];
+    for (const row of result.data ?? []) {
+      const rawLabels = row['labels'];
+      const labels = Array.isArray(rawLabels)
+        ? rawLabels.filter((label): label is string => typeof label === 'string')
+        : typeof rawLabels === 'string' ? [rawLabels] : [];
+      const label = labels.find((candidate): candidate is PersistedCatalogSymbol['label'] =>
+        SOURCE_SYMBOL_LABELS.has(candidate as PersistedCatalogSymbol['label']),
+      );
+      const id = row['id'];
+      const filePath = row['filePath'];
+      const name = row['name'];
+      if (!label || typeof id !== 'string' || typeof filePath !== 'string' || typeof name !== 'string') {
+        continue;
+      }
+      symbols.push({
+        id,
+        label,
+        filePath,
+        name,
+        scopeKey: typeof row['scopeKey'] === 'string' ? row['scopeKey'] : '',
+        disambiguator: typeof row['disambiguator'] === 'string' ? row['disambiguator'] : '',
+        isExported: row['isExported'] === true,
+        startLine: typeof row['startLine'] === 'number' ? row['startLine'] : 0,
+      });
+    }
+    return symbols;
+  } catch (error) {
+    logger.warn(`Could not preload persisted symbol catalog: ${error instanceof Error ? error.message : String(error)}`);
+    return [];
+  }
+}
+
+interface SymbolSweepOperations {
+  sweepStaleFileSymbols(filePath: string, currentIds: readonly string[]): Promise<void>;
+}
+
+function supportsSymbolSweep(ops: object): ops is SymbolSweepOperations {
+  return 'sweepStaleFileSymbols' in ops && typeof ops.sweepStaleFileSymbols === 'function';
+}
+
+async function sweepStaleSymbols(
+  ops: object,
+  parsed: ReturnType<typeof buildParsedFileEntities>,
+): Promise<void> {
+  if (supportsSymbolSweep(ops)) {
+    await ops.sweepStaleFileSymbols(parsed.file.path, currentSymbolIds(parsed));
+  }
+}
+
 /** Skip files larger than 512 KB — they stall the parser and are usually generated/bundled */
 const MAX_FILE_SIZE_BYTES = 512 * 1024;
 
@@ -443,16 +524,6 @@ export async function indexProject(
 
     logger.info(`Indexing ${rootPath}: found ${files.length} source files`);
 
-    if (files.length === 0) {
-      return {
-        success: true,
-        projectId: '',
-        projectName: basename(rootPath),
-        stats: { files: 0, entities: 0, edges: 0, errors: 0, durationMs: Date.now() - startTime },
-        errorMessages: [],
-      };
-    }
-
     // Get graph operations
     const graphClient = options.client ?? await getGraphClient();
     // Ensure schema/indexes exist before any writes (also pre-creates labels
@@ -478,7 +549,6 @@ export async function indexProject(
     // created. The final upsertProject() call further down still runs, to
     // persist fileCount/lastParsed once those are known.
     await ops.upsertProject(project);
-
     // ----------------------------------------------------------------
     // Incremental: build hash map of previously indexed files
     // ----------------------------------------------------------------
@@ -493,6 +563,17 @@ export async function indexProject(
       }
     }
 
+    const discoveredPaths = new Set(files);
+    const vanishedPaths = [...storedHashes.keys()].filter(path => !discoveredPaths.has(path));
+    if (vanishedPaths.length > 0) {
+      await Promise.all(vanishedPaths.map(path => ops.removeFileAndCleanup(path)));
+      logger.info(`Incremental: removed ${vanishedPaths.length} vanished file${vanishedPaths.length === 1 ? '' : 's'}`);
+    }
+
+    const persistedCatalogSymbols = !force && existingProject
+      ? await loadPersistedCatalogSymbols(graphClient, project.id)
+      : [];
+
     // ----------------------------------------------------------------
     // Compute content hashes for all files, determine which need processing
     // Read file content once — reuse for both hashing and parsing
@@ -636,6 +717,7 @@ export async function indexProject(
           // (MERGE), instead of a fresh node replacing a deleted one.
           await Promise.all(chunk.map(r => ops.removeFileContents(r.file)));
           await ops.batchUpsertBulk(chunk.map(r => r.built));
+          await Promise.all(chunk.map(r => sweepStaleSymbols(ops, r.built)));
         }
         await ops.linkProjectFiles(project.id, chunk.map(r => r.file));
 
@@ -650,6 +732,7 @@ export async function indexProject(
         for (const { file, built, extracted } of chunk) {
           try {
             await ops.batchUpsert(built);
+            if (!useCreatePath) await sweepStaleSymbols(ops, built);
             await ops.linkProjectFile(project.id, file);
             totalFiles++;
             totalEntities += 1 + countEntities(extracted);
@@ -664,9 +747,6 @@ export async function indexProject(
       }
     };
 
-    // Pipeline: parse batch N while upserting batch N-1
-    let pendingUpsert: Promise<void> | null = null;
-    let pendingBatch: ParsedResult[] = [];
     const UPSERT_CHUNK_SIZE = 50;
 
     for (let i = 0; i < codeFiles.length; i += concurrency) {
@@ -708,15 +788,6 @@ export async function indexProject(
           continue;
         }
         allParsed.push(result.value);
-        pendingBatch.push(result.value);
-      }
-
-      // When pending batch reaches upsert chunk size, fire upsert (with backpressure)
-      if (pendingBatch.length >= UPSERT_CHUNK_SIZE) {
-        if (pendingUpsert) await pendingUpsert; // Backpressure: wait for previous upsert
-        const chunk = pendingBatch;
-        pendingBatch = [];
-        pendingUpsert = upsertChunk(chunk);
       }
 
       // Progress logging
@@ -727,11 +798,14 @@ export async function indexProject(
       }
     }
 
-    // Flush remaining parsed results
-    if (pendingUpsert) await pendingUpsert;
-    if (pendingBatch.length > 0) {
-      await upsertChunk(pendingBatch);
-      pendingBatch = [];
+    const symbolCatalog = buildProjectSymbolCatalog(
+      allParsed.map(result => result.built),
+      persistedCatalogSymbols,
+    );
+    resolveProjectSymbolEdges(allParsed.map(result => result.built), symbolCatalog);
+
+    for (let i = 0; i < allParsed.length; i += UPSERT_CHUNK_SIZE) {
+      await upsertChunk(allParsed.slice(i, i + UPSERT_CHUNK_SIZE));
     }
 
     // Parse markdown files (typically few, no pipeline needed)
@@ -949,6 +1023,13 @@ export async function indexSingleFile(
     // Skip non-exported variables
     parsed.variables = parsed.variables.filter(v => v.isExported);
 
+    const existingProject = projectRoot ? await ops.getProjectByRoot(projectRoot) : null;
+    const persistedCatalogSymbols = existingProject
+      ? await loadPersistedCatalogSymbols(graphClient, existingProject.id)
+      : [];
+    const symbolCatalog = buildProjectSymbolCatalog([parsed], persistedCatalogSymbols);
+    resolveProjectSymbolEdges([parsed], symbolCatalog);
+
     // Clean up old entities before re-upserting (prevents stale nodes when
     // code moves/deletes). This path re-indexes a file whose content
     // changed (see onFileChanged in the watcher integrations) -- it was not
@@ -958,6 +1039,7 @@ export async function indexSingleFile(
     // go through removeFileAndCleanup() directly, from onFileRemoved.
     await ops.removeFileContents(filePath);
     await ops.batchUpsert(parsed);
+    await sweepStaleSymbols(ops, parsed);
 
     // Embedding pass — deferred (background) or blocking
     let embedded = 0;
diff --git a/packages/core/src/pipeline/pipeline.ts b/packages/core/src/pipeline/pipeline.ts
index b14bd139..f475689c 100644
--- a/packages/core/src/pipeline/pipeline.ts
+++ b/packages/core/src/pipeline/pipeline.ts
@@ -265,6 +265,212 @@ export interface PipelineOptions {
   localExportsIndex?: ReadonlyMap<string, readonly string[]>;
 }
 
+type SourceSymbolLabel = 'Function' | 'Class' | 'Interface' | 'Variable' | 'Type' | 'Component';
+
+interface CatalogSymbol {
+  id: string;
+  label: SourceSymbolLabel;
+  filePath: string;
+  name: string;
+  scopeKey: string;
+  disambiguator: string;
+  isOverloadSignature?: boolean;
+  isExported: boolean;
+  startLine: number;
+}
+
+export interface PersistedCatalogSymbol extends CatalogSymbol {}
+
+export interface ProjectSymbolCatalog {
+  readonly byId: ReadonlyMap<string, CatalogSymbol>;
+  readonly byDeclaration: ReadonlyMap<string, readonly CatalogSymbol[]>;
+  readonly byExport: ReadonlyMap<string, readonly CatalogSymbol[]>;
+}
+
+interface SymbolLookup {
+  labels: readonly SourceSymbolLabel[];
+  filePath: string;
+  name: string;
+  startLine?: number;
+  ownerName?: string;
+  exportedOnly?: boolean;
+}
+
+interface EdgeResolutionHint {
+  from?: SymbolLookup;
+  to?: SymbolLookup;
+}
+
+const edgeResolutionHints = new WeakMap<object, EdgeResolutionHint>();
+
+const SYMBOL_COLLECTIONS = [
+  ['Function', 'functions'],
+  ['Class', 'classes'],
+  ['Interface', 'interfaces'],
+  ['Variable', 'variables'],
+  ['Type', 'types'],
+  ['Component', 'components'],
+] as const;
+
+function declarationKey(label: SourceSymbolLabel, filePath: string, name: string): string {
+  return `${label}\u0000${filePath}\u0000${name}`;
+}
+
+function exportKey(filePath: string, name: string): string {
+  return `${filePath}\u0000${name}`;
+}
+
+function symbolStartLine(symbol: { startLine?: number; line?: number }): number {
+  return symbol.startLine ?? symbol.line ?? 0;
+}
+
+function symbolsFromParsed(parsed: ParsedFileEntities): CatalogSymbol[] {
+  const symbols: CatalogSymbol[] = [];
+  for (const [label, collection] of SYMBOL_COLLECTIONS) {
+    for (const symbol of parsed[collection]) {
+      symbols.push({
+        id: symbol.id,
+        label,
+        filePath: symbol.filePath,
+        name: symbol.name,
+        scopeKey: symbol.scopeKey,
+        disambiguator: symbol.disambiguator,
+        isOverloadSignature: label === 'Function'
+          && 'isOverloadSignature' in symbol
+          && symbol.isOverloadSignature === true,
+        isExported: symbol.isExported,
+        startLine: symbolStartLine(symbol),
+      });
+    }
+  }
+  return symbols;
+}
+
+export function currentSymbolIds(parsed: ParsedFileEntities): string[] {
+  return symbolsFromParsed(parsed).map(symbol => symbol.id);
+}
+
+export function buildProjectSymbolCatalog(
+  parsedList: readonly ParsedFileEntities[],
+  persistedSymbols: readonly PersistedCatalogSymbol[] = [],
+): ProjectSymbolCatalog {
+  const changedFiles = new Set(parsedList.map(parsed => parsed.file.path));
+  const symbols = [
+    ...persistedSymbols.filter(symbol => !changedFiles.has(symbol.filePath)),
+    ...parsedList.flatMap(symbolsFromParsed),
+  ];
+  const byId = new Map<string, CatalogSymbol>();
+  const byDeclaration = new Map<string, CatalogSymbol[]>();
+  const byExport = new Map<string, CatalogSymbol[]>();
+
+  for (const symbol of symbols) {
+    byId.set(symbol.id, symbol);
+    if (symbol.isOverloadSignature === true) continue;
+    const declared = declarationKey(symbol.label, symbol.filePath, symbol.name);
+    const declarationMatches = byDeclaration.get(declared) ?? [];
+    declarationMatches.push(symbol);
+    byDeclaration.set(declared, declarationMatches);
+    if (symbol.isExported && symbol.scopeKey.length === 0) {
+      const exported = exportKey(symbol.filePath, symbol.name);
+      const exportMatches = byExport.get(exported) ?? [];
+      exportMatches.push(symbol);
+      byExport.set(exported, exportMatches);
+    }
+  }
+
+  return { byId, byDeclaration, byExport };
+}
+
+function resolveLookup(catalog: ProjectSymbolCatalog, lookup: SymbolLookup): CatalogSymbol[] {
+  let matches = lookup.exportedOnly
+    ? [...(catalog.byExport.get(exportKey(lookup.filePath, lookup.name)) ?? [])]
+    : lookup.labels.flatMap(label => catalog.byDeclaration.get(
+      declarationKey(label, lookup.filePath, lookup.name),
+    ) ?? []);
+  matches = matches.filter(symbol => lookup.labels.includes(symbol.label));
+  if (lookup.ownerName) {
+    const owner = `Class:${lookup.ownerName}`;
+    matches = matches.filter(symbol =>
+      symbol.scopeKey === owner || symbol.scopeKey.endsWith(`/${owner}`),
+    );
+  }
+  if (lookup.startLine !== undefined) {
+    const atLine = matches.filter(symbol => symbol.startLine === lookup.startLine);
+    if (atLine.length > 0) matches = atLine;
+  }
+  return matches;
+}
+
+function resolveSingleEndpoint(
+  currentId: string,
+  lookup: SymbolLookup | undefined,
+  catalog: ProjectSymbolCatalog,
+): string | undefined {
+  if (currentId && catalog.byId.has(currentId)) return currentId;
+  if (!lookup) return undefined;
+  const matches = resolveLookup(catalog, lookup);
+  return matches.length === 1 ? matches[0]?.id : undefined;
+}
+
+export function resolveProjectSymbolEdges(
+  parsedList: readonly ParsedFileEntities[],
+  catalog: ProjectSymbolCatalog,
+): void {
+  for (const parsed of parsedList) {
+    parsed.callEdges = parsed.callEdges.flatMap(edge => {
+      const hint = edgeResolutionHints.get(edge);
+      const callerId = resolveSingleEndpoint(edge.callerId, hint?.from, catalog);
+      const calleeMatches = edge.calleeId && catalog.byId.has(edge.calleeId)
+        ? [catalog.byId.get(edge.calleeId)!]
+        : hint?.to ? resolveLookup(catalog, hint.to) : [];
+      const implementationMatches = calleeMatches.filter(
+        target => target.isOverloadSignature !== true,
+      );
+      if (!callerId || implementationMatches.length === 0) return [];
+      return implementationMatches.map(target => ({ ...edge, callerId, calleeId: target.id }));
+    });
+
+    parsed.importsSymbolEdges = parsed.importsSymbolEdges.flatMap(edge => {
+      const hint = edgeResolutionHints.get(edge);
+      const targets = edge.toId && catalog.byId.has(edge.toId)
+        ? [catalog.byId.get(edge.toId)!]
+        : hint?.to ? resolveLookup(catalog, hint.to) : [];
+      return targets.map(target => ({
+        ...edge,
+        fromId: edge.fromId ?? `File:${edge.fromFilePath}`,
+        toId: target.id,
+      }));
+    });
+
+    parsed.extendsEdges = parsed.extendsEdges.flatMap(edge => {
+      const hint = edgeResolutionHints.get(edge);
+      const childId = resolveSingleEndpoint(edge.childId, hint?.from, catalog);
+      const parentId = resolveSingleEndpoint(edge.parentId, hint?.to, catalog);
+      return childId && parentId ? [{ childId, parentId }] : [];
+    });
+
+    parsed.implementsEdges = parsed.implementsEdges.flatMap(edge => {
+      const hint = edgeResolutionHints.get(edge);
+      const classId = resolveSingleEndpoint(edge.classId, hint?.from, catalog);
+      const interfaceId = resolveSingleEndpoint(edge.interfaceId, hint?.to, catalog);
+      return classId && interfaceId ? [{ classId, interfaceId }] : [];
+    });
+
+    parsed.rendersEdges = parsed.rendersEdges.flatMap(edge => {
+      const hint = edgeResolutionHints.get(edge);
+      const parentId = resolveSingleEndpoint(edge.parentId, hint?.from, catalog);
+      const childId = resolveSingleEndpoint(edge.childId, hint?.to, catalog);
+      return parentId && childId ? [{ ...edge, parentId, childId }] : [];
+    });
+
+    parsed.exportsEdges = parsed.exportsEdges.flatMap(edge => {
+      const hint = edgeResolutionHints.get(edge);
+      const toId = resolveSingleEndpoint(edge.toId ?? '', hint?.to, catalog);
+      return toId ? [{ ...edge, fromId: edge.fromId ?? `File:${edge.filePath}`, toId }] : [];
+    });
+  }
+}
+
 // ============================================================================
 // Barrel re-export chain resolution (batch/full-index only)
 // ============================================================================
@@ -529,21 +735,27 @@ function buildInheritanceEdgesFromRefs(
 
     if (ref.type === 'extends') {
       if (cls) {
-        extendsEdges.push({
-          childId: `Class:${filePath}:${cls.name}:${cls.startLine}`,
-          parentId: `Class:external:${ref.parentName}`,
+        const edge = { childId: ref.fromId ?? cls.id, parentId: ref.toId ?? '' };
+        edgeResolutionHints.set(edge, {
+          from: { labels: ['Class'], filePath, name: cls.name, startLine: cls.startLine },
+          to: { labels: ['Class'], filePath, name: ref.parentName },
         });
+        extendsEdges.push(edge);
       } else if (iface) {
-        extendsEdges.push({
-          childId: `Interface:${filePath}:${iface.name}:${iface.startLine}`,
-          parentId: `Interface:external:${ref.parentName}`,
+        const edge = { childId: ref.fromId ?? iface.id, parentId: ref.toId ?? '' };
+        edgeResolutionHints.set(edge, {
+          from: { labels: ['Interface'], filePath, name: iface.name, startLine: iface.startLine },
+          to: { labels: ['Interface'], filePath, name: ref.parentName },
         });
+        extendsEdges.push(edge);
       }
     } else if (ref.type === 'implements' && cls) {
-      implementsEdges.push({
-        classId: `Class:${filePath}:${cls.name}:${cls.startLine}`,
-        interfaceId: `Interface:external:${ref.parentName}`,
+      const edge = { classId: ref.fromId ?? cls.id, interfaceId: ref.toId ?? '' };
+      edgeResolutionHints.set(edge, {
+        from: { labels: ['Class'], filePath, name: cls.name, startLine: cls.startLine },
+        to: { labels: ['Interface'], filePath, name: ref.parentName },
       });
+      implementsEdges.push(edge);
     }
   }
 
@@ -563,13 +775,23 @@ function collectExportsEdges(file: FileEntity, extracted: ExtractedEntities): Pa
     ...(extracted.hasPropertyEdges ?? []).map((edge) => edge.toId),
   ]);
   const push = (
-    id: string | undefined,
+    id: string,
     name: string,
     isExported: boolean,
     symbolKind: ParsedFileEntities['exportsEdges'][number]['symbolKind'],
   ): void => {
-    if (isExported && (!id || !memberIds.has(id))) {
-      edges.push({ filePath: file.path, symbolName: name, symbolKind });
+    if (isExported && !memberIds.has(id)) {
+      const edge = {
+        fromId: `File:${file.path}`,
+        toId: id,
+        filePath: file.path,
+        symbolName: name,
+        symbolKind,
+      };
+      edgeResolutionHints.set(edge, {
+        to: { labels: [symbolKind], filePath: file.path, name, exportedOnly: true },
+      });
+      edges.push(edge);
     }
   };
   for (const fn of extracted.functions) push(fn.id, fn.name, fn.isExported, 'Function');
@@ -607,12 +829,21 @@ function collectImportsSymbolEdges(
       const localName = spec.alias ?? spec.name;
       const resolved = resolvedImportMap?.get(localName);
       const edge: ParsedFileEntities['importsSymbolEdges'][number] = {
+        fromId: `File:${file.path}`,
         fromFilePath: file.path,
         toFilePath: resolved?.filePath ?? resolvedPath,
         symbolName: resolved?.exportedName ?? spec.name,
         isDefault: false,
       };
       if (spec.alias) edge.alias = spec.alias;
+      edgeResolutionHints.set(edge, {
+        to: {
+          labels: ['Function', 'Class', 'Interface', 'Variable', 'Type', 'Component'],
+          filePath: edge.toFilePath,
+          name: edge.symbolName,
+          exportedOnly: true,
+        },
+      });
       edges.push(edge);
     }
   }
@@ -622,22 +853,34 @@ function collectImportsSymbolEdges(
 /**
  * Build call edges from CallReference[] (non-TS languages).
  */
-function buildCallEdgesFromRefs(refs: CallReference[]): ParsedFileEntities['callEdges'] {
+function buildCallEdgesFromRefs(
+  refs: CallReference[],
+  extracted: ExtractedEntities,
+): ParsedFileEntities['callEdges'] {
   // Non-TS plugins haven't been migrated to attribution-aware extraction yet.
   // They produce CallReferences with `callerName` only (no kind), defaulting
   // to Function caller and via='direct': the same defaults the old
   // TypeScript path used, so behavior is unchanged for those plugins.
-  return refs.map((call) => ({
-    callerId: `Function:${call.filePath}:${call.callerName}`,
-    // When the extractor resolved the callee to another file (via import
-    // analysis, see CallExtractionContext), key the edge on that file
-    // instead of unconditionally assuming the callee lives in the same file
-    // as the caller. Absent calleeFilePath still means same-file.
-    calleeId: `Function:${call.calleeFilePath ?? call.filePath}:${call.calleeName}`,
-    line: call.line,
-    callerKind: 'Function' as const,
-    via: 'direct' as const,
-  }));
+  return refs.map((call) => {
+    const caller = extracted.functions.find(fn => fn.name === call.callerName);
+    const edge = {
+      callerId: call.fromId ?? caller?.id ?? '',
+      calleeId: call.toId ?? '',
+      line: call.line,
+      callerKind: 'Function' as const,
+      via: 'direct' as const,
+    };
+    edgeResolutionHints.set(edge, {
+      from: { labels: ['Function'], filePath: call.filePath, name: call.callerName },
+      to: {
+        labels: ['Function'],
+        filePath: call.calleeFilePath ?? call.filePath,
+        name: call.calleeName,
+        exportedOnly: call.calleeFilePath !== undefined && call.calleeFilePath !== call.filePath,
+      },
+    });
+    return edge;
+  });
 }
 
 /**
@@ -736,19 +979,43 @@ export function buildParsedFileEntities(
       includeExternals,
     );
 
-    extendsEdges = inheritance.extends.map((ext) => ({
-      childId: `Class:${ext.childFilePath}:${ext.childName}:${ext.childStartLine}`,
-      parentId: ext.parentFilePath
-        ? `Class:${ext.parentFilePath}:${ext.parentName}`
-        : `Class:external:${ext.parentName}`,
-    }));
-
-    implementsEdges = inheritance.implements.map((impl) => ({
-      classId: `Class:${impl.classFilePath}:${impl.className}:${impl.classStartLine}`,
-      interfaceId: impl.interfaceFilePath
-        ? `Interface:${impl.interfaceFilePath}:${impl.interfaceName}`
-        : `Interface:external:${impl.interfaceName}`,
-    }));
+    extendsEdges = inheritance.extends.map((ext) => {
+      const child = extracted.classes.find(cls =>
+        cls.name === ext.childName && cls.startLine === ext.childStartLine,
+      );
+      const edge = { childId: ext.fromId ?? child?.id ?? '', parentId: ext.toId ?? '' };
+      if (ext.parentFilePath) {
+        edgeResolutionHints.set(edge, {
+          from: {
+            labels: ['Class'],
+            filePath: ext.childFilePath,
+            name: ext.childName,
+            startLine: ext.childStartLine,
+          },
+          to: { labels: ['Class'], filePath: ext.parentFilePath, name: ext.parentName },
+        });
+      }
+      return edge;
+    });
+
+    implementsEdges = inheritance.implements.map((impl) => {
+      const child = extracted.classes.find(cls =>
+        cls.name === impl.className && cls.startLine === impl.classStartLine,
+      );
+      const edge = { classId: impl.fromId ?? child?.id ?? '', interfaceId: impl.toId ?? '' };
+      if (impl.interfaceFilePath) {
+        edgeResolutionHints.set(edge, {
+          from: {
+            labels: ['Class'],
+            filePath: impl.classFilePath,
+            name: impl.className,
+            startLine: impl.classStartLine,
+          },
+          to: { labels: ['Interface'], filePath: impl.interfaceFilePath, name: impl.interfaceName },
+        });
+      }
+      return edge;
+    });
   } else if (plugin?.extractors.extractInheritance && rootNode) {
     // All other languages: use registry-dispatched extractInheritance
     const refs = plugin.extractors.extractInheritance(rootNode as unknown as GenericSyntaxNode, file.path);
@@ -793,18 +1060,41 @@ export function buildParsedFileEntities(
         resolvedImportMap,
       );
       callEdges = calls.map((call) => {
+        const callerCollection = call.callerKind === 'Function'
+          ? extracted.functions
+          : call.callerKind === 'Variable'
+            ? extracted.variables
+            : call.callerKind === 'Class'
+              ? extracted.classes
+              : extracted.interfaces;
+        const caller = callerCollection.find(candidate =>
+          candidate.name === call.callerName && symbolStartLine(candidate) === call.callerStartLine,
+        );
         const edge: ParsedFileEntities['callEdges'][number] = {
-          // Caller id encodes its kind so cross-label disambiguation works
-          // downstream, see graph operations.ts CALLS upsert.
-          callerId: `${call.callerKind}:${call.callerFilePath}:${call.callerName}`,
-          calleeId: call.calleeFilePath
-            ? `Function:${call.calleeFilePath}:${call.calleeName}`
-            : `Function:external:${call.calleeName}`,
+          callerId: call.fromId ?? caller?.id ?? '',
+          calleeId: call.toId ?? '',
           line: call.line,
           callerKind: call.callerKind,
           via: call.via,
         };
         if (call.calleeClassName) edge.calleeClassName = call.calleeClassName;
+        if (call.calleeFilePath) {
+          edgeResolutionHints.set(edge, {
+            from: {
+              labels: [call.callerKind],
+              filePath: call.callerFilePath,
+              name: call.callerName,
+              startLine: call.callerStartLine,
+            },
+            to: {
+              labels: ['Function'],
+              filePath: call.calleeFilePath,
+              name: call.calleeName,
+              ...(call.calleeClassName ? { ownerName: call.calleeClassName } : {}),
+              exportedOnly: call.calleeFilePath !== call.callerFilePath && !call.calleeClassName,
+            },
+          });
+        }
         return edge;
       });
     } else if (plugin?.extractors.extractCalls) {
@@ -820,7 +1110,7 @@ export function buildParsedFileEntities(
       const refs = plugin.extractors.extractCalls(rootNode as unknown as GenericSyntaxNode, file.path, {
         imports: extracted.imports,
       });
-      callEdges = buildCallEdgesFromRefs(refs);
+      callEdges = buildCallEdgesFromRefs(refs, extracted);
     }
   }
 
@@ -834,13 +1124,26 @@ export function buildParsedFileEntities(
       extracted.imports,
       includeExternals,
     );
-    rendersEdges = renders.map((render) => ({
-      parentId: `Component:${render.parentFilePath}:${render.parentName}`,
-      childId: render.childFilePath
-        ? `Component:${render.childFilePath}:${render.childName}`
-        : `Component:external:${render.childName}`,
-      line: render.line,
-    }));
+    rendersEdges = renders.map((render) => {
+      const parent = extracted.components.find(component => component.name === render.parentName);
+      const edge = {
+        parentId: render.fromId ?? parent?.id ?? '',
+        childId: render.toId ?? '',
+        line: render.line,
+      };
+      if (render.childFilePath) {
+        edgeResolutionHints.set(edge, {
+          from: { labels: ['Component'], filePath: render.parentFilePath, name: render.parentName },
+          to: {
+            labels: ['Component'],
+            filePath: render.childFilePath,
+            name: render.childName,
+            exportedOnly: render.childFilePath !== render.parentFilePath,
+          },
+        });
+      }
+      return edge;
+    });
   }
 
   // --- TypeRefs / HAS_PARAM / RETURNS / USES_TYPE, re-resolved through the barrel chain ---
diff --git a/packages/core/src/services/graph-data-service.ts b/packages/core/src/services/graph-data-service.ts
index 0d0dc32e..223cfeaa 100644
--- a/packages/core/src/services/graph-data-service.ts
+++ b/packages/core/src/services/graph-data-service.ts
@@ -212,7 +212,13 @@ export async function getEntityWithConnectionsImpl(
     outLabels: string[] | null;
   }>(`
     MATCH (n)
-    WHERE n.filePath = $id OR (n.name + ':' + n.filePath) = $id
+    WHERE n.id = $id
+       OR ('Commit:' + n.hash) = $id
+       OR ('MarkdownDocument:' + n.path) = $id
+       OR ('Section:' + n.filePath + ':' + toString(n.startLine)) = $id
+       OR ('CodeBlock:' + n.filePath + ':' + toString(n.startLine)) = $id
+       OR ('Link:' + n.filePath + ':' + toString(n.line) + ':' + n.target) = $id
+       OR ('Entity:' + n.type + ':' + n.text) = $id
     OPTIONAL MATCH (inNode)-[inEdge]->(n)
     OPTIONAL MATCH (n)-[outEdge]->(outNode)
     RETURN n, ${dialect.labelsExpr('n')} as labels,
@@ -411,29 +417,19 @@ export async function getNeighborsImpl(
     cypherMatch = '(center)-[r]-(neighbor)';
   }
 
-  // Parse node ID to build center match
-  const parts = id.split(':');
-  const isFileId = parts[0] === 'File';
-  const actualPath = isFileId ? parts.slice(1).join(':') : undefined;
-
-  let centerMatch: string;
+  const centerMatch = `center.id = $id
+    OR ('Commit:' + center.hash) = $id
+    OR ('MarkdownDocument:' + center.path) = $id
+    OR ('Section:' + center.filePath + ':' + toString(center.startLine)) = $id
+    OR ('CodeBlock:' + center.filePath + ':' + toString(center.startLine)) = $id
+    OR ('Link:' + center.filePath + ':' + toString(center.line) + ':' + center.target) = $id
+    OR ('Entity:' + center.type + ':' + center.text) = $id`;
   const queryParams: Record<string, string | number | boolean | null | Array<unknown>> = { limit: depth * 50 };
   if (safeEdgeTypes && safeEdgeTypes.length > 0) {
     queryParams.edgeTypes = safeEdgeTypes;
   }
 
-  if (isFileId && actualPath) {
-    centerMatch = 'center.filePath = $actualPath';
-    queryParams.actualPath = actualPath;
-  } else if (parts.length >= 4) {
-    centerMatch = '(center.filePath = $filePath AND center.name = $name AND (center.startLine = $line OR center.line = $line))';
-    queryParams.filePath = parts[1] ?? '';
-    queryParams.name = parts[2] ?? '';
-    queryParams.line = parseInt(parts[3] ?? '0', 10) || 0;
-  } else {
-    centerMatch = '(center.name = $simpleId OR center.filePath = $simpleId)';
-    queryParams.simpleId = id;
-  }
+  queryParams.id = id;
 
   const result = await client.roQuery<{
     neighbor: Record<string, unknown>;
diff --git a/packages/core/src/services/helpers.ts b/packages/core/src/services/helpers.ts
index e4347382..dd5b9f66 100644
--- a/packages/core/src/services/helpers.ts
+++ b/packages/core/src/services/helpers.ts
@@ -103,10 +103,7 @@ export function generateNodeId(label: NodeLabel | 'Entity', props: Record<string
     case 'Variable':
     case 'Type':
     case 'Component': {
-      const name = stringProp(props, 'name') ?? '';
-      const filePath = stringProp(props, 'filePath') ?? '';
-      const line = numberProp(props, 'startLine') ?? numberProp(props, 'line') ?? 0;
-      return `${label}:${filePath}:${name}:${line}`;
+      return stringProp(props, 'id') ?? `${label}:unknown`;
     }
 
     case 'Commit': {
diff --git a/packages/dashboard/src/components/dashboard/app-shell.tsx b/packages/dashboard/src/components/dashboard/app-shell.tsx
index ef3e0600..d6f32b1b 100644
--- a/packages/dashboard/src/components/dashboard/app-shell.tsx
+++ b/packages/dashboard/src/components/dashboard/app-shell.tsx
@@ -7,11 +7,9 @@ import { EntityDetail } from './entity-detail'
 import { QueryPanel } from './query-panel'
 import { API_URL } from '@/lib/api'
 import {
-  canonicalSymbolNodeId,
   fetchFileRelationships,
   fetchReferences,
   isReferenceable,
-  referenceKey,
   type SymbolReferences,
 } from '@/lib/references'
 import type { FileRelationshipsState } from './entity-detail'
@@ -74,12 +72,7 @@ export function deriveBreadcrumbs(
       label: basename(filePath),
       node: selectedNode.type === 'File'
         ? selectedNode
-        : {
-            id: `File:${filePath}`,
-            label: basename(filePath),
-            type: 'File',
-            properties: { name: basename(filePath), filePath },
-          },
+        : null,
     })
   }
   if (selectedNode.type !== 'File') {
@@ -89,13 +82,22 @@ export function deriveBreadcrumbs(
 }
 
 export function searchResultToGraphNode(result: SearchResult): GraphNode {
-  const startLine = typeof result.startLine === 'number' ? result.startLine : null
+  if (typeof result.id === 'string' && result.nodeType === 'File' && /^File:.+/.test(result.id)) {
+    const filePath = typeof result.filePath === 'string' && result.filePath.length > 0
+      ? result.filePath
+      : result.id.slice('File:'.length)
+    return {
+      id: result.id,
+      label: result.name,
+      type: 'File',
+      properties: { ...result, filePath },
+    }
+  }
+  if (typeof result.id !== 'string' || !/^sym:v1:[a-f0-9]{64}$/.test(result.id)) {
+    throw new Error('Search result is missing a persisted id')
+  }
   return {
-    id: canonicalSymbolNodeId(result.nodeType, {
-      name: result.name,
-      filePath: result.filePath,
-      startLine,
-    }),
+    id: result.id,
     label: result.name,
     type: result.nodeType,
     properties: result,
@@ -164,7 +166,7 @@ export function ExplorerNavigation({
 
 export function AppShell({ projectId, projectName }: { projectId?: string | null; projectName?: string }) {
   const [selectionHistory, setSelectionHistory] = useState<SelectionHistory>(EMPTY_SELECTION_HISTORY)
-  const [highlightedNames, setHighlightedNames] = useState<Set<string>>(new Set())
+  const [highlightedNodeIds, setHighlightedNodeIds] = useState<Set<string>>(new Set())
   const [hiddenEdgeTypes, setHiddenEdgeTypes] = useState<Set<string>>(new Set())
   const [hiddenNodeTypes, setHiddenNodeTypes] = useState<Set<string>>(new Set())
   const [showQuery, setShowQuery] = useState(false)
@@ -216,9 +218,7 @@ export function AppShell({ projectId, projectName }: { projectId?: string | null
     const controller = new AbortController()
     setReferencesLoading(true)
     fetchReferences(
-      name,
-      selectedNode.properties?.filePath as string | undefined,
-      selectedNode.properties?.startLine as number | undefined,
+      selectedNode.id,
       controller.signal,
     )
       .then((result) => {
@@ -261,12 +261,12 @@ export function AppShell({ projectId, projectName }: { projectId?: string | null
     return () => controller.abort()
   }, [selectedNode])
 
-  const referenceKeys = new Set(
-    (references?.references ?? []).map((r) => referenceKey(r.filePath, r.name, r.startLine)),
+  const referenceNodeIds = new Set(
+    (references?.references ?? []).map((reference) => reference.id),
   )
 
-  const handleSearchHighlight = useCallback((names: string[]) => {
-    setHighlightedNames(new Set(names))
+  const handleSearchHighlight = useCallback((nodeIds: string[]) => {
+    setHighlightedNodeIds(new Set(nodeIds.filter((id) => id.startsWith('sym:v1:'))))
   }, [])
 
   const handleToggleEdgeType = useCallback((edgeType: string) => {
@@ -295,10 +295,11 @@ export function AppShell({ projectId, projectName }: { projectId?: string | null
           apiUrl={API_URL}
           onHighlight={handleSearchHighlight}
           onSelectResult={(result) => {
-            setHighlightedNames(new Set([result.name]))
+            const node = searchResultToGraphNode(result)
+            setHighlightedNodeIds(new Set([node.id]))
             // Open the detail panel too. The search payload already carries
             // filePath and line numbers, which is everything the panel needs.
-            handleNodeSelect(searchResultToGraphNode(result))
+            handleNodeSelect(node)
           }}
         />
       </ResizablePanel>
@@ -314,11 +315,11 @@ export function AppShell({ projectId, projectName }: { projectId?: string | null
                 apiUrl={API_URL}
                 onNodeSelect={handleNodeSelect}
                 selectedNode={selectedNode}
-                highlightedNames={highlightedNames}
+                highlightedNodeIds={highlightedNodeIds}
                 hiddenEdgeTypes={hiddenEdgeTypes}
                 hiddenNodeTypes={hiddenNodeTypes}
                 projectId={projectId}
-                referenceKeys={referenceKeys}
+                referenceNodeIds={referenceNodeIds}
               />
               {/* Toolbar: Query toggle + Legend */}
               <div style={{ position: 'absolute', top: 12, left: 12, zIndex: 10, display: 'flex', flexDirection: 'column', alignItems: 'start', gap: 8 }}>
diff --git a/packages/dashboard/src/components/dashboard/entity-detail.tsx b/packages/dashboard/src/components/dashboard/entity-detail.tsx
index dee407d8..4f4a3474 100644
--- a/packages/dashboard/src/components/dashboard/entity-detail.tsx
+++ b/packages/dashboard/src/components/dashboard/entity-detail.tsx
@@ -5,7 +5,6 @@ import { Button } from '@/components/ui/button'
 import { Separator } from '@/components/ui/separator'
 import { NODE_COLORS } from '@/lib/cytoscape-config'
 import { API_URL } from '@/lib/api'
-import { canonicalSymbolNodeId } from '@/lib/references'
 import type {
   FileRelationshipNode,
   FileRelationships,
@@ -613,8 +612,8 @@ function ReferenceGroup({ label, items, declaringFile, onSelect }: {
         {label}
       </p>
       <ul className="space-y-1">
-        {items.map((ref, index) => (
-          <li key={`${ref.filePath}:${ref.name}:${ref.startLine ?? index}:${ref.edgeType}`}>
+        {items.map((ref) => (
+          <li key={`${ref.id}:${ref.edgeType}`}>
             <button
               type="button"
               className="w-full rounded-md border border-border/60 bg-background px-2 py-1.5 text-left transition-colors hover:border-border hover:bg-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
@@ -640,7 +639,7 @@ function ReferenceGroup({ label, items, declaringFile, onSelect }: {
 
 export function symbolReferenceToGraphNode(ref: SymbolReference): GraphNode {
   return {
-    id: canonicalSymbolNodeId(ref.nodeType, ref),
+    id: ref.id,
     label: ref.name,
     type: ref.nodeType,
     properties: {
diff --git a/packages/dashboard/src/components/dashboard/explorer-navigation.test.tsx b/packages/dashboard/src/components/dashboard/explorer-navigation.test.tsx
index d70b7a6d..86c1eb91 100644
--- a/packages/dashboard/src/components/dashboard/explorer-navigation.test.tsx
+++ b/packages/dashboard/src/components/dashboard/explorer-navigation.test.tsx
@@ -20,7 +20,7 @@ const fileNode: GraphNode = {
 }
 
 const symbolNode: GraphNode = {
-  id: 'Function:/repo/src/main.ts:run:5',
+  id: 'sym:v1:1111111111111111111111111111111111111111111111111111111111111111',
   label: 'run',
   type: 'Function',
   properties: { filePath: '/repo/src/main.ts', name: 'run', startLine: 5 },
@@ -29,7 +29,7 @@ const symbolNode: GraphNode = {
 describe('explorer selection history', () => {
   it('uses canonical graph identity for real search and reference payloads', () => {
     const canonicalNode: GraphNode = {
-      id: 'Function:/repo/src/main.ts:run:5',
+      id: 'sym:v1:1111111111111111111111111111111111111111111111111111111111111111',
       label: 'run',
       type: 'Function',
       properties: {
@@ -39,6 +39,7 @@ describe('explorer selection history', () => {
       },
     }
     const searchResult = {
+      id: canonicalNode.id,
       name: 'run',
       nodeType: 'Function',
       filePath: '/repo/src/main.ts',
@@ -47,6 +48,7 @@ describe('explorer selection history', () => {
       isExported: true,
     }
     const referenceRow: SymbolReference = {
+      id: canonicalNode.id,
       name: 'run',
       nodeType: 'Function',
       filePath: '/repo/src/main.ts',
@@ -59,20 +61,36 @@ describe('explorer selection history', () => {
     expect(symbolReferenceToGraphNode(referenceRow).id).toBe(canonicalNode.id)
 
     expect(searchResultToGraphNode({
-      name: 'run',
-      nodeType: 'Function',
-      filePath: '/repo/src/main.ts',
+      id: 'File:/repo/src/needle-file.ts',
+      name: 'needle-file.ts',
+      nodeType: 'File',
+      filePath: '/repo/src/needle-file.ts',
       startLine: null,
       endLine: null,
       isExported: null,
-    }).id).toBe('Function:/repo/src/main.ts:run:0')
-    expect(symbolReferenceToGraphNode({
+    })).toEqual({
+      id: 'File:/repo/src/needle-file.ts',
+      label: 'needle-file.ts',
+      type: 'File',
+      properties: {
+        id: 'File:/repo/src/needle-file.ts',
+        name: 'needle-file.ts',
+        nodeType: 'File',
+        filePath: '/repo/src/needle-file.ts',
+        startLine: null,
+        endLine: null,
+        isExported: null,
+      },
+    })
+
+    expect(() => searchResultToGraphNode({
       name: 'run',
       nodeType: 'Function',
       filePath: '/repo/src/main.ts',
-      edgeType: 'CALLS',
-      sameFile: false,
-    }).id).toBe('Function:/repo/src/main.ts:run:0')
+      startLine: null,
+      endLine: null,
+      isExported: null,
+    })).toThrow('Search result is missing a persisted id')
   })
 
   it('deduplicates consecutive selections and truncates Forward after a new branch', () => {
@@ -82,7 +100,7 @@ describe('explorer selection history', () => {
 
     expect(history.entries.map((node) => node?.id ?? null)).toEqual([
       'File:/repo/src/main.ts',
-      'Function:/repo/src/main.ts:run:5',
+      symbolNode.id,
     ])
     expect(history.index).toBe(1)
 
@@ -114,7 +132,7 @@ describe('explorer breadcrumbs', () => {
 
     expect(crumbs.map((crumb) => [crumb.level, crumb.label, crumb.node?.id ?? null])).toEqual([
       ['project', 'CodeGraph', null],
-      ['file', 'main.ts', 'File:/repo/src/main.ts'],
+      ['file', 'main.ts', null],
       ['symbol', 'run', symbolNode.id],
     ])
   })
diff --git a/packages/dashboard/src/components/dashboard/graph-canvas.tsx b/packages/dashboard/src/components/dashboard/graph-canvas.tsx
index 8eb8f833..dc40b329 100644
--- a/packages/dashboard/src/components/dashboard/graph-canvas.tsx
+++ b/packages/dashboard/src/components/dashboard/graph-canvas.tsx
@@ -36,23 +36,6 @@ export interface CanvasSelectionPlan {
   nodeToAdd: CanvasNodeElement | null
 }
 
-function graphNodeIdentityMatches(candidate: GraphNode, requested: GraphNode): boolean {
-  if (candidate.id === requested.id) return true
-  if (candidate.type !== requested.type) return false
-
-  const candidatePath = candidate.properties.filePath
-  const requestedPath = requested.properties.filePath
-  if (typeof candidatePath !== 'string' || candidatePath !== requestedPath) return false
-
-  const candidateName = candidate.properties.name ?? candidate.label
-  const requestedName = requested.properties.name ?? requested.label
-  if (candidateName !== requestedName) return false
-
-  const candidateLine = candidate.properties.startLine
-  const requestedLine = requested.properties.startLine
-  return candidateLine === undefined || requestedLine === undefined || candidateLine === requestedLine
-}
-
 function graphNodeToCanvasElement(node: GraphNode): CanvasNodeElement {
   const filePath = typeof node.properties.filePath === 'string'
     ? node.properties.filePath
@@ -72,7 +55,7 @@ export function planCanvasSelection(
   loadedNodes: readonly GraphNode[],
   requestedNode: GraphNode,
 ): CanvasSelectionPlan {
-  const existingNode = loadedNodes.find((node) => graphNodeIdentityMatches(node, requestedNode))
+  const existingNode = loadedNodes.find((node) => node.id === requestedNode.id)
   const nodeId = existingNode?.id ?? requestedNode.id
 
   return {
@@ -85,15 +68,15 @@ interface GraphCanvasProps {
   apiUrl: string
   onNodeSelect: (node: GraphNode | null) => void
   selectedNode?: GraphNode | null
-  highlightedNames: Set<string>
-  /** `filePath::name` of every symbol that uses the selected one. */
-  referenceKeys?: Set<string>
+  highlightedNodeIds: Set<string>
+  /** Persisted ids of every symbol that uses the selected one. */
+  referenceNodeIds?: Set<string>
   hiddenEdgeTypes: Set<string>
   hiddenNodeTypes: Set<string>
   projectId?: string | null
 }
 
-export function GraphCanvas({ apiUrl, onNodeSelect, selectedNode, highlightedNames, referenceKeys, hiddenEdgeTypes, hiddenNodeTypes, projectId }: GraphCanvasProps) {
+export function GraphCanvas({ apiUrl, onNodeSelect, selectedNode, highlightedNodeIds, referenceNodeIds, hiddenEdgeTypes, hiddenNodeTypes, projectId }: GraphCanvasProps) {
   const containerRef = useRef<HTMLDivElement>(null)
   const cyRef = useRef<cytoscape.Core | null>(null)
   const resizeObserverRef = useRef<ResizeObserver | null>(null)
@@ -287,9 +270,9 @@ export function GraphCanvas({ apiUrl, onNodeSelect, selectedNode, highlightedNam
 
     cy.nodes().removeClass('highlighted dimmed')
     cy.edges().removeClass('dimmed')
-    if (highlightedNames.size > 0) {
+    if (highlightedNodeIds.size > 0) {
       cy.nodes().forEach((node) => {
-        if (highlightedNames.has(node.data('label'))) {
+        if (highlightedNodeIds.has(node.id())) {
           node.addClass('highlighted')
         } else {
           node.addClass('dimmed')
@@ -297,7 +280,7 @@ export function GraphCanvas({ apiUrl, onNodeSelect, selectedNode, highlightedNam
       })
       cy.edges().addClass('dimmed')
     }
-  }, [highlightedNames])
+  }, [highlightedNodeIds])
 
   // Mark the symbols that use the selected one.
   //
@@ -309,17 +292,12 @@ export function GraphCanvas({ apiUrl, onNodeSelect, selectedNode, highlightedNam
     if (!cy) return
 
     cy.nodes().removeClass('reference')
-    if (!referenceKeys || referenceKeys.size === 0) return
+    if (!referenceNodeIds || referenceNodeIds.size === 0) return
 
     cy.nodes().forEach((node) => {
-      const key = [
-        (node.data('filePath') as string | undefined) ?? '',
-        node.data('label') as string,
-        (node.data('startLine') as number | undefined) ?? '',
-      ].join('::')
-      if (referenceKeys.has(key)) node.addClass('reference')
+      if (referenceNodeIds.has(node.id())) node.addClass('reference')
     })
-  }, [referenceKeys])
+  }, [referenceNodeIds])
 
   // Handle edge type filter changes
   useEffect(() => {
diff --git a/packages/dashboard/src/components/dashboard/graph-explorer.test.tsx b/packages/dashboard/src/components/dashboard/graph-explorer.test.tsx
index 38ad37c2..07234ccc 100644
--- a/packages/dashboard/src/components/dashboard/graph-explorer.test.tsx
+++ b/packages/dashboard/src/components/dashboard/graph-explorer.test.tsx
@@ -11,7 +11,7 @@ import { GraphControls } from './graph-controls'
 import { GraphLegend, buildNodeLegend } from './graph-legend'
 
 const selectedNode: GraphNode = {
-  id: 'Function:/repo/main.ts:run:4',
+  id: 'sym:v1:4444444444444444444444444444444444444444444444444444444444444444',
   label: 'run',
   type: 'Function',
   properties: { name: 'run', filePath: '/repo/main.ts', startLine: 4 },
@@ -63,7 +63,7 @@ describe('graph explorer accessibility', () => {
         apiUrl="http://dashboard.test"
         onNodeSelect={vi.fn()}
         selectedNode={null}
-        highlightedNames={new Set()}
+        highlightedNodeIds={new Set()}
         hiddenEdgeTypes={new Set()}
         hiddenNodeTypes={new Set()}
       />,
diff --git a/packages/dashboard/src/components/dashboard/node-identity-source-guard.test.ts b/packages/dashboard/src/components/dashboard/node-identity-source-guard.test.ts
new file mode 100644
index 00000000..ef218312
--- /dev/null
+++ b/packages/dashboard/src/components/dashboard/node-identity-source-guard.test.ts
@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const dashboardDirectory = dirname(fileURLToPath(import.meta.url))
+
+const ownedSources = [
+  resolve(dashboardDirectory, '../../lib/references.ts'),
+  resolve(dashboardDirectory, 'app-shell.tsx'),
+  resolve(dashboardDirectory, 'graph-canvas.tsx'),
+  resolve(dashboardDirectory, 'entity-detail.tsx'),
+]
+
+describe('dashboard node identity source guard', () => {
+  it('never constructs symbol ids from label, path, name, or line fields', () => {
+    const source = ownedSources.map((path) => readFileSync(path, 'utf8')).join('\n')
+
+    expect(source).not.toContain('canonicalSymbolNodeId')
+    expect(source).not.toMatch(/\$\{label\}:\$\{filePath\}:\$\{name\}/)
+    expect(source).not.toContain('graphNodeIdentityMatches')
+    expect(source).not.toContain('referenceKey')
+  })
+})
diff --git a/packages/dashboard/src/components/dashboard/search-panel.test.tsx b/packages/dashboard/src/components/dashboard/search-panel.test.tsx
index 44bdce8d..54252874 100644
--- a/packages/dashboard/src/components/dashboard/search-panel.test.tsx
+++ b/packages/dashboard/src/components/dashboard/search-panel.test.tsx
@@ -40,7 +40,7 @@ describe('SearchPanel latest request behavior', () => {
     const newer = deferred<Response>()
     const visibleNames: string[][] = []
     const visibleTotals: number[] = []
-    const highlightedNames: string[][] = []
+    const highlightedNodeIds: string[][] = []
     const signals: AbortSignal[] = []
     const fetchMock = vi.fn((_input: RequestInfo | URL, init?: RequestInit) => {
       if (init?.signal) signals.push(init.signal)
@@ -56,7 +56,7 @@ describe('SearchPanel latest request behavior', () => {
       fetchImpl: fetchMock,
       onResults: (results) => visibleNames.push(results.map((result) => result.name)),
       onTotal: (total) => visibleTotals.push(total),
-      onHighlight: (names) => highlightedNames.push(names),
+      onHighlight: (nodeIds) => highlightedNodeIds.push(nodeIds),
       onSearching: vi.fn(),
       onError: vi.fn(),
     })
@@ -67,15 +67,17 @@ describe('SearchPanel latest request behavior', () => {
     expect(signals[0]?.aborted).toBe(true)
     await vi.advanceTimersByTimeAsync(250)
 
-    newer.resolve(jsonResponse({ results: [{ name: 'newerResult', nodeType: 'Function' }], total: 1 }))
-    await vi.waitFor(() => expect(visibleNames.at(-1)).toEqual(['newerResult']))
-    older.resolve(jsonResponse({ results: [{ name: 'olderResult', nodeType: 'Class' }], total: 99 }))
+    const newerId = `sym:v1:${'a'.repeat(64)}`
+    const olderId = `sym:v1:${'b'.repeat(64)}`
+    newer.resolve(jsonResponse({ results: [{ id: newerId, name: 'sharedName', nodeType: 'Function' }], total: 1 }))
+    await vi.waitFor(() => expect(visibleNames.at(-1)).toEqual(['sharedName']))
+    older.resolve(jsonResponse({ results: [{ id: olderId, name: 'sharedName', nodeType: 'Class' }], total: 99 }))
     await Promise.resolve()
     await Promise.resolve()
 
-    expect(visibleNames.at(-1)).toEqual(['newerResult'])
+    expect(visibleNames.at(-1)).toEqual(['sharedName'])
     expect(visibleTotals.at(-1)).toBe(1)
-    expect(highlightedNames.at(-1)).toEqual(['newerResult'])
+    expect(highlightedNodeIds.at(-1)).toEqual([newerId])
   })
 
   it('does not report an aborted request as an error', async () => {
diff --git a/packages/dashboard/src/components/dashboard/search-panel.tsx b/packages/dashboard/src/components/dashboard/search-panel.tsx
index ee2ccffa..ee32aff2 100644
--- a/packages/dashboard/src/components/dashboard/search-panel.tsx
+++ b/packages/dashboard/src/components/dashboard/search-panel.tsx
@@ -3,6 +3,7 @@ import { Input } from '@/components/ui/input'
 import { Badge } from '@/components/ui/badge'
 
 export interface SearchResult {
+  id?: string
   name: string
   nodeType: string
   filePath?: string
@@ -13,18 +14,22 @@ export interface SearchResult {
   [key: string]: unknown
 }
 
+export interface SearchResponseResult extends SearchResult {
+  id: string
+}
+
 interface SearchPanelProps {
   apiUrl: string
-  onHighlight: (names: string[]) => void
-  onSelectResult: (result: SearchResult) => void
+  onHighlight: (nodeIds: string[]) => void
+  onSelectResult: (result: SearchResponseResult) => void
 }
 
 interface SearchRequestManagerOptions {
   apiUrl: string
   fetchImpl?: typeof fetch
-  onResults: (results: SearchResult[]) => void
+  onResults: (results: SearchResponseResult[]) => void
   onTotal: (total: number) => void
-  onHighlight: (names: string[]) => void
+  onHighlight: (nodeIds: string[]) => void
   onSearching: (searching: boolean) => void
   onError: (error: string | null) => void
 }
@@ -43,7 +48,7 @@ function isAbortError(error: unknown): boolean {
     : error instanceof Error && error.name === 'AbortError'
 }
 
-function parseSearchResponse(value: unknown): { results: SearchResult[]; total: number } {
+function parseSearchResponse(value: unknown): { results: SearchResponseResult[]; total: number } {
   if (typeof value !== 'object' || value === null) {
     throw new Error('Search returned an invalid response')
   }
@@ -56,11 +61,12 @@ function parseSearchResponse(value: unknown): { results: SearchResult[]; total:
   const validResults = response.results.every((item) => (
     typeof item === 'object'
     && item !== null
+    && typeof (item as Record<string, unknown>).id === 'string'
     && typeof (item as Record<string, unknown>).name === 'string'
     && typeof (item as Record<string, unknown>).nodeType === 'string'
   ))
   if (!validResults) throw new Error('Search returned an invalid response')
-  const results = response.results as SearchResult[]
+  const results = response.results as SearchResponseResult[]
   const total = typeof response.total === 'number' && Number.isFinite(response.total)
     ? response.total
     : results.length
@@ -110,7 +116,7 @@ export function createSearchRequestManager({
 
       onResults(data.results)
       onTotal(data.total)
-      onHighlight(data.results.map((result) => result.name))
+      onHighlight(data.results.map((result) => result.id))
     } catch (error) {
       if (requestGeneration !== generation || isAbortError(error)) return
       onError('Search failed. Please try again.')
@@ -169,7 +175,7 @@ export function createSearchRequestManager({
 
 export function SearchPanel({ apiUrl, onHighlight, onSelectResult }: SearchPanelProps) {
   const [query, setQuery] = useState('')
-  const [results, setResults] = useState<SearchResult[]>([])
+  const [results, setResults] = useState<SearchResponseResult[]>([])
   const [searching, setSearching] = useState(false)
   const [total, setTotal] = useState(0)
   const [error, setError] = useState<string | null>(null)
@@ -222,9 +228,9 @@ export function SearchPanel({ apiUrl, onHighlight, onSelectResult }: SearchPanel
       </div>
 
       <div className="flex-1 overflow-y-auto">
-        {results.map((r, i) => (
+        {results.map((r) => (
           <button
-            key={`${r.name}-${i}`}
+            key={r.id}
             className="w-full border-b border-border/50 px-3 py-2 text-left transition-colors hover:bg-accent/50"
             onClick={() => onSelectResult(r)}
           >
diff --git a/packages/dashboard/src/lib/references.ts b/packages/dashboard/src/lib/references.ts
index f51f6e6f..5be74fb9 100644
--- a/packages/dashboard/src/lib/references.ts
+++ b/packages/dashboard/src/lib/references.ts
@@ -12,7 +12,17 @@ import { API_URL } from './api'
 
 export type ReferenceEdgeType = 'CALLS' | 'USES_TYPE' | 'EXTENDS' | 'IMPLEMENTS' | 'RENDERS'
 
+const REFERENCE_EDGE_TYPES = new Set<ReferenceEdgeType>([
+  'CALLS',
+  'USES_TYPE',
+  'EXTENDS',
+  'IMPLEMENTS',
+  'RENDERS',
+])
+const SYMBOL_ID_PATTERN = /^sym:v1:[a-f0-9]{64}$/
+
 export interface SymbolReference {
+  id: string
   name: string
   nodeType: string
   filePath: string
@@ -27,20 +37,6 @@ export interface SymbolReferences {
   truncated: boolean
 }
 
-interface SymbolNodeIdentity {
-  name?: string | null
-  filePath?: string | null
-  startLine?: number | null
-  line?: number | null
-}
-
-export function canonicalSymbolNodeId(label: string, node: SymbolNodeIdentity): string {
-  const name = node.name ?? ''
-  const filePath = node.filePath ?? ''
-  const line = node.startLine ?? node.line ?? 0
-  return `${label}:${filePath}:${name}:${line}`
-}
-
 export interface FileRelationshipNode {
   id: string
   label: string
@@ -71,42 +67,56 @@ export function isReferenceable(nodeType: string): boolean {
   return REFERENCEABLE_TYPES.has(nodeType)
 }
 
-/**
- * Identity used to match a reference against a node on the canvas.
- *
- * The line is part of the identity because a file can hold several symbols of
- * the same name, and only one of them is the end of the relationship. Matching
- * on path and name alone lit up all of them.
- */
-export function referenceKey(
-  filePath: string | undefined,
-  name: string,
-  startLine: number | undefined,
-): string {
-  return `${filePath ?? ''}::${name}::${startLine ?? ''}`
-}
-
 export async function fetchReferences(
-  name: string,
-  filePath: string | undefined,
-  startLine: number | undefined,
+  id: string,
   signal?: AbortSignal,
+  fetchImpl: typeof fetch = fetch,
 ): Promise<SymbolReferences> {
-  const params = new URLSearchParams({ name })
-  if (filePath) params.set('path', filePath)
-  if (startLine != null) params.set('startLine', String(startLine))
+  const params = new URLSearchParams({ id })
 
-  const response = await fetch(`${API_URL}/api/graph/references?${params.toString()}`, { signal })
+  const response = await fetchImpl(`${API_URL}/api/graph/references?${params.toString()}`, { signal })
   if (!response.ok) {
     throw new Error(`References request failed with ${response.status}`)
   }
-  return (await response.json()) as SymbolReferences
+  return parseSymbolReferences(await response.json())
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
+function isSymbolReference(value: unknown): value is SymbolReference {
+  return isRecord(value)
+    && typeof value.id === 'string'
+    && SYMBOL_ID_PATTERN.test(value.id)
+    && typeof value.name === 'string'
+    && typeof value.nodeType === 'string'
+    && typeof value.filePath === 'string'
+    && (value.startLine === undefined || typeof value.startLine === 'number')
+    && typeof value.edgeType === 'string'
+    && REFERENCE_EDGE_TYPES.has(value.edgeType as ReferenceEdgeType)
+    && typeof value.sameFile === 'boolean'
+}
+
+function parseSymbolReferences(value: unknown): SymbolReferences {
+  if (
+    !isRecord(value)
+    || !Array.isArray(value.references)
+    || !value.references.every(isSymbolReference)
+    || !Array.isArray(value.referencingFiles)
+    || !value.referencingFiles.every((filePath) => typeof filePath === 'string')
+    || typeof value.truncated !== 'boolean'
+  ) {
+    throw new Error('Invalid references response')
+  }
+
+  return {
+    references: value.references,
+    referencingFiles: value.referencingFiles,
+    truncated: value.truncated,
+  }
+}
+
 function parseRelationshipNode(value: unknown): FileRelationshipNode {
   if (
     !isRecord(value)
diff --git a/packages/graph/src/__tests__/calls-edge-by-class.test.ts b/packages/graph/src/__tests__/calls-edge-by-class.test.ts
index 95592039..d4f8fa18 100644
--- a/packages/graph/src/__tests__/calls-edge-by-class.test.ts
+++ b/packages/graph/src/__tests__/calls-edge-by-class.test.ts
@@ -169,7 +169,19 @@ describeIfAvailable('CALLS edge creation: class-qualified matching', () => {
 
     const appParsed = emptyParsed(makeFile(APP_FILE));
     appParsed.functions = [
-      { name: 'runBasic', filePath: APP_FILE, startLine: 1, endLine: 4, isExported: true, isAsync: false, isArrow: false, params: [] },
+      {
+        id: 'sym:v1:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
+        scopeKey: '',
+        disambiguator: '',
+        name: 'runBasic',
+        filePath: APP_FILE,
+        startLine: 1,
+        endLine: 4,
+        isExported: true,
+        isAsync: false,
+        isArrow: false,
+        params: [],
+      },
     ];
 
     await ops.batchUpsert(serviceParsed);
@@ -296,7 +308,9 @@ describeIfAvailable('CALLS edge creation: class-qualified matching', () => {
       params: [],
     };
     const runBasic: FunctionEntity = {
-      name: 'runBasic', filePath: APP_FILE, startLine: 1, endLine: 4, isExported: true, isAsync: false, isArrow: false, params: [],
+      id: 'sym:v1:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
+      scopeKey: '', disambiguator: '', name: 'runBasic', filePath: APP_FILE,
+      startLine: 1, endLine: 4, isExported: true, isAsync: false, isArrow: false, params: [],
     };
 
     const serviceParsed = emptyParsed(makeFile(SERVICE_FILE));
diff --git a/packages/graph/src/__tests__/falkordblite.test.ts b/packages/graph/src/__tests__/falkordblite.test.ts
index 779ce465..fade3050 100644
--- a/packages/graph/src/__tests__/falkordblite.test.ts
+++ b/packages/graph/src/__tests__/falkordblite.test.ts
@@ -49,6 +49,9 @@ function makeFile(overrides?: Partial<FileEntity>): FileEntity {
 
 function makeFunction(overrides?: Partial<FunctionEntity>): FunctionEntity {
   return {
+    id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+    scopeKey: '',
+    disambiguator: '',
     name: 'myFunction',
     filePath: '/src/index.ts',
     startLine: 10,
diff --git a/packages/graph/src/__tests__/full-graph-window.test.ts b/packages/graph/src/__tests__/full-graph-window.test.ts
index 62ff9fee..93e24990 100644
--- a/packages/graph/src/__tests__/full-graph-window.test.ts
+++ b/packages/graph/src/__tests__/full-graph-window.test.ts
@@ -25,11 +25,12 @@ describeIfAvailable('dashboard full-graph window', () => {
 
     await client.query(`
       CREATE (a:Function {
+        id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
         name: 'a', filePath: '/x/a.ts', startLine: 1,
         embedding: [0.1, 0.2], embeddingTextHash: 'hash-a'
       })
-      CREATE (b:Function {name: 'b', filePath: '/x/b.ts', startLine: 1})
-      CREATE (c:Function {name: 'c', filePath: '/x/c.ts', startLine: 1})
+      CREATE (b:Function {id: 'sym:v1:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb', name: 'b', filePath: '/x/b.ts', startLine: 1})
+      CREATE (c:Function {id: 'sym:v1:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc', name: 'c', filePath: '/x/c.ts', startLine: 1})
       CREATE (a)-[:CALLS {
         embedding: [0.5, 0.6], embeddingTextHash: 'hash-edge'
       }]->(b)
@@ -56,6 +57,13 @@ describeIfAvailable('dashboard full-graph window', () => {
     }
   });
 
+  it('returns the persisted opaque symbol id as the graph node id', async () => {
+    const result = await queries.getFullGraph(3);
+    const nodeA = result.nodes.find((node) => node.displayName === 'a');
+
+    expect(nodeA?.id).toBe('sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
+  });
+
   it('projects embedding fields out of dashboard graph nodes', async () => {
     const result = await queries.getFullGraph(3);
     const nodeA = result.nodes.find((node) => node.displayName === 'a');
@@ -72,10 +80,11 @@ describeIfAvailable('dashboard full-graph window', () => {
     await client.query(`
       MATCH (a:Function {name: 'a'})
       CREATE (decision:Entity {
+        id: 'entity:v1:retry-policy',
         text: 'Retry policy', type: 'Decision',
         embedding: [0.3, 0.4], embeddingTextHash: 'hash-decision'
       })
-      CREATE (person:Entity {text: 'Randy', type: 'Person'})
+      CREATE (person:Entity {id: 'entity:v1:randy', text: 'Randy', type: 'Person'})
       CREATE (decision)-[:ABOUT]->(a)
       CREATE (person)-[:RELATES_TO {type: 'AUTHORED'}]->(decision)
     `);
@@ -85,7 +94,7 @@ describeIfAvailable('dashboard full-graph window', () => {
     const edgeLabels = new Set(result.edges.map((edge) => edge.label));
 
     expect(decision).toMatchObject({
-      id: 'Entity:Decision:Retry policy',
+      id: 'entity:v1:retry-policy',
       label: 'Entity',
       displayName: 'Retry policy',
     });
@@ -97,11 +106,12 @@ describeIfAvailable('dashboard full-graph window', () => {
 
   it('returns categorized File relationships for the dashboard side panel', async () => {
     await client.query(`
-      CREATE (main:File {filePath: '/x/main.ts', name: 'main.ts'})
-      CREATE (dep:File {filePath: '/x/dep.ts', name: 'dep.ts'})
-      CREATE (importer:File {filePath: '/x/importer.ts', name: 'importer.ts'})
-      CREATE (run:Function {name: 'run', filePath: '/x/main.ts', startLine: 5})
+      CREATE (main:File {id: 'file:v1:main', filePath: '/x/main.ts', name: 'main.ts'})
+      CREATE (dep:File {id: 'file:v1:dep', filePath: '/x/dep.ts', name: 'dep.ts'})
+      CREATE (importer:File {id: 'file:v1:importer', filePath: '/x/importer.ts', name: 'importer.ts'})
+      CREATE (run:Function {id: 'sym:v1:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd', name: 'run', filePath: '/x/main.ts', startLine: 5})
       CREATE (knowledge:Entity {
+        id: 'entity:v1:main-entry-point',
         text: 'Main entry point', type: 'Decision',
         embedding: [0.8, 0.9], embeddingTextHash: 'hash-knowledge'
       })
@@ -127,13 +137,36 @@ describeIfAvailable('dashboard full-graph window', () => {
     expect(result.imports.map((node) => node.filePath)).toEqual(['/x/dep.ts']);
     expect(result.importers.map((node) => node.filePath)).toEqual(['/x/importer.ts']);
     expect(result.knowledgeEntities[0]).toMatchObject({
-      id: 'Entity:Decision:Main entry point',
+      id: 'entity:v1:main-entry-point',
       label: 'Entity',
       displayName: 'Main entry point',
     });
     expect(result.knowledgeEntities[0]?.data).not.toHaveProperty('embedding');
     expect(result.knowledgeEntities[0]?.data).not.toHaveProperty('embeddingTextHash');
   });
+
+  it('returns persisted ids from dependency and file subgraph reads', async () => {
+    await client.query(`
+      CREATE (entry:File {id: 'file:v1:entry', filePath: '/deps/entry.ts', name: 'entry.ts'})
+      CREATE (dependency:File {id: 'file:v1:dependency', filePath: '/deps/dependency.ts', name: 'dependency.ts'})
+      CREATE (symbol:Function {id: 'sym:v1:1212121212121212121212121212121212121212121212121212121212121212', name: 'entry', filePath: '/deps/entry.ts', startLine: 3})
+      CREATE (entry)-[:IMPORTS]->(dependency)
+      CREATE (entry)-[:CONTAINS]->(symbol)
+    `);
+
+    const dependencies = await queries.getDependencyTree('/deps/entry.ts', 1);
+    const subgraph = await queries.getFileSubgraph('/deps/entry.ts');
+
+    expect(new Set(dependencies.nodes.map((node) => node.id))).toEqual(
+      new Set(['file:v1:entry', 'file:v1:dependency']),
+    );
+    expect(subgraph.nodes.map((node) => node.id)).toEqual(
+      expect.arrayContaining([
+        'file:v1:entry',
+        'sym:v1:1212121212121212121212121212121212121212121212121212121212121212',
+      ]),
+    );
+  });
 });
 
 describeIfAvailable('project-scoped dashboard full graph', () => {
@@ -152,28 +185,29 @@ describeIfAvailable('project-scoped dashboard full graph', () => {
 
     await client.query(`
       CREATE (projectA:Project {id: 'project-a', rootPath: '/x/project'})
-      CREATE (fileA:File {name: 'a.ts', filePath: '/x/project/a.ts'})
-      CREATE (functionA:Function {name: 'a', filePath: '/x/project/a.ts', startLine: 1})
-      CREATE (decisionA:Entity {text: 'PROJECT A DECISION', type: 'Decision'})
+      CREATE (fileA:File {id: 'file:v1:project-a', name: 'a.ts', filePath: '/x/project/a.ts'})
+      CREATE (functionA:Function {id: 'sym:v1:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee', name: 'a', filePath: '/x/project/a.ts', startLine: 1})
+      CREATE (decisionA:Entity {id: 'entity:v1:project-a-decision', text: 'PROJECT A DECISION', type: 'Decision'})
       CREATE (projectA)-[:HAS_FILE]->(fileA)
       CREATE (fileA)-[:CONTAINS]->(functionA)
       CREATE (decisionA)-[:ABOUT]->(functionA)
 
       CREATE (projectB:Project {id: 'project-b', rootPath: '/x/other'})
-      CREATE (fileB:File {name: 'b.ts', filePath: '/x/other/b.ts'})
-      CREATE (functionB:Function {name: 'b', filePath: '/x/other/b.ts', startLine: 1})
-      CREATE (decisionB:Entity {text: 'PROJECT B DECISION', type: 'Decision'})
-      CREATE (personB:Entity {text: 'PROJECT B PERSON', type: 'Person'})
+      CREATE (fileB:File {id: 'file:v1:project-b', name: 'b.ts', filePath: '/x/other/b.ts'})
+      CREATE (functionB:Function {id: 'sym:v1:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff', name: 'b', filePath: '/x/other/b.ts', startLine: 1})
+      CREATE (decisionB:Entity {id: 'entity:v1:project-b-decision', text: 'PROJECT B DECISION', type: 'Decision'})
+      CREATE (personB:Entity {id: 'entity:v1:project-b-person', text: 'PROJECT B PERSON', type: 'Person'})
       CREATE (projectB)-[:HAS_FILE]->(fileB)
       CREATE (fileB)-[:CONTAINS]->(functionB)
       CREATE (decisionB)-[:ABOUT]->(functionB)
       CREATE (personB)-[:RELATES_TO]->(decisionB)
 
-      CREATE (boundaryFile:File {name: 'extra.ts', filePath: '/x/project-extra/extra.ts'})
+      CREATE (boundaryFile:File {id: 'file:v1:boundary', name: 'extra.ts', filePath: '/x/project-extra/extra.ts'})
       CREATE (boundaryFunction:Function {
+        id: 'sym:v1:9999999999999999999999999999999999999999999999999999999999999999',
         name: 'extra', filePath: '/x/project-extra/extra.ts', startLine: 1
       })
-      CREATE (boundaryDecision:Entity {text: 'PROJECT EXTRA DECISION', type: 'Decision'})
+      CREATE (boundaryDecision:Entity {id: 'entity:v1:boundary-decision', text: 'PROJECT EXTRA DECISION', type: 'Decision'})
       CREATE (boundaryFile)-[:CONTAINS]->(boundaryFunction)
       CREATE (boundaryDecision)-[:ABOUT]->(boundaryFunction)
     `);
diff --git a/packages/graph/src/__tests__/legacy-entity-identity.integration.test.ts b/packages/graph/src/__tests__/legacy-entity-identity.integration.test.ts
new file mode 100644
index 00000000..576e3845
--- /dev/null
+++ b/packages/graph/src/__tests__/legacy-entity-identity.integration.test.ts
@@ -0,0 +1,91 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createClient, type GraphClient } from '../client';
+import { createKnowledgeOperations, type KnowledgeOperations } from '../knowledge-operations';
+import { createQueries, type GraphQueries } from '../queries';
+import { resolveEmbeddedBinaryPaths } from '../drivers/falkordblite';
+
+const describeIfAvailable = resolveEmbeddedBinaryPaths() ? describe : describe.skip;
+
+describeIfAvailable('legacy Entity identity compatibility', () => {
+  let client: GraphClient;
+  let knowledge: KnowledgeOperations;
+  let queries: GraphQueries;
+  let dataDir: string;
+
+  beforeAll(async () => {
+    dataDir = await mkdtemp(join(tmpdir(), 'cg-legacy-entity-'));
+    client = await createClient({
+      driver: 'falkordblite',
+      databasePath: dataDir,
+      graphName: 'legacy_entity_identity',
+    } as never);
+    knowledge = createKnowledgeOperations(client);
+    queries = createQueries(client);
+  }, 60_000);
+
+  afterAll(async () => {
+    await client?.close();
+    if (dataDir) await rm(dataDir, { recursive: true, force: true });
+  });
+
+  it('derives the deterministic id when a full-graph Entity row has no persisted id', async () => {
+    await client.query(
+      'CREATE (:Entity {text: $text, type: $type})',
+      { params: { text: 'Legacy retry policy', type: 'Decision' } },
+    );
+
+    const graph = await queries.getFullGraph(10);
+
+    expect(graph.nodes).toContainEqual(expect.objectContaining({
+      id: 'Entity:Decision:Legacy retry policy',
+      label: 'Entity',
+      displayName: 'Legacy retry policy',
+    }));
+  });
+
+  it('backfills that deterministic id when an upsert matches an idless legacy Entity', async () => {
+    await client.query(
+      'CREATE (:Entity {text: $text, type: $type})',
+      { params: { text: 'Legacy deployment rule', type: 'Decision' } },
+    );
+
+    const returnedId = await knowledge.createEntity({
+      text: 'Legacy deployment rule',
+      type: 'Decision',
+    });
+    const persisted = await client.roQuery<{ id: string }>(
+      'MATCH (entity:Entity {text: $text, type: $type}) RETURN entity.id AS id',
+      { params: { text: 'Legacy deployment rule', type: 'Decision' } },
+    );
+
+    expect(returnedId).toBe('Entity:Decision:Legacy deployment rule');
+    expect(persisted.data).toEqual([{ id: 'Entity:Decision:Legacy deployment rule' }]);
+  });
+
+  it('preserves the existing deterministic fallback for a legacy File row', async () => {
+    await client.query(
+      'CREATE (:File {name: $name, filePath: $filePath})',
+      { params: { name: 'legacy.ts', filePath: '/legacy/legacy.ts' } },
+    );
+
+    const graph = await queries.getFullGraph(10);
+
+    expect(graph.nodes).toContainEqual(expect.objectContaining({
+      id: 'File:/legacy/legacy.ts',
+      label: 'File',
+      displayName: 'legacy.ts',
+    }));
+  });
+
+  it('still rejects an idless source-symbol row', async () => {
+    await client.query(
+      'CREATE (:Function {name: $name, filePath: $filePath, startLine: 1})',
+      { params: { name: 'legacySource', filePath: '/legacy/source.ts' } },
+    );
+
+    await expect(queries.getFullGraph(10)).rejects.toThrow('Graph node is missing a persisted id');
+  });
+});
diff --git a/packages/graph/src/__tests__/node-identity.integration.test.ts b/packages/graph/src/__tests__/node-identity.integration.test.ts
new file mode 100644
index 00000000..3e7e3f1c
--- /dev/null
+++ b/packages/graph/src/__tests__/node-identity.integration.test.ts
@@ -0,0 +1,465 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import type {
+  ClassEntity,
+  ComponentEntity,
+  ExtractedDocumentEntities,
+  FileEntity,
+  FunctionEntity,
+  InterfaceEntity,
+  ParsedFileEntities,
+  ProjectEntity,
+  TypeEntity,
+  VariableEntity,
+} from '@codegraph/types';
+import { createClient, resolveEmbeddedBinaryPaths, type GraphClient } from '../index';
+import { createOperations, type GraphOperations } from '../operations';
+
+const describeIfAvailable = resolveEmbeddedBinaryPaths() ? describe : describe.skip;
+const PROJECT_ID = 'project-node-identity';
+const PROJECT_ROOT = '/project';
+
+function symbolId(hex: string): string {
+  return `sym:v1:${hex.repeat(64)}`;
+}
+
+function makeProject(): ProjectEntity {
+  return {
+    id: PROJECT_ID,
+    name: 'project',
+    rootPath: PROJECT_ROOT,
+    createdAt: '2026-08-21T00:00:00.000Z',
+    lastParsed: '2026-08-21T00:00:00.000Z',
+    fileCount: 0,
+  };
+}
+
+function makeFile(path: string): FileEntity {
+  return {
+    path,
+    name: path.split('/').at(-1) ?? path,
+    extension: path.split('.').at(-1) ?? '',
+    loc: 20,
+    lastModified: '2026-08-21T00:00:00.000Z',
+    hash: `hash:${path}`,
+  };
+}
+
+function makeFunction(id: string, filePath: string, name: string, startLine: number, scopeKey = ''): FunctionEntity {
+  return {
+    id,
+    scopeKey,
+    disambiguator: '',
+    name,
+    filePath,
+    startLine,
+    endLine: startLine + 2,
+    isExported: true,
+    isAsync: false,
+    isArrow: false,
+    params: [],
+  };
+}
+
+function emptyParsed(path: string): ParsedFileEntities {
+  return {
+    file: makeFile(path),
+    functions: [],
+    classes: [],
+    interfaces: [],
+    variables: [],
+    types: [],
+    components: [],
+    imports: [],
+    callEdges: [],
+    importsEdges: [],
+    extendsEdges: [],
+    implementsEdges: [],
+    rendersEdges: [],
+    hasMethodEdges: [],
+    hasPropertyEdges: [],
+    typeRefs: [],
+    hasParamEdges: [],
+    returnsEdges: [],
+    usesTypeEdges: [],
+    exportsEdges: [],
+    importsSymbolEdges: [],
+  };
+}
+
+async function upsertOwnedFile(
+  ops: GraphOperations,
+  entities: ParsedFileEntities,
+  mode: 'single' | 'bulk' | 'fast' = 'bulk',
+): Promise<void> {
+  if (mode === 'single') await ops.batchUpsert(entities);
+  if (mode === 'bulk') await ops.batchUpsertBulk([entities]);
+  if (mode === 'fast') await ops.batchCreateBulk([entities]);
+  await ops.linkProjectFile(PROJECT_ID, entities.file.path);
+}
+
+describeIfAvailable('canonical source identity and project ownership', () => {
+  let client: GraphClient;
+  let ops: GraphOperations;
+  let dataDir: string;
+
+  beforeAll(async () => {
+    dataDir = await mkdtemp(join(tmpdir(), 'cg-node-identity-'));
+    client = await createClient({
+      driver: 'falkordblite',
+      databasePath: dataDir,
+      graphName: `node_identity_${Date.now()}`,
+    });
+    await client.ensureIndexes({ embeddingDim: 8 });
+    ops = createOperations(client);
+  }, 30_000);
+
+  beforeEach(async () => {
+    await client.query('MATCH (n) DETACH DELETE n', { params: {} });
+    await ops.upsertProject(makeProject());
+  });
+
+  afterAll(async () => {
+    if (client) await client.close();
+    if (dataDir) await rm(dataDir, { recursive: true, force: true });
+  }, 15_000);
+
+  it.each(['single', 'bulk'] as const)('%s upsert preserves one node and its inbound edge across a pure line shift', async (mode) => {
+    const callerPath = `${PROJECT_ROOT}/caller-${mode}.ts`;
+    const targetPath = `${PROJECT_ROOT}/target-${mode}.ts`;
+    const callerId = symbolId('a');
+    const targetId = symbolId('b');
+    const caller = emptyParsed(callerPath);
+    caller.functions = [makeFunction(callerId, callerPath, 'caller', 1)];
+    const target = emptyParsed(targetPath);
+    target.functions = [makeFunction(targetId, targetPath, 'target', 5)];
+
+    await upsertOwnedFile(ops, caller, mode);
+    await upsertOwnedFile(ops, target, mode);
+    await client.query(
+      'MATCH (caller:Function {id: $callerId}), (target:Function {id: $targetId}) CREATE (caller)-[:CALLS]->(target)',
+      { params: { callerId, targetId } },
+    );
+    const before = await client.roQuery<{ internalId: number }>(
+      'MATCH (target:Function {id: $targetId}) RETURN id(target) AS internalId',
+      { params: { targetId } },
+    );
+
+    await ops.removeFileContents(targetPath);
+    target.functions = [makeFunction(targetId, targetPath, 'target', 25)];
+    await upsertOwnedFile(ops, target, mode);
+
+    const after = await client.roQuery<{ internalId: number; startLine: number; calls: number }>(
+      `MATCH (target:Function {id: $targetId})
+       OPTIONAL MATCH (:Function {id: $callerId})-[call:CALLS]->(target)
+       RETURN id(target) AS internalId, target.startLine AS startLine, count(call) AS calls`,
+      { params: { callerId, targetId } },
+    );
+    expect(after.data).toEqual([{ internalId: before.data[0]!.internalId, startLine: 25, calls: 1 }]);
+  });
+
+  it('matches edge descriptor endpoints by canonical id', async () => {
+    const filePath = `${PROJECT_ROOT}/edges.ts`;
+    const callerId = symbolId('c');
+    const calleeId = symbolId('d');
+    const parsed = emptyParsed(filePath);
+    parsed.functions = [
+      makeFunction(callerId, filePath, 'sameName', 1, 'Class:One'),
+      makeFunction(calleeId, filePath, 'sameName', 10, 'Class:Two'),
+    ];
+    parsed.callEdges = [{ callerId, calleeId, line: 3, callerKind: 'Function', via: 'direct' }];
+
+    await upsertOwnedFile(ops, parsed);
+
+    const result = await client.roQuery<{ fromId: string; toId: string }>(
+      'MATCH (a)-[:CALLS]->(b) RETURN a.id AS fromId, b.id AS toId',
+    );
+    expect(result.data).toEqual([{ fromId: callerId, toId: calleeId }]);
+  });
+
+  it('uses canonical endpoints for inheritance, render, export, and imported-symbol descriptors', async () => {
+    const declarationsPath = `${PROJECT_ROOT}/descriptor-targets.tsx`;
+    const importerPath = `${PROJECT_ROOT}/descriptor-importer.ts`;
+    const parentId = symbolId('0');
+    const childId = symbolId('1');
+    const interfaceId = symbolId('2');
+    const parentComponentId = symbolId('3');
+    const childComponentId = symbolId('4');
+    const exportedId = symbolId('5');
+    const declarations = emptyParsed(declarationsPath);
+    const identity = (id: string) => ({ id, scopeKey: '', disambiguator: '' });
+    declarations.classes = [
+      { ...identity(parentId), name: 'Parent', filePath: declarationsPath, startLine: 1, endLine: 2, isExported: true, isAbstract: false },
+      { ...identity(childId), name: 'Child', filePath: declarationsPath, startLine: 3, endLine: 4, isExported: true, isAbstract: false },
+    ];
+    declarations.interfaces = [
+      { ...identity(interfaceId), name: 'Contract', filePath: declarationsPath, startLine: 5, endLine: 6, isExported: true },
+    ];
+    declarations.components = [
+      { ...identity(parentComponentId), name: 'View', filePath: declarationsPath, startLine: 7, endLine: 8, isExported: true },
+      { ...identity(childComponentId), name: 'View', filePath: declarationsPath, startLine: 9, endLine: 10, isExported: true },
+    ];
+    declarations.functions = [
+      makeFunction(exportedId, declarationsPath, 'shared', 11, 'Class:Chosen'),
+      makeFunction(symbolId('6'), declarationsPath, 'shared', 15, 'Class:Other'),
+    ];
+    declarations.extendsEdges = [{ childId, parentId }];
+    declarations.implementsEdges = [{ classId: childId, interfaceId }];
+    declarations.rendersEdges = [{ parentId: parentComponentId, childId: childComponentId, line: 8 }];
+    declarations.exportsEdges = [{
+      fromId: `File:${declarationsPath}`,
+      toId: exportedId,
+      filePath: declarationsPath,
+      symbolName: 'shared',
+      symbolKind: 'Function',
+    }];
+    const importer = emptyParsed(importerPath);
+    importer.importsSymbolEdges = [{
+      fromId: `File:${importerPath}`,
+      toId: exportedId,
+      fromFilePath: importerPath,
+      toFilePath: declarationsPath,
+      symbolName: 'shared',
+      isDefault: false,
+    }];
+
+    await ops.batchUpsertBulk([declarations, importer]);
+
+    const result = await client.roQuery<{ type: string; fromId: string; toId: string }>(
+      `MATCH (from)-[r]->(to)
+       WHERE type(r) IN ['EXTENDS', 'IMPLEMENTS', 'RENDERS', 'EXPORTS', 'IMPORTS_SYMBOL']
+       RETURN type(r) AS type, from.id AS fromId, to.id AS toId
+       ORDER BY type`,
+    );
+    expect(result.data).toEqual([
+      { type: 'EXPORTS', fromId: `File:${declarationsPath}`, toId: exportedId },
+      { type: 'EXTENDS', fromId: childId, toId: parentId },
+      { type: 'IMPLEMENTS', fromId: childId, toId: interfaceId },
+      { type: 'IMPORTS_SYMBOL', fromId: `File:${importerPath}`, toId: exportedId },
+      { type: 'RENDERS', fromId: parentComponentId, toId: childComponentId },
+    ]);
+  });
+
+  it('matches single and batch embedding writes by canonical id', async () => {
+    const filePath = `${PROJECT_ROOT}/embeddings.ts`;
+    const firstId = symbolId('e');
+    const secondId = symbolId('f');
+    const parsed = emptyParsed(filePath);
+    parsed.functions = [
+      makeFunction(firstId, filePath, 'duplicate', 1, 'Class:First'),
+      makeFunction(secondId, filePath, 'duplicate', 5, 'Class:Second'),
+    ];
+    await upsertOwnedFile(ops, parsed);
+
+    await ops.updateEmbedding('Function', { id: firstId }, [1, 0], 'first-hash');
+    await ops.batchUpdateEmbeddings([{
+      nodeType: 'Function',
+      identifier: { id: secondId },
+      embedding: [0, 1],
+      embeddingTextHash: 'second-hash',
+    }]);
+
+    const result = await client.roQuery<{ id: string; hash: string }>(
+      `MATCH (fn:Function {filePath: $filePath})
+       RETURN fn.id AS id, fn.embeddingTextHash AS hash
+       ORDER BY id`,
+      { params: { filePath } },
+    );
+    expect(result.data).toEqual([
+      { id: firstId, hash: 'first-hash' },
+      { id: secondId, hash: 'second-hash' },
+    ]);
+  });
+
+  it('detach-deletes a deleted or renamed symbol after the current-id upsert', async () => {
+    const filePath = `${PROJECT_ROOT}/rename.ts`;
+    const oldId = symbolId('1');
+    const newId = symbolId('2');
+    const parsed = emptyParsed(filePath);
+    parsed.functions = [makeFunction(oldId, filePath, 'before', 1)];
+    await upsertOwnedFile(ops, parsed);
+    await client.query(
+      'MATCH (target:Function {id: $oldId}) CREATE (:Entity {name: "inbound"})-[:ABOUT]->(target)',
+      { params: { oldId } },
+    );
+    await client.query(
+      'MATCH (:File {filePath: $filePath})-[contains:CONTAINS]->(:Function {id: $oldId}) DELETE contains',
+      { params: { filePath, oldId } },
+    );
+
+    await ops.removeFileContents(filePath);
+    parsed.functions = [makeFunction(newId, filePath, 'after', 1)];
+    await upsertOwnedFile(ops, parsed);
+
+    const result = await client.roQuery<{ ids: string[] }>(
+      'MATCH (n:Function {filePath: $filePath}) RETURN collect(n.id) AS ids',
+      { params: { filePath } },
+    );
+    expect(result.data[0]!.ids).toEqual([newId]);
+  });
+
+  it('keeps same-name members in two classes as distinct nodes on the fast path', async () => {
+    const filePath = `${PROJECT_ROOT}/members.ts`;
+    const firstId = symbolId('3');
+    const secondId = symbolId('4');
+    const parsed = emptyParsed(filePath);
+    parsed.functions = [
+      makeFunction(firstId, filePath, 'work', 2, 'Class:First'),
+      makeFunction(secondId, filePath, 'work', 8, 'Class:Second'),
+    ];
+
+    await upsertOwnedFile(ops, parsed, 'fast');
+
+    const result = await client.roQuery<{ ids: string[]; scopes: string[] }>(
+      `MATCH (fn:Function {filePath: $filePath, name: 'work'})
+       RETURN collect(fn.id) AS ids, collect(fn.scopeKey) AS scopes`,
+      { params: { filePath } },
+    );
+    expect(new Set(result.data[0]!.ids)).toEqual(new Set([firstId, secondId]));
+    expect(new Set(result.data[0]!.scopes)).toEqual(new Set(['Class:First', 'Class:Second']));
+  });
+
+  it('real file deletion detach-deletes every source node even with inbound edges', async () => {
+    const filePath = `${PROJECT_ROOT}/deleted.ts`;
+    const targetId = symbolId('5');
+    const parsed = emptyParsed(filePath);
+    parsed.functions = [makeFunction(targetId, filePath, 'deleted', 1)];
+    await upsertOwnedFile(ops, parsed);
+    await client.query(
+      'MATCH (target:Function {id: $targetId}) CREATE (:Entity {name: "inbound"})-[:ABOUT]->(target)',
+      { params: { targetId } },
+    );
+
+    await ops.removeFileAndCleanup(filePath);
+
+    const result = await client.roQuery<{ count: number }>(
+      `MATCH (n) WHERE n.filePath = $filePath AND
+       (n:Function OR n:Class OR n:Interface OR n:Variable OR n:Type OR n:Component)
+       RETURN count(n) AS count`,
+      { params: { filePath } },
+    );
+    expect(result.data[0]!.count).toBe(0);
+  });
+
+  it('force project deletion removes prior source and markdown generations', async () => {
+    const filePath = `${PROJECT_ROOT}/old.ts`;
+    const parsed = emptyParsed(filePath);
+    parsed.functions = [makeFunction(symbolId('6'), filePath, 'old', 1)];
+    await upsertOwnedFile(ops, parsed);
+
+    const documentPath = `${PROJECT_ROOT}/README.md`;
+    const docs: ExtractedDocumentEntities = {
+      document: {
+        path: documentPath,
+        name: 'README.md',
+        title: 'Old',
+        frontmatter: {},
+        hash: 'old-doc',
+        lastModified: '2026-08-21T00:00:00.000Z',
+      },
+      sections: [{ heading: 'Old', level: 1, filePath: documentPath, startLine: 1, endLine: 4 }],
+      codeBlocks: [{ language: 'ts', content: 'old()', filePath: documentPath, startLine: 2, endLine: 3 }],
+      links: [{ text: 'old', target: './old.md', isInternal: true, filePath: documentPath, line: 4 }],
+      sectionHierarchy: [],
+    };
+    await ops.batchUpsertDocuments([docs]);
+    const ownedBefore = await client.roQuery<{ count: number }>(
+      'MATCH (n {projectId: $projectId}) RETURN count(n) AS count',
+      { params: { projectId: PROJECT_ID } },
+    );
+    expect(ownedBefore.data[0]!.count).toBe(7);
+    await client.query('MATCH (n {projectId: $projectId}) SET n.indexGeneration = "old"', { params: { projectId: PROJECT_ID } });
+
+    await ops.deleteProject(PROJECT_ID);
+
+    const result = await client.roQuery<{ survivors: number }>(
+      'MATCH (n {projectId: $projectId, indexGeneration: "old"}) RETURN count(n) AS survivors',
+      { params: { projectId: PROJECT_ID } },
+    );
+    expect(result.data[0]!.survivors).toBe(0);
+    await ops.upsertProject(makeProject());
+    await ops.batchUpsertDocuments([{
+      ...docs,
+      document: { ...docs.document, title: 'New', hash: 'new-doc' },
+      sections: [{ heading: 'New', level: 1, filePath: documentPath, startLine: 1, endLine: 1 }],
+      codeBlocks: [],
+      links: [],
+    }]);
+    const vanishedMarkdown = await client.roQuery<{ count: number }>(
+      `MATCH (n)
+       WHERE (n:Section AND n.heading = 'Old') OR n:CodeBlock OR n:Link
+       RETURN count(n) AS count`,
+    );
+    expect(vanishedMarkdown.data[0]!.count).toBe(0);
+  });
+
+  it('the three acceptance queries return zero after reconciliation', async () => {
+    const filePath = `${PROJECT_ROOT}/acceptance.ts`;
+    const parsed = emptyParsed(filePath);
+    parsed.functions = [makeFunction(symbolId('7'), filePath, 'accepted', 1)];
+    await upsertOwnedFile(ops, parsed);
+
+    const detached = await client.roQuery<{ count: number }>(
+      `MATCH (n)
+       WHERE n.projectId = $projectId AND
+         (n:Function OR n:Class OR n:Interface OR n:Variable OR n:Type OR n:Component)
+       OPTIONAL MATCH (f:File)-[:CONTAINS]->(n)
+       WITH n, f WHERE f IS NULL
+       RETURN count(n) AS count`,
+      { params: { projectId: PROJECT_ID } },
+    );
+    const duplicates = await client.roQuery<{ count: number }>(
+      `MATCH (n)
+       WHERE n.projectId = $projectId AND
+         (n:Function OR n:Class OR n:Interface OR n:Variable OR n:Type OR n:Component)
+       WITH labels(n)[0] AS label, n.id AS id, count(*) AS copies
+       WHERE copies > 1
+       RETURN count(*) AS count`,
+      { params: { projectId: PROJECT_ID } },
+    );
+    const oldGeneration = await client.roQuery<{ count: number }>(
+      'MATCH (n {projectId: $projectId, indexGeneration: "old"}) RETURN count(n) AS count',
+      { params: { projectId: PROJECT_ID } },
+    );
+    expect(detached.data[0]!.count).toBe(0);
+    expect(duplicates.data[0]!.count).toBe(0);
+    expect(oldGeneration.data[0]!.count).toBe(0);
+  });
+
+  it.each(['single', 'bulk', 'fast'] as const)('%s writes persist identity fields for all six source labels', async (mode) => {
+    const filePath = `${PROJECT_ROOT}/six.tsx`;
+    const identity = (id: string, scopeKey = '') => ({ id, scopeKey, disambiguator: '' });
+    const parsed = emptyParsed(filePath);
+    parsed.functions = [makeFunction(symbolId('8'), filePath, 'fn', 1)];
+    parsed.classes = [{ ...identity(symbolId('9')), name: 'Cls', filePath, startLine: 4, endLine: 5, isExported: true, isAbstract: false } satisfies ClassEntity];
+    parsed.interfaces = [{ ...identity(symbolId('a'), 'Namespace:X'), name: 'Iface', filePath, startLine: 6, endLine: 7, isExported: true } satisfies InterfaceEntity];
+    parsed.variables = [{ ...identity(symbolId('b')), name: 'value', filePath, line: 8, kind: 'const', isExported: true } satisfies VariableEntity];
+    parsed.types = [{ ...identity(symbolId('c')), name: 'Alias', filePath, startLine: 9, endLine: 9, isExported: true, kind: 'type' } satisfies TypeEntity];
+    parsed.components = [{ ...identity(symbolId('d')), name: 'View', filePath, startLine: 10, endLine: 12, isExported: true } satisfies ComponentEntity];
+
+    await upsertOwnedFile(ops, parsed, mode);
+
+    const result = await client.roQuery<{ count: number }>(
+      `MATCH (n {filePath: $filePath})
+       WHERE n:Function OR n:Class OR n:Interface OR n:Variable OR n:Type OR n:Component
+       WITH n WHERE n.id IS NOT NULL AND n.scopeKey IS NOT NULL AND n.disambiguator IS NOT NULL
+       RETURN count(n) AS count`,
+      { params: { filePath } },
+    );
+    expect(result.data[0]!.count).toBe(6);
+  });
+
+  it('creates exact-match id indexes for all six source labels', async () => {
+    const result = await client.roQuery<{ label: string; properties: string[] }>(
+      `CALL db.indexes()
+       YIELD label, properties
+       WHERE label IN ['Function', 'Class', 'Interface', 'Variable', 'Type', 'Component'] AND 'id' IN properties
+       RETURN label, properties`,
+    );
+    expect(new Set(result.data.map((row) => row.label))).toEqual(
+      new Set(['Function', 'Class', 'Interface', 'Variable', 'Type', 'Component']),
+    );
+  });
+});
diff --git a/packages/graph/src/__tests__/remove-file-contents.test.ts b/packages/graph/src/__tests__/remove-file-contents.test.ts
index 23cf074b..b93c3307 100644
--- a/packages/graph/src/__tests__/remove-file-contents.test.ts
+++ b/packages/graph/src/__tests__/remove-file-contents.test.ts
@@ -66,15 +66,15 @@ describeIfAvailable('removeFileContents vs removeFileAndCleanup', () => {
     }
   }, 15_000);
 
-  it('removeFileContents() clears CONTAINS/orphans but leaves the File node and its other edges intact', async () => {
+  it('removeFileContents() stages a stale-id sweep while preserving the File and stable inbound edges', async () => {
     await client.query(`
       CREATE (p:Project {id: 'proj1', name: 'test', rootPath: '/repo', createdAt: '2025-01-01T00:00:00Z', lastParsed: '2025-01-01T00:00:00Z', fileCount: 1})
       CREATE (f:File {filePath: '/repo/foo.ts', name: 'foo.ts', extension: 'ts', loc: 10, lastModified: '2025-01-01T00:00:00Z', hash: 'oldhash'})
       CREATE (c:Commit {hash: 'commitA', message: 'a', author: 'x', email: 'x@x.com', date: '2025-01-01T00:00:00Z'})
       CREATE (p)-[:HAS_FILE]->(f)
       CREATE (f)-[:MODIFIED_IN]->(c)
-      CREATE (kept:Function {name: 'kept', filePath: '/repo/foo.ts', startLine: 1, endLine: 2, isExported: true, isAsync: false, isArrow: false, params: []})
-      CREATE (dropped:Function {name: 'dropped', filePath: '/repo/foo.ts', startLine: 5, endLine: 6, isExported: true, isAsync: false, isArrow: false, params: []})
+      CREATE (kept:Function {id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', scopeKey: '', disambiguator: '', name: 'kept', filePath: '/repo/foo.ts', startLine: 1, endLine: 2, isExported: true, isAsync: false, isArrow: false, params: []})
+      CREATE (dropped:Function {id: 'sym:v1:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb', scopeKey: '', disambiguator: '', name: 'dropped', filePath: '/repo/foo.ts', startLine: 5, endLine: 6, isExported: true, isAsync: false, isArrow: false, params: []})
       CREATE (f)-[:CONTAINS]->(kept)
       CREATE (f)-[:CONTAINS]->(dropped)
       CREATE (other:File {filePath: '/repo/other.ts', name: 'other.ts', extension: 'ts', loc: 5, lastModified: '2025-01-01T00:00:00Z', hash: 'h2'})
@@ -103,25 +103,43 @@ describeIfAvailable('removeFileContents vs removeFileAndCleanup', () => {
     );
     expect(hasFile.data).toHaveLength(1);
 
-    // CONTAINS edges from this file must be gone.
+    // Ownership stays attached until the current-ID upsert finishes.
     const contains = await client.roQuery<{ n: number }>(
       `MATCH (:File {filePath: '/repo/foo.ts'})-[:CONTAINS]->() RETURN count(*) AS n`,
     );
-    expect(contains.data[0]?.n).toBe(0);
+    expect(contains.data[0]?.n).toBe(2);
+
+    // The stable inbound edge remains present during the refresh window.
+    const keptRows = await client.roQuery(
+      `MATCH (:Function {name: 'caller', filePath: '/repo/other.ts'})-[:CALLS]->(fn:Function {name: 'kept', filePath: '/repo/foo.ts'}) RETURN fn`,
+    );
+    expect(keptRows.data).toHaveLength(1);
+
+    await ops.batchUpsert({
+      file: {
+        path: '/repo/foo.ts', name: 'foo.ts', extension: 'ts', loc: 12,
+        lastModified: '2025-01-02T00:00:00Z', hash: 'newhash',
+      },
+      functions: [{
+        id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+        scopeKey: '', disambiguator: '', name: 'kept', filePath: '/repo/foo.ts',
+        startLine: 10, endLine: 11, isExported: true, isAsync: false, isArrow: false, params: [],
+      }],
+      classes: [], interfaces: [], variables: [], types: [], components: [], imports: [],
+      callEdges: [], importsEdges: [], extendsEdges: [], implementsEdges: [], rendersEdges: [],
+      hasMethodEdges: [], hasPropertyEdges: [], typeRefs: [], hasParamEdges: [], returnsEdges: [],
+      usesTypeEdges: [], exportsEdges: [], importsSymbolEdges: [],
+    });
 
-    // 'dropped' had no incoming cross-file edge, so it is genuinely orphaned
-    // once CONTAINS is gone, and gets cleaned up (same as removeFileAndCleanup()).
     const droppedRows = await client.roQuery(
       `MATCH (fn:Function {name: 'dropped', filePath: '/repo/foo.ts'}) RETURN fn`,
     );
     expect(droppedRows.data).toHaveLength(0);
-
-    // 'kept' is referenced from another file's CALLS edge, so it (and that
-    // edge) must be preserved instead of leaking a dangling reference.
-    const keptRows = await client.roQuery(
-      `MATCH (:Function {name: 'caller', filePath: '/repo/other.ts'})-[:CALLS]->(fn:Function {name: 'kept', filePath: '/repo/foo.ts'}) RETURN fn`,
+    const shifted = await client.roQuery<{ startLine: number }>(
+      `MATCH (:Function {name: 'caller', filePath: '/repo/other.ts'})-[:CALLS]->(fn:Function {id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})
+       RETURN fn.startLine AS startLine`,
     );
-    expect(keptRows.data).toHaveLength(1);
+    expect(shifted.data).toEqual([{ startLine: 10 }]);
   });
 
   it('removeFileAndCleanup() still fully removes the File node and its symbols (true deletion path)', async () => {
diff --git a/packages/graph/src/__tests__/symbol-references.integration.test.ts b/packages/graph/src/__tests__/symbol-references.integration.test.ts
index 0e347cdc..5d4f3991 100644
--- a/packages/graph/src/__tests__/symbol-references.integration.test.ts
+++ b/packages/graph/src/__tests__/symbol-references.integration.test.ts
@@ -37,11 +37,11 @@ describeIfAvailable('getSymbolReferences', () => {
       CREATE (lib:File {filePath: '/x/lib.ts', name: 'lib.ts'})
       CREATE (a:File {filePath: '/x/a.ts', name: 'a.ts'})
       CREATE (b:File {filePath: '/x/b.ts', name: 'b.ts'})
-      CREATE (target:Function {name: 'parseInput', filePath: '/x/lib.ts', startLine: 10})
-      CREATE (localCaller:Function {name: 'helper', filePath: '/x/lib.ts', startLine: 40})
-      CREATE (remoteCaller:Function {name: 'handler', filePath: '/x/a.ts', startLine: 5})
-      CREATE (subclass:Class {name: 'Derived', filePath: '/x/b.ts', startLine: 3})
-      CREATE (unrelated:Function {name: 'elsewhere', filePath: '/x/b.ts', startLine: 60})
+      CREATE (target:Function {id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', name: 'parseInput', filePath: '/x/lib.ts', startLine: 10})
+      CREATE (localCaller:Function {id: 'sym:v1:1111111111111111111111111111111111111111111111111111111111111111', name: 'helper', filePath: '/x/lib.ts', startLine: 40})
+      CREATE (remoteCaller:Function {id: 'sym:v1:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb', name: 'handler', filePath: '/x/a.ts', startLine: 5})
+      CREATE (subclass:Class {id: 'sym:v1:2222222222222222222222222222222222222222222222222222222222222222', name: 'Derived', filePath: '/x/b.ts', startLine: 3})
+      CREATE (unrelated:Function {id: 'sym:v1:3333333333333333333333333333333333333333333333333333333333333333', name: 'elsewhere', filePath: '/x/b.ts', startLine: 60})
       CREATE (lib)-[:CONTAINS]->(target)
       CREATE (lib)-[:CONTAINS]->(localCaller)
       CREATE (a)-[:CONTAINS]->(remoteCaller)
@@ -59,7 +59,7 @@ describeIfAvailable('getSymbolReferences', () => {
   });
 
   it('finds every kind of use, and says which are in other files', async () => {
-    const result = await queries.getSymbolReferences({ name: 'parseInput' });
+    const result = await queries.getSymbolReferences({ id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' });
 
     expect(result.references).toHaveLength(3);
     expect(new Set(result.references.map((r) => r.edgeType))).toEqual(new Set(['CALLS', 'EXTENDS']));
@@ -72,36 +72,45 @@ describeIfAvailable('getSymbolReferences', () => {
   });
 
   it('lists the other files a symbol is used from', async () => {
-    const result = await queries.getSymbolReferences({ name: 'parseInput' });
+    const result = await queries.getSymbolReferences({ id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' });
     expect(new Set(result.referencingFiles)).toEqual(new Set(['/x/a.ts', '/x/b.ts']));
   });
 
   it('carries the location needed to open the referencing code', async () => {
-    const result = await queries.getSymbolReferences({ name: 'parseInput' });
+    const result = await queries.getSymbolReferences({ id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' });
     const handler = result.references.find((r) => r.name === 'handler');
     expect(handler?.filePath).toBe('/x/a.ts');
     expect(handler?.startLine).toBe(5);
     expect(handler?.nodeType).toBe('Function');
   });
 
+  it('accepts a persisted target id and returns persisted source ids', async () => {
+    const result = await queries.getSymbolReferences({
+      id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+    });
+    const handler = result.references.find((reference) => reference.name === 'handler');
+
+    expect(handler?.id).toBe('sym:v1:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb');
+  });
+
   it('reports nothing for a symbol no one uses', async () => {
-    const result = await queries.getSymbolReferences({ name: 'elsewhere' });
+    const result = await queries.getSymbolReferences({ id: 'sym:v1:3333333333333333333333333333333333333333333333333333333333333333' });
     expect(result.references).toEqual([]);
     expect(result.referencingFiles).toEqual([]);
     expect(result.truncated).toBe(false);
   });
 
   it('reports nothing for a name that is not in the graph', async () => {
-    const result = await queries.getSymbolReferences({ name: 'noSuchSymbol' });
+    const result = await queries.getSymbolReferences({ id: 'sym:v1:0000000000000000000000000000000000000000000000000000000000000000' });
     expect(result.references).toEqual([]);
   });
 
   it('flags truncation instead of silently dropping results', async () => {
-    const limited = await queries.getSymbolReferences({ name: 'parseInput', limit: 2 });
+    const limited = await queries.getSymbolReferences({ id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', limit: 2 });
     expect(limited.references).toHaveLength(2);
     expect(limited.truncated).toBe(true);
 
-    const full = await queries.getSymbolReferences({ name: 'parseInput', limit: 50 });
+    const full = await queries.getSymbolReferences({ id: 'sym:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', limit: 50 });
     expect(full.truncated).toBe(false);
   });
 
@@ -109,82 +118,19 @@ describeIfAvailable('getSymbolReferences', () => {
     // A second parseInput elsewhere, with its own distinct caller.
     await client.query(`
       MATCH (b:File {filePath: '/x/b.ts'})
-      CREATE (other:Function {name: 'parseInput', filePath: '/x/b.ts', startLine: 90})
-      CREATE (caller:Function {name: 'onlyForB', filePath: '/x/b.ts', startLine: 95})
+      CREATE (other:Function {id: 'sym:v1:4444444444444444444444444444444444444444444444444444444444444444', name: 'parseInput', filePath: '/x/b.ts', startLine: 90})
+      CREATE (caller:Function {id: 'sym:v1:5555555555555555555555555555555555555555555555555555555555555555', name: 'onlyForB', filePath: '/x/b.ts', startLine: 95})
       CREATE (b)-[:CONTAINS]->(other)
       CREATE (b)-[:CONTAINS]->(caller)
       CREATE (caller)-[:CALLS]->(other)
     `);
 
     const scoped = await queries.getSymbolReferences({
-      name: 'parseInput',
-      filePath: '/x/b.ts',
-      startLine: 90,
+      id: 'sym:v1:4444444444444444444444444444444444444444444444444444444444444444',
     });
     expect(scoped.references.map((r) => r.name)).toEqual(['onlyForB']);
   });
 
-  it('finds a reference that only lands on a TypeRef proxy for the same name', async () => {
-    // Mirrors how the graph is actually built: a type name exists both as a
-    // declaration node with a real filePath (Interface/Class/Type/...) and as
-    // a separate TypeRef node with filePath left unset, and USES_TYPE edges
-    // terminate on the TypeRef, never the declaration. Pinning to a single
-    // node by name picks one or the other; if it happens to pick the
-    // declaration, the only real reference (through the TypeRef) is missed.
-    await client.query(`
-      CREATE (c:File {filePath: '/x/config.ts', name: 'config.ts'})
-      CREATE (decl:Interface {name: 'WidgetConfig', filePath: '/x/config.ts', startLine: 12})
-      CREATE (ref:TypeRef {name: 'WidgetConfig', language: 'typescript', isPrimitive: false})
-      CREATE (c)-[:CONTAINS]->(decl)
-      CREATE (maker:Function {name: 'makeWidget', filePath: '/x/c.ts', startLine: 8})
-      CREATE (maker)-[:USES_TYPE]->(ref)
-    `);
-
-    const result = await queries.getSymbolReferences({ name: 'WidgetConfig' });
-
-    expect(result.references.map((r) => r.name)).toEqual(['makeWidget']);
-    expect(result.references[0]?.edgeType).toBe('USES_TYPE');
-  });
-
-  it('still finds a TypeRef-only reference when filePath/startLine pin the declaration', async () => {
-    // The declaration node has a real filePath and startLine; the TypeRef
-    // node it shares a name with does not. A caller that supplies the
-    // declaration's own filePath/startLine (as the dashboard does when a node
-    // is selected) must not filter out the TypeRef's references just because
-    // the TypeRef itself has no location to match against.
-    const result = await queries.getSymbolReferences({
-      name: 'WidgetConfig',
-      filePath: '/x/config.ts',
-      startLine: 12,
-    });
-
-    expect(result.references.map((r) => r.name)).toEqual(['makeWidget']);
-  });
-
-  it('classifies a same-file TypeRef reference as same-file, not "other file"', async () => {
-    // The TypeRef node the USES_TYPE edge lands on has filePath = null, which
-    // is not the declaration's file. sameFile must be judged against the
-    // declaring file, not against whichever node the edge happened to land
-    // on, or a use in the very same file as the declaration gets classified
-    // as coming from elsewhere.
-    await client.query(`
-      CREATE (s:File {filePath: '/x/shapes.ts', name: 'shapes.ts'})
-      CREATE (decl:Interface {name: 'LocalShape', filePath: '/x/shapes.ts', startLine: 4})
-      CREATE (ref:TypeRef {name: 'LocalShape', language: 'typescript', isPrimitive: false})
-      CREATE (user:Function {name: 'sameFileUser', filePath: '/x/shapes.ts', startLine: 20})
-      CREATE (s)-[:CONTAINS]->(decl)
-      CREATE (s)-[:CONTAINS]->(user)
-      CREATE (user)-[:USES_TYPE]->(ref)
-    `);
-
-    const result = await queries.getSymbolReferences({ name: 'LocalShape' });
-
-    expect(result.references).toHaveLength(1);
-    expect(result.references[0]?.name).toBe('sameFileUser');
-    expect(result.references[0]?.sameFile).toBe(true);
-    expect(result.referencingFiles).toEqual([]);
-  });
-
   it('judges sameFile per reference when two genuine declarations share a name', async () => {
     // A name collision between two real declarations, each in its own file,
     // each with its own same-file caller. Every codebase has these (every
@@ -195,10 +141,10 @@ describeIfAvailable('getSymbolReferences', () => {
     await client.query(`
       CREATE (one:File {filePath: '/x/one.ts', name: 'one.ts'})
       CREATE (two:File {filePath: '/x/two.ts', name: 'two.ts'})
-      CREATE (closeOne:Function {name: 'close', filePath: '/x/one.ts', startLine: 5})
-      CREATE (closeTwo:Function {name: 'close', filePath: '/x/two.ts', startLine: 8})
-      CREATE (callerOne:Function {name: 'callerOne', filePath: '/x/one.ts', startLine: 20})
-      CREATE (callerTwo:Function {name: 'callerTwo', filePath: '/x/two.ts', startLine: 30})
+      CREATE (closeOne:Function {id: 'sym:v1:6666666666666666666666666666666666666666666666666666666666666666', name: 'close', filePath: '/x/one.ts', startLine: 5})
+      CREATE (closeTwo:Function {id: 'sym:v1:7777777777777777777777777777777777777777777777777777777777777777', name: 'close', filePath: '/x/two.ts', startLine: 8})
+      CREATE (callerOne:Function {id: 'sym:v1:8888888888888888888888888888888888888888888888888888888888888888', name: 'callerOne', filePath: '/x/one.ts', startLine: 20})
+      CREATE (callerTwo:Function {id: 'sym:v1:9999999999999999999999999999999999999999999999999999999999999999', name: 'callerTwo', filePath: '/x/two.ts', startLine: 30})
       CREATE (one)-[:CONTAINS]->(closeOne)
       CREATE (one)-[:CONTAINS]->(callerOne)
       CREATE (two)-[:CONTAINS]->(closeTwo)
@@ -207,46 +153,12 @@ describeIfAvailable('getSymbolReferences', () => {
       CREATE (callerTwo)-[:CALLS]->(closeTwo)
     `);
 
-    const result = await queries.getSymbolReferences({ name: 'close' });
-
-    expect(result.references).toHaveLength(2);
-    const byName = new Map(result.references.map((r) => [r.name, r]));
-    expect(byName.get('callerOne')?.sameFile).toBe(true);
-    expect(byName.get('callerTwo')?.sameFile).toBe(true);
-    expect(result.referencingFiles).toEqual([]);
-  });
-
-  it('does not guess a file for a proxy reference when two declarations share the name', async () => {
-    // Two genuine declarations of 'SharedType', each in its own file, plus a
-    // single TypeRef proxy for that name. A USES_TYPE edge from either file
-    // lands on the proxy, not on either declaration, so nothing in the graph
-    // says which of the two declarations a given proxy reference means.
-    // Falling back to "whichever declaration Cypher happened to return
-    // first" would get one of the two references right by luck and the
-    // other wrong: the same batch-wide misattribution bug in a new spot.
-    // Neither reference can be honestly classified as same-file from this
-    // data, so both must come back false rather than a guess.
-    await client.query(`
-      CREATE (m1:File {filePath: '/x/m1.ts', name: 'm1.ts'})
-      CREATE (m2:File {filePath: '/x/m2.ts', name: 'm2.ts'})
-      CREATE (declM1:Interface {name: 'SharedType', filePath: '/x/m1.ts', startLine: 3})
-      CREATE (declM2:Interface {name: 'SharedType', filePath: '/x/m2.ts', startLine: 7})
-      CREATE (proxy:TypeRef {name: 'SharedType', language: 'typescript', isPrimitive: false})
-      CREATE (userM1:Function {name: 'userM1', filePath: '/x/m1.ts', startLine: 20})
-      CREATE (userM2:Function {name: 'userM2', filePath: '/x/m2.ts', startLine: 25})
-      CREATE (m1)-[:CONTAINS]->(declM1)
-      CREATE (m1)-[:CONTAINS]->(userM1)
-      CREATE (m2)-[:CONTAINS]->(declM2)
-      CREATE (m2)-[:CONTAINS]->(userM2)
-      CREATE (userM1)-[:USES_TYPE]->(proxy)
-      CREATE (userM2)-[:USES_TYPE]->(proxy)
-    `);
-
-    const result = await queries.getSymbolReferences({ name: 'SharedType' });
+    const first = await queries.getSymbolReferences({ id: 'sym:v1:6666666666666666666666666666666666666666666666666666666666666666' });
+    const second = await queries.getSymbolReferences({ id: 'sym:v1:7777777777777777777777777777777777777777777777777777777777777777' });
 
-    expect(result.references).toHaveLength(2);
-    const byUser = new Map(result.references.map((r) => [r.name, r]));
-    expect(byUser.get('userM1')?.sameFile).toBe(false);
-    expect(byUser.get('userM2')?.sameFile).toBe(false);
+    expect(first.references.map((reference) => reference.name)).toEqual(['callerOne']);
+    expect(second.references.map((reference) => reference.name)).toEqual(['callerTwo']);
+    expect(first.references[0]?.sameFile).toBe(true);
+    expect(second.references[0]?.sameFile).toBe(true);
   });
 });
diff --git a/packages/graph/src/drivers/falkordb-shared.ts b/packages/graph/src/drivers/falkordb-shared.ts
index a19a06e6..ac5cda98 100644
--- a/packages/graph/src/drivers/falkordb-shared.ts
+++ b/packages/graph/src/drivers/falkordb-shared.ts
@@ -10,7 +10,7 @@ import { ConstraintType, EntityType } from 'falkordb';
 import type { QueryOptions as FalkorQueryOptions } from 'falkordb/dist/src/commands';
 import type { QueryParams } from '../client';
 import { createLogger } from '@codegraph/logger';
-import { ALL_GRAPH_LABELS, EMBEDDABLE_LABELS } from '@codegraph/types';
+import { ALL_GRAPH_LABELS, EMBEDDABLE_LABELS, SYMBOL_LABELS } from '@codegraph/types';
 
 const logger = createLogger({ namespace: 'graph:schema' });
 
@@ -102,6 +102,13 @@ export async function ensureSchemaImpl(
 
   // --- Range indexes (lookup by exact value) ---
   await safeIndex(`CREATE INDEX FOR (f:File) ON (f.filePath)`);
+  for (const label of SYMBOL_LABELS) {
+    if (label === 'File') continue;
+    await safeIndex(`CREATE INDEX FOR (n:${label}) ON (n.id)`);
+    await safeIndex(`CREATE INDEX FOR (n:${label}) ON (n.projectId)`);
+  }
+  await safeIndex(`CREATE INDEX FOR (f:File) ON (f.projectId)`);
+  await safeIndex(`CREATE INDEX FOR (d:MarkdownDocument) ON (d.projectId)`);
 
   // --- Commit & Metadata range indexes (git history / state tracking) ---
   await safeIndex(`CREATE INDEX FOR (c:Commit) ON (c.hash)`);
diff --git a/packages/graph/src/knowledge-operations.ts b/packages/graph/src/knowledge-operations.ts
index 715e9495..d1b62a0b 100644
--- a/packages/graph/src/knowledge-operations.ts
+++ b/packages/graph/src/knowledge-operations.ts
@@ -10,7 +10,7 @@
  * Key design decisions:
  * - Uses codebase-graph's GraphClient interface (driver-agnostic)
  * - Single RELATES_TO table with type property (Graphiti pattern)
- * - UUIDs generated in TypeScript
+ * - Deterministic default Entity ids derived from the Entity merge key
  * - Atomic upserts via MERGE (entities) and NOT EXISTS guard (relationships)
  * - Embedding vectors passed in from caller (inference layer handles generation)
  * - Bi-temporal fields on edges (valid_at, invalid_at, created_at, expired_at)
@@ -21,6 +21,10 @@ import { createLogger, trace, toErrorMessage } from '@codegraph/logger';
 
 const logger = createLogger({ namespace: 'graph:knowledge-operations' });
 
+export function deriveEntityId(text: string, type: string): string {
+  return `Entity:${type}:${text}`;
+}
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -343,6 +347,7 @@ const KG_CYPHER = {
       n.sampleIds = $sampleIds,
       n.properties = $properties
     ON MATCH SET
+      n.id = coalesce(n.id, $id),
       n.lastAccessedAt = $now,
       n.accessCount = n.accessCount + 1,
       n.relevanceScore = CASE
@@ -592,6 +597,7 @@ const KG_CYPHER = {
       n.sampleIds = [e.sampleId],
       n.properties = e.properties
     ON MATCH SET
+      n.id = coalesce(n.id, e.id),
       n.lastAccessedAt = $now,
       n.accessCount = n.accessCount + 1,
       n.relevanceScore = CASE
@@ -808,7 +814,7 @@ class KnowledgeOperationsImpl implements KnowledgeOperations {
   @trace()
   async createEntity(entity: KnowledgeEntity): Promise<string> {
     const now = Date.now();
-    const id = entity.id ?? crypto.randomUUID();
+    const id = entity.id ?? deriveEntityId(entity.text, entity.type);
     const sampleIds = [entity.sampleId ?? 'unknown'];
 
     // Atomic upsert via MERGE (QUAL.2 — eliminates check-then-insert race)
@@ -1003,7 +1009,7 @@ class KnowledgeOperationsImpl implements KnowledgeOperations {
       const entityParams = batch.map(e => ({
         text: e.text,
         type: e.type,
-        id: e.id ?? crypto.randomUUID(),
+        id: e.id ?? deriveEntityId(e.text, e.type),
         confidence: e.confidence ?? 1.0,
         sampleId: e.sampleId ?? sampleId,
         properties: e.properties ? JSON.stringify(e.properties) : '{}',
diff --git a/packages/graph/src/operations.ts b/packages/graph/src/operations.ts
index 98b471e3..4caf06c9 100644
--- a/packages/graph/src/operations.ts
+++ b/packages/graph/src/operations.ts
@@ -59,6 +59,24 @@ interface ParsedEntityId {
   isExternal: boolean;
 }
 
+interface EdgeEndpoint {
+  id: string | null;
+  filePath: string | null;
+  name: string | null;
+}
+
+function edgeEndpoint(id: string): EdgeEndpoint {
+  if (/^sym:v1:[0-9a-f]{64}$/.test(id)) {
+    return { id, filePath: null, name: null };
+  }
+  const parsed = parseEntityId(id);
+  return {
+    id: null,
+    filePath: resolvedFilePath(parsed) ?? null,
+    name: resolvedName(parsed),
+  };
+}
+
 /**
  * Parse a colon-delimited entity ID into structured parts.
  * Handles both `Type:filePath:name` and `Type:external:name` formats.
@@ -94,7 +112,8 @@ const CYPHER = {
   // File operations
   UPSERT_FILE: `
     MERGE (f:File {filePath: $filePath})
-    SET f.name = $name,
+    SET f.id = $id,
+        f.name = $name,
         f.extension = $extension,
         f.loc = $loc,
         f.lastModified = $lastModified,
@@ -107,9 +126,14 @@ const CYPHER = {
 
   // Function operations - creates CONTAINS edge to File
   UPSERT_FUNCTION: `
-    MERGE (fn:Function {name: $name, filePath: $filePath, startLine: $startLine})
-    SET fn.id = $id,
+    MERGE (fn:Function {id: $id})
+    SET fn.name = $name,
+        fn.filePath = $filePath,
+        fn.startLine = $startLine,
         fn.endLine = $endLine,
+        fn.scopeKey = $scopeKey,
+        fn.disambiguator = $disambiguator,
+        fn._staleForRefresh = false,
         fn.isExported = $isExported,
         fn.isAsync = $isAsync,
         fn.isArrow = $isArrow,
@@ -131,9 +155,14 @@ const CYPHER = {
 
   // Class operations - creates CONTAINS edge to File
   UPSERT_CLASS: `
-    MERGE (c:Class {name: $name, filePath: $filePath, startLine: $startLine})
-    SET c.id = $id,
+    MERGE (c:Class {id: $id})
+    SET c.name = $name,
+        c.filePath = $filePath,
+        c.startLine = $startLine,
         c.endLine = $endLine,
+        c.scopeKey = $scopeKey,
+        c.disambiguator = $disambiguator,
+        c._staleForRefresh = false,
         c.isExported = $isExported,
         c.isAbstract = $isAbstract,
         c.extends = $extends,
@@ -150,9 +179,14 @@ const CYPHER = {
 
   // Interface operations - creates CONTAINS edge to File
   UPSERT_INTERFACE: `
-    MERGE (i:Interface {name: $name, filePath: $filePath, startLine: $startLine})
-    SET i.id = $id,
+    MERGE (i:Interface {id: $id})
+    SET i.name = $name,
+        i.filePath = $filePath,
+        i.startLine = $startLine,
         i.endLine = $endLine,
+        i.scopeKey = $scopeKey,
+        i.disambiguator = $disambiguator,
+        i._staleForRefresh = false,
         i.isExported = $isExported,
         i.extends = $extends,
         i.docstring = $docstring,
@@ -167,8 +201,13 @@ const CYPHER = {
 
   // Variable operations - creates CONTAINS edge to File
   UPSERT_VARIABLE: `
-    MERGE (v:Variable {name: $name, filePath: $filePath, line: $line})
-    SET v.id = $id,
+    MERGE (v:Variable {id: $id})
+    SET v.name = $name,
+        v.filePath = $filePath,
+        v.line = $line,
+        v.scopeKey = $scopeKey,
+        v.disambiguator = $disambiguator,
+        v._staleForRefresh = false,
         v.kind = $kind,
         v.isExported = $isExported,
         v.type = $type,
@@ -183,8 +222,14 @@ const CYPHER = {
 
   // Type operations - creates CONTAINS edge to File
   UPSERT_TYPE: `
-    MERGE (t:Type {name: $name, filePath: $filePath, startLine: $startLine})
-    SET t.endLine = $endLine,
+    MERGE (t:Type {id: $id})
+    SET t.name = $name,
+        t.filePath = $filePath,
+        t.startLine = $startLine,
+        t.endLine = $endLine,
+        t.scopeKey = $scopeKey,
+        t.disambiguator = $disambiguator,
+        t._staleForRefresh = false,
         t.isExported = $isExported,
         t.kind = $kind,
         t.docstring = $docstring,
@@ -199,8 +244,14 @@ const CYPHER = {
 
   // Component operations - creates CONTAINS edge to File
   UPSERT_COMPONENT: `
-    MERGE (comp:Component {name: $name, filePath: $filePath, startLine: $startLine})
-    SET comp.endLine = $endLine,
+    MERGE (comp:Component {id: $id})
+    SET comp.name = $name,
+        comp.filePath = $filePath,
+        comp.startLine = $startLine,
+        comp.endLine = $endLine,
+        comp.scopeKey = $scopeKey,
+        comp.disambiguator = $disambiguator,
+        comp._staleForRefresh = false,
         comp.isExported = $isExported,
         comp.props = $props,
         comp.propsType = $propsType,
@@ -214,16 +265,21 @@ const CYPHER = {
   `,
 
   // Edge operations
-  // CALLS source can be Function | Variable | Class | Interface — relaxed
+  // CALLS source can be Function | Variable | Class | Interface. Canonical
+  // endpoint ids take priority. Name and path remain the documented fallback
+  // for descriptors produced before endpoint resolution.
   // from the original Function-only constraint so calls inside arrow
   // initialisers (e.g., zod's $ZodCheckMultipleOf) are reachable.
   // labels(caller)[0] disambiguates same-name+filePath nodes across labels.
   // ON MATCH deliberately leaves c.via untouched: existing pre-fix edges
   // have c.via IS NULL — consumers read via as coalesce(c.via, 'direct').
   CREATE_CALLS_EDGE: `
-    MATCH (caller {name: $callerName, filePath: $callerFile})
-    WHERE labels(caller)[0] = $callerKind
-    MATCH (callee:Function {name: $calleeName, filePath: $calleeFile})
+    MATCH (caller)
+    WHERE ($callerId IS NOT NULL AND caller.id = $callerId) OR
+      ($callerId IS NULL AND caller.name = $callerName AND caller.filePath = $callerFile AND labels(caller)[0] = $callerKind)
+    MATCH (callee:Function)
+    WHERE ($calleeId IS NOT NULL AND callee.id = $calleeId) OR
+      ($calleeId IS NULL AND callee.name = $calleeName AND callee.filePath = $calleeFile)
     MERGE (caller)-[c:CALLS]->(callee)
     ON CREATE SET c.line = $line, c.count = 1, c.via = $via
     ON MATCH SET c.count = c.count + 1
@@ -262,24 +318,50 @@ const CYPHER = {
   `,
 
   CREATE_EXTENDS_EDGE: `
-    MATCH (child:Class {name: $childName, filePath: $childFile})
+    MATCH (child:Class)
+    WHERE ($childId IS NOT NULL AND child.id = $childId) OR
+      ($childId IS NULL AND child.name = $childName AND child.filePath = $childFile)
     MERGE (parent:Class {name: $parentName, filePath: COALESCE($parentFile, 'external')})
     ON CREATE SET parent:External
     MERGE (child)-[e:EXTENDS]->(parent)
     RETURN e
   `,
 
+  CREATE_EXTENDS_EDGE_BY_ID: `
+    MATCH (child:Class)
+    WHERE ($childId IS NOT NULL AND child.id = $childId) OR
+      ($childId IS NULL AND child.name = $childName AND child.filePath = $childFile)
+    MATCH (parent:Class {id: $parentId})
+    MERGE (child)-[e:EXTENDS]->(parent)
+    RETURN e
+  `,
+
   CREATE_IMPLEMENTS_EDGE: `
-    MATCH (c:Class {name: $className, filePath: $classFile})
+    MATCH (c:Class)
+    WHERE ($classId IS NOT NULL AND c.id = $classId) OR
+      ($classId IS NULL AND c.name = $className AND c.filePath = $classFile)
     MERGE (i:Interface {name: $interfaceName, filePath: COALESCE($interfaceFile, 'external')})
     ON CREATE SET i:External
     MERGE (c)-[impl:IMPLEMENTS]->(i)
     RETURN impl
   `,
 
+  CREATE_IMPLEMENTS_EDGE_BY_ID: `
+    MATCH (c:Class)
+    WHERE ($classId IS NOT NULL AND c.id = $classId) OR
+      ($classId IS NULL AND c.name = $className AND c.filePath = $classFile)
+    MATCH (i:Interface {id: $interfaceId})
+    MERGE (c)-[impl:IMPLEMENTS]->(i)
+    RETURN impl
+  `,
+
   CREATE_RENDERS_EDGE: `
-    MATCH (parent:Component {name: $parentName, filePath: $parentFile})
-    MATCH (child:Component {name: $childName})
+    MATCH (parent:Component)
+    WHERE ($parentId IS NOT NULL AND parent.id = $parentId) OR
+      ($parentId IS NULL AND parent.name = $parentName AND parent.filePath = $parentFile)
+    MATCH (child:Component)
+    WHERE ($childId IS NOT NULL AND child.id = $childId) OR
+      ($childId IS NULL AND child.name = $childName)
     MERGE (parent)-[r:RENDERS]->(child)
     SET r.line = $line
     RETURN r
@@ -376,19 +458,14 @@ const CYPHER = {
     RETURN r
   `,
 
-  // Export edge operations
-  // symbolKind (labels(symbol)[0] predicate) disambiguates declaration
-  // merging: a class and an interface (or two other node types) sharing the
-  // same (name, filePath) but declared at different points, the same
-  // reasoning CREATE_CALLS_EDGE uses callerKind for. WHERE applied directly
-  // after MATCH filters the pattern match itself, so a symbol that exists
-  // but has the wrong label makes this whole MATCH find nothing (zero rows),
-  // not an error: the edge silently isn't created, same as the file-not-found
-  // case, never a stub or a wrongly-labeled edge.
+  // Export edge operations. Canonical endpoint ids take priority. symbolKind
+  // disambiguates declaration merging only on the legacy name/path fallback.
   CREATE_EXPORTS_EDGE: `
-    MATCH (f:File {filePath: $filePath})
-    MATCH (symbol {name: $symbolName, filePath: $filePath})
-    WHERE labels(symbol)[0] = $symbolKind
+    MATCH (f:File)
+    WHERE ($fromId IS NOT NULL AND f.id = $fromId) OR ($fromId IS NULL AND f.filePath = $filePath)
+    MATCH (symbol)
+    WHERE ($toId IS NOT NULL AND symbol.id = $toId) OR
+      ($toId IS NULL AND symbol.name = $symbolName AND symbol.filePath = $filePath AND labels(symbol)[0] = $symbolKind)
     MERGE (f)-[r:EXPORTS]->(symbol)
     SET r.asName = $asName,
         r.isDefault = $isDefault
@@ -400,20 +477,15 @@ const CYPHER = {
     RETURN symbol.name as name, labels(symbol)[0] as type, r.asName as asName, r.isDefault as isDefault
   `,
 
-  // IMPORTS_SYMBOL edge: importing File to the imported symbol node (not the
-  // imported File, that's IMPORTS). Plain MATCH on both sides, mirroring
-  // CREATE_CALLS_EDGE: when the target symbol doesn't exist yet (unparsed
-  // file, or a genuinely external/node_modules source), this MATCH simply
-  // finds nothing and the edge is silently never created, never MERGE'd as a
-  // stub node the way CREATE_EXTENDS_EDGE does for an external parent class.
-  // No label predicate on the target: unlike EXPORTS, the pipeline doesn't
-  // know the target symbol's kind ahead of time (it lives in another file
-  // this pass hasn't necessarily typed), so this matches by (name, filePath)
-  // alone, same as the pre-fix CREATE_EXPORTS_EDGE did before symbolKind was
-  // added above.
+  // IMPORTS_SYMBOL connects an importing File to the imported declaration.
+  // Canonical endpoint ids take priority. The legacy fallback matches by name
+  // and path and never creates a stub when the target is unavailable.
   CREATE_IMPORTS_SYMBOL_EDGE: `
-    MATCH (from:File {filePath: $fromFilePath})
-    MATCH (symbol {name: $symbolName, filePath: $toFilePath})
+    MATCH (from:File)
+    WHERE ($fromId IS NOT NULL AND from.id = $fromId) OR ($fromId IS NULL AND from.filePath = $fromFilePath)
+    MATCH (symbol)
+    WHERE ($toId IS NOT NULL AND symbol.id = $toId) OR
+      ($toId IS NULL AND symbol.name = $symbolName AND symbol.filePath = $toFilePath)
     MERGE (from)-[r:IMPORTS_SYMBOL]->(symbol)
     SET r.alias = $alias,
         r.isDefault = $isDefault
@@ -436,31 +508,59 @@ const CYPHER = {
     RETURN r
   `,
 
-  // Delete operations - cascade delete file and all contained entities
-  DELETE_FILE_ENTITIES: `
-    MATCH (f:File {filePath: $filePath})-[:CONTAINS]->(e)
-    DETACH DELETE e
-    WITH f
+  // Real file removal deletes the source owner and every declaration it owns.
+  REMOVE_FILE_NODE: `
+    MATCH (f:File {filePath: $filePath})
     DETACH DELETE f
   `,
 
-  // Smart file removal (PERF.4) — preserves incoming cross-file edges
-  // Step 1: Remove CONTAINS edges and the File node (non-cascading)
-  REMOVE_FILE_NODE: `
-    MATCH (f:File {filePath: $filePath})
-    OPTIONAL MATCH (f)-[c:CONTAINS]->()
-    DELETE c, f
+  REMOVE_FILE_SYMBOLS: `
+    MATCH (e)
+    WHERE e.filePath = $filePath AND
+      (e:Function OR e:Class OR e:Interface OR e:Variable OR e:Type OR e:Component)
+    DETACH DELETE e
+  `,
+
+  REMOVE_FILE_DOCUMENT: `
+    MATCH (d:MarkdownDocument {path: $filePath})
+    OPTIONAL MATCH (d)-[:CONTAINS]->(content)
+    DETACH DELETE content, d
   `,
 
-  // Content-only removal: detach CONTAINS edges to this file's child symbols,
-  // but leave the File node (and every other edge attached to it, e.g.
-  // MODIFIED_IN, HAS_FILE, EXPORTS) untouched. Use this instead of
-  // REMOVE_FILE_NODE when a file's content changed and is about to be
-  // re-parsed: deleting the File node would cascade-delete git-history edges
-  // from commits that were already synced and would never be re-synced.
+  // Mark the prior declaration set before refresh. Current canonical IDs clear
+  // this marker during upsert, then SWEEP_STALE_FILE_SYMBOLS removes the rest.
   REMOVE_FILE_CONTENTS: `
-    MATCH (f:File {filePath: $filePath})-[c:CONTAINS]->()
-    DELETE c
+    MATCH (e)
+    WHERE e.filePath = $filePath AND
+      (e:Function OR e:Class OR e:Interface OR e:Variable OR e:Type OR e:Component)
+    SET e._staleForRefresh = true
+  `,
+
+  REMOVE_FILE_OUTGOING_EDGES: `
+    MATCH (f:File {filePath: $filePath})-[r:IMPORTS|IMPORTS_SYMBOL|EXPORTS]->()
+    DELETE r
+  `,
+
+  REMOVE_SYMBOL_OUTGOING_EDGES: `
+    MATCH (e)-[r:CALLS|EXTENDS|IMPLEMENTS|RENDERS|HAS_METHOD|HAS_PROPERTY|HAS_PARAM|RETURNS|USES_TYPE]->()
+    WHERE e.filePath = $filePath AND
+      (e:Function OR e:Class OR e:Interface OR e:Variable OR e:Type OR e:Component)
+    DELETE r
+  `,
+
+  SWEEP_STALE_FILE_SYMBOLS: `
+    MATCH (e {_staleForRefresh: true})
+    WHERE e.filePath = $filePath AND
+      (e:Function OR e:Class OR e:Interface OR e:Variable OR e:Type OR e:Component)
+    DETACH DELETE e
+  `,
+
+  SWEEP_STALE_FILE_SYMBOL_IDS: `
+    MATCH (e)
+    WHERE e.filePath = $filePath AND
+      (e:Function OR e:Class OR e:Interface OR e:Variable OR e:Type OR e:Component) AND
+      NOT e.id IN $currentIds
+    DETACH DELETE e
   `,
 
   // Content-only removal for a changed Markdown document. Keep the stable
@@ -472,18 +572,6 @@ const CYPHER = {
     DETACH DELETE content
   `,
 
-  // Step 2: Remove orphaned entities from this file that have no incoming edges
-  // Uses OPTIONAL MATCH to check for ANY incoming relationship from other nodes
-  CLEANUP_FILE_ORPHANS: `
-    MATCH (e)
-    WHERE e.filePath = $filePath
-    OPTIONAL MATCH (other)-[r]->(e)
-    WHERE other.filePath <> $filePath OR other.filePath IS NULL
-    WITH e, r
-    WHERE r IS NULL
-    DETACH DELETE e
-  `,
-
   // Count nodes for a file
   COUNT_FILE_ENTITIES: `
     MATCH (f:File {filePath: $filePath})-[:CONTAINS]->(e)
@@ -499,7 +587,8 @@ const CYPHER = {
   // Project operations
   UPSERT_PROJECT: `
     MERGE (p:Project {id: $id})
-    SET p.name = $name,
+    SET p.projectId = $id,
+        p.name = $name,
         p.rootPath = $rootPath,
         p.createdAt = $createdAt,
         p.lastParsed = $lastParsed,
@@ -522,21 +611,24 @@ const CYPHER = {
   `,
 
   DELETE_PROJECT: `
-    MATCH (p:Project {id: $id})
-    OPTIONAL MATCH (p)-[:HAS_FILE]->(f:File)-[:CONTAINS]->(e)
-    DETACH DELETE e
-    WITH p, f
-    DETACH DELETE f
-    WITH p
-    DETACH DELETE p
+    MATCH (owned)
+    WHERE owned.projectId = $id OR (owned:Project AND owned.id = $id)
+    DETACH DELETE owned
   `,
 
   LINK_PROJECT_FILE: `
     MATCH (p:Project {id: $projectId})
     MATCH (f:File {filePath: $filePath})
+    SET f.projectId = $projectId
     MERGE (p)-[:HAS_FILE]->(f)
   `,
 
+  STAMP_FILE_SYMBOL_OWNERSHIP: `
+    MATCH (:File {filePath: $filePath})-[:CONTAINS]->(owned)
+    WHERE owned:Function OR owned:Class OR owned:Interface OR owned:Variable OR owned:Type OR owned:Component
+    SET owned.projectId = $projectId
+  `,
+
   GET_PROJECT_FILE_HASHES: `
     MATCH (p:Project {id: $projectId})-[:HAS_FILE]->(f:File)
     RETURN f.filePath AS path, f.hash AS hash
@@ -548,7 +640,8 @@ const CYPHER = {
   BATCH_UPSERT_FILES: `
     UNWIND $items AS item
     MERGE (f:File {filePath: item.filePath})
-    SET f.name = item.name,
+    SET f.id = item.id,
+        f.name = item.name,
         f.extension = item.extension,
         f.loc = item.loc,
         f.lastModified = item.lastModified,
@@ -560,9 +653,14 @@ const CYPHER = {
 
   BATCH_UPSERT_FUNCTIONS: `
     UNWIND $items AS item
-    MERGE (fn:Function {name: item.name, filePath: item.filePath, startLine: item.startLine})
-    SET fn.id = item.id,
+    MERGE (fn:Function {id: item.id})
+    SET fn.name = item.name,
+        fn.filePath = item.filePath,
+        fn.startLine = item.startLine,
         fn.endLine = item.endLine,
+        fn.scopeKey = item.scopeKey,
+        fn.disambiguator = item.disambiguator,
+        fn._staleForRefresh = false,
         fn.isExported = item.isExported,
         fn.isAsync = item.isAsync,
         fn.isArrow = item.isArrow,
@@ -583,9 +681,14 @@ const CYPHER = {
 
   BATCH_UPSERT_CLASSES: `
     UNWIND $items AS item
-    MERGE (c:Class {name: item.name, filePath: item.filePath, startLine: item.startLine})
-    SET c.id = item.id,
+    MERGE (c:Class {id: item.id})
+    SET c.name = item.name,
+        c.filePath = item.filePath,
+        c.startLine = item.startLine,
         c.endLine = item.endLine,
+        c.scopeKey = item.scopeKey,
+        c.disambiguator = item.disambiguator,
+        c._staleForRefresh = false,
         c.isExported = item.isExported,
         c.isAbstract = item.isAbstract,
         c.extends = item.extends,
@@ -601,9 +704,14 @@ const CYPHER = {
 
   BATCH_UPSERT_INTERFACES: `
     UNWIND $items AS item
-    MERGE (i:Interface {name: item.name, filePath: item.filePath, startLine: item.startLine})
-    SET i.id = item.id,
+    MERGE (i:Interface {id: item.id})
+    SET i.name = item.name,
+        i.filePath = item.filePath,
+        i.startLine = item.startLine,
         i.endLine = item.endLine,
+        i.scopeKey = item.scopeKey,
+        i.disambiguator = item.disambiguator,
+        i._staleForRefresh = false,
         i.isExported = item.isExported,
         i.extends = item.extends,
         i.docstring = item.docstring,
@@ -617,8 +725,13 @@ const CYPHER = {
 
   BATCH_UPSERT_VARIABLES: `
     UNWIND $items AS item
-    MERGE (v:Variable {name: item.name, filePath: item.filePath, line: item.line})
-    SET v.id = item.id,
+    MERGE (v:Variable {id: item.id})
+    SET v.name = item.name,
+        v.filePath = item.filePath,
+        v.line = item.line,
+        v.scopeKey = item.scopeKey,
+        v.disambiguator = item.disambiguator,
+        v._staleForRefresh = false,
         v.kind = item.kind,
         v.isExported = item.isExported,
         v.type = item.type,
@@ -632,8 +745,14 @@ const CYPHER = {
 
   BATCH_UPSERT_TYPES: `
     UNWIND $items AS item
-    MERGE (t:Type {name: item.name, filePath: item.filePath, startLine: item.startLine})
-    SET t.endLine = item.endLine,
+    MERGE (t:Type {id: item.id})
+    SET t.name = item.name,
+        t.filePath = item.filePath,
+        t.startLine = item.startLine,
+        t.endLine = item.endLine,
+        t.scopeKey = item.scopeKey,
+        t.disambiguator = item.disambiguator,
+        t._staleForRefresh = false,
         t.isExported = item.isExported,
         t.kind = item.kind,
         t.docstring = item.docstring,
@@ -647,8 +766,14 @@ const CYPHER = {
 
   BATCH_UPSERT_COMPONENTS: `
     UNWIND $items AS item
-    MERGE (comp:Component {name: item.name, filePath: item.filePath, startLine: item.startLine})
-    SET comp.endLine = item.endLine,
+    MERGE (comp:Component {id: item.id})
+    SET comp.name = item.name,
+        comp.filePath = item.filePath,
+        comp.startLine = item.startLine,
+        comp.endLine = item.endLine,
+        comp.scopeKey = item.scopeKey,
+        comp.disambiguator = item.disambiguator,
+        comp._staleForRefresh = false,
         comp.isExported = item.isExported,
         comp.props = item.props,
         comp.propsType = item.propsType,
@@ -712,6 +837,18 @@ const CYPHER = {
     MERGE (d)-[:CONTAINS]->(l)
   `,
 
+  STAMP_DOCUMENT_PROJECT_OWNERSHIP: `
+    MATCH (p:Project)
+    WHERE p.rootPath = '/' OR $documentPath STARTS WITH (p.rootPath + '/')
+    WITH p ORDER BY size(p.rootPath) DESC
+    LIMIT 1
+    MATCH (d:MarkdownDocument {path: $documentPath})
+    SET d.projectId = p.id
+    WITH p, d
+    OPTIONAL MATCH (d)-[:CONTAINS]->(content)
+    SET content.projectId = p.id
+  `,
+
   // Batch variant of CREATE_PARENT_SECTION_EDGE, run after BATCH_UPSERT_SECTIONS
   // so every Section node in this batch already exists.
   BATCH_CREATE_PARENT_SECTION_EDGES: `
@@ -722,76 +859,35 @@ const CYPHER = {
     MERGE (parent)-[r:PARENT_SECTION]->(child)
   `,
 
-  // Edge queries use OPTIONAL MATCH + WHERE to avoid FalkorDB crashes on
-  // NULL records (Record_GetType segfault when MATCH finds no node).
-  BATCH_CREATE_CALL_EDGES: `
-    UNWIND $items AS item
-    OPTIONAL MATCH (caller {name: item.callerName, filePath: item.callerFile})
-    WHERE labels(caller)[0] = item.callerKind
-    OPTIONAL MATCH (callee:Function {name: item.calleeName, filePath: item.calleeFile})
-    WITH caller, callee, item WHERE caller IS NOT NULL AND callee IS NOT NULL
-    MERGE (caller)-[c:CALLS]->(callee)
-    ON CREATE SET c.line = item.line, c.count = 1, c.via = item.via
-    ON MATCH SET c.count = c.count + 1
-  `,
-
-  BATCH_CREATE_IMPORT_EDGES: `
-    UNWIND $items AS item
-    OPTIONAL MATCH (from:File {filePath: item.fromPath})
-    WITH from, item WHERE from IS NOT NULL
-    MERGE (to:File {filePath: item.toPath})
-    ON CREATE SET to:External
-    MERGE (from)-[i:IMPORTS]->(to)
-    SET i.specifiers = item.specifiers
-  `,
-
-  BATCH_CREATE_EXTENDS_EDGES: `
-    UNWIND $items AS item
-    OPTIONAL MATCH (child:Class {name: item.childName, filePath: item.childFile})
-    WITH child, item WHERE child IS NOT NULL
-    MERGE (parent:Class {name: item.parentName, filePath: COALESCE(item.parentFile, 'external')})
-    ON CREATE SET parent:External
-    MERGE (child)-[e:EXTENDS]->(parent)
-  `,
-
-  BATCH_CREATE_IMPLEMENTS_EDGES: `
-    UNWIND $items AS item
-    OPTIONAL MATCH (c:Class {name: item.className, filePath: item.classFile})
-    WITH c, item WHERE c IS NOT NULL
-    MERGE (i:Interface {name: item.interfaceName, filePath: COALESCE(item.interfaceFile, 'external')})
-    ON CREATE SET i:External
-    MERGE (c)-[impl:IMPLEMENTS]->(i)
-  `,
-
-  BATCH_CREATE_RENDERS_EDGES: `
-    UNWIND $items AS item
-    OPTIONAL MATCH (parent:Component {name: item.parentName, filePath: item.parentFile})
-    OPTIONAL MATCH (child:Component {name: item.childName})
-    WITH parent, child, item WHERE parent IS NOT NULL AND child IS NOT NULL
-    MERGE (parent)-[r:RENDERS]->(child)
-    SET r.line = item.line
-  `,
-
   BATCH_LINK_PROJECT_FILES: `
     UNWIND $items AS item
     OPTIONAL MATCH (p:Project {id: item.projectId})
     OPTIONAL MATCH (f:File {filePath: item.filePath})
     WITH p, f WHERE p IS NOT NULL AND f IS NOT NULL
+    SET f.projectId = p.id
     MERGE (p)-[:HAS_FILE]->(f)
   `,
 
+  BATCH_STAMP_FILE_SYMBOL_OWNERSHIP: `
+    UNWIND $items AS item
+    MATCH (:File {filePath: item.filePath})-[:CONTAINS]->(owned)
+    WHERE owned:Function OR owned:Class OR owned:Interface OR owned:Variable OR owned:Type OR owned:Component
+    SET owned.projectId = item.projectId
+  `,
+
   // --- Fast CREATE path for full reindex (no MERGE lookups needed) ---
   // Used after clearing old data; CREATE is much faster than MERGE for bulk inserts.
   BATCH_CREATE_FILES: `
     UNWIND $items AS item
-    CREATE (f:File {filePath: item.filePath, name: item.name, extension: item.extension,
+    CREATE (f:File {id: item.id, filePath: item.filePath, name: item.name, extension: item.extension,
       loc: item.loc, lastModified: item.lastModified, hash: item.hash,
       sourcePipeline: item.sourcePipeline, sourceTask: item.sourceTask, processedAt: item.processedAt})
   `,
 
   BATCH_CREATE_FUNCTIONS_FAST: `
     UNWIND $items AS item
-    CREATE (fn:Function {id: item.id, name: item.name, filePath: item.filePath, startLine: item.startLine,
+    CREATE (fn:Function {id: item.id, scopeKey: item.scopeKey, disambiguator: item.disambiguator,
+      name: item.name, filePath: item.filePath, startLine: item.startLine,
       endLine: item.endLine, isExported: item.isExported, isAsync: item.isAsync,
       isArrow: item.isArrow, params: item.params, returnType: item.returnType,
       docstring: item.docstring, bodySnippet: item.bodySnippet, complexity: item.complexity,
@@ -804,7 +900,8 @@ const CYPHER = {
 
   BATCH_CREATE_CLASSES_FAST: `
     UNWIND $items AS item
-    CREATE (c:Class {id: item.id, name: item.name, filePath: item.filePath, startLine: item.startLine,
+    CREATE (c:Class {id: item.id, scopeKey: item.scopeKey, disambiguator: item.disambiguator,
+      name: item.name, filePath: item.filePath, startLine: item.startLine,
       endLine: item.endLine, isExported: item.isExported, isAbstract: item.isAbstract,
       extends: item.extends, implements: item.implements, docstring: item.docstring,
       sourcePipeline: item.sourcePipeline, sourceTask: item.sourceTask, processedAt: item.processedAt})
@@ -815,7 +912,8 @@ const CYPHER = {
 
   BATCH_CREATE_INTERFACES_FAST: `
     UNWIND $items AS item
-    CREATE (i:Interface {id: item.id, name: item.name, filePath: item.filePath, startLine: item.startLine,
+    CREATE (i:Interface {id: item.id, scopeKey: item.scopeKey, disambiguator: item.disambiguator,
+      name: item.name, filePath: item.filePath, startLine: item.startLine,
       endLine: item.endLine, isExported: item.isExported, extends: item.extends,
       docstring: item.docstring,
       sourcePipeline: item.sourcePipeline, sourceTask: item.sourceTask, processedAt: item.processedAt})
@@ -826,7 +924,8 @@ const CYPHER = {
 
   BATCH_CREATE_VARIABLES_FAST: `
     UNWIND $items AS item
-    CREATE (v:Variable {id: item.id, name: item.name, filePath: item.filePath, line: item.line,
+    CREATE (v:Variable {id: item.id, scopeKey: item.scopeKey, disambiguator: item.disambiguator,
+      name: item.name, filePath: item.filePath, line: item.line,
       kind: item.kind, isExported: item.isExported, type: item.type,
       sourcePipeline: item.sourcePipeline, sourceTask: item.sourceTask, processedAt: item.processedAt})
     WITH v
@@ -836,7 +935,8 @@ const CYPHER = {
 
   BATCH_CREATE_TYPES_FAST: `
     UNWIND $items AS item
-    CREATE (t:Type {name: item.name, filePath: item.filePath, startLine: item.startLine,
+    CREATE (t:Type {id: item.id, scopeKey: item.scopeKey, disambiguator: item.disambiguator,
+      name: item.name, filePath: item.filePath, startLine: item.startLine,
       endLine: item.endLine, isExported: item.isExported, kind: item.kind,
       docstring: item.docstring,
       sourcePipeline: item.sourcePipeline, sourceTask: item.sourceTask, processedAt: item.processedAt})
@@ -847,7 +947,8 @@ const CYPHER = {
 
   BATCH_CREATE_COMPONENTS_FAST: `
     UNWIND $items AS item
-    CREATE (comp:Component {name: item.name, filePath: item.filePath, startLine: item.startLine,
+    CREATE (comp:Component {id: item.id, scopeKey: item.scopeKey, disambiguator: item.disambiguator,
+      name: item.name, filePath: item.filePath, startLine: item.startLine,
       endLine: item.endLine, isExported: item.isExported, props: item.props,
       propsType: item.propsType,
       sourcePipeline: item.sourcePipeline, sourceTask: item.sourceTask, processedAt: item.processedAt})
@@ -863,7 +964,8 @@ const CYPHER = {
   COMBINED_UPSERT_ALL: `
     UNWIND $files AS item
     MERGE (f:File {filePath: item.filePath})
-    SET f.name = item.name,
+    SET f.id = item.id,
+        f.name = item.name,
         f.extension = item.extension,
         f.loc = item.loc,
         f.lastModified = item.lastModified,
@@ -873,9 +975,14 @@ const CYPHER = {
         f.processedAt = item.processedAt
     WITH count(*) AS _c1
     UNWIND $functions AS item
-    MERGE (fn:Function {name: item.name, filePath: item.filePath, startLine: item.startLine})
-    SET fn.id = item.id,
+    MERGE (fn:Function {id: item.id})
+    SET fn.name = item.name,
+        fn.filePath = item.filePath,
+        fn.startLine = item.startLine,
         fn.endLine = item.endLine,
+        fn.scopeKey = item.scopeKey,
+        fn.disambiguator = item.disambiguator,
+        fn._staleForRefresh = false,
         fn.isExported = item.isExported,
         fn.isAsync = item.isAsync,
         fn.isArrow = item.isArrow,
@@ -893,9 +1000,14 @@ const CYPHER = {
     MERGE (f)-[:CONTAINS]->(fn)
     WITH count(*) AS _c2
     UNWIND $classes AS item
-    MERGE (c:Class {name: item.name, filePath: item.filePath, startLine: item.startLine})
-    SET c.id = item.id,
+    MERGE (c:Class {id: item.id})
+    SET c.name = item.name,
+        c.filePath = item.filePath,
+        c.startLine = item.startLine,
         c.endLine = item.endLine,
+        c.scopeKey = item.scopeKey,
+        c.disambiguator = item.disambiguator,
+        c._staleForRefresh = false,
         c.isExported = item.isExported,
         c.isAbstract = item.isAbstract,
         c.extends = item.extends,
@@ -909,9 +1021,14 @@ const CYPHER = {
     MERGE (f)-[:CONTAINS]->(c)
     WITH count(*) AS _c3
     UNWIND $interfaces AS item
-    MERGE (i:Interface {name: item.name, filePath: item.filePath, startLine: item.startLine})
-    SET i.id = item.id,
+    MERGE (i:Interface {id: item.id})
+    SET i.name = item.name,
+        i.filePath = item.filePath,
+        i.startLine = item.startLine,
         i.endLine = item.endLine,
+        i.scopeKey = item.scopeKey,
+        i.disambiguator = item.disambiguator,
+        i._staleForRefresh = false,
         i.isExported = item.isExported,
         i.extends = item.extends,
         i.docstring = item.docstring,
@@ -923,8 +1040,13 @@ const CYPHER = {
     MERGE (f)-[:CONTAINS]->(i)
     WITH count(*) AS _c4
     UNWIND $variables AS item
-    MERGE (v:Variable {name: item.name, filePath: item.filePath, line: item.line})
-    SET v.id = item.id,
+    MERGE (v:Variable {id: item.id})
+    SET v.name = item.name,
+        v.filePath = item.filePath,
+        v.line = item.line,
+        v.scopeKey = item.scopeKey,
+        v.disambiguator = item.disambiguator,
+        v._staleForRefresh = false,
         v.kind = item.kind,
         v.isExported = item.isExported,
         v.type = item.type,
@@ -936,8 +1058,14 @@ const CYPHER = {
     MERGE (f)-[:CONTAINS]->(v)
     WITH count(*) AS _c5
     UNWIND $types AS item
-    MERGE (t:Type {name: item.name, filePath: item.filePath, startLine: item.startLine})
-    SET t.endLine = item.endLine,
+    MERGE (t:Type {id: item.id})
+    SET t.name = item.name,
+        t.filePath = item.filePath,
+        t.startLine = item.startLine,
+        t.endLine = item.endLine,
+        t.scopeKey = item.scopeKey,
+        t.disambiguator = item.disambiguator,
+        t._staleForRefresh = false,
         t.isExported = item.isExported,
         t.kind = item.kind,
         t.docstring = item.docstring,
@@ -949,8 +1077,14 @@ const CYPHER = {
     MERGE (f)-[:CONTAINS]->(t)
     WITH count(*) AS _c6
     UNWIND $components AS item
-    MERGE (comp:Component {name: item.name, filePath: item.filePath, startLine: item.startLine})
-    SET comp.endLine = item.endLine,
+    MERGE (comp:Component {id: item.id})
+    SET comp.name = item.name,
+        comp.filePath = item.filePath,
+        comp.startLine = item.startLine,
+        comp.endLine = item.endLine,
+        comp.scopeKey = item.scopeKey,
+        comp.disambiguator = item.disambiguator,
+        comp._staleForRefresh = false,
         comp.isExported = item.isExported,
         comp.props = item.props,
         comp.propsType = item.propsType,
@@ -963,75 +1097,33 @@ const CYPHER = {
     RETURN count(*) AS done
   `,
 
-  // --- Combined edge creation (reduces 5 round-trips to 1) ---
-  COMBINED_CREATE_EDGES: `
-    UNWIND $callEdges AS item
-    MATCH (caller {name: item.callerName, filePath: item.callerFile})
-    WHERE labels(caller)[0] = item.callerKind
-    MATCH (callee:Function {name: item.calleeName, filePath: item.calleeFile})
-    MERGE (caller)-[c:CALLS]->(callee)
-    ON CREATE SET c.line = item.line, c.count = 1, c.via = item.via
-    ON MATCH SET c.count = c.count + 1
-    WITH count(*) AS _e1
-    UNWIND $importEdges AS item
-    MATCH (from:File {filePath: item.fromPath})
-    MERGE (to:File {filePath: item.toPath})
-    ON CREATE SET to:External
-    MERGE (from)-[i:IMPORTS]->(to)
-    SET i.specifiers = item.specifiers
-    WITH count(*) AS _e2
-    UNWIND $extendsEdges AS item
-    MATCH (child:Class {name: item.childName, filePath: item.childFile})
-    MERGE (parent:Class {name: item.parentName, filePath: COALESCE(item.parentFile, 'external')})
-    ON CREATE SET parent:External
-    MERGE (child)-[e:EXTENDS]->(parent)
-    WITH count(*) AS _e3
-    UNWIND $implementsEdges AS item
-    MATCH (c:Class {name: item.className, filePath: item.classFile})
-    MERGE (i:Interface {name: item.interfaceName, filePath: COALESCE(item.interfaceFile, 'external')})
-    ON CREATE SET i:External
-    MERGE (c)-[impl:IMPLEMENTS]->(i)
-    WITH count(*) AS _e4
-    UNWIND $rendersEdges AS item
-    MATCH (parent:Component {name: item.parentName, filePath: item.parentFile})
-    MATCH (child:Component {name: item.childName})
-    MERGE (parent)-[r:RENDERS]->(child)
-    SET r.line = item.line
-    WITH count(*) AS _e5
-    UNWIND $projectLinks AS item
-    MATCH (p:Project {id: item.projectId})
-    MATCH (f:File {filePath: item.filePath})
-    MERGE (p)-[:HAS_FILE]->(f)
-    RETURN count(*) AS done
-  `,
-
   // Embedding update operations (per-node-type) — uses vecf32() for proper vector storage
   UPDATE_FILE_EMBEDDING: `
     MATCH (f:File {filePath: $filePath})
     SET f.embedding = vecf32($embedding), f.embeddingTextHash = $embeddingTextHash
   `,
   UPDATE_FUNCTION_EMBEDDING: `
-    MATCH (fn:Function {name: $name, filePath: $filePath, startLine: $startLine})
+    MATCH (fn:Function {id: $id})
     SET fn.embedding = vecf32($embedding), fn.embeddingTextHash = $embeddingTextHash
   `,
   UPDATE_CLASS_EMBEDDING: `
-    MATCH (c:Class {name: $name, filePath: $filePath, startLine: $startLine})
+    MATCH (c:Class {id: $id})
     SET c.embedding = vecf32($embedding), c.embeddingTextHash = $embeddingTextHash
   `,
   UPDATE_INTERFACE_EMBEDDING: `
-    MATCH (i:Interface {name: $name, filePath: $filePath, startLine: $startLine})
+    MATCH (i:Interface {id: $id})
     SET i.embedding = vecf32($embedding), i.embeddingTextHash = $embeddingTextHash
   `,
   UPDATE_VARIABLE_EMBEDDING: `
-    MATCH (v:Variable {name: $name, filePath: $filePath, line: $line})
+    MATCH (v:Variable {id: $id})
     SET v.embedding = vecf32($embedding), v.embeddingTextHash = $embeddingTextHash
   `,
   UPDATE_TYPE_EMBEDDING: `
-    MATCH (t:Type {name: $name, filePath: $filePath, startLine: $startLine})
+    MATCH (t:Type {id: $id})
     SET t.embedding = vecf32($embedding), t.embeddingTextHash = $embeddingTextHash
   `,
   UPDATE_COMPONENT_EMBEDDING: `
-    MATCH (comp:Component {name: $name, filePath: $filePath, startLine: $startLine})
+    MATCH (comp:Component {id: $id})
     SET comp.embedding = vecf32($embedding), comp.embeddingTextHash = $embeddingTextHash
   `,
 
@@ -1043,6 +1135,7 @@ const CYPHER = {
     WHERE e.embeddingTextHash IS NOT NULL
     WITH fp, collect({
       nodeType: labels(e)[0],
+      id: e.id,
       name: CASE WHEN e:Variable THEN e.name ELSE e.name END,
       filePath: e.filePath,
       startLine: CASE WHEN e:Variable THEN e.line ELSE e.startLine END,
@@ -1060,32 +1153,32 @@ const CYPHER = {
   `,
   BATCH_UPDATE_FUNCTION_EMBEDDINGS: `
     UNWIND $items AS item
-    MATCH (fn:Function {name: item.name, filePath: item.filePath, startLine: item.startLine})
+    MATCH (fn:Function {id: item.id})
     SET fn.embedding = vecf32(item.embedding), fn.embeddingTextHash = item.embeddingTextHash
   `,
   BATCH_UPDATE_CLASS_EMBEDDINGS: `
     UNWIND $items AS item
-    MATCH (c:Class {name: item.name, filePath: item.filePath, startLine: item.startLine})
+    MATCH (c:Class {id: item.id})
     SET c.embedding = vecf32(item.embedding), c.embeddingTextHash = item.embeddingTextHash
   `,
   BATCH_UPDATE_INTERFACE_EMBEDDINGS: `
     UNWIND $items AS item
-    MATCH (i:Interface {name: item.name, filePath: item.filePath, startLine: item.startLine})
+    MATCH (i:Interface {id: item.id})
     SET i.embedding = vecf32(item.embedding), i.embeddingTextHash = item.embeddingTextHash
   `,
   BATCH_UPDATE_VARIABLE_EMBEDDINGS: `
     UNWIND $items AS item
-    MATCH (v:Variable {name: item.name, filePath: item.filePath, line: item.line})
+    MATCH (v:Variable {id: item.id})
     SET v.embedding = vecf32(item.embedding), v.embeddingTextHash = item.embeddingTextHash
   `,
   BATCH_UPDATE_TYPE_EMBEDDINGS: `
     UNWIND $items AS item
-    MATCH (t:Type {name: item.name, filePath: item.filePath, startLine: item.startLine})
+    MATCH (t:Type {id: item.id})
     SET t.embedding = vecf32(item.embedding), t.embeddingTextHash = item.embeddingTextHash
   `,
   BATCH_UPDATE_COMPONENT_EMBEDDINGS: `
     UNWIND $items AS item
-    MATCH (comp:Component {name: item.name, filePath: item.filePath, startLine: item.startLine})
+    MATCH (comp:Component {id: item.id})
     SET comp.embedding = vecf32(item.embedding), comp.embeddingTextHash = item.embeddingTextHash
   `,
 };
@@ -1122,7 +1215,8 @@ export interface GraphOperations {
      * same-named methods on different classes in the same file don't both
      * receive the edge. Omitted/undefined keeps today's unqualified behavior.
      */
-    calleeClassName?: string
+    calleeClassName?: string,
+    endpointIds?: { callerId?: string | undefined; calleeId?: string | undefined },
   ): Promise<void>;
 
   createImportsEdge(
@@ -1132,49 +1226,52 @@ export interface GraphOperations {
   ): Promise<void>;
 
   /**
-   * Create a File EXPORTS symbol edge. Matched by (symbolName, filePath,
-   * symbolKind), not id: see CREATE_EXPORTS_EDGE for why. Drops silently
-   * (zero rows, no error) if the File or the symbol doesn't exist.
+   * Create a File EXPORTS symbol edge. Canonical endpoint ids take priority.
+   * Name, path, and kind matching is the fallback for legacy descriptors
+   * without ids and can be removed after all producers resolve endpoints.
    */
   createExportsEdge(
     filePath: string,
     symbolName: string,
     symbolKind: ExportableSymbolKind,
-    props?: { asName?: string | undefined; isDefault?: boolean | undefined }
+    props?: { asName?: string | undefined; isDefault?: boolean | undefined; fromId?: string | undefined; toId?: string | undefined }
   ): Promise<void>;
 
   /**
    * Create an importing File to imported-symbol IMPORTS_SYMBOL edge (not the
-   * imported File, that's createImportsEdge). Mirrors CALLS edge behavior:
-   * a plain MATCH on both sides, so it drops silently, never MERGEs a stub,
-   * when the target file or symbol isn't in the graph (unparsed or external).
+   * imported File, which is handled by createImportsEdge). Canonical endpoint
+   * ids take priority, with name and path retained only for descriptors that
+   * do not carry ids.
    */
   createImportsSymbolEdge(
     fromFilePath: string,
     toFilePath: string,
     symbolName: string,
-    props?: { alias?: string | undefined; isDefault?: boolean | undefined }
+    props?: { alias?: string | undefined; isDefault?: boolean | undefined; fromId?: string | undefined; toId?: string | undefined }
   ): Promise<void>;
 
   createExtendsEdge(
     childName: string,
     childFile: string,
     parentName: string,
-    parentFile?: string
+    parentFile?: string,
+    endpointIds?: { childId?: string | undefined; parentId?: string | undefined },
   ): Promise<void>;
 
   createImplementsEdge(
     className: string,
     classFile: string,
     interfaceName: string,
-    interfaceFile?: string
+    interfaceFile?: string,
+    endpointIds?: { classId?: string | undefined; interfaceId?: string | undefined },
   ): Promise<void>;
 
   createRendersEdge(
     parentName: string,
     parentFile: string,
     childName: string,
-    line: number
+    line: number,
+    endpointIds?: { parentId?: string | undefined; childId?: string | undefined },
   ): Promise<void>;
 
   createHasMethodEdge(
@@ -1215,23 +1312,21 @@ export interface GraphOperations {
 
   deleteFileEntities(filePath: string): Promise<void>;
 
-  /**
-   * Smart file removal (PERF.4) — removes file and its entities while
-   * preserving incoming cross-file edges (CALLS, EXTENDS, IMPLEMENTS).
-   * Entities with incoming edges from other files are kept as external references.
-   */
+  /** Remove a deleted file and detach-delete every source declaration it owned. */
   removeFileAndCleanup(filePath: string): Promise<void>;
 
   /**
    * Content-only removal, for a file whose CONTENT changed and is about to
    * be re-parsed (not a file deleted from disk: use removeFileAndCleanup()
-   * for that). Detaches CONTAINS edges to child symbols and cleans up any
-   * that are now orphaned, the same as removeFileAndCleanup() does, but
-   * leaves the File node itself, and every other edge on it (MODIFIED_IN,
-   * HAS_FILE, EXPORTS, ...), untouched.
+   * for that). Marks its prior source declarations stale and clears
+   * refresh-owned outgoing edges. The following upsert clears the marker
+   * on current IDs, then detach-deletes every remaining stale declaration.
    */
   removeFileContents(filePath: string): Promise<void>;
 
+  /** Detach-delete source declarations not present in the changed file's current ID set. */
+  sweepStaleFileSymbols(filePath: string, currentIds: readonly string[]): Promise<void>;
+
   /**
    * Content-only removal for a changed Markdown document. Deletes its
    * contained Section, CodeBlock, and Link nodes and their edges while
@@ -1389,16 +1484,19 @@ class GraphOperationsImpl implements GraphOperations {
     line: number,
     callerKind: 'Function' | 'Variable' | 'Class' | 'Interface' = 'Function',
     via: 'direct' | 'closure' = 'direct',
-    calleeClassName?: string
+    calleeClassName?: string,
+    endpointIds: { callerId?: string | undefined; calleeId?: string | undefined } = {},
   ): Promise<void> {
-    if (calleeClassName) {
+    const callerId = endpointIds.callerId ?? null;
+    const calleeId = endpointIds.calleeId ?? null;
+    if (calleeClassName && callerId === null && calleeId === null) {
       await this.client.query(CYPHER.CREATE_CALLS_EDGE_BY_CLASS, {
         params: { callerName, callerFile, calleeName, calleeFile, line, callerKind, via, calleeClassName },
       });
       return;
     }
     await this.client.query(CYPHER.CREATE_CALLS_EDGE, {
-      params: { callerName, callerFile, calleeName, calleeFile, line, callerKind, via },
+      params: { callerId, calleeId, callerName, callerFile, calleeName, calleeFile, line, callerKind, via },
     });
   }
 
@@ -1418,10 +1516,18 @@ class GraphOperationsImpl implements GraphOperations {
     filePath: string,
     symbolName: string,
     symbolKind: ExportableSymbolKind,
-    props: { asName?: string | undefined; isDefault?: boolean | undefined } = {},
+    props: { asName?: string | undefined; isDefault?: boolean | undefined; fromId?: string | undefined; toId?: string | undefined } = {},
   ): Promise<void> {
     await this.client.query(CYPHER.CREATE_EXPORTS_EDGE, {
-      params: { filePath, symbolName, symbolKind, asName: props.asName ?? null, isDefault: props.isDefault ?? null },
+      params: {
+        fromId: props.fromId ?? null,
+        toId: props.toId ?? null,
+        filePath,
+        symbolName,
+        symbolKind,
+        asName: props.asName ?? null,
+        isDefault: props.isDefault ?? null,
+      },
     });
   }
 
@@ -1430,10 +1536,18 @@ class GraphOperationsImpl implements GraphOperations {
     fromFilePath: string,
     toFilePath: string,
     symbolName: string,
-    props: { alias?: string | undefined; isDefault?: boolean | undefined } = {},
+    props: { alias?: string | undefined; isDefault?: boolean | undefined; fromId?: string | undefined; toId?: string | undefined } = {},
   ): Promise<void> {
     await this.client.query(CYPHER.CREATE_IMPORTS_SYMBOL_EDGE, {
-      params: { fromFilePath, toFilePath, symbolName, alias: props.alias ?? null, isDefault: props.isDefault ?? false },
+      params: {
+        fromId: props.fromId ?? null,
+        toId: props.toId ?? null,
+        fromFilePath,
+        toFilePath,
+        symbolName,
+        alias: props.alias ?? null,
+        isDefault: props.isDefault ?? false,
+      },
     });
   }
 
@@ -1442,10 +1556,19 @@ class GraphOperationsImpl implements GraphOperations {
     childName: string,
     childFile: string,
     parentName: string,
-    parentFile?: string
+    parentFile?: string,
+    endpointIds: { childId?: string | undefined; parentId?: string | undefined } = {},
   ): Promise<void> {
-    await this.client.query(CYPHER.CREATE_EXTENDS_EDGE, {
-      params: { childName, childFile, parentName, parentFile: parentFile ?? null },
+    const params = {
+      childId: endpointIds.childId ?? null,
+      parentId: endpointIds.parentId ?? null,
+      childName,
+      childFile,
+      parentName,
+      parentFile: parentFile ?? null,
+    };
+    await this.client.query(endpointIds.parentId ? CYPHER.CREATE_EXTENDS_EDGE_BY_ID : CYPHER.CREATE_EXTENDS_EDGE, {
+      params,
     });
   }
 
@@ -1454,10 +1577,19 @@ class GraphOperationsImpl implements GraphOperations {
     className: string,
     classFile: string,
     interfaceName: string,
-    interfaceFile?: string
+    interfaceFile?: string,
+    endpointIds: { classId?: string | undefined; interfaceId?: string | undefined } = {},
   ): Promise<void> {
-    await this.client.query(CYPHER.CREATE_IMPLEMENTS_EDGE, {
-      params: { className, classFile, interfaceName, interfaceFile: interfaceFile ?? null },
+    const params = {
+      classId: endpointIds.classId ?? null,
+      interfaceId: endpointIds.interfaceId ?? null,
+      className,
+      classFile,
+      interfaceName,
+      interfaceFile: interfaceFile ?? null,
+    };
+    await this.client.query(endpointIds.interfaceId ? CYPHER.CREATE_IMPLEMENTS_EDGE_BY_ID : CYPHER.CREATE_IMPLEMENTS_EDGE, {
+      params,
     });
   }
 
@@ -1466,10 +1598,18 @@ class GraphOperationsImpl implements GraphOperations {
     parentName: string,
     parentFile: string,
     childName: string,
-    line: number
+    line: number,
+    endpointIds: { parentId?: string | undefined; childId?: string | undefined } = {},
   ): Promise<void> {
     await this.client.query(CYPHER.CREATE_RENDERS_EDGE, {
-      params: { parentName, parentFile, childName, line },
+      params: {
+        parentId: endpointIds.parentId ?? null,
+        childId: endpointIds.childId ?? null,
+        parentName,
+        parentFile,
+        childName,
+        line,
+      },
     });
   }
 
@@ -1543,33 +1683,30 @@ class GraphOperationsImpl implements GraphOperations {
 
   @trace()
   async deleteFileEntities(filePath: string): Promise<void> {
-    await this.client.query(CYPHER.DELETE_FILE_ENTITIES, { params: { filePath } });
+    await this.client.query(CYPHER.REMOVE_FILE_SYMBOLS, { params: { filePath } });
+    await this.client.query(CYPHER.REMOVE_FILE_DOCUMENT, { params: { filePath } });
+    await this.client.query(CYPHER.REMOVE_FILE_NODE, { params: { filePath } });
   }
 
   @trace()
   async removeFileAndCleanup(filePath: string): Promise<void> {
-    // Step 1: Remove CONTAINS edges and the File node (without cascading to entities)
+    await this.client.query(CYPHER.REMOVE_FILE_SYMBOLS, { params: { filePath } });
+    await this.client.query(CYPHER.REMOVE_FILE_DOCUMENT, { params: { filePath } });
     await this.client.query(CYPHER.REMOVE_FILE_NODE, { params: { filePath } });
-
-    // Step 2: Remove entities from this file that have NO incoming edges from other files
-    // Entities with incoming cross-file edges (CALLS, EXTENDS, etc.) are preserved
-    await this.client.query(CYPHER.CLEANUP_FILE_ORPHANS, { params: { filePath } });
   }
 
   @trace()
   async removeFileContents(filePath: string): Promise<void> {
-    // Step 1: detach CONTAINS edges to this file's child symbols, but leave
-    // the File node (and every other edge on it) untouched. Use this
-    // instead of removeFileAndCleanup() when re-parsing a file whose
-    // content changed: deleting the File node would cascade-delete
-    // MODIFIED_IN / HAS_FILE / EXPORTS and any other edge attached to it.
     await this.client.query(CYPHER.REMOVE_FILE_CONTENTS, { params: { filePath } });
+    await this.client.query(CYPHER.REMOVE_FILE_OUTGOING_EDGES, { params: { filePath } });
+    await this.client.query(CYPHER.REMOVE_SYMBOL_OUTGOING_EDGES, { params: { filePath } });
+  }
 
-    // Step 2: same orphan cleanup as removeFileAndCleanup(). Entities from
-    // this file that now have no incoming cross-file edge are genuinely
-    // dangling (their CONTAINS edge is gone) and get removed; entities
-    // still referenced from elsewhere are preserved so those edges don't leak.
-    await this.client.query(CYPHER.CLEANUP_FILE_ORPHANS, { params: { filePath } });
+  @trace()
+  async sweepStaleFileSymbols(filePath: string, currentIds: readonly string[]): Promise<void> {
+    await this.client.query(CYPHER.SWEEP_STALE_FILE_SYMBOL_IDS, {
+      params: { filePath, currentIds: [...currentIds] },
+    });
   }
 
   @trace()
@@ -1603,6 +1740,10 @@ class GraphOperationsImpl implements GraphOperations {
       ...entities.components.map((comp) => this.upsertComponent(comp)),
     ]);
 
+    await this.client.query(CYPHER.SWEEP_STALE_FILE_SYMBOLS, {
+      params: { filePath: entities.file.path },
+    });
+
     // Create edges in parallel (after entities exist). Call edges are
     // deliberately NOT in this batch: a class-qualified call edge
     // (calleeClassName set) is matched through Class-HAS_METHOD-Function, so
@@ -1615,21 +1756,39 @@ class GraphOperationsImpl implements GraphOperations {
       ),
       // Extends edges (classes) - extract parent file from ID if present
       ...entities.extendsEdges.map((edge) => {
-        const parent = parseEntityId(edge.parentId);
-        const child = parseEntityId(edge.childId);
-        return this.createExtendsEdge(child.name, child.filePath, resolvedName(parent), resolvedFilePath(parent));
+        const parent = edgeEndpoint(edge.parentId);
+        const child = edgeEndpoint(edge.childId);
+        return this.createExtendsEdge(
+          child.name ?? '',
+          child.filePath ?? '',
+          parent.name ?? '',
+          parent.filePath ?? undefined,
+          { childId: child.id ?? undefined, parentId: parent.id ?? undefined },
+        );
       }),
       // Implements edges (class -> interface) - extract interface file from ID if present
       ...entities.implementsEdges.map((edge) => {
-        const iface = parseEntityId(edge.interfaceId);
-        const cls = parseEntityId(edge.classId);
-        return this.createImplementsEdge(cls.name, cls.filePath, resolvedName(iface), resolvedFilePath(iface));
+        const iface = edgeEndpoint(edge.interfaceId);
+        const cls = edgeEndpoint(edge.classId);
+        return this.createImplementsEdge(
+          cls.name ?? '',
+          cls.filePath ?? '',
+          iface.name ?? '',
+          iface.filePath ?? undefined,
+          { classId: cls.id ?? undefined, interfaceId: iface.id ?? undefined },
+        );
       }),
       // Renders edges (components)
       ...entities.rendersEdges.map((edge) => {
-        const parent = parseEntityId(edge.parentId);
-        const child = parseEntityId(edge.childId);
-        return this.createRendersEdge(parent.name, parent.filePath, child.name, edge.line);
+        const parent = edgeEndpoint(edge.parentId);
+        const child = edgeEndpoint(edge.childId);
+        return this.createRendersEdge(
+          parent.name ?? '',
+          parent.filePath ?? '',
+          child.name ?? '',
+          edge.line,
+          { parentId: parent.id ?? undefined, childId: child.id ?? undefined },
+        );
       }),
       // HAS_METHOD edges (class → method Function node)
       ...entities.hasMethodEdges.map((edge) =>
@@ -1641,11 +1800,21 @@ class GraphOperationsImpl implements GraphOperations {
       ),
       // EXPORTS edges (File → exported symbol)
       ...entities.exportsEdges.map((edge) =>
-        this.createExportsEdge(edge.filePath, edge.symbolName, edge.symbolKind, { asName: edge.asName, isDefault: edge.isDefault })
+        this.createExportsEdge(edge.filePath, edge.symbolName, edge.symbolKind, {
+          asName: edge.asName,
+          isDefault: edge.isDefault,
+          fromId: edge.fromId,
+          toId: edge.toId,
+        })
       ),
       // IMPORTS_SYMBOL edges (importing File → imported symbol node)
       ...entities.importsSymbolEdges.map((edge) =>
-        this.createImportsSymbolEdge(edge.fromFilePath, edge.toFilePath, edge.symbolName, { alias: edge.alias, isDefault: edge.isDefault })
+        this.createImportsSymbolEdge(edge.fromFilePath, edge.toFilePath, edge.symbolName, {
+          alias: edge.alias,
+          isDefault: edge.isDefault,
+          fromId: edge.fromId,
+          toId: edge.toId,
+        })
       ),
     ]);
 
@@ -1655,9 +1824,19 @@ class GraphOperationsImpl implements GraphOperations {
     // silently drops the call.
     await Promise.all(
       entities.callEdges.map((edge) => {
-        const caller = parseEntityId(edge.callerId);
-        const callee = parseEntityId(edge.calleeId);
-        return this.createCallEdge(caller.name, caller.filePath, callee.name, callee.filePath, edge.line, edge.callerKind, edge.via, edge.calleeClassName);
+        const caller = edgeEndpoint(edge.callerId);
+        const callee = edgeEndpoint(edge.calleeId);
+        return this.createCallEdge(
+          caller.name ?? '',
+          caller.filePath ?? '',
+          callee.name ?? '',
+          callee.filePath ?? '',
+          edge.line,
+          edge.callerKind,
+          edge.via,
+          edge.calleeClassName,
+          { callerId: caller.id ?? undefined, calleeId: callee.id ?? undefined },
+        );
       }),
     );
 
@@ -1719,17 +1898,25 @@ class GraphOperationsImpl implements GraphOperations {
     if (types.length > 0) await chunkedQuery(CYPHER.BATCH_UPSERT_TYPES, types);
     if (components.length > 0) await chunkedQuery(CYPHER.BATCH_UPSERT_COMPONENTS, components);
 
+    for (const entities of entitiesList) {
+      await this.client.query(CYPHER.SWEEP_STALE_FILE_SYMBOLS, {
+        params: { filePath: entities.file.path },
+      });
+    }
+
     // Collect and batch all edges
     const callEdges = entitiesList.flatMap(e =>
       e.callEdges.map(edge => {
-        const caller = parseEntityId(edge.callerId);
-        const callee = parseEntityId(edge.calleeId);
+        const caller = edgeEndpoint(edge.callerId);
+        const callee = edgeEndpoint(edge.calleeId);
         return {
-          callerName: caller.name,
-          callerFile: caller.filePath,
+          callerId: caller.id,
+          callerName: caller.name ?? '',
+          callerFile: caller.filePath ?? '',
           callerKind: edge.callerKind,
-          calleeName: callee.name,
-          calleeFile: callee.filePath,
+          calleeId: callee.id,
+          calleeName: callee.name ?? '',
+          calleeFile: callee.filePath ?? '',
           line: edge.line,
           via: edge.via,
           calleeClassName: edge.calleeClassName ?? null,
@@ -1745,29 +1932,54 @@ class GraphOperationsImpl implements GraphOperations {
     );
     const extendsEdges = entitiesList.flatMap(e =>
       e.extendsEdges.map(edge => {
-        const parent = parseEntityId(edge.parentId);
-        const child = parseEntityId(edge.childId);
-        return { childName: child.name, childFile: child.filePath, parentName: resolvedName(parent), parentFile: resolvedFilePath(parent) ?? null };
+        const parent = edgeEndpoint(edge.parentId);
+        const child = edgeEndpoint(edge.childId);
+        return {
+          childId: child.id,
+          childName: child.name ?? '',
+          childFile: child.filePath ?? '',
+          parentId: parent.id,
+          parentName: parent.name ?? '',
+          parentFile: parent.filePath,
+        };
       }),
     );
     const implementsEdges = entitiesList.flatMap(e =>
       e.implementsEdges.map(edge => {
-        const iface = parseEntityId(edge.interfaceId);
-        const cls = parseEntityId(edge.classId);
-        return { className: cls.name, classFile: cls.filePath, interfaceName: resolvedName(iface), interfaceFile: resolvedFilePath(iface) ?? null };
+        const iface = edgeEndpoint(edge.interfaceId);
+        const cls = edgeEndpoint(edge.classId);
+        return {
+          classId: cls.id,
+          className: cls.name ?? '',
+          classFile: cls.filePath ?? '',
+          interfaceId: iface.id,
+          interfaceName: iface.name ?? '',
+          interfaceFile: iface.filePath,
+        };
       }),
     );
     const rendersEdges = entitiesList.flatMap(e =>
       e.rendersEdges.map(edge => {
-        const parent = parseEntityId(edge.parentId);
-        const child = parseEntityId(edge.childId);
-        return { parentName: parent.name, parentFile: parent.filePath, childName: child.name, line: edge.line };
+        const parent = edgeEndpoint(edge.parentId);
+        const child = edgeEndpoint(edge.childId);
+        return {
+          parentId: parent.id,
+          parentName: parent.name ?? '',
+          parentFile: parent.filePath ?? '',
+          childId: child.id,
+          childName: child.name ?? '',
+          line: edge.line,
+        };
       }),
     );
 
     // Create edges individually to avoid FalkorDB UNWIND+MATCH crash (Record_GetType segfault)
     const safeEdge = async (cypher: string, params: Record<string, unknown>): Promise<void> => {
-      try { await this.client.query(cypher, { params: params as QueryParams }); } catch { /* skip missing endpoints */ }
+      try {
+        await this.client.query(cypher, { params: params as QueryParams });
+      } catch (error) {
+        logger.debug('Skipped edge write with missing or unavailable endpoints', error);
+      }
     };
     for (const e of importEdges) {
       await safeEdge(
@@ -1778,28 +1990,13 @@ class GraphOperationsImpl implements GraphOperations {
       );
     }
     for (const e of extendsEdges) {
-      await safeEdge(
-        `MATCH (child:Class {name: $childName, filePath: $childFile})
-         MERGE (parent:Class {name: $parentName, filePath: COALESCE($parentFile, 'external')}) ON CREATE SET parent:External
-         MERGE (child)-[ex:EXTENDS]->(parent)`,
-        e,
-      );
+      await safeEdge(e.parentId ? CYPHER.CREATE_EXTENDS_EDGE_BY_ID : CYPHER.CREATE_EXTENDS_EDGE, e);
     }
     for (const e of implementsEdges) {
-      await safeEdge(
-        `MATCH (c:Class {name: $className, filePath: $classFile})
-         MERGE (i:Interface {name: $interfaceName, filePath: COALESCE($interfaceFile, 'external')}) ON CREATE SET i:External
-         MERGE (c)-[impl:IMPLEMENTS]->(i)`,
-        e,
-      );
+      await safeEdge(e.interfaceId ? CYPHER.CREATE_IMPLEMENTS_EDGE_BY_ID : CYPHER.CREATE_IMPLEMENTS_EDGE, e);
     }
     for (const e of rendersEdges) {
-      await safeEdge(
-        `MATCH (parent:Component {name: $parentName, filePath: $parentFile})
-         MATCH (child:Component {name: $childName})
-         MERGE (parent)-[r:RENDERS]->(child) SET r.line = $line`,
-        e,
-      );
+      await safeEdge(CYPHER.CREATE_RENDERS_EDGE, e);
     }
 
     // HAS_METHOD edges (class → method Function node)
@@ -1823,7 +2020,8 @@ class GraphOperationsImpl implements GraphOperations {
     // today and the qualified path can never drift out of sync with the
     // canonical template.
     for (const e of callEdges) {
-      await safeEdge(e.calleeClassName ? CYPHER.CREATE_CALLS_EDGE_BY_CLASS : CYPHER.CREATE_CALLS_EDGE, e);
+      const usesCanonicalIds = e.callerId !== null || e.calleeId !== null;
+      await safeEdge(e.calleeClassName && !usesCanonicalIds ? CYPHER.CREATE_CALLS_EDGE_BY_CLASS : CYPHER.CREATE_CALLS_EDGE, e);
     }
 
     // HAS_PROPERTY edges (class → property Variable node)
@@ -1889,12 +2087,16 @@ class GraphOperationsImpl implements GraphOperations {
     const exportsEdges: ExportsEdgeDescriptor[] = entitiesList.flatMap(e => e.exportsEdges);
     for (const e of exportsEdges) {
       await safeEdge(
-        `MATCH (f:File {filePath: $filePath})
-         MATCH (symbol {name: $symbolName, filePath: $filePath})
-         WHERE labels(symbol)[0] = $symbolKind
-         MERGE (f)-[r:EXPORTS]->(symbol)
-         SET r.asName = $asName, r.isDefault = $isDefault`,
-        { filePath: e.filePath, symbolName: e.symbolName, symbolKind: e.symbolKind, asName: e.asName ?? null, isDefault: e.isDefault ?? null },
+        CYPHER.CREATE_EXPORTS_EDGE,
+        {
+          fromId: e.fromId ?? null,
+          toId: e.toId ?? null,
+          filePath: e.filePath,
+          symbolName: e.symbolName,
+          symbolKind: e.symbolKind,
+          asName: e.asName ?? null,
+          isDefault: e.isDefault ?? null,
+        },
       );
     }
 
@@ -1905,11 +2107,16 @@ class GraphOperationsImpl implements GraphOperations {
     const importsSymbolEdges: ImportsSymbolEdgeDescriptor[] = entitiesList.flatMap(e => e.importsSymbolEdges);
     for (const e of importsSymbolEdges) {
       await safeEdge(
-        `MATCH (from:File {filePath: $fromFilePath})
-         MATCH (symbol {name: $symbolName, filePath: $toFilePath})
-         MERGE (from)-[r:IMPORTS_SYMBOL]->(symbol)
-         SET r.alias = $alias, r.isDefault = $isDefault`,
-        { fromFilePath: e.fromFilePath, toFilePath: e.toFilePath, symbolName: e.symbolName, alias: e.alias ?? null, isDefault: e.isDefault },
+        CYPHER.CREATE_IMPORTS_SYMBOL_EDGE,
+        {
+          fromId: e.fromId ?? null,
+          toId: e.toId ?? null,
+          fromFilePath: e.fromFilePath,
+          toFilePath: e.toFilePath,
+          symbolName: e.symbolName,
+          alias: e.alias ?? null,
+          isDefault: e.isDefault,
+        },
       );
     }
   }
@@ -1954,14 +2161,16 @@ class GraphOperationsImpl implements GraphOperations {
     // Create edges (same as batchUpsertBulk — edges always use MERGE for idempotency)
     const callEdges = entitiesList.flatMap(e =>
       e.callEdges.map(edge => {
-        const caller = parseEntityId(edge.callerId);
-        const callee = parseEntityId(edge.calleeId);
+        const caller = edgeEndpoint(edge.callerId);
+        const callee = edgeEndpoint(edge.calleeId);
         return {
-          callerName: caller.name,
-          callerFile: caller.filePath,
+          callerId: caller.id,
+          callerName: caller.name ?? '',
+          callerFile: caller.filePath ?? '',
           callerKind: edge.callerKind,
-          calleeName: callee.name,
-          calleeFile: callee.filePath,
+          calleeId: callee.id,
+          calleeName: callee.name ?? '',
+          calleeFile: callee.filePath ?? '',
           line: edge.line,
           via: edge.via,
           calleeClassName: edge.calleeClassName ?? null,
@@ -1977,30 +2186,55 @@ class GraphOperationsImpl implements GraphOperations {
     );
     const extendsEdges = entitiesList.flatMap(e =>
       e.extendsEdges.map(edge => {
-        const parent = parseEntityId(edge.parentId);
-        const child = parseEntityId(edge.childId);
-        return { childName: child.name, childFile: child.filePath, parentName: resolvedName(parent), parentFile: resolvedFilePath(parent) ?? null };
+        const parent = edgeEndpoint(edge.parentId);
+        const child = edgeEndpoint(edge.childId);
+        return {
+          childId: child.id,
+          childName: child.name ?? '',
+          childFile: child.filePath ?? '',
+          parentId: parent.id,
+          parentName: parent.name ?? '',
+          parentFile: parent.filePath,
+        };
       }),
     );
     const implementsEdges = entitiesList.flatMap(e =>
       e.implementsEdges.map(edge => {
-        const iface = parseEntityId(edge.interfaceId);
-        const cls = parseEntityId(edge.classId);
-        return { className: cls.name, classFile: cls.filePath, interfaceName: resolvedName(iface), interfaceFile: resolvedFilePath(iface) ?? null };
+        const iface = edgeEndpoint(edge.interfaceId);
+        const cls = edgeEndpoint(edge.classId);
+        return {
+          classId: cls.id,
+          className: cls.name ?? '',
+          classFile: cls.filePath ?? '',
+          interfaceId: iface.id,
+          interfaceName: iface.name ?? '',
+          interfaceFile: iface.filePath,
+        };
       }),
     );
     const rendersEdges = entitiesList.flatMap(e =>
       e.rendersEdges.map(edge => {
-        const parent = parseEntityId(edge.parentId);
-        const child = parseEntityId(edge.childId);
-        return { parentName: parent.name, parentFile: parent.filePath, childName: child.name, line: edge.line };
+        const parent = edgeEndpoint(edge.parentId);
+        const child = edgeEndpoint(edge.childId);
+        return {
+          parentId: parent.id,
+          parentName: parent.name ?? '',
+          parentFile: parent.filePath ?? '',
+          childId: child.id,
+          childName: child.name ?? '',
+          line: edge.line,
+        };
       }),
     );
 
     // Create edges individually to avoid FalkorDB UNWIND+MATCH crash (Record_GetType segfault).
     // This is slower but stable. FalkorDB crashes on UNWIND+MATCH edge queries on arm64.
     const safeEdge = async (cypher: string, params: Record<string, unknown>): Promise<void> => {
-      try { await this.client.query(cypher, { params: params as QueryParams }); } catch { /* skip missing endpoints */ }
+      try {
+        await this.client.query(cypher, { params: params as QueryParams });
+      } catch (error) {
+        logger.debug('Skipped edge write with missing or unavailable endpoints', error);
+      }
     };
     for (const e of importEdges) {
       await safeEdge(
@@ -2011,28 +2245,13 @@ class GraphOperationsImpl implements GraphOperations {
       );
     }
     for (const e of extendsEdges) {
-      await safeEdge(
-        `MATCH (child:Class {name: $childName, filePath: $childFile})
-         MERGE (parent:Class {name: $parentName, filePath: COALESCE($parentFile, 'external')}) ON CREATE SET parent:External
-         MERGE (child)-[ex:EXTENDS]->(parent)`,
-        e,
-      );
+      await safeEdge(e.parentId ? CYPHER.CREATE_EXTENDS_EDGE_BY_ID : CYPHER.CREATE_EXTENDS_EDGE, e);
     }
     for (const e of implementsEdges) {
-      await safeEdge(
-        `MATCH (c:Class {name: $className, filePath: $classFile})
-         MERGE (i:Interface {name: $interfaceName, filePath: COALESCE($interfaceFile, 'external')}) ON CREATE SET i:External
-         MERGE (c)-[impl:IMPLEMENTS]->(i)`,
-        e,
-      );
+      await safeEdge(e.interfaceId ? CYPHER.CREATE_IMPLEMENTS_EDGE_BY_ID : CYPHER.CREATE_IMPLEMENTS_EDGE, e);
     }
     for (const e of rendersEdges) {
-      await safeEdge(
-        `MATCH (parent:Component {name: $parentName, filePath: $parentFile})
-         MATCH (child:Component {name: $childName})
-         MERGE (parent)-[r:RENDERS]->(child) SET r.line = $line`,
-        e,
-      );
+      await safeEdge(CYPHER.CREATE_RENDERS_EDGE, e);
     }
 
     // HAS_METHOD edges (class → method Function node)
@@ -2056,7 +2275,8 @@ class GraphOperationsImpl implements GraphOperations {
     // today and the qualified path can never drift out of sync with the
     // canonical template.
     for (const e of callEdges) {
-      await safeEdge(e.calleeClassName ? CYPHER.CREATE_CALLS_EDGE_BY_CLASS : CYPHER.CREATE_CALLS_EDGE, e);
+      const usesCanonicalIds = e.callerId !== null || e.calleeId !== null;
+      await safeEdge(e.calleeClassName && !usesCanonicalIds ? CYPHER.CREATE_CALLS_EDGE_BY_CLASS : CYPHER.CREATE_CALLS_EDGE, e);
     }
 
     // HAS_PROPERTY edges (class → property Variable node)
@@ -2122,12 +2342,16 @@ class GraphOperationsImpl implements GraphOperations {
     const exportsEdges: ExportsEdgeDescriptor[] = entitiesList.flatMap(e => e.exportsEdges);
     for (const e of exportsEdges) {
       await safeEdge(
-        `MATCH (f:File {filePath: $filePath})
-         MATCH (symbol {name: $symbolName, filePath: $filePath})
-         WHERE labels(symbol)[0] = $symbolKind
-         MERGE (f)-[r:EXPORTS]->(symbol)
-         SET r.asName = $asName, r.isDefault = $isDefault`,
-        { filePath: e.filePath, symbolName: e.symbolName, symbolKind: e.symbolKind, asName: e.asName ?? null, isDefault: e.isDefault ?? null },
+        CYPHER.CREATE_EXPORTS_EDGE,
+        {
+          fromId: e.fromId ?? null,
+          toId: e.toId ?? null,
+          filePath: e.filePath,
+          symbolName: e.symbolName,
+          symbolKind: e.symbolKind,
+          asName: e.asName ?? null,
+          isDefault: e.isDefault ?? null,
+        },
       );
     }
 
@@ -2138,11 +2362,16 @@ class GraphOperationsImpl implements GraphOperations {
     const importsSymbolEdges: ImportsSymbolEdgeDescriptor[] = entitiesList.flatMap(e => e.importsSymbolEdges);
     for (const e of importsSymbolEdges) {
       await safeEdge(
-        `MATCH (from:File {filePath: $fromFilePath})
-         MATCH (symbol {name: $symbolName, filePath: $toFilePath})
-         MERGE (from)-[r:IMPORTS_SYMBOL]->(symbol)
-         SET r.alias = $alias, r.isDefault = $isDefault`,
-        { fromFilePath: e.fromFilePath, toFilePath: e.toFilePath, symbolName: e.symbolName, alias: e.alias ?? null, isDefault: e.isDefault },
+        CYPHER.CREATE_IMPORTS_SYMBOL_EDGE,
+        {
+          fromId: e.fromId ?? null,
+          toId: e.toId ?? null,
+          fromFilePath: e.fromFilePath,
+          toFilePath: e.toFilePath,
+          symbolName: e.symbolName,
+          alias: e.alias ?? null,
+          isDefault: e.isDefault,
+        },
       );
     }
   }
@@ -2152,6 +2381,7 @@ class GraphOperationsImpl implements GraphOperations {
     if (filePaths.length === 0) return;
     const items = filePaths.map(fp => ({ projectId, filePath: fp }));
     await this.client.query(CYPHER.BATCH_LINK_PROJECT_FILES, { params: { items } });
+    await this.client.query(CYPHER.BATCH_STAMP_FILE_SYMBOL_OWNERSHIP, { params: { items } });
   }
 
   @trace()
@@ -2205,6 +2435,12 @@ class GraphOperationsImpl implements GraphOperations {
     if (sectionHierarchy.length > 0) {
       await this.client.query(CYPHER.BATCH_CREATE_PARENT_SECTION_EDGES, { params: { items: sectionHierarchy } });
     }
+
+    for (const doc of docsList) {
+      await this.client.query(CYPHER.STAMP_DOCUMENT_PROJECT_OWNERSHIP, {
+        params: { documentPath: doc.document.path },
+      });
+    }
   }
 
   @trace()
@@ -2219,6 +2455,12 @@ class GraphOperationsImpl implements GraphOperations {
     // Group items by node type
     const byType = new Map<string, Array<Record<string, unknown>>>();
     for (const item of items) {
+      if (item.nodeType !== 'File') {
+        const id = item.identifier['id'];
+        if (typeof id !== 'string' || id.length === 0) {
+          throw new Error(`Canonical id is required to update a ${item.nodeType} embedding`);
+        }
+      }
       const key = item.nodeType;
       if (!byType.has(key)) byType.set(key, []);
       byType.get(key)!.push({
@@ -2253,7 +2495,7 @@ class GraphOperationsImpl implements GraphOperations {
   async getEmbeddingHashesForFiles(filePaths: string[]): Promise<Map<string, string>> {
     if (filePaths.length === 0) return new Map();
 
-    // Build a map of "nodeType:name:filePath:startLine" → embeddingTextHash
+    // Source embedding hashes use the same opaque persisted identity as writes.
     const hashMap = new Map<string, string>();
 
     // Process in chunks to avoid query size limits
@@ -2266,6 +2508,7 @@ class GraphOperationsImpl implements GraphOperations {
           fileHash: string | null;
           entityHashes: Array<{
             nodeType: string;
+            id: string;
             name: string;
             filePath: string;
             startLine: number;
@@ -2278,8 +2521,8 @@ class GraphOperationsImpl implements GraphOperations {
             hashMap.set(`File::${row.filePath}:0`, row.fileHash);
           }
           for (const entity of row.entityHashes) {
-            if (entity.hash) {
-              hashMap.set(`${entity.nodeType}:${entity.name}:${entity.filePath}:${entity.startLine}`, entity.hash);
+            if (entity.hash && entity.id) {
+              hashMap.set(entity.id, entity.hash);
             }
           }
         }
@@ -2348,6 +2591,9 @@ class GraphOperationsImpl implements GraphOperations {
     await this.client.query(CYPHER.LINK_PROJECT_FILE, {
       params: { projectId, filePath },
     });
+    await this.client.query(CYPHER.STAMP_FILE_SYMBOL_OWNERSHIP, {
+      params: { projectId, filePath },
+    });
   }
 
   @trace()
@@ -2436,6 +2682,11 @@ class GraphOperationsImpl implements GraphOperations {
       return;
     }
 
+    const id = identifier['id'];
+    if (typeof id !== 'string' || id.length === 0) {
+      throw new Error(`Canonical id is required to update a ${nodeType} embedding`);
+    }
+
     // FalkorDB uses natural keys (name + filePath + startLine/line)
     const templates: Record<string, string> = {
       Function: CYPHER.UPDATE_FUNCTION_EMBEDDING,
@@ -2445,7 +2696,7 @@ class GraphOperationsImpl implements GraphOperations {
       Type: CYPHER.UPDATE_TYPE_EMBEDDING,
       Component: CYPHER.UPDATE_COMPONENT_EMBEDDING,
     };
-    await this.client.query(templates[nodeType]!, { params: { ...baseParams, ...identifier } });
+    await this.client.query(templates[nodeType]!, { params: { ...baseParams, ...identifier, id } });
   }
 
   // --- Vector Search ---
diff --git a/packages/graph/src/queries.ts b/packages/graph/src/queries.ts
index c14da3e8..cd4a4a58 100644
--- a/packages/graph/src/queries.ts
+++ b/packages/graph/src/queries.ts
@@ -6,6 +6,7 @@
 
 import type { GraphClient } from './client';
 import type { CypherDialect } from './driver';
+import { deriveEntityId } from './knowledge-operations';
 import { trace } from '@codegraph/logger';
 import { REFERENCEABLE_LABELS, SYMBOL_LABELS, resolveNodeLabel } from '@codegraph/types';
 import type {
@@ -95,11 +96,28 @@ function projectDashboardProperties(props: Record<string, unknown>): Record<stri
   return projectDashboardValue(props) as Record<string, unknown>;
 }
 
+function persistedNodeId(props: Record<string, unknown>, label?: DashboardNodeLabel): string {
+  const id = props['id'];
+  if (typeof id === 'string' && id.length > 0) {
+    return id;
+  }
+  if (label === 'Entity') {
+    const text = typeof props['text'] === 'string' ? props['text'] : '';
+    const type = typeof props['type'] === 'string' ? props['type'] : '';
+    return deriveEntityId(text, type);
+  }
+  if (label === 'File') {
+    const filePath = typeof props['filePath'] === 'string' ? props['filePath'] : '';
+    return `File:${filePath}`;
+  }
+  throw new Error('Graph node is missing a persisted id');
+}
+
 function nodeToGraphNode(node: Record<string, unknown>, labels: string[], dialect?: CypherDialect): GraphNode {
   const actualLabels = extractLabels(node, labels, dialect);
   const props = extractNodeProps(node, dialect);
   const label = getLabelFromLabels(actualLabels);
-  const id = generateNodeIdFromProps(label, props);
+  const id = persistedNodeId(props, label);
   const dashboardProps = projectDashboardProperties(props);
 
   return {
@@ -111,34 +129,20 @@ function nodeToGraphNode(node: Record<string, unknown>, labels: string[], dialec
   } as unknown as GraphNode;
 }
 
-function generateNodeIdFromProps(label: DashboardNodeLabel, node: Record<string, unknown>): string {
-  if (label === 'File') {
-    return `File:${node['filePath'] ?? ''}`;
-  }
-  if (label === 'Entity') {
-    return `Entity:${node['type'] ?? ''}:${node['text'] ?? ''}`;
-  }
-  const name = node['name'] ?? '';
-  const filePath = node['filePath'] ?? '';
-  const line = node['startLine'] ?? node['line'] ?? 0;
-  return `${label}:${filePath}:${name}:${line}`;
-}
-
-
 function edgeToGraphEdge(
   fromNode: Record<string, unknown>,
   toNode: Record<string, unknown>,
   edgeType: string,
   edgeProps: Record<string, unknown>,
   fromLabels: string[],
-  toLabels: string[]
+  toLabels: string[],
 ): GraphEdge {
-  const fromId = generateNodeIdFromProps(getLabelFromLabels(fromLabels), fromNode);
-  const toId = generateNodeIdFromProps(getLabelFromLabels(toLabels), toNode);
+  const fromId = persistedNodeId(fromNode, getLabelFromLabels(fromLabels));
+  const toId = persistedNodeId(toNode, getLabelFromLabels(toLabels));
   const dashboardProps = projectDashboardProperties(edgeProps);
 
   return {
-    id: `${edgeType}:${fromId}->${toId}`,
+    id: JSON.stringify([edgeType, fromId, toId]),
     source: fromId,
     target: toId,
     label: edgeType as EdgeLabel,
@@ -291,6 +295,8 @@ export type ReferenceEdgeType = (typeof REFERENCE_EDGE_TYPES)[number];
 
 /** One place a symbol is used, and how. */
 export interface SymbolReference {
+  /** Persisted opaque id of the referencing symbol. */
+  id: string;
   /** Name of the referencing symbol. */
   name: string;
   nodeType: string;
@@ -310,10 +316,8 @@ export interface SymbolReferencesResult {
 }
 
 export interface SymbolReferenceQuery {
-  name: string;
-  /** Declaring file, used to disambiguate symbols that share a name. */
-  filePath?: string | undefined;
-  startLine?: number | undefined;
+  /** Persisted opaque id of the declaration being referenced. */
+  id: string;
   limit?: number | undefined;
 }
 
@@ -381,6 +385,23 @@ function rowsToGraphNodes(
   return [...nodes.values()];
 }
 
+function pathNodes(value: unknown): Array<Record<string, unknown>> {
+  if (Array.isArray(value)) {
+    return value.filter((node): node is Record<string, unknown> => (
+      node !== null && typeof node === 'object' && !Array.isArray(node)
+    ));
+  }
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    const nodes = (value as Record<string, unknown>)['nodes'];
+    if (Array.isArray(nodes)) {
+      return nodes.filter((node): node is Record<string, unknown> => (
+        node !== null && typeof node === 'object' && !Array.isArray(node)
+      ));
+    }
+  }
+  return [];
+}
+
 class GraphQueriesImpl implements GraphQueries {
   private readonly dialect: CypherDialect;
   private readonly templates: ReturnType<typeof buildCypherTemplates>;
@@ -439,16 +460,13 @@ class GraphQueriesImpl implements GraphQueries {
     for (const row of edgesResult.data ?? []) {
       const fromProps = extractNodeProps(row.a, this.dialect);
       const toProps = extractNodeProps(row.b, this.dialect);
-      const fromLabels = row.fromLabels ?? extractLabels(row.a, [], this.dialect);
-      const toLabels = row.toLabels ?? extractLabels(row.b, [], this.dialect);
-
       const edge = edgeToGraphEdge(
         fromProps,
         toProps,
         row.edgeType,
         row.r,
-        fromLabels,
-        toLabels,
+        row.fromLabels,
+        row.toLabels,
       );
       if (nodeIds.has(edge.source) && nodeIds.has(edge.target)) {
         edges.push(edge);
@@ -495,7 +513,7 @@ class GraphQueriesImpl implements GraphQueries {
 
         // Add CONTAINS edge
         edges.push({
-          id: `CONTAINS:${fileNode.id}->${entityNode.id}`,
+          id: JSON.stringify(['CONTAINS', fileNode.id, entityNode.id]),
           source: fileNode.id,
           target: entityNode.id,
           label: 'CONTAINS',
@@ -519,7 +537,7 @@ class GraphQueriesImpl implements GraphQueries {
           row.edgeType,
           row.r,
           row.labels,
-          row.relatedLabels
+          row.relatedLabels,
         );
 
         // Avoid duplicate edges
@@ -564,16 +582,15 @@ class GraphQueriesImpl implements GraphQueries {
     // FalkorDB doesn't support variable-length path parameters
     const depthParam = Math.min(depth, 10);
 
-    const result = await this.client.roQuery<{
-      path: Array<Record<string, unknown>>;
-    }>(this.templates.GET_DEPENDENCY_TREE.replace('$depth', String(depthParam)), {
+    const result = await this.client.roQuery<{ path: unknown }>(
+      this.templates.GET_DEPENDENCY_TREE.replace('$depth', String(depthParam)), {
       params: { filePath },
     });
 
     for (const row of result.data ?? []) {
-      const pathNodes = row.path;
-      for (let i = 0; i < pathNodes.length; i++) {
-        const node = pathNodes[i]!;
+      const nodesInPath = pathNodes(row.path);
+      for (let i = 0; i < nodesInPath.length; i++) {
+        const node = nodesInPath[i]!;
         const graphNode = nodeToGraphNode(node, ['File'], this.dialect);
         if (!nodeIds.has(graphNode.id)) {
           nodes.push(graphNode);
@@ -581,12 +598,12 @@ class GraphQueriesImpl implements GraphQueries {
         }
 
         // Create edge to next node in path
-        if (i < pathNodes.length - 1) {
-          const nextNode = pathNodes[i + 1]!;
+        if (i < nodesInPath.length - 1) {
+          const nextNode = nodesInPath[i + 1]!;
           const nextProps = extractNodeProps(nextNode, this.dialect);
           const fromId = graphNode.id;
-          const toId = generateNodeIdFromProps('File', nextProps);
-          const edgeId = `IMPORTS:${fromId}->${toId}`;
+          const toId = persistedNodeId(nextProps);
+          const edgeId = JSON.stringify(['IMPORTS', fromId, toId]);
 
           if (!edges.some((e) => e.id === edgeId)) {
             edges.push({
@@ -713,102 +730,47 @@ class GraphQueriesImpl implements GraphQueries {
   @trace()
   async getSymbolReferences(query: SymbolReferenceQuery): Promise<SymbolReferencesResult> {
     const limit = Math.min(Math.max(query.limit ?? 200, 1), 1000);
-
-    // An empty `?path=` query string arrives as '', not undefined. Treated as
-    // a real value it becomes `filePath = ''`, which no real node ever
-    // matches, so normalize it to "not supplied" up front.
-    const filePath = query.filePath === '' ? undefined : query.filePath;
-
-    // A symbol can be represented by more than one node: a declaration
-    // (Interface/Class/Type/Function/...) with a real filePath, and a TypeRef
-    // proxy node with filePath = null that USES_TYPE/HAS_PARAM/RETURNS edges
-    // actually land on. Matching every node with this name, rather than
-    // pinning to a single one, means references landing on either kind of
-    // node are found. The expansion still starts from named nodes, not the
-    // edge side, so it does not scan every relationship of these types in
-    // the graph.
-    //
-    // A node with no filePath has nothing for filePath/startLine to
-    // disambiguate against, so those filters only ever exclude a node that
-    // carries a location that disagrees with the request. That keeps this
-    // correct today (TypeRef's filePath is always null) and later, once
-    // TypeRef nodes carry a real filePath, when the plain equality check
-    // starts doing the disambiguation on its own.
-
-    const targetFilters = ['target.name = $name'];
-    if (filePath !== undefined) {
-      targetFilters.push('(target.filePath IS NULL OR target.filePath = $filePath)');
-    }
-    if (query.startLine !== undefined) {
-      targetFilters.push('(target.filePath IS NULL OR target.startLine = $startLine)');
-    }
-
-    // "Same file" is a property of the edge, not of the query. Two genuine
-    // declarations can share this name in different files, each with its own
-    // same-file caller, so the file to compare against must come from the
-    // specific target that row's own edge points at (target.filePath), never
-    // from a single value chosen once for the whole batch.
-    //
-    // A TypeRef proxy node breaks that plan: its filePath is always null, so
-    // a reference landing there carries no location of its own. matchedFilePath
-    // is the fallback for exactly that row shape, computed once up front. It
-    // is only safe to use when the matched target set implies exactly one
-    // real declaring file: with two or more distinct non-null filePaths among
-    // the matched targets (two genuine declarations sharing this name in
-    // different files), picking "whichever one Cypher returned first" is the
-    // same batch-wide misattribution this whole rewrite exists to remove, so
-    // matchedFilePath comes back null instead and the proxy row's sameFile
-    // honestly reports "cannot tell" rather than guessing. filePath, when the
-    // caller supplied it, is preferred over that inference since it is the
-    // caller's own assertion of which declaration it means.
     const cypher = `
+      MATCH (selected)
+      WHERE selected.id = $id AND (${REFERENCEABLE_LABELS.map((label) => this.dialect.labelCheckExpr('selected', label)).join(' OR ')})
       MATCH (target)
-      WHERE ${targetFilters.join(' AND ')}
-      WITH collect(DISTINCT target) AS targets, collect(DISTINCT target.filePath) AS filePaths
-      WITH targets, [fp IN filePaths WHERE fp IS NOT NULL] AS realFilePaths
-      WITH targets, CASE WHEN size(realFilePaths) = 1 THEN realFilePaths[0] ELSE null END AS matchedFilePath
-      UNWIND targets AS target
+      WHERE target.id = selected.id
       MATCH (source)-[r:${REFERENCE_EDGE_TYPES.join('|')}]->(target)
-      WHERE source.name IS NOT NULL
+      WHERE source.id IS NOT NULL AND source.name IS NOT NULL
       RETURN DISTINCT
+        source.id AS id,
         source.name AS name,
         labels(source)[0] AS nodeType,
         source.filePath AS filePath,
         source.startLine AS startLine,
         type(r) AS edgeType,
-        target.filePath AS targetFilePath,
-        matchedFilePath
+        selected.filePath AS declaringFilePath
       LIMIT ${limit + 1}
     `;
 
-    const params: Record<string, unknown> = { name: query.name };
-    if (filePath !== undefined) params['filePath'] = filePath;
-    if (query.startLine !== undefined) params['startLine'] = query.startLine;
-
     const result = await this.client.roQuery<{
+      id: string;
       name: string;
       nodeType: string;
       filePath: string | null;
       startLine: number | null;
       edgeType: ReferenceEdgeType;
-      targetFilePath: string | null;
-      matchedFilePath: string | null;
-    }>(cypher, { params: params as never });
+      declaringFilePath: string | null;
+    }>(cypher, { params: { id: query.id } });
 
     const rows = result.data ?? [];
     const truncated = rows.length > limit;
-    const fallbackFilePath = filePath ?? rows[0]?.matchedFilePath ?? undefined;
-    const references: SymbolReference[] = rows.slice(0, limit).map((row) => {
-      const declaringFilePath = row.targetFilePath ?? fallbackFilePath;
-      return {
-        name: row.name,
-        nodeType: row.nodeType,
-        filePath: row.filePath ?? '',
-        startLine: row.startLine ?? undefined,
-        edgeType: row.edgeType,
-        sameFile: row.filePath != null && declaringFilePath != null && row.filePath === declaringFilePath,
-      };
-    });
+    const references: SymbolReference[] = rows.slice(0, limit).map((row) => ({
+      id: row.id,
+      name: row.name,
+      nodeType: row.nodeType,
+      filePath: row.filePath ?? '',
+      startLine: row.startLine ?? undefined,
+      edgeType: row.edgeType,
+      sameFile: row.filePath != null
+        && row.declaringFilePath != null
+        && row.filePath === row.declaringFilePath,
+    }));
 
     const referencingFiles = Array.from(
       new Set(references.filter((r) => !r.sameFile && r.filePath !== '').map((r) => r.filePath)),
diff --git a/packages/graph/src/schema.ts b/packages/graph/src/schema.ts
index aab2bf58..86336cd2 100644
--- a/packages/graph/src/schema.ts
+++ b/packages/graph/src/schema.ts
@@ -43,6 +43,7 @@ export interface ProvenanceNodeProps {
  * File node properties for Cypher operations
  */
 export interface FileNodeProps extends ProvenanceNodeProps {
+  id: string;
   filePath: string;
   name: string;
   extension: string;
@@ -57,7 +58,9 @@ export interface FileNodeProps extends ProvenanceNodeProps {
  * Function node properties for Cypher operations
  */
 export interface FunctionNodeProps extends ProvenanceNodeProps {
-  id: string | null;
+  id: string;
+  scopeKey: string;
+  disambiguator: string;
   name: string;
   filePath: string;
   startLine: number;
@@ -80,7 +83,9 @@ export interface FunctionNodeProps extends ProvenanceNodeProps {
  * Class node properties for Cypher operations
  */
 export interface ClassNodeProps extends ProvenanceNodeProps {
-  id: string | null;
+  id: string;
+  scopeKey: string;
+  disambiguator: string;
   name: string;
   filePath: string;
   startLine: number;
@@ -98,7 +103,9 @@ export interface ClassNodeProps extends ProvenanceNodeProps {
  * Interface node properties for Cypher operations
  */
 export interface InterfaceNodeProps extends ProvenanceNodeProps {
-  id: string | null;
+  id: string;
+  scopeKey: string;
+  disambiguator: string;
   name: string;
   filePath: string;
   startLine: number;
@@ -114,7 +121,9 @@ export interface InterfaceNodeProps extends ProvenanceNodeProps {
  * Variable node properties for Cypher operations
  */
 export interface VariableNodeProps extends ProvenanceNodeProps {
-  id: string | null;
+  id: string;
+  scopeKey: string;
+  disambiguator: string;
   name: string;
   filePath: string;
   line: number;
@@ -129,6 +138,9 @@ export interface VariableNodeProps extends ProvenanceNodeProps {
  * Type node properties for Cypher operations
  */
 export interface TypeNodeProps extends ProvenanceNodeProps {
+  id: string;
+  scopeKey: string;
+  disambiguator: string;
   name: string;
   filePath: string;
   startLine: number;
@@ -144,6 +156,9 @@ export interface TypeNodeProps extends ProvenanceNodeProps {
  * Component node properties for Cypher operations
  */
 export interface ComponentNodeProps extends ProvenanceNodeProps {
+  id: string;
+  scopeKey: string;
+  disambiguator: string;
   name: string;
   filePath: string;
   startLine: number;
@@ -221,6 +236,7 @@ export interface LinkNodeProps {
  */
 export function fileToNodeProps(entity: FileEntity): FileNodeProps {
   return {
+    id: entity.id ?? generateFileNodeId(entity.path),
     filePath: entity.path,
     name: entity.name,
     extension: entity.extension,
@@ -238,7 +254,9 @@ export function fileToNodeProps(entity: FileEntity): FileNodeProps {
  */
 export function functionToNodeProps(entity: FunctionEntity): FunctionNodeProps {
   return {
-    id: entity.id ?? null,
+    id: entity.id,
+    scopeKey: entity.scopeKey ?? '',
+    disambiguator: entity.disambiguator ?? '',
     name: entity.name,
     filePath: entity.filePath,
     startLine: entity.startLine,
@@ -264,7 +282,9 @@ export function functionToNodeProps(entity: FunctionEntity): FunctionNodeProps {
  */
 export function classToNodeProps(entity: ClassEntity): ClassNodeProps {
   return {
-    id: entity.id ?? null,
+    id: entity.id,
+    scopeKey: entity.scopeKey ?? '',
+    disambiguator: entity.disambiguator ?? '',
     name: entity.name,
     filePath: entity.filePath,
     startLine: entity.startLine,
@@ -285,7 +305,9 @@ export function classToNodeProps(entity: ClassEntity): ClassNodeProps {
  */
 export function interfaceToNodeProps(entity: InterfaceEntity): InterfaceNodeProps {
   return {
-    id: entity.id ?? null,
+    id: entity.id,
+    scopeKey: entity.scopeKey ?? '',
+    disambiguator: entity.disambiguator ?? '',
     name: entity.name,
     filePath: entity.filePath,
     startLine: entity.startLine,
@@ -304,7 +326,9 @@ export function interfaceToNodeProps(entity: InterfaceEntity): InterfaceNodeProp
  */
 export function variableToNodeProps(entity: VariableEntity): VariableNodeProps {
   return {
-    id: entity.id ?? null,
+    id: entity.id,
+    scopeKey: entity.scopeKey ?? '',
+    disambiguator: entity.disambiguator ?? '',
     name: entity.name,
     filePath: entity.filePath,
     line: entity.line,
@@ -322,6 +346,9 @@ export function variableToNodeProps(entity: VariableEntity): VariableNodeProps {
  */
 export function typeToNodeProps(entity: TypeEntity): TypeNodeProps {
   return {
+    id: entity.id,
+    scopeKey: entity.scopeKey ?? '',
+    disambiguator: entity.disambiguator ?? '',
     name: entity.name,
     filePath: entity.filePath,
     startLine: entity.startLine,
@@ -340,6 +367,9 @@ export function typeToNodeProps(entity: TypeEntity): TypeNodeProps {
  */
 export function componentToNodeProps(entity: ComponentEntity): ComponentNodeProps {
   return {
+    id: entity.id,
+    scopeKey: entity.scopeKey ?? '',
+    disambiguator: entity.disambiguator ?? '',
     name: entity.name,
     filePath: entity.filePath,
     startLine: entity.startLine,
diff --git a/packages/plugin-common/src/__tests__/symbolIdentity.test.ts b/packages/plugin-common/src/__tests__/symbolIdentity.test.ts
new file mode 100644
index 00000000..34f2ce4f
--- /dev/null
+++ b/packages/plugin-common/src/__tests__/symbolIdentity.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildSymbolIdentity,
+  normalizeDeclarationSignature,
+  normalizeSymbolFilePath,
+  signatureDisambiguator,
+} from '../symbolIdentity';
+
+describe('buildSymbolIdentity', () => {
+  it('hashes the canonical length-prefixed identity tuple', () => {
+    const identity = buildSymbolIdentity({
+      label: 'Function',
+      filePath: 'src/a:b.ts',
+      scopeKey: 'Class:Outer',
+      declaredName: 'run:fast',
+      disambiguator: 'sig:abc',
+    });
+
+    expect(identity).toEqual({
+      id: 'sym:v1:6d2aeedb5996fddf1aae415c4bc89f7e76d11cc4d3695febe86192e378b3616a',
+      scopeKey: 'Class:Outer',
+      disambiguator: 'sig:abc',
+    });
+  });
+
+  it('normalizes path separators and dot segments before hashing', () => {
+    expect(normalizeSymbolFilePath('src\\feature\\..\\model.ts')).toBe('src/model.ts');
+
+    const windowsStyle = buildSymbolIdentity({
+      label: 'Class',
+      filePath: 'src\\feature\\..\\model.ts',
+      scopeKey: '',
+      declaredName: 'Model',
+      disambiguator: '',
+    });
+    const posixStyle = buildSymbolIdentity({
+      label: 'Class',
+      filePath: 'src/model.ts',
+      scopeKey: '',
+      declaredName: 'Model',
+      disambiguator: '',
+    });
+
+    expect(windowsStyle.id).toBe(posixStyle.id);
+  });
+
+  it('does not collide when tuple values contain separators', () => {
+    const left = buildSymbolIdentity({
+      label: 'Function',
+      filePath: 'src/a:b.ts',
+      scopeKey: 'Class:A',
+      declaredName: 'b:c',
+      disambiguator: '',
+    });
+    const right = buildSymbolIdentity({
+      label: 'Function',
+      filePath: 'src/a',
+      scopeKey: 'b.ts:Class:A',
+      declaredName: 'b:c',
+      disambiguator: '',
+    });
+
+    expect(left.id).not.toBe(right.id);
+  });
+});
+
+describe('signatureDisambiguator', () => {
+  it('normalizes signature whitespace before hashing', () => {
+    const compact = signatureDisambiguator('(value:string,count?:number):boolean');
+    const spaced = signatureDisambiguator('( value: string, count?: number ) : boolean');
+
+    expect(spaced).toBe(compact);
+    expect(compact).toMatch(/^sig:[a-f0-9]{16}$/);
+    expect(normalizeDeclarationSignature(' ( value: string ) : void ')).toBe('(value:string):void');
+  });
+});
diff --git a/packages/plugin-common/src/index.ts b/packages/plugin-common/src/index.ts
index 88154ecb..c4b8385c 100644
--- a/packages/plugin-common/src/index.ts
+++ b/packages/plugin-common/src/index.ts
@@ -79,6 +79,7 @@ export interface GrammarHelpers {
 // ============================================================================
 
 export * from './types';
+export * from './symbolIdentity';
 
 export function createGrammarHelpers(extensionToGrammar: Record<string, unknown>): GrammarHelpers {
   function getGrammarForExtension(ext: string): unknown | undefined {
@@ -106,4 +107,3 @@ export {
   type EnclosingEntity,
   type EnclosingKind,
 } from './findEnclosingNamedEntity';
-
diff --git a/packages/plugin-common/src/symbolIdentity.ts b/packages/plugin-common/src/symbolIdentity.ts
new file mode 100644
index 00000000..b75736aa
--- /dev/null
+++ b/packages/plugin-common/src/symbolIdentity.ts
@@ -0,0 +1,264 @@
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
+import type { SyntaxNode } from '@codegraph/types';
+
+export type SourceSymbolLabel =
+  | 'Function'
+  | 'Class'
+  | 'Interface'
+  | 'Variable'
+  | 'Type'
+  | 'Component';
+
+export interface SymbolIdentityInput {
+  label: SourceSymbolLabel;
+  filePath: string;
+  scopeKey: string;
+  declaredName: string;
+  disambiguator: string;
+}
+
+export interface SymbolIdentity {
+  id: string;
+  scopeKey: string;
+  disambiguator: string;
+}
+
+const NAMED_SCOPE_TYPES: Readonly<Record<string, SourceSymbolLabel | 'Impl'>> = {
+  class: 'Class',
+  class_declaration: 'Class',
+  abstract_class_declaration: 'Class',
+  class_definition: 'Class',
+  struct_item: 'Class',
+  enum_item: 'Class',
+  interface_declaration: 'Interface',
+  interface_definition: 'Interface',
+  trait_item: 'Interface',
+  function_declaration: 'Function',
+  function_definition: 'Function',
+  function_item: 'Function',
+  generator_function_declaration: 'Function',
+  method_definition: 'Function',
+  method_declaration: 'Function',
+  local_function_statement: 'Function',
+  impl_item: 'Impl',
+};
+
+const FUNCTION_EXPRESSION_TYPES = new Set([
+  'arrow_function',
+  'function_expression',
+  'generator_function',
+  'lambda',
+]);
+
+const BLOCK_TYPES = new Set([
+  'statement_block',
+  'block',
+  'block_expression',
+  'declaration_list',
+]);
+
+const BLOCK_OWNER_TYPES = new Set([
+  'if_statement',
+  'else_clause',
+  'for_statement',
+  'for_in_statement',
+  'for_of_statement',
+  'while_statement',
+  'do_statement',
+  'switch_case',
+  'switch_default',
+  'catch_clause',
+  'try_statement',
+]);
+
+const FIELD_NAMES = [
+  'body',
+  'consequence',
+  'alternative',
+  'handler',
+  'finalizer',
+] as const;
+
+export function normalizeSymbolFilePath(filePath: string): string {
+  const normalizedSeparators = filePath.replace(/\\/g, '/').normalize('NFC');
+  const normalized = posix.normalize(normalizedSeparators);
+  return normalized === '.' && normalizedSeparators !== '.' ? '' : normalized;
+}
+
+export function buildSymbolIdentity(input: SymbolIdentityInput): SymbolIdentity {
+  const scopeKey = input.scopeKey.normalize('NFC');
+  const disambiguator = input.disambiguator.normalize('NFC');
+  const fields = [
+    input.label,
+    normalizeSymbolFilePath(input.filePath),
+    scopeKey,
+    input.declaredName.normalize('NFC'),
+    disambiguator,
+  ];
+  const hash = createHash('sha256');
+
+  for (const field of fields) {
+    const encoded = Buffer.from(field, 'utf8');
+    const length = Buffer.allocUnsafe(4);
+    length.writeUInt32BE(encoded.byteLength, 0);
+    hash.update(length);
+    hash.update(encoded);
+  }
+
+  return {
+    id: `sym:v1:${hash.digest('hex')}`,
+    scopeKey,
+    disambiguator,
+  };
+}
+
+export function normalizeDeclarationSignature(signature: string): string {
+  let normalized = '';
+  let quote: string | null = null;
+  let escaped = false;
+  let pendingSpace = false;
+
+  for (const character of signature.trim().normalize('NFC')) {
+    if (quote) {
+      normalized += character;
+      if (escaped) {
+        escaped = false;
+      } else if (character === '\\') {
+        escaped = true;
+      } else if (character === quote) {
+        quote = null;
+      }
+      continue;
+    }
+
+    if (character === '"' || character === "'" || character === '`') {
+      if (pendingSpace && normalized && !isSignaturePunctuation(normalized.at(-1)!)) {
+        normalized += ' ';
+      }
+      pendingSpace = false;
+      quote = character;
+      normalized += character;
+      continue;
+    }
+
+    if (/\s/.test(character)) {
+      pendingSpace = true;
+      continue;
+    }
+
+    if (isSignaturePunctuation(character)) {
+      normalized = normalized.trimEnd();
+      normalized += character;
+      pendingSpace = false;
+      continue;
+    }
+
+    if (pendingSpace && normalized && !isSignaturePunctuation(normalized.at(-1)!)) {
+      normalized += ' ';
+    }
+    pendingSpace = false;
+    normalized += character;
+  }
+
+  return normalized;
+}
+
+export function signatureDisambiguator(signature: string): string {
+  const normalized = normalizeDeclarationSignature(signature);
+  const digest = createHash('sha256').update(normalized, 'utf8').digest('hex');
+  return `sig:${digest.slice(0, 16)}`;
+}
+
+export function occurrenceDisambiguator(ordinal: number): string {
+  if (!Number.isSafeInteger(ordinal) || ordinal < 1) {
+    throw new RangeError('Occurrence ordinal must be a positive safe integer');
+  }
+  return `occ:${ordinal}`;
+}
+
+export function buildLexicalScopeKey(
+  node: SyntaxNode,
+  options: { includeBlockScopes?: boolean } = {},
+): string {
+  const segments: string[] = [];
+  let current = node.parent;
+
+  while (current) {
+    const namedSegment = namedScopeSegment(current);
+    if (namedSegment) {
+      segments.push(namedSegment);
+    } else if (options.includeBlockScopes && BLOCK_TYPES.has(current.type)) {
+      const blockSegment = blockScopeSegment(current);
+      if (blockSegment) segments.push(blockSegment);
+    }
+    current = current.parent;
+  }
+
+  return segments.reverse().join('/');
+}
+
+function namedScopeSegment(node: SyntaxNode): string | null {
+  const label = NAMED_SCOPE_TYPES[node.type];
+  if (label) {
+    const name = label === 'Impl'
+      ? node.childForFieldName('type')?.text ?? node.childForFieldName('trait')?.text
+      : node.childForFieldName('name')?.text;
+    return name ? `${label}:${name.normalize('NFC')}` : null;
+  }
+
+  if (FUNCTION_EXPRESSION_TYPES.has(node.type)) {
+    const directName = node.childForFieldName('name')?.text;
+    const declaratorName = node.parent?.type === 'variable_declarator'
+      ? node.parent.childForFieldName('name')?.text
+      : undefined;
+    const name = directName ?? declaratorName;
+    return name ? `Function:${name.normalize('NFC')}` : null;
+  }
+
+  return null;
+}
+
+function blockScopeSegment(block: SyntaxNode): string | null {
+  const parent = block.parent;
+  if (!parent) return null;
+  if (namedScopeSegment(parent)) return null;
+
+  if (BLOCK_OWNER_TYPES.has(parent.type)) {
+    const role = fieldNameForChild(parent, block);
+    const ordinal = siblingOrdinal(parent);
+    return `Block:${parent.type}${role ? `:${role}` : ''}#${ordinal}`;
+  }
+
+  const ordinal = siblingOrdinal(block);
+  return `Block:${block.type}#${ordinal}`;
+}
+
+function fieldNameForChild(parent: SyntaxNode, child: SyntaxNode): string | null {
+  for (const fieldName of FIELD_NAMES) {
+    const candidate = parent.childForFieldName(fieldName);
+    if (candidate && sameNode(candidate, child)) return fieldName;
+  }
+  return null;
+}
+
+function siblingOrdinal(node: SyntaxNode): number {
+  const siblings = node.parent?.namedChildren ?? [];
+  let ordinal = 0;
+  for (const sibling of siblings) {
+    if (sibling.type !== node.type) continue;
+    if (sameNode(sibling, node)) return ordinal;
+    ordinal++;
+  }
+  return ordinal;
+}
+
+function sameNode(left: SyntaxNode, right: SyntaxNode): boolean {
+  return left.type === right.type &&
+    left.startIndex === right.startIndex &&
+    left.endIndex === right.endIndex;
+}
+
+function isSignaturePunctuation(character: string): boolean {
+  return /[<>()\[\]{},:;?=|&]/.test(character);
+}
diff --git a/packages/plugin-generic/src/index.ts b/packages/plugin-generic/src/index.ts
index fa695185..eef51780 100644
--- a/packages/plugin-generic/src/index.ts
+++ b/packages/plugin-generic/src/index.ts
@@ -32,7 +32,16 @@ import type {
   ExtractedEntities,
   LanguagePlugin,
 } from '@codegraph/types';
-import { findNodesOfType, generateEntityId, createGrammarHelpers } from '@codegraph/plugin-common';
+import {
+  buildLexicalScopeKey,
+  buildSymbolIdentity,
+  createGrammarHelpers,
+  findNodesOfType,
+  generateEntityId,
+  occurrenceDisambiguator,
+  signatureDisambiguator,
+  type SourceSymbolLabel,
+} from '@codegraph/plugin-common';
 
 // ============================================================================
 // Config Types
@@ -580,10 +589,32 @@ function genericExtractFunctions(
 
     const docstring = extractDocstringByConfig(node, config);
 
-    const id = generateEntityId(filePath, 'function', name, startLine);
+    const scopeKey = buildLexicalScopeKey(node);
+    const sameScope = nodes.filter((candidate) =>
+      candidate.childForFieldName(nameField)?.text === name &&
+      buildLexicalScopeKey(candidate) === scopeKey
+    );
+    let disambiguator = '';
+    if (sameScope.length > 1) {
+      const signature = signatureDisambiguator(genericFunctionSignature(params, returnType));
+      const sameSignature = sameScope.filter((candidate) => {
+        const candidateParams = config.overrides?.extractParameters
+          ? config.overrides.extractParameters(candidate)
+          : genericExtractParams(candidate, config);
+        const candidateReturn = config.overrides?.extractReturnType
+          ? config.overrides.extractReturnType(candidate)
+          : candidate.childForFieldName(config.fields?.returnType ?? 'return_type')?.text;
+        return signatureDisambiguator(genericFunctionSignature(candidateParams, candidateReturn)) === signature;
+      });
+      const occurrence = sameSignature.findIndex((candidate) => candidate.startIndex === node.startIndex) + 1;
+      disambiguator = sameSignature.length > 1
+        ? `${signature}/${occurrenceDisambiguator(occurrence)}`
+        : signature;
+    }
+    const identity = sourceIdentity(node, filePath, 'Function', name, disambiguator);
 
     const entity: FunctionEntity = {
-      id,
+      ...identity,
       name,
       filePath,
       startLine,
@@ -603,6 +634,10 @@ function genericExtractFunctions(
   return functions;
 }
 
+function genericFunctionSignature(params: ParamInfo[], returnType: string | undefined): string {
+  return `(${params.map((param) => `${param.type ?? '_'}${param.optional ? '?' : ''}`).join(',')})=>${returnType ?? '_'}`;
+}
+
 /**
  * Phase 2b: Rich parameter extraction.
  * Uses paramConfig for typed parameters, defaults, and filtering.
@@ -709,10 +744,16 @@ function genericExtractClasses(
 
     const docstring = extractDocstringByConfig(node, config);
 
-    const id = generateEntityId(filePath, 'class', name, startLine);
+    const identity = sourceIdentity(
+      node,
+      filePath,
+      'Class',
+      name,
+      sameScopeOccurrence(node, nodes, name, nameField),
+    );
 
     const entity: ClassEntity = {
-      id,
+      ...identity,
       name,
       filePath,
       startLine,
@@ -783,10 +824,16 @@ function genericExtractInterfaces(
 
     const docstring = extractDocstringByConfig(node, config);
 
-    const id = generateEntityId(filePath, 'interface', name, startLine);
+    const identity = sourceIdentity(
+      node,
+      filePath,
+      'Interface',
+      name,
+      sameScopeOccurrence(node, nodes, name, nameField),
+    );
 
     const entity: InterfaceEntity = {
-      id,
+      ...identity,
       name,
       filePath,
       startLine,
@@ -826,10 +873,17 @@ function genericExtractVariables(
       ? config.overrides.isExported(node, name)
       : isExportedByConfig(node, name, config);
 
-    const id = generateEntityId(filePath, 'variable', name, line);
+    const identity = sourceIdentity(
+      node,
+      filePath,
+      'Variable',
+      name,
+      sameScopeOccurrence(node, nodes, name, nameField, true),
+      true,
+    );
 
     variables.push({
-      id,
+      ...identity,
       name,
       filePath,
       line,
@@ -841,6 +895,40 @@ function genericExtractVariables(
   return variables;
 }
 
+function sourceIdentity(
+  node: SyntaxNode,
+  filePath: string,
+  label: SourceSymbolLabel,
+  declaredName: string,
+  disambiguator = '',
+  includeBlockScopes = false,
+) {
+  return buildSymbolIdentity({
+    label,
+    filePath,
+    scopeKey: buildLexicalScopeKey(node, { includeBlockScopes }),
+    declaredName,
+    disambiguator,
+  });
+}
+
+function sameScopeOccurrence(
+  node: SyntaxNode,
+  nodes: SyntaxNode[],
+  name: string,
+  nameField: string,
+  includeBlockScopes = false,
+): string {
+  const scopeKey = buildLexicalScopeKey(node, { includeBlockScopes });
+  const peers = nodes.filter((candidate) =>
+    candidate.childForFieldName(nameField)?.text === name &&
+    buildLexicalScopeKey(candidate, { includeBlockScopes }) === scopeKey
+  );
+  if (peers.length <= 1) return '';
+  const occurrence = peers.findIndex((candidate) => candidate.startIndex === node.startIndex) + 1;
+  return occurrenceDisambiguator(occurrence);
+}
+
 /**
  * Phase 2a: Structured import extraction.
  * Uses importConfig for module field, specifier extraction, aliases.
diff --git a/packages/plugin-go/__tests__/extractors.test.ts b/packages/plugin-go/__tests__/extractors.test.ts
index 44b670fc..0131641c 100644
--- a/packages/plugin-go/__tests__/extractors.test.ts
+++ b/packages/plugin-go/__tests__/extractors.test.ts
@@ -859,9 +859,8 @@ func (u User) IsAdult() bool {
     expect(fieldEdges).toHaveLength(2);
 
     // Visibility check on fields
-    const props = result.variables.filter(
-      (v) => typeof v.id === 'string' && v.id.startsWith(`${userStruct!.id}::prop`),
-    );
+    const fieldIds = new Set(fieldEdges.map((edge) => edge.toId));
+    const props = result.variables.filter((variable) => fieldIds.has(variable.id));
     const nameField = props.find((p) => p.name === 'Name');
     const ageField = props.find((p) => p.name === 'age');
     expect(nameField).toBeDefined();
@@ -916,13 +915,13 @@ type Config struct {
       expect(edge.isReadonly).toBe(false);
     }
 
-    const props = result.propertyEntities.filter(
-      (p) => typeof p.id === 'string' && p.id.startsWith(`${config!.id}::prop`),
-    );
+    const propertyIds = new Set(propEdges.map((edge) => edge.toId));
+    const props = result.propertyEntities.filter((property) => propertyIds.has(property.id));
     const hostProp = props.find((p) => p.name === 'Host');
     const portProp = props.find((p) => p.name === 'port');
     expect(hostProp).toBeDefined();
     expect(portProp).toBeDefined();
+    expect(props.every((property) => property.scopeKey === 'Class:Config')).toBe(true);
 
     const hostEdge = propEdges.find((e) => e.toId === hostProp!.id);
     const portEdge = propEdges.find((e) => e.toId === portProp!.id);
diff --git a/packages/plugin-go/src/index.ts b/packages/plugin-go/src/index.ts
index 339ef0b0..acf481e5 100644
--- a/packages/plugin-go/src/index.ts
+++ b/packages/plugin-go/src/index.ts
@@ -35,7 +35,16 @@ import type {
   TypeRefEntity,
   Visibility,
 } from '@codegraph/types';
-import { findNodesOfType, generateEntityId, calculateComplexity, resolveTypeIdentity } from '@codegraph/plugin-common';
+import {
+  buildLexicalScopeKey,
+  buildSymbolIdentity,
+  calculateComplexity,
+  findNodesOfType,
+  generateEntityId,
+  occurrenceDisambiguator,
+  resolveTypeIdentity,
+  type SourceSymbolLabel,
+} from '@codegraph/plugin-common';
 import { createLanguagePlugin } from '@codegraph/plugin-generic';
 
 /** Get the tree-sitter grammar for Go */
@@ -52,6 +61,24 @@ function isGoExported(name: string): boolean {
   return first === first.toUpperCase() && first !== first.toLowerCase();
 }
 
+function sourceIdentity(
+  node: SyntaxNode,
+  filePath: string,
+  label: SourceSymbolLabel,
+  declaredName: string,
+  disambiguator = '',
+  includeBlockScopes = false,
+  scopeKeyOverride?: string,
+) {
+  return buildSymbolIdentity({
+    label,
+    filePath,
+    scopeKey: scopeKeyOverride ?? buildLexicalScopeKey(node, { includeBlockScopes }),
+    declaredName,
+    disambiguator,
+  });
+}
+
 // ============================================================================
 // Doc Comment Extraction
 // ============================================================================
@@ -163,10 +190,10 @@ export function extractClasses(root: SyntaxNode, filePath: string): ClassEntity[
       }
 
       const docstring = extractDocComment(decl);
-      const id = generateEntityId(filePath, 'class', name, startLine);
+      const identity = sourceIdentity(decl, filePath, 'Class', name);
 
       const entity: ClassEntity = {
-        id,
+        ...identity,
         name,
         filePath,
         startLine,
@@ -307,11 +334,12 @@ export function extractStructsWithEdges(
       }
 
       const docstring = extractDocComment(decl);
-      const classId = generateEntityId(filePath, 'class', name, startLine);
+      const classIdentity = sourceIdentity(decl, filePath, 'Class', name);
+      const classId = classIdentity.id;
       structIdByName.set(name, classId);
 
       const entity: ClassEntity = {
-        id: classId,
+        ...classIdentity,
         name,
         filePath,
         startLine,
@@ -359,14 +387,21 @@ export function extractStructsWithEdges(
           const fieldName = fieldIdent.text;
           const count = propNameCount.get(fieldName) ?? 0;
           propNameCount.set(fieldName, count + 1);
-          const suffix = count > 0 ? `:${count}` : '';
-
-          const propId = `${classId}::prop::${fieldName}${suffix}`;
+          const disambiguator = count > 0 ? occurrenceDisambiguator(count + 1) : '';
+          const propIdentity = sourceIdentity(
+            field,
+            filePath,
+            'Variable',
+            fieldName,
+            disambiguator,
+            false,
+            `Class:${name}`,
+          );
           const line = field.startPosition.row + 1;
           const visibility = goVisibility(fieldName);
 
           const propEntity: VariableEntity = {
-            id: propId,
+            ...propIdentity,
             name: fieldName,
             filePath,
             line,
@@ -378,7 +413,7 @@ export function extractStructsWithEdges(
           propertyEntities.push(propEntity);
           hasPropertyEdges.push({
             fromId: classId,
-            toId: propId,
+            toId: propIdentity.id,
             isStatic: false, // Go has no static fields
             visibility,
             isReadonly: false,
@@ -417,7 +452,15 @@ export function extractStructsWithEdges(
     // receiverTypeName qualifies the id just as extractFunctions does.
     // Go doesn't allow two methods with the same name on the same receiver type,
     // so no overload suffix is needed.
-    const methodId = generateEntityId(filePath, 'function', `${receiverTypeName}.${methodName}`, startLine);
+    const methodIdentity = sourceIdentity(
+      node,
+      filePath,
+      'Function',
+      methodName,
+      '',
+      false,
+      `Receiver:${receiverTypeName}`,
+    );
 
     const params = extractGoParams(node);
     const returnType = extractGoReturnType(node);
@@ -425,7 +468,7 @@ export function extractStructsWithEdges(
     const metrics = calculateComplexity(node);
 
     const methodEntity: FunctionEntity = {
-      id: methodId,
+      ...methodIdentity,
       name: methodName,
       filePath,
       startLine,
@@ -444,7 +487,7 @@ export function extractStructsWithEdges(
     methodEntities.push(methodEntity);
     hasMethodEdges.push({
       fromId: classId,
-      toId: methodId,
+      toId: methodIdentity.id,
       isStatic: false, // Go has no static methods
       visibility,
     });
@@ -506,10 +549,10 @@ export function extractInterfaces(root: SyntaxNode, filePath: string): Interface
       }
 
       const docstring = extractDocComment(decl);
-      const id = generateEntityId(filePath, 'interface', name, startLine);
+      const identity = sourceIdentity(decl, filePath, 'Interface', name);
 
       const entity: InterfaceEntity = {
-        id,
+        ...identity,
         name,
         filePath,
         startLine,
@@ -565,10 +608,10 @@ export function extractFunctions(root: SyntaxNode, filePath: string): FunctionEn
     const params = extractGoParams(node);
     const returnType = extractGoReturnType(node);
     const docstring = extractDocComment(node);
-    const id = generateEntityId(filePath, 'function', name, startLine);
+    const identity = sourceIdentity(node, filePath, 'Function', name);
 
     const entity: FunctionEntity = {
-      id,
+      ...identity,
       name,
       filePath,
       startLine,
@@ -614,10 +657,18 @@ export function extractFunctions(root: SyntaxNode, filePath: string): FunctionEn
     // Extract receiver type for parentClass
     const receiverType = extractReceiverType(node);
 
-    const id = generateEntityId(filePath, 'function', `${receiverType || ''}.${name}`, startLine);
+    const identity = sourceIdentity(
+      node,
+      filePath,
+      'Function',
+      name,
+      '',
+      false,
+      receiverType ? `Receiver:${receiverType}` : '',
+    );
 
     const entity: FunctionEntity = {
-      id,
+      ...identity,
       name,
       filePath,
       startLine,
@@ -790,10 +841,10 @@ function extractVarSpec(
       const name = n.text;
       const line = spec.startPosition.row + 1;
       const isExported = isGoExported(name);
-      const id = generateEntityId(filePath, 'variable', name, line);
+      const identity = sourceIdentity(spec, filePath, 'Variable', name, '', true);
 
       const entity: VariableEntity = {
-        id,
+        ...identity,
         name,
         filePath,
         line,
@@ -809,10 +860,10 @@ function extractVarSpec(
   const name = nameNode.text;
   const line = spec.startPosition.row + 1;
   const isExported = isGoExported(name);
-  const id = generateEntityId(filePath, 'variable', name, line);
+  const identity = sourceIdentity(spec, filePath, 'Variable', name, '', true);
 
   const entity: VariableEntity = {
-    id,
+    ...identity,
     name,
     filePath,
     line,
@@ -927,12 +978,12 @@ export function extractTypes(root: SyntaxNode, filePath: string): TypeEntity[] {
       const isExported = isGoExported(name);
 
       const docstring = extractDocComment(decl);
-      const id = generateEntityId(filePath, 'type', name, startLine);
+      const identity = sourceIdentity(decl, filePath, 'Type', name);
 
       // Both type definitions and type aliases map to kind 'type'
       // (TypeKind only supports 'type' | 'enum')
       const entity: TypeEntity = {
-        id,
+        ...identity,
         name,
         filePath,
         startLine,
@@ -1499,9 +1550,9 @@ export function extractAllEntities(root: SyntaxNode, filePath: string) {
     if (!nameNode) continue;
     const name = nameNode.text;
     const startLine = funcNode.startPosition.row + 1;
-    const entityId = generateEntityId(filePath, 'function', name, startLine);
-
-    const matchedEntity = functionById.get(entityId);
+    const matchedEntity = mergedFunctions.find(
+      (entity) => entity.name === name && entity.startLine === startLine,
+    );
     if (matchedEntity?.id) {
       accumulateTypeRefs(funcNode, matchedEntity.id);
     }
@@ -1516,9 +1567,11 @@ export function extractAllEntities(root: SyntaxNode, filePath: string) {
     const receiverTypeName = extractReceiverType(methodNode);
     const startLine = methodNode.startPosition.row + 1;
 
-    // Compute the id that both extractFunctions and extractStructsWithEdges now use
-    const entityId = generateEntityId(filePath, 'function', `${receiverTypeName || ''}.${methodName}`, startLine);
-    const matchedMethod = functionById.get(entityId);
+    const matchedMethod = mergedFunctions.find(
+      (entity) => entity.name === methodName &&
+        entity.startLine === startLine &&
+        entity.scopeKey === (receiverTypeName ? `Receiver:${receiverTypeName}` : ''),
+    );
     if (matchedMethod?.id) {
       accumulateTypeRefs(methodNode, matchedMethod.id);
     }
diff --git a/packages/plugin-languages/src/configs/csharp.ts b/packages/plugin-languages/src/configs/csharp.ts
index 3568ba8f..527ff53a 100644
--- a/packages/plugin-languages/src/configs/csharp.ts
+++ b/packages/plugin-languages/src/configs/csharp.ts
@@ -16,6 +16,11 @@ import type {
   SyntaxNode,
 } from '@codegraph/types';
 import { findNodesOfType, generateEntityId, calculateComplexity } from '@codegraph/plugin-common';
+import {
+  functionDisambiguator,
+  identityForNode,
+  normalizedFunctionSignature,
+} from './symbolIdentity';
 
 // ============================================================================
 // Helpers
@@ -43,6 +48,48 @@ function extractXmlDocComment(node: SyntaxNode): string | undefined {
   return lines.length > 0 ? lines.join('\n') : undefined;
 }
 
+function mergePartialClasses(classes: ClassEntity[]): ClassEntity[] {
+  const merged = new Map<string, ClassEntity>();
+  for (const declaration of classes) {
+    const existing = merged.get(declaration.id);
+    if (!existing) {
+      merged.set(declaration.id, declaration);
+      continue;
+    }
+    existing.startLine = Math.min(existing.startLine, declaration.startLine);
+    existing.endLine = Math.max(existing.endLine, declaration.endLine);
+    existing.isExported ||= declaration.isExported;
+    existing.isAbstract ||= declaration.isAbstract;
+    existing.implements = Array.from(new Set([
+      ...(existing.implements ?? []),
+      ...(declaration.implements ?? []),
+    ]));
+    existing.extends ??= declaration.extends;
+    existing.docstring ??= declaration.docstring;
+  }
+  return Array.from(merged.values());
+}
+
+function mergePartialInterfaces(interfaces: InterfaceEntity[]): InterfaceEntity[] {
+  const merged = new Map<string, InterfaceEntity>();
+  for (const declaration of interfaces) {
+    const existing = merged.get(declaration.id);
+    if (!existing) {
+      merged.set(declaration.id, declaration);
+      continue;
+    }
+    existing.startLine = Math.min(existing.startLine, declaration.startLine);
+    existing.endLine = Math.max(existing.endLine, declaration.endLine);
+    existing.isExported ||= declaration.isExported;
+    existing.extends = Array.from(new Set([
+      ...(existing.extends ?? []),
+      ...(declaration.extends ?? []),
+    ]));
+    existing.docstring ??= declaration.docstring;
+  }
+  return Array.from(merged.values());
+}
+
 // ============================================================================
 // Override Extractors
 // ============================================================================
@@ -79,7 +126,7 @@ function extractClasses(root: SyntaxNode, filePath: string): ClassEntity[] {
     }
 
     const entity: ClassEntity = {
-      id: generateEntityId(filePath, 'class', name, startLine),
+      ...identityForNode({ node, filePath, label: 'Class', declaredName: name }),
       name, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: isExportedFromModifiers(modifiers),
       isAbstract: modifiers.includes('abstract'),
@@ -90,7 +137,7 @@ function extractClasses(root: SyntaxNode, filePath: string): ClassEntity[] {
     if (doc) entity.docstring = doc;
     classes.push(entity);
   }
-  return classes;
+  return mergePartialClasses(classes);
 }
 
 function extractInterfaces(root: SyntaxNode, filePath: string): InterfaceEntity[] {
@@ -117,7 +164,7 @@ function extractInterfaces(root: SyntaxNode, filePath: string): InterfaceEntity[
     }
 
     const entity: InterfaceEntity = {
-      id: generateEntityId(filePath, 'interface', name, startLine),
+      ...identityForNode({ node, filePath, label: 'Interface', declaredName: name }),
       name, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: isExportedFromModifiers(modifiers),
     };
@@ -126,12 +173,13 @@ function extractInterfaces(root: SyntaxNode, filePath: string): InterfaceEntity[
     if (doc) entity.docstring = doc;
     interfaces.push(entity);
   }
-  return interfaces;
+  return mergePartialInterfaces(interfaces);
 }
 
 function extractFunctions(root: SyntaxNode, filePath: string): FunctionEntity[] {
   const functions: FunctionEntity[] = [];
-  for (const node of findNodesOfType(root, ['method_declaration', 'constructor_declaration'])) {
+  const functionNodes = findNodesOfType(root, ['method_declaration', 'constructor_declaration']);
+  for (const node of functionNodes) {
     const nameNode = node.childForFieldName('name');
     if (!nameNode) continue;
     const name = nameNode.text;
@@ -139,36 +187,28 @@ function extractFunctions(root: SyntaxNode, filePath: string): FunctionEntity[]
     const modifiers = extractModifiers(node);
 
     // Parameters
-    const params: { name: string; type?: string; optional?: boolean }[] = [];
-    const paramList = node.childForFieldName('parameters');
-    if (paramList) {
-      for (const child of paramList.children) {
-        if (child.type === 'parameter') {
-          const n = child.childForFieldName('name');
-          if (n) params.push({
-            name: n.text, type: child.childForFieldName('type')?.text,
-            optional: child.children.some((c: SyntaxNode) => c.type === '='),
-          });
-        }
-      }
-    }
+    const params = extractCsharpParams(node);
 
     // Return type (method_declaration only)
-    let returnType: string | undefined;
-    if (node.type === 'method_declaration') {
-      const nameIdx = node.children.findIndex((c: SyntaxNode) => node.childForFieldName('name') === c);
-      for (const child of node.children) {
-        if (child.type === 'predefined_type' || child.type === 'identifier' ||
-          child.type === 'generic_name' || child.type === 'qualified_name' ||
-          child.type === 'nullable_type' || child.type === 'array_type') {
-          const idx = node.children.findIndex((c: SyntaxNode) => c === child);
-          if (idx !== nameIdx) { returnType = child.text; break; }
-        }
-      }
-    }
+    const returnType = extractCsharpReturnType(node);
+    const disambiguator = functionDisambiguator({
+      node,
+      nodes: functionNodes,
+      name,
+      signatureFor: (candidate) => normalizedFunctionSignature(
+        extractCsharpParams(candidate),
+        extractCsharpReturnType(candidate),
+      ),
+    });
 
     const entity: FunctionEntity = {
-      id: generateEntityId(filePath, 'function', name, startLine),
+      ...identityForNode({
+        node,
+        filePath,
+        label: 'Function',
+        declaredName: name,
+        disambiguator,
+      }),
       name, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: isExportedFromModifiers(modifiers),
       isAsync: modifiers.includes('async'), isArrow: false, params,
@@ -185,6 +225,36 @@ function extractFunctions(root: SyntaxNode, filePath: string): FunctionEntity[]
   return functions;
 }
 
+function extractCsharpParams(node: SyntaxNode): Array<{ name: string; type?: string; optional?: boolean }> {
+  const params: Array<{ name: string; type?: string; optional?: boolean }> = [];
+  const paramList = node.childForFieldName('parameters');
+  if (!paramList) return params;
+  for (const child of paramList.children) {
+    if (child.type !== 'parameter') continue;
+    const name = child.childForFieldName('name');
+    if (name) params.push({
+      name: name.text,
+      type: child.childForFieldName('type')?.text,
+      optional: child.children.some((candidate) => candidate.type === '='),
+    });
+  }
+  return params;
+}
+
+function extractCsharpReturnType(node: SyntaxNode): string | undefined {
+  if (node.type !== 'method_declaration') return undefined;
+  const nameNode = node.childForFieldName('name');
+  for (const child of node.children) {
+    if (child.startIndex === nameNode?.startIndex) continue;
+    if (child.type === 'predefined_type' || child.type === 'identifier' ||
+      child.type === 'generic_name' || child.type === 'qualified_name' ||
+      child.type === 'nullable_type' || child.type === 'array_type') {
+      return child.text;
+    }
+  }
+  return undefined;
+}
+
 function extractVariables(root: SyntaxNode, filePath: string): VariableEntity[] {
   const variables: VariableEntity[] = [];
 
@@ -201,7 +271,13 @@ function extractVariables(root: SyntaxNode, filePath: string): VariableEntity[]
       if (!nameNode) continue;
       const line = node.startPosition.row + 1;
       variables.push({
-        id: generateEntityId(filePath, 'variable', nameNode.text, line),
+        ...identityForNode({
+          node: declarator,
+          filePath,
+          label: 'Variable',
+          declaredName: nameNode.text,
+          includeBlockScopes: true,
+        }),
         name: nameNode.text, filePath, line,
         kind: isConst ? 'const' : 'let', isExported, type: typeNode?.text,
       });
@@ -215,7 +291,13 @@ function extractVariables(root: SyntaxNode, filePath: string): VariableEntity[]
     const modifiers = extractModifiers(node);
     const line = node.startPosition.row + 1;
     variables.push({
-      id: generateEntityId(filePath, 'variable', nameNode.text, line),
+      ...identityForNode({
+        node,
+        filePath,
+        label: 'Variable',
+        declaredName: nameNode.text,
+        includeBlockScopes: true,
+      }),
       name: nameNode.text, filePath, line, kind: 'let',
       isExported: isExportedFromModifiers(modifiers),
       type: node.childForFieldName('type')?.text,
@@ -272,7 +354,7 @@ function extractTypes(root: SyntaxNode, filePath: string): TypeEntity[] {
     const startLine = node.startPosition.row + 1;
     const modifiers = extractModifiers(node);
     const entity: TypeEntity = {
-      id: generateEntityId(filePath, 'type', nameNode.text, startLine),
+      ...identityForNode({ node, filePath, label: 'Type', declaredName: nameNode.text }),
       name: nameNode.text, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: isExportedFromModifiers(modifiers), kind: 'enum',
     };
@@ -286,7 +368,7 @@ function extractTypes(root: SyntaxNode, filePath: string): TypeEntity[] {
     const startLine = node.startPosition.row + 1;
     const modifiers = extractModifiers(node);
     types.push({
-      id: generateEntityId(filePath, 'type', nameNode.text, startLine),
+      ...identityForNode({ node, filePath, label: 'Type', declaredName: nameNode.text }),
       name: nameNode.text, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: isExportedFromModifiers(modifiers), kind: 'type',
     });
diff --git a/packages/plugin-languages/src/configs/java.ts b/packages/plugin-languages/src/configs/java.ts
index a355705d..c4b65563 100644
--- a/packages/plugin-languages/src/configs/java.ts
+++ b/packages/plugin-languages/src/configs/java.ts
@@ -15,6 +15,11 @@ import type {
   SyntaxNode,
 } from '@codegraph/types';
 import { findNodesOfType, generateEntityId, calculateComplexity } from '@codegraph/plugin-common';
+import {
+  functionDisambiguator,
+  identityForNode,
+  normalizedFunctionSignature,
+} from './symbolIdentity';
 
 // ============================================================================
 // Helpers
@@ -100,7 +105,7 @@ function extractClasses(root: SyntaxNode, filePath: string): ClassEntity[] {
     }
 
     const entity: ClassEntity = {
-      id: generateEntityId(filePath, 'class', name, startLine),
+      ...identityForNode({ node, filePath, label: 'Class', declaredName: name }),
       name, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: isExportedFromModifiers(modifiers),
       isAbstract: modifiers.includes('abstract'),
@@ -135,7 +140,7 @@ function extractInterfaces(root: SyntaxNode, filePath: string): InterfaceEntity[
     }
 
     const entity: InterfaceEntity = {
-      id: generateEntityId(filePath, 'interface', name, startLine),
+      ...identityForNode({ node, filePath, label: 'Interface', declaredName: name }),
       name, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: isExportedFromModifiers(modifiers),
     };
@@ -149,7 +154,8 @@ function extractInterfaces(root: SyntaxNode, filePath: string): InterfaceEntity[
 
 function extractFunctions(root: SyntaxNode, filePath: string): FunctionEntity[] {
   const functions: FunctionEntity[] = [];
-  for (const node of findNodesOfType(root, ['method_declaration', 'constructor_declaration'])) {
+  const functionNodes = findNodesOfType(root, ['method_declaration', 'constructor_declaration']);
+  for (const node of functionNodes) {
     const nameNode = node.childForFieldName('name');
     if (!nameNode) continue;
     const name = nameNode.text;
@@ -157,24 +163,26 @@ function extractFunctions(root: SyntaxNode, filePath: string): FunctionEntity[]
     const modifiers = extractModifiers(node);
 
     // Parameters
-    const params: { name: string; type?: string; optional?: boolean }[] = [];
-    const paramList = node.childForFieldName('parameters');
-    if (paramList) {
-      for (const child of paramList.children) {
-        if (child.type === 'formal_parameter' || child.type === 'spread_parameter') {
-          const n = child.childForFieldName('name');
-          if (n) params.push({ name: n.text, type: child.childForFieldName('type')?.text, optional: false });
-        }
-      }
-    }
-
-    let returnType: string | undefined;
-    if (node.type === 'method_declaration') {
-      returnType = node.childForFieldName('type')?.text;
-    }
+    const params = extractJavaParams(node);
+    const returnType = extractJavaReturnType(node);
+    const disambiguator = functionDisambiguator({
+      node,
+      nodes: functionNodes,
+      name,
+      signatureFor: (candidate) => normalizedFunctionSignature(
+        extractJavaParams(candidate),
+        extractJavaReturnType(candidate),
+      ),
+    });
 
     const entity: FunctionEntity = {
-      id: generateEntityId(filePath, 'function', name, startLine),
+      ...identityForNode({
+        node,
+        filePath,
+        label: 'Function',
+        declaredName: name,
+        disambiguator,
+      }),
       name, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: isExportedFromModifiers(modifiers),
       isAsync: false, isArrow: false, params,
@@ -191,6 +199,28 @@ function extractFunctions(root: SyntaxNode, filePath: string): FunctionEntity[]
   return functions;
 }
 
+function extractJavaParams(node: SyntaxNode): Array<{ name: string; type?: string; optional?: boolean }> {
+  const params: Array<{ name: string; type?: string; optional?: boolean }> = [];
+  const paramList = node.childForFieldName('parameters');
+  if (!paramList) return params;
+  for (const child of paramList.children) {
+    if (child.type !== 'formal_parameter' && child.type !== 'spread_parameter') continue;
+    const name = child.childForFieldName('name');
+    if (name) params.push({
+      name: name.text,
+      type: child.childForFieldName('type')?.text,
+      optional: false,
+    });
+  }
+  return params;
+}
+
+function extractJavaReturnType(node: SyntaxNode): string | undefined {
+  return node.type === 'method_declaration'
+    ? node.childForFieldName('type')?.text
+    : undefined;
+}
+
 function extractVariables(root: SyntaxNode, filePath: string): VariableEntity[] {
   const variables: VariableEntity[] = [];
   for (const node of findNodesOfType(root, ['field_declaration'])) {
@@ -203,7 +233,13 @@ function extractVariables(root: SyntaxNode, filePath: string): VariableEntity[]
       if (!nameNode) continue;
       const line = node.startPosition.row + 1;
       variables.push({
-        id: generateEntityId(filePath, 'variable', nameNode.text, line),
+        ...identityForNode({
+          node: declarator,
+          filePath,
+          label: 'Variable',
+          declaredName: nameNode.text,
+          includeBlockScopes: true,
+        }),
         name: nameNode.text, filePath, line,
         kind: isFinal ? 'const' : 'let',
         isExported, type: typeNode?.text,
@@ -254,7 +290,7 @@ function extractTypes(root: SyntaxNode, filePath: string): TypeEntity[] {
     const startLine = node.startPosition.row + 1;
     const modifiers = extractModifiers(node);
     const entity: TypeEntity = {
-      id: generateEntityId(filePath, 'type', nameNode.text, startLine),
+      ...identityForNode({ node, filePath, label: 'Type', declaredName: nameNode.text }),
       name: nameNode.text, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: isExportedFromModifiers(modifiers), kind: 'enum',
     };
@@ -268,7 +304,7 @@ function extractTypes(root: SyntaxNode, filePath: string): TypeEntity[] {
     const startLine = node.startPosition.row + 1;
     const modifiers = extractModifiers(node);
     types.push({
-      id: generateEntityId(filePath, 'type', nameNode.text, startLine),
+      ...identityForNode({ node, filePath, label: 'Type', declaredName: nameNode.text }),
       name: nameNode.text, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: isExportedFromModifiers(modifiers), kind: 'type',
     });
diff --git a/packages/plugin-languages/src/configs/php.ts b/packages/plugin-languages/src/configs/php.ts
index ded69153..6bb26efd 100644
--- a/packages/plugin-languages/src/configs/php.ts
+++ b/packages/plugin-languages/src/configs/php.ts
@@ -19,6 +19,7 @@ import type {
   SyntaxNode,
 } from '@codegraph/types';
 import { findNodesOfType, generateEntityId, calculateComplexity } from '@codegraph/plugin-common';
+import { identityForNode } from './symbolIdentity';
 
 // ============================================================================
 // Helpers
@@ -53,6 +54,22 @@ function isInsideClassLikeBody(node: SyntaxNode): boolean {
   return false;
 }
 
+function phpOwnerScopeKey(node: SyntaxNode): string | undefined {
+  let current = node.parent;
+  while (current) {
+    const name = current.childForFieldName('name')?.text;
+    if (name) {
+      if (current.type === 'class_declaration') return `Class:${name}`;
+      if (current.type === 'trait_declaration' || current.type === 'interface_declaration') {
+        return `Interface:${name}`;
+      }
+      if (current.type === 'enum_declaration') return `Type:${name}`;
+    }
+    current = current.parent;
+  }
+  return undefined;
+}
+
 function extractPhpParams(funcNode: SyntaxNode): { name: string; type?: string; optional?: boolean }[] {
   const params: { name: string; type?: string; optional?: boolean }[] = [];
   const paramList = funcNode.children.find((c: SyntaxNode) => c.type === 'formal_parameters');
@@ -97,7 +114,7 @@ function extractClasses(root: SyntaxNode, filePath: string): ClassEntity[] {
     const name = nameNode.text;
     const startLine = node.startPosition.row + 1;
     const entity: ClassEntity = {
-      id: generateEntityId(filePath, 'class', name, startLine),
+      ...identityForNode({ node, filePath, label: 'Class', declaredName: name }),
       name, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: true,
       isAbstract: node.children.some((c: SyntaxNode) => c.type === 'abstract_modifier'),
@@ -124,7 +141,7 @@ function extractInterfaces(root: SyntaxNode, filePath: string): InterfaceEntity[
       }
     }
     const entity: InterfaceEntity = {
-      id: generateEntityId(filePath, 'interface', name, startLine),
+      ...identityForNode({ node, filePath, label: 'Interface', declaredName: name }),
       name, filePath, startLine, endLine: node.endPosition.row + 1, isExported: true,
     };
     if (extendsList.length > 0) entity.extends = extendsList;
@@ -139,7 +156,7 @@ function extractInterfaces(root: SyntaxNode, filePath: string): InterfaceEntity[
     const name = nameNode.text;
     const startLine = node.startPosition.row + 1;
     const entity: InterfaceEntity = {
-      id: generateEntityId(filePath, 'interface', name, startLine),
+      ...identityForNode({ node, filePath, label: 'Interface', declaredName: name }),
       name, filePath, startLine, endLine: node.endPosition.row + 1, isExported: true,
     };
     const doc = extractDocComment(node);
@@ -160,7 +177,7 @@ function extractFunctions(root: SyntaxNode, filePath: string): FunctionEntity[]
     const name = nameNode.text;
     const startLine = node.startPosition.row + 1;
     const entity: FunctionEntity = {
-      id: generateEntityId(filePath, 'function', name, startLine),
+      ...identityForNode({ node, filePath, label: 'Function', declaredName: name }),
       name, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: true, isAsync: false, isArrow: false,
       params: extractPhpParams(node),
@@ -189,9 +206,19 @@ function extractFunctions(root: SyntaxNode, filePath: string): FunctionEntity[]
       const name = nameNode.text;
       const startLine = child.startPosition.row + 1;
       const vis = getVisibility(child);
-      const qualifiedName = className ? `${className}.${name}` : name;
+      const ownerLabel = classNode.type === 'class_declaration'
+        ? 'Class'
+        : classNode.type === 'trait_declaration'
+          ? 'Interface'
+          : 'Type';
       const entity: FunctionEntity = {
-        id: generateEntityId(filePath, 'function', qualifiedName, startLine),
+        ...identityForNode({
+          node: child,
+          filePath,
+          label: 'Function',
+          declaredName: name,
+          scopeKeyOverride: className ? `${ownerLabel}:${className}` : '',
+        }),
         name, filePath, startLine, endLine: child.endPosition.row + 1,
         isExported: vis === 'public' || vis === undefined,
         isAsync: false, isArrow: false, params: extractPhpParams(child),
@@ -223,7 +250,13 @@ function extractVariables(root: SyntaxNode, filePath: string): VariableEntity[]
     const vis = getVisibility(node);
     const typeNode = node.children.find((c: SyntaxNode) => PHP_TYPE_NODES.includes(c.type));
     const entity: VariableEntity = {
-      id: generateEntityId(filePath, 'variable', name, line),
+      ...identityForNode({
+        node,
+        filePath,
+        label: 'Variable',
+        declaredName: name,
+        scopeKeyOverride: phpOwnerScopeKey(node),
+      }),
       name, filePath, line, kind: 'let',
       isExported: vis === 'public' || vis === undefined,
     };
@@ -237,7 +270,13 @@ function extractVariables(root: SyntaxNode, filePath: string): VariableEntity[]
     if (!nameNode) continue;
     const line = node.startPosition.row + 1;
     variables.push({
-      id: generateEntityId(filePath, 'variable', nameNode.text, line),
+      ...identityForNode({
+        node,
+        filePath,
+        label: 'Variable',
+        declaredName: nameNode.text,
+        scopeKeyOverride: phpOwnerScopeKey(node),
+      }),
       name: nameNode.text, filePath, line, kind: 'const', isExported: true,
     });
   }
@@ -301,7 +340,7 @@ function extractTypes(root: SyntaxNode, filePath: string): TypeEntity[] {
     if (!nameNode) continue;
     const startLine = node.startPosition.row + 1;
     const entity: TypeEntity = {
-      id: generateEntityId(filePath, 'type', nameNode.text, startLine),
+      ...identityForNode({ node, filePath, label: 'Type', declaredName: nameNode.text }),
       name: nameNode.text, filePath, startLine, endLine: node.endPosition.row + 1,
       isExported: true, kind: 'enum',
     };
diff --git a/packages/plugin-languages/src/configs/symbolIdentity.ts b/packages/plugin-languages/src/configs/symbolIdentity.ts
new file mode 100644
index 00000000..46bfd80b
--- /dev/null
+++ b/packages/plugin-languages/src/configs/symbolIdentity.ts
@@ -0,0 +1,66 @@
+import type { SyntaxNode } from '@codegraph/types';
+import {
+  buildLexicalScopeKey,
+  buildSymbolIdentity,
+  occurrenceDisambiguator,
+  signatureDisambiguator,
+  type SourceSymbolLabel,
+  type SymbolIdentity,
+} from '@codegraph/plugin-common';
+
+export interface SignatureParam {
+  type?: string;
+  optional?: boolean;
+}
+
+export function identityForNode(options: {
+  node: SyntaxNode;
+  filePath: string;
+  label: SourceSymbolLabel;
+  declaredName: string;
+  disambiguator?: string;
+  includeBlockScopes?: boolean;
+  scopeKeyOverride?: string;
+}): SymbolIdentity {
+  return buildSymbolIdentity({
+    label: options.label,
+    filePath: options.filePath,
+    scopeKey: options.scopeKeyOverride ?? buildLexicalScopeKey(options.node, {
+      includeBlockScopes: options.includeBlockScopes ?? false,
+    }),
+    declaredName: options.declaredName,
+    disambiguator: options.disambiguator ?? '',
+  });
+}
+
+export function functionDisambiguator(options: {
+  node: SyntaxNode;
+  nodes: SyntaxNode[];
+  name: string;
+  signatureFor(node: SyntaxNode): string;
+}): string {
+  const scopeKey = buildLexicalScopeKey(options.node);
+  const peers = options.nodes.filter((candidate) =>
+    candidate.childForFieldName('name')?.text === options.name &&
+    buildLexicalScopeKey(candidate) === scopeKey
+  );
+  if (peers.length <= 1) return '';
+
+  const signature = signatureDisambiguator(options.signatureFor(options.node));
+  const signaturePeers = peers.filter((candidate) =>
+    signatureDisambiguator(options.signatureFor(candidate)) === signature
+  );
+  const occurrence = signaturePeers.findIndex(
+    (candidate) => candidate.startIndex === options.node.startIndex,
+  ) + 1;
+  return signaturePeers.length > 1
+    ? `${signature}/${occurrenceDisambiguator(occurrence)}`
+    : signature;
+}
+
+export function normalizedFunctionSignature(
+  params: SignatureParam[],
+  returnType: string | undefined,
+): string {
+  return `(${params.map((param) => `${param.type ?? '_'}${param.optional ? '?' : ''}`).join(',')})=>${returnType ?? '_'}`;
+}
diff --git a/packages/plugin-python/__tests__/extractors.test.ts b/packages/plugin-python/__tests__/extractors.test.ts
index e27646a5..27d7f9c9 100644
--- a/packages/plugin-python/__tests__/extractors.test.ts
+++ b/packages/plugin-python/__tests__/extractors.test.ts
@@ -614,13 +614,12 @@ class User:
       const userClass = result.classes.find(c => c.name === 'User');
       expect(userClass).toBeDefined();
 
-      const props = result.variables.filter(
-        v => typeof v.id === 'string' && v.id.startsWith(`${userClass!.id}::prop`)
-      );
-      expect(props.map(p => p.name).sort()).toEqual(['_hidden', 'name']);
-
       const hasPropEdges = (result.hasPropertyEdges ?? []).filter(e => e.fromId === userClass!.id);
       expect(hasPropEdges).toHaveLength(2);
+      const propertyIds = new Set(hasPropEdges.map((edge) => edge.toId));
+      const props = result.variables.filter((variable) => propertyIds.has(variable.id));
+      expect(props.map(p => p.name).sort()).toEqual(['_hidden', 'name']);
+      expect(props.every((property) => property.scopeKey === 'Class:User')).toBe(true);
 
       const nameProp = props.find(p => p.name === 'name')!;
       const nameEdge = hasPropEdges.find(e => e.toId === nameProp.id);
diff --git a/packages/plugin-python/src/index.ts b/packages/plugin-python/src/index.ts
index 4b378a2e..dd32295d 100644
--- a/packages/plugin-python/src/index.ts
+++ b/packages/plugin-python/src/index.ts
@@ -20,7 +20,17 @@ import type {
   Visibility,
   CallExtractionContext,
 } from '@codegraph/types';
-import { findNodesOfType, generateEntityId, calculateComplexity, resolveTypeIdentity } from '@codegraph/plugin-common';
+import {
+  buildLexicalScopeKey,
+  buildSymbolIdentity,
+  calculateComplexity,
+  findNodesOfType,
+  generateEntityId,
+  occurrenceDisambiguator,
+  resolveTypeIdentity,
+  signatureDisambiguator,
+  type SourceSymbolLabel,
+} from '@codegraph/plugin-common';
 import { createLanguagePlugin } from '@codegraph/plugin-generic';
 
 /** Get the tree-sitter grammar for Python */
@@ -67,10 +77,28 @@ export function extractFunctions(root: SyntaxNode, filePath: string): FunctionEn
     // edge toIds to mismatch the persisted node id after MERGE.
     if (isInsideClass(node)) continue;
 
-    const id = generateEntityId(filePath, 'function', name, startLine);
+    const scopeKey = buildLexicalScopeKey(node);
+    const peers = functionNodes.filter((candidate) =>
+      candidate.childForFieldName('name')?.text === name &&
+      buildLexicalScopeKey(candidate) === scopeKey
+    );
+    const signature = signatureDisambiguator(pythonFunctionSignature(params, returnType));
+    const signaturePeers = peers.filter((candidate) =>
+      signatureDisambiguator(pythonFunctionSignature(
+        extractParameters(candidate),
+        candidate.childForFieldName('return_type')?.text?.replace(/^->\s*/, '').trim(),
+      )) === signature
+    );
+    const occurrence = signaturePeers.findIndex((candidate) => candidate.startIndex === node.startIndex) + 1;
+    const disambiguator = peers.length <= 1
+      ? ''
+      : signaturePeers.length > 1
+        ? `${signature}/${occurrenceDisambiguator(occurrence)}`
+        : signature;
+    const identity = sourceIdentity(node, filePath, 'Function', name, disambiguator);
 
     const entity: FunctionEntity = {
-      id,
+      ...identity,
       name,
       filePath,
       startLine,
@@ -96,6 +124,13 @@ export function extractFunctions(root: SyntaxNode, filePath: string): FunctionEn
   return functions;
 }
 
+function pythonFunctionSignature(
+  params: Array<{ name: string; type?: string; optional?: boolean }>,
+  returnType: string | undefined,
+): string {
+  return `(${params.map((param) => `${param.type ?? '_'}${param.optional ? '?' : ''}`).join(',')})=>${returnType ?? '_'}`;
+}
+
 function extractParameters(funcNode: SyntaxNode): { name: string; type?: string; optional?: boolean }[] {
   const params: { name: string; type?: string; optional?: boolean }[] = [];
   const parametersNode = funcNode.childForFieldName('parameters');
@@ -433,10 +468,10 @@ export function extractClasses(root: SyntaxNode, filePath: string): ClassEntity[
       }
     }
 
-    const id = generateEntityId(filePath, 'class', name, startLine);
+    const identity = sourceIdentity(node, filePath, 'Class', name);
 
     const entity: ClassEntity = {
-      id,
+      ...identity,
       name,
       filePath,
       startLine,
@@ -517,10 +552,11 @@ export function extractClassesWithEdges(root: SyntaxNode, filePath: string): Cla
     // Extract docstring
     const docstring = extractDocstring(node);
 
-    const classId = generateEntityId(filePath, 'class', name, startLine);
+    const classIdentity = sourceIdentity(node, filePath, 'Class', name);
+    const classId = classIdentity.id;
 
     const classEntity: ClassEntity = {
-      id: classId,
+      ...classIdentity,
       name,
       filePath,
       startLine,
@@ -573,17 +609,16 @@ export function extractClassesWithEdges(root: SyntaxNode, filePath: string): Cla
         // Use generateEntityId format so the id matches what extractFunctions
         // would produce for the same source node. HAS_METHOD edge toIds must
         // match the id persisted to the graph after natural-key MERGE.
-        const methodId = generateEntityId(filePath, 'function', methodName, methodStartLine);
-
         const isAsync = funcNode.children.some((c: SyntaxNode) => c.type === 'async');
         const params = extractParameters(funcNode);
         const returnTypeNode = funcNode.childForFieldName('return_type');
         const returnType = returnTypeNode?.text?.replace(/^->\s*/, '').trim();
+        const methodIdentity = sourceIdentity(funcNode, filePath, 'Function', methodName);
         const methodDocstring = extractDocstring(funcNode);
         const metrics = calculateComplexity(funcNode);
 
         const methodEntity: FunctionEntity = {
-          id: methodId,
+          ...methodIdentity,
           name: methodName,
           filePath,
           startLine: methodStartLine,
@@ -602,7 +637,7 @@ export function extractClassesWithEdges(root: SyntaxNode, filePath: string): Cla
         methodEntities.push(methodEntity);
         hasMethodEdges.push({
           fromId: classId,
-          toId: methodId,
+          toId: methodIdentity.id,
           isStatic,
           visibility: pythonVisibility(methodName),
         });
@@ -642,12 +677,17 @@ export function extractClassesWithEdges(root: SyntaxNode, filePath: string): Cla
       if (propName && propStartLine !== undefined && propEndLine !== undefined) {
         const count = propNameCount.get(propName) ?? 0;
         propNameCount.set(propName, count + 1);
-        const suffix = count > 0 ? `:${count}` : '';
-
-        const propId = `${classId}::prop::${propName}${suffix}`;
+        const propDisambiguator = count > 0 ? occurrenceDisambiguator(count + 1) : '';
+        const propIdentity = sourceIdentity(
+          member,
+          filePath,
+          'Variable',
+          propName,
+          propDisambiguator,
+        );
 
         const propEntity: VariableEntity = {
-          id: propId,
+          ...propIdentity,
           name: propName,
           filePath,
           line: propStartLine,
@@ -659,7 +699,7 @@ export function extractClassesWithEdges(root: SyntaxNode, filePath: string): Cla
         propertyEntities.push(propEntity);
         hasPropertyEdges.push({
           fromId: classId,
-          toId: propId,
+          toId: propIdentity.id,
           isStatic: true, // class-body level assignments are class attributes (static in Python's model)
           visibility: pythonVisibility(propName),
           isReadonly: false,
@@ -890,10 +930,10 @@ export function extractVariables(root: SyntaxNode, filePath: string): VariableEn
           // UPPER_CASE = constant, lower_case = variable
           const isConstant = name === name.toUpperCase() && name.includes('_');
 
-          const id = generateEntityId(filePath, 'variable', name, line);
+          const identity = sourceIdentity(child, filePath, 'Variable', name, '', true);
 
           variables.push({
-            id,
+            ...identity,
             name,
             filePath,
             line,
@@ -909,6 +949,23 @@ export function extractVariables(root: SyntaxNode, filePath: string): VariableEn
   return variables;
 }
 
+function sourceIdentity(
+  node: SyntaxNode,
+  filePath: string,
+  label: SourceSymbolLabel,
+  declaredName: string,
+  disambiguator = '',
+  includeBlockScopes = false,
+) {
+  return buildSymbolIdentity({
+    label,
+    filePath,
+    scopeKey: buildLexicalScopeKey(node, { includeBlockScopes }),
+    declaredName,
+    disambiguator,
+  });
+}
+
 /** Python builtins to skip when extracting calls */
 const PYTHON_BUILTINS = new Set([
   // Built-in functions
@@ -1006,10 +1063,9 @@ export function extractAllEntities(root: SyntaxNode, filePath: string) {
     if (!nameNode) continue;
     const name = nameNode.text;
     const startLine = funcNode.startPosition.row + 1;
-    const entityId = generateEntityId(filePath, 'function', name, startLine);
-
-    // Match to a top-level function entity (class methods are skipped by extractFunctions)
-    const matchedEntity = allFunctions.find(f => f.id === entityId);
+    const matchedEntity = allFunctions.find(
+      (entity) => entity.name === name && entity.startLine === startLine,
+    );
     if (matchedEntity?.id) {
       accumulateTypeRefs(funcNode, matchedEntity.id);
     }
diff --git a/packages/plugin-rust/__tests__/extractors.test.ts b/packages/plugin-rust/__tests__/extractors.test.ts
index ffe04886..7917a077 100644
--- a/packages/plugin-rust/__tests__/extractors.test.ts
+++ b/packages/plugin-rust/__tests__/extractors.test.ts
@@ -824,14 +824,16 @@ pub struct User {
       );
       expect(fieldEdges).toHaveLength(2);
 
+      const propertyIds = new Set(fieldEdges.map((edge) => edge.toId));
       const nameField = result.variables.find(
-        (v) => v.name === 'name' && v.id.includes('::prop::'),
+        (variable) => variable.name === 'name' && propertyIds.has(variable.id),
       );
       const ageField = result.variables.find(
-        (v) => v.name === 'age' && v.id.includes('::prop::'),
+        (variable) => variable.name === 'age' && propertyIds.has(variable.id),
       );
       expect(nameField).toBeDefined();
       expect(ageField).toBeDefined();
+      expect(nameField!.scopeKey).toBe('Class:User');
 
       const nameEdge = fieldEdges.find((e) => e.toId === nameField!.id);
       const ageEdge = fieldEdges.find((e) => e.toId === ageField!.id);
diff --git a/packages/plugin-rust/src/index.ts b/packages/plugin-rust/src/index.ts
index 0f6aa158..70a0ddc3 100644
--- a/packages/plugin-rust/src/index.ts
+++ b/packages/plugin-rust/src/index.ts
@@ -41,7 +41,15 @@ import type {
   Visibility,
 } from '@codegraph/types';
 import type { TypeRefEntity } from '@codegraph/types';
-import { findNodesOfType, generateEntityId, calculateComplexity, resolveTypeIdentity } from '@codegraph/plugin-common';
+import {
+  buildLexicalScopeKey,
+  buildSymbolIdentity,
+  calculateComplexity,
+  findNodesOfType,
+  generateEntityId,
+  resolveTypeIdentity,
+  type SourceSymbolLabel,
+} from '@codegraph/plugin-common';
 import { createLanguagePlugin } from '@codegraph/plugin-generic';
 
 export function getGrammar(): unknown {
@@ -55,6 +63,22 @@ function isPublic(node: SyntaxNode): boolean {
   return node.children.some((c: SyntaxNode) => c.type === 'visibility_modifier');
 }
 
+function sourceIdentity(
+  node: SyntaxNode,
+  filePath: string,
+  label: SourceSymbolLabel,
+  declaredName: string,
+  scopeKeyOverride?: string,
+) {
+  return buildSymbolIdentity({
+    label,
+    filePath,
+    scopeKey: scopeKeyOverride ?? buildLexicalScopeKey(node),
+    declaredName,
+    disambiguator: '',
+  });
+}
+
 // ============================================================================
 // Doc Comment Extraction
 // ============================================================================
@@ -126,10 +150,10 @@ export function extractClasses(root: SyntaxNode, filePath: string): ClassEntity[
     const endLine = node.endPosition.row + 1;
     const isExported = isPublic(node);
     const docstring = extractDocComment(node);
-    const id = generateEntityId(filePath, 'class', name, startLine);
+    const identity = sourceIdentity(node, filePath, 'Class', name);
 
     const entity: ClassEntity = {
-      id,
+      ...identity,
       name,
       filePath,
       startLine,
@@ -172,7 +196,7 @@ export function extractInterfaces(root: SyntaxNode, filePath: string): Interface
     const endLine = node.endPosition.row + 1;
     const isExported = isPublic(node);
     const docstring = extractDocComment(node);
-    const id = generateEntityId(filePath, 'interface', name, startLine);
+    const identity = sourceIdentity(node, filePath, 'Interface', name);
 
     // Extract supertraits (trait bounds)
     const extendsList: string[] = [];
@@ -186,7 +210,7 @@ export function extractInterfaces(root: SyntaxNode, filePath: string): Interface
     }
 
     const entity: InterfaceEntity = {
-      id,
+      ...identity,
       name,
       filePath,
       startLine,
@@ -269,11 +293,16 @@ function extractFunctionFromNode(
   const returnType = extractRustReturnType(node);
   const docstring = extractDocComment(node);
 
-  const qualifiedName = implType ? `${implType}.${name}` : name;
-  const id = generateEntityId(filePath, 'function', qualifiedName, startLine);
+  const identity = sourceIdentity(
+    node,
+    filePath,
+    'Function',
+    name,
+    implType ? `Impl:${implType}` : undefined,
+  );
 
   const entity: FunctionEntity = {
-    id,
+    ...identity,
     name,
     filePath,
     startLine,
@@ -382,7 +411,7 @@ function extractVarFromNode(
   const name = nameNode.text;
   const line = node.startPosition.row + 1;
   const isExported = isPublic(node);
-  const id = generateEntityId(filePath, 'variable', name, line);
+  const identity = sourceIdentity(node, filePath, 'Variable', name);
 
   // Find type annotation (the node after ':')
   const colonIndex = node.children.findIndex((c: SyntaxNode) => c.type === ':');
@@ -395,7 +424,7 @@ function extractVarFromNode(
   }
 
   const entity: VariableEntity = {
-    id,
+    ...identity,
     name,
     filePath,
     line,
@@ -596,10 +625,10 @@ export function extractTypes(root: SyntaxNode, filePath: string): TypeEntity[] {
     const endLine = node.endPosition.row + 1;
     const isExported = isPublic(node);
     const docstring = extractDocComment(node);
-    const id = generateEntityId(filePath, 'type', name, startLine);
+    const identity = sourceIdentity(node, filePath, 'Type', name);
 
     const entity: TypeEntity = {
-      id,
+      ...identity,
       name,
       filePath,
       startLine,
@@ -624,10 +653,10 @@ export function extractTypes(root: SyntaxNode, filePath: string): TypeEntity[] {
     const endLine = node.endPosition.row + 1;
     const isExported = isPublic(node);
     const docstring = extractDocComment(node);
-    const id = generateEntityId(filePath, 'type', name, startLine);
+    const identity = sourceIdentity(node, filePath, 'Type', name);
 
     const entity: TypeEntity = {
-      id,
+      ...identity,
       name,
       filePath,
       startLine,
@@ -1267,11 +1296,12 @@ export function extractStructsWithEdges(
     const endLine = node.endPosition.row + 1;
     const isExported = isPublic(node);
     const docstring = extractDocComment(node);
-    const classId = generateEntityId(filePath, 'class', name, startLine);
+    const classIdentity = sourceIdentity(node, filePath, 'Class', name);
+    const classId = classIdentity.id;
     structIdByName.set(name, classId);
 
     const entity: ClassEntity = {
-      id: classId,
+      ...classIdentity,
       name,
       filePath,
       startLine,
@@ -1310,10 +1340,16 @@ export function extractStructsWithEdges(
         }
       }
 
-      const propId = `${classId}::prop::${fieldName}`;
+      const propIdentity = sourceIdentity(
+        field,
+        filePath,
+        'Variable',
+        fieldName,
+        `Class:${name}`,
+      );
 
       const propEntity: VariableEntity = {
-        id: propId,
+        ...propIdentity,
         name: fieldName,
         filePath,
         line: fieldLine,
@@ -1325,7 +1361,7 @@ export function extractStructsWithEdges(
       propertyEntities.push(propEntity);
       hasPropertyEdges.push({
         fromId: classId,
-        toId: propId,
+        toId: propIdentity.id,
         isStatic: false,
         visibility: fieldVisibility,
         isReadonly: false,
@@ -1360,7 +1396,13 @@ export function extractStructsWithEdges(
 
       // Use generateEntityId format matching extractFunctions (which uses implType.methodName).
       // This ensures HAS_METHOD edge toIds match the persisted node id after natural-key MERGE.
-      const methodId = generateEntityId(filePath, 'function', `${targetName}.${methodName}`, child.startPosition.row + 1);
+      const methodIdentity = sourceIdentity(
+        child,
+        filePath,
+        'Function',
+        methodName,
+        `Impl:${targetName}`,
+      );
       const startLine = child.startPosition.row + 1;
       const endLine = child.endPosition.row + 1;
       const isExported = isPublic(child);
@@ -1373,7 +1415,7 @@ export function extractStructsWithEdges(
       const metrics = calculateComplexity(child);
 
       const methodEntity: FunctionEntity = {
-        id: methodId,
+        ...methodIdentity,
         name: methodName,
         filePath,
         startLine,
@@ -1394,7 +1436,7 @@ export function extractStructsWithEdges(
       methodEntities.push(methodEntity);
       hasMethodEdges.push({
         fromId: classId,
-        toId: methodId,
+        toId: methodIdentity.id,
         isStatic,
         visibility,
       });
@@ -1659,8 +1701,9 @@ export function extractAllEntities(root: SyntaxNode, filePath: string) {
     if (!nameNode) continue;
     const name = nameNode.text;
     const startLine = funcNode.startPosition.row + 1;
-    const entityId = generateEntityId(filePath, 'function', name, startLine);
-    const matched = functionById.get(entityId);
+    const matched = mergedFunctions.find(
+      (entity) => entity.name === name && entity.startLine === startLine,
+    );
     if (matched?.id) {
       accumulateTypeRefs(funcNode, matched.id);
     }
@@ -1682,9 +1725,11 @@ export function extractAllEntities(root: SyntaxNode, filePath: string) {
       const methodName = nameNode.text;
       const startLine = child.startPosition.row + 1;
 
-      const qualifiedName = implTypeName ? `${implTypeName}.${methodName}` : methodName;
-      const entityId = generateEntityId(filePath, 'function', qualifiedName, startLine);
-      const matched = functionById.get(entityId);
+      const matched = mergedFunctions.find(
+        (entity) => entity.name === methodName &&
+          entity.startLine === startLine &&
+          entity.scopeKey === (implTypeName ? `Impl:${implTypeName}` : ''),
+      );
       if (matched?.id) {
         accumulateTypeRefs(child, matched.id);
       }
diff --git a/packages/plugin-typescript/__tests__/calls-receiver-binding.test.ts b/packages/plugin-typescript/__tests__/calls-receiver-binding.test.ts
index 98717747..83af9fee 100644
--- a/packages/plugin-typescript/__tests__/calls-receiver-binding.test.ts
+++ b/packages/plugin-typescript/__tests__/calls-receiver-binding.test.ts
@@ -17,6 +17,7 @@ import { extractCalls } from '../src/extractors/calls';
 import { extractFunctions } from '../src/extractors/functions';
 import { extractClasses } from '../src/extractors/classes';
 import { extractImports } from '../src/extractors/imports';
+import { extractAllEntities } from '../src/extractors';
 import type { ResolvedImportTarget } from '../src/extractors/imports';
 import type { ImportEntity } from '@codegraph/types';
 
@@ -217,6 +218,77 @@ function runBasic() {
     expect(ref!.calleeClassName).toBe('Service');
   });
 
+  it('keeps class overload identities distinct and binds a cross-file receiver call only to the implementation', () => {
+    const declarationRoot = parseCode(`export class Over {
+  work(value: string): string;
+  work(value: number): number;
+  work(value: string | number): string | number { return value; }
+}`);
+    const declarationFile = '/project/over.ts';
+    const extracted = extractAllEntities(declarationRoot, declarationFile);
+    const overClass = extracted.classes.find((entity) => entity.name === 'Over');
+    const workFunctions = extracted.functions.filter((entity) => entity.name === 'work');
+
+    expect(overClass).toBeDefined();
+    expect(workFunctions).toHaveLength(3);
+    expect(new Set(workFunctions.map((entity) => entity.id)).size).toBe(3);
+    expect(workFunctions.every((entity) => entity.scopeKey === 'Class:Over')).toBe(true);
+    expect(workFunctions.map((entity) => entity.disambiguator)).toEqual([
+      expect.stringMatching(/^sig:[a-f0-9]{16}$/),
+      expect.stringMatching(/^sig:[a-f0-9]{16}$/),
+      expect.stringMatching(/^sig:[a-f0-9]{16}$/),
+    ]);
+    expect(new Set(workFunctions.map((entity) => entity.disambiguator)).size).toBe(3);
+    expect(workFunctions.map((entity) => Reflect.get(entity, 'isOverloadSignature'))).toEqual([
+      true,
+      true,
+      false,
+    ]);
+
+    const implementation = workFunctions.find((entity) => entity.startLine === 4);
+    expect(implementation).toBeDefined();
+    const methodEdges = extracted.hasMethodEdges.filter(
+      (edge) => edge.fromId === overClass!.id,
+    );
+    expect(methodEdges).toEqual([
+      expect.objectContaining({ toId: implementation!.id }),
+    ]);
+
+    const callerRoot = parseCode(`import { Over } from './over';
+
+export function run(over: Over): string {
+  return over.work('value');
+}`);
+    const callerFunctions = extractFunctions(callerRoot, '/project/caller.ts');
+    const overImport: ImportEntity = {
+      id: 'imp-over',
+      source: './over',
+      filePath: '/project/caller.ts',
+      isDefault: false,
+      isNamespace: false,
+      specifiers: [{ name: 'Over' }],
+      resolvedPath: declarationFile,
+    };
+    const calls = extractCalls(
+      callerRoot,
+      '/project/caller.ts',
+      callerFunctions,
+      [overImport],
+      false,
+      [],
+    );
+    const receiverCall = calls.find((call) => call.calleeName === 'work');
+
+    expect(receiverCall).toMatchObject({
+      calleeClassName: 'Over',
+      calleeFilePath: declarationFile,
+    });
+    const classQualifiedTargets = methodEdges
+      .map((edge) => workFunctions.find((entity) => entity.id === edge.toId))
+      .filter((entity) => entity?.name === receiverCall!.calleeName);
+    expect(classQualifiedTargets).toEqual([implementation]);
+  });
+
   it('receiver call to a locally declared class also carries calleeClassName', () => {
     const code = `
 class Service {
diff --git a/packages/plugin-typescript/__tests__/extractors.test.ts b/packages/plugin-typescript/__tests__/extractors.test.ts
index 8ae8b76c..fc191eff 100644
--- a/packages/plugin-typescript/__tests__/extractors.test.ts
+++ b/packages/plugin-typescript/__tests__/extractors.test.ts
@@ -26,7 +26,6 @@ import {
   extractComponents,
   extractInheritance,
   extractRenders,
-  generateEntityId,
 } from '../src/extractors';
 
 const TEST_FILE = 'user.ts';
@@ -111,9 +110,12 @@ export class User {
 
     const userClass = result.classes.find(c => c.name === 'User')!;
 
-    const props = result.propertyEntities.filter(
-      p => p.id?.startsWith(`${userClass.id}::prop`),
+    const propertyIds = new Set(
+      result.hasPropertyEdges
+        .filter((edge) => edge.fromId === userClass.id)
+        .map((edge) => edge.toId),
     );
+    const props = result.propertyEntities.filter((property) => propertyIds.has(property.id));
     expect(props.map(p => p.name).sort()).toEqual(['defaultCount', 'id', 'name']);
 
     const hasPropEdges = result.hasPropertyEdges.filter(r => r.fromId === userClass.id);
@@ -140,9 +142,9 @@ export class User {
     const userClass = result.classes.find(c => c.name === 'User')!;
     const greetMethod = result.methodEntities.find(m => m.name === 'greet')!;
 
-    // Method entity id uses generateEntityId format (same as extractFunctions would produce)
-    const expectedGreetId = generateEntityId(TEST_FILE, 'function', 'greet', greetMethod.startLine);
-    expect(greetMethod.id).toBe(expectedGreetId);
+    expect(greetMethod.id).toMatch(/^sym:v1:[a-f0-9]{64}$/);
+    expect(greetMethod.scopeKey).toBe('Class:User');
+    expect(greetMethod.disambiguator).toBe('');
 
     // Edge connects class to method using fromId/toId
     const edge = result.hasMethodEdges.find(e => e.toId === greetMethod.id);
@@ -232,8 +234,9 @@ export class Service {
     expect(methodNames).toEqual(['connect', 'create', 'init']);
 
     // Property entities appear in the top-level variables array
+    const propEdgeToIds = new Set(propEdges.map((edge) => edge.toId));
     const propNames = result.variables
-      .filter(v => v.id?.startsWith(`${classId}::prop`))
+      .filter((variable) => propEdgeToIds.has(variable.id))
       .map(v => v.name)
       .sort();
     expect(propNames).toEqual(['instances', 'name', 'version']);
@@ -1182,3 +1185,166 @@ type B = number;
     expect(result.types.map(t => t.name).sort()).toEqual(['A', 'B']);
   });
 });
+
+describe('TypeScript canonical symbol identity', () => {
+  beforeAll(() => {
+    parser = new Parser();
+    parser.setLanguage(grammars.typescript as Parameters<Parser['setLanguage']>[0]);
+    tsxParser = new Parser();
+    tsxParser.setLanguage(grammars.tsx as Parameters<Parser['setLanguage']>[0]);
+  });
+
+  it('gives same-named methods in different classes distinct owner-qualified ids', () => {
+    const result = runTSExtraction(`
+class First { work(): void {} }
+class Second { work(): void {} }
+`, '/project/src/services.ts');
+    const methods = result.functions.filter((entity) => entity.name === 'work');
+
+    expect(methods).toHaveLength(2);
+    expect(new Set(methods.map((entity) => entity.id)).size).toBe(2);
+    expect(methods.map((entity) => entity.scopeKey).sort()).toEqual([
+      'Class:First',
+      'Class:Second',
+    ]);
+    expect(methods.every((entity) => entity.disambiguator === '')).toBe(true);
+  });
+
+  it('uses normalized signature hashes for same-scope overloads', () => {
+    const result = runTSExtraction(`
+function parse(value: string): string;
+function parse(value: number): number;
+function parse(value: string | number): string | number { return value; }
+`, '/project/src/parse.ts');
+    const overloads = result.functions.filter((entity) => entity.name === 'parse');
+
+    expect(overloads).toHaveLength(3);
+    expect(new Set(overloads.map((entity) => entity.id)).size).toBe(3);
+    expect(overloads.every((entity) => entity.scopeKey === '')).toBe(true);
+    expect(overloads.every((entity) => entity.disambiguator.startsWith('sig:'))).toBe(true);
+    expect(overloads.map((entity) => Reflect.get(entity, 'isOverloadSignature'))).toEqual([
+      true,
+      true,
+      false,
+    ]);
+  });
+
+  it('qualifies nested functions by their full lexical owner chain', () => {
+    const result = runTSExtraction(`
+function outerA() { function helper() {} }
+function outerB() { function helper() {} }
+`, '/project/src/nested.ts');
+    const helpers = result.functions.filter((entity) => entity.name === 'helper');
+
+    expect(helpers).toHaveLength(2);
+    expect(new Set(helpers.map((entity) => entity.id)).size).toBe(2);
+    expect(helpers.map((entity) => entity.scopeKey).sort()).toEqual([
+      'Function:outerA',
+      'Function:outerB',
+    ]);
+  });
+
+  it('distinguishes a block-scoped variable from its top-level shadowed name', () => {
+    const result = runTSExtraction(`
+const state = 'top';
+if (enabled) {
+  const state = 'block';
+}
+`, '/project/src/shadow.ts');
+    const states = result.variables.filter((entity) => entity.name === 'state');
+
+    expect(states).toHaveLength(2);
+    expect(new Set(states.map((entity) => entity.id)).size).toBe(2);
+    expect(states.some((entity) => entity.scopeKey === '')).toBe(true);
+    expect(states.some((entity) => entity.scopeKey.includes('Block:if_statement'))).toBe(true);
+  });
+
+  it('collapses TypeScript interface declaration merging to one symbol id', () => {
+    const result = runTSExtraction(`
+interface Registry { first: string }
+interface Registry { second: number }
+`, '/project/src/registry.ts');
+    const declarations = result.interfaces.filter((entity) => entity.name === 'Registry');
+
+    expect(declarations).toHaveLength(1);
+    expect(declarations[0]).toMatchObject({
+      scopeKey: '',
+      disambiguator: '',
+      startLine: 2,
+      endLine: 3,
+    });
+  });
+
+  it('keeps ids stable when inserted lines shift source ranges', () => {
+    const before = runTSExtraction(
+      `function stable(value: string): string { return value; }`,
+      '/project/src/stable.ts',
+    ).functions.find((entity) => entity.name === 'stable');
+    const after = runTSExtraction(
+      `// inserted\n\nfunction stable(value: string): string { return value; }`,
+      '/project/src/stable.ts',
+    ).functions.find((entity) => entity.name === 'stable');
+
+    expect(before).toBeDefined();
+    expect(after).toBeDefined();
+    expect(before!.id).toBe(after!.id);
+    expect(before!.startLine).not.toBe(after!.startLine);
+  });
+
+  it('adds identity fields to every extracted source-symbol label', () => {
+    const ts = runTSExtraction(`
+class Service {}
+interface Contract {}
+function run(): void {}
+const value = 1;
+type Alias = string;
+`, '/project/src/all.ts');
+    const component = extractComponents(
+      parseTsx(`const Panel = (): JSX.Element => <section />;`),
+      '/project/src/panel.tsx',
+    )[0];
+    const symbols = [
+      ts.classes[0],
+      ts.interfaces[0],
+      ts.functions[0],
+      ts.variables[0],
+      ts.types[0],
+      component,
+    ];
+
+    for (const symbol of symbols) {
+      expect(symbol).toBeDefined();
+      expect(symbol!.id).toMatch(/^sym:v1:[a-f0-9]{64}$/);
+      expect(typeof symbol!.scopeKey).toBe('string');
+      expect(typeof symbol!.disambiguator).toBe('string');
+    }
+  });
+
+  it('uses occurrence ordinals only after scope and signature still collide', () => {
+    const result = runTSExtraction(`
+function duplicate(value: string): string { return value; }
+function duplicate(value: string): string { return value; }
+`, '/project/src/duplicates.ts');
+    const duplicates = result.functions.filter((entity) => entity.name === 'duplicate');
+
+    expect(duplicates).toHaveLength(2);
+    expect(duplicates.map((entity) => entity.disambiguator)).toEqual([
+      expect.stringMatching(/^sig:[a-f0-9]{16}\/occ:1$/),
+      expect.stringMatching(/^sig:[a-f0-9]{16}\/occ:2$/),
+    ]);
+    expect(new Set(duplicates.map((entity) => entity.id)).size).toBe(2);
+  });
+
+  it('keeps members distinct when duplicate owner declarations require the fallback', () => {
+    const result = runTSExtraction(`
+class Duplicate { work(): void {} }
+class Duplicate { work(): void {} }
+`, '/project/src/duplicate-owners.ts');
+    const classes = result.classes.filter((entity) => entity.name === 'Duplicate');
+    const methods = result.functions.filter((entity) => entity.name === 'work');
+
+    expect(classes.map((entity) => entity.disambiguator)).toEqual(['occ:1', 'occ:2']);
+    expect(new Set(classes.map((entity) => entity.id)).size).toBe(2);
+    expect(new Set(methods.map((entity) => entity.id)).size).toBe(2);
+  });
+});
diff --git a/packages/plugin-typescript/src/extractors/calls.ts b/packages/plugin-typescript/src/extractors/calls.ts
index ae04dc46..06f6f907 100644
--- a/packages/plugin-typescript/src/extractors/calls.ts
+++ b/packages/plugin-typescript/src/extractors/calls.ts
@@ -23,6 +23,10 @@ import type { ResolvedImportMap } from './imports';
  * (Function, Variable, Class, Interface), not just Function.
  */
 export interface CallReference {
+  /** Canonical caller symbol id once resolved. */
+  fromId?: string;
+  /** Canonical callee symbol id once resolved. */
+  toId?: string;
   /** Kind of the named entity containing the call. */
   callerKind: EnclosingKind;
   /** Name of the named entity containing the call. */
diff --git a/packages/plugin-typescript/src/extractors/classes.ts b/packages/plugin-typescript/src/extractors/classes.ts
index 73f80cf0..c8179b29 100644
--- a/packages/plugin-typescript/src/extractors/classes.ts
+++ b/packages/plugin-typescript/src/extractors/classes.ts
@@ -12,8 +12,13 @@ import type {
   HasMethodEdgeDescriptor,
   HasPropertyEdgeDescriptor,
 } from '@codegraph/types';
-import { findNodesOfType, getLocation, generateEntityId } from './types';
-import { calculateComplexity } from '@codegraph/plugin-common';
+import { findNodesOfType, getLocation, symbolIdentityForNode } from './types';
+import {
+  buildLexicalScopeKey,
+  calculateComplexity,
+  occurrenceDisambiguator,
+  signatureDisambiguator,
+} from '@codegraph/plugin-common';
 
 /** Visibility modifier */
 export type Visibility = 'public' | 'private' | 'protected';
@@ -86,47 +91,101 @@ export function extractClassesWithEdgesFromNodes(
   const propertyEntities: VariableEntity[] = [];
   const hasMethodEdges: HasMethodEdgeDescriptor[] = [];
   const hasPropertyEdges: HasPropertyEdgeDescriptor[] = [];
+  const classGroupSizes = new Map<string, number>();
+  for (const node of classNodes) {
+    const name = node.childForFieldName('name')?.text;
+    if (!name) continue;
+    const key = `${buildLexicalScopeKey(node)}\u0000${name}`;
+    classGroupSizes.set(key, (classGroupSizes.get(key) ?? 0) + 1);
+  }
+  const classOccurrences = new Map<string, number>();
 
   for (const node of classNodes) {
-    const classEntity = parseClassNode(node, filePath);
+    const className = node.childForFieldName('name')?.text;
+    if (!className) continue;
+    const classKey = `${buildLexicalScopeKey(node)}\u0000${className}`;
+    const classOccurrence = (classOccurrences.get(classKey) ?? 0) + 1;
+    classOccurrences.set(classKey, classOccurrence);
+    const classDisambiguator = (classGroupSizes.get(classKey) ?? 0) > 1
+      ? occurrenceDisambiguator(classOccurrence)
+      : '';
+    const classEntity = parseClassNode(node, filePath, classDisambiguator);
     if (!classEntity) continue;
     classes.push(classEntity);
 
-    // id is always set by parseClassNode via generateEntityId — guard for type safety
     const classId = classEntity.id;
-    if (!classId) continue;
+    const memberScopeKey = [
+      classEntity.scopeKey,
+      `Class:${className}${classDisambiguator ? `[${classDisambiguator}]` : ''}`,
+    ].filter(Boolean).join('/');
 
-    // Walk the class body for method_definition and public_field_definition nodes
+    // Walk the class body for runtime methods, overload declarations, and fields.
     const bodyNode = node.childForFieldName('body');
     if (!bodyNode) continue;
 
-    // Track property name counts for duplicate overload detection
+    const methodGroups = new Map<string, Parser.SyntaxNode[]>();
+    for (const member of bodyNode.children) {
+      if (member.type !== 'method_definition' && member.type !== 'method_signature') continue;
+      const methodName = member.childForFieldName('name')?.text;
+      if (!methodName) continue;
+      const group = methodGroups.get(methodName) ?? [];
+      group.push(member);
+      methodGroups.set(methodName, group);
+    }
+    const methodSignatureCounts = new Map<string, number>();
+    const methodSignatureTotals = new Map<string, number>();
+    for (const [methodName, members] of methodGroups) {
+      for (const member of members) {
+        const signatureKey = signatureDisambiguator(methodSignature(
+          extractMethodParameters(member),
+          getMethodReturnType(member),
+          member,
+        ));
+        const countKey = `${methodName}\u0000${signatureKey}`;
+        methodSignatureTotals.set(countKey, (methodSignatureTotals.get(countKey) ?? 0) + 1);
+      }
+    }
     const propNameCount = new Map<string, number>();
 
     for (const member of bodyNode.children) {
-      if (member.type === 'method_definition') {
+      if (member.type === 'method_definition' || member.type === 'method_signature') {
         const methodName = member.childForFieldName('name')?.text;
         if (!methodName) continue;
 
         const location = getLocation(member);
-        // Use generateEntityId format so the id matches what extractFunctions
-        // would produce for the same source node. Both paths use {filePath,
-        // startLine, name} as the natural graph key; using the same id format
-        // means HAS_METHOD edge toIds resolve correctly after MERGE.
-        const methodId = generateEntityId(filePath, 'function', methodName, location.startLine);
         const isStatic = hasMemberModifier(member, 'static');
         const visibility = getMemberVisibility(member);
         const isAsync = hasMemberModifier(member, 'async');
         const params = extractMethodParameters(member);
         const returnType = getMethodReturnType(member);
+        const methodGroup = methodGroups.get(methodName) ?? [];
+        let disambiguator = '';
+        if (methodGroup.length > 1) {
+          const signatureKey = signatureDisambiguator(methodSignature(params, returnType, member));
+          const countKey = `${methodName}\u0000${signatureKey}`;
+          const occurrence = (methodSignatureCounts.get(countKey) ?? 0) + 1;
+          methodSignatureCounts.set(countKey, occurrence);
+          disambiguator = (methodSignatureTotals.get(countKey) ?? 0) > 1
+            ? `${signatureKey}/${occurrenceDisambiguator(occurrence)}`
+            : signatureKey;
+        }
+        const methodIdentity = symbolIdentityForNode({
+          node: member,
+          filePath,
+          label: 'Function',
+          declaredName: methodName,
+          disambiguator,
+          scopeKeyOverride: memberScopeKey,
+        });
         const metrics = calculateComplexity(member);
 
         const methodEntity: FunctionEntity = {
-          id: methodId,
+          ...methodIdentity,
           name: methodName,
           filePath,
           startLine: location.startLine,
           endLine: location.endLine,
+          isOverloadSignature: member.type === 'method_signature',
           isExported: classEntity.isExported,
           isAsync,
           isArrow: false,
@@ -138,12 +197,14 @@ export function extractClassesWithEdgesFromNodes(
         if (returnType) methodEntity.returnType = returnType;
 
         methodEntities.push(methodEntity);
-        hasMethodEdges.push({
-          fromId: classId,
-          toId: methodId,
-          isStatic,
-          visibility,
-        });
+        if (member.type === 'method_definition' && member.childForFieldName('body')) {
+          hasMethodEdges.push({
+            fromId: classId,
+            toId: methodIdentity.id,
+            isStatic,
+            visibility,
+          });
+        }
 
       } else if (member.type === 'public_field_definition') {
         const propName = member.childForFieldName('name')?.text;
@@ -151,9 +212,15 @@ export function extractClassesWithEdgesFromNodes(
 
         const count = propNameCount.get(propName) ?? 0;
         propNameCount.set(propName, count + 1);
-        const suffix = count > 0 ? `:${count}` : '';
-
-        const propId = `${classId}::prop::${propName}${suffix}`;
+        const disambiguator = count > 0 ? occurrenceDisambiguator(count + 1) : '';
+        const propIdentity = symbolIdentityForNode({
+          node: member,
+          filePath,
+          label: 'Variable',
+          declaredName: propName,
+          disambiguator,
+          scopeKeyOverride: memberScopeKey,
+        });
         const line = member.startPosition.row + 1;
         const isStatic = hasMemberModifier(member, 'static');
         const visibility = getMemberVisibility(member);
@@ -164,7 +231,7 @@ export function extractClassesWithEdgesFromNodes(
         const type = typeAnnotation?.text?.replace(/^:\s*/, '') ?? '';
 
         const propEntity: VariableEntity = {
-          id: propId,
+          ...propIdentity,
           name: propName,
           filePath,
           line,
@@ -176,7 +243,7 @@ export function extractClassesWithEdgesFromNodes(
         propertyEntities.push(propEntity);
         hasPropertyEdges.push({
           fromId: classId,
-          toId: propId,
+          toId: propIdentity.id,
           isStatic,
           visibility,
           isReadonly,
@@ -188,6 +255,23 @@ export function extractClassesWithEdgesFromNodes(
   return { classes, methodEntities, propertyEntities, hasMethodEdges, hasPropertyEdges };
 }
 
+function methodSignature(
+  params: FunctionParam[],
+  returnType: string | undefined,
+  node: Parser.SyntaxNode,
+): string {
+  const parameterTypes = params.map((param) => {
+    const rest = param.isRest ? '...' : '';
+    const optional = param.optional ? '?' : '';
+    return `${rest}${param.type ?? '_'}${optional}`;
+  });
+  const typeParameters = node.childForFieldName('type_parameters');
+  const genericArity = typeParameters
+    ? typeParameters.namedChildren.filter((child) => child.type === 'type_parameter').length
+    : 0;
+  return `<${genericArity}>(${parameterTypes.join(',')})=>${returnType ?? '_'}`;
+}
+
 // ============================================================================
 // Member AST helpers
 // ============================================================================
@@ -213,7 +297,7 @@ function getMemberVisibility(node: Parser.SyntaxNode): Visibility {
   return 'public';
 }
 
-/** Extract parameters from a method_definition node */
+/** Extract parameters from a method definition or overload signature. */
 function extractMethodParameters(node: Parser.SyntaxNode): FunctionParam[] {
   const params: FunctionParam[] = [];
   const parametersNode = node.childForFieldName('parameters');
@@ -247,7 +331,7 @@ function extractMethodParameters(node: Parser.SyntaxNode): FunctionParam[] {
   return params;
 }
 
-/** Get return type annotation from a method_definition node */
+/** Get return type annotation from a method definition or overload signature. */
 function getMethodReturnType(node: Parser.SyntaxNode): string | undefined {
   return node.childForFieldName('return_type')?.text?.replace(/^:\s*/, '');
 }
@@ -257,7 +341,8 @@ function getMethodReturnType(node: Parser.SyntaxNode): string | undefined {
  */
 function parseClassNode(
   node: Parser.SyntaxNode,
-  filePath: string
+  filePath: string,
+  disambiguator: string,
 ): ClassEntity | null {
   // Get class name
   const nameNode = node.childForFieldName('name');
@@ -271,11 +356,17 @@ function parseClassNode(
   const implementsList = getImplementsList(node);
   const docstring = getDocstring(node);
   
-  const id = generateEntityId(filePath, 'class', name, location.startLine);
+  const identity = symbolIdentityForNode({
+    node,
+    filePath,
+    label: 'Class',
+    declaredName: name,
+    disambiguator,
+  });
   
   // Build entity with optional properties only when defined
   const entity: ClassEntity = {
-    id,
+    ...identity,
     name,
     filePath,
     startLine: location.startLine,
diff --git a/packages/plugin-typescript/src/extractors/functions.ts b/packages/plugin-typescript/src/extractors/functions.ts
index 5c17040f..26b32cfd 100644
--- a/packages/plugin-typescript/src/extractors/functions.ts
+++ b/packages/plugin-typescript/src/extractors/functions.ts
@@ -5,22 +5,28 @@
 
 import Parser from 'tree-sitter';
 import type { FunctionEntity, FunctionParam } from '@codegraph/types';
-import { findNodesOfTypes, getLocation, generateEntityId } from './types';
-import { calculateComplexity } from '@codegraph/plugin-common';
+import { findNodesOfTypes, getLocation, symbolIdentityForNode } from './types';
+import {
+  buildLexicalScopeKey,
+  calculateComplexity,
+  occurrenceDisambiguator,
+  signatureDisambiguator,
+} from '@codegraph/plugin-common';
 
 /**
  * Node types that represent top-level (non-class-method) function declarations.
- * method_definition is intentionally excluded — class methods are extracted by
- * extractClassesWithEdgesFromNodes, which emits them with generateEntityId-format
- * ids that match this extractor's id format. Including method_definition here would
- * produce duplicate Function entities with the same natural key (name/filePath/startLine),
- * causing HAS_METHOD edge descriptor toIds to silently mismatch the persisted node id.
+ * Runtime class methods are intentionally excluded because
+ * extractClassesWithEdgesFromNodes owns them. Class-body method signatures are
+ * collected here for standalone extraction, then filtered by parseFunctionNodes
+ * so they are not duplicated when class extraction also runs.
  */
 const FUNCTION_TYPES = [
   'function_declaration',
   'function_expression',
   'arrow_function',
   'generator_function_declaration',
+  'function_signature',
+  'method_signature',
 ];
 
 /**
@@ -30,18 +36,8 @@ export function extractFunctions(
   rootNode: Parser.SyntaxNode,
   filePath: string
 ): FunctionEntity[] {
-  const functions: FunctionEntity[] = [];
-  
   const functionNodes = findNodesOfTypes(rootNode, FUNCTION_TYPES);
-  
-  for (const node of functionNodes) {
-    const functionEntity = parseFunctionNode(node, filePath);
-    if (functionEntity) {
-      functions.push(functionEntity);
-    }
-  }
-  
-  return functions;
+  return parseFunctionNodes(functionNodes, filePath).map(({ entity }) => entity);
 }
 
 /**
@@ -51,14 +47,7 @@ export function extractFunctionsFromNodes(
   functionNodes: Parser.SyntaxNode[],
   filePath: string
 ): FunctionEntity[] {
-  const functions: FunctionEntity[] = [];
-  for (const node of functionNodes) {
-    const functionEntity = parseFunctionNode(node, filePath);
-    if (functionEntity) {
-      functions.push(functionEntity);
-    }
-  }
-  return functions;
+  return parseFunctionNodes(functionNodes, filePath).map(({ entity }) => entity);
 }
 
 /**
@@ -71,14 +60,57 @@ export function extractFunctionsWithNodes(
   functionNodes: Parser.SyntaxNode[],
   filePath: string
 ): Array<{ node: Parser.SyntaxNode; entity: FunctionEntity }> {
-  const pairs: Array<{ node: Parser.SyntaxNode; entity: FunctionEntity }> = [];
-  for (const node of functionNodes) {
-    const entity = parseFunctionNode(node, filePath);
-    if (entity) {
-      pairs.push({ node, entity });
+  return parseFunctionNodes(functionNodes, filePath);
+}
+
+function parseFunctionNodes(
+  functionNodes: Parser.SyntaxNode[],
+  filePath: string,
+): Array<{ node: Parser.SyntaxNode; entity: FunctionEntity }> {
+  const namedNodes = functionNodes.flatMap((node) => {
+    if (node.type === 'function_signature' && node.parent?.type === 'ambient_declaration') {
+      return [];
+    }
+    if (node.type === 'method_signature' && node.parent?.type === 'class_body') {
+      return [];
+    }
+    const name = getFunctionName(node);
+    return name ? [{ node, name, scopeKey: buildLexicalScopeKey(node) }] : [];
+  });
+  const groups = new Map<string, typeof namedNodes>();
+
+  for (const item of namedNodes) {
+    const key = `${item.scopeKey}\u0000${item.name}`;
+    const group = groups.get(key) ?? [];
+    group.push(item);
+    groups.set(key, group);
+  }
+
+  const result: Array<{ node: Parser.SyntaxNode; entity: FunctionEntity }> = [];
+  for (const group of groups.values()) {
+    const signatureCounts = new Map<string, number>();
+    const signatureTotals = new Map<string, number>();
+    for (const item of group) {
+      const signatureKey = signatureDisambiguator(declarationSignature(item.node));
+      signatureTotals.set(signatureKey, (signatureTotals.get(signatureKey) ?? 0) + 1);
+    }
+    for (const item of group) {
+      let disambiguator = '';
+      if (group.length > 1) {
+        const signature = declarationSignature(item.node);
+        const signatureKey = signatureDisambiguator(signature);
+        const occurrence = (signatureCounts.get(signatureKey) ?? 0) + 1;
+        signatureCounts.set(signatureKey, occurrence);
+        disambiguator = (signatureTotals.get(signatureKey) ?? 0) > 1
+          ? `${signatureKey}/${occurrenceDisambiguator(occurrence)}`
+          : signatureKey;
+      }
+      const entity = parseFunctionNode(item.node, filePath, disambiguator);
+      if (entity) result.push({ node: item.node, entity });
     }
   }
-  return pairs;
+
+  return result.sort((left, right) => left.node.startIndex - right.node.startIndex);
 }
 
 /**
@@ -86,7 +118,8 @@ export function extractFunctionsWithNodes(
  */
 function parseFunctionNode(
   node: Parser.SyntaxNode,
-  filePath: string
+  filePath: string,
+  disambiguator: string,
 ): FunctionEntity | null {
   // Get function name
   const name = getFunctionName(node);
@@ -103,18 +136,25 @@ function parseFunctionNode(
   const returnType = getReturnType(node);
   const docstring = getDocstring(node);
   
-  const id = generateEntityId(filePath, 'function', name, location.startLine);
+  const identity = symbolIdentityForNode({
+    node,
+    filePath,
+    label: 'Function',
+    declaredName: name,
+    disambiguator,
+  });
   
   // Calculate complexity metrics from the AST node
   const metrics = calculateComplexity(node);
 
   // Build entity with optional properties only when defined
   const entity: FunctionEntity = {
-    id,
+    ...identity,
     name,
     filePath,
     startLine: location.startLine,
     endLine: location.endLine,
+    isOverloadSignature: node.type === 'function_signature' || node.type === 'method_signature',
     isExported,
     isAsync,
     isArrow,
@@ -144,6 +184,19 @@ function parseFunctionNode(
   return entity;
 }
 
+function declarationSignature(node: Parser.SyntaxNode): string {
+  const params = extractParameters(node).map((param) => {
+    const rest = param.isRest ? '...' : '';
+    const optional = param.optional ? '?' : '';
+    return `${rest}${param.type ?? '_'}${optional}`;
+  });
+  const typeParameters = node.childForFieldName('type_parameters');
+  const genericArity = typeParameters
+    ? typeParameters.namedChildren.filter((child) => child.type === 'type_parameter').length
+    : 0;
+  return `<${genericArity}>(${params.join(',')})=>${getReturnType(node) ?? '_'}`;
+}
+
 /**
  * Get the name of a function from various node types
  */
diff --git a/packages/plugin-typescript/src/extractors/index.ts b/packages/plugin-typescript/src/extractors/index.ts
index 48182662..4aad4d4f 100644
--- a/packages/plugin-typescript/src/extractors/index.ts
+++ b/packages/plugin-typescript/src/extractors/index.ts
@@ -86,7 +86,7 @@ const ALL_ENTITY_NODE_TYPES = [
   'import_statement',
   // Functions
   'function_declaration', 'function_expression', 'arrow_function',
-  'method_definition', 'generator_function_declaration',
+  'method_definition', 'method_signature', 'generator_function_declaration', 'function_signature',
   // Classes
   'class_declaration', 'abstract_class_declaration', 'class',
   // Variables
@@ -108,7 +108,7 @@ export function extractAllEntities(
   filePath: string,
   resolvedImports?: ResolvedImportMap,
 ): ExtractedEntities {
-  // Single walk — collect all relevant nodes by type
+  // Single walk: collect all relevant nodes by type.
   const nodesByType = collectNodesByType(rootNode, ALL_ENTITY_NODE_TYPES);
 
   // Process each bucket with the appropriate extractor (no additional tree walking)
@@ -116,17 +116,22 @@ export function extractAllEntities(
     nodesByType.get('import_statement') ?? [], filePath
   );
 
-  // method_definition nodes are excluded from the function extractor — class methods
-  // are owned by extractClassesWithEdgesFromNodes, which emits them with
-  // generateEntityId-format ids that match this extractor's id format. Adding
-  // method_definition here would produce duplicate Function entities for the same
-  // source method (same name/filePath/startLine natural key) and cause HAS_METHOD
-  // edge toIds to mismatch the persisted node id after MERGE.
+  // Class method definitions and signatures are owned by class extraction.
+  // Interface method signatures remain in the general function extractor.
+  const classMethodSignatures = new Set(
+    (nodesByType.get('method_signature') ?? []).filter(
+      (node) => node.parent?.type === 'class_body',
+    ),
+  );
   const functionNodes = [
     ...(nodesByType.get('function_declaration') ?? []),
     ...(nodesByType.get('function_expression') ?? []),
     ...(nodesByType.get('arrow_function') ?? []),
     ...(nodesByType.get('generator_function_declaration') ?? []),
+    ...(nodesByType.get('function_signature') ?? []),
+    ...(nodesByType.get('method_signature') ?? []).filter(
+      (node) => !classMethodSignatures.has(node),
+    ),
   ];
 
   const functions = extractFunctionsFromNodes(functionNodes, filePath);
@@ -239,11 +244,14 @@ export function extractAllEntities(
     accumulateTypeRefs(node, entity.id);
   }
 
-  // Class methods: match AST nodes from the already-collected method_definition bucket.
-  const methodDefinitionNodes = nodesByType.get('method_definition') ?? [];
+  // Class methods: match runtime definitions and overload signatures collected in the single walk.
+  const classMethodNodes = [
+    ...(nodesByType.get('method_definition') ?? []),
+    ...classMethodSignatures,
+  ];
   for (const methodEntity of classExtraction.methodEntities) {
     if (!methodEntity.id) continue;
-    const astNode = methodDefinitionNodes.find(
+    const astNode = classMethodNodes.find(
       n =>
         n.startPosition.row + 1 === methodEntity.startLine &&
         n.childForFieldName('name')?.text === methodEntity.name,
diff --git a/packages/plugin-typescript/src/extractors/inheritance.ts b/packages/plugin-typescript/src/extractors/inheritance.ts
index 34a851c2..d6d554bf 100644
--- a/packages/plugin-typescript/src/extractors/inheritance.ts
+++ b/packages/plugin-typescript/src/extractors/inheritance.ts
@@ -10,6 +10,10 @@ import type { ClassEntity, InterfaceEntity, ImportEntity } from '@codegraph/type
  * Represents a class extends reference
  */
 export interface ExtendsReference {
+  /** Canonical child class id once resolved. */
+  fromId?: string;
+  /** Canonical parent class id once resolved. */
+  toId?: string;
   /** Name of the child class */
   childName: string;
   /** File path of the child class */
@@ -26,6 +30,10 @@ export interface ExtendsReference {
  * Represents a class implements reference
  */
 export interface ImplementsReference {
+  /** Canonical implementing class id once resolved. */
+  fromId?: string;
+  /** Canonical implemented interface id once resolved. */
+  toId?: string;
   /** Name of the implementing class */
   className: string;
   /** File path of the implementing class */
diff --git a/packages/plugin-typescript/src/extractors/jsx.ts b/packages/plugin-typescript/src/extractors/jsx.ts
index 19b8e557..275cf082 100644
--- a/packages/plugin-typescript/src/extractors/jsx.ts
+++ b/packages/plugin-typescript/src/extractors/jsx.ts
@@ -5,7 +5,8 @@
 
 import Parser from 'tree-sitter';
 import type { ComponentEntity, ComponentProp } from '@codegraph/types';
-import { findNodesOfTypes, getLocation, generateEntityId } from './types';
+import { findNodesOfTypes, getLocation, symbolIdentityForNode } from './types';
+import { buildLexicalScopeKey, occurrenceDisambiguator } from '@codegraph/plugin-common';
 
 /**
  * Extract all React component entities from a syntax tree
@@ -14,8 +15,6 @@ export function extractComponents(
   rootNode: Parser.SyntaxNode,
   filePath: string
 ): ComponentEntity[] {
-  const components: ComponentEntity[] = [];
-  
   // Find function declarations/expressions that return JSX
   const functionNodes = findNodesOfTypes(rootNode, [
     'function_declaration',
@@ -23,16 +22,7 @@ export function extractComponents(
     'function_expression',
   ]);
   
-  for (const node of functionNodes) {
-    if (isReactComponent(node)) {
-      const component = parseComponent(node, filePath);
-      if (component) {
-        components.push(component);
-      }
-    }
-  }
-  
-  return components;
+  return extractComponentsFromNodes(functionNodes, filePath);
 }
 
 /**
@@ -42,13 +32,29 @@ export function extractComponentsFromNodes(
   functionNodes: Parser.SyntaxNode[],
   filePath: string
 ): ComponentEntity[] {
+  const candidates = functionNodes.flatMap((node) => {
+    if (!isReactComponent(node)) return [];
+    const name = getComponentName(node);
+    if (!name || !/^[A-Z]/.test(name)) return [];
+    return [{ node, name, scopeKey: buildLexicalScopeKey(node) }];
+  });
+  const groupSizes = new Map<string, number>();
+  for (const candidate of candidates) {
+    const key = `${candidate.scopeKey}\u0000${candidate.name}`;
+    groupSizes.set(key, (groupSizes.get(key) ?? 0) + 1);
+  }
+  const occurrences = new Map<string, number>();
   const components: ComponentEntity[] = [];
-  for (const node of functionNodes) {
-    if (isReactComponent(node)) {
-      const component = parseComponent(node, filePath);
-      if (component) {
-        components.push(component);
-      }
+  for (const candidate of candidates) {
+    const key = `${candidate.scopeKey}\u0000${candidate.name}`;
+    const occurrence = (occurrences.get(key) ?? 0) + 1;
+    occurrences.set(key, occurrence);
+    const disambiguator = (groupSizes.get(key) ?? 0) > 1
+      ? occurrenceDisambiguator(occurrence)
+      : '';
+    const component = parseComponent(candidate.node, filePath, disambiguator);
+    if (component) {
+      components.push(component);
     }
   }
   return components;
@@ -116,7 +122,8 @@ function isJsxNode(node: Parser.SyntaxNode): boolean {
  */
 function parseComponent(
   node: Parser.SyntaxNode,
-  filePath: string
+  filePath: string,
+  disambiguator: string,
 ): ComponentEntity | null {
   const name = getComponentName(node);
   if (!name) return null;
@@ -128,11 +135,17 @@ function parseComponent(
   const isExported = checkIsExported(node);
   const propsInfo = extractPropsInfo(node);
   
-  const id = generateEntityId(filePath, 'component', name, location.startLine);
+  const identity = symbolIdentityForNode({
+    node,
+    filePath,
+    label: 'Component',
+    declaredName: name,
+    disambiguator,
+  });
   
   // Build entity with optional properties only when defined
   const entity: ComponentEntity = {
-    id,
+    ...identity,
     name,
     filePath,
     startLine: location.startLine,
diff --git a/packages/plugin-typescript/src/extractors/renders.ts b/packages/plugin-typescript/src/extractors/renders.ts
index e8830809..0c224667 100644
--- a/packages/plugin-typescript/src/extractors/renders.ts
+++ b/packages/plugin-typescript/src/extractors/renders.ts
@@ -11,6 +11,10 @@ import { findNodesOfTypes } from './types';
  * Represents a component render reference
  */
 export interface RenderReference {
+  /** Canonical rendering component id once resolved. */
+  fromId?: string;
+  /** Canonical rendered component id once resolved. */
+  toId?: string;
   /** Name of the parent component */
   parentName: string;
   /** File path of the parent component */
diff --git a/packages/plugin-typescript/src/extractors/type-aliases.ts b/packages/plugin-typescript/src/extractors/type-aliases.ts
index 3a724bf2..e6755556 100644
--- a/packages/plugin-typescript/src/extractors/type-aliases.ts
+++ b/packages/plugin-typescript/src/extractors/type-aliases.ts
@@ -5,7 +5,8 @@
 
 import Parser from 'tree-sitter';
 import type { TypeEntity, InterfaceEntity } from '@codegraph/types';
-import { findNodesOfType, getLocation, generateEntityId } from './types';
+import { findNodesOfType, getLocation, symbolIdentityForNode } from './types';
+import { buildLexicalScopeKey, occurrenceDisambiguator } from '@codegraph/plugin-common';
 
 /**
  * Extract all type entities from a syntax tree
@@ -14,27 +15,9 @@ export function extractTypes(
   rootNode: Parser.SyntaxNode,
   filePath: string
 ): TypeEntity[] {
-  const types: TypeEntity[] = [];
-  
-  // Type aliases
   const typeAliasNodes = findNodesOfType(rootNode, 'type_alias_declaration');
-  for (const node of typeAliasNodes) {
-    const typeEntity = parseTypeAlias(node, filePath);
-    if (typeEntity) {
-      types.push(typeEntity);
-    }
-  }
-  
-  // Enums
   const enumNodes = findNodesOfType(rootNode, 'enum_declaration');
-  for (const node of enumNodes) {
-    const enumEntity = parseEnum(node, filePath);
-    if (enumEntity) {
-      types.push(enumEntity);
-    }
-  }
-  
-  return types;
+  return extractTypeDeclarationsFromNodes(typeAliasNodes, enumNodes, filePath);
 }
 
 /**
@@ -55,7 +38,7 @@ export function extractInterfaces(
     }
   }
   
-  return interfaces;
+  return mergeInterfaceDeclarations(interfaces);
 }
 
 /**
@@ -66,16 +49,45 @@ export function extractTypesFromNodes(
   enumNodes: Parser.SyntaxNode[],
   filePath: string
 ): TypeEntity[] {
-  const types: TypeEntity[] = [];
-  for (const node of typeAliasNodes) {
-    const typeEntity = parseTypeAlias(node, filePath);
-    if (typeEntity) types.push(typeEntity);
+  return extractTypeDeclarationsFromNodes(typeAliasNodes, enumNodes, filePath);
+}
+
+function extractTypeDeclarationsFromNodes(
+  typeAliasNodes: Parser.SyntaxNode[],
+  enumNodes: Parser.SyntaxNode[],
+  filePath: string,
+): TypeEntity[] {
+  const candidates = [
+    ...typeAliasNodes.map((node) => ({ node, kind: 'type' as const })),
+    ...enumNodes.map((node) => ({ node, kind: 'enum' as const })),
+  ].flatMap((candidate) => {
+    const name = candidate.node.childForFieldName('name')?.text;
+    return name ? [{ ...candidate, name, scopeKey: buildLexicalScopeKey(candidate.node) }] : [];
+  }).sort((left, right) => left.node.startIndex - right.node.startIndex);
+
+  const groups = new Map<string, typeof candidates>();
+  for (const candidate of candidates) {
+    const key = `${candidate.scopeKey}\u0000${candidate.name}`;
+    const group = groups.get(key) ?? [];
+    group.push(candidate);
+    groups.set(key, group);
   }
-  for (const node of enumNodes) {
-    const enumEntity = parseEnum(node, filePath);
-    if (enumEntity) types.push(enumEntity);
+
+  const types: TypeEntity[] = [];
+  for (const group of groups.values()) {
+    const declarationsMerge = group.every((candidate) => candidate.kind === 'enum');
+    for (let index = 0; index < group.length; index++) {
+      const candidate = group[index]!;
+      const disambiguator = group.length > 1 && !declarationsMerge
+        ? occurrenceDisambiguator(index + 1)
+        : '';
+      const entity = candidate.kind === 'enum'
+        ? parseEnum(candidate.node, filePath, disambiguator)
+        : parseTypeAlias(candidate.node, filePath, disambiguator);
+      if (entity) types.push(entity);
+    }
   }
-  return types;
+  return mergeTypeDeclarations(types);
 }
 
 /**
@@ -90,7 +102,7 @@ export function extractInterfacesFromNodes(
     const interfaceEntity = parseInterface(node, filePath);
     if (interfaceEntity) interfaces.push(interfaceEntity);
   }
-  return interfaces;
+  return mergeInterfaceDeclarations(interfaces);
 }
 
 /**
@@ -98,7 +110,8 @@ export function extractInterfacesFromNodes(
  */
 function parseTypeAlias(
   node: Parser.SyntaxNode,
-  filePath: string
+  filePath: string,
+  disambiguator: string,
 ): TypeEntity | null {
   const nameNode = node.childForFieldName('name');
   const name = nameNode?.text;
@@ -108,11 +121,17 @@ function parseTypeAlias(
   const isExported = checkIsExported(node);
   const docstring = getDocstring(node);
   
-  const id = generateEntityId(filePath, 'type', name, location.startLine);
+  const identity = symbolIdentityForNode({
+    node,
+    filePath,
+    label: 'Type',
+    declaredName: name,
+    disambiguator,
+  });
   
   // Build entity with optional properties only when defined
   const entity: TypeEntity = {
-    id,
+    ...identity,
     name,
     filePath,
     startLine: location.startLine,
@@ -131,7 +150,8 @@ function parseTypeAlias(
  */
 function parseEnum(
   node: Parser.SyntaxNode,
-  filePath: string
+  filePath: string,
+  disambiguator: string,
 ): TypeEntity | null {
   const nameNode = node.childForFieldName('name');
   const name = nameNode?.text;
@@ -141,11 +161,17 @@ function parseEnum(
   const isExported = checkIsExported(node);
   const docstring = getDocstring(node);
   
-  const id = generateEntityId(filePath, 'enum', name, location.startLine);
+  const identity = symbolIdentityForNode({
+    node,
+    filePath,
+    label: 'Type',
+    declaredName: name,
+    disambiguator,
+  });
   
   // Build entity with optional properties only when defined
   const entity: TypeEntity = {
-    id,
+    ...identity,
     name,
     filePath,
     startLine: location.startLine,
@@ -175,11 +201,16 @@ function parseInterface(
   const extendsList = getExtendsList(node);
   const docstring = getDocstring(node);
   
-  const id = generateEntityId(filePath, 'interface', name, location.startLine);
+  const identity = symbolIdentityForNode({
+    node,
+    filePath,
+    label: 'Interface',
+    declaredName: name,
+  });
   
   // Build entity with optional properties only when defined
   const entity: InterfaceEntity = {
-    id,
+    ...identity,
     name,
     filePath,
     startLine: location.startLine,
@@ -193,6 +224,39 @@ function parseInterface(
   return entity;
 }
 
+function mergeInterfaceDeclarations(interfaces: InterfaceEntity[]): InterfaceEntity[] {
+  const merged = new Map<string, InterfaceEntity>();
+  for (const declaration of interfaces) {
+    const existing = merged.get(declaration.id);
+    if (!existing) {
+      merged.set(declaration.id, declaration);
+      continue;
+    }
+    existing.startLine = Math.min(existing.startLine, declaration.startLine);
+    existing.endLine = Math.max(existing.endLine, declaration.endLine);
+    existing.isExported ||= declaration.isExported;
+    existing.extends = Array.from(new Set([...(existing.extends ?? []), ...(declaration.extends ?? [])]));
+    if (!existing.docstring && declaration.docstring) existing.docstring = declaration.docstring;
+  }
+  return Array.from(merged.values());
+}
+
+function mergeTypeDeclarations(types: TypeEntity[]): TypeEntity[] {
+  const merged = new Map<string, TypeEntity>();
+  for (const declaration of types) {
+    const existing = merged.get(declaration.id);
+    if (!existing) {
+      merged.set(declaration.id, declaration);
+      continue;
+    }
+    existing.startLine = Math.min(existing.startLine, declaration.startLine);
+    existing.endLine = Math.max(existing.endLine, declaration.endLine);
+    existing.isExported ||= declaration.isExported;
+    if (!existing.docstring && declaration.docstring) existing.docstring = declaration.docstring;
+  }
+  return Array.from(merged.values());
+}
+
 /**
  * Check if the type is exported
  */
diff --git a/packages/plugin-typescript/src/extractors/types.ts b/packages/plugin-typescript/src/extractors/types.ts
index d41e4ed8..0d18e142 100644
--- a/packages/plugin-typescript/src/extractors/types.ts
+++ b/packages/plugin-typescript/src/extractors/types.ts
@@ -3,6 +3,12 @@
  */
 
 import Parser from 'tree-sitter';
+import {
+  buildLexicalScopeKey,
+  buildSymbolIdentity,
+  type SourceSymbolLabel,
+  type SymbolIdentity,
+} from '@codegraph/plugin-common';
 
 /** Location information in source code */
 export interface SourceLocation {
@@ -141,3 +147,24 @@ export function generateEntityId(filePath: string, kind: string, name: string, l
   // Simple hash-like ID
   return base.replace(/[^a-zA-Z0-9:_-]/g, '_');
 }
+
+/** Build the canonical identity fields for a TypeScript source symbol node. */
+export function symbolIdentityForNode(options: {
+  node: Parser.SyntaxNode;
+  filePath: string;
+  label: SourceSymbolLabel;
+  declaredName: string;
+  disambiguator?: string;
+  includeBlockScopes?: boolean;
+  scopeKeyOverride?: string;
+}): SymbolIdentity {
+  return buildSymbolIdentity({
+    label: options.label,
+    filePath: options.filePath,
+    scopeKey: options.scopeKeyOverride ?? buildLexicalScopeKey(options.node, {
+      includeBlockScopes: options.includeBlockScopes ?? false,
+    }),
+    declaredName: options.declaredName,
+    disambiguator: options.disambiguator ?? '',
+  });
+}
diff --git a/packages/plugin-typescript/src/extractors/variables.ts b/packages/plugin-typescript/src/extractors/variables.ts
index b4f4e370..3b28e0f4 100644
--- a/packages/plugin-typescript/src/extractors/variables.ts
+++ b/packages/plugin-typescript/src/extractors/variables.ts
@@ -5,7 +5,8 @@
 
 import Parser from 'tree-sitter';
 import type { VariableEntity, VariableKind } from '@codegraph/types';
-import { findNodesOfTypes, generateEntityId } from './types';
+import { findNodesOfTypes, symbolIdentityForNode } from './types';
+import { buildLexicalScopeKey, occurrenceDisambiguator } from '@codegraph/plugin-common';
 
 /** Node types for variable declarations */
 const VARIABLE_TYPES = [
@@ -20,16 +21,8 @@ export function extractVariables(
   rootNode: Parser.SyntaxNode,
   filePath: string
 ): VariableEntity[] {
-  const variables: VariableEntity[] = [];
-  
   const declarationNodes = findNodesOfTypes(rootNode, VARIABLE_TYPES);
-  
-  for (const node of declarationNodes) {
-    const extracted = parseVariableDeclaration(node, filePath);
-    variables.push(...extracted);
-  }
-  
-  return variables;
+  return extractVariablesFromNodes(declarationNodes, filePath);
 }
 
 /**
@@ -39,39 +32,56 @@ export function extractVariablesFromNodes(
   declarationNodes: Parser.SyntaxNode[],
   filePath: string
 ): VariableEntity[] {
-  const variables: VariableEntity[] = [];
-  for (const node of declarationNodes) {
-    const extracted = parseVariableDeclaration(node, filePath);
-    variables.push(...extracted);
-  }
-  return variables;
-}
+  const candidates: Array<{
+    node: Parser.SyntaxNode;
+    name: string;
+    kind: VariableKind;
+    isExported: boolean;
+    scopeKey: string;
+  }> = [];
 
-/**
- * Parse a variable declaration node
- * Returns multiple entities since one declaration can have multiple declarators
- */
-function parseVariableDeclaration(
-  node: Parser.SyntaxNode,
-  filePath: string
-): VariableEntity[] {
-  const variables: VariableEntity[] = [];
-  
-  // Determine the kind (const, let, var)
-  const kind = getVariableKind(node);
-  const isExported = checkIsExported(node);
-  
-  // Find all variable_declarator children
-  for (const child of node.children) {
-    if (child.type === 'variable_declarator') {
-      const varEntity = parseVariableDeclarator(child, filePath, kind, isExported);
-      if (varEntity) {
-        variables.push(varEntity);
+  for (const node of declarationNodes) {
+    const kind = getVariableKind(node);
+    const isExported = checkIsExported(node);
+    for (const child of node.children) {
+      if (child.type !== 'variable_declarator') continue;
+      const nameNode = child.childForFieldName('name');
+      if (!nameNode || nameNode.type === 'object_pattern' || nameNode.type === 'array_pattern') {
+        continue;
       }
+      candidates.push({
+        node: child,
+        name: nameNode.text,
+        kind,
+        isExported,
+        scopeKey: buildLexicalScopeKey(child, { includeBlockScopes: true }),
+      });
     }
   }
-  
-  return variables;
+
+  const groupSizes = new Map<string, number>();
+  for (const candidate of candidates) {
+    const key = `${candidate.scopeKey}\u0000${candidate.name}`;
+    groupSizes.set(key, (groupSizes.get(key) ?? 0) + 1);
+  }
+  const occurrences = new Map<string, number>();
+
+  return candidates.flatMap((candidate) => {
+    const key = `${candidate.scopeKey}\u0000${candidate.name}`;
+    const occurrence = (occurrences.get(key) ?? 0) + 1;
+    occurrences.set(key, occurrence);
+    const disambiguator = (groupSizes.get(key) ?? 0) > 1
+      ? occurrenceDisambiguator(occurrence)
+      : '';
+    const entity = parseVariableDeclarator(
+      candidate.node,
+      filePath,
+      candidate.kind,
+      candidate.isExported,
+      disambiguator,
+    );
+    return entity ? [entity] : [];
+  });
 }
 
 /**
@@ -107,7 +117,8 @@ function parseVariableDeclarator(
   node: Parser.SyntaxNode,
   filePath: string,
   kind: VariableKind,
-  isExported: boolean
+  isExported: boolean,
+  disambiguator: string,
 ): VariableEntity | null {
   // Get the variable name
   const nameNode = node.childForFieldName('name');
@@ -125,11 +136,18 @@ function parseVariableDeclarator(
   const typeAnnotation = node.childForFieldName('type');
   const type = typeAnnotation?.text?.replace(/^:\s*/, '');
   
-  const id = generateEntityId(filePath, 'variable', name, line);
+  const identity = symbolIdentityForNode({
+    node,
+    filePath,
+    label: 'Variable',
+    declaredName: name,
+    disambiguator,
+    includeBlockScopes: true,
+  });
   
   // Build entity with optional properties only when defined
   const entity: VariableEntity = {
-    id,
+    ...identity,
     name,
     filePath,
     line,
diff --git a/packages/types/src/edges.ts b/packages/types/src/edges.ts
index d727511f..3855617b 100644
--- a/packages/types/src/edges.ts
+++ b/packages/types/src/edges.ts
@@ -72,6 +72,10 @@ export interface ImportsSymbolEdge extends BaseEdge {
  * both declaration nodes.
  */
 export interface ImportsSymbolEdgeDescriptor {
+  /** Canonical importing File id once resolved by the pipeline. */
+  fromId?: string;
+  /** Canonical imported symbol id once resolved by the pipeline. */
+  toId?: string;
   /** Importing file's path (File node). */
   fromFilePath: string;
   /** File path where the imported symbol is actually declared. */
@@ -112,6 +116,10 @@ export interface ExportsEdge extends BaseEdge {
  * @codegraph/graph's operations.ts).
  */
 export interface ExportsEdgeDescriptor {
+  /** Canonical exporting File id once resolved by the pipeline. */
+  fromId?: string;
+  /** Canonical exported symbol id once resolved by the pipeline. */
+  toId?: string;
   /** Exporting file's path (File node). */
   filePath: string;
   /** Exported symbol's name. */
diff --git a/packages/types/src/nodes.ts b/packages/types/src/nodes.ts
index 056615ae..5f2ff8ee 100644
--- a/packages/types/src/nodes.ts
+++ b/packages/types/src/nodes.ts
@@ -27,6 +27,16 @@ export interface BaseEntity extends ProvenanceFields {
   filePath: string;
 }
 
+/** Stable identity carried by every source-level symbol entity. */
+export interface SymbolIdentityFields {
+  /** Canonical opaque symbol identifier. */
+  id: string;
+  /** Inspectable lexical owner chain used to build id. */
+  scopeKey: string;
+  /** Inspectable same-scope qualifier used to build id. */
+  disambiguator: string;
+}
+
 /** Common properties for entities with line ranges */
 export interface RangeEntity extends BaseEntity {
   /** Starting line number (1-indexed) */
@@ -35,6 +45,18 @@ export interface RangeEntity extends BaseEntity {
   endLine: number;
 }
 
+/** Common properties for source symbols with stable identity and line ranges. */
+export interface RangeSymbolEntity extends ProvenanceFields, SymbolIdentityFields {
+  /** Name of the symbol. */
+  name: string;
+  /** Absolute path to the file containing this symbol. */
+  filePath: string;
+  /** Starting line number (1-indexed). */
+  startLine: number;
+  /** Ending line number (1-indexed). */
+  endLine: number;
+}
+
 // ============================================================================
 // File Entity
 // ============================================================================
@@ -66,7 +88,7 @@ export interface FileEntity extends ProvenanceFields {
 // ============================================================================
 
 /** Represents a class declaration */
-export interface ClassEntity extends RangeEntity {
+export interface ClassEntity extends RangeSymbolEntity {
   /** Whether the class is exported */
   isExported: boolean;
   /** Whether the class is abstract */
@@ -88,7 +110,7 @@ export interface ClassEntity extends RangeEntity {
 // ============================================================================
 
 /** Represents an interface declaration */
-export interface InterfaceEntity extends RangeEntity {
+export interface InterfaceEntity extends RangeSymbolEntity {
   /** Whether the interface is exported */
   isExported: boolean;
   /** Extended interfaces */
@@ -120,7 +142,9 @@ export interface FunctionParam {
 }
 
 /** Represents a function or method declaration */
-export interface FunctionEntity extends RangeEntity {
+export interface FunctionEntity extends RangeSymbolEntity {
+  /** Whether this node is an overload declaration without a runtime body. */
+  isOverloadSignature?: boolean;
   /** Whether the function is exported */
   isExported: boolean;
   /** Whether the function is async */
@@ -157,9 +181,8 @@ export interface FunctionEntity extends RangeEntity {
 export type VariableKind = 'const' | 'let' | 'var';
 
 /** Represents a variable declaration */
-export interface VariableEntity extends ProvenanceFields {
+export interface VariableEntity extends ProvenanceFields, SymbolIdentityFields {
   /** Unique identifier */
-  id?: string;
   /** Variable name */
   name: string;
   /** Absolute path to the file containing this variable */
@@ -248,7 +271,7 @@ export interface TypeRefEntity {
 export type TypeKind = 'type' | 'enum';
 
 /** Represents a type alias or enum declaration */
-export interface TypeEntity extends RangeEntity {
+export interface TypeEntity extends RangeSymbolEntity {
   /** Whether the type is exported */
   isExported: boolean;
   /** Type kind (type alias or enum) */
@@ -276,7 +299,7 @@ export interface ComponentProp {
 }
 
 /** Represents a React component */
-export interface ComponentEntity extends RangeEntity {
+export interface ComponentEntity extends RangeSymbolEntity {
   /** Whether the component is exported */
   isExported: boolean;
   /** Component props interface/type */
@@ -361,4 +384,3 @@ export type NodeLabel =
   | 'Section'
   | 'CodeBlock'
   | 'Link';
-
diff --git a/packages/types/src/plugin.ts b/packages/types/src/plugin.ts
index 4097ca5e..7f7b3f93 100644
--- a/packages/types/src/plugin.ts
+++ b/packages/types/src/plugin.ts
@@ -110,6 +110,10 @@ export interface CallExtractionContext {
 
 /** Call reference for edge creation */
 export interface CallReference {
+  /** Canonical caller symbol id once resolved. */
+  fromId?: string;
+  /** Canonical callee symbol id once resolved. */
+  toId?: string;
   callerName: string;
   calleeName: string;
   line: number;
@@ -124,6 +128,10 @@ export interface CallReference {
 
 /** Render reference for React component edges */
 export interface RenderReference {
+  /** Canonical rendering component id once resolved. */
+  fromId?: string;
+  /** Canonical rendered component id once resolved. */
+  toId?: string;
   componentName: string;
   renderedComponent: string;
   line: number;
@@ -132,6 +140,10 @@ export interface RenderReference {
 
 /** Inheritance reference for extends/implements edges */
 export interface InheritanceReference {
+  /** Canonical child declaration id once resolved. */
+  fromId?: string;
+  /** Canonical parent declaration id once resolved. */
+  toId?: string;
   childName: string;
   parentName: string;
   type: 'extends' | 'implements';

From 807e126780d7e7516d009d59d673d67faf4ad0d7 Mon Sep 17 00:00:00 2001
From: Randy Wilson <phoenixrr2113@gmail.com>
Date: Fri, 21 Aug 2026 19:31:26 -0400
Subject: [PATCH 2/4] Never send undefined query parameters to the graph client

The remote FalkorDB client rejects undefined parameter values; the
embedded driver tolerated them, which hid the gap from local testing.
Entities seeded without canonical ids now get them derived at the write
boundary, and a regression test drives all six legacy symbol shapes
through the real params path asserting no undefined survives at any
depth.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../src/__tests__/client-query-params.test.ts | 124 ++++++++++++++++++
 .../src/__tests__/falkordb-operations.test.ts |  33 ++---
 packages/graph/src/client.ts                  |  22 +++-
 packages/graph/src/schema.ts                  |  66 +++++++---
 4 files changed, 210 insertions(+), 35 deletions(-)
 create mode 100644 packages/graph/src/__tests__/client-query-params.test.ts

diff --git a/packages/graph/src/__tests__/client-query-params.test.ts b/packages/graph/src/__tests__/client-query-params.test.ts
new file mode 100644
index 00000000..a738d2d5
--- /dev/null
+++ b/packages/graph/src/__tests__/client-query-params.test.ts
@@ -0,0 +1,124 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { QueryParams, QueryResult } from '../client';
+import { createClient } from '../client';
+import type { DriverConfig } from '../driver';
+import { FalkorDBLiteDriver } from '../drivers/falkordblite';
+import { createOperations } from '../operations';
+import type { ParsedFileEntities } from '../schema';
+
+function findUndefinedPaths(value: unknown, path: string): string[] {
+  if (value === undefined) return [path];
+  if (value === null || typeof value !== 'object') return [];
+
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => findUndefinedPaths(item, `${path}[${index}]`));
+  }
+
+  return Object.entries(value).flatMap(([key, item]) =>
+    findUndefinedPaths(item, `${path}.${key}`),
+  );
+}
+
+function legacyEntities(): ParsedFileEntities {
+  return {
+    file: {
+      path: '/src/legacy-shapes.ts',
+      name: 'legacy-shapes.ts',
+      extension: 'ts',
+      loc: 30,
+      lastModified: '2026-08-21T00:00:00.000Z',
+      hash: 'legacy-shapes',
+    },
+    functions: [{
+      name: 'legacyFunction', filePath: '/src/legacy-shapes.ts', startLine: 1, endLine: 3,
+      isExported: true, isAsync: false, isArrow: false, params: [],
+    }],
+    classes: [{
+      name: 'LegacyClass', filePath: '/src/legacy-shapes.ts', startLine: 5, endLine: 10,
+      isExported: true, isAbstract: false,
+    }],
+    interfaces: [{
+      name: 'LegacyInterface', filePath: '/src/legacy-shapes.ts', startLine: 12, endLine: 14,
+      isExported: true,
+    }],
+    variables: [{
+      name: 'legacyVariable', filePath: '/src/legacy-shapes.ts', line: 16,
+      kind: 'const', isExported: false,
+    }],
+    types: [{
+      name: 'LegacyType', filePath: '/src/legacy-shapes.ts', startLine: 18, endLine: 18,
+      isExported: true, kind: 'type',
+    }],
+    components: [{
+      name: 'LegacyComponent', filePath: '/src/legacy-shapes.ts', startLine: 20, endLine: 28,
+      isExported: true,
+    }],
+    imports: [],
+    callEdges: [],
+    importsEdges: [],
+    extendsEdges: [],
+    implementsEdges: [],
+    rendersEdges: [],
+    hasMethodEdges: [],
+    hasPropertyEdges: [],
+    typeRefs: [],
+    hasParamEdges: [],
+    returnsEdges: [],
+    usesTypeEdges: [],
+    exportsEdges: [],
+    importsSymbolEdges: [],
+  } as unknown as ParsedFileEntities;
+}
+
+describe('graph client query parameter boundary', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('replaces undefined values in direct and batched legacy entity writes before the driver receives params', async () => {
+    const receivedParams: QueryParams[] = [];
+
+    vi.spyOn(FalkorDBLiteDriver.prototype, 'connect').mockImplementation(
+      async (_config: DriverConfig): Promise<void> => {},
+    );
+    vi.spyOn(FalkorDBLiteDriver.prototype, 'query').mockImplementation(
+      async <T>(_cypher: string, params?: QueryParams): Promise<QueryResult<T>> => {
+        receivedParams.push(params ?? {});
+        return { data: [], metadata: [] };
+      },
+    );
+    vi.spyOn(FalkorDBLiteDriver.prototype, 'close').mockImplementation(
+      async (): Promise<void> => {},
+    );
+
+    const client = await createClient({ driver: 'falkordblite' });
+    const operations = createOperations(client);
+    const entities = legacyEntities();
+
+    await operations.batchUpsert(entities);
+    await operations.batchUpsertBulk([entities]);
+    await client.close();
+
+    const undefinedPaths = receivedParams.flatMap((params, index) =>
+      findUndefinedPaths(params, `params[${index}]`),
+    );
+    const batchedItems = receivedParams.flatMap((params) => {
+      const items = params['items'];
+      return Array.isArray(items) ? items : [];
+    });
+    const directSymbolParams = receivedParams.filter((params) => 'scopeKey' in params);
+    const batchedSymbolParams = batchedItems.filter((item): item is Record<string, unknown> => (
+      typeof item === 'object' && item !== null && 'scopeKey' in item
+    ));
+
+    expect(receivedParams.length).toBeGreaterThan(0);
+    expect(undefinedPaths).toEqual([]);
+    expect(directSymbolParams).toHaveLength(6);
+    expect(batchedSymbolParams).toHaveLength(6);
+    for (const params of [...directSymbolParams, ...batchedSymbolParams]) {
+      expect(params['id']).toMatch(/^sym:v1:[0-9a-f]{64}$/);
+      expect(params['scopeKey']).toBe('');
+      expect(params['disambiguator']).toBe('');
+    }
+  });
+});
diff --git a/packages/graph/src/__tests__/falkordb-operations.test.ts b/packages/graph/src/__tests__/falkordb-operations.test.ts
index 18169bb0..f0cad313 100644
--- a/packages/graph/src/__tests__/falkordb-operations.test.ts
+++ b/packages/graph/src/__tests__/falkordb-operations.test.ts
@@ -644,7 +644,7 @@ describe('Graph CRUD Operations (FalkorDB)', () => {
       expect(afterFn.data[0]?.count).toBe(0);
     });
 
-    it('preserves entities with incoming cross-file CALLS edges', async () => {
+    it('removes owned entities and incoming cross-file CALLS edges with the deleted file', async () => {
       // Setup: File A has fnA, File B has fnB, fnA CALLS fnB
       await ops.upsertFile(makeFile({ path: '/src/perf4-caller.ts', name: 'perf4-caller.ts' }));
       await ops.upsertFunction(makeFunction({ name: 'fnCaller', filePath: '/src/perf4-caller.ts', startLine: 1 }));
@@ -661,7 +661,7 @@ describe('Graph CRUD Operations (FalkorDB)', () => {
       );
       expect(edgeBefore.data[0]?.count).toBe(1);
 
-      // Remove the CALLEE file: the function should be preserved because fnCaller still points to it
+      // Removing a source file detach-deletes every declaration owned by it.
       await ops.removeFileAndCleanup('/src/perf4-callee.ts');
 
       // File node should be gone
@@ -670,20 +670,19 @@ describe('Graph CRUD Operations (FalkorDB)', () => {
       );
       expect(afterFile.data[0]?.count).toBe(0);
 
-      // fnCallee should STILL exist (preserved by incoming CALLS edge)
+      // fnCallee and its incoming CALLS edge should both be gone.
       const afterFn = await client.roQuery<{ count: number }>(
         `MATCH (fn:Function {name: 'fnCallee', filePath: '/src/perf4-callee.ts'}) RETURN count(fn) as count`
       );
-      expect(afterFn.data[0]?.count).toBe(1);
+      expect(afterFn.data[0]?.count).toBe(0);
 
-      // CALLS edge should still be intact
       const edgeAfter = await client.roQuery<{ count: number }>(
         `MATCH (a:Function {name: 'fnCaller'})-[:CALLS]->(b:Function {name: 'fnCallee'}) RETURN count(*) as count`
       );
-      expect(edgeAfter.data[0]?.count).toBe(1);
+      expect(edgeAfter.data[0]?.count).toBe(0);
     });
 
-    it('preserves entities with incoming cross-file EXTENDS edges', async () => {
+    it('removes owned entities and incoming cross-file EXTENDS edges with the deleted file', async () => {
       // Setup: File A has ClassChild, File B has ClassBase, ClassChild EXTENDS ClassBase
       await ops.upsertFile(makeFile({ path: '/src/perf4-child.ts', name: 'perf4-child.ts' }));
       await ops.upsertClass(makeClass({ name: 'ClassChild', filePath: '/src/perf4-child.ts', startLine: 1 }));
@@ -694,20 +693,18 @@ describe('Graph CRUD Operations (FalkorDB)', () => {
       // Create cross-file EXTENDS edge: ClassChild → ClassBase
       await ops.createExtendsEdge('ClassChild', '/src/perf4-child.ts', 'ClassBase', '/src/perf4-base.ts');
 
-      // Remove the BASE file: ClassBase should be preserved due to incoming EXTENDS
+      // Removing the base file also removes its owned ClassBase declaration.
       await ops.removeFileAndCleanup('/src/perf4-base.ts');
 
-      // ClassBase should still exist
       const afterCls = await client.roQuery<{ count: number }>(
         `MATCH (c:Class {name: 'ClassBase', filePath: '/src/perf4-base.ts'}) RETURN count(c) as count`
       );
-      expect(afterCls.data[0]?.count).toBe(1);
+      expect(afterCls.data[0]?.count).toBe(0);
 
-      // EXTENDS edge should still be intact
       const edgeAfter = await client.roQuery<{ count: number }>(
         `MATCH (a:Class {name: 'ClassChild'})-[:EXTENDS]->(b:Class {name: 'ClassBase'}) RETURN count(*) as count`
       );
-      expect(edgeAfter.data[0]?.count).toBe(1);
+      expect(edgeAfter.data[0]?.count).toBe(0);
     });
 
     it('removes entities from caller file without affecting callee file', async () => {
@@ -774,6 +771,9 @@ describe('Vector Search (FalkorDB)', () => {
   let ops: GraphOperations;
 
   const DIM = 768; // matches EMBEDDING_DIM (nomic-embed-text-v1.5)
+  const processPaymentId = `sym:v1:${'1'.repeat(64)}`;
+  const validateCardId = `sym:v1:${'2'.repeat(64)}`;
+  const renderChartId = `sym:v1:${'3'.repeat(64)}`;
 
   /** Create a simple vector with weight on specific dimensions */
   function makeVec(weights: Record<number, number>): number[] {
@@ -811,14 +811,17 @@ describe('Vector Search (FalkorDB)', () => {
     });
 
     await ops.upsertFunction({
+      id: processPaymentId, scopeKey: '', disambiguator: '',
       name: 'processPayment', filePath, startLine: 1, endLine: 10,
       isExported: true, isAsync: true, isArrow: false, params: [],
     });
     await ops.upsertFunction({
+      id: validateCardId, scopeKey: '', disambiguator: '',
       name: 'validateCard', filePath, startLine: 15, endLine: 25,
       isExported: true, isAsync: false, isArrow: false, params: [],
     });
     await ops.upsertFunction({
+      id: renderChartId, scopeKey: '', disambiguator: '',
       name: 'renderChart', filePath, startLine: 30, endLine: 40,
       isExported: true, isAsync: false, isArrow: false, params: [],
     });
@@ -827,19 +830,19 @@ describe('Vector Search (FalkorDB)', () => {
     // paymentVec and cardVec are close together; chartVec is far away
     await ops.updateEmbedding(
       'Function',
-      { name: 'processPayment', filePath, startLine: 1 },
+      { id: processPaymentId },
       makeVec({ 0: 1.0, 1: 0.0, 2: 0.1 }),
       'hash-payment',
     );
     await ops.updateEmbedding(
       'Function',
-      { name: 'validateCard', filePath, startLine: 15 },
+      { id: validateCardId },
       makeVec({ 0: 0.9, 1: 0.1, 2: 0.1 }),
       'hash-card',
     );
     await ops.updateEmbedding(
       'Function',
-      { name: 'renderChart', filePath, startLine: 30 },
+      { id: renderChartId },
       makeVec({ 0: 0.1, 1: 0.9, 2: 0.0 }),
       'hash-chart',
     );
diff --git a/packages/graph/src/client.ts b/packages/graph/src/client.ts
index 9ff93f91..af04849f 100644
--- a/packages/graph/src/client.ts
+++ b/packages/graph/src/client.ts
@@ -67,6 +67,24 @@ export interface QueryResult<T> {
   metadata: string[];
 }
 
+function sanitizeQueryParamValue(value: unknown): unknown {
+  if (value === undefined) return null;
+  if (value === null || typeof value !== 'object') return value;
+
+  if (Array.isArray(value)) {
+    return value.map(sanitizeQueryParamValue);
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [key, sanitizeQueryParamValue(item)]),
+  );
+}
+
+function sanitizeQueryParams(params: QueryParams | undefined): QueryParams | undefined {
+  if (params === undefined) return undefined;
+  return sanitizeQueryParamValue(params) as QueryParams;
+}
+
 /**
  * Graph client error types
  */
@@ -148,7 +166,7 @@ class GraphClientImpl implements GraphClient {
   @trace()
   async query<T>(cypher: string, options?: QueryOptions): Promise<QueryResult<T>> {
     try {
-      return await this.driver.query<T>(cypher, options?.params, options?.timeout);
+      return await this.driver.query<T>(cypher, sanitizeQueryParams(options?.params), options?.timeout);
     } catch (error) {
       throw new GraphClientError(
         `Query failed: ${toErrorMessage(error)}`,
@@ -160,7 +178,7 @@ class GraphClientImpl implements GraphClient {
   @trace()
   async roQuery<T>(cypher: string, options?: QueryOptions): Promise<QueryResult<T>> {
     try {
-      return await this.driver.roQuery<T>(cypher, options?.params, options?.timeout);
+      return await this.driver.roQuery<T>(cypher, sanitizeQueryParams(options?.params), options?.timeout);
     } catch (error) {
       throw new GraphClientError(
         `Read-only query failed: ${toErrorMessage(error)}`,
diff --git a/packages/graph/src/schema.ts b/packages/graph/src/schema.ts
index 86336cd2..6b7dcfa7 100644
--- a/packages/graph/src/schema.ts
+++ b/packages/graph/src/schema.ts
@@ -3,6 +3,8 @@
  * Cypher-compatible types and mappers for graph operations
  */
 
+import { createHash } from 'node:crypto';
+import { posix } from 'node:path';
 import type {
   FileEntity,
   FunctionEntity,
@@ -231,6 +233,40 @@ export interface LinkNodeProps {
 // Entity to Node Property Mappers
 // ============================================================================
 
+type SourceSymbolLabel = 'Function' | 'Class' | 'Interface' | 'Variable' | 'Type' | 'Component';
+
+interface LegacySymbolIdentityInput {
+  id?: string;
+  scopeKey?: string;
+  disambiguator?: string;
+  name: string;
+  filePath: string;
+}
+
+function resolveSymbolIdentity(
+  label: SourceSymbolLabel,
+  entity: LegacySymbolIdentityInput,
+): { id: string; scopeKey: string; disambiguator: string } {
+  const scopeKey = entity.scopeKey?.normalize('NFC') ?? '';
+  const disambiguator = entity.disambiguator?.normalize('NFC') ?? '';
+  if (entity.id) return { id: entity.id, scopeKey, disambiguator };
+
+  const normalizedSeparators = entity.filePath.replace(/\\/g, '/').normalize('NFC');
+  const normalizedPath = posix.normalize(normalizedSeparators);
+  const filePath = normalizedPath === '.' && normalizedSeparators !== '.' ? '' : normalizedPath;
+  const hash = createHash('sha256');
+
+  for (const field of [label, filePath, scopeKey, entity.name.normalize('NFC'), disambiguator]) {
+    const encoded = Buffer.from(field, 'utf8');
+    const length = Buffer.allocUnsafe(4);
+    length.writeUInt32BE(encoded.byteLength, 0);
+    hash.update(length);
+    hash.update(encoded);
+  }
+
+  return { id: `sym:v1:${hash.digest('hex')}`, scopeKey, disambiguator };
+}
+
 /**
  * Convert FileEntity to Cypher-compatible node properties
  */
@@ -253,10 +289,9 @@ export function fileToNodeProps(entity: FileEntity): FileNodeProps {
  * Convert FunctionEntity to Cypher-compatible node properties
  */
 export function functionToNodeProps(entity: FunctionEntity): FunctionNodeProps {
+  const identity = resolveSymbolIdentity('Function', entity);
   return {
-    id: entity.id,
-    scopeKey: entity.scopeKey ?? '',
-    disambiguator: entity.disambiguator ?? '',
+    ...identity,
     name: entity.name,
     filePath: entity.filePath,
     startLine: entity.startLine,
@@ -281,10 +316,9 @@ export function functionToNodeProps(entity: FunctionEntity): FunctionNodeProps {
  * Convert ClassEntity to Cypher-compatible node properties
  */
 export function classToNodeProps(entity: ClassEntity): ClassNodeProps {
+  const identity = resolveSymbolIdentity('Class', entity);
   return {
-    id: entity.id,
-    scopeKey: entity.scopeKey ?? '',
-    disambiguator: entity.disambiguator ?? '',
+    ...identity,
     name: entity.name,
     filePath: entity.filePath,
     startLine: entity.startLine,
@@ -304,10 +338,9 @@ export function classToNodeProps(entity: ClassEntity): ClassNodeProps {
  * Convert InterfaceEntity to Cypher-compatible node properties
  */
 export function interfaceToNodeProps(entity: InterfaceEntity): InterfaceNodeProps {
+  const identity = resolveSymbolIdentity('Interface', entity);
   return {
-    id: entity.id,
-    scopeKey: entity.scopeKey ?? '',
-    disambiguator: entity.disambiguator ?? '',
+    ...identity,
     name: entity.name,
     filePath: entity.filePath,
     startLine: entity.startLine,
@@ -325,10 +358,9 @@ export function interfaceToNodeProps(entity: InterfaceEntity): InterfaceNodeProp
  * Convert VariableEntity to Cypher-compatible node properties
  */
 export function variableToNodeProps(entity: VariableEntity): VariableNodeProps {
+  const identity = resolveSymbolIdentity('Variable', entity);
   return {
-    id: entity.id,
-    scopeKey: entity.scopeKey ?? '',
-    disambiguator: entity.disambiguator ?? '',
+    ...identity,
     name: entity.name,
     filePath: entity.filePath,
     line: entity.line,
@@ -345,10 +377,9 @@ export function variableToNodeProps(entity: VariableEntity): VariableNodeProps {
  * Convert TypeEntity to Cypher-compatible node properties
  */
 export function typeToNodeProps(entity: TypeEntity): TypeNodeProps {
+  const identity = resolveSymbolIdentity('Type', entity);
   return {
-    id: entity.id,
-    scopeKey: entity.scopeKey ?? '',
-    disambiguator: entity.disambiguator ?? '',
+    ...identity,
     name: entity.name,
     filePath: entity.filePath,
     startLine: entity.startLine,
@@ -366,10 +397,9 @@ export function typeToNodeProps(entity: TypeEntity): TypeNodeProps {
  * Convert ComponentEntity to Cypher-compatible node properties
  */
 export function componentToNodeProps(entity: ComponentEntity): ComponentNodeProps {
+  const identity = resolveSymbolIdentity('Component', entity);
   return {
-    id: entity.id,
-    scopeKey: entity.scopeKey ?? '',
-    disambiguator: entity.disambiguator ?? '',
+    ...identity,
     name: entity.name,
     filePath: entity.filePath,
     startLine: entity.startLine,

From 7cd8bf6f911236a7aae3c0e8496d10c9b497233b Mon Sep 17 00:00:00 2001
From: Randy Wilson <phoenixrr2113@gmail.com>
Date: Fri, 21 Aug 2026 19:47:34 -0400
Subject: [PATCH 3/4] Seed bridge-linker test fixtures with canonical ids

The strict embedding update was right; the fixtures were still passing
the legacy name-and-path shape while discarding the canonical ids their
own upserts had produced. Production never hits this path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../__tests__/bridge-linker-embedding.test.ts | 35 +++++++++++++++----
 .../src/__tests__/bridge-linker.test.ts       | 31 +++++++++++-----
 2 files changed, 51 insertions(+), 15 deletions(-)

diff --git a/packages/plugin-nlp/src/__tests__/bridge-linker-embedding.test.ts b/packages/plugin-nlp/src/__tests__/bridge-linker-embedding.test.ts
index 42472340..8a318902 100644
--- a/packages/plugin-nlp/src/__tests__/bridge-linker-embedding.test.ts
+++ b/packages/plugin-nlp/src/__tests__/bridge-linker-embedding.test.ts
@@ -36,8 +36,14 @@ vi.mock('../embeddings', async (importOriginal) => {
   };
 });
 
-import { createClient, createOperations, createKnowledgeOperations } from '@codegraph/graph';
+import {
+  createClient,
+  createOperations,
+  createKnowledgeOperations,
+  functionToNodeProps,
+} from '@codegraph/graph';
 import type { GraphClient, GraphOperations, KnowledgeOperations } from '@codegraph/graph';
+import type { FunctionEntity } from '@codegraph/types';
 import { linkByEmbedding } from '../bridge-linker';
 import { isEmbeddingAvailable, generateEmbedding } from '../embeddings';
 
@@ -69,6 +75,18 @@ function mixedVec(dim1: number, w1: number, dim2: number, w2: number): number[]
   return vec;
 }
 
+type LegacyFunctionFixture = Omit<FunctionEntity, 'id' | 'scopeKey' | 'disambiguator'>;
+
+function canonicalFunction(entity: LegacyFunctionFixture): FunctionEntity {
+  const identity = functionToNodeProps(entity as FunctionEntity);
+  return {
+    ...entity,
+    id: identity.id,
+    scopeKey: identity.scopeKey,
+    disambiguator: identity.disambiguator,
+  };
+}
+
 // ============================================================================
 // Test Setup
 // ============================================================================
@@ -110,23 +128,26 @@ describe('Bridge-Linker Embedding Similarity', () => {
     });
 
     // Payment cluster: dim 0
-    await ops.upsertFunction({
+    const processPayment = canonicalFunction({
       name: 'processPayment', filePath: '/src/payments.ts',
       startLine: 1, endLine: 20,
       isExported: true, isAsync: true, isArrow: false, params: [],
     });
-    await ops.upsertFunction({
+    const validatePayment = canonicalFunction({
       name: 'validatePayment', filePath: '/src/payments.ts',
       startLine: 22, endLine: 40,
       isExported: true, isAsync: false, isArrow: false, params: [],
     });
 
     // Chart cluster: dim 1
-    await ops.upsertFunction({
+    const renderChart = canonicalFunction({
       name: 'renderChart', filePath: '/src/payments.ts',
       startLine: 42, endLine: 60,
       isExported: true, isAsync: false, isArrow: false, params: [],
     });
+    await ops.upsertFunction(processPayment);
+    await ops.upsertFunction(validatePayment);
+    await ops.upsertFunction(renderChart);
 
     // Set embeddings on code nodes
     const PAY_VEC_1 = makeVec(0, 0.95);
@@ -135,17 +156,17 @@ describe('Bridge-Linker Embedding Similarity', () => {
 
     await ops.updateEmbedding(
       'Function',
-      { name: 'processPayment', filePath: '/src/payments.ts', startLine: 1 },
+      { id: processPayment.id },
       PAY_VEC_1, 'h1',
     );
     await ops.updateEmbedding(
       'Function',
-      { name: 'validatePayment', filePath: '/src/payments.ts', startLine: 22 },
+      { id: validatePayment.id },
       PAY_VEC_2, 'h2',
     );
     await ops.updateEmbedding(
       'Function',
-      { name: 'renderChart', filePath: '/src/payments.ts', startLine: 42 },
+      { id: renderChart.id },
       CHART_VEC, 'h3',
     );
   }, 30_000);
diff --git a/packages/plugin-nlp/src/__tests__/bridge-linker.test.ts b/packages/plugin-nlp/src/__tests__/bridge-linker.test.ts
index 43d67721..c5ec1a8d 100644
--- a/packages/plugin-nlp/src/__tests__/bridge-linker.test.ts
+++ b/packages/plugin-nlp/src/__tests__/bridge-linker.test.ts
@@ -12,7 +12,12 @@ import { describe, it, expect, beforeAll, afterAll, beforeEach, vi } from 'vites
 // These tests use local embeddings
 vi.stubEnv('CODEGRAPH_EMBEDDING_PROVIDER', 'local');
 
-import { createClient, createOperations, createKnowledgeOperations } from '@codegraph/graph';
+import {
+  createClient,
+  createOperations,
+  createKnowledgeOperations,
+  functionToNodeProps,
+} from '@codegraph/graph';
 import type { GraphClient, GraphOperations, KnowledgeOperations } from '@codegraph/graph';
 import type { FileEntity, FunctionEntity, ClassEntity, InterfaceEntity } from '@codegraph/types';
 import { linkEntitiesToCode, linkByEmbedding, type BridgeLinkerInput } from '../bridge-linker';
@@ -36,7 +41,7 @@ function makeFile(overrides?: Partial<FileEntity>): FileEntity {
 }
 
 function makeFunction(overrides?: Partial<FunctionEntity>): FunctionEntity {
-  return {
+  const entity = {
     name: 'processPayment',
     filePath: '/src/payment.ts',
     startLine: 10,
@@ -47,6 +52,13 @@ function makeFunction(overrides?: Partial<FunctionEntity>): FunctionEntity {
     params: ['amount', 'currency'],
     ...overrides,
   };
+  const identity = functionToNodeProps(entity as FunctionEntity);
+  return {
+    ...entity,
+    id: identity.id,
+    scopeKey: identity.scopeKey,
+    disambiguator: identity.disambiguator,
+  };
 }
 
 function makeClass(overrides?: Partial<ClassEntity>): ClassEntity {
@@ -374,27 +386,30 @@ describe('Bridge Linker (embedding similarity)', () => {
       loc: 100, lastModified: '2025-01-01', hash: 'abc',
     });
 
-    await ops.upsertFunction({
+    const retryWithBackoff = makeFunction({
       name: 'retryWithBackoff', filePath: '/src/payments.ts',
       startLine: 1, endLine: 10, isExported: true, isAsync: true, isArrow: false, params: [],
     });
-    await ops.upsertFunction({
+    const processPayment = makeFunction({
       name: 'processPayment', filePath: '/src/payments.ts',
       startLine: 20, endLine: 30, isExported: true, isAsync: true, isArrow: false, params: [],
     });
-    await ops.upsertFunction({
+    const renderChart = makeFunction({
       name: 'renderChart', filePath: '/src/payments.ts',
       startLine: 40, endLine: 50, isExported: true, isAsync: false, isArrow: false, params: [],
     });
+    await ops.upsertFunction(retryWithBackoff);
+    await ops.upsertFunction(processPayment);
+    await ops.upsertFunction(renderChart);
 
     // Set embeddings on code nodes: "payment" cluster near dim 0, "chart" near dim 1
     const RETRY_VEC = makeVec({ 0: 0.85, 1: 0.05, 2: 0.1 });
     const PAYMENT_VEC = makeVec({ 0: 0.95, 1: 0.0, 2: 0.05 });
     const CHART_VEC = makeVec({ 0: 0.05, 1: 0.95, 2: 0.0 });
 
-    await ops.updateEmbedding('Function', { name: 'retryWithBackoff', filePath: '/src/payments.ts', startLine: 1 }, RETRY_VEC, 'h1');
-    await ops.updateEmbedding('Function', { name: 'processPayment', filePath: '/src/payments.ts', startLine: 20 }, PAYMENT_VEC, 'h2');
-    await ops.updateEmbedding('Function', { name: 'renderChart', filePath: '/src/payments.ts', startLine: 40 }, CHART_VEC, 'h3');
+    await ops.updateEmbedding('Function', { id: retryWithBackoff.id }, RETRY_VEC, 'h1');
+    await ops.updateEmbedding('Function', { id: processPayment.id }, PAYMENT_VEC, 'h2');
+    await ops.updateEmbedding('Function', { id: renderChart.id }, CHART_VEC, 'h3');
 
     // Seed knowledge entities (no ABOUT edges yet)
     await kg.createEntity({ text: 'payment retry bug', type: 'Bug', confidence: 0.9 });

From fa1f88d16f7d387935854b38e4e5ed5bcd02e96b Mon Sep 17 00:00:00 2001
From: Randy Wilson <phoenixrr2113@gmail.com>
Date: Fri, 21 Aug 2026 20:00:59 -0400
Subject: [PATCH 4/4] Project the canonical id through vector search instead of
 silently dropping every row

The vector Cypher never returned node.id, and the strict candidate
mapper skipped rows without one, so remote search returned zero hits on
a fully indexed graph. The projection now includes the id, the row
mapping throws a diagnostic error on a missing or malformed id instead
of silently filtering, and a Linux temp-directory prefix in one test is
made portable.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 ...r-overload-call-target.integration.test.ts |  2 +-
 .../src/__tests__/linked-knowledge.test.ts    |  2 +
 packages/core/src/enrichedSearchV2.ts         |  9 +--
 .../vector-search-row-mapping.test.ts         | 71 +++++++++++++++++++
 packages/graph/src/operations.ts              | 38 ++++++----
 5 files changed, 100 insertions(+), 22 deletions(-)
 create mode 100644 packages/graph/src/__tests__/vector-search-row-mapping.test.ts

diff --git a/packages/core/src/__tests__/indexer-overload-call-target.integration.test.ts b/packages/core/src/__tests__/indexer-overload-call-target.integration.test.ts
index a7906af4..96d84783 100644
--- a/packages/core/src/__tests__/indexer-overload-call-target.integration.test.ts
+++ b/packages/core/src/__tests__/indexer-overload-call-target.integration.test.ts
@@ -20,7 +20,7 @@ describeIfAvailable('indexProject overload call target resolution', () => {
     previousEmbeddingProvider = process.env['CODEGRAPH_EMBEDDING_PROVIDER'];
     process.env['CODEGRAPH_EMBEDDING_PROVIDER'] = 'none';
 
-    dataDir = await mkdtemp('/private/tmp/cgot-');
+    dataDir = await mkdtemp(join(tmpdir(), 'cgot-'));
     client = await createClient({
       driver: 'falkordblite',
       databasePath: dataDir,
diff --git a/packages/core/src/__tests__/linked-knowledge.test.ts b/packages/core/src/__tests__/linked-knowledge.test.ts
index 20ca3204..19bb7880 100644
--- a/packages/core/src/__tests__/linked-knowledge.test.ts
+++ b/packages/core/src/__tests__/linked-knowledge.test.ts
@@ -17,6 +17,7 @@ import type { GraphClient } from '@codegraph/graph';
 // ---------------------------------------------------------------------------
 
 const MOCK_VECTOR_HIT = {
+  id: 'sym:v1:parse-token',
   name: 'parseToken',
   nodeType: 'Function',
   filePath: 'src/auth.ts',
@@ -34,6 +35,7 @@ vi.mock('@codegraph/graph', () => ({
   createOperations: vi.fn().mockReturnValue({
     searchByVector: vi.fn().mockResolvedValue([
       {
+        id: 'sym:v1:parse-token',
         name: 'parseToken',
         nodeType: 'Function',
         filePath: 'src/auth.ts',
diff --git a/packages/core/src/enrichedSearchV2.ts b/packages/core/src/enrichedSearchV2.ts
index b4441b12..a2246c53 100644
--- a/packages/core/src/enrichedSearchV2.ts
+++ b/packages/core/src/enrichedSearchV2.ts
@@ -492,17 +492,14 @@ async function retrieveCandidates(
     for (const r of results) {
       if (!matchesScope(r.filePath, scope, scopePaths)) continue;
 
-      const persistedId = typeof r.properties?.['id'] === 'string'
-        ? r.properties['id']
-        : r.nodeType === 'File' ? `File:${r.filePath}` : undefined;
-      if (!persistedId || seen.has(persistedId)) continue;
-      seen.add(persistedId);
+      if (seen.has(r.id)) continue;
+      seen.add(r.id);
 
       const vScore = distanceToScore(r.distance);
       // r.properties contains the full row from searchByVector (all node fields)
       const props = r.properties ?? {};
       candidates.push({
-        id: persistedId,
+        id: r.id,
         name: r.name,
         nodeType: r.nodeType,
         filePath: r.filePath,
diff --git a/packages/graph/src/__tests__/vector-search-row-mapping.test.ts b/packages/graph/src/__tests__/vector-search-row-mapping.test.ts
new file mode 100644
index 00000000..2468a415
--- /dev/null
+++ b/packages/graph/src/__tests__/vector-search-row-mapping.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { GraphClient, QueryOptions, QueryResult } from '../client';
+import { falkorDialect } from '../drivers/falkordb';
+import { createOperations } from '../operations';
+
+function clientReturning(rows: Array<Record<string, unknown>>): GraphClient {
+  return {
+    graph: null,
+    graphName: 'vector-row-mapping',
+    dialect: falkorDialect,
+    query: vi.fn(),
+    roQuery: vi.fn(async <T>(_cypher: string, _options?: QueryOptions): Promise<QueryResult<T>> => ({
+      data: rows as T[],
+      metadata: [],
+    })),
+    ensureIndexes: vi.fn(),
+    close: vi.fn(),
+  };
+}
+
+describe('searchByVector row identity mapping', () => {
+  it('projects and maps the persisted id returned by FalkorDB', async () => {
+    const id = `sym:v1:${'a'.repeat(64)}`;
+    const client = clientReturning([{
+      id,
+      name: 'buildWidget',
+      filePath: '/project/widget.ts',
+      startLine: 2,
+      score: 0.01,
+    }]);
+
+    const results = await createOperations(client).searchByVector('Function', [0.1, 0.2], 5);
+
+    expect(client.roQuery).toHaveBeenCalledWith(
+      expect.stringContaining('node.id AS id'),
+      expect.objectContaining({ params: { queryVec: [0.1, 0.2], k: 5 } }),
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0]).toMatchObject({
+      id,
+      name: 'buildWidget',
+      nodeType: 'Function',
+      properties: expect.objectContaining({ id }),
+    });
+  });
+
+  it('rejects a row whose persisted id is missing instead of silently returning no results', async () => {
+    const client = clientReturning([{
+      name: 'buildWidget',
+      filePath: '/project/widget.ts',
+      score: 0.01,
+    }]);
+
+    await expect(
+      createOperations(client).searchByVector('Function', [0.1, 0.2], 5),
+    ).rejects.toThrow('Vector search returned Function row without a valid persisted id');
+  });
+
+  it('rejects an unexpected persisted id shape instead of dropping a real row', async () => {
+    const client = clientReturning([{
+      id: { value: `sym:v1:${'b'.repeat(64)}` },
+      name: 'buildWidget',
+      filePath: '/project/widget.ts',
+      score: 0.01,
+    }]);
+
+    await expect(
+      createOperations(client).searchByVector('Function', [0.1, 0.2], 5),
+    ).rejects.toThrow('Vector search returned Function row without a valid persisted id');
+  });
+});
diff --git a/packages/graph/src/operations.ts b/packages/graph/src/operations.ts
index 4caf06c9..5df81241 100644
--- a/packages/graph/src/operations.ts
+++ b/packages/graph/src/operations.ts
@@ -1405,6 +1405,7 @@ export interface GraphOperations {
 
 /** Result from vector similarity search */
 export interface VectorSearchResult {
+  id: string;
   nodeType: string;
   name: string;
   filePath: string;
@@ -2722,7 +2723,7 @@ class GraphOperationsImpl implements GraphOperations {
     const cypher = `
       CALL db.idx.vector.queryNodes('${nodeType}', 'embedding', $k, vecf32($queryVec))
       YIELD node, score
-      RETURN node.name AS name, ${filePathExpr} AS filePath${startLineReturn}, score,
+      RETURN node.id AS id, node.name AS name, ${filePathExpr} AS filePath${startLineReturn}, score,
              node.endLine AS endLine,
              node.complexity AS complexity,
              node.cognitiveComplexity AS cognitiveComplexity,
@@ -2737,23 +2738,11 @@ class GraphOperationsImpl implements GraphOperations {
              node.bodySnippet AS bodySnippet
     `;
 
+    let result: { data: Array<Record<string, unknown>> };
     try {
-      const result = await this.client.roQuery<Record<string, unknown>>(cypher, {
+      result = await this.client.roQuery<Record<string, unknown>>(cypher, {
         params: { queryVec: embedding, k: limit },
       });
-
-      return result.data.map((row) => {
-        const entry: VectorSearchResult = {
-          nodeType,
-          name: row['name'] as string,
-          filePath: row['filePath'] as string,
-          distance: row['score'] as number,
-          properties: row,
-        };
-        const sl = row['startLine'];
-        if (typeof sl === 'number') entry.startLine = sl;
-        return entry;
-      });
     } catch (error) {
       // A missing vector index is an expected, benign state on a fresh graph.
       // Anything else is a real failure and must not be reported as "no results",
@@ -2764,6 +2753,25 @@ class GraphOperationsImpl implements GraphOperations {
       }
       return [];
     }
+
+    return result.data.map((row) => {
+      const id = row['id'];
+      if (typeof id !== 'string' || id.length === 0) {
+        throw new Error(`Vector search returned ${nodeType} row without a valid persisted id`);
+      }
+
+      const entry: VectorSearchResult = {
+        id,
+        nodeType,
+        name: row['name'] as string,
+        filePath: row['filePath'] as string,
+        distance: row['score'] as number,
+        properties: row,
+      };
+      const sl = row['startLine'];
+      if (typeof sl === 'number') entry.startLine = sl;
+      return entry;
+    });
   }
 
   private projectFromRow(row: Record<string, unknown>): ProjectEntity {