railiance-master/docs/adr/ADR-0007-rapp-declaration-contract.md

---
id: RMASTER-ADR-0007
title: "Rapp Declaration Contract"
status: accepted
revision: "accepted-2"
owner: railiance-master
last_reviewed: "2026-08-23"
review_interval: 6m
---

# ADR-0007: Rapp Declaration Contract

Date: 2026-08-13
Status: Accepted

## Context

`RMASTER-WP-0017` through `RMASTER-WP-0019` established the four-axis
model and materialized the first family repos. The model held up. Its
enforcement did not.

A 2026-08-11 survey by `railiance-platform` found that the three live
`rapp.yaml` files were mutually unreadable: rollout, smoke, and rollback
contracts used different shapes; metadata that both rails carry consistently
appeared in only one rapp; `reef-railiance` `bound_rapps` listed `rapp-qonto`
only, while `rapp-openbao` and `rapp-postgres` were already live on the same
reef. `docs/repo-family-bootstrap-contract.md` named fields in prose and
could not catch any of this.

The same survey treated rapp grouping as something that might be derived from
Forgejo organizations or from State Hub domains. Neither works. A repo lives
in exactly one Forgejo org, so `org:repo` is one-to-many. A repo may
legitimately contribute to more than one rapp, so `rapp:repo` is
many-to-many. A many-to-many grouping cannot be derived from a one-to-many
one. Domains fail in both directions. The three dimensions also change at
different speeds.

Canon OAS P1 requires independent perspectives to be separate orthogonal
dimensions. Decision `d07ee5f9` already recorded this from the
`railiance-platform` side; this ADR is the framework record.

## Decision

1. **Bounded rapp context is its own dimension.** It is derived neither from
   Forgejo organizations nor from State Hub domains. Grouping is a first-class
   declaration, not a projection of some other axis.

2. **Two cardinalities stay distinct.** Repos to rapps is many-to-many: a
   repo may appear in the `composition.member_repos` of more than one rapp.
   Deployables to rapps is one-to-one: every running deployable has exactly
   one rapp that owns its rollout. The coverage question — *does every live
   deployable belong to exactly one rapp?* — is well-formed only if these
   stay distinct.

3. **Granularity is grouped-by-bounded-context.** One rapp per cohesive group
   that deploys, versions, and rolls back together, not one rapp per
   deployable. Grouping is legitimate only where members share rollout and
   rollback fate. A single-repo rapp is the one-member case of the same
   `composition` block, not a second shape.

4. **The schema is normative.** `schemas/rapp.schema.json`,
   `schemas/rail.schema.json`, and `schemas/reef.schema.json` define the
   shapes. Framework prose cites those files. It does not restate their
   fields. Reef `bound_rapps` is a derived projection of `rapp.bound_reefs`,
   not a hand-maintained registry.

5. **Coverage includes every managed running deployable.** Application,
   operational, and tooling runtimes participate in the same exactly-one-rapp
   invariant when they are installed, scheduled, or otherwise operated as a
   managed deployable. This includes a managed one-shot Job; it does not turn
   a human command or approval act into a workload. Human access, credential
   patterns, broker actions, one-off operational acts, and infrastructure
   resources that are not workloads retain their native actor, lane, activity,
   or resource identity.

   A running deployable that predates rapp extraction is migration debt. Until
   an authoritative declaration claims it, workload-based controls report it
   as `unknown`; they do not infer a rapp from its repository, namespace, path,
   labels, or apparent owner. A subject explicitly established as not being a
   workload is `not-applicable`. `unknown` and `not-applicable` are different
   outcomes and omission must not collapse them.

   Railiance Master remains the sole owner of the normative rapp vocabulary and
   schemas. Consumer catalogs may store explicit references and integration
   owners may resolve them, but neither creates a parallel declaration surface
   or copies rapp metadata as another source of truth.

The detailed shapes, including the single normative form of the rollout,
smoke, and rollback contracts, live in the schema files and
`schemas/README.md`.

## Consequences

- Drift across family declarations fails in
  `tools/validate-family-declarations.py` instead of accumulating in prose.
- `railiance-platform` `RAILIANCE-WP-0015-T02` can converge `rapp-openbao`
  and `rapp-postgres` onto one shape. Migration belongs to the owning repos;
  this ADR does not move any declaration.
- `reef-railiance` must stop treating `bound_rapps: [rapp-qonto]` as source
  of truth. The list is already stale.
- Three further `rapp-*` repos (`rapp-secrets-engine`, `rapp-tenant-engine`,
  `rapp-user-engine`) carry the family prefix and no declaration. They are
  visible to the validator as undeclared and must be declared, renamed, or
  retired by their owners.
- Operational and tooling deployables are not exempt from family coverage.
  Existing pre-rapp runtimes may continue during migration, but their workload
  identity remains visibly `unknown` to controls until declared.
- Runtime inventory is still required to prove universal coverage. Repository
  discovery alone cannot establish that every running unit has exactly one
  authoritative rapp.
- Calling the validator from `fix-consistency` still waits on
  `the-custodian` admitting the family prefixes into the classification
  standard. That sequencing is not this repo's.