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.

The field lists below are an index, not a specification. The JSON Schema for each family is normative. If this document and a schema disagree, the schema wins. Shapes, types, enums, and cardinality live in the schema files; do not restate them here.

rail-*

Path: declarations/rail.yaml

Schema: schemas/rail.schema.json

A rail is either composition_kind: base or composition_kind: derived. A derived rail names its base contract rather than copying it. See docs/rail-composition-contract.md and ADR-0005. The live name for substrate needs is required_substrate_capabilities; the earlier substrate_prerequisites label is retired.

rapp-*

Path: declarations/rapp.yaml

Schema: schemas/rapp.schema.json

A rapp is a composition: a stated purpose, first-party member repos, and pinned third-party components. Repos to rapps is many-to-many; deployables to rapps is one-to-one. See ADR-0007. bound_reefs is how a rapp names the reefs it is placed on; that field is the source of a reef's bound_rapps.

runtime_dependencies names capabilities, not the resources that satisfy them. Who provisions a capability (for example the postgres backup object store) is owned outside the rapp: procurement and cost by resource-control, operation and non-secret attributes by the reef (reef-storage for S3, not reef-railiance), the credential by railiance-platform. The rapp consumes a reviewed destination.

reef-*

Path: declarations/reef.yaml

Schema: schemas/reef.schema.json

bound_rapps is a derived projection of every rapp whose bound_reefs lists this reef. It is not a hand-maintained registry. A reef may omit the field; if it keeps the field, the validator requires an exact match against the projection. A compute reef that hosts rails must set primary_rail and list it in hosted_rails. A provider-delegated reef (for example reef-storage, substrate_kind: object-storage) omits both: there is no execution contract to host. Hosting a rail or binding a rapp is topology, not readiness — see ADR-0006.

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 planned first materialization wave was rail-kubernetes, rapp-openbao, reef-railiance, then rapp-vergabe-teilnahme. What was actually built, and the wave-2 inventory, is recorded in docs/rapp-first-wave-candidates.md. Do not restate that list here.

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