From ff7e98a28dd4ef381e44bdec872a63c721202b84 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 24 May 2026 00:26:00 +0200 Subject: [PATCH] chore: register financial fabric read model workplan --- ...-financial-fabric-read-model-adaptation.md | 231 ++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 workplans/STATE-WP-0051-financial-fabric-read-model-adaptation.md diff --git a/workplans/STATE-WP-0051-financial-fabric-read-model-adaptation.md b/workplans/STATE-WP-0051-financial-fabric-read-model-adaptation.md new file mode 100644 index 0000000..6f132e3 --- /dev/null +++ b/workplans/STATE-WP-0051-financial-fabric-read-model-adaptation.md @@ -0,0 +1,231 @@ +--- +id: STATE-WP-0051 +type: workplan +title: "Financial Fabric Read Model Adaptation" +domain: custodian +repo: state-hub +status: ready +owner: codex +topic_slug: custodian +created: "2026-05-23" +updated: "2026-05-23" +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: todo +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. + +## T02 - Extend Read-Model Storage + +```task +id: STATE-WP-0051-T02 +status: todo +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. + +## T03 - Update Ingest And Validation + +```task +id: STATE-WP-0051-T03 +status: todo +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. + +## T04 - Add Query Surfaces And Views + +```task +id: STATE-WP-0051-T04 +status: todo +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. + +## T05 - Add Dashboard/Operator Readiness + +```task +id: STATE-WP-0051-T05 +status: todo +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. + +## T06 - Verify Against A Rebuilt Railiance Baseline + +```task +id: STATE-WP-0051-T06 +status: todo +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. + +## 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. +