railiance-fabric/workplans/RAIL-FAB-WP-0001-ecosystem-graph-model.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, state_hub_workstream_id, created, updated

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	state_hub_workstream_id	created	updated
RAIL-FAB-WP-0001	workplan	Railiance Ecosystem Graph Model	railiance	railiance-fabric	completed	codex	railiance	high	1	bd190990-8e68-49a3-9ce4-0ba89103ea54	2026-05-17	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:

fabric/
  services/*.yaml
  capabilities/*.yaml
  interfaces/*.yaml
  dependencies/*.yaml

Suggested edge model:

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

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

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

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

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

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

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

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

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.