fin-hub/docs/fabric-authority-consumer-contract-v1.md

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:

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.