generated from coulomb/repo-seed
494 lines
14 KiB
Markdown
494 lines
14 KiB
Markdown
# 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.
|