# ADR-0002: Wave 1 `rail-kubernetes` Boundary

Date: 2026-07-25
Status: Accepted

## Context

Railiance wants `rail-*` repos to represent workload execution contracts rather
than abstract naming ideas.

Today, the concrete Kubernetes workload contract already exists, but it is
embedded in `railiance-cluster`. That repo currently owns both:

- the S2 Kubernetes substrate
- and the generic workload lifecycle and tooling that run on top of it

That mixed ownership is the main blocker to introducing the first real rail.

## Decision

Railiance will treat `rail-kubernetes` as the wave-1 base rail.

The boundary is:

- `railiance-cluster` owns the Kubernetes substrate and its prerequisites
- `rail-kubernetes` owns the generic workload-on-Kubernetes execution contract

Workload-specific helper flows currently living in `railiance-cluster` are
temporary exceptions and must be rehomed rather than carried forward as part of
the generic rail.

## Consequences

### Positive

- The first real rail gains a concrete ownership boundary.
- `railiance-cluster` can return to a clean S2 substrate identity.
- Future rails such as `rail-knative` get a stable base boundary to extend from.
- `rapp-*` repos gain a clearer execution-contract home for Kubernetes-managed
  workloads.

### Required Follow-On Work

- Create the detailed `rail-kubernetes` boundary contract and migration map.
- Split generic lifecycle docs, schema, examples, and Stage 1-3 tooling out of
  `railiance-cluster`.
- Leave a compatibility path so current users of the cluster repo are not
  broken during the migration.
- Rehome workload-specific helpers that do not belong in either boundary.

### Constraints

- `rail-kubernetes` must not take ownership of cluster bootstrap, operators, or
  kubeconfig management.
- `railiance-cluster` must not continue as the owner of generic workload
  promotion semantics after the split.
- `rail-knative` should follow this cleanup, not bypass it.

## Notes

This ADR does not require all current files to move immediately.

It requires the ownership line to be explicit now, so practical repo separation
can proceed without ambiguity.