# State Hub Integration Contract

Railiance Fabric is the authoring and validation layer for ecosystem graph
declarations. 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 services, capabilities, interfaces, dependencies,
or bindings.

## Source-Of-Truth Boundary

| Layer | Owns | Does Not Own |
|-------|------|--------------|
| Participating repos | Declaration files under `fabric/` | Global graph interpretation |
| Railiance Fabric | Schemas, type catalogs, validation, graph construction, exports | State Hub tasks/progress/decisions |
| State Hub | Read-model storage, links to repos/workstreams/tasks/progress, dashboard/search views | Editing Fabric declarations |

The flow is:

```text
repo-local fabric/*.yaml
        |
        v
railiance-fabric validate/export
        |
        v
State Hub graph read model
        |
        v
dashboard, search, planning, progress links
```

## Export Shape

The CLI emits `FabricGraphExport` JSON:

```bash
railiance-fabric export --format json
```

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

Top-level shape:

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

Edge fields:

| Field | Meaning |
|-------|---------|
| `from` | Source node id. |
| `to` | Target node id. |
| `type` | Relationship type, such as `provides`, `exposes`, `available_via`, `consumes`, `binds:exact`, or `uses_interface`. |

## 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 normalized node/edge tables are optional at first. State Hub can begin with
`fabric_graph_exports.graph_json` and materialize node/edge tables once query
needs harden.

## 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
repo-owned declaration files.

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

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