generated from coulomb/repo-seed
318 lines
11 KiB
Markdown
318 lines
11 KiB
Markdown
---
|
|
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.
|