tegwick
debe67edf0
Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a053ff-1d6f-7fe2-ac1c-a6eb40a42a0c
68 lines
3.4 KiB
Markdown
68 lines
3.4 KiB
Markdown
# 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.
|