Define derived rail and Qonto readiness architecture

docs/reef-production-readiness-contract.md

@@ -0,0 +1,79 @@
+# 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.