feat: version state hub fabric export contract

docs/state-hub-integration.md

@@ -1,26 +1,27 @@
 # 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.
+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 |
 |-------|------|--------------|
-| 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 |
+| 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
-repo-local fabric/*.yaml
+accountability roots + durable deployment evidence + repo evidence
         |
         v
-railiance-fabric validate/export
+railiance-fabric scan/validate/export
         |
         v
 State Hub graph read model
@@ -31,7 +32,7 @@ dashboard, search, planning, progress links
 
 ## Export Shape
 
-The CLI emits `FabricGraphExport` JSON:
+The CLI and registry emit `FabricGraphExport` JSON:
 
 ```bash
 railiance-fabric export --format json
@@ -39,7 +40,16 @@ railiance-fabric export --format json
 
 Schema: `schemas/state-hub-export.schema.yaml`
 
-Top-level shape:
+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
@@ -74,6 +84,57 @@ Edge fields:
 | `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`.
+
 ## Proposed State Hub Read Model
 
 Add a State Hub ingestion endpoint or job that stores the latest graph export
@@ -126,9 +187,20 @@ fabric_graph_edges
   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.
+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
 
@@ -140,7 +212,7 @@ State Hub should enrich graph nodes by matching:
 - 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.
+Fabric export or source evidence.
 
 ## Ingestion Rules
 
@@ -150,7 +222,22 @@ repo-owned declaration files.
    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.
+   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