railiance-fabric/docs/state-hub-integration.md

State Hub Integration Contract

Railiance Fabric is the discovery, validation, and versioning layer for the Railiance infrastructure-responsibility graph. State Hub should ingest Fabric outputs as a read model for coordination, search, dashboards, and planning. It should not become the primary authoring surface for Fabric topology, ownership, fabric membership, or cross-boundary utility relations.

Source-Of-Truth Boundary

Layer	Owns	Does Not Own
Deployment/accountability roots	Durable evidence of infrastructure, deployment, ownership, utility, and payment responsibility	State Hub task state
Participating repos	Self-description evidence such as code, manifests, API contracts, package metadata, and legacy fabric/ declarations	All external deployment/fabric relations
Railiance Fabric	Schemas, discovery, validation, graph construction, accepted snapshots, exports	State Hub tasks/progress/decisions
State Hub	Read-model storage, links to repos/workstreams/tasks/progress, dashboard/search views	Editing Fabric topology or inventing ownership

The flow is:

accountability roots + durable deployment evidence + repo evidence
        |
        v
railiance-fabric scan/validate/export
        |
        v
State Hub graph read model
        |
        v
dashboard, search, planning, progress links

Export Shape

The CLI and registry emit FabricGraphExport JSON:

railiance-fabric export --format json
railiance-fabric export --format financial

Schema: schemas/state-hub-export.schema.yaml

The schema now accepts two export families:

• railiance.fabric/v1alpha1: legacy declaration-centered graph export.
• railiance.fabric/v1alpha2 with schema_version: financial-fabric-v1: financial Fabric graph export.

Legacy v1alpha1 Shape

The legacy top-level shape remains supported for compatibility with STATE-WP-0050:

apiVersion: railiance.fabric/v1alpha1
kind: FabricGraphExport
nodes: []
edges: []

Node fields:

Field	Meaning
id	Stable graph id from declaration metadata.
kind	Declaration kind: service, capability, interface, dependency, or binding.
name	Human-readable name.
repo	Owning repo slug.
domain	Owning domain slug.
lifecycle	Declaration lifecycle.
canon_category	Canon-aligned entity category when known.
canon_anchor	Canon surface that owns the selected category.
mapping_fit	Mapping confidence bucket: direct, partial, conflict, gap, or unknown.
evidence_state	Evidence state for the node claim: observed, declared, inferred, proposed, or gap.

Edge fields:

Field	Meaning
from	Source node id.
to	Target node id.
type	Fabric relationship type, such as provides, exposes, available_via, consumes, binds:exact, or uses_interface.
canonical_type	Canon-aligned relationship family when known, such as exposes, depends_on, deploys, or flows_to.
display_only	true when the edge is a visualization/layout relationship rather than a canonical graph claim.
evidence_state	Evidence state for the claim: observed, declared, inferred, proposed, or gap.

Financial v1alpha2 Shape

The financial Fabric export adds first-class responsibility and value semantics:

apiVersion: railiance.fabric/v1alpha2
kind: FabricGraphExport
schema_version: financial-fabric-v1
netkingdom:
  id: railiance.netkingdom
  king_actor_id: actor.railiance.king
actors: []
fabrics: []
nodes: []
edges: []
unresolved: []

Additional top-level sections:

Field	Meaning
schema_version	Financial Fabric export schema identity.
netkingdom	Root responsibility context and king actor.
actors	King, lord, tenant, operator, and steward actors.
fabrics	Fabric and subfabric boundaries.
unresolved	Ownership, containment, or import gaps to display for review.

Additional node fields:

Field	Meaning
containment	Netkingdom, fabric, optional subfabric, environment, and optional deployment scenario.
ownership	Owner actor, owner role, and ownership resolution state.
accounting	Optional cost/profit center and allocation metadata.
evidence	Evidence state, review state, confidence, and evidence references.

Additional edge fields:

Field	Meaning
relationship_category	containment, ownership, technical, utility, accounting, or evidence.
provider / consumer	Owner and boundary context for utility edges.
boundary	Whether the edge crosses fabric or subfabric boundaries.
utility	Utility type, contract, payment schema, metering basis, and business model.
accounting	Optional cost/profit attribution for the relationship.
evidence	Evidence state, review state, confidence, and evidence references.

Example payload: examples/exports/financial-fabric-v1.json.

Operator Refresh During Reset

For the current reset, operators should produce both export families:

railiance-fabric validate .
railiance-fabric export --format json
railiance-fabric export --format financial

The json export remains the compatibility payload for State Hub graph views implemented by STATE-WP-0050. The financial export is the vNext contract artifact for STATE-WP-0051 and should be reviewed whenever the baseline, discovery inputs, ownership model, or registry materialization changes.

After workplan file changes, refresh State Hub's file-backed index from the State Hub repo:

make fix-consistency REPO=railiance-fabric

Graph import and workplan consistency are separate. The consistency command does not author Fabric graph topology; it only keeps State Hub's workplan cache aligned with repo files.

Proposed State Hub Read Model

Add a State Hub ingestion endpoint or job that stores the latest graph export per source repo:

POST /fabric/graph-exports

Suggested payload:

{
  "repo_slug": "railiance-fabric",
  "commit": "<git-sha>",
  "generated_at": "2026-05-17T00:00:00Z",
  "graph": {
    "apiVersion": "railiance.fabric/v1alpha1",
    "kind": "FabricGraphExport",
    "nodes": [],
    "edges": []
  }
}

Suggested storage:

fabric_graph_exports
  id
  repo_id
  commit
  generated_at
  graph_json
  created_at

fabric_graph_nodes
  export_id
  graph_id
  kind
  name
  repo_slug
  domain_slug
  lifecycle

fabric_graph_edges
  export_id
  from_graph_id
  to_graph_id
  edge_type

The STATE-WP-0050 implementation already stores a v1alpha1 read model. The STATE-WP-0051 follow-up should extend that storage with:

• import/export schema version;
• netkingdom id;
• fabric and subfabric ids;
• actor ids and roles;
• node containment;
• node owner actor, owner role, and ownership resolution;
• edge relationship category;
• utility provider/consumer ownership context;
• fabric/subfabric boundary crossing flags;
• node and edge accounting attribution;
• unresolved ownership or containment gaps.

Linking To Existing State Hub Entities

State Hub should enrich graph nodes by matching:

• node.repo -> managed_repos.slug
• node.domain -> domains.slug
• workplan source links -> workstreams.slug or file-backed workplan index
• progress events -> repo_id and related workstream/task when available

These links are annotations on the read model. They should never overwrite the Fabric export or source evidence.

Ingestion Rules

1. Reject exports that fail schemas/state-hub-export.schema.yaml.
2. Record the source repo and commit for every accepted export.
3. Replace the previous latest export for the same repo only after the new export validates.
4. Preserve historical exports long enough to compare graph drift.
5. Surface validation errors as State Hub progress events or human-review tasks, but do not auto-edit Fabric topology, ownership, or source evidence.
6. For v1alpha2, preserve unresolved ownership/containment gaps rather than inventing State Hub-owned values.
7. For v1alpha2, expose cost/profit center fields as accounting views, not as fabric membership changes.

Current State Hub Limitations

As of STATE-WP-0050, State Hub imports the legacy v1alpha1 export as a read model. It does not yet materialize the v1alpha2 financial Fabric fields.

Until STATE-WP-0051 is implemented, a v1alpha2 export is a contract and registry capability in railiance-fabric, not a fully queryable State Hub read model. Operators should keep importing the current v1alpha1 export for existing dashboard/query behavior and use v1alpha2 payloads for contract verification and follow-on implementation.

Initial Dashboard Queries

State Hub should be able to answer:

• providers for a capability type
• consumers of a capability or interface
• unresolved dependencies
• blast radius for an interface id or type
• graph nodes by repo/domain/lifecycle

These are the same query families exposed locally by Railiance Fabric. The hub read model should match local answers for the same export.