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