generated from coulomb/repo-seed
320 lines
8.5 KiB
Markdown
320 lines
8.5 KiB
Markdown
---
|
|
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.
|