feat: complete fabric authority cutover contract

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

docs/evidence/FIN-WP-0003-precutover-2026-08-31.md

@@ -0,0 +1,28 @@
+# FIN-WP-0003 pre-cutover evidence — 2026-08-31
+
+The new gate was exercised against the current local Fabric registry and the
+live State Hub projection:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m fin_hub.cli fabric-cutover-check \
+  --authority http://127.0.0.1:8765/exports/financial \
+  --projection http://127.0.0.1:8000/fabric/graph/summary
+```
+
+Result: expected exit `2`, `ready: false`.
+
+| Measure | Fabric authority | State Hub read model |
+| --- | ---: | ---: |
+| API version | `railiance.fabric/v1alpha2` | `railiance.fabric/v1alpha2` |
+| Nodes | 131 | 49 |
+| Edges | 117 | 58 |
+| Actors | 2 | 2 |
+| Fabrics | 1 | 1 |
+| Unresolved | 0 | 0 |
+
+The content hashes differ. The authority now supplies immutable snapshot-set
+revision and path provenance; the old State Hub import has null source revision,
+path, and export time. This is a correct no-go result: the owner contract and
+checker are ready, but STATE-WP-0079 must refresh from one selected authority
+export and obtain a green comparison before switching callers or removing the
+legacy tables. No production route was changed by FIN-WP-0003.

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.