generated from coulomb/repo-seed
docs: define financial fabric architecture
This commit is contained in:
241
workplans/RAIL-FAB-WP-0017-financial-fabric-model-reset.md
Normal file
241
workplans/RAIL-FAB-WP-0017-financial-fabric-model-reset.md
Normal file
@@ -0,0 +1,241 @@
|
||||
---
|
||||
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.
|
||||
|
||||
@@ -0,0 +1,213 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0018
|
||||
type: workplan
|
||||
title: "Accountability Root Discovery And Update Loop"
|
||||
domain: railiance
|
||||
repo: railiance-fabric
|
||||
status: ready
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
created: "2026-05-23"
|
||||
updated: "2026-05-23"
|
||||
state_hub_workstream_id: "651185b5-83fe-4aef-b29d-617b2bc48c7a"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0018 - Accountability Root Discovery And Update Loop
|
||||
|
||||
## Goal
|
||||
|
||||
Build the discovery and update mechanism that keeps Fabric current from durable
|
||||
accountability roots and deployment automation, rather than from repo-owned
|
||||
external relation declarations.
|
||||
|
||||
This workplan depends on the semantic direction from
|
||||
`RAIL-FAB-WP-0017-financial-fabric-model-reset.md`.
|
||||
|
||||
## Background
|
||||
|
||||
Fabric should be able to rebuild the Railiance graph from scratch by starting
|
||||
with the netkingdom, king/lord/tenant actors, fabric/subfabric boundaries,
|
||||
State Hub attached repositories, Gitea URLs, deployment automation, service
|
||||
configuration, infrastructure manifests, secret/backup evidence, and endpoint
|
||||
contracts.
|
||||
|
||||
The update loop must stay below live telemetry. It should track durable
|
||||
configuration and automation changes that alter topology, ownership, deployment,
|
||||
interfaces, or cross-boundary utility.
|
||||
|
||||
## T01 - Define Discovery Root Manifest
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0018-T01
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "38ae49fb-ce21-489c-ba67-7f76ab4febc9"
|
||||
```
|
||||
|
||||
Define a manifest format for accountability-root discovery.
|
||||
|
||||
The manifest should be able to register:
|
||||
|
||||
- netkingdom root;
|
||||
- king, lord, and tenant actors;
|
||||
- fabric and subfabric boundaries;
|
||||
- State Hub attached repo inventory roots;
|
||||
- Gitea organization or repository roots;
|
||||
- deployment automation roots;
|
||||
- known host paths;
|
||||
- infrastructure, backup, recovery, and secret-root evidence sources;
|
||||
- refresh cadence or trigger hints.
|
||||
|
||||
Done when:
|
||||
|
||||
- manifest schema and examples exist;
|
||||
- the current Railiance one-fabric baseline can be represented;
|
||||
- the format can add future tenant subfabrics without changing the top-level
|
||||
fabric criterion.
|
||||
|
||||
## T02 - Implement Durable Evidence Discovery Adapters
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0018-T02
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "09246f06-10db-4c6c-9cb3-f2808fdbaa38"
|
||||
```
|
||||
|
||||
Implement or adapt scanners for durable evidence sources.
|
||||
|
||||
Initial adapters should cover:
|
||||
|
||||
- State Hub attached repositories and host paths;
|
||||
- local/Gitea repository identity;
|
||||
- Dockerfiles and Compose files;
|
||||
- Kubernetes, systemd, reverse proxy, and service config where present;
|
||||
- deployment scripts and CI/CD references;
|
||||
- API specs and endpoint contracts;
|
||||
- backup, recovery, and secret-management evidence where safely discoverable.
|
||||
|
||||
Done when:
|
||||
|
||||
- each adapter emits provenance-rich raw evidence;
|
||||
- evidence distinguishes durable existence/configuration from live operational
|
||||
state;
|
||||
- adapters can run against the current local Railiance workspace.
|
||||
|
||||
## T03 - Build Evidence Store And Identity Normalization
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0018-T03
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "2a79938f-13e2-41b4-b692-74420d31bec4"
|
||||
```
|
||||
|
||||
Persist discovery output and normalize identities before graph promotion.
|
||||
|
||||
Requirements:
|
||||
|
||||
- scanner run metadata;
|
||||
- source paths, URLs, timestamps, scanner versions, and content hashes;
|
||||
- stable identity candidates for repos, deployables, services, machines,
|
||||
endpoints, fabrics, subfabrics, and actors;
|
||||
- duplicate/ambiguous identity detection;
|
||||
- candidate graph generation separate from accepted graph snapshots.
|
||||
|
||||
Done when:
|
||||
|
||||
- raw evidence can be inspected independently from accepted graph state;
|
||||
- identity normalization produces reviewable candidates;
|
||||
- repeated scans produce deterministic identities for unchanged sources.
|
||||
|
||||
## T04 - Add Ownership Resolution And Review Flow
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0018-T04
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "670be2c2-6bec-4534-ae6a-ab0186ce0a8d"
|
||||
```
|
||||
|
||||
Resolve ownership for discovered nodes and flag gaps.
|
||||
|
||||
Requirements:
|
||||
|
||||
- inherit owner from containing fabric/subfabric when evidence is sufficient;
|
||||
- support explicit owner evidence from manifests or deployment automation;
|
||||
- flag nodes with unresolved ownership;
|
||||
- flag ambiguous fabric/subfabric containment;
|
||||
- expose review/accept operations for candidates;
|
||||
- preserve reviewer decisions across rescans when evidence identity is stable.
|
||||
|
||||
Done when:
|
||||
|
||||
- no accepted node can silently lack ownership;
|
||||
- unresolved or ambiguous nodes are visible before promotion;
|
||||
- review decisions survive ordinary rescans.
|
||||
|
||||
## T05 - Implement Snapshot Deltas And Freshness Triggers
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0018-T05
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "c2f28b34-de32-4090-8782-5d00541b9018"
|
||||
```
|
||||
|
||||
Add an update loop that detects meaningful Fabric changes.
|
||||
|
||||
Triggers should include:
|
||||
|
||||
- deployment automation changes;
|
||||
- infrastructure manifest changes;
|
||||
- State Hub attached repository inventory changes;
|
||||
- repository changes affecting deployables, APIs, service names, ports,
|
||||
endpoint contracts, images, or deployment configuration;
|
||||
- lord, tenant, cost/profit center, backup, recovery, or secret-root changes;
|
||||
- manual operator rebuilds;
|
||||
- scheduled periodic rescans.
|
||||
|
||||
Done when:
|
||||
|
||||
- scanner runs can compare against the previous accepted snapshot;
|
||||
- deltas distinguish added/changed/removed nodes and edges;
|
||||
- ownership, containment, accounting attribution, and cross-boundary utility
|
||||
changes are highlighted;
|
||||
- unchanged sources are not needlessly promoted.
|
||||
|
||||
## T06 - Bootstrap The Current Railiance Rebuild
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0018-T06
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "0d05ee40-0823-473f-9c87-0ed964e8900c"
|
||||
```
|
||||
|
||||
Run the new discovery/update loop against the current Railiance workspace.
|
||||
|
||||
Requirements:
|
||||
|
||||
- rebuild from the accountability root manifest;
|
||||
- produce a reviewable candidate graph;
|
||||
- accept the baseline into a versioned Fabric snapshot;
|
||||
- export the snapshot for State Hub;
|
||||
- document unresolved gaps as follow-up workplans rather than hiding them.
|
||||
|
||||
Done when:
|
||||
|
||||
- the current Railiance graph can be rebuilt from durable roots;
|
||||
- ownership is resolved or explicitly flagged for every node;
|
||||
- State Hub can import the resulting export after `STATE-WP-0051`;
|
||||
- operator docs explain how to rerun the rebuild and update loop.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Fabric discovery starts from accountability roots and deployment automation.
|
||||
- Raw evidence, candidate graph state, and accepted graph snapshots are
|
||||
separated.
|
||||
- The update loop detects durable topology, ownership, deployment, interface,
|
||||
and cross-boundary utility changes.
|
||||
- Live telemetry remains out of scope.
|
||||
- The current Railiance baseline can be rebuilt from scratch and exported.
|
||||
|
||||
Reference in New Issue
Block a user