From b6c24a7195eca26e506e96f95177506c0b56af85 Mon Sep 17 00:00:00 2001 From: codex Date: Sun, 26 Jul 2026 08:51:13 +0200 Subject: [PATCH] Finish first repo-family materialization wave --- SCOPE.md | 4 +- WORK-RECORDS.md | 12 +-- docs/adr/ADR-0004-first-wave-reef-rollout.md | 10 +-- docs/fabric-state-hub-adaptation.md | 4 +- docs/reef-first-wave-rollout.md | 36 ++++----- docs/reef-substrate-model.md | 18 ++--- docs/repo-family-bootstrap-contract.md | 2 +- docs/repository-axes.md | 2 +- ...-WP-0017-rail-rapp-reef-repo-separation.md | 4 +- ...-first-wave-repo-family-materialization.md | 76 +++++++++++++++---- 10 files changed, 108 insertions(+), 60 deletions(-) diff --git a/SCOPE.md b/SCOPE.md index b2cf59d..56cd52d 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -65,8 +65,8 @@ Railiance repos and cannot be owned cleanly by only one of them. ## Current State -- Status: active / evolving -- Implementation: architecture baseline documents are present and the first concrete repo-family materialization wave is now being coordinated from this repo +- Status: maintained / evolving +- Implementation: architecture baseline documents are present and the first concrete repo-family materialization wave has been completed from this repo - Stability: evolving - Usage: internal Railiance framework architecture home and handoff point for cross-repo planning diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index 3973ee5..58db712 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -9,7 +9,7 @@ | Kind | ID | Status | Lane | Source | | --- | --- | --- | --- | --- | | workplan | RAILIANCE-WP-0017 | finished | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | -| workplan | RAILIANCE-WP-0018 | active | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| workplan | RAILIANCE-WP-0018 | finished | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | | task | RAILIANCE-WP-0017-T01 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | | task | RAILIANCE-WP-0017-T02 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | | task | RAILIANCE-WP-0017-T03 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | @@ -18,8 +18,8 @@ | task | RAILIANCE-WP-0017-T06 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | | task | RAILIANCE-WP-0017-T07 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md | | task | RAILIANCE-WP-0018-T01 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | -| task | RAILIANCE-WP-0018-T02 | progress | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | -| task | RAILIANCE-WP-0018-T03 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | -| task | RAILIANCE-WP-0018-T04 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | -| task | RAILIANCE-WP-0018-T05 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | -| task | RAILIANCE-WP-0018-T06 | wait | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| task | RAILIANCE-WP-0018-T02 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| task | RAILIANCE-WP-0018-T03 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| task | RAILIANCE-WP-0018-T04 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| task | RAILIANCE-WP-0018-T05 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | +| task | RAILIANCE-WP-0018-T06 | done | — | workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md | diff --git a/docs/adr/ADR-0004-first-wave-reef-rollout.md b/docs/adr/ADR-0004-first-wave-reef-rollout.md index fca4c9d..9ca7ee7 100644 --- a/docs/adr/ADR-0004-first-wave-reef-rollout.md +++ b/docs/adr/ADR-0004-first-wave-reef-rollout.md @@ -20,7 +20,7 @@ At the same time, S1 ownership is ambiguous because `railiance-hosts` and The first-wave reef rollout is: -1. `reef-railiance01` +1. `reef-railiance` 2. `reef-coulombcore` 3. `reef-ops-workstations` @@ -33,8 +33,8 @@ frozen, or reduced later rather than as a second canonical S1 architecture home. ### Positive -- Railiance gets a primary home-reef seed without waiting for a multi-node - future. +- Railiance gets a grouped home-reef seed whose name remains stable as more + home servers are added. - Transitional CoulombCore reality is acknowledged without being treated as the long-term preferred production pattern. - Operator edge compute is modeled without defaulting to one repo per machine. @@ -43,8 +43,8 @@ frozen, or reduced later rather than as a second canonical S1 architecture home. ### Required Follow-On Work - Create repo-local rollout work for the first reef repos. -- Decide whether Railiance01 later remains a singleton reef or becomes part of - a grouped home reef. +- Define how additional Railiance home servers join `reef-railiance` and what + future split criteria would justify narrower reefs. - Plan the `railiance-hosts` cleanup direction relative to `railiance-infra`. ### Constraints diff --git a/docs/fabric-state-hub-adaptation.md b/docs/fabric-state-hub-adaptation.md index fd0620e..826c697 100644 --- a/docs/fabric-state-hub-adaptation.md +++ b/docs/fabric-state-hub-adaptation.md @@ -53,8 +53,8 @@ Add or derive the following repo-level concepts: not `ownership` - `primary_rail`: for reefs or workloads where one rail is the declared default - `supported_rails`: for `rapp-*` repos -- `substrate_kind`: for `reef-*` repos, such as `server`, `cluster`, - `workstation-group`, or `edge` +- `substrate_kind`: for `reef-*` repos, such as `server`, `server-group`, + `cluster`, `workstation-group`, or `edge` These fields may start in `.repo-classification.yaml` or a repo-local companion metadata file if the classification schema should stay smaller. diff --git a/docs/reef-first-wave-rollout.md b/docs/reef-first-wave-rollout.md index ca652cc..ba6cb79 100644 --- a/docs/reef-first-wave-rollout.md +++ b/docs/reef-first-wave-rollout.md @@ -43,7 +43,7 @@ Railiance currently has three clearly different substrate realities: The first-wave reef rollout is: -1. `reef-railiance01` +1. `reef-railiance` 2. `reef-coulombcore` 3. `reef-ops-workstations` @@ -51,17 +51,19 @@ Do **not** create `reef-workstation` as a singleton first-wave repo. ## Why These Three -### `reef-railiance01` +### `reef-railiance` -This should be the first canonical reef. +This should be the first canonical grouped home reef. Why: -- it is already the clearest purpose-bound substrate +- `Railiance01` is already the clearest current seed of that substrate - it is the default home for new Kubernetes-oriented Railiance workloads -- it is the likely seed of the future Railiance home reef +- 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 reef + distinct enough to justify a dedicated home reef Primary rail stance: @@ -69,8 +71,8 @@ Primary rail stance: - 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 +- if criticality or security pressure grows, reassess whether the grouped home + reef should split by rail or security boundary ### `reef-coulombcore` @@ -116,18 +118,18 @@ Interpretation: Applying the reef rules to the current hosts yields: -- `RAILIANCE01`: singleton reef now, because the machine itself is the current - durable substrate boundary +- `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 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. +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` @@ -156,7 +158,7 @@ What this means: The reef rollout should happen in this order: -1. create `reef-railiance01` as the first canonical home reef seed +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` @@ -176,7 +178,7 @@ The reef rollout should happen in this order: Railiance now has a concrete first reef rollout: -- `reef-railiance01` as the primary home-reef seed +- `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 diff --git a/docs/reef-substrate-model.md b/docs/reef-substrate-model.md index f1e0a3e..fc93c38 100644 --- a/docs/reef-substrate-model.md +++ b/docs/reef-substrate-model.md @@ -128,7 +128,7 @@ A reef name should follow the durable substrate identity used by operators. Good examples: - `reef-coulombcore` -- `reef-railiance01` +- `reef-railiance` - `reef-workstation` - `reef-ops-workstations` @@ -176,18 +176,18 @@ kind of substrate. Terms such as "associate", "sidecar", or "comet" may be useful exploration language, but they should stay provisional until the pattern repeats and earns a stable place in the framework vocabulary. -### `RAILIANCE01` +### Railiance Home Substrate -`reef-railiance01` is reasonable if Railiance01 is separately managed, migrated, -or recovered, rather than being just another fungible node in a larger -substrate. +`reef-railiance` is reasonable when Railiance home servers are expected to +share one durable operational substrate boundary, with `Railiance01` as the +first current member rather than the permanent repo name anchor. -At the current maturity level, it is acceptable for `reef-railiance01` to host +At the current maturity level, it is acceptable for `reef-railiance` to host `rail-kubernetes` and later also `rail-knative` if that is the most pragmatic -way to support early workloads. +way to support early workloads across that grouped home substrate. -If that substrate becomes production-critical or security-sensitive, reassess -whether a clearer reef separation is warranted. +If member servers later diverge enough in lifecycle, access path, or security +boundary, reassess whether the grouped reef should split into narrower reefs. ### `WORKSTATION` diff --git a/docs/repo-family-bootstrap-contract.md b/docs/repo-family-bootstrap-contract.md index 1b60692..ff04bf0 100644 --- a/docs/repo-family-bootstrap-contract.md +++ b/docs/repo-family-bootstrap-contract.md @@ -149,7 +149,7 @@ The first materialization wave should target: - `rail-kubernetes` - `rapp-openbao` -- `reef-railiance01` +- `reef-railiance` The follow-on first-wave candidates after those anchors are stable: diff --git a/docs/repository-axes.md b/docs/repository-axes.md index b1503e4..d17c800 100644 --- a/docs/repository-axes.md +++ b/docs/repository-axes.md @@ -145,7 +145,7 @@ are bound. Examples: - `reef-coulombcore` -- `reef-railiance01` +- `reef-railiance` - `reef-workstation` - `reef-ops-workstations` diff --git a/workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md b/workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md index e7ea203..5ecc975 100644 --- a/workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md +++ b/workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md @@ -218,7 +218,7 @@ Apply the new reef model to the current Railiance substrate reality and decide whether the first rollout should be: - `reef-coulombcore` -- `reef-railiance01` +- `reef-railiance` - `reef-workstation` - or a grouped substrate such as `reef-ops-workstations` @@ -239,7 +239,7 @@ Acceptance: 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 +`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. diff --git a/workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md b/workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md index 3b74190..36610d4 100644 --- a/workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md +++ b/workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md @@ -4,13 +4,13 @@ type: workplan title: "First-Wave Repo Family Materialization" domain: financials repo: railiance-master -status: active +status: finished owner: codex topic_slug: railiance planning_priority: high planning_order: 18 created: "2026-07-25" -updated: "2026-07-25" +updated: "2026-07-26" related_repos: - railiance-master - railiance-cluster @@ -76,7 +76,7 @@ When this workplan is complete: `rapp-*`, and `reef-*` repos. 2. The first concrete `rail-kubernetes` repo exists and is registered. 3. The first concrete `rapp-openbao` repo exists and is registered. -4. The first concrete `reef-railiance01` repo exists and is registered. +4. The first concrete `reef-railiance` repo exists and is registered. 5. Fabric can project the minimum rail/rapp/reef relation topology needed to answer placement questions. @@ -120,7 +120,7 @@ Acceptance: ```task id: RAILIANCE-WP-0018-T02 -status: progress +status: done priority: high state_hub_task_id: "726a0c5c-2fa5-4bb9-a730-3200abc40ac8" ``` @@ -151,6 +151,13 @@ but the registry endpoint at `http://127.0.0.1:8765` refused the connection. The repo is now remote-backed and source-registered, while live registry ingestion remains blocked on the local Fabric registry service being up. +2026-07-25: Started the local Fabric registry service and completed the +targeted live sync for `rail-kubernetes`. The repo is now State Hub +registered, source-registered in the Fabric onboarding manifest, remote-backed +in Forgejo, and live-ingested into the Fabric registry. Remaining wave-1 +`rail-kubernetes` work is now about helper scripts and command +implementations rather than registration. + 2026-07-25: Imported the first core generic contract artifacts into `rail-kubernetes`: the canonical deployment lifecycle doc, the canonical `railiance/app.toml` contract doc, the machine-readable schema, and the example @@ -163,11 +170,15 @@ deploy/observe contract, promotion/rollback guide, and Stage 1 run-command contract. Remaining wave-1 import debt is now mainly helper scripts and command implementations rather than core contract documentation. +2026-07-25: Closed T02 after confirming the first-class repo baseline, source +declaration, compatibility path, remote registration, State Hub registration, +and live Fabric ingestion are all in place for `rail-kubernetes`. + ## T03 - Launch the first `rapp-openbao` repo materialization ```task id: RAILIANCE-WP-0018-T03 -status: wait +status: done priority: high state_hub_task_id: "3e46e1bd-c730-4e41-a00a-6aa7a4645023" ``` @@ -182,17 +193,27 @@ Acceptance: - the repo declares supported rails and rollout/smoke/rollback contract - the remaining ownership boundary with `railiance-platform` stays explicit -## T04 - Launch the first `reef-railiance01` repo materialization +2026-07-25: Confirmed that `/home/worsch/rapp-openbao` does not yet exist. +Bootstrap will start from the boundary and first move set already recorded in +`railiance-platform/docs/rapp-openbao-boundary.md`. + +2026-07-25: Bootstrapped `/home/worsch/rapp-openbao` with the first-wave repo +baseline, `declarations/rapp.yaml`, a package-local Makefile, repo-local docs, +the first imported OpenBao package assets from `railiance-platform`, and +`RAPP-OPENBAO-WP-0001`. The repo is now registered in State Hub; Fabric +registry onboarding remains open as repo-local follow-up work. + +## T04 - Launch the first `reef-railiance` repo materialization ```task id: RAILIANCE-WP-0018-T04 -status: wait +status: done priority: medium state_hub_task_id: "f6f2ea73-0ff3-4cfa-b7a7-7b71db3afb4a" ``` Create the concrete repo bootstrap and substrate declaration for -`reef-railiance01` as the first durable reef repo. +`reef-railiance` as the first grouped home reef repo. Acceptance: @@ -202,11 +223,21 @@ Acceptance: - the repo stays compatible with the canonical S1 ownership role of `railiance-infra` +2026-07-26: Corrected the first-wave home reef target from singleton +`reef-railiance01` to grouped `reef-railiance`, updated the framework and S1 +source docs accordingly, and bootstrapped `/home/worsch/reef-railiance` with +the baseline repo files, grouped reef declaration, substrate/topology files, +repo-local docs, and `REEF-RAILIANCE-WP-0001`. The repo is now remote-backed in +Forgejo, registered in State Hub, added to +`railiance-fabric/registry/railiance-repos.yaml`, and live-ingested into the +Fabric registry as `repo_family: reef` with `primary_rail: rail-kubernetes` +and `substrate_kind: server-group`. + ## T05 - Add relation projection for rails, `rapp`s, and reefs in Fabric ```task id: RAILIANCE-WP-0018-T05 -status: wait +status: done priority: medium state_hub_task_id: "ef999db5-e75e-467a-a72a-d45fda2b6fa7" ``` @@ -223,11 +254,18 @@ Acceptance: - the projection path is grounded in repo-local declarations rather than registry-only guesses +2026-07-26: Completed the Fabric relation-projection slice in +`railiance-fabric`. Repository records now retain local checkout paths, the +registry combined graph reopens repo-local `rail`, `rapp`, and `reef` files to +project `governed_by`, `supports_rail`, `hosts_rail`, and `binds_rapp`, and +the graph explorer preserves the declaration evidence on projected repository +nodes. Focused Fabric tests passed after the projection update. + ## T06 - Verify first-wave registration and coordination end to end ```task id: RAILIANCE-WP-0018-T06 -status: wait +status: done priority: medium state_hub_task_id: "5834f122-b9e9-41c1-93e9-d5525cd720bf" ``` @@ -245,14 +283,22 @@ Acceptance: - cross-repo ownership and runtime relations are queryable - the wave can continue to second candidates without redefining the bootstrap model +2026-07-26: Verified the first-wave coordination path end to end. The live +Fabric registry at `http://127.0.0.1:8765` now stores the local paths and +repo-family metadata for `rail-kubernetes`, `rapp-openbao`, and +`reef-railiance`, and its graph-explorer export emits live `governed_by`, +`supports_rail`, and `hosts_rail` edges from repo-local declarations. State +Hub consistency sync remains clean for the framework and repo-local workplans, +so the first wave can continue without reopening the bootstrap model. + ## Exit Criteria - [x] The first-wave bootstrap contract is published -- [ ] `rail-kubernetes` exists as a first-class repo baseline -- [ ] `rapp-openbao` exists as a first-class repo baseline -- [ ] `reef-railiance01` exists as a first-class repo baseline -- [ ] Fabric projects the minimum rail/rapp/reef relation topology -- [ ] State Hub and Fabric can coordinate the first concrete repo-family wave end to end +- [x] `rail-kubernetes` exists as a first-class repo baseline +- [x] `rapp-openbao` exists as a first-class repo baseline +- [x] `reef-railiance` exists as a first-class repo baseline +- [x] Fabric projects the minimum rail/rapp/reef relation topology +- [x] State Hub and Fabric can coordinate the first concrete repo-family wave end to end ## Notes