Implement financial Fabric vNext read model

workplans/STATE-WP-0051-financial-fabric-read-model-adaptation.md

@@ -4,11 +4,11 @@ type: workplan
 title: "Financial Fabric Read Model Adaptation"
 domain: custodian
 repo: state-hub
-status: ready
+status: finished
 owner: codex
 topic_slug: custodian
 created: "2026-05-23"
-updated: "2026-05-23"
+updated: "2026-05-24"
 state_hub_workstream_id: "6811cf57-2896-43a1-bbb5-162e0ccfa8c5"
 ---
 
@@ -51,7 +51,7 @@ contract developed by `RAIL-FAB-WP-0017` and populated by `RAIL-FAB-WP-0018`.
 
 ```task
 id: STATE-WP-0051-T01
-status: todo
+status: done
 priority: high
 state_hub_task_id: "cf39a822-81ec-4834-9b95-b8013ccc1434"
 ```
@@ -75,11 +75,37 @@ Done when:
 - 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: todo
+status: done
 priority: high
 state_hub_task_id: "989387ff-5c70-4eb4-a418-fd61e2a664dd"
 ```
@@ -103,11 +129,25 @@ Done when:
 - 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: todo
+status: done
 priority: high
 state_hub_task_id: "97c40d3c-33dd-4848-b375-4302811c0319"
 ```
@@ -131,11 +171,24 @@ Done when:
 - 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: todo
+status: done
 priority: medium
 state_hub_task_id: "64b0d9d2-bcfc-498f-b9b5-cbbcd3c26ead"
 ```
@@ -163,11 +216,22 @@ Done when:
 - 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: todo
+status: done
 priority: medium
 state_hub_task_id: "852ac7b6-9296-4900-a34d-3e8ed2983237"
 ```
@@ -191,11 +255,23 @@ Done when:
 - 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: todo
+status: done
 priority: high
 state_hub_task_id: "6bee7960-4714-4278-80fc-f8e32ec203bc"
 ```
@@ -219,6 +295,17 @@ Done when:
 - 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.
@@ -228,4 +315,3 @@ Done when:
 - State Hub does not redefine Fabric boundaries or invent ownership.
 - Regression tests cover ingest, validation, idempotency, latest import, and
   read-only query behavior.
-