railiance-fabric/docs/financial-fabric-vnext-contract.md

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:

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

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.

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.

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: []

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.

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.

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.

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.

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:

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:

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.

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

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

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

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.