# Reef Production Readiness Contract

Date: 2026-07-26
Status: Adopted for the second implementation wave

## Purpose

Prevent a topology declaration from being mistaken for permission to run a
critical workload.

`hosts_rail` and `binds_rapp` describe intended composition. Production use
requires explicit readiness evidence.

## Admission States

Every hosted rail and bound `rapp` uses:

- `declared`
- `installed`
- `verified`
- `production-approved`
- `deprecated`

Promotion is monotonic only while its evidence remains current. Failed or
expired evidence returns the binding to the last proven state.

## Required Reef Evidence

Before a rail becomes `verified`, the reef must provide machine-readable
evidence for:

- substrate and Kubernetes version compatibility
- control-plane and workload capacity with documented headroom
- ingress, DNS, and certificate path
- storage and stateful-workload constraints
- workload identity and approved secret-delivery path
- network isolation and egress enforcement
- logs, metrics, traces, alerting, and audit delivery
- backup, restore, and rollback path
- upgrade and maintenance ownership
- failure-domain and recovery assumptions

## Critical Workload Gate

Before a critical, internet-facing, or high-value-credential workload becomes
`production-approved`, its binding must additionally record:

- threat-model reference
- availability, cold-start, and recovery objectives
- identity, secret revocation, and audit evidence
- negative authorization and network tests
- rollback and temporary-fallback rules
- accepted residual risks and their owner

The single-server and shared-control-plane risks of `reef-railiance` must be
explicitly accepted or mitigated for `rapp-qonto`; the reef name or `high`
criticality label is not evidence by itself.

## Mixed-Rail Rule

`reef-railiance` may host `rail-kubernetes` and `rail-knative` during the
second wave, while `rail-kubernetes` remains primary.

Reassess or split the reef when any of these triggers occurs:

- incompatible maintenance or upgrade windows
- inability to meet a critical workload recovery objective
- control-plane or workload resource contention
- materially different network or tenant-isolation requirements
- independent scaling or availability requirements
- failure in one rail cannot be contained from the other
- premium-security or regulatory policy requires a separate boundary

## Automation Requirement

Readiness evidence should be produced by idempotent probes and stored as
source-linked, timestamped records. Agents may execute and reconcile the
probes. Human approval should consume the evidence only where policy requires
explicit risk acceptance; it should not be used as a substitute for tests.