coulomb/railiance-master
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Launch first repo-family materialization wave

Browse source
This commit is contained in:
codex 2026-07-25 18:14:06 +02:00
parent 4779bcdeee
commit f8200b269c
5 changed files with 432 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

1
README.md
View file

@ -14,6 +14,7 @@ recorded before they are spread across implementation repos.
- [docs/rapp-first-wave-candidates.md](docs/rapp-first-wave-candidates.md)
- [docs/reef-first-wave-rollout.md](docs/reef-first-wave-rollout.md)
- [docs/fabric-state-hub-adaptation.md](docs/fabric-state-hub-adaptation.md)
- [docs/repo-family-bootstrap-contract.md](docs/repo-family-bootstrap-contract.md)
- [docs/adr/ADR-0001-repository-prefix-architecture.md](docs/adr/ADR-0001-repository-prefix-architecture.md)
- [docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md](docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md)
- [docs/adr/ADR-0003-rapp-first-wave-selection.md](docs/adr/ADR-0003-rapp-first-wave-selection.md)

9
SCOPE.md
View file

@ -65,15 +65,16 @@ Railiance repos and cannot be owned cleanly by only one of them.
## Current State
- Status: maintained / evolving
- Implementation: architecture baseline documents are present and the first cross-repo separation workplan has been completed and handed off to sibling repos
- Status: active / evolving
- Implementation: architecture baseline documents are present and the first concrete repo-family materialization wave is now being coordinated from this repo
- Stability: evolving
- Usage: internal Railiance framework architecture home and handoff point for cross-repo planning
The repo now holds the canonical framework decisions and boundary documents for
separating `rail-*`, `rapp-*`, and `reef-*` concerns out of the existing
Railiance repos. Active implementation follow-up continues in the sibling
ownership repos.
Railiance repos. It also now governs the first implementation wave that turns
those repo families into concrete repos while downstream ownership repos retain
their implementation responsibility.
---

7
WORK-RECORDS.md
View file

@ -9,6 +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 |
| 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 |
@ -16,3 +17,9 @@
| task | RAILIANCE-WP-0017-T05 | done | — | workplans/RAILIANCE-WP-0017-rail-rapp-reef-repo-separation.md |
| 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 |

183
docs/repo-family-bootstrap-contract.md Normal file
View file

@ -0,0 +1,183 @@
# First-Wave Repo Family Bootstrap Contract
Date: 2026-07-25
## Purpose
Define the minimum bootstrap contract for the first concrete `rail-*`,
`rapp-*`, and `reef-*` repos.
This document exists to keep the first repo-materialization wave coherent.
Without a shared bootstrap contract, each new repo would improvise its own file
layout, declaration shape, and metadata vocabulary, which would weaken the
architecture as soon as the new repo families become real.
## Design Goal
The first concrete repos should be:
- small enough to create quickly
- explicit enough to be queryable by Fabric and State Hub
- narrow enough to avoid reintroducing ownership ambiguity
The goal is not to design a perfect final schema before the first repo exists.
The goal is to establish a minimal, repeatable repo baseline that can evolve
without fragmenting.
## Required Repo Baseline
Every first-wave `rail-*`, `rapp-*`, and `reef-*` repo should start with:
- `.repo-classification.yaml`
- `README.md`
- `INTENT.md`
- `SCOPE.md`
- `AGENTS.md`
- `CLAUDE.md`
- `workplans/`
- `workplans/archived/`
- one repo-family declaration file under `declarations/`
If a repo needs implementation code, manifests, charts, or automation, those
can be added after the bootstrap baseline is in place.
## Required Classification Metadata
The following metadata should be present either directly in
`.repo-classification.yaml` or in the first declaration file and projected from
there into Fabric and State Hub:
- `repo_family`
- `ownership_repo`
- `primary_rail` when applicable
- `supported_rails` when applicable
- `substrate_kind` when applicable
The source-of-truth rule is:
- repo-local declarations define the domain facts
- registry metadata reflects the smallest useful projection of those facts
Do not let registry-only metadata become the only place where a repo family is
described.
## Required Declaration Files
The first wave should standardize one obvious declaration path per repo family.
### `rail-*`
Path:
`declarations/rail.yaml`
Minimum fields:
- `rail_id`
- `ownership_repo`
- `execution_architecture`
- `substrate_prerequisites`
- `supported_rollout_modes`
- `compatibility_notes`
### `rapp-*`
Path:
`declarations/rapp.yaml`
Minimum fields:
- `rapp_id`
- `workload_identity`
- `ownership_repo`
- `supported_rails`
- `runtime_dependencies`
- `rollout_contract`
- `smoke_contract`
- `rollback_contract`
### `reef-*`
Path:
`declarations/reef.yaml`
Minimum fields:
- `reef_id`
- `substrate_kind`
- `ownership_repo`
- `lifecycle_state`
- `criticality`
- `hosted_rails`
- `bound_rapps`
- `primary_rail`
## Required Boundary Rules
The first concrete repos must respect the architecture boundaries already
defined in `railiance-master`.
### `rail-*`
- A rail repo owns an execution contract, not substrate bootstrap.
- `rail-kubernetes` must not absorb S2 cluster provisioning, admission
controller ownership, or generic substrate hardening from
`railiance-cluster`.
- A rail repo may own generic workload-on-that-rail semantics, compatibility
guidance, and rail-local helper tooling.
### `rapp-*`
- A `rapp-*` repo owns managed workload packaging and scaffolding.
- A `rapp-*` repo must not become the long-term ownership home of the platform
or application domain around that workload.
- Shared policy, tenant governance, or platform-wide credential semantics stay
in the owning `railiance-*` repo.
### `reef-*`
- A reef repo owns one durable substrate boundary.
- A reef repo must not be created automatically for every machine.
- Grouped reefs remain preferred when the machines are managed as one class,
such as workstation fleets.
## First-Wave Candidates
The first materialization wave should target:
- `rail-kubernetes`
- `rapp-openbao`
- `reef-railiance01`
The follow-on first-wave candidates after those anchors are stable:
- `rapp-vergabe-teilnahme`
- `reef-coulombcore`
- `reef-ops-workstations`
This keeps the first concrete rollout narrow while still covering all three new
repo families.
## Integration Expectations
The first-wave repos should be able to participate in:
- State Hub workplan indexing
- Fabric repository registration
- repo-family metadata projection
- later relation projection such as `supports_rail`, `hosts_rail`,
`binds_rapp`, and `governed_by`
They do not need a fully mature graph model on day one, but they do need enough
structured metadata to avoid becoming opaque one-off repos.
## Outcome
The bootstrap contract for the first repo-family wave is:
- one repeatable baseline file set
- one obvious declaration path per repo family
- one clear metadata projection path into Fabric and State Hub
- one narrow initial rollout set covering `rail-*`, `rapp-*`, and `reef-*`

236
workplans/RAILIANCE-WP-0018-first-wave-repo-family-materialization.md Normal file
View file

@ -0,0 +1,236 @@
---
id: RAILIANCE-WP-0018
type: workplan
title: "First-Wave Repo Family Materialization"
domain: financials
repo: railiance-master
status: active
owner: codex
topic_slug: railiance
planning_priority: high
planning_order: 18
created: "2026-07-25"
updated: "2026-07-25"
related_repos:
- railiance-master
- railiance-cluster
- railiance-platform
- railiance-infra
- railiance-fabric
state_hub_workstream_id: "054a494c-e430-4164-b2c3-e32e759cc3e0"
---
# RAILIANCE-WP-0018 - First-Wave Repo Family Materialization
## Goal
Turn the completed separation architecture into the first concrete
`rail-*`, `rapp-*`, and `reef-*` repo materialization wave.
This workplan governs the first implementation wave that makes the new repo
families real rather than only defined. It stays in `railiance-master` because
the sequencing still spans multiple ownership repos and Fabric integration.
## Why This Exists
`RAILIANCE-WP-0017` completed the architecture baseline and launched the first
repo-local follow-up workplans.
What is still missing is the shared control plane for:
- creating the first concrete repo-family baselines
- keeping their boundaries consistent across repos
- aligning repo-local declarations with Fabric and State Hub ingestion
- preventing the first repo creations from drifting into ad hoc local patterns
## Current Starting Point
The architecture baseline already exists in `railiance-master`:
- `docs/repository-axes.md`
- `docs/rail-kubernetes-boundary.md`
- `docs/rapp-first-wave-candidates.md`
- `docs/reef-first-wave-rollout.md`
- `docs/fabric-state-hub-adaptation.md`
The first implementation follow-up work also already exists:
- `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`
- `railiance-fabric/workplans/RAIL-FAB-WP-0025-rail-rapp-reef-fabric-adaptation.md`
Fabric now has first repo-family-aware repository metadata, but the ecosystem
still lacks:
- the first actual `rail-*` repo
- the first actual `rapp-*` repo
- the first actual `reef-*` repo
- relation projection for rail/rapp/reef topology
## Target Outcome
When this workplan is complete:
1. Railiance has a repeatable bootstrap contract for first-wave `rail-*`,
`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.
5. Fabric can project the minimum rail/rapp/reef relation topology needed to
answer placement questions.
## Boundaries
This workplan may coordinate repo creation, repo-family bootstrap, and graph
integration across Railiance repos.
It must not weaken the existing ownership boundaries:
- `railiance-cluster` remains the S2 ownership home
- `railiance-platform` remains the S3 ownership home for OpenBao
- `railiance-infra` remains the canonical S1 ownership home for first-wave reefs
- `railiance-fabric` remains the implementation home for graph ingestion and
projection
## Tasks
## T01 - Publish the first-wave repo bootstrap contract
```task
id: RAILIANCE-WP-0018-T01
status: done
priority: high
state_hub_task_id: "d6ba9286-222d-49d2-83e9-fd251c534dde"
```
Record the minimum bootstrap contract future `rail-*`, `rapp-*`, and
`reef-*` repos should follow so the first materialization wave does not invent
three incompatible patterns.
Acceptance:
- one framework document defines the minimum file baseline
- one framework document defines the first declaration path per repo family
- the metadata projection rule into Fabric and State Hub is named
2026-07-25: Added `docs/repo-family-bootstrap-contract.md`.
## T02 - Launch the first `rail-kubernetes` repo materialization
```task
id: RAILIANCE-WP-0018-T02
status: progress
priority: high
state_hub_task_id: "726a0c5c-2fa5-4bb9-a730-3200abc40ac8"
```
Create the concrete repo bootstrap and extraction path for `rail-kubernetes`
using the boundary already defined in `railiance-master` and the repo-local
follow-up work already opened in `railiance-cluster`.
Acceptance:
- the new repo has the required baseline files
- the repo declares the Kubernetes rail contract in source-controlled form
- the compatibility path from `railiance-cluster` is preserved
- the repo is ready for Fabric and State Hub registration
## T03 - Launch the first `rapp-openbao` repo materialization
```task
id: RAILIANCE-WP-0018-T03
status: wait
priority: high
state_hub_task_id: "3e46e1bd-c730-4e41-a00a-6aa7a4645023"
```
Create the concrete repo bootstrap and workload-package declaration for
`rapp-openbao` without letting the package repo absorb platform ownership.
Acceptance:
- the new repo has the required baseline files
- the repo declares OpenBao as a managed workload package
- 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
```task
id: RAILIANCE-WP-0018-T04
status: wait
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.
Acceptance:
- the new repo has the required baseline files
- the repo declares substrate kind, lifecycle, criticality, hosted rails, and
primary rail
- the repo stays compatible with the canonical S1 ownership role of
`railiance-infra`
## T05 - Add relation projection for rails, `rapp`s, and reefs in Fabric
```task
id: RAILIANCE-WP-0018-T05
status: wait
priority: medium
state_hub_task_id: "ef999db5-e75e-467a-a72a-d45fda2b6fa7"
```
Extend Fabric beyond repo-family-aware metadata so it can project the minimum
rail/rapp/reef relation topology.
Acceptance:
- Fabric can project `supports_rail`
- Fabric can project `hosts_rail`
- Fabric can project `binds_rapp`
- Fabric can project `governed_by`
- the projection path is grounded in repo-local declarations rather than
registry-only guesses
## T06 - Verify first-wave registration and coordination end to end
```task
id: RAILIANCE-WP-0018-T06
status: wait
priority: medium
state_hub_task_id: "5834f122-b9e9-41c1-93e9-d5525cd720bf"
```
Verify that the first concrete repos participate cleanly in:
- State Hub registration and indexing
- Fabric registration and graph projection
- workplan tracking across ownership repo and repo-family repo boundaries
Acceptance:
- the first concrete repos are visible to State Hub
- the first concrete repos are visible to Fabric
- cross-repo ownership and runtime relations are queryable
- the wave can continue to second candidates without redefining 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
## Notes
This workplan should stay focused on the first concrete repo-family wave.
Second-wave candidates such as `rapp-vergabe-teilnahme`, `reef-coulombcore`,
or a future `rail-knative` should be launched only after the first wave proves
the bootstrap contract, registration path, and relation model.