117 lines
3.5 KiB
Markdown
117 lines
3.5 KiB
Markdown
# 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.
|