--- id: RAILIANCE-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" --- # RAILIANCE-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: RAILIANCE-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: RAILIANCE-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: RAILIANCE-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: RAILIANCE-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: RAILIANCE-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-railiance01` - `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-railiance01`, `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: RAILIANCE-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: RAILIANCE-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.