railiance-fabric/workplans/RAIL-FAB-WP-0017-financial-fabric-model-reset.md

---
id: RAIL-FAB-WP-0017
type: workplan
title: "Financial Fabric Model Reset"
domain: railiance
repo: railiance-fabric
status: ready
owner: codex
topic_slug: railiance
created: "2026-05-23"
updated: "2026-05-23"
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: todo
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.

## T02 - Define The VNext Fabric Semantic Contract

```task
id: RAIL-FAB-WP-0017-T02
status: todo
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.

## T03 - Refactor Core Validation And Registry Materialization

```task
id: RAIL-FAB-WP-0017-T03
status: todo
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.

## T04 - Update The State Hub Export Contract

```task
id: RAIL-FAB-WP-0017-T04
status: todo
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.

## T05 - Seed The Current Railiance Netkingdom Baseline

```task
id: RAIL-FAB-WP-0017-T05
status: todo
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.

## T06 - Update Documentation, Fixtures, And Operator Guidance

```task
id: RAIL-FAB-WP-0017-T06
status: todo
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.

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