--- id: STATE-WP-0051 type: workplan title: "Financial Fabric Read Model Adaptation" domain: custodian repo: state-hub status: finished owner: codex topic_slug: custodian created: "2026-05-23" updated: "2026-05-24" state_hub_workstream_id: "6811cf57-2896-43a1-bbb5-162e0ccfa8c5" --- # STATE-WP-0051 - Financial Fabric Read Model Adaptation ## Goal Adapt State Hub's Railiance Fabric read model to the improved Fabric intent: financial fabric boundaries, king/lord/tenant ownership, fabric and subfabric containment, cross-boundary utility interfaces, and optional cost/profit center views. State Hub remains a read/cache/query surface. `railiance-fabric` remains the source of truth for Fabric graph discovery, normalization, versioning, and exports. ## Background `STATE-WP-0050` added the first State Hub ingest/read model for `railiance-fabric` graph exports. That implementation matches the post-`RAIL-FAB-WP-0016` canon-aligned export. The Fabric intent has now shifted away from repo-owned external declarations toward durable infrastructure-responsibility boundaries: - the king is responsible for the netkingdom and holds relevant recovery, secrets, and backup authority; - lords pay for fabrics; - tenants pay for restricted subfabric utility; - every graph node needs resolvable ownership; - cross-boundary utility edges are first-class value interfaces; - cost/profit centers are optional accounting attributions and view dimensions; - security-zone concepts such as realm and domain are intentionally not core Fabric concepts. This workplan adapts State Hub to import, query, and display the vNext Fabric contract developed by `RAIL-FAB-WP-0017` and populated by `RAIL-FAB-WP-0018`. ## T01 - Align With The VNext Fabric Export Contract ```task id: STATE-WP-0051-T01 status: done priority: high state_hub_task_id: "cf39a822-81ec-4834-9b95-b8013ccc1434" ``` Review and align with the vNext Fabric export contract from `RAIL-FAB-WP-0017`. Requirements: - identify new export fields for fabric/subfabric containment; - identify owner actor fields and king/lord/tenant roles; - identify cross-boundary utility edge metadata; - identify cost/profit center attribution fields; - identify schema/export version metadata; - decide backward compatibility behavior for existing `STATE-WP-0050` imports. Done when: - State Hub has an implementation checklist for the new export shape; - compatibility and migration behavior are explicit; - blocking questions are fed back to `railiance-fabric` if the export contract is incomplete. Review update 2026-05-24: - vNext export identity is `apiVersion: railiance.fabric/v1alpha2` with `schema_version: financial-fabric-v1`; legacy `railiance.fabric/v1alpha1` remains supported for `STATE-WP-0050` imports. - Top-level vNext sections are `compatibility`, `netkingdom`, `actors`, `fabrics`, `nodes`, `edges`, and `unresolved`; State Hub will preserve them in `graph_json` and materialize dashboard/query columns where useful. - Node materialization will add containment (`netkingdom_id`, `fabric_id`, `subfabric_id`, `environment`, `deployment_scenario_id`), ownership (`owner_actor_id`, `owner_role`, `ownership_resolution`), accounting (`cost_center_id`, `profit_center_id`), and evidence review metadata. - Edge materialization will add `relationship_category`, utility provider/consumer owner and fabric/subfabric context, boundary crossing flags, utility type/payment/business metadata, accounting attribution, and evidence review metadata. - Import validation should accept both export families. For vNext, accepted nodes must carry containment, ownership, and evidence; utility edges must carry provider, consumer, boundary, and utility objects. State Hub will preserve unresolved or ambiguous markers from Fabric instead of inventing ownership. - Backward compatibility behavior: existing `v1alpha1` payloads continue to ingest and query with new columns left null/defaulted. The follow-up migration is additive and does not reset existing imports. ## T02 - Extend Read-Model Storage ```task id: STATE-WP-0051-T02 status: done priority: high state_hub_task_id: "989387ff-5c70-4eb4-a418-fd61e2a664dd" ``` Extend State Hub storage for the improved Fabric graph read model. Requirements: - preserve import metadata and idempotency from `STATE-WP-0050`; - store export schema/version metadata; - store fabric and subfabric identity on nodes and edges; - store owner actor identity and owner role; - store cross-boundary utility metadata; - store node and edge cost/profit center attribution when present; - preserve raw payloads for audit/debugging; - avoid treating imported Fabric graph rows as State Hub-authored work items. Done when: - migrations and repository/service helpers exist; - old imports remain readable or are intentionally reset with documentation; - latest-import behavior still works. Result: - Added an additive Alembic migration for financial Fabric vNext read-model columns on imports, nodes, and edges. - Imports now store `schema_version`, netkingdom/king actor metadata, actor, fabric, and unresolved counts, and compatibility metadata while preserving the full raw `graph_json`. - Nodes now materialize containment, ownership, evidence review, and optional cost/profit center attribution. Edges now materialize relationship category, utility provider/consumer context, boundary crossing flags, utility payment metadata, evidence review state, and accounting attribution. - Legacy `railiance.fabric/v1alpha1` imports remain valid with vNext columns left null or defaulted. ## T03 - Update Ingest And Validation ```task id: STATE-WP-0051-T03 status: done priority: high state_hub_task_id: "97c40d3c-33dd-4848-b375-4302811c0319" ``` Update Fabric graph ingest to accept and validate the vNext export payload. Requirements: - validate required ownership and fabric/subfabric fields according to the export contract; - preserve incomplete/unresolved markers from Fabric rather than inventing State Hub ownership; - ingest cross-boundary utility edges without flattening their business meaning; - ingest cost/profit center attribution as optional accounting metadata; - record failed validation in normal import/progress surfaces; - keep pull mode from the Fabric registry. Done when: - direct ingest and pull ingest work for vNext exports; - malformed exports fail without partially mutating the read model; - repeated vNext imports remain idempotent. Result: - Extended ingest validation to accept both `railiance.fabric/v1alpha1` and `railiance.fabric/v1alpha2` / `financial-fabric-v1`. - vNext validation requires netkingdom, actors, fabrics, node containment, node ownership, node/edge evidence, and complete utility edge provider, consumer, boundary, and utility metadata. - Accepted nodes with unresolved or ambiguous ownership are rejected; candidate or unresolved markers from Fabric are preserved instead of invented by State Hub. - Existing invalid-import behavior still records a failed import/progress row without writing graph nodes or edges. ## T04 - Add Query Surfaces And Views ```task id: STATE-WP-0051-T04 status: done priority: medium state_hub_task_id: "64b0d9d2-bcfc-498f-b9b5-cbbcd3c26ead" ``` Expose read-only query surfaces for the improved Fabric model. Queries should support filtering or summarizing by: - fabric; - subfabric; - owner actor; - owner role: king, lord, tenant, operator/steward where present; - cross-boundary utility edges; - provider owner and consumer owner; - cost center; - profit center; - unresolved ownership; - unresolved accounting attribution; - source repo and canonical metadata retained from the previous model. Done when: - API endpoints can answer the primary architecture questions; - existing `/fabric/graph/*` endpoints are extended or versioned cleanly; - no query mutates State Hub workstreams, tasks, messages, decisions, or progress rows. Result: - Extended `/fabric/graph/nodes` filters for fabric, subfabric, owner actor, owner role, ownership resolution, cost/profit center, evidence review state, and unresolved ownership. - Extended `/fabric/graph/edges` filters for relationship category, utility provider/consumer owners and boundaries, fabric/subfabric crossing flags, utility type/business/payment metadata, cost/profit attribution, evidence review state, and missing payment schema. - Kept existing endpoints read-only and backward compatible. ## T05 - Add Dashboard/Operator Readiness ```task id: STATE-WP-0051-T05 status: done priority: medium state_hub_task_id: "852ac7b6-9296-4900-a34d-3e8ed2983237" ``` Prepare State Hub surfaces for operator use. Useful summaries: - node counts by fabric and subfabric; - nodes by owner and owner role; - cross-boundary utility edges by provider and consumer; - tenant-facing utilities without payment schema; - owned nodes without cost/profit center attribution; - unresolved ownership or containment gaps; - latest import freshness and schema version. Done when: - API summaries are dashboard-ready; - docs include operator examples; - the UI or documented API flow makes it clear that State Hub is displaying a Fabric read model, not authoring topology. Result: - Extended `/fabric/graph/summary` with dashboard-ready financial counters: schema/netkingdom metadata, actor/fabric/unresolved counts, nodes by fabric/subfabric/owner/role/resolution, utility edges by provider/consumer owner and business model, tenant utilities missing payment schema, nodes without accounting attribution, unresolved ownership, and unresolved accounting counts. - Updated `docs/fabric-graph-read-model.md` with vNext refresh and query examples and the source-of-truth warning that State Hub does not synthesize Fabric ownership. ## T06 - Verify Against A Rebuilt Railiance Baseline ```task id: STATE-WP-0051-T06 status: done priority: high state_hub_task_id: "6bee7960-4714-4278-80fc-f8e32ec203bc" ``` Verify the State Hub adaptation against the rebuilt Railiance Fabric baseline from `RAIL-FAB-WP-0018`. Requirements: - import a vNext export from `railiance-fabric`; - verify fabric/subfabric, ownership, cross-boundary utility, and accounting fields are stored and queryable; - verify old read-model behavior that remains supported; - add regression tests for validation failure, idempotent import, latest import selection, and read-only query behavior; - document refresh commands for operators. Done when: - State Hub can import and query the improved Fabric export; - tests cover the new fields and compatibility behavior; - operator docs explain how to refresh after a Fabric rebuild. Result: - Added regression coverage for financial vNext ingest/materialization, summary counters, utility edge queries, invalid accepted-node ownership, and legacy v1alpha1 compatibility. - Verified the generated local `railiance-fabric export --format financial` payload validates in State Hub as `railiance.fabric/v1alpha2`, `financial-fabric-v1` with 2 actors, 1 fabric, 49 nodes, 58 edges, and 0 unresolved gaps. - Full State Hub test suite passed: 332 tests. ## Acceptance - State Hub imports the vNext Fabric graph export as a read model only. - Fabric/subfabric containment and owner actor data are stored and queryable. - Cross-boundary utility interfaces can be queried as value interfaces. - Cost/profit center attribution is queryable as accounting/view metadata. - State Hub does not redefine Fabric boundaries or invent ownership. - Regression tests cover ingest, validation, idempotency, latest import, and read-only query behavior.