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-railiance`
2. `reef-coulombcore`
3. `reef-ops-workstations`

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

## Why These Three

### `reef-railiance`

This should be the first canonical grouped home reef.

Why:

- `Railiance01` is already the clearest current seed of that substrate
- it is the default home for new Kubernetes-oriented Railiance workloads
- more Railiance servers may join the same home substrate over time
- keeping the grouped reef name stable now avoids renaming the substrate every
  time membership changes
- its lifecycle, access path, and workload-placement decisions are already
  distinct enough to justify a dedicated home 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 the grouped home
  reef should split by rail or security boundary

### `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`: grouped home reef now, with `Railiance01` as the first current
  member because additional Railiance servers should be represented from the
  same named home substrate when they share lifecycle, access path, and
  workload-placement policy
- `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 future Railiance servers diverge enough to need separate lifecycle,
placement, or recovery policies, reassess whether `reef-railiance` should stay
grouped or split into narrower reefs.

## `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-railiance` as the first grouped 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-railiance` as the primary grouped 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.