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

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:

• export relations such as supports_rail, hosts_rail, binds_rapp, or governed_by
• validator rules for repo-family-specific declaration completeness
• graph queries that resolve placement or governance directly from the new repo-family metadata
• State Hub read-model fields that surface repo family directly in generated repo briefs or inventory views

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.