generated from coulomb/repo-seed
Add Railiance Fabric graph ingest workplan
This commit is contained in:
@@ -0,0 +1,142 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user