# 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.