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.

Second-wave projection also retains:

• rail contract version and base/derived composition kind
• a derived rail's base_rail and compatible base contract
• rail and package readiness state
• binding readiness, contract version, and evidence references

Topology remains distinct from readiness. A relation can be declared without being installed, verified, or production-approved.

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
• base_rail from a derived rail 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.