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 `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-<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`: `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.