rail-kubernetes/docs/wave-1-contract.md

Wave-1 Kubernetes Rail Contract

Purpose

Summarize the initial contract rail-kubernetes owns in wave 1.

This repo starts from already-reviewed source documents rather than inventing a new runtime model:

• railiance-master/docs/rail-kubernetes-boundary.md
• railiance-cluster/docs/rail-kubernetes-extraction-map.md
• railiance-cluster/docs/rail-kubernetes-substrate-profile.md

What rail-kubernetes Owns

Wave 1 assigns these concerns to the rail:

• the generic workload-on-Kubernetes execution contract
• the generic railiance/app.toml workload declaration surface
• generic stage 1 / stage 2 / stage 3 lifecycle semantics
• generic canary, observe, promote, and rollback behavior
• generic wrapper and overlay guidance for workloads that still use the current overlay pattern during migration

What Stays In railiance-cluster

Wave 1 keeps these concerns in the S2 ownership repo:

• k3s bootstrap and host-to-cluster installation
• cluster backup, restore, smoke, and preflight operations
• operator ownership for ingress, TLS, and other cluster-level components
• cluster access delivery and kubeconfig handling
• substrate-level safety rails

Published Substrate Assumptions

Wave 1 rail-kubernetes may assume:

• a Kubernetes API backed by k3s
• Helm-based apply paths
• operator-driven kubeconfig access
• isolated canary exposure as the safe default
• namespace creation during workload rollout

Wave 1 rail-kubernetes must not assume:

• guaranteed weighted routing
• a generic workload RBAC model
• a generic persistent-storage contract
• a secret-delivery contract at the S2 layer

Migration Constraint

Until the extraction is complete, railiance-cluster remains the compatibility surface for current operators.

The current migration-window handoff is:

• rail-kubernetes/bin/railiance is the canonical owner for the six generic lifecycle commands;
• railiance-cluster/bin/railiance keeps those command names as a thin delegation shim with a temporary local fallback;
• retained S2 operations and non-rail helper debt stay outside this handoff.

See docs/cluster-compatibility-handoff.md for the command-resolution path and operator migration steps.