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:

```text
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:

```bash
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`:

```yaml
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:

```yaml
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:

```bash
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:

```bash
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:

```text
POST /fabric/graph-exports
```

Suggested payload:

```json
{
  "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:

```text
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.