From 5b62da81fa110472f4a140e418919e589927841a Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 23 May 2026 16:34:37 +0200 Subject: [PATCH] Add Railiance Fabric graph ingest workplan --- ...ailiance-fabric-graph-read-model-ingest.md | 142 ++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 workplans/STATE-WP-0050-railiance-fabric-graph-read-model-ingest.md diff --git a/workplans/STATE-WP-0050-railiance-fabric-graph-read-model-ingest.md b/workplans/STATE-WP-0050-railiance-fabric-graph-read-model-ingest.md new file mode 100644 index 0000000..f756dda --- /dev/null +++ b/workplans/STATE-WP-0050-railiance-fabric-graph-read-model-ingest.md @@ -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.