From 39762551c09127ba62a2a5ad37544a43a0acf6b5 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sun, 24 May 2026 00:42:39 +0200 Subject: [PATCH] docs: audit financial fabric vnext contract --- docs/financial-fabric-model-audit.md | 421 +++++++++++++++ docs/financial-fabric-vnext-contract.md | 493 ++++++++++++++++++ ...AB-WP-0017-financial-fabric-model-reset.md | 36 +- 3 files changed, 945 insertions(+), 5 deletions(-) create mode 100644 docs/financial-fabric-model-audit.md create mode 100644 docs/financial-fabric-vnext-contract.md diff --git a/docs/financial-fabric-model-audit.md b/docs/financial-fabric-model-audit.md new file mode 100644 index 0000000..c2b9df0 --- /dev/null +++ b/docs/financial-fabric-model-audit.md @@ -0,0 +1,421 @@ +# 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. diff --git a/docs/financial-fabric-vnext-contract.md b/docs/financial-fabric-vnext-contract.md new file mode 100644 index 0000000..05e3f7a --- /dev/null +++ b/docs/financial-fabric-vnext-contract.md @@ -0,0 +1,493 @@ +# Financial Fabric VNext Contract + +Date: 2026-05-24 + +Workplan: `RAIL-FAB-WP-0017` + +Status: contract draft for implementation + +## Intent + +The vNext Fabric contract models the Railiance netkingdom as a durable +infrastructure-responsibility graph. + +The contract separates: + +- financial responsibility boundaries from environments and views; +- ownership from repository metadata; +- cross-boundary utility interfaces from ordinary technical dependencies; +- accounting attribution from fabric membership; +- durable topology from live telemetry. + +The contract should be implemented as a versioned export shape before replacing +the existing `railiance.fabric/v1alpha1` declaration-centered graph. + +## Versioning + +Recommended contract identity: + +```yaml +apiVersion: railiance.fabric/v1alpha2 +kind: FabricGraphExport +schema_version: financial-fabric-v1 +``` + +`v1alpha1` remains the compatibility layer for legacy declarations and the +current State Hub import. `v1alpha2` introduces first-class netkingdom, +actor, fabric, subfabric, ownership, utility, and accounting semantics. + +## Top-Level Export Shape + +```yaml +apiVersion: railiance.fabric/v1alpha2 +kind: FabricGraphExport +schema_version: financial-fabric-v1 +generated_at: "2026-05-24T00:00:00Z" +source: + producer: railiance-fabric + registry: registry + commit: "" + generation_reason: rebuild | rescan | operator_refresh +compatibility: + legacy_v1alpha1_supported: true + breaking_reset: false +netkingdom: + id: railiance.netkingdom + name: Railiance Netkingdom + king_actor_id: actor.railiance.king +actors: [] +fabrics: [] +nodes: [] +edges: [] +unresolved: [] +``` + +The top-level sections are intentionally explicit. `nodes` and `edges` remain +the primary graph payload for State Hub and visualizers, but `netkingdom`, +`actors`, and `fabrics` define the responsibility boundary context used to +resolve ownership and containment. + +## Actors + +Actors are accountable parties. They are graph addressable and may also be +materialized as nodes when a consumer needs a pure node/edge projection. + +```yaml +id: actor.railiance.king +kind: FabricActor +role: king +name: Railiance King +legal_name: "" +description: Responsible for the Railiance netkingdom. +authority: + recovery_authority: true + secrets_authority: true + backup_authority: true + termination_authority: true +relationships: + contracts_with: + - actor.railiance.primary-lord +``` + +Actor roles: + +- `king`: responsible for the netkingdom and relevant recovery/secrets/backup + authority. +- `lord`: pays for a fabric. +- `tenant`: pays for restricted use of a subfabric. +- `operator`: operates infrastructure on behalf of a king, lord, or tenant. +- `steward`: maintains a repo, service, or capability but does not necessarily + pay for it. + +Only king, lord, and tenant define financial boundary semantics. Operator and +steward roles are supporting roles. + +## Fabrics And Subfabrics + +Fabrics and subfabrics are responsibility boundaries. + +```yaml +id: fabric.railiance.primary +kind: Fabric +name: Railiance Primary Fabric +netkingdom_id: railiance.netkingdom +lord_actor_id: actor.railiance.primary-lord +parent_fabric_id: null +boundary: + boundary_type: fabric + criterion: financial_and_operational_accountability + payment_responsibility: actor.railiance.primary-lord + operational_responsibility: actor.railiance.king + recovery_responsibility: actor.railiance.king +status: active +evidence_refs: [] +``` + +```yaml +id: subfabric.railiance.tenant.coulomb +kind: Subfabric +name: Coulomb Tenant Subfabric +netkingdom_id: railiance.netkingdom +parent_fabric_id: fabric.railiance.primary +tenant_actor_id: actor.coulomb.tenant +boundary: + boundary_type: subfabric + criterion: restricted_paid_tenant_utility + payment_responsibility: actor.coulomb.tenant + operational_responsibility: actor.railiance.primary-lord + recovery_responsibility: actor.railiance.king +status: planned +evidence_refs: [] +``` + +Fabric membership changes when payment, operational responsibility, recovery +responsibility, or legal accountability changes. It does not change because a +service moves environments, a host is replaced, a repo is refactored, or a +diagnostic view changes. + +## Nodes + +Every accepted node must resolve ownership and containment. + +```yaml +id: state-hub.api +kind: Service +name: State Hub API +repo: state-hub +domain: custodian +lifecycle: active +containment: + netkingdom_id: railiance.netkingdom + fabric_id: fabric.railiance.primary + subfabric_id: null + environment: local + deployment_scenario_id: null +ownership: + owner_actor_id: actor.railiance.primary-lord + owner_role: lord + resolution: inherited + inherited_from: fabric.railiance.primary + supporting_actor_ids: + - actor.state-hub.steward +accounting: + cost_center_id: null + profit_center_id: null + allocation_model: null +evidence: + state: observed + review_state: accepted + confidence: 0.95 + refs: [] +attributes: {} +``` + +Required accepted-node semantics: + +- `containment.netkingdom_id` +- `containment.fabric_id` +- `ownership.owner_actor_id` +- `ownership.owner_role` +- `ownership.resolution` +- `evidence.state` +- `evidence.review_state` + +Recommended compatibility fields: + +- `repo` +- `domain` +- `lifecycle` +- `canon_category` +- `canon_anchor` +- `mapping_fit` +- `attributes` + +## Ownership Resolution + +Ownership resolution values: + +- `explicit`: evidence directly names the owner actor. +- `inherited`: ownership is inherited from containing fabric or subfabric. +- `unresolved`: no acceptable owner could be resolved. +- `ambiguous`: multiple plausible owners exist and review is needed. + +Unresolved or ambiguous nodes may appear as candidates or importable read-model +gaps, but they must not silently become accepted graph truth. + +```yaml +id: unresolved:node:fixture +target_id: fixture.unknown-service +kind: unresolved_ownership +severity: needs_review +message: Node has no explicit owner and no resolvable fabric/subfabric owner. +evidence_refs: [] +``` + +## Edges + +Edges keep technical topology while adding boundary and value semantics. + +```yaml +id: edge:state-hub.api:exposes:state-hub.http +from: state-hub.api +to: state-hub.http +type: exposes +relationship_category: technical +canonical_type: exposes +boundary: + crosses_fabric_boundary: false + crosses_subfabric_boundary: false +evidence: + state: observed + review_state: accepted + confidence: 0.95 + refs: [] +attributes: {} +``` + +Relationship categories: + +- `containment`: netkingdom, fabric, subfabric, actor, or node containment. +- `ownership`: owner/steward/operator relationships. +- `technical`: deployment, exposure, dependency, flow, build, or evidence edge. +- `utility`: value-bearing interface from provider to consumer. +- `accounting`: cost/profit attribution or allocation edge. +- `evidence`: source artifact or provenance relationship. + +## Cross-Boundary Utility Edges + +Cross-boundary utility edges are first-class because they represent value moving +across financial responsibility boundaries. + +```yaml +id: utility:state-hub-api:coulomb-tenant +from: state-hub.http +to: tenant.coulomb.automation-client +type: provides_utility_to +relationship_category: utility +canonical_type: depends_on +provider: + owner_actor_id: actor.railiance.primary-lord + fabric_id: fabric.railiance.primary + subfabric_id: null +consumer: + owner_actor_id: actor.coulomb.tenant + fabric_id: fabric.railiance.primary + subfabric_id: subfabric.railiance.tenant.coulomb +boundary: + crosses_fabric_boundary: false + crosses_subfabric_boundary: true +utility: + utility_type: coordination_api + contract_id: state-hub.http + payment_schema_id: payment.internal-tenant-access + metering_basis: request | seat | flat | allocation | unknown + business_model: tenant_utility +accounting: + provider_profit_center_id: null + consumer_cost_center_id: null + allocation_model: null +evidence: + state: declared + review_state: accepted + confidence: 0.8 + refs: [] +attributes: {} +``` + +The edge may cross a subfabric boundary without crossing the parent fabric +boundary. This is expected for tenant utility inside the current Railiance +fabric. + +## Cost And Profit Center Attribution + +Accounting attribution is optional and must not redefine containment. + +Node-level attribution: + +```yaml +accounting: + cost_center_id: cc.platform.shared + profit_center_id: null + allocation_model: direct + valid_from: "2026-05-24" + valid_until: null +``` + +Edge-level attribution: + +```yaml +accounting: + provider_profit_center_id: pc.tenant-utilities + consumer_cost_center_id: cc.coulomb.automation + allocation_model: usage_weighted + payment_schema_id: payment.internal-tenant-access + metering_basis: request + valid_from: "2026-05-24" + valid_until: null +``` + +Cost/profit center changes should produce accounting deltas and views, not +fabric moves. + +## Evidence And Provenance + +Every discovered or accepted fact should carry evidence. + +```yaml +evidence: + state: observed | declared | inferred | proposed | gap + review_state: accepted | candidate | needs_review | rejected + confidence: 0.0 + refs: + - id: evidence:state-hub:compose:api + source_kind: deployment_manifest + source_path: compose.yaml + source_url: null + source_repo: state-hub + source_commit: abc123 + scanner: compose + scanner_version: "0.1.0" + content_hash: sha256:... + observed_at: "2026-05-24T00:00:00Z" +``` + +The contract continues to distinguish durable discovered configuration from +live operational telemetry. Health, current running state, latency, incident +status, and usage volume are not Fabric core fields. + +## Legacy Canon Mapping + +Existing canonical metadata remains useful for compatibility, but some legacy +terms should be demoted to evidence. + +| Existing kind/type | vNext disposition | +| --- | --- | +| `Repository` | Keep as source-repository node evidence. | +| `ServiceDeclaration` | Legacy self-description evidence for `Service`. | +| `CapabilityDeclaration` | Legacy self-description evidence for utility or service capability. | +| `InterfaceDeclaration` | Legacy self-description evidence for `Endpoint` or `Contract`. | +| `DependencyDeclaration` | Legacy consumer-purpose or dependency evidence; not sufficient for value edge alone. | +| `BindingAssertion` | Legacy binding evidence; may support utility edge when boundary actors are known. | +| `RuntimeService`, `DeploymentService`, `Kubernetes*`, `Server` | Durable deployment/runtime-resource evidence. | +| `provides`, `exposes`, `runs_on`, `deployed_as`, `flows_to` | Keep as technical/topology edges. | +| `consumes`, `binds:*`, `uses_interface` | Keep as technical dependency edges; promote to utility edges only when provider/consumer ownership and boundary context are known. | +| `declares` | Display/evidence edge only. | + +New vNext node kinds to map: + +| vNext kind | Suggested canonical category | +| --- | --- | +| `Netkingdom` | `software-system` until canon has a better category. | +| `FabricActor` | `consumer-purpose` or `control` depending role; likely canon gap. | +| `Fabric` | `software-system` or `control`; likely canon gap. | +| `Subfabric` | `software-system` or `control`; likely canon gap. | +| `UtilityInterface` | `endpoint` when technical, `software-system` when abstract. | +| `CostCenter` | `control`; likely canon gap. | +| `ProfitCenter` | `control`; likely canon gap. | + +New vNext edge types to map: + +| vNext edge type | Suggested canonical type | +| --- | --- | +| `contains` | `part_of` | +| `owned_by` | `governed_by` | +| `operated_by` | `governed_by` | +| `provides_utility_to` | `depends_on` with `relationship_category: utility` | +| `attributed_to_cost_center` | `governed_by` or canon gap | +| `attributed_to_profit_center` | `governed_by` or canon gap | +| `evidenced_by` | `evidenced_by` | + +## Examples + +### Current Single Railiance Fabric + +```yaml +netkingdom: + id: railiance.netkingdom + name: Railiance Netkingdom + king_actor_id: actor.railiance.king +actors: + - id: actor.railiance.king + kind: FabricActor + role: king + name: Railiance King + - id: actor.railiance.primary-lord + kind: FabricActor + role: lord + name: Railiance Primary Lord +fabrics: + - id: fabric.railiance.primary + kind: Fabric + name: Railiance Primary Fabric + netkingdom_id: railiance.netkingdom + lord_actor_id: actor.railiance.primary-lord + parent_fabric_id: null + status: active +``` + +### Future Tenant Subfabric + +```yaml +actors: + - id: actor.coulomb.tenant + kind: FabricActor + role: tenant + name: Coulomb Tenant +fabrics: + - id: subfabric.railiance.tenant.coulomb + kind: Subfabric + name: Coulomb Tenant Subfabric + netkingdom_id: railiance.netkingdom + parent_fabric_id: fabric.railiance.primary + tenant_actor_id: actor.coulomb.tenant + status: planned +``` + +### Cross-Subfabric Utility + +```yaml +edges: + - id: utility:state-hub-http:coulomb-client + from: state-hub.http + to: coulomb.automation-client + type: provides_utility_to + relationship_category: utility + provider: + owner_actor_id: actor.railiance.primary-lord + fabric_id: fabric.railiance.primary + subfabric_id: null + consumer: + owner_actor_id: actor.coulomb.tenant + fabric_id: fabric.railiance.primary + subfabric_id: subfabric.railiance.tenant.coulomb + boundary: + crosses_fabric_boundary: false + crosses_subfabric_boundary: true + utility: + utility_type: coordination_api + contract_id: state-hub.http + payment_schema_id: payment.internal-tenant-access + metering_basis: unknown + business_model: tenant_utility +``` + +## State Hub Import Requirements + +State Hub should materialize at least: + +- export version and schema version; +- netkingdom id; +- fabric/subfabric ids and names; +- actor ids, roles, and names; +- node containment fields; +- node owner actor and owner role; +- ownership resolution state; +- edge relationship category; +- utility provider/consumer ownership context; +- boundary crossing booleans; +- cost/profit center attribution; +- unresolved ownership and containment gaps; +- retained canon metadata and evidence state. + +State Hub must not invent missing ownership or redefine fabric membership. It +may display unresolved gaps and expose filters/views for operator review. diff --git a/workplans/RAIL-FAB-WP-0017-financial-fabric-model-reset.md b/workplans/RAIL-FAB-WP-0017-financial-fabric-model-reset.md index adfb412..1366816 100644 --- a/workplans/RAIL-FAB-WP-0017-financial-fabric-model-reset.md +++ b/workplans/RAIL-FAB-WP-0017-financial-fabric-model-reset.md @@ -4,11 +4,11 @@ type: workplan title: "Financial Fabric Model Reset" domain: railiance repo: railiance-fabric -status: ready +status: active owner: codex topic_slug: railiance created: "2026-05-23" -updated: "2026-05-23" +updated: "2026-05-24" state_hub_workstream_id: "39cc363c-6e2a-46a2-bd19-cee7ff6fc149" --- @@ -54,7 +54,7 @@ work can rebuild the graph from accountability roots and deployment automation. ```task id: RAIL-FAB-WP-0017-T01 -status: todo +status: done priority: high state_hub_task_id: "3d259e3c-5534-4b6a-930a-d085d3db57e4" ``` @@ -80,11 +80,24 @@ Done when: - 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: todo +status: done priority: high state_hub_task_id: "8bbab878-0bff-4302-a925-15a8aceabf9b" ``` @@ -111,6 +124,20 @@ Done when: - 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 @@ -238,4 +265,3 @@ Done when: - 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. -