railiance-master/docs/repo-family-bootstrap-contract.md

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-railiance

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-*