--- 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 ` 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.