railiance-fabric/docs/rail-rapp-reef-adaptation.md

# Rail Rapp Reef Adaptation

Date: 2026-07-26

## 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
- persist repo-family metadata in the registry and repository projections
- 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.

## Registry Metadata Path

The registry now carries the first repo-family-aware metadata fields on
repository records:

- `repo_family`
- `ownership_repo`
- `primary_rail`
- `supported_rails`
- `substrate_kind`

This metadata is available through repository registration, manifest sync, and
repository projections such as the graph explorer's synthesized repository
nodes.

The registry now also retains the local checkout `path` used during onboarding.
That lets Fabric reopen the conventional repo-local `rail`, `rapp`, and `reef`
files when it needs to project first-wave relation edges.

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

## Relation Projection Path

Fabric now projects the minimum first-wave repo-family relations from
repo-local files:

- `governed_by` from `declarations/rail.yaml`, `declarations/rapp.yaml`, and
  `declarations/reef.yaml`
- `supports_rail` from `declarations/rapp.yaml`
- `hosts_rail` from `bindings/rails.yaml` with a fallback to the reef
  declaration
- `binds_rapp` from `bindings/rapps.yaml` with a fallback to the reef
  declaration

This keeps the relation path anchored in reviewed repo-local files rather than
guessing solely from registry metadata.

## What Is Still Missing

The following are still not done:

- validator rules for repo-family-specific declaration completeness
- richer graph queries that answer reef/workload placement beyond the first
  projected repo edges
- State Hub read-model fields that surface repo family directly in generated
  repo briefs or inventory views
- deeper runtime placement semantics than the first repo-level topology

## Outcome

Fabric can now move from "the new repo families exist only in architecture
docs" to "the registry can project the first repo-family topology from
repo-local evidence" without overcommitting to a premature graph redesign.