generated from coulomb/repo-seed
Establish Railiance Fabric graph model
This commit is contained in:
319
workplans/RAIL-FAB-WP-0001-ecosystem-graph-model.md
Normal file
319
workplans/RAIL-FAB-WP-0001-ecosystem-graph-model.md
Normal file
@@ -0,0 +1,319 @@
|
||||
---
|
||||
id: RAIL-FAB-WP-0001
|
||||
type: workplan
|
||||
title: "Railiance Ecosystem Graph Model"
|
||||
domain: railiance
|
||||
repo: railiance-fabric
|
||||
status: completed
|
||||
owner: codex
|
||||
topic_slug: railiance
|
||||
planning_priority: high
|
||||
planning_order: 1
|
||||
state_hub_workstream_id: "bd190990-8e68-49a3-9ce4-0ba89103ea54"
|
||||
created: "2026-05-17"
|
||||
updated: "2026-05-17"
|
||||
---
|
||||
|
||||
# RAIL-FAB-WP-0001 - Railiance Ecosystem Graph Model
|
||||
|
||||
## Goal
|
||||
|
||||
Define and implement the first useful version of the Railiance ecosystem
|
||||
graph: a repo-owned declaration model for services, capabilities, interfaces,
|
||||
and dependencies, plus tooling to validate, inspect, and export that graph.
|
||||
|
||||
The first outcome should be small but real: Railiance can declare that
|
||||
OpenBao provides runtime secrets, NetKingdom provides identity/security
|
||||
architecture, flex-auth provides authorization decisions, CNPG provides
|
||||
PostgreSQL, and consumers can declare the exact capability/interface
|
||||
requirements they rely on.
|
||||
|
||||
## Context
|
||||
|
||||
Railiance is moving from independent service setup into a connected ecosystem.
|
||||
Platform services, identity, authorization, object storage, app workloads,
|
||||
automation, and observability are starting to interact.
|
||||
|
||||
The current risk is that dependencies remain implicit: in docs, deployment
|
||||
scripts, assumptions, and agent memory. That makes blast radius hard to see and
|
||||
capability discovery fragile.
|
||||
|
||||
This workplan creates the foundation for a flexible ecosystem graph where:
|
||||
|
||||
- repos declare what they provide and consume
|
||||
- capabilities are stable semantic contracts
|
||||
- interfaces describe concrete integration surfaces
|
||||
- dependencies capture consumer requirements
|
||||
- bindings connect consumers to providers
|
||||
- State Hub can ingest the result as a read model
|
||||
|
||||
## Scope
|
||||
|
||||
In scope:
|
||||
|
||||
- define vocabulary for repo, service, capability, interface, dependency, and
|
||||
binding
|
||||
- define YAML schemas for repo-owned declarations
|
||||
- create examples for current Railiance services and cross-domain integrations
|
||||
- implement a local graph loader and validator
|
||||
- implement basic discovery queries and graph export
|
||||
- define State Hub ingestion shape without making State Hub the authoring
|
||||
surface
|
||||
- document adoption guidance for other repos
|
||||
|
||||
Out of scope:
|
||||
|
||||
- replacing State Hub workstream/task/capability catalog ownership
|
||||
- deployment orchestration or GitOps
|
||||
- service mesh runtime traffic discovery
|
||||
- enforcing production rollout gates before the model is proven
|
||||
- complete static code analysis across all repos
|
||||
|
||||
## Initial Model
|
||||
|
||||
Suggested declaration layout inside each participating repo:
|
||||
|
||||
```text
|
||||
fabric/
|
||||
services/*.yaml
|
||||
capabilities/*.yaml
|
||||
interfaces/*.yaml
|
||||
dependencies/*.yaml
|
||||
```
|
||||
|
||||
Suggested edge model:
|
||||
|
||||
```text
|
||||
Repository
|
||||
produces Service
|
||||
provides Capability
|
||||
exposes Interface
|
||||
consumes Dependency
|
||||
|
||||
Dependency
|
||||
requires Capability
|
||||
optionally constrains Interface, version, environment, auth, tenant,
|
||||
data_class, criticality, and fallback
|
||||
|
||||
Binding
|
||||
resolves Dependency -> Capability/Interface
|
||||
```
|
||||
|
||||
## Tasks
|
||||
|
||||
### T01 - Intent And Vocabulary Baseline
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "7a74b4cf-6e0e-468c-8426-7dd85c027a21"
|
||||
```
|
||||
|
||||
Create `INTENT.md` and establish the initial vocabulary: repository, service,
|
||||
capability, interface, dependency, and binding.
|
||||
|
||||
Done when the repo has a clear intent document that distinguishes repo-owned
|
||||
declarations from State Hub's read-model role.
|
||||
|
||||
### T02 - Declaration Schema Design
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "eb4be5b3-7440-43ce-8af3-8da371cab8a5"
|
||||
```
|
||||
|
||||
Define the first YAML schema set:
|
||||
|
||||
- `ServiceDeclaration`
|
||||
- `CapabilityDeclaration`
|
||||
- `InterfaceDeclaration`
|
||||
- `DependencyDeclaration`
|
||||
- `BindingOverride` or `BindingAssertion`
|
||||
|
||||
Include fields for:
|
||||
|
||||
- id, name, owner, repo, domain
|
||||
- lifecycle status: planned, active, deprecated, retired
|
||||
- environment: dev, staging, prod, all
|
||||
- interface type and version
|
||||
- auth method
|
||||
- data classification
|
||||
- criticality
|
||||
- compatibility constraints
|
||||
- source links
|
||||
|
||||
Done when schemas are documented and have example valid/invalid fixtures.
|
||||
|
||||
### T03 - Core Capability Type Catalog
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T03
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "070098b9-53b6-42d2-a041-e98b5c5ddcc7"
|
||||
```
|
||||
|
||||
Define the first catalog of capability and interface types.
|
||||
|
||||
Initial capabilities:
|
||||
|
||||
- runtime secrets
|
||||
- IAM Profile issuer
|
||||
- authorization decision service
|
||||
- PostgreSQL database service
|
||||
- Redis-compatible cache
|
||||
- object storage
|
||||
- object-storage credential vending
|
||||
- audit/event sink
|
||||
- scope generation
|
||||
|
||||
Initial interface types:
|
||||
|
||||
- HTTP API
|
||||
- OIDC discovery
|
||||
- Kubernetes Secret
|
||||
- Kubernetes CRD
|
||||
- Helm release
|
||||
- CLI
|
||||
- database connection
|
||||
- object-storage bucket
|
||||
- event stream
|
||||
- policy package
|
||||
- OpenBao KV v2 mount
|
||||
- OpenBao dynamic credential role
|
||||
|
||||
Done when the type catalog is explicit enough for examples to avoid ad hoc
|
||||
strings.
|
||||
|
||||
### T04 - Example Declarations For Core Services
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T04
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "cfbc8d6e-58a3-4359-baf4-369d3357f6f5"
|
||||
```
|
||||
|
||||
Create seed declarations for known Railiance ecosystem capabilities:
|
||||
|
||||
- OpenBao as `runtime-secrets`
|
||||
- NetKingdom IAM Profile as identity contract
|
||||
- key-cape as lightweight IAM Profile implementation
|
||||
- flex-auth as authorization decision control plane
|
||||
- Topaz as delegated PDP runtime
|
||||
- CloudNativePG as PostgreSQL service
|
||||
- Valkey as Redis-compatible cache
|
||||
- object storage and STS credential vending as planned capabilities
|
||||
- State Hub as coordination/read-model service
|
||||
- repo-scoping as scope-generation provider
|
||||
|
||||
Done when the first graph has real provider nodes and at least a few consumer
|
||||
requirements.
|
||||
|
||||
### T05 - Graph Loader And Validator
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T05
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "59e46f73-04ba-464c-acbb-767169525d43"
|
||||
```
|
||||
|
||||
Implement a local tool that loads declarations from one or more repo roots,
|
||||
validates schema conformance, and builds an in-memory graph.
|
||||
|
||||
Validation should catch:
|
||||
|
||||
- duplicate ids
|
||||
- missing provider capability for required dependencies
|
||||
- unknown interface or capability types
|
||||
- incompatible environment/status constraints
|
||||
- missing source links for active production dependencies
|
||||
- circular dependency warnings where relevant
|
||||
|
||||
Done when `railiance-fabric validate <repo...>` can run against the seed
|
||||
examples and produce useful diagnostics.
|
||||
|
||||
### T06 - Discovery Queries And Exports
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T06
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "ee50217c-8cdc-4c18-bb15-9fed35599d6c"
|
||||
```
|
||||
|
||||
Add initial query commands:
|
||||
|
||||
- list providers for a capability
|
||||
- list consumers of a capability/interface
|
||||
- show dependency path for a service
|
||||
- show missing or unresolved dependencies
|
||||
- show blast radius for an interface version change
|
||||
- export graph as JSON
|
||||
- export graph as Mermaid for documentation
|
||||
|
||||
Done when a human or agent can answer "who consumes OpenBao?" and "what
|
||||
capabilities are missing?" from local files.
|
||||
|
||||
### T07 - State Hub Integration Contract
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T07
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "32587d7a-565d-4457-a7ed-61e6f16f781a"
|
||||
```
|
||||
|
||||
Define how State Hub ingests Railiance Fabric graph exports.
|
||||
|
||||
The integration contract must preserve the source-of-truth boundary:
|
||||
|
||||
- repo declarations are authoritative
|
||||
- Railiance Fabric validates and exports
|
||||
- State Hub stores or displays the read model
|
||||
- State Hub links graph nodes to topics, repos, workstreams, tasks, and
|
||||
progress events where useful
|
||||
|
||||
Done when there is a documented export shape and a proposed ingestion path for
|
||||
State Hub.
|
||||
|
||||
### T08 - Adoption Guide And First Repo Rollout
|
||||
|
||||
```task
|
||||
id: RAIL-FAB-WP-0001-T08
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "c13b29a7-053c-4f16-ab71-75fba966897e"
|
||||
```
|
||||
|
||||
Write an adoption guide and apply the first declarations to a small set of
|
||||
repos.
|
||||
|
||||
Suggested first rollout:
|
||||
|
||||
- `railiance-platform`
|
||||
- `net-kingdom`
|
||||
- `flex-auth`
|
||||
- `artifact-store`
|
||||
- `repo-scoping`
|
||||
- `the-custodian/state-hub`
|
||||
|
||||
Done when another repo can add declarations without reading Railiance Fabric
|
||||
source code.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- `INTENT.md` clearly defines why Railiance Fabric exists.
|
||||
- The repo contains a documented schema for services, capabilities,
|
||||
interfaces, dependencies, and bindings.
|
||||
- Seed declarations represent at least OpenBao, NetKingdom IAM, flex-auth,
|
||||
CNPG, object storage, and State Hub.
|
||||
- A local validation command can detect missing providers and type mistakes.
|
||||
- A local query can list providers and consumers for a capability.
|
||||
- A graph export can be consumed by State Hub without making State Hub the
|
||||
authoring surface.
|
||||
- Adoption guidance exists for adding declarations to other repos.
|
||||
184
workplans/RAIL-FAB-WP-0002-ecosystem-registry-service.md
Normal file
184
workplans/RAIL-FAB-WP-0002-ecosystem-registry-service.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user