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

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.