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. State Hub accepts both the legacy railiance.fabric/v1alpha1 export and the financial Fabric railiance.fabric/v1alpha2 export with schema_version: financial-fabric-v1.

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

For the financial Fabric export, generate or save the vNext payload from railiance-fabric:

railiance-fabric validate .
railiance-fabric export --format financial > financial-fabric-v1.json
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 @financial-fabric-v1.json

The vNext import preserves the full graph_json payload and materializes dashboard fields for netkingdom, actors, fabrics/subfabrics, containment, ownership, utility edges, boundary crossing, evidence review state, and accounting attribution. Legacy imports remain readable; vNext-only fields are null or empty for old rows.

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"

Financial Fabric filters:

curl -s "http://127.0.0.1:8000/fabric/graph/nodes?fabric_id=fabric.railiance.primary"
curl -s "http://127.0.0.1:8000/fabric/graph/nodes?subfabric_id=subfabric.railiance.tenant.coulomb"
curl -s "http://127.0.0.1:8000/fabric/graph/nodes?owner_role=tenant"
curl -s "http://127.0.0.1:8000/fabric/graph/nodes?unresolved_ownership=true"
curl -s "http://127.0.0.1:8000/fabric/graph/edges?relationship_category=utility"
curl -s "http://127.0.0.1:8000/fabric/graph/edges?consumer_owner_actor_id=actor.coulomb.tenant"
curl -s "http://127.0.0.1:8000/fabric/graph/edges?crosses_subfabric_boundary=true"
curl -s "http://127.0.0.1:8000/fabric/graph/edges?missing_payment_schema=true"

Summary output includes financial dashboard counters such as nodes by fabric, subfabric, owner actor, owner role, ownership resolution, utility edges by provider/consumer owner, tenant utility edges missing payment schema, nodes without cost/profit attribution, and unresolved ownership/accounting counts.

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
• State Hub does not synthesize Fabric ownership; unresolved or ambiguous ownership/accounting markers must come from the Fabric export and remain visible as read-model gaps