--- id: RAIL-FAB-WP-0017 type: workplan title: "Financial Fabric Model Reset" domain: railiance repo: railiance-fabric status: finished owner: codex topic_slug: railiance created: "2026-05-23" updated: "2026-05-24" state_hub_workstream_id: "39cc363c-6e2a-46a2-bd19-cee7ff6fc149" --- # RAIL-FAB-WP-0017 - Financial Fabric Model Reset ## Goal Adapt `railiance-fabric` to the revised Fabric intent captured in `docs/FabricDiscoveryAndUpdate.md`. Fabric should model durable infrastructure-responsibility boundaries rather than repo-owned external relation declarations. The core model must understand the Railiance netkingdom, king/lord/tenant financial actors, fabric and subfabric containment, resolvable node ownership, cross-boundary utility interfaces, and optional cost/profit center attribution. ## Background The current Fabric implementation grew from repo-owned declarations and a canon-aligned graph export. That was useful for bootstrapping, but it now misplaces authority for external relations: a repository cannot sustainably own all deployment contexts, tenant relations, or cross-boundary utility edges in which it participates. The updated architecture establishes these principles: - a fabric is bounded by financial and operational accountability; - the king is responsible for the whole netkingdom and holds the relevant recovery/secrets/backups authority; - a lord pays for a fabric; - a tenant pays for restricted use of a subfabric; - every node needs resolvable ownership; - cross-boundary utility edges are first-class value interfaces; - cost/profit centers are accounting attributions and view dimensions, not fabric boundaries; - Fabric should avoid security-zone terms such as realm or domain for its core concepts. This workplan resets the Fabric contract and internal model so later discovery work can rebuild the graph from accountability roots and deployment automation. ## T01 - Audit Current Model Assumptions ```task id: RAIL-FAB-WP-0017-T01 status: done priority: high state_hub_task_id: "3d259e3c-5534-4b6a-930a-d085d3db57e4" ``` Inventory the current assumptions that must change. Scope: - schema files and declaration shapes under `schemas/` and `fabric/`; - Python model classes and validators; - registry storage tables and snapshot materialization; - State Hub export payload shape; - tests and fixtures that assume repo-owned declarations are the primary graph source; - documentation that still describes Fabric as repo-owned external relation declarations. Done when: - affected files and APIs are listed; - compatibility risks are documented; - the migration approach for existing accepted graph data is explicit; - follow-on tasks have enough detail to implement without rediscovering the whole codebase. Result: - Added `docs/financial-fabric-model-audit.md`. - Listed affected schemas, Python modules, registry/API surfaces, docs, fixtures, tests, and projections. - Documented compatibility risks for State Hub ingest, Graph Explorer, provider/consumer query commands, registry storage, test fixtures, canon mapping, and the existing accepted graph baseline. - Defined a migration approach that preserves `v1alpha1` declarations as legacy evidence, adds a versioned vNext contract, reuses the existing discovery/reconciliation mechanics, seeds the current one-fabric Railiance baseline, and coordinates State Hub changes through `STATE-WP-0051`. ## T02 - Define The VNext Fabric Semantic Contract ```task id: RAIL-FAB-WP-0017-T02 status: done priority: high state_hub_task_id: "8bbab878-0bff-4302-a925-15a8aceabf9b" ``` Define the next graph contract for Fabric snapshots and exports. Required concepts: - netkingdom root; - actor nodes for king, lord, tenant, and supporting operators/stewards; - fabric and subfabric containment; - node ownership and inherited ownership resolution; - cross-boundary utility interfaces; - optional cost center and profit center attribution on nodes and edges; - evidence and provenance fields for every discovered or accepted fact; - schema versioning and compatibility metadata. Done when: - schemas or contract documents describe the vNext shape; - existing canonical node/edge concepts are mapped to the new model or marked for retirement; - unresolved ownership and ambiguous containment have explicit representation; - examples cover the current single Railiance fabric, a tenant subfabric, and a cross-boundary utility edge. Result: - Added `docs/financial-fabric-vnext-contract.md`. - Defined a proposed `railiance.fabric/v1alpha2` / `financial-fabric-v1` export shape with top-level netkingdom, actor, fabric, node, edge, and unresolved sections. - Defined actor roles, fabric/subfabric containment, ownership resolution, cross-boundary utility edges, accounting attribution, and evidence/provenance shape. - Mapped legacy declaration kinds and existing edge types to vNext disposition. - Included examples for the current single Railiance fabric, a future tenant subfabric, and a cross-subfabric utility edge. - Listed State Hub import requirements for `STATE-WP-0051`. ## T03 - Refactor Core Validation And Registry Materialization ```task id: RAIL-FAB-WP-0017-T03 status: done priority: high state_hub_task_id: "7ff1c162-f778-4ab4-9e09-a512a54b2f68" ``` Update validation and registry materialization around the new contract. Requirements: - enforce resolvable ownership for graph nodes; - distinguish containment, ownership, accounting attribution, and diagnostic views; - support fabric and subfabric membership without treating environments as fabrics; - represent cross-boundary utility edges as first-class accepted graph edges; - retain evidence/provenance and confidence/review state; - keep old graph data readable long enough for migration or controlled reset. Done when: - model classes, validators, registry materialization, and tests support the new contract; - invalid missing-owner cases fail or are flagged according to the contract; - existing snapshot/export code can emit the vNext model. Result: - Added `railiance_fabric/financial.py` with `v1alpha2` financial Fabric graph materialization, validation, and merge helpers. - Registry snapshot ingestion now materializes financial graphs before validation while preserving the legacy `v1alpha1` schema path. - Registry combined graph output can preserve and merge `v1alpha2` actors, fabrics, nodes, edges, unresolved gaps, ownership, containment, accounting, and utility metadata when all latest snapshots use the financial contract. - Added canon mappings for vNext kinds and edge types such as `FabricActor`, `Fabric`, `Subfabric`, `UtilityInterface`, `CostCenter`, `ProfitCenter`, `contains`, `owned_by`, `operated_by`, `provides_utility_to`, and accounting attribution edges. - Added registry tests covering missing accepted-node ownership rejection, financial graph snapshot ingestion, utility edge materialization, and combined `v1alpha2` graph output. - Verified with `python3 -m pytest tests/test_registry.py -q` and full `python3 -m pytest`. ## T04 - Update The State Hub Export Contract ```task id: RAIL-FAB-WP-0017-T04 status: done priority: high state_hub_task_id: "d10f120d-746d-468d-b208-d946b54c2707" ``` Revise the State Hub export payload so State Hub can import the improved Fabric model as a read model. Requirements: - include fabric/subfabric identity and containment; - include owner actor identity and owner role; - include accounting attribution fields when present; - include cross-boundary utility metadata; - include schema/export version metadata; - preserve enough current canonical fields for compatibility where practical; - document required State Hub changes for `STATE-WP-0051`. Done when: - export schema and sample payloads are updated; - current State Hub import limitations are documented; - compatibility tests cover both old baseline import behavior and the new vNext export behavior, or intentionally document a controlled breaking reset. Result: - Updated `schemas/state-hub-export.schema.yaml` to accept both the legacy `railiance.fabric/v1alpha1` declaration-centered export and the `railiance.fabric/v1alpha2` / `financial-fabric-v1` export. - Added schema fields for netkingdom, actors, fabrics, node containment, node ownership, accounting attribution, evidence, utility edge provider/consumer context, boundary crossing flags, and unresolved gaps. - Added `examples/exports/financial-fabric-v1.json` as a materialized sample payload. - Updated `docs/state-hub-integration.md` to describe the v1alpha1/v1alpha2 contract split, State Hub import expectations, and the current limitation that `STATE-WP-0050` only materializes v1alpha1 until `STATE-WP-0051`. - Added schema compatibility coverage for both old and financial graph export shapes. - Verified with `python3 -m pytest tests/test_registry.py -q` and full `python3 -m pytest`. ## T05 - Seed The Current Railiance Netkingdom Baseline ```task id: RAIL-FAB-WP-0017-T05 status: done priority: medium state_hub_task_id: "b8430050-94a8-43f6-9b3c-7928c5c6bb69" ``` Create the initial accepted model for the current Railiance responsibility boundary. Requirements: - one root Railiance netkingdom; - current king actor; - current lord/fabric boundary reflecting that one actor pays for the current infrastructure; - initial default ownership rules for discovered nodes; - placeholders for future tenant/subfabric modeling; - no security-zone terminology in the core model. Done when: - the current graph can resolve ownership for all accepted nodes; - the baseline explains why there is currently one effective fabric; - future tenant subfabrics can be added without changing the root fabric definition. Result: - Added `fabric/financial/railiance-netkingdom.yaml` as the current Railiance netkingdom baseline with king, lord, one active fabric, inherited default containment/ownership/accounting, and a future subfabric template. - Added `railiance_fabric/financial_baseline.py` to load the baseline and project legacy `v1alpha1` exports into `v1alpha2` financial Fabric exports. - Added `railiance-fabric export --format financial` so the current graph can emit a financial baseline projection. - Added tests proving the current graph projects to the Railiance baseline, validates as a financial graph, has no unresolved gaps, and gives every node inherited ownership in `fabric.railiance.primary`. - Verified with `python3 -m pytest tests/test_registry.py -q` and full `python3 -m pytest`. ## T06 - Update Documentation, Fixtures, And Operator Guidance ```task id: RAIL-FAB-WP-0017-T06 status: done priority: medium state_hub_task_id: "93a8a79e-877f-48c1-888e-0fb50c8de75b" ``` Bring docs and fixtures in line with the reset model. Requirements: - update README and affected architecture/registry/export docs; - document the migration from repo-owned declarations to accountability-root discovery; - update sample graph exports and validation fixtures; - document the handoff to State Hub and to the discovery/update-loop workplan; - keep `docs/FabricDiscoveryAndUpdate.md` as the architecture anchor. Done when: - docs no longer present repo-owned external declarations as the default source of truth; - tests and examples exercise king/lord/tenant, ownership, fabric/subfabric, cost/profit attribution, and cross-boundary utility edges; - operator guidance explains how to refresh State Hub after a reset export. Result: - Added `docs/financial-fabric-operator-guide.md` with the baseline refresh loop, guarded reset rebuild sequence, State Hub handoff, and discovery-loop follow-up. - Updated README, query/export docs, State Hub integration docs, registry API, onboarding, and reset operations to document `railiance-fabric export --format financial` and the v1alpha1/v1alpha2 transition. - Updated declaration, rollout, scanner, canon, fabric, and example docs so repo-local declarations are presented as evidence/bootstrap data rather than the default authority for external fabric relations. - Kept `docs/FabricDiscoveryAndUpdate.md` as the architecture anchor and linked operator-facing docs back to it. - Verified with `git diff --check`, `python3 -m pytest tests/test_registry.py -q`, and full `python3 -m pytest`. ## Acceptance - Fabric has a documented vNext contract aligned with `docs/FabricDiscoveryAndUpdate.md`. - Every accepted graph node has resolvable ownership. - Fabric and subfabric membership is distinct from environments, deployment scenarios, and views. - Cross-boundary utility interfaces are first-class graph edges. - Cost/profit centers are optional accounting attributions and view dimensions. - The State Hub export schema is updated or a controlled reset path is documented. - Existing tests are updated or replaced with coverage for the new model.