---
id: STATE-WP-0050
type: workplan
title: "Railiance Fabric Graph Read Model Ingest"
domain: custodian
repo: state-hub
status: ready
owner: codex
topic_slug: custodian
created: "2026-05-23"
updated: "2026-05-23"
state_hub_workstream_id: "22f15fd4-2bec-4fea-adbc-2b02b7f4c1f3"
---

# STATE-WP-0050 - Railiance Fabric Graph Read Model Ingest

## Goal

Add State Hub support for ingesting Railiance Fabric graph exports as a read
model, so Fabric can remain the graph source of truth while State Hub can query,
summarize, and display the latest cross-repository graph state.

## Background

RAIL-FAB-WP-0016 completed a canon-aligned reset and reingest in
`railiance-fabric`. The renewed Fabric registry now exposes a schema-valid
`FabricGraphExport` at `/exports/state-hub`.

The current blocker is on the State Hub side: no graph read-model ingest
endpoint or pull job exists in `state-hub`, so the renewed Fabric export cannot
yet be stored as a State Hub read model. The integration must preserve Fabric as
the source of truth and treat State Hub data as cache/index/query state.

Current verified Fabric export baseline from 2026-05-23:

- Source repo: `railiance-fabric`
- Export endpoint: `http://127.0.0.1:8765/exports/state-hub`
- Schema: `schemas/state-hub-export.schema.yaml` in `railiance-fabric`
- Export kind: `FabricGraphExport`
- Node count: 49
- Edge count: 58
- Representative canonical edge relationships: `exposes`, `depends_on`,
  `implements`

## T01 - Read-model storage and identity

```task
id: STATE-WP-0050-T01
status: todo
priority: high
state_hub_task_id: "d80b74bd-57ee-4e7a-81d7-406c02da52bc"
```

Design and implement persistent State Hub storage for imported Fabric graph
exports.

Requirements:

- Store import run metadata, source repo slug, source URL, export timestamp,
  content hash, node count, edge count, validation status, and error details.
- Store latest graph nodes and edges as a read model keyed by stable export
  identity, not as authoritative State Hub work items.
- Preserve canon metadata fields from Fabric exports, including canonical type,
  canon category/anchor, mapping fit, evidence state, and display-only flags.
- Make repeated ingest of the same export idempotent.
- Include migrations and repository/service helpers.

## T02 - Ingest API and pull job

```task
id: STATE-WP-0050-T02
status: todo
priority: high
state_hub_task_id: "3a94655d-703a-4aec-b724-46cafce14fdb"
```

Add an operator-usable ingestion path for Railiance Fabric graph exports.

Requirements:

- Provide either an HTTP endpoint, a CLI/scripted job, or both, that can ingest
  a `FabricGraphExport` JSON payload from `railiance-fabric`.
- Validate payload shape before persisting; reject malformed exports without
  partially mutating the read model.
- Support a pull mode from a configured Fabric registry URL, initially
  `http://127.0.0.1:8765/exports/state-hub`.
- Record import progress/errors in normal State Hub progress surfaces.
- Keep the integration explicit to `railiance-fabric` at first, while leaving
  source metadata general enough for future graph producers.

## T03 - Query surfaces and dashboard readiness

```task
id: STATE-WP-0050-T03
status: todo
priority: medium
state_hub_task_id: "6b4ed6fe-bc84-43c8-a4b0-55ee93918bac"
```

Expose read-only query surfaces for the imported graph.

Requirements:

- Return latest import status and counts by source repo.
- Query nodes and edges by source repo, domain, repo, canonical category,
  canonical relationship, evidence state, and mapping fit.
- Provide summary counts suitable for dashboard cards.
- Include representative examples for graph nodes and graph edges.
- Do not allow graph read-model queries to mutate State Hub workstreams,
  tasks, messages, decisions, or progress rows.

## T04 - Verification with RAIL-FAB-WP-0016 export

```task
id: STATE-WP-0050-T04
status: todo
priority: high
state_hub_task_id: "fdf5275a-f04d-43a3-b18a-12cfe0dcc2f7"
```

Verify the integration against the renewed Railiance Fabric registry export.

Requirements:

- Import the 2026-05-23 post-reset Fabric export successfully.
- Confirm stored counts match the verified baseline: 49 nodes and 58 edges.
- Confirm representative canonical relationships are queryable:
  `exposes`, `depends_on`, and `implements`.
- Add regression tests for validation failure, idempotent reingest, latest
  import selection, and read-only query behavior.
- Document the operator command for refreshing the State Hub graph read model
  after a Fabric reset/reingest.

## Acceptance

- State Hub has a documented endpoint or job for importing the
  `railiance-fabric` graph export.
- Import validates the payload and is idempotent.
- Imported graph data is stored only as a read model/cache.
- Query surfaces can answer latest counts and representative node/edge queries.
- RAIL-FAB-WP-0016's renewed export can be imported with matching counts.
- Tests cover import, validation, idempotency, and read-only query behavior.