Establish Railiance Fabric graph model

workplans/RAIL-FAB-WP-0002-ecosystem-registry-service.md

@@ -0,0 +1,184 @@
+---
+id: RAIL-FAB-WP-0002
+type: workplan
+title: "Railiance Ecosystem Registry Service"
+domain: railiance
+repo: railiance-fabric
+status: proposed
+owner: codex
+topic_slug: railiance
+planning_priority: high
+planning_order: 2
+created: "2026-05-17"
+updated: "2026-05-17"
+---
+
+# RAIL-FAB-WP-0002 - Railiance Ecosystem Registry Service
+
+## Goal
+
+Create the first service interface for registering repositories and interacting
+with the Railiance ecosystem model across repos.
+
+The service should make Fabric declarations queryable without requiring every
+agent or dashboard to clone every repo and run the local CLI. It should remain
+an indexed read model over repo-owned declarations, not a central editor for
+those declarations.
+
+## Context
+
+RAIL-FAB-WP-0001 created the repo-owned graph declaration model, validator,
+query CLI, and State Hub export contract.
+
+The next useful step is a service that can:
+
+- register participating repos
+- ingest validated graph snapshots by repo and commit
+- expose providers, consumers, unresolved dependencies, dependency paths, and
+  blast-radius queries over the combined ecosystem graph
+- attach supporting artifacts such as CycloneDX SBOMs, OpenAPI contracts,
+  AsyncAPI contracts, and Score workload intent
+- project graph data to State Hub and, later, Backstage or xRegistry-compatible
+  views
+
+## Direction
+
+Use `docs/ecosystem-registry-service.md` as the design baseline.
+
+The closest external comparison point is CNCF xRegistry because it defines an
+extensible metadata registry model with document/API views, versioned resources,
+filtering, import/export, and endpoint/schema/message extensions. Railiance
+should keep an xRegistry-compatible projection path, while preserving the
+Fabric graph model as the repo-native source of truth.
+
+## Scope
+
+In scope:
+
+- define the registry service API and storage model
+- implement repository registration
+- implement snapshot ingestion for `FabricGraphExport`
+- reuse the existing Fabric loader, validator, graph builder, and query logic
+- store validation results per repo and commit
+- expose initial HTTP query endpoints matching current CLI queries
+- expose State Hub export data from the latest accepted snapshots
+- support artifact attachment metadata for OpenAPI, AsyncAPI, and CycloneDX
+- document Backstage and xRegistry projection strategy
+
+Out of scope:
+
+- editing repo-owned `fabric/` declarations through the service
+- provisioning or binding live infrastructure
+- replacing State Hub planning, task, progress, or workplan state
+- building a full developer portal
+- runtime service mesh discovery
+- mandatory Score adoption
+
+## Tasks
+
+### T01 - Service API And Storage Design
+
+```task
+id: RAIL-FAB-WP-0002-T01
+status: proposed
+priority: high
+```
+
+Define the API surface, storage tables, validation semantics, and snapshot
+replacement rules.
+
+Done when the repo contains an implementation-ready service design that
+identifies request/response shapes and storage ownership.
+
+### T02 - Service Scaffold
+
+```task
+id: RAIL-FAB-WP-0002-T02
+status: proposed
+priority: high
+```
+
+Create a lightweight HTTP service that reuses the existing Python loader,
+validator, graph builder, and export model.
+
+Done when the service can start locally and expose a health endpoint.
+
+### T03 - Repository Registration
+
+```task
+id: RAIL-FAB-WP-0002-T03
+status: proposed
+priority: high
+```
+
+Add endpoints and storage for repository slug, repo URL, default branch,
+optional State Hub repo id, and ingest configuration.
+
+Done when repos can be registered, listed, and fetched by slug.
+
+### T04 - Snapshot Ingestion
+
+```task
+id: RAIL-FAB-WP-0002-T04
+status: proposed
+priority: high
+```
+
+Add atomic ingestion for `FabricGraphExport` payloads keyed by repo and commit.
+
+Done when a valid export is accepted, invalid exports are rejected with useful
+errors, and the latest accepted snapshot is queryable.
+
+### T05 - Ecosystem Query Endpoints
+
+```task
+id: RAIL-FAB-WP-0002-T05
+status: proposed
+priority: high
+```
+
+Expose providers, consumers, unresolved dependencies, dependency paths, and
+blast-radius queries over the latest accepted snapshots.
+
+Done when HTTP responses match the local CLI answers for the same graph.
+
+### T06 - Artifact Attachment
+
+```task
+id: RAIL-FAB-WP-0002-T06
+status: proposed
+priority: medium
+```
+
+Support artifact metadata for CycloneDX SBOMs, OpenAPI contracts, AsyncAPI
+contracts, and Score workload files.
+
+Done when artifacts can be linked to repos, services, or interfaces and surfaced
+in graph node details.
+
+### T07 - State Hub Export
+
+```task
+id: RAIL-FAB-WP-0002-T07
+status: proposed
+priority: high
+```
+
+Expose State Hub export data from the registry's latest accepted snapshots.
+
+Done when State Hub can fetch the same graph shape documented in
+`docs/state-hub-integration.md`.
+
+### T08 - Projection Strategy
+
+```task
+id: RAIL-FAB-WP-0002-T08
+status: proposed
+priority: medium
+```
+
+Document and, if small enough, prototype Backstage and xRegistry projections.
+
+Done when it is clear which Fabric nodes map to Backstage entities and which
+parts of the registry can be exposed through xRegistry-style groups, resources,
+and versions.