Phase B: Federation read-path evolution for graph traversal

[DarrenZal]

Context

Phase A (PR #9) ships bounded graph traversal via PostgreSQL recursive CTEs: neighborhood, shortest-path, and direction filters. All reads go through PG — no TerminusDB dependency.

Phase B extends the read path for federation and scale scenarios.

Potential scope

• TerminusDB read path: Option to route traversal queries through TDB WOQL when TDB is available (PG remains fallback). Requires graph_queries.py backend abstraction — the current structure is designed for this swap.
• Cross-node traversal: Follow relationships that span federation peers (requires KOI-net protocol extensions for graph queries).
• Materialized neighbor cache: For high-fanout hub entities, pre-compute neighborhood at write time to avoid CTE cost at read time.
• Graph analytics endpoints: Degree distribution, connected components, centrality metrics — useful for understanding graph topology.
• Pagination on neighborhood: Current approach returns all nodes up to cap. For large neighborhoods, cursor-based pagination may be needed.

Dependencies

• Phase 1 TerminusDB integration (smoke-validated, PR merged)
• Phase A graph traversal (PR Phase A: Graph traversal endpoints with direction filters #9)
• KOI-net federation stack (in progress on feature/personal-koi-federation)

Not in scope

• Schema migrations (Phase A confirmed all required indexes exist)
• Auth model changes (localhost + WireGuard mesh is sufficient for personal KOI)