From 1e4e0ea5dffcd9831375616e63ba0ea6807641e0 Mon Sep 17 00:00:00 2001
From: "cortex-ai-agents[bot]"
 <279748396+cortex-ai-agents[bot]@users.noreply.github.com>
Date: Mon, 8 Jun 2026 07:51:50 +0000
Subject: [PATCH] docs: document candidate reservation cleanup on VM confirm

---
 docs/reservations/committed-resource-reservations.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/reservations/committed-resource-reservations.md b/docs/reservations/committed-resource-reservations.md
index 4d96d43a6..e335e79b4 100644
--- a/docs/reservations/committed-resource-reservations.md
+++ b/docs/reservations/committed-resource-reservations.md
@@ -220,6 +220,8 @@ stateDiagram-v2
     Confirmed --> [*] : not on HV CRD
 ```
 
+**Candidate reservation cleanup**: When a VM is newly confirmed on a reservation (transitions from Spec-only to Spec+Status for the first time), the controller immediately removes that VM's UUID from `Spec.Allocations` on all other candidate reservations that still carry it. This proactive cleanup frees phantom capacity blocks on non-selected hosts immediately rather than waiting for each candidate reservation's own grace period expiry or periodic requeue to detect that the VM landed elsewhere.
+
 **Note**: VM allocations may not consume all resources of a reservation slot. A reservation with 128 GB may have VMs totaling only 96 GB if that fits the project's needs. Allocations may exceed reservation capacity (e.g., after VM resize).
 
 #### Capacity Blocking