generated from coulomb/repo-seed
194 lines
5.5 KiB
Markdown
194 lines
5.5 KiB
Markdown
---
|
|
id: RAIL-FAB-WP-0002
|
|
type: workplan
|
|
title: "Railiance Ecosystem Registry Service"
|
|
domain: railiance
|
|
repo: railiance-fabric
|
|
status: completed
|
|
owner: codex
|
|
topic_slug: railiance
|
|
planning_priority: high
|
|
planning_order: 2
|
|
state_hub_workstream_id: "eab084f2-b71e-45c7-ae9c-8528b69f8dec"
|
|
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: done
|
|
priority: high
|
|
state_hub_task_id: "e3c219cf-1b81-4209-9f11-a79a78e1bb52"
|
|
```
|
|
|
|
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: done
|
|
priority: high
|
|
state_hub_task_id: "ef7363a1-afae-4ac2-a977-6d162b3714e6"
|
|
```
|
|
|
|
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: done
|
|
priority: high
|
|
state_hub_task_id: "59323dfe-4702-4b8a-bd60-86d2caea4618"
|
|
```
|
|
|
|
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: done
|
|
priority: high
|
|
state_hub_task_id: "807fcb38-839f-43fd-9f45-ad5cd1f70d8f"
|
|
```
|
|
|
|
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: done
|
|
priority: high
|
|
state_hub_task_id: "f3dd0aba-b83c-4066-b0eb-efb07284a7ac"
|
|
```
|
|
|
|
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: done
|
|
priority: medium
|
|
state_hub_task_id: "95e4e60b-9d32-407e-83d4-c2a532047775"
|
|
```
|
|
|
|
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: done
|
|
priority: high
|
|
state_hub_task_id: "5ef7ccea-fd79-498b-99ce-b6bacb00d46d"
|
|
```
|
|
|
|
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: done
|
|
priority: medium
|
|
state_hub_task_id: "285215e6-6018-44be-abea-56eb79c5d349"
|
|
```
|
|
|
|
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.
|