feat: allow provider-delegated reefs with no rail

Object-storage reefs omit primary_rail and hosted_rails. Scaleway
operates S3; reef-storage only names the boundary. Finish
RMASTER-WP-0022.
This commit is contained in:
codex 2026-08-14 15:53:30 +02:00
parent 82b7b7295d
commit 654bbe891b
8 changed files with 67 additions and 32 deletions

View file

@ -10,12 +10,16 @@ boundary.
A reef is the place where:
- infrastructure becomes a named operational reality,
- rails are installed or made available,
- managed workloads are bound,
- rails may be installed or made available,
- managed workloads may be bound,
- a provider-delegated capability may be named as a substrate,
- and operators interact with a concrete environment.
More concretely, a reef represents **compute resources organized for a defined
purpose**.
A reef is **one durable operational boundary organized for a defined
purpose**. That purpose is often compute. It can also be a
provider-operated capability we consume as a unit — for example S3
object storage at Scaleway (`reef-storage`). In that case there is **no
rail**: we do not take care of how the capability is provided.
The substrate may be:
@ -24,10 +28,11 @@ The substrate may be:
- a workstation,
- an edge site,
- a lab substrate,
- or a small fleet treated as one unit.
- a small fleet treated as one unit,
- or a provider-delegated service boundary (object storage, later others).
The important point is not the shape of the hardware. The important point is
that the compute resources form one recognizable operational boundary.
that the boundary is one recognizable operational reality.
## Why `reef-*` Instead Of `host-*`
@ -41,8 +46,9 @@ Railiance substrates are not always just hosts. They may also be:
- grouped node fleets,
- or mixed environments with both machines and control surfaces.
`reef-*` is useful because it names the substrate reality that rails attach to,
not merely the hardware object underneath it.
`reef-*` is useful because it names the substrate reality — the place
rails may attach, or the place a delegated capability is consumed — not
merely the hardware object underneath it.
## Core Responsibility Of A Reef
@ -51,8 +57,10 @@ A reef repo should answer:
- What is this substrate called?
- What components belong to it?
- What access paths and operator assumptions apply?
- Which rails exist here?
- Which `rapp`s are allowed or deployed here?
- Which rails exist here, if any?
- Which `rapp`s are allowed or deployed here, if any?
- For a provider-delegated reef: which provider, region, and non-secret
attributes (endpoint, bucket, …) define the boundary?
- Which overlays, exceptions, and evidence are specific to this substrate?
It should also make the substrate purpose explicit, so the existence of the

View file

@ -110,8 +110,11 @@ Schema: [`schemas/reef.schema.json`](../schemas/reef.schema.json)
`bound_rapps` is a derived projection of every rapp whose `bound_reefs`
lists this reef. It is not a hand-maintained registry. A reef may omit the
field; if it keeps the field, the validator requires an exact match against
the projection. `primary_rail` must appear in `hosted_rails`. Hosting a rail
or binding a rapp is topology, not readiness — see ADR-0006.
the projection. A compute reef that hosts rails must set `primary_rail`
and list it in `hosted_rails`. A provider-delegated reef (for example
`reef-storage`, `substrate_kind: object-storage`) omits both: there is no
execution contract to host. Hosting a rail or binding a rapp is topology,
not readiness — see ADR-0006.
## Required Boundary Rules