Start rail/rapp/reef fabric adaptation

docs/rail-rapp-reef-adaptation.md

@@ -0,0 +1,100 @@
+# Rail Rapp Reef Adaptation
+
+Date: 2026-07-25
+
+## Purpose
+
+Define the first compatibility-first Fabric conventions for the new
+`rail-*`, `rapp-*`, and `reef-*` repo families without pretending the registry
+or export model is already fully adapted.
+
+This document is intentionally narrower than the framework architecture in
+`railiance-master`. It answers one question:
+
+> What should Fabric accept and publish first so the new repo families can
+> start existing as graph entities?
+
+## Immediate Compatibility Stance
+
+The first adaptation wave is deliberately small:
+
+- onboard the missing current Railiance repos in the seed manifest
+- add the first rail-specific capability type
+- define canonical `service_type` values for future declarations
+- avoid inventing full repo-family metadata or new export relations before the
+  first repos exist
+
+This keeps Fabric aligned with the architecture without forcing a premature
+schema redesign.
+
+## Canonical First-Use Conventions
+
+### `rail-*`
+
+Initial Fabric shape:
+
+- one `ServiceDeclaration` with `spec.service_type: execution-rail`
+- one `CapabilityDeclaration` with
+  `spec.capability_type: workload-execution-contract`
+
+Typical evidence should describe:
+
+- the execution architecture
+- substrate prerequisites
+- rollout modes or workload lifecycle expectations
+- which ownership repo governs the rail
+
+### `rapp-*`
+
+Initial Fabric shape:
+
+- one `ServiceDeclaration` with `spec.service_type: managed-workload-package`
+
+Optional follow-on declarations may later capture runtime dependencies,
+verification interfaces, or artifact evidence, but the first requirement is
+simply to make the package queryable as a distinct ecosystem entity.
+
+### `reef-*`
+
+Initial Fabric shape:
+
+- one `ServiceDeclaration` with `spec.service_type: substrate-boundary`
+
+The first declarations should make the substrate boundary visible before Fabric
+tries to model every machine or placement relation in detail.
+
+## First New Capability Type
+
+Fabric now reserves:
+
+- `workload-execution-contract`
+
+Meaning:
+
+- a stable execution contract that workloads depend on
+- usually published by a `rail-*` repo
+- expected to expose Kubernetes-, rollout-, or runtime-facing interfaces over
+  time
+
+This is intentionally rail-focused. `rapp-*` and `reef-*` can start with
+service-level visibility before they need their own dedicated capability types.
+
+## What Is Still Missing
+
+The following are not done by this adaptation slice:
+
+- repo-level `repo_family` metadata in the registry
+- `ownership_repo`, `supported_rails`, `primary_rail`, or `substrate_kind`
+  registry metadata
+- export relations such as `supports_rail`, `hosts_rail`, `binds_rapp`, or
+  `governed_by`
+- validator rules for repo-family-specific declaration completeness
+
+Those require a second wave after the first real `rail-*`, `rapp-*`, and
+`reef-*` repos exist.
+
+## Outcome
+
+Fabric can now move from "the new repo families exist only in architecture
+docs" to "the registry and declaration guidance are ready for the first repo
+instances" without overcommitting to a premature graph redesign.