183 lines
4.6 KiB
Markdown
183 lines
4.6 KiB
Markdown
# 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-*`
|