docs(adr): add ADR-0001 (Rust/kube-rs) and ADR-0002 (cold-start as state)

ADR-0001 records why the operator is built in Rust with kube-rs rather
than Go with controller-runtime: the operator model matters more than the
language, continuity with the project's Rust profiling tools, and kube-rs
being mature enough for the job — while honestly accepting the costs (Go's
more mature ecosystem and wider hiring overlap).

ADR-0002 records the decision that distinguishes this operator from a
generic Deployment wrapper: modeling cold start as an explicit Pending ->
Warming -> Ready lifecycle state, justified by the probe's measurement that
"running" and "able to serve" are different moments for an LLM server. It
also documents the deliberate placeholder data plane as a scope boundary.

Author: MicheleCampi

docs/adr/0001-rust-and-kube-rs.md

@@ -0,0 +1,42 @@
+# ADR-0001: Build the operator in Rust with kube-rs
+
+- Status: Accepted
+- Date: 2026-05-31
+
+## Context
+
+This operator needs a control plane: a CRD, a reconcile loop, owned-resource management, and a status machine. The dominant ecosystem for building Kubernetes operators is Go — Kubernetes itself, controller-runtime, kubebuilder, and operator-sdk are all Go, and the overwhelming majority of production operators are written in it. Choosing the implementation language is therefore a real decision, not a default, and it deserves a record.
+
+The realistic options were:
+
+1. **Go with controller-runtime / kubebuilder** — the ecosystem standard.
+2. **Rust with kube-rs** — a mature but smaller operator framework.
+
+## Decision
+
+Build the operator in Rust with kube-rs.
+
+## Rationale
+
+The decision rests on three points, in order of weight.
+
+1. **The operator model matters more than the language.** What a reviewer or employer should take from this project is that the author understands the Kubernetes control-plane model: custom resources, the reconcile loop, server-side apply, owner references and garbage collection, and the status subresource. That understanding is language-agnostic. Demonstrating it in Rust — where the type system makes the resource shapes and the reconcile contract explicit — is if anything a stronger demonstration that the model is understood rather than scaffolded.
+
+2. **Continuity with the project's existing tooling.** This operator is the operational half of a cold-start research line whose measurement tools (vllm-coldstart-probe, inferscope) are already in Rust. Keeping the operator in the same language keeps the toolchain, the idioms, and the maintainer's productivity coherent across the whole line, rather than splitting it across two ecosystems for one component.
+
+3. **kube-rs is mature enough not to be an obstacle.** kube-rs 2.x provides the CustomResource derive, a Controller runtime with watches and owned-resource retriggering, server-side apply, and status subresource support — everything this operator needs. The reconcile loop, ownership GC, and status machine were all implemented and verified end-to-end against a live cluster without hitting framework limitations.
+
+## Consequences
+
+### What we accept by not using Go
+
+This is the honest cost of the decision, stated plainly:
+
+- **A smaller ecosystem.** Go's operator tooling is more mature: kubebuilder scaffolds projects and RBAC, controller-runtime has a larger body of examples, envtest provides a standard integration-testing harness. In Rust these are either lighter or assembled by hand (here, an end-to-end test on an ephemeral kind cluster in CI plays the role envtest would in Go).
+- **A smaller hiring overlap.** Most teams operating Kubernetes write their controllers in Go. A Rust operator demonstrates the model but is not in the language those teams maintain day to day.
+
+### Why we accept it
+
+The project's purpose is to demonstrate that cold start can be made a first-class control-plane signal, and to demonstrate control-plane competence. Both goals are served by a correct, tested, well-documented operator in the language the author is most effective in. The cost — a less mature framework and a narrower language overlap — is outweighed, for a portfolio control plane built and maintained by one person, by correctness, coherence, and clarity.
+
+A reviewer who maintains operators in Go should read this project as evidence that the author understands the operator model and can pick up controller-runtime quickly, not as a claim that Rust is the better choice for their stack.

docs/adr/0002-coldstart-as-first-class-state.md

@@ -0,0 +1,38 @@
+# ADR-0002: Model cold start as a first-class lifecycle state
+
+- Status: Accepted
+- Date: 2026-05-31
+
+## Context
+
+Kubernetes already has a readiness model: a pod becomes Ready when its readiness probe passes. For most workloads that is enough. For an LLM inference server it is not, because there is a gap between two events that Kubernetes collapses into one:
+
+- the process is up and accepting connections, and
+- the model is loaded, the GPU is warm, and the server can actually serve a token within normal latency.
+
+The vllm-coldstart-probe study measured this gap directly: for a 7B model the cold start is dominated not by disk I/O but by GPU warmup and synchronization after the process is already running, and enabling CUDA graphs makes the gap several times larger. A generic operator that wraps a Deployment inherits Kubernetes' single notion of readiness and therefore cannot distinguish "running" from "warm". An operator born from the profiling work can.
+
+## Decision
+
+Make cold start an explicit, observable lifecycle state on the custom resource, rather than leaving it implicit in pod readiness.
+
+The VllmService status exposes a phase derived from the owned Deployment's ready replicas:
+
+- **Pending** — Deployment created, no replica ready.
+- **Warming** — at least one replica exists but not all desired replicas are ready: the process is up, the server is warming.
+- **Ready** — all desired replicas are ready: warm and able to serve, not merely running.
+
+The warmupStrategy field (Eager / Graph) is part of the same decision: it lets the operator configure the cold-start/throughput trade-off the profiling work quantified, instead of treating it as an opaque deployment detail.
+
+## Rationale
+
+This is the decision that makes the operator more than a Deployment wrapper, and it is not clonable from a generic template: it exists because the cold-start cost was measured, and the measurement is what justifies treating warmth as a state worth modeling. The phase is derived from real Deployment status, not a timer, so it reflects the cluster's actual condition.
+
+## Consequences
+
+- The status is honest about the difference between "running" and "able to serve", which is the difference that matters for scale-to-zero and autoscaling decisions on inference workloads.
+- Future work can attach the measured cost to the state — for example, surfacing the expected cold-start cost per warmupStrategy in the status, so an operator can choose a strategy on the basis of the profiling data rather than a guess.
+
+## Note on the placeholder data plane
+
+On a CPU-only kind cluster the managed pod is a documented placeholder image, and warmupStrategy is recorded as an environment variable rather than driving a real vLLM flag. This is a deliberate scope boundary: the control plane (the lifecycle, ownership, and status modeling described here) is real and tested; the data plane is stubbed because a GPU and a real vLLM image are out of scope for a reproducible local/CI cluster. Validating that the Warming to Ready transition tracks the measured cold start on real vLLM is the next step, recorded in the README roadmap.