Establish Railiance Fabric graph model

2026-05-17 19:47:37 +02:00
parent 9c1f4d1381
commit 19f9fddc35
89 changed files with 5007 additions and 2 deletions
--- a/docs/adoption-guide.md
+++ b/docs/adoption-guide.md
@@ -0,0 +1,207 @@
+# 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.