---
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.