Establish Railiance architecture home

docs/reef-substrate-model.md

@@ -0,0 +1,262 @@
+# 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 are installed or made available,
+- managed workloads are bound,
+- and operators interact with a concrete environment.
+
+More concretely, a reef represents **compute resources organized for a defined
+purpose**.
+
+The substrate may be:
+
+- a single named server,
+- a cluster,
+- a workstation,
+- an edge site,
+- a lab substrate,
+- or a small fleet treated as one unit.
+
+The important point is not the shape of the hardware. The important point is
+that the compute resources form one recognizable operational boundary.
+
+## 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 that rails attach to,
+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?
+- Which `rapp`s are allowed or deployed here?
+- 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-railiance01`
+- `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.
+
+### `RAILIANCE01`
+
+`reef-railiance01` is reasonable if Railiance01 is separately managed, migrated,
+or recovered, rather than being just another fungible node in a larger
+substrate.
+
+At the current maturity level, it is acceptable for `reef-railiance01` to host
+`rail-kubernetes` and later also `rail-knative` if that is the most pragmatic
+way to support early workloads.
+
+If that substrate becomes production-critical or security-sensitive, reassess
+whether a clearer reef separation is warranted.
+
+### `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.