# 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:

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

Pull the current export into State Hub:

```bash
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:

```bash
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`:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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