144 lines
4.6 KiB
Markdown
144 lines
4.6 KiB
Markdown
# 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.
|