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.