state-hub/docs/fabric-graph-read-model.md

Fabric Graph Read Model

State Hub stores Railiance Fabric graph exports as a read model. Fabric remains the source of truth; the State Hub tables are cache/index/query state for dashboard and operator use.

Refresh After Fabric Reset/Reingest

Start or confirm the Railiance Fabric registry is serving its export:

curl -s http://127.0.0.1:8765/exports/state-hub

Pull the current export into State Hub:

curl -s -X POST http://127.0.0.1:8000/fabric/graph-exports/pull \
  -H "Content-Type: application/json" \
  -d '{
    "source_repo_slug": "railiance-fabric",
    "source_url": "http://127.0.0.1:8765/exports/state-hub",
    "requested_by": "operator"
  }'

For a saved export file, post the FabricGraphExport JSON directly:

curl -s -X POST "http://127.0.0.1:8000/fabric/graph-exports?source_repo_slug=railiance-fabric" \
  -H "Content-Type: application/json" \
  --data-binary @fabric-state-hub-export.json

Query Checks

Latest import and counts:

curl -s http://127.0.0.1:8000/fabric/graph-exports/latest
curl -s http://127.0.0.1:8000/fabric/graph/summary

Representative relationship queries:

curl -s "http://127.0.0.1:8000/fabric/graph/edges?canonical_relationship=exposes"
curl -s "http://127.0.0.1:8000/fabric/graph/edges?canonical_relationship=depends_on"
curl -s "http://127.0.0.1:8000/fabric/graph/edges?canonical_relationship=implements"

Node filters:

curl -s "http://127.0.0.1:8000/fabric/graph/nodes?repo=state-hub"
curl -s "http://127.0.0.1:8000/fabric/graph/nodes?domain=custodian"
curl -s "http://127.0.0.1:8000/fabric/graph/nodes?canonical_category=service"

Guarantees

• malformed exports create a failed import/progress record but do not write graph node or edge rows
• repeated imports of the same graph content are idempotent
• latest selection is per source_repo_slug
• read endpoints do not mutate workstreams, tasks, messages, decisions, or progress rows