railiance-fabric/workplans/RAIL-FAB-WP-0017-financial-fabric-model-reset.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
RAIL-FAB-WP-0017	workplan	Financial Fabric Model Reset	railiance	railiance-fabric	finished	codex	railiance	2026-05-23	2026-05-24	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

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

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

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

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

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

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.