address Sam and Mike comments

Signed-off-by: Antonio Ojea <aojea@google.com>

Author: aojea

docs/pod-sandbox-lifecycle.md

@@ -5,7 +5,7 @@
 This specification defines how NRI plugins interact with pod sandbox lifecycle events. The underlying pod sandbox operations are defined by the [Kubernetes CRI API](https://github.com/kubernetes/cri-api):
 
 - **RunPodSandbox (CRI)**: Creates and starts a pod-level sandbox. Runtimes must ensure the sandbox is in the ready state on success.
-- **StopPodSandbox (CRI)**: Stops any running process that is part of the sandbox and reclaims network resources.
+- **StopPodSandbox (CRI)**: Stops any running process that is part of the sandbox and directs the runtime to reclaim certain pod resources (e.g. Network Namespace, CNI teardown, and image mounts). May be called multiple times, and is idempotent.
 - **RemovePodSandbox (CRI)**: Removes the sandbox. If there are any running containers, they must be forcibly terminated and removed.
 
 This NRI specification details when and under what conditions NRI plugins receive notifications for these events, ensuring plugins can reliably depend on consistent sandbox state across different runtime implementations.
@@ -14,7 +14,7 @@ This NRI specification details when and under what conditions NRI plugins receiv
 
 The pod sandbox lifecycle consists of three distinct phases, each with a corresponding NRI event that plugins can subscribe to:
 
-1. **RunPodSandbox**: Fired after the runtime successfully executes CRI RunPodSandbox
+1. **RunPodSandbox**: Fired during the the runtime CRI RunPodSandbox execution, after the PodSandbox is created but before setting the pod to running and then replying success to CRI RunPodSandbox request.
 2. **StopPodSandbox**: Fired when the runtime initiates CRI StopPodSandbox
 3. **RemovePodSandbox**: Fired when the runtime performs CRI RemovePodSandbox
 
@@ -27,7 +27,7 @@ For each event, this specification defines:
 
 **CRI Operation**: RunPodSandbox - Creates and starts a pod-level sandbox.
 
-**NRI Event Timing**: The RunPodSandbox NRI event is fired after the runtime has successfully executed the CRI RunPodSandbox operation and the sandbox has reached a "Ready" state, but before any workload containers are started.
+**NRI Event Timing**: The RunPodSandbox NRI event is fired after the runtime has successfully executed most of the CRI RunPodSandbox operation; NRI plugin execution is the final step before the sandbox reaches a "Ready" state. The Kubelet does not start workload containers until after the sandbox becomes "Ready".
 
 ### Sandbox State Contract
 
@@ -38,7 +38,7 @@ When the runtime fires the RunPodSandbox NRI event, it guarantees:
 - Network setup has been fully configured (network interfaces are up and assigned addressing)
 - The pod IP address (if applicable) is assigned and available
 - The "pause" container (if the runtime uses one) is running
-- All prerequisite operations for workload container startup are complete
+- All prerequisite operations for workload container startup are complete, the pod is in the "unknown state" and will become "Ready" once the NRI event is processed. This guarantees the NRI plugin has a window to allocate resources for the pod before any workload containers are started.
 
 ### Plugin Responsibilities and Capabilities
 
@@ -64,7 +64,7 @@ When the runtime fires the StopPodSandbox NRI event, it guarantees:
 
 - Workload containers within the sandbox are stopped or are stopping
 - **CRITICAL**: The sandbox infrastructure still exists and remains fully accessible during this hook
-- The network namespace is not unmounted or deleted until this hook completes
+- The pod resources allocated by the runtime; such as network namespace, CNI networks, and image mounts; are not unmounted or deleted until this hook completes
 - The pod's cgroups remain accessible
 - All pod-level resources remain stable until this hook returns
 
@@ -84,7 +84,7 @@ StopPodSandbox is the designated cleanup and observation phase for plugins. Upon
 
 **CRI Operation**: RemovePodSandbox - Removes the sandbox and forcibly terminates any remaining containers.
 
-**NRI Event Timing**: The RemovePodSandbox NRI event is fired when the runtime initiates the CRI RemovePodSandbox operation, during final garbage collection.
+**NRI Event Timing**: The RemovePodSandbox NRI event is fired when the runtime initiates the CRI RemovePodSandbox operation, just prior to removing the pod from the pod list.
 
 ### Sandbox State Contract
 
@@ -114,8 +114,8 @@ Plugins receiving this event should only:
 
 Runtimes MUST guarantee the following ordering:
 
-1. **RunPodSandbox** NRI event fires after successful CRI RunPodSandbox execution
-2. **StopPodSandbox** NRI event fires during CRI StopPodSandbox execution
+1. **RunPodSandbox** NRI event fires after successful CRI RunPodSandbox execution, but before the pod is set to the "Ready" state.
+2. **StopPodSandbox** NRI event fires during CRI StopPodSandbox execution, just prior to removing the runtime pod resources allocated by the runtime; such as network namespace, CNI networks, and image mounts
 3. **RemovePodSandbox** NRI event fires during CRI RemovePodSandbox execution
 4. These events MUST fire in strict order: RunPodSandbox → StopPodSandbox → RemovePodSandbox
 5. No workload containers will be started until after RunPodSandbox hook completes