railiance-fabric/docs/adoption-guide.md

# Adoption Guide

This guide shows another repo how to adopt Railiance Fabric declarations without
reading Railiance Fabric source code.

## 1. Add The Directory Layout

Create the declaration directories in your repo:

```text
fabric/
  services/
  capabilities/
  interfaces/
  dependencies/
  bindings/
```

Start with only the files you need. A repo can adopt Fabric with one service
and one capability, or with one dependency on a capability provided elsewhere.

## 2. Declare A Service

Create `fabric/services/<repo>-<service>.yaml`:

```yaml
apiVersion: railiance.fabric/v1alpha1
kind: ServiceDeclaration
metadata:
  id: your-repo.your-service
  name: Your Service
  owner: your-repo
  repo: your-repo
  domain: railiance
  source_links:
    - label: Service README
      path: README.md
spec:
  lifecycle: active
  environments: [dev, staging, prod]
  description: What this service does.
  service_type: app-service
  provides_capabilities: []
  exposes_interfaces: []
```

Use lower-case dotted IDs. Prefer IDs that begin with the owning repo slug.

## 3. Declare A Provided Capability

Create `fabric/capabilities/<repo>-<capability>.yaml`:

```yaml
apiVersion: railiance.fabric/v1alpha1
kind: CapabilityDeclaration
metadata:
  id: your-repo.your-service.runtime-secrets
  name: Runtime secrets
  owner: your-repo
  repo: your-repo
  domain: railiance
  source_links:
    - label: Capability docs
      path: docs/runtime-secrets.md
spec:
  lifecycle: active
  environments: [dev, staging, prod]
  description: What this capability provides.
  capability_type: runtime-secrets
  service_id: your-repo.your-service
  interface_ids:
    - your-repo.your-service.kv-v2
  criticality: high
  data_classification: secret
```

Pick `capability_type` from `catalog/capability-types.yaml`.

## 4. Declare An Interface

Create `fabric/interfaces/<repo>-<interface>.yaml`:

```yaml
apiVersion: railiance.fabric/v1alpha1
kind: InterfaceDeclaration
metadata:
  id: your-repo.your-service.http-api
  name: Your Service HTTP API
  owner: your-repo
  repo: your-repo
  domain: railiance
  source_links:
    - label: API docs
      path: docs/api.md
spec:
  lifecycle: active
  environments: [dev, staging, prod]
  description: How consumers call this interface.
  interface_type: http-api
  version: v1
  service_id: your-repo.your-service
  capability_ids:
    - your-repo.your-service.some-capability
  auth:
    method: oidc
  data_classification: internal
```

Pick `interface_type` from `catalog/interface-types.yaml`.

## 5. Declare A Dependency

Create `fabric/dependencies/<repo>-<dependency>.yaml`:

```yaml
apiVersion: railiance.fabric/v1alpha1
kind: DependencyDeclaration
metadata:
  id: your-repo.your-service.needs-runtime-secrets
  name: Runtime secrets dependency
  owner: your-repo
  repo: your-repo
  domain: railiance
  source_links:
    - label: Deployment values
      path: deploy/values.yaml
spec:
  lifecycle: active
  environments: [dev, staging, prod]
  consumer_service_id: your-repo.your-service
  requires:
    capability_type: runtime-secrets
  interface:
    type: openbao-kv-v2-mount
    version_constraint: ">=v1 <v2"
  auth:
    method: kubernetes_service_account
  criticality: high
  data_classification: secret
  fallback:
    mode: none
    description: Service cannot start without runtime secrets.
```

Active production dependencies should include at least one source link.

## 6. Add A Binding Only When Needed

Most bindings can be computed by the graph loader from dependency requirements
and provider capabilities. Add a `BindingAssertion` when you need to pin,
override, dispute, or document a planned provider:

```yaml
apiVersion: railiance.fabric/v1alpha1
kind: BindingAssertion
metadata:
  id: your-repo.your-service.runtime-secrets-to-openbao
  name: Runtime secrets binding
  owner: your-repo
  repo: your-repo
  domain: railiance
spec:
  lifecycle: active
  environments: [dev, staging, prod]
  dependency_id: your-repo.your-service.needs-runtime-secrets
  provider_capability_id: railiance-platform.openbao.runtime-secrets
  provider_interface_id: railiance-platform.openbao.kv-v2
  status: compatible
  rationale: This service uses OpenBao KV v2 for runtime secrets.
```

## 7. Validate Locally

From the Railiance Fabric repo:

```bash
railiance-fabric validate /path/to/your-repo
```

During early bootstrapping:

```bash
PYTHONPATH=. python -m railiance_fabric.cli validate /path/to/your-repo
```

Useful discovery checks:

```bash
railiance-fabric providers runtime-secrets /path/to/your-repo
railiance-fabric consumers runtime-secrets /path/to/your-repo
railiance-fabric unresolved /path/to/your-repo
```

For multi-repo validation, pass multiple roots:

```bash
railiance-fabric validate /path/to/repo-a /path/to/repo-b
```

## 8. Export For State Hub

```bash
railiance-fabric export --format json /path/to/your-repo
```

State Hub should ingest that export as a read model. Do not edit declarations in
State Hub; change them in the owning repo and re-export.