# 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.