Keeps this page in sync as the body changes. Pause it any time for a quieter view.
Path /specs/universal-node-edge-layer
Last refresh never
Spec: Universal Node + Edge Data Layer
inventory_source local | spec_api /api/spec-registry/universal-node-edge-layer | registry_updated 2026-04-09T03:10:09.062201Z
potential_value 0.00 | actual_value 1.00 | value_gap 0.00
estimated_cost 0.00 | actual_cost 1.00 | cost_gap 1.00
estimated_roi 0.00 | actual_roi 1.00
Missing contributor linkage. Submit a change request with contributor attribution.
Open process view for this spec
task_ids -
branches -
source_files specs/api-request-logging-middleware.md, specs/canonical-route-registry-and-runtime-mapping.md, specs/coherence-algorithm-spec.md, specs/postgresql-migration.md, specs/release-gates.md, specs/runtime-telemetry-db-precedence.md, specs/unified-sqlite-store.md, specs/universal-node-edge-layer.md
evidence_refs -
Open implementation view for this spec
implementation_refs spec-registry:api-request-logging-middleware, spec-registry:canonical-route-registry-and-runtime-mapping, spec-registry:coherence-algorithm-spec, spec-registry:postgresql-migration, spec-registry:release-gates, spec-registry:runtime-telemetry-db-precedence, spec-registry:unified-sqlite-store, spec-registry:universal-node-edge-layer
lineage_ids -
public_endpoints -
summary Coherence Network currently stores entity relationships across heterogeneous tables (ideas, tasks, nodes, edges) with no uniform contract — causing 3130 failed-task events and 447,958 wasted minutes from broken contracts at seams between pipeline stages. This spec introduces a **Universal Node + Edge data layer**: a single source of truth for all graph entities and their relationships, with a uniform `payload` column and stable `node_id` / `edge_id` keys. Every pipeline stage reads and writes th
process_summary `graph_nodes` table: `id UUID PK`, `node_type VARCHAR(64) NOT NULL`, `external_id VARCHAR(256)`, `payload JSONB NOT NULL; `graph_edges` table: `id UUID PK`, `edge_type VARCHAR(64) NOT NULL`, `from_node_id UUID NOT NULL REFERENCES graph_nodes(; Unique index on `(node_type, external_id)` in `graph_nodes` to allow idempotent upserts; Index on `(edge_type, from_node_id)` and `(edge_type, to_node_id)` in `graph_edges` for traversal queries; FastAPI router `GET /api/graph/nodes/{node_id}` returns node + outgoing edges
pseudocode_summary -
implementation_summary api/app/services/graph_service.py (create_node(), get_node(), create_edge(), get_edges()); api/app/models/graph.py (Node, Edge); api/app/routers/graph.py (graph CRUD endpoints)