fix(core): stop the paged budget test underflowing past the v2 reserve

[inureyes]

Summary

execution::memory_estimate::tests::resolve_block_budget_explicit_bytes_floors_to_block_count failed deterministically in 0.00s on GB10 / CUDA sm_121 / Linux aarch64 at assertion failed: shortfall < 100. The test computed its own expected value with (per_block * 100 - workspace) / per_block, an unsigned subtraction of a device-derived reserve from a fixed budget. device_target_ctas() returns 512 on every non-Metal host, putting the paged decode v2 workspace reserve at 16.25 MiB for this geometry against a 12.5 MiB budget, so the u64 subtraction wrapped and shortfall became 2^47 - 31.

Where the underflow lives: test-only, confirmed

The issue's evidence said test-only and the acceptance criteria required confirming or refuting that rather than assuming it. Both halves of the confirmation are here.

paged_v2_workspace_reserve_bytes has exactly four call sites in the tree:

Site	Subtracts from a budget?	Arithmetic
memory_estimate.rs (resolve_paged_block_budget, production)	yes	saturating_sub, already correct
memory_estimate.rs (the failing test)	yes	-, wraps
the_v2_workspace_reserve_is_small_and_scales_with_the_head_dim, 2 sites	no	measurement only

One subtraction in non-test code, and it already saturated. The claim does not rest on the grep: the new resolve_block_budget_below_the_workspace_reserve_is_zero_blocks calls the production function at budgets of 0, 1, workspace / 2, workspace - 1 and workspace and requires Some(0) for each. A wrapping - would return a block count near 2^47 for the last three (a budget near u64::MAX over a 128 KiB block, not usize::MAX, which on this host the try_from never reaches). The test is green, so the implementation is measured clean, not read clean.

What changed

• src/execution/memory_estimate.rs
  • resolve_paged_block_budget: a comment recording why the subtraction must saturate, with the numbers that make a sub-reserve budget reachable on any non-Metal host, so the saturating_sub is not "simplified" back to - later.
  • resolve_block_budget_explicit_bytes_floors_to_block_count: the wrapping - becomes saturating_sub; the arithmetic sanity check shortfall < 100 is replaced by the exact-reserve contract stated twice, so neither statement is vacuous on any host. Capped: 100 - shortfall == min(ceil(workspace / per_block), 100), an identity below the crossover and pinned at 100 above it. Uncapped: asking for per_block * (100 + ceil(workspace / per_block)) bytes resolves to exactly 100 blocks, which exercises the exact-reserve arithmetic on large-CTA devices rather than leaving it covered only on small Apple parts. All reserve-derived request and expectation arithmetic in the test is now saturating, since test-fast inherits release and would otherwise wrap silently into a wrong expectation rather than panicking.
  • New resolve_block_budget_below_the_workspace_reserve_is_zero_blocks, pinning the boundary from both sides: workspace + per_block - 1 yields Some(0), workspace + per_block yields Some(1).
• src/server/model_worker.rs: the zero-block arm of resolve_worker_paged_block_budget emitted one message for both directives, and it blamed model size and available memory. That is the right diagnosis for --kv-cache-budget auto and the wrong one for an explicit byte budget, where on a non-Metal host anything under roughly 16 MiB lands there regardless of model size. The arm now matches on the directive: Auto keeps its original wording, and Bytes reports the requested budget, the reserve, and the smallest budget that would mint one block, through the module's format_bytes. The issue asked whether the Some(0) path is reachable and handled by callers rather than assumed; it is reachable, and the caller already warns and leaves the pool unbounded rather than installing a wedging zero budget. Only message text changed.
• CHANGELOG.md: one ### Fixed entry under ## [Unreleased], stating explicitly that no budget resolves to a different block count and that auto keeps its message.

The MLXCEL_PAGED_DECODE_V2_TARGET_CTAS override was rejected. device_target_ctas() memoizes through a OnceLock, so pinning it inside a test is order-dependent under a shared test binary, which would trade a deterministic failure for an order-dependent one.

Review round

A review pass found that the first version of the warning gave the reserve-naming message to Auto as well. It is accurate there (budget < reserve + per_block holds either way) but misleading, since Auto is the shipped default and reaches zero blocks when the model leaves no room for KV at all, where the real shortfall is tens of gigabytes and the reserve is a red herring. Fixed by splitting on the directive. The same pass corrected the magnitude of the wrapped block count from usize::MAX to roughly 2^47, in the code comments, the tests, this body, and the committed report.

Test plan

• cargo test --profile test-fast --features cuda --lib -- --exact execution::memory_estimate::tests::resolve_block_budget_explicit_bytes_floors_to_block_count on GB10, the case that failed before
• cargo test --profile test-fast --features cuda --lib execution::memory_estimate on GB10: 36 passed, 0 failed
• cargo clippy --profile test-fast --features cuda --lib --tests -- -D warnings
• cargo fmt --all -- --check

Not covered: the Apple small-CTA branch was not run on hardware. It is covered by construction rather than by execution, since every assertion is now either an identity over the measured workspace or a request computed from it. --test-threads=1 was not used; the full lib suite aborts under parallel execution on this CUDA host for reasons unrelated to this change, so the module filter above is the equivalent evidence. The changed warning text was read, not observed in a live server log.

Closes #1091