docs(adr-702): address spike review findings

ADR:
- Engine responsibilities now list arrow-glyph rendering and edge-type
  coloring (propagating spike findings #1 and #2 from the findings section
  into the engine contract).
- EngineNode interface adds label as first-class field; UnifiedGraphEngineProps
  adds edgePalette and showArrows props (finding #3 and full wiring of #1/#2).
- Phase 1 gets an explicit pre-merge gate requiring a 1k-concept scale
  spike (finding #5).
- LOC-reduction estimate tied to phase sequencing (~2k off phase 1, rest
  across phases 2–3) rather than a bare range.
- Spike results section cites the committed spike-server.js path instead
  of the gitignored reproduction copy.

Spike:
- export-kg-data.sh: note the AGE agtype→jsonb cast assumption against the
  pinned image; switch SQL cycle to Python context manager for the JSONL
  read; clarify that node degree is undirected by design.

Author: aaronsb

docs/architecture/user-interfaces/ADR-702-unified-graph-rendering-engine.md

@@ -157,7 +157,10 @@ The engine owns:
 - Edge index array (`Uint32Array` of length `2M`)
 - Force simulation (CPU or GPU, same parameter object)
 - Instanced node rendering (polygon or billboarded sprite)
-- Edge rendering (straight or bezier, via line shader)
+- Edge rendering (straight or bezier, via line shader) with optional
+  edge-type coloring (see Plugin surface)
+- Arrow-glyph rendering on directed edges, as an instanced-triangle mesh
+  anchored to the target end of each edge (togglable per plugin)
 - Camera (orthographic or perspective)
 - Pointer picking via `instanceId` (uniform across node modes)
 - Hidden mask (per-instance visibility, respected by both sim and renderer)
@@ -211,9 +214,24 @@ Plugins implement the existing `ExplorerPlugin` interface from ADR-034 and
 embed the engine component as their scene. The engine exposes:
 
 ```ts
+interface EngineNode {
+  id: string;                // stable key (e.g. kg concept_id)
+  label: string;              // human-readable display text
+  category: string;           // opaque string; resolved via palette
+  degree: number;             // used for size scaling
+  pinned?: boolean;
+}
+
+interface EngineEdge {
+  from: string;
+  to: string;
+  type: string;               // relationship type; resolved via edgePalette
+  weight?: number;
+}
+
 interface UnifiedGraphEngineProps {
-  nodes: EngineNode[];            // { id, category, degree, pinned? }
-  edges: EngineEdge[];            // { from, to, type, weight? }
+  nodes: EngineNode[];
+  edges: EngineEdge[];
   projection: '2D' | '3D';
   nodeMode: 'sprite' | 'poly';
   physicsBackend?: 'auto' | 'cpu' | 'gpu';
@@ -223,7 +241,12 @@ interface UnifiedGraphEngineProps {
   highlightedEdges?: Set<string>;
   selectedId?: string | null;
   hoveredId?: string | null;
-  palette: (category: string) => string;
+  palette: (category: string) => string;         // node category → hex
+  edgePalette?: (edgeType: string) => string;    // edge type → hex (optional;
+                                                 //   falls back to endpoint
+                                                 //   gradient if absent)
+  showArrows?: boolean;                          // render target-end arrow
+                                                 //   glyphs; default true
   onSelect?: (id: string | null) => void;
   onHover?: (id: string | null) => void;
   onHide?: (id: string) => void;
@@ -242,9 +265,11 @@ through the engine.
 ### Positive
 
 - **One engine, one physics, one rendering path.** Maintenance surface
-  shrinks substantially — estimated ~2000-3000 LOC reduction across the
-  three current surfaces once migration completes, plus removal of
-  `react-force-graph-3d` as a dependency.
+  shrinks substantially — the three current surfaces total ~4,400 lines
+  (`ForceGraph2D` 1840, `ForceGraph3D` 2052, `EmbeddingScatter3D` 529).
+  Phase 1 alone takes ~2000 lines off the 3D surface (V2 replaces V1 and
+  `react-force-graph-3d` is removed); phases 2 and 3 reduce the remaining
+  two stacks. Expected total reduction ~2,000–3,000 lines by phase 3.
 - **10k-node real-time interaction** becomes viable for the first time.
   Current 3D hits visible frame drops at a few hundred nodes.
 - **2D and 3D share a camera and a sim**, so switching projection mode on
@@ -325,6 +350,11 @@ V1 stays registered. Users pick via the explorer dropdown. Once V2 reaches
 full parity and soaks, V1 is removed and `react-force-graph-3d` dep is
 dropped.
 
+**Phase-1 merge gate:** before the phase-1 PR merges, a follow-up spike at
+kg-scale (1,000+ concepts) must validate the performance target on
+kg-shaped data at volume (per spike finding #5). The current spike (52
+concepts) validated shape compatibility but not scaling.
+
 ### Phase 2 — Add 2D projection
 
 Extend the engine with `projection: '2D'`:
@@ -447,10 +477,12 @@ The spike lives in `spike/unified-3d/` on this branch. It consists of:
 - An export script (`export-kg-data.sh`) that pulls concepts and relationships
   from a live kg postgres and writes them to `spike/unified-3d/data/kg-graph.json`
   in the shape the atlassian-graph UI expects (`{nodes, edges, meta}`)
-- A drop-in spike server (`spike/unified-3d/reference/spike-server.js`) that
-  replaces atlassian-graph's GraphQL-schema-backed `/api/graph`, `/api/type/:name`,
-  `/api/stats`, `/api/categories` endpoints with static reads from the kg export,
-  leaving the rest of the reference implementation unchanged.
+- A drop-in spike server (`spike/unified-3d/spike-server.js`; copied into
+  `spike/unified-3d/reference/` at reproduction time so it resolves
+  `express` from `reference/node_modules`) that replaces atlassian-graph's
+  GraphQL-schema-backed `/api/graph`, `/api/type/:name`, `/api/stats`,
+  `/api/categories` endpoints with static reads from the kg export, leaving
+  the rest of the reference implementation unchanged.
 
 The reference UI's vite dev server and the spike server both run cleanly and
 serve kg data through the atlassian-graph pipeline end-to-end. At the time of

spike/unified-3d/export-kg-data.sh

@@ -15,6 +15,14 @@ set -euo pipefail
 OUT_DIR="$(dirname "$0")/data"
 mkdir -p "$OUT_DIR"
 
+# AGE note: we cast agtype → text → jsonb. This works on the AGE image pinned
+# in this repo (see CLAUDE.md). Across AGE versions this cast can emit numeric
+# type annotations or unquoted keys that break jsonb parsing; if this script
+# starts failing after an AGE upgrade, switch to the kg REST API as the data
+# source instead of SQL.
+# Degree uses an undirected match (c)-[r]-() — each relationship is counted
+# twice (once from each endpoint) when summed across nodes, which matches how
+# the reference renderer scales node size.
 docker exec -i knowledge-graph-postgres psql -U admin -d knowledge_graph -qtA <<'SQL' > "$OUT_DIR/kg-raw.jsonl"
 LOAD 'age';
 SET search_path = ag_catalog, "$user", public;
@@ -70,7 +78,9 @@ def source_bucket(cid, _seen={}):
         _seen[key] = ATLASSIAN_CATEGORIES[idx]
     return _seen[key]
 
-for line in open(src):
+with open(src) as f:
+    raw_lines = f.readlines()
+for line in raw_lines:
     line = line.strip()
     if not line:
         continue