docs: state leaving the state unchanged on failure as a requirement

The function's doc comment presented it as a consequence of performing the
withdrawal before the refund, and did not mention it at all where the error is
documented. State the requirement first and the order as the means, in both the
function's and the test's doc comment, without spelling out what the callers do
with it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: mraszyk

rs/cycles_account_manager/src/cycles_account_manager.rs

@@ -890,12 +890,14 @@ impl CyclesAccountManager {
     /// it ends up with exactly the prepayment that the cost schedule in effect at
     /// response time requires.
     ///
-    /// The withdrawal is performed before the refund so that a failing withdrawal
-    /// leaves the canister state unchanged, as the callers expect.
+    /// A failing adjustment must leave the canister state unchanged: neither the
+    /// balance nor the consumed cycles metrics may move. The withdrawal is therefore
+    /// performed before the refund, which cannot fail.
     ///
     /// Returns the prepayment matching the cycles required for executing the response
     /// in the given Wasm execution mode, or a `CanisterOutOfCyclesError` if the
-    /// canister's balance does not cover the additional prepayment.
+    /// canister's balance does not cover the additional prepayment, in which case
+    /// the canister state is left unchanged.
     pub fn adjust_prepayment_for_response_execution(
         &self,
         system_state: &mut SystemState,

rs/cycles_account_manager/tests/cycles_account_manager.rs

@@ -555,19 +555,9 @@ fn response_execution_cycles_match_response_execution_setting() {
 }
 
 /// If the canister's balance does not cover the cycles missing from the
-/// prepayment, then the adjustment fails and leaves the canister state unchanged.
-///
-/// Both of its call sites in `rs/execution_environment/src/execution/response.rs`
-/// rely on that, since both go on to settle the *unadjusted* prepayment: the
-/// `ResponseHelper` method wrapping the adjustment records the adjusted prepayment
-/// only on success, so what a failure leaves to be settled is the prepayment
-/// recorded in the callback. `execute_response` rejects the response without
-/// executing the callback, settling that prepayment in
-/// `settle_prepayment_for_unexecuted_response`; `ResponseHelper::resume` turns the
-/// failure of replaying the adjustment on the clean canister state into a Wasm
-/// execution error, which ends up settling it in `refund_unused_execution_cycles`.
-/// Either way, an excess that a failed adjustment had already refunded would be
-/// refunded a second time.
+/// prepayment, then the adjustment fails and leaves the canister state unchanged:
+/// neither the balance nor the consumed cycles metrics move. That is a requirement
+/// of `adjust_prepayment_for_response_execution` which its callers rely on.
 ///
 /// In the second setting below the prepayment falls short of the requirement in
 /// the real part while exceeding it in the nominal one, so that the excess to be