# Financial Fabric Model Audit Date: 2026-05-24 Workplan: `RAIL-FAB-WP-0017` ## Purpose This audit identifies the current `railiance-fabric` assumptions that must change to implement the financial Fabric architecture in `docs/FabricDiscoveryAndUpdate.md`. The current implementation is still centered on repo-owned declarations: ```text repo -> service -> capability -> interface -> dependency -> binding ``` That model remains useful as legacy evidence and as a self-description layer, but it is no longer the correct top-level source of truth for external fabric relations. The vNext model must start from accountability roots: netkingdom, king, lords, tenants, fabrics, subfabrics, deployment automation, durable infrastructure evidence, and cross-boundary utility interfaces. ## Current Model Assumptions ### Repo-Owned Declarations Are The Primary Graph Source Affected files: - `INTENT.md` - `SCOPE.md` - `docs/declaration-schema.md` - `docs/adoption-guide.md` - `docs/first-rollout.md` - `docs/repo-reality-scanner.md` - `fabric/README.md` - `examples/declarations/**` - `fabric/services/**` - `fabric/capabilities/**` - `fabric/interfaces/**` - `fabric/dependencies/**` - `fabric/bindings/**` Current behavior: - Repositories are expected to own declarations for services, capabilities, interfaces, dependencies, and binding assertions. - The scanner treats repo-owned Fabric declarations as the highest-trust source for accepted graph data. - Existing examples and docs teach adoption by adding `fabric/` files to participating repositories. Required change: - Repo-owned declarations should become one evidence source, mostly useful for self-description, not the default authority for external relations. - External relations, tenancy, deployment membership, and cross-boundary utility edges should come from fabric-scoped discovery roots and deployment evidence. ### Declaration Kinds Encode The Graph Shape Affected files: - `schemas/service.schema.yaml` - `schemas/capability.schema.yaml` - `schemas/interface.schema.yaml` - `schemas/dependency.schema.yaml` - `schemas/binding.schema.yaml` - `schemas/common.schema.yaml` - `railiance_fabric/model.py` - `railiance_fabric/loader.py` - `railiance_fabric/validation.py` - `railiance_fabric/graph.py` - `railiance_fabric/canon.py` - `tests/test_canon.py` - `tests/test_registry.py` - `tests/test_scanner.py` - `tests/test_discovery.py` - `tests/test_discovery_registry.py` - `tests/test_reconciliation.py` Current behavior: - `loader.py` hardcodes declaration directories: `services`, `capabilities`, `interfaces`, `dependencies`, and `bindings`. - `validation.py` only accepts the legacy declaration kinds through `SCHEMA_BY_KIND`. - `graph.py` builds provider/consumer/binding behavior directly from those declaration kinds. - `canon.py` maps those declaration kinds into canonical categories, with several partial or gap mappings. - Tests assert the legacy kinds and edge types as the normal graph shape. Required change: - Add vNext semantic graph concepts for netkingdom, actor, fabric, subfabric, owned node, utility interface, accounting attribution, and provenance. - Keep legacy declaration kinds as a compatibility/evidence layer until they can be migrated or intentionally retired. - Stop treating environment tags as possible fabric boundaries. ### Metadata Owner Is Not Financial Ownership Affected files: - `schemas/common.schema.yaml` - `railiance_fabric/graph.py` - `railiance_fabric/scanner.py` - `railiance_fabric/registry.py` - `schemas/state-hub-export.schema.yaml` - existing declaration files under `fabric/**` Current behavior: - `metadata.owner` is required for declarations, but it is just a string. - Graph exports place owner inside node `attributes.owner`, not as a first-class field. - Discovery candidates can carry owner-like attributes, but there is no enforced owner actor, role, inheritance rule, or unresolved-owner state. - State Hub export nodes require `repo`, `domain`, and `lifecycle`, but not financial owner, fabric, or subfabric. Required change: - Introduce actor identity and role: king, lord, tenant, and supporting operator/steward where needed. - Every accepted node must resolve to an owner actor, either explicit or inherited from containing fabric/subfabric. - Missing or ambiguous ownership must be represented as review state before promotion. ### Fabric Membership Is Missing Affected files: - `schemas/state-hub-export.schema.yaml` - `schemas/discovery-snapshot.schema.yaml` - `railiance_fabric/scanner.py` - `railiance_fabric/registry.py` - `railiance_fabric/graph_explorer.py` - `railiance_fabric/graph_explorer_ui.py` - `docs/graph-explorer-contract.md` - `docs/state-hub-integration.md` Current behavior: - Accepted graph nodes have repo/domain/lifecycle fields, but no `fabric_id`, `subfabric_id`, containment path, or owning lord/tenant relation. - Discovery snapshots are scoped to one `repo_slug`, one commit, and one scan profile. - Registry snapshots are stored per repository and combined by merging the latest snapshot for each repo. Required change: - Add first-class fabric/subfabric identity and containment. - Preserve repo scoping for repository evidence, but do not let repo scope define fabric membership. - Add a root netkingdom/fabric baseline for the current one-fabric Railiance setup. ### Cross-Boundary Utility Is Flattened Into Dependency Edges Affected files: - `schemas/dependency.schema.yaml` - `schemas/binding.schema.yaml` - `railiance_fabric/graph.py` - `railiance_fabric/registry.py` - `railiance_fabric/canon.py` - `railiance_fabric/graph_explorer.py` - `railiance_fabric/graph_explorer_ui.py` - `tests/test_registry.py` - `tests/test_graph_explorer.py` Current behavior: - Consumers and providers are expressed as dependencies and binding assertions. - Edges such as `consumes`, `binds:*`, and `uses_interface` map mostly to canonical `depends_on`. - There is no explicit provider-owner/consumer-owner boundary, payment schema, metering basis, or business model on the edge. Required change: - Add a first-class cross-boundary utility edge concept. - Preserve technical dependency edges, but distinguish them from economic or tenancy value interfaces. - Allow cross-boundary edges across fabric and subfabric boundaries without treating the boundary crossing as an error. ### Cost/Profit Centers Are Not Represented Affected files: - all current graph schemas and exports - `railiance_fabric/registry.py` - `railiance_fabric/graph_explorer.py` - `railiance_fabric/graph_explorer_ui.py` - State Hub import contract in `schemas/state-hub-export.schema.yaml` Current behavior: - There are no node or edge fields for cost center, profit center, allocation model, payment schema, metering basis, or attribution validity. Required change: - Add optional accounting attribution on nodes and edges. - Ensure accounting attribution can drive views without changing fabric or subfabric membership. ### Discovery Has Good Mechanics But Wrong Roots Affected files: - `railiance_fabric/scanner.py` - `railiance_fabric/discovery.py` - `railiance_fabric/reconciliation.py` - `railiance_fabric/connectors.py` - `schemas/discovery-snapshot.schema.yaml` - `docs/repo-reality-scanner.md` - `docs/operational-rescan-loops.md` - `docs/registry-onboarding.md` Current behavior: - Discovery snapshots are provenance-rich and already separate candidates from accepted graph state. - Replacement scopes, stable keys, tombstones, review states, reconciliation diffs, and connector runs are already present. - Discovery is still repo-scoped and gives `repo_declaration` precedence. - `local-fabric-registry` reads repository onboarding manifests, not accountability roots or deployment responsibility boundaries. Required change: - Reuse the raw-evidence/candidate/accepted mechanics. - Add accountability-root manifests and adapters for deployment automation, infrastructure evidence, recovery/secrets/backup evidence, and ownership boundaries. - Change precedence so repo declarations can be strong self-description evidence without overriding fabric-scoped deployment evidence. ### State Hub Export Is Too Thin For The New Model Affected files: - `schemas/state-hub-export.schema.yaml` - `railiance_fabric/graph.py` - `railiance_fabric/registry.py` - `railiance_fabric/server.py` - `docs/state-hub-integration.md` - `docs/registry-api.md` Current behavior: - `/exports/state-hub` returns a `FabricGraphExport` with nodes and edges. - Nodes require `id`, `kind`, `name`, `repo`, `domain`, and `lifecycle`. - Edges require `from`, `to`, and `type`. - Canon metadata and evidence state are present, but ownership, containment, accounting, and utility metadata are not first-class. Required change: - Version the export contract. - Add fabric/subfabric containment, owner actor identity, owner role, cross-boundary utility metadata, and optional cost/profit attribution. - Keep enough compatibility metadata for State Hub to support old imports until `STATE-WP-0051` replaces or migrates the read model. ## Affected APIs And Commands HTTP surfaces: - `GET /exports/state-hub` - `GET /exports/graph-explorer` - `GET /exports/backstage` - `GET /exports/xregistry` - `GET /graph/providers` - `GET /graph/consumers` - `GET /graph/unresolved` - `GET /graph/blast-radius` - `GET /graph/dependency-path` - `POST /repositories/{repo_slug}/snapshots` - `POST /repositories/{repo_slug}/discovery-snapshots` - `POST /repositories/{repo_slug}/discovery-snapshots/{id}/accept` - `GET /repositories/{repo_slug}/inventory` CLI surfaces: - `railiance-fabric validate` - `railiance-fabric export` - `railiance-fabric providers` - `railiance-fabric consumers` - `railiance-fabric dependency-path` - `railiance-fabric unresolved` - `railiance-fabric blast-radius` - `railiance-fabric scan` - `railiance-fabric registry sync` - `railiance-fabric registry sync-manifest` - `railiance-fabric registry scan-manifest` - `railiance-fabric registry ingest-discovery` - `railiance-fabric registry accept-discovery` - `railiance-fabric registry rescan-status` Projection surfaces: - Graph Explorer payload and manifest. - Backstage projection. - xRegistry projection. - State Hub Fabric read-model import. ## Compatibility Risks 1. State Hub import compatibility: `STATE-WP-0050` expects the current `FabricGraphExport` shape. Adding required fields or changing node/edge semantics can break ingest unless the export is versioned or State Hub is updated in lockstep. 2. Graph Explorer compatibility: Graph Explorer filters and detail panes use current node kinds, layers, dependency chains, unresolved states, and canon metadata. New actor/fabric nodes and utility edges need UI mapping before the explorer remains useful. 3. Query command compatibility: Provider/consumer/dependency-path commands are built on capability and dependency declarations. They may remain useful as legacy views, but should not be presented as the whole Fabric model. 4. Registry storage compatibility: The registry stores snapshots as JSON, so schema migration is flexible, but combined graph behavior currently deduplicates by node id across latest per-repo snapshots. Fabric-scoped snapshots may need a root snapshot or scenario/fabric identity instead of only repo latest snapshots. 5. Test fixture blast radius: Most tests assert legacy declaration kinds, repo-scoped discovery keys, and current export payload shape. The migration should add vNext tests before replacing old assertions. 6. Canon mapping ambiguity: Current canonical categories do not include financial actors, fabrics, subfabrics, accounting attributions, or utility value interfaces. These either need canonical mappings or explicit `mapping_fit: gap` handling. 7. Existing accepted graph baseline: The current accepted graph contains 49 nodes and 58 edges from the post-`RAIL-FAB-WP-0016` reset. It should be treated as a legacy baseline and re-exported or archived before a controlled vNext reset. ## Migration Approach 1. Preserve legacy declarations as `v1alpha1` evidence. Do not delete `fabric/` declarations or examples immediately. Reclassify them as self-description and bootstrap evidence. 2. Introduce a vNext contract alongside the current export. Add schema version metadata before making breaking changes. Prefer either `railiance.fabric/v1alpha2` or an explicit export `schema_version`. 3. Add first-class model concepts before changing scanner roots. Implement netkingdom, actor, fabric, subfabric, ownership, utility edge, and accounting attribution semantics in schemas/tests first. 4. Extend discovery rather than replacing it. Reuse `FabricDiscoverySnapshot`, replacement scopes, candidates, provenance, reconciliation, and acceptance. Add accountability-root manifest evidence and deployment automation adapters. 5. Seed the current one-fabric baseline. Create the Railiance netkingdom root, current king, current lord/fabric, and inherited ownership defaults. This lets existing nodes resolve ownership before tenant subfabrics exist. 6. Version State Hub import. Coordinate with `STATE-WP-0051` so State Hub can ingest both the old and vNext export during the transition, or explicitly perform a read-model reset. 7. Rebuild and compare. Produce a vNext export from the current baseline, compare it against the legacy 49-node/58-edge export, and document intentional semantic changes. ## Follow-On Implementation Notes For `RAIL-FAB-WP-0017-T02`: - Define schema names and versioning for vNext graph exports. - Decide whether netkingdom/fabric/actor are node kinds, top-level export sections, or both. - Define ownership inheritance and unresolved-owner representation. - Define utility edge fields: provider owner, consumer owner, provider boundary, consumer boundary, payment schema, metering basis, and evidence. - Define accounting fields: cost center, profit center, allocation model, attribution validity. For `RAIL-FAB-WP-0017-T03`: - Add model classes or typed helpers beyond the generic `Declaration` wrapper. - Extend validation to enforce resolvable ownership on accepted nodes. - Update registry projection to preserve ownership, containment, accounting, and utility metadata. - Keep old declaration graph validation available as a legacy command or compatibility path. For `RAIL-FAB-WP-0017-T04`: - Update `schemas/state-hub-export.schema.yaml`. - Add sample vNext export payloads and tests. - Coordinate the import fields with `STATE-WP-0051`. For `RAIL-FAB-WP-0018`: - Build an accountability-root manifest instead of extending `registry/local-repos.yaml` into too many meanings. - Treat State Hub attached repos as one discovery root, not as the Fabric boundary itself. - Add deployment automation and infrastructure evidence adapters before trying to infer cross-boundary value edges.