# Fabric authority and retirement consumer contract v1

## Decision

`railiance-fabric` is the specialized authority for Fabric topology,
containment, ownership, accepted graph snapshots, and graph exports. Fin-hub is
the accountable financial-domain consumer: it may join Fabric identifiers to
booked-cost and reporting facts, but it does not copy or mutate authority
tables. State Hub's `fabric_graph_*` tables are a rebuildable legacy read model.

The authoritative machine contract is `FabricGraphExport` from:

- `GET /exports/financial` on the Railiance Fabric registry; or
- `railiance-fabric export --format financial` for an operator-reviewed file.

The preferred contract is `railiance.fabric/v1alpha2` with
`schema_version: financial-fabric-v1`. The v1alpha1 form remains a compatibility
input during cutover.

Every cutover export must carry:

- `source.producer: railiance-fabric`;
- an immutable `source.commit` (a Git revision or `snapshot-set:sha256:*`);
- `source.path`;
- `generated_at`; and
- complete `nodes` and `edges` arrays.

## State Hub route disposition

| Legacy State Hub surface | Successor |
| --- | --- |
| `POST /fabric/graph-exports`, `POST /fabric/graph-exports/pull` | Replace with Railiance Fabric repository/discovery snapshot ingest and explicit acceptance. State Hub must not remain an authoring/import authority. |
| `GET /fabric/graph-exports`, `GET /fabric/graph-exports/latest` | Replace with Fabric snapshot history plus `GET /exports/state-hub`. |
| `GET /fabric/graph/nodes` | Replace with Fabric `GET /graph/nodes` or the authoritative export. |
| `GET /fabric/graph/edges` | Replace with Fabric `GET /graph/edges` or the authoritative export. |
| `GET /fabric/graph/summary` | Replace with Fabric `GET /graph/summary`. |
| State Hub Fabric dashboard assumptions | Replace with `GET /ui/graph-explorer`; no independent State Hub Fabric page or external caller was found in the 2026-08-31 scan. |
| `fabric_graph_imports`, `fabric_graph_nodes`, `fabric_graph_edges` | Archive with the final State Hub dump, then retire. Do not reproduce these tables in fin-hub or hub-core. |

## Cutover gate

Capture the authority export and the State Hub summary from the same candidate
refresh, then run:

```bash
finhub fabric-cutover-check \
  --authority http://127.0.0.1:8765/exports/financial \
  --projection http://127.0.0.1:8000/fabric/graph/summary
```

The command exits `0` only when API/schema identity, canonical content hash,
node/edge/actor/fabric/unresolved counts, source revision/path, and export time
are equal. Exit `2` means no cutover. Evidence output is non-secret JSON and can
be attached to the State Hub retirement record.

Rollback keeps the State Hub read routes available during the dual-read window.
If the direct Fabric surface fails or the check drifts, restore the caller route
to State Hub, do not accept a new authority snapshot, and re-run the comparison.
The source graph remains in Railiance Fabric in either direction.

## Hub-core projection decision

Deferred. There is no current external caller that needs a cross-domain Fabric
orientation projection, and Fabric already provides a graph API and explorer.
Adding hub-core tables would create a third copy with no demonstrated consumer.
If a future hub view needs Fabric context, it must use a versioned read port over
the authority export, cache only rebuildable bounded results, carry the source
revision/content hash, and never expose mutation operations.