# Reef Substrate Model Date: 2026-07-25 ## Definition A `reef-*` repo is the conceptual home for one durable Railiance substrate boundary. A reef is the place where: - infrastructure becomes a named operational reality, - 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. 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: - a single named server, - a cluster, - a workstation, - an edge site, - a lab substrate, - 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 boundary is one recognizable operational reality. ## Why `reef-*` Instead Of `host-*` `host-*` is too narrow for the intended concept. Railiance substrates are not always just hosts. They may also be: - operator workstations, - Kubernetes substrates, - serverless-capable execution surfaces, - grouped node fleets, - or mixed environments with both machines and control surfaces. `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 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, 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 reef is justified by its role rather than by a hostname alone. It is therefore an environment or substrate boundary repo, not a generic infrastructure logic repo. ## What A Reef Owns A reef repo may own: - substrate identity and metadata - topology and membership description - rail bindings for this substrate - `rapp` bindings for this substrate - substrate-specific overlays and values - substrate-specific runbooks - substrate-specific evidence and readiness notes - access-path descriptions such as bridges, kubeconfig routes, or workstation assumptions ## What A Reef Does Not Own A reef repo should not become the place for: - generic OS provisioning logic that belongs in `railiance-infra` - generic cluster runtime logic that belongs in `railiance-cluster` - generic platform-service logic that belongs in `railiance-platform` - generic workload packaging that belongs in a `rapp-*` repo - generic rail semantics that belong in a `rail-*` repo Reefs compose those concerns into a concrete substrate. They do not replace their owning repos. ## Granularity Rules The main risk with reefs is repo explosion through near-duplicate per-machine repos. The default rules below are intended to prevent that. ### Rule 1: One Reef Per Substrate Boundary, Not Per Node By Default If multiple machines form one operational substrate with the same lifecycle, access path, and overlays, prefer one reef. Example: - Prefer `reef-ops-workstations` over one repo per laptop if they are managed as one operator substrate class. ### Rule 2: A Single Machine Gets Its Own Reef Only When It Is The Boundary A single named machine can justify its own reef when it is itself a durable substrate boundary. This is reasonable when the machine has: - unique operational identity, - unique overlays or access paths, - unique binding decisions, - or independent migration and recovery decisions. ### Rule 3: Group Fungible Fleets Do not create one reef per fungible worker, node, or ephemeral instance. Represent those inside one reef's topology instead. ### Rule 4: Prefer Stable Operational Names A reef name should follow the durable substrate identity used by operators. Good examples: - `reef-coulombcore` - `reef-railiance` - `reef-workstation` - `reef-ops-workstations` Avoid names tied only to transient VM ids, cloud instance ids, or incidental hardware details. ### Rule 5: Allow Multi-Rail Reefs Early, Prefer Clearer Separation Later It is acceptable for one reef to host multiple rails when the substrate is experimental, preproduction, prototyping, or otherwise intentionally mixed. For production-grade, enterprise-grade, or premium-security situations, the better default is clearer separation by substrate purpose and a more explicit primary rail per reef unless there is a reviewed reason to mix rails. This is guidance, not a hard prohibition. The point is to keep the substrate model operationally legible as criticality increases. ### Rule 6: Do Not Canonize Transitional Substrate Labels Too Early Railiance may observe loosely planned or historically accumulated compute resources that are still in use but do not yet fit a clean substrate class. Those realities should be described plainly in architecture notes or reef-local documents, but the taxonomy should avoid locking in catchy names before the operational pattern is mature enough to deserve a stable term. ## Guidance For Current Railiance Substrates ### `COULOMBCORE` `reef-coulombcore` is reasonable if COULOMBCORE remains a durable singleton substrate with its own: - access paths, - operational evidence, - rail availability, - and workload binding decisions. It may also serve as the temporary home for older or transitional workloads that have not yet been integrated into newer operating patterns. What should not be decided too early is a permanent taxonomy term for that kind of substrate. Terms such as "associate", "sidecar", or "comet" may be useful exploration language, but they should stay provisional until the pattern repeats and earns a stable place in the framework vocabulary. ### Railiance Home Substrate `reef-railiance` is reasonable when Railiance home servers are expected to share one durable operational substrate boundary, with `Railiance01` as the first current member rather than the permanent repo name anchor. At the current maturity level, it is acceptable for `reef-railiance` to host `rail-kubernetes` and later also `rail-knative` if that is the most pragmatic way to support early workloads across that grouped home substrate. If member servers later diverge enough in lifecycle, access path, or security boundary, reassess whether the grouped reef should split into narrower reefs. ### `WORKSTATION` If there is effectively one operator workstation with unique responsibility, `reef-workstation` is acceptable. If Railiance expects multiple equivalent operator machines, prefer a grouped reef such as `reef-ops-workstations` and model individual machines inside that repo instead of multiplying repos. This class of reef is best understood as edge or operator compute, not as part of the same substrate category as a home server reef. ## Suggested Reef Repo Layout The exact layout can evolve, but a reef repo should have an obvious substrate home structure. ```text reef-/ README.md INTENT.md SCOPE.md substrate/ identity.yaml topology.yaml bindings/ rails.yaml rapps.yaml overlays/ runbooks/ evidence/ ``` Suggested file responsibilities: - `substrate/identity.yaml`: substrate id, type, owner, lifecycle, criticality - `substrate/topology.yaml`: members, providers, network zones, access surfaces - `bindings/rails.yaml`: rails available on this substrate - `bindings/rapps.yaml`: `rapp`s bound or approved for this substrate - `overlays/`: substrate-specific values or adapter overlays - `runbooks/`: substrate-local operations and recovery - `evidence/`: substrate readiness, migration, or recovery evidence ## Relationship To Railiance Fabric Reefs should become first-class graph objects in `railiance-fabric`. At minimum, Fabric should eventually be able to answer: - Which reefs provide `rail-kubernetes`? - Which reefs bind `rapp-openbao`? - Which reefs are production-critical? - Which rails are available on `reef-coulombcore`? - Which `rapp`s depend on a given reef? Until Fabric gains first-class reef vocabulary, reef repos should still use clear file-backed declarations so later ingestion is straightforward. ## Recommended Decision Adopt `reef-*` as the substrate-boundary prefix for Railiance. Use it carefully: - yes for real substrate boundaries, - no for arbitrary one-repo-per-machine duplication, - and yes for grouped substrate classes when that better matches operational reality. Treat a reef as purpose-bound compute first. The exact machine count is secondary.