railiance-master/docs/reef-first-wave-rollout.md

# First-Wave `reef-*` Rollout

Date: 2026-07-25

## Purpose

Apply the `reef-*` model to the current Railiance substrate reality and choose
the first actual reef rollout.

This document intentionally decides both:

- which reefs should exist first
- and which current repo should remain the canonical S1 ownership home while
  reefs are introduced

## Current Substrate Reality

Railiance currently has three clearly different substrate realities:

### `RAILIANCE01`

- HostEurope server at `92.205.62.239`
- the most mature current home for new Kubernetes-first workloads
- already hosts Forgejo and overlapping platform services
- likely seed of a future multi-server Railiance home substrate

### `COULOMBCORE`

- HostEurope server at `92.205.130.254`
- older, mixed-purpose, still actively used
- retains current Gitea fallback and other legacy or transitional runtime
  realities
- not yet fully integrated into the newer operating model

### operator workstation

- edge/operator compute, not the same kind of substrate as the servers
- hosts operator tools, local keys, bridges, kubeconfig usage, and attended
  control-plane work
- likely to become a class of substrates rather than a forever-singleton machine

## Decision

The first-wave reef rollout is:

1. `reef-railiance01`
2. `reef-coulombcore`
3. `reef-ops-workstations`

Do **not** create `reef-workstation` as a singleton first-wave repo.

## Why These Three

### `reef-railiance01`

This should be the first canonical reef.

Why:

- it is already the clearest purpose-bound substrate
- it is the default home for new Kubernetes-oriented Railiance workloads
- it is the likely seed of the future Railiance home reef
- its lifecycle, access path, and workload-placement decisions are already
  distinct enough to justify a dedicated reef

Primary rail stance:

- primary rail: `rail-kubernetes`
- temporary multi-rail reality is acceptable here during early growth
- later `rail-knative` may coexist on this reef if that is the most pragmatic
  path for early workloads such as `qonto-assistent`
- if criticality or security pressure grows, reassess whether a broader grouped
  home reef or a rail-specific separation is required

### `reef-coulombcore`

This should exist, but explicitly as a transitional reef.

Why:

- COULOMBCORE is still a real operational boundary
- it has its own access path, operational evidence, fallback responsibilities,
  and recovery decisions
- it is exactly the kind of substrate that should be described honestly even if
  its long-term role is not yet clean

Interpretation:

- treat it as a mixed-purpose, legacy, or transition reef
- allow multi-rail and compatibility realities here without pretending they are
  the preferred long-term production pattern
- use the reef to make drain, cleanup, fallback, and migration decisions visible

Do not force a permanent taxonomy label such as "associate", "sidecar", or
"comet" yet. Those labels may become useful later, but the operational pattern
is not stable enough to canonize.

### `reef-ops-workstations`

Use a grouped reef for operator workstations.

Why:

- the workstation role is clearly a different substrate class from the servers
- the machine count is likely to grow or vary over time
- one repo per laptop would create exactly the duplication the reef model is
  supposed to prevent

Interpretation:

- treat current workstation reality as the first member of an operator/edge
  compute reef class
- keep machine-specific details inside the reef topology, not in separate repos

## Singleton Versus Grouped Rule Applied

Applying the reef rules to the current hosts yields:

- `RAILIANCE01`: singleton reef now, because the machine itself is the current
  durable substrate boundary
- `COULOMBCORE`: singleton reef now, because it remains an independent
  operational and fallback boundary
- workstation: grouped reef, because the substrate concept is "operator edge
  compute" rather than one permanently special laptop

If Railiance01 later becomes one node in a clearly unified multi-node home
substrate with shared lifecycle and placement policy, reassess whether the
right target becomes a grouped reef such as `reef-railiance-home`.

Until then, `reef-railiance01` is the cleaner decision.

## `railiance-hosts` Versus `railiance-infra`

Current reality:

- `railiance-hosts` and `railiance-infra` are functionally duplicate S1 repos
- both describe the same S1 provisioning and baseline responsibility
- both contain the same authoritative-looking server inventory path
- Fabric onboarding already uses `railiance-infra`

Decision:

- `railiance-infra` is the canonical S1 ownership repo going forward
- `railiance-hosts` should be treated as a predecessor or migration duplicate,
  not as the long-term authority for new architecture work

What this means:

- new framework architecture should anchor on `railiance-infra`
- reef introduction should not preserve the `hosts` naming line as a second S1
  authority
- later cleanup should either retire `railiance-hosts` or reduce it to an
  explicit compatibility/archive role

## Practical Rollout Sequence

The reef rollout should happen in this order:

1. create `reef-railiance01` as the first canonical home reef seed
2. create `reef-coulombcore` as the transitional legacy/fallback reef
3. create `reef-ops-workstations` as the grouped operator-edge reef
4. document `railiance-infra` as canonical S1 and plan the `railiance-hosts`
   retirement or freeze direction

## Risks To Watch

- If `reef-coulombcore` is described as if it were the preferred long-term
  production substrate, the reef model will normalize transitional mess instead
  of making it visible.
- If `reef-workstation` is created first, the framework will drift toward
  one-repo-per-machine duplication.
- If `railiance-hosts` and `railiance-infra` remain equally canonical, reef
  ownership will rest on an unstable S1 base.

## Outcome

Railiance now has a concrete first reef rollout:

- `reef-railiance01` as the primary home-reef seed
- `reef-coulombcore` as the transitional legacy/fallback reef
- `reef-ops-workstations` as the grouped operator-edge reef

That is enough to move from reef theory into practical repo planning.