generated from coulomb/repo-seed
233 lines
6.8 KiB
Markdown
233 lines
6.8 KiB
Markdown
# Railiance Fabric Intent
|
|
|
|
Date: 2026-05-17
|
|
|
|
## Intent
|
|
|
|
Railiance Fabric exists to make the Railiance ecosystem understandable,
|
|
discoverable, and evolvable as services begin to depend on one another.
|
|
|
|
It models the living fabric of repositories, services, capabilities,
|
|
interfaces, and dependencies so humans and agents can answer questions like:
|
|
|
|
- Which service provides runtime secrets?
|
|
- Which repos consume the NetKingdom IAM Profile?
|
|
- What breaks if the flex-auth decision envelope changes?
|
|
- Which workloads require OpenBao KV, dynamic database credentials, or
|
|
object-storage credential vending?
|
|
- Which dependencies are declared, missing, stale, or boundary-violating?
|
|
|
|
The core idea is simple:
|
|
|
|
```text
|
|
repo -> service -> capability -> interface -> dependency
|
|
```
|
|
|
|
Repos remain the source of truth for what they provide and require. Railiance
|
|
Fabric gives those declarations a shared schema, validation model, graph view,
|
|
and discovery surface.
|
|
|
|
## Why This Exists
|
|
|
|
Railiance is entering the phase where platform services, identity services,
|
|
application workloads, automation, policy engines, storage, and observability
|
|
will interact continuously.
|
|
|
|
Without an explicit ecosystem graph, those interactions become folklore:
|
|
implicit dependencies, stale mental maps, fragile deployment order, and unclear
|
|
ownership when interfaces change.
|
|
|
|
Railiance Fabric turns that implicit web into a reviewable graph:
|
|
|
|
- capabilities are discoverable by name and semantics
|
|
- interfaces are typed and versioned
|
|
- consumers declare their requirements
|
|
- providers declare what they actually offer
|
|
- State Hub can ingest the graph as a read model
|
|
- agents can reason about blast radius, missing providers, and safe sequencing
|
|
|
|
## Responsibility Boundary
|
|
|
|
### Repositories Own Declarations
|
|
|
|
Each repo owns file-backed declarations for its provided capabilities,
|
|
consumed capabilities, services, and interface contracts.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
fabric/capabilities/*.yaml
|
|
fabric/dependencies/*.yaml
|
|
fabric/interfaces/*.yaml
|
|
fabric/services/*.yaml
|
|
```
|
|
|
|
These files are reviewable, versioned with the repo, and changed through normal
|
|
pull-request or workplan flow.
|
|
|
|
### Railiance Fabric Owns The Graph Model
|
|
|
|
Railiance Fabric owns:
|
|
|
|
- declaration schemas
|
|
- validation rules
|
|
- graph construction
|
|
- local inspection tools
|
|
- provider/consumer matching
|
|
- compatibility and drift checks
|
|
- example declarations for core Railiance services
|
|
- export formats for State Hub, docs, and dashboards
|
|
|
|
### State Hub Owns The Read Model
|
|
|
|
State Hub should ingest the ecosystem graph and expose it for coordination,
|
|
but it should not become the primary authoring surface for capability and
|
|
dependency declarations.
|
|
|
|
This keeps ADR-001 intact: formal work and declarations originate in repos;
|
|
the hub reads, visualizes, and coordinates.
|
|
|
|
## First-Class Concepts
|
|
|
|
### Repository
|
|
|
|
A source-controlled project with ownership, workplans, implementation, and
|
|
local declarations.
|
|
|
|
### Service
|
|
|
|
A deployable or callable unit produced by a repository. A repo may produce zero
|
|
or more services.
|
|
|
|
Examples: OpenBao, key-cape, flex-auth API, Topaz deployment, artifact-store.
|
|
|
|
### Capability
|
|
|
|
A stable semantic ability that consumers can depend on without hard-coding the
|
|
current implementation.
|
|
|
|
Examples:
|
|
|
|
- runtime secrets
|
|
- IAM Profile issuer
|
|
- authorization decision service
|
|
- PostgreSQL database service
|
|
- object-storage credential vending
|
|
- scope generation
|
|
|
|
### Interface
|
|
|
|
The concrete contract through which a capability is consumed.
|
|
|
|
Examples:
|
|
|
|
- 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 database dynamic credential role
|
|
|
|
### Dependency
|
|
|
|
A consumer's declared requirement for a capability or interface, including
|
|
version, environment, auth, data classification, criticality, and fallback
|
|
expectations.
|
|
|
|
### Binding
|
|
|
|
A resolved edge between a consumer dependency and a provider capability.
|
|
Bindings may be exact, compatible, degraded, missing, or disputed.
|
|
|
|
## Design Principles
|
|
|
|
- Source of truth lives in repos.
|
|
- Capabilities are stable; implementations may move.
|
|
- Interfaces are typed, versioned, and testable.
|
|
- Dependencies are explicit requirements, not accidental imports.
|
|
- Discovery is graph search, not tribal memory.
|
|
- Validation should catch missing providers before deployment time.
|
|
- Compatibility should be machine-checkable where possible.
|
|
- Human-readable files matter; agents and humans must both be able to inspect
|
|
declarations without a running service.
|
|
- The model must support partial adoption. A repo can begin with one declared
|
|
capability or dependency and mature over time.
|
|
- The graph should reveal boundary violations without pretending to own every
|
|
domain's decisions.
|
|
|
|
## Strategic Role
|
|
|
|
Railiance Fabric sits between repository scoping, State Hub, and the Railiance
|
|
deployment stack.
|
|
|
|
```text
|
|
repo-local declarations
|
|
|
|
|
v
|
|
Railiance Fabric schema and graph tools
|
|
|
|
|
+-- State Hub ingestion and coordination
|
|
+-- documentation and topology maps
|
|
+-- agent planning and blast-radius analysis
|
|
+-- deployment readiness checks
|
|
```
|
|
|
|
It complements:
|
|
|
|
- `repo-scoping`, which explains what a repo is useful for.
|
|
- `the-custodian/state-hub`, which coordinates domains, workstreams, tasks, and
|
|
progress.
|
|
- `railiance-platform`, which deploys shared S3 services such as OpenBao,
|
|
PostgreSQL, Valkey, and object storage.
|
|
- `net-kingdom`, which owns identity, credential, and security architecture.
|
|
- `flex-auth`, which owns authorization policy and decision semantics.
|
|
|
|
## Non-Goals
|
|
|
|
Railiance Fabric is not:
|
|
|
|
- a deployment orchestrator
|
|
- a replacement for State Hub
|
|
- a replacement for SCOPE.md
|
|
- a service mesh
|
|
- a CMDB that must manually mirror everything
|
|
- an authorization engine
|
|
- a secret manager
|
|
- a package registry
|
|
|
|
It may inform those systems, but its job is the ecosystem graph and declaration
|
|
model.
|
|
|
|
## Early Questions
|
|
|
|
- What is the smallest declaration schema that is useful without becoming
|
|
ceremony?
|
|
- Which capability and interface types must exist on day one?
|
|
- How should provider/consumer matching handle environment, version, auth,
|
|
tenant, and data-class constraints?
|
|
- Which graph checks are advisory, and which should block deployment?
|
|
- How does State Hub ingest the graph without becoming the authoring source?
|
|
- How do we represent capabilities that are planned but not deployed yet?
|
|
|
|
## Maturity Target
|
|
|
|
A mature Railiance Fabric should let a human or agent ask:
|
|
|
|
```text
|
|
Show all consumers of OpenBao.
|
|
Show missing providers for production Railiance.
|
|
Show every service that depends on NetKingdom identity claims.
|
|
Show all interfaces crossing from S3 platform services into S5 applications.
|
|
Show blast radius for changing flex-auth decision envelope v1.
|
|
Show runtime readiness for tenant:coulomb onboarding.
|
|
```
|
|
|
|
and receive source-linked, repo-owned answers.
|
|
|