4864b7852d
Rename RAILIANCE-WP-0017..0021 to RMASTER-WP-* so railiance-master IDs no longer collide with railiance-platform's RAILIANCE-WP series. Hub UUIDs are unchanged.
310 lines
11 KiB
Markdown
310 lines
11 KiB
Markdown
---
|
|
id: RMASTER-WP-0017
|
|
type: workplan
|
|
title: "Rail, Rapp, and Reef Repo Separation"
|
|
domain: financials
|
|
repo: railiance-master
|
|
status: finished
|
|
owner: codex
|
|
topic_slug: railiance
|
|
planning_priority: high
|
|
planning_order: 17
|
|
created: "2026-07-25"
|
|
updated: "2026-07-25"
|
|
related_repos:
|
|
- railiance-master
|
|
- railiance-cluster
|
|
- railiance-platform
|
|
- railiance-apps
|
|
- railiance-forge
|
|
- railiance-fabric
|
|
- railiance-infra
|
|
- railiance-hosts
|
|
state_hub_workstream_id: "dd794e38-6da0-4acd-8ad8-e00bd2aa62bc"
|
|
---
|
|
|
|
# RMASTER-WP-0017 - Rail, Rapp, and Reef Repo Separation
|
|
|
|
## Goal
|
|
|
|
Turn the newly defined `rail-*`, `rapp-*`, and `reef-*` concepts into an
|
|
executable migration plan for the current Railiance repo family, so the
|
|
framework can evolve without leaving workload execution semantics, workload
|
|
packaging, and substrate realities mixed into the existing ownership repos.
|
|
|
|
This workplan is explicitly cross-repo. It belongs in `railiance-master`
|
|
because no single implementation repo can own the migration end to end.
|
|
|
|
## Current Starting Point
|
|
|
|
The framework baseline is now recorded in `railiance-master`:
|
|
|
|
- `docs/repository-axes.md`
|
|
- `docs/reef-substrate-model.md`
|
|
- `docs/adr/ADR-0001-repository-prefix-architecture.md`
|
|
|
|
The repo is also now prepared and registered with State Hub as the architecture
|
|
home for future multi-repo Railiance work.
|
|
|
|
The architectural direction is now further clarified:
|
|
|
|
- wave 1 is centered on `rail-kubernetes` as the default base rail
|
|
- new rails are introduced only for concrete workload needs with a sound
|
|
runtime argument
|
|
- `rail-knative` is the first expected follow-on rail, driven by the need to
|
|
support `qonto-assistent`, but only after the Kubernetes rail boundary is
|
|
clean
|
|
- `rapp-*` repos are about managed wrapping and scaffolding, not ownership
|
|
- `reef-*` repos are about compute resources organized for a defined purpose
|
|
- mixed-rail reefs are acceptable early, but production-grade cases should
|
|
prefer clearer substrate and primary-rail separation unless deliberately
|
|
justified
|
|
|
|
The remaining problem is implementation reality:
|
|
|
|
- `railiance-cluster` still owns Kubernetes-specific workload lifecycle and
|
|
overlay semantics that should eventually become `rail-kubernetes`
|
|
- first-class workload wrappers are still spread across `railiance-apps`,
|
|
`railiance-platform`, and `railiance-forge`
|
|
- substrate reality is under-described and split between `railiance-infra` and
|
|
`railiance-hosts`
|
|
- `railiance-fabric` and State Hub do not yet model rails, `rapp`s, or reefs
|
|
as first-class entities
|
|
|
|
## Target Outcome
|
|
|
|
When this workplan is complete:
|
|
|
|
1. Railiance has a clear first migration target for `rail-kubernetes`.
|
|
2. The first set of `rapp-*` candidates is chosen and ordered.
|
|
3. The first `reef-*` rollout rule is chosen for current named substrates.
|
|
4. `railiance-fabric` and State Hub have a defined integration path for the new
|
|
repo families.
|
|
5. The current repo set has an approved separation plan, not only a naming idea.
|
|
|
|
## Boundaries
|
|
|
|
This workplan may define, sequence, and coordinate repo splits.
|
|
|
|
It must not silently move implementation content between repos without explicit
|
|
repo-local follow-up workplans or commits in those repos.
|
|
|
|
## Tasks
|
|
|
|
## T01 - Record the framework repo-family baseline in railiance-master
|
|
|
|
```task
|
|
id: RMASTER-WP-0017-T01
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "7cb6769a-5557-46e5-8e20-c492e5049604"
|
|
```
|
|
|
|
Record the first canonical architecture baseline for:
|
|
|
|
- `railiance-*` as ownership repos
|
|
- `rail-*` as execution-contract repos
|
|
- `rapp-*` as managed workload package repos
|
|
- `reef-*` as substrate-boundary repos
|
|
|
|
Acceptance:
|
|
|
|
- `railiance-master` contains the baseline documents and ADR
|
|
- the `reef-*` model is explicitly defined and bounded against repo explosion
|
|
|
|
## T02 - Prepare railiance-master as the cross-repo workplan home
|
|
|
|
```task
|
|
id: RMASTER-WP-0017-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "17be5faa-cba2-4838-97af-dc3b79e0511b"
|
|
```
|
|
|
|
Prepare and register `railiance-master` in State Hub so cross-repo architecture
|
|
work can live here as first-class workplans.
|
|
|
|
Acceptance:
|
|
|
|
- repo is classification-registered
|
|
- repo passes `statehub fix-consistency`
|
|
- workplan and architecture files can now be indexed from this repo
|
|
|
|
## T03 - Define the `rail-kubernetes` extraction boundary
|
|
|
|
```task
|
|
id: RMASTER-WP-0017-T03
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "e25ea023-e2fe-44b9-96c1-cca19c65053f"
|
|
```
|
|
|
|
Define what moves from `railiance-cluster` into a future `rail-kubernetes`
|
|
repo, and what must remain owned by `railiance-cluster`.
|
|
|
|
This is the wave-1 architecture task. It must treat `rail-kubernetes` as the
|
|
default base rail for the current ecosystem rather than as one option among
|
|
many equally urgent rails.
|
|
|
|
At minimum, decide the boundary for:
|
|
|
|
- `railiance/app.toml`
|
|
- promotion lifecycle semantics
|
|
- overlay repo pattern
|
|
- stage-1/2/3 tooling
|
|
- cluster-runtime prerequisites versus workload-runtime semantics
|
|
- the compatibility path future rails such as `rail-knative` will rely on
|
|
|
|
Acceptance:
|
|
|
|
- one written boundary contract names what `railiance-cluster` keeps
|
|
- one written boundary contract names what `rail-kubernetes` must own
|
|
- at least one migration-safe path exists that does not break current users
|
|
- the boundary leaves a coherent follow-on path for `rail-knative` without
|
|
forcing knative design decisions into wave 1
|
|
|
|
2026-07-25: Added `docs/rail-kubernetes-boundary.md` and
|
|
`docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md`. The boundary now names
|
|
the retained S2 substrate scope, the extracted Kubernetes rail contract, the
|
|
rehome-required workload-specific helpers, and a compatibility-preserving split
|
|
sequence.
|
|
|
|
## T04 - Identify and sequence the first `rapp-*` candidates
|
|
|
|
```task
|
|
id: RMASTER-WP-0017-T04
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "674b1a4f-2c5b-499c-b26f-9ed4f9f0861c"
|
|
```
|
|
|
|
Choose the first workload packages that should become first-class `rapp-*`
|
|
repos instead of remaining embedded inside ownership repos.
|
|
|
|
This task must treat `rapp-*` as managed workload packaging for third-party or
|
|
self-built workloads in the Railiance and Net Kingdom context. It must not
|
|
turn `rapp-*` into an ownership mirror of existing `railiance-*` repos.
|
|
|
|
Candidate set to assess:
|
|
|
|
- Forgejo or Gitea from `railiance-forge`
|
|
- OpenBao from `railiance-platform`
|
|
- one user-facing S5 workload from `railiance-apps`
|
|
|
|
Acceptance:
|
|
|
|
- first-wave `rapp-*` candidates are named
|
|
- rationale is recorded for each chosen or deferred candidate
|
|
- split order is defined so ownership boundaries do not get weaker during migration
|
|
- each chosen candidate is justified as a managed wrapper and not as a new
|
|
ownership home
|
|
|
|
2026-07-25: Added `docs/rapp-first-wave-candidates.md` and
|
|
`docs/adr/ADR-0003-rapp-first-wave-selection.md`. The first-wave order is now
|
|
`rapp-openbao`, then `rapp-vergabe-teilnahme`, with the forge workload
|
|
explicitly deferred until the Gitea-versus-Forgejo package target is stable
|
|
enough to avoid immediate wrapper churn.
|
|
|
|
## T05 - Decide the first `reef-*` rollout for current substrates
|
|
|
|
```task
|
|
id: RMASTER-WP-0017-T05
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "53c63266-fbcb-4644-86f4-042e7b80744e"
|
|
```
|
|
|
|
Apply the new reef model to the current Railiance substrate reality and decide
|
|
whether the first rollout should be:
|
|
|
|
- `reef-coulombcore`
|
|
- `reef-railiance`
|
|
- `reef-workstation`
|
|
- or a grouped substrate such as `reef-ops-workstations`
|
|
|
|
This task must also resolve the conceptual overlap between `railiance-infra`
|
|
and `railiance-hosts`.
|
|
|
|
It should treat reefs as compute resources organized for a defined purpose and
|
|
should explicitly decide how much multi-rail mixing is acceptable in early
|
|
substrates such as `RAILIANCE01`.
|
|
|
|
Acceptance:
|
|
|
|
- first-wave reef repo set is chosen
|
|
- the rule for singleton versus grouped reef repos is applied to current hosts
|
|
- the `railiance-hosts` versus `railiance-infra` ambiguity has a documented direction
|
|
- any provisional terminology for transitional substrates is kept provisional
|
|
unless the pattern is stable enough to canonize
|
|
|
|
2026-07-25: Added `docs/reef-first-wave-rollout.md` and
|
|
`docs/adr/ADR-0004-first-wave-reef-rollout.md`. The first rollout is now
|
|
`reef-railiance`, `reef-coulombcore`, and `reef-ops-workstations`, with
|
|
`railiance-infra` chosen as the canonical S1 ownership repo and transitional
|
|
substrate nicknames intentionally left provisional.
|
|
|
|
## T06 - Define `railiance-fabric` and State Hub adaptation for the new repo families
|
|
|
|
```task
|
|
id: RMASTER-WP-0017-T06
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "4f47d000-6495-4163-8673-f339dd7ef41f"
|
|
```
|
|
|
|
Define the minimum graph and coordination changes needed so rails, `rapp`s, and
|
|
reefs are not only naming conventions but visible ecosystem entities.
|
|
|
|
Acceptance:
|
|
|
|
- `railiance-fabric` adaptation requirements are listed
|
|
- State Hub registration/indexing implications are listed
|
|
- the minimum fields or declarations needed in future `rail-*`, `rapp-*`, and
|
|
`reef-*` repos are recorded
|
|
|
|
2026-07-25: Added `docs/fabric-state-hub-adaptation.md`. The minimum
|
|
adaptation requirements now cover repo-family metadata, Fabric onboarding
|
|
updates, typed service/relation vocabulary, and the smallest repo-local
|
|
declaration surface future `rail-*`, `rapp-*`, and `reef-*` repos must expose.
|
|
|
|
## T07 - Launch the first migration wave into concrete repo-local follow-up work
|
|
|
|
```task
|
|
id: RMASTER-WP-0017-T07
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "e762c05a-c6f1-439e-98e2-bf4d7b312a74"
|
|
```
|
|
|
|
Create the concrete follow-up workplans in the affected implementation repos for
|
|
the first migration wave.
|
|
|
|
Acceptance:
|
|
|
|
- at least one repo-local workplan exists for `rail-kubernetes`
|
|
- at least one repo-local workplan exists for a first `rapp-*` extraction
|
|
- at least one repo-local workplan exists for a first `reef-*` rollout or substrate cleanup
|
|
- this master workplan can then govern sequencing rather than holding all implementation detail itself
|
|
|
|
2026-07-25: Added the first repo-local follow-up workplans:
|
|
|
|
- `railiance-cluster/workplans/RAIL-BS-WP-0012-rail-kubernetes-extraction.md`
|
|
- `railiance-platform/workplans/RAILIANCE-WP-0012-rapp-openbao-extraction-boundary.md`
|
|
- `railiance-infra/workplans/RAIL-HO-WP-0007-first-reef-rollout-and-s1-canonicalization.md`
|
|
|
|
## Exit Criteria
|
|
|
|
- [x] The architecture baseline is recorded in `railiance-master`
|
|
- [x] `railiance-master` is registered and synced with State Hub
|
|
- [x] `rail-kubernetes` boundary is written and approved
|
|
- [x] first `rapp-*` candidates and split order are written and approved
|
|
- [x] first `reef-*` rollout decision is written and approved
|
|
- [x] Fabric and State Hub adaptation requirements are written
|
|
- [x] first migration-wave follow-up workplans exist in the affected repos
|
|
|
|
## Notes
|
|
|
|
This workplan is intended to stay small at the framework level. Once a split or
|
|
migration has a concrete owner, the implementation detail should move into the
|
|
relevant repo-local workplan rather than expanding this file into a second
|
|
control plane.
|