docs: audit financial fabric vnext contract

2026-05-24 00:42:39 +02:00
parent 0874446994
commit 39762551c0
3 changed files with 945 additions and 5 deletions
--- a/docs/financial-fabric-model-audit.md
+++ 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.
--- a/docs/financial-fabric-vnext-contract.md
+++ 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.
--- 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.
-