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