railiance-master/docs/reef-production-readiness-contract.md

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.