railiance-master/docs/reef-substrate-model.md

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

reef-<substrate-id>/
  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: rapps 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 rapps 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.