feat: complete fabric authority cutover contract

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a053ff-1d6f-7fe2-ac1c-a6eb40a42a0c

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

@@ -0,0 +1,68 @@
+# 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.