LSP/Index Engineer

Here's the graphd setup for TypeScript + Python:

Step 1: Initialize LSP clients

• TypeScript: spawn typescript-language-server --stdio, send initialize with workspace root
• Python: spawn pylsp --check-parent-process, send initialize with Python path
• Wait for initialized notification from both before proceeding

Step 2: Build initial graph

• Request textDocument/documentSymbol for all files in workspace
• For each symbol, request textDocument/definition and textDocument/references
• Build graph: File nodes → (contains) → Symbol nodes → (references) → Symbol nodes
• Write to nav.index.jsonl with format: one JSON object per line, {id, type, name, location, edges}

Step 3: Incremental updates

• File watcher on workspace → on change, send textDocument/didChange to appropriate LSP
• Re-request symbols for changed file → diff against current graph → apply delta
• Stream graph diff via WebSocket: {type: 'node_updated', id, changes} or {type: 'edge_added', from, to, kind}

Performance: With ~5K TypeScript symbols and ~2K Python symbols, expect initial build in <10 seconds, incremental updates in <200ms.

Graph recovery procedure:

1. Detect inconsistency: Run integrity check:

   • Verify every edge references valid node IDs on both ends
   • Verify every symbol node has a parent file node
   • Verify no duplicate definition nodes for the same symbol
   • Report: X orphaned edges, Y missing file nodes, Z duplicate definitions

2. Repair strategy:

   • Delete orphaned edges (edges pointing to non-existent nodes)
   • For missing file nodes: re-scan the file from disk, rebuild its symbol subtree
   • For duplicate definitions: keep the one from the latest file version, remove others

3. Rebuild if >10% corrupt: If corruption exceeds 10% of nodes, a full rebuild is faster and safer than incremental repair. Drop the graph, kill all LSP processes, restart from Step 2 of initial setup.

4. Prevention: Write a transaction log alongside the graph. Each mutation logs: {op: 'add_node', id, data, timestamp}. On crash recovery, replay the transaction log from last known good checkpoint.