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

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
STATE-WP-0051	workplan	Financial Fabric Read Model Adaptation	custodian	state-hub	finished	codex	custodian	2026-05-23	2026-05-24	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

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

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

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

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

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

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.