[Madubuezejoshua]

Closes #1394

Enforce the inclusive reserve cap against the tracked USDC balance before deposit writes or transfers, preserve validation order, remove the duplicate pause lookup, and return Overflow for unrepresentable finite-cap sums. Unset/MAX caps retain the arithmetic-free fast path. Lowering a cap below balance blocks deposits while withdrawals/deducts keep their existing rules. Reject non-USDC cap tokens with typed code 59; legacy numeric errors are unchanged (a separate setter error enum avoids the existing 50-case XDR limit).

Regression: unchanged production baseline f4ab47e incorrectly accepts 900 + 101 under cap 1000: actual assertion output unexpected result: Ok(Ok(())), expected code 43. The same regression now passes with storage, token-balance and event atomicity checks. Final base is 87fba99; its vault production sources match the baseline.

Validation:

• cargo test -p callora-vault reserve_cap -- --nocapture: 20 passed, none failed/ignored.
• cargo fmt -p callora-vault -- --check and required release WASM build for vault, settlement and revenue-pool: passed.
• Latest-base global fmt, workspace tests and workspace clippy are blocked by unchanged upstream yield/checkpoint/registry errors, detailed in docs/RESERVE_CAP_1394_VALIDATION.md. On the initial base plus this fix, workspace tests passed: 1873 passed, 170 existing ignored.
• Native Soroban CPU estimates (baseline -> updated): unset 272314 -> 272457 (+143, 0.053%); explicit MAX 278427 -> 280700 (+2273, 0.816%); finite 277838 -> 279806 (+1968, 0.708%). Setup excluded; one SDK cap lookup, not one raw host call or CPU instruction.

Coverage: cargo llvm-cov --lib -p callora-vault --json --output-path coverage.json -- reserve_cap (cargo-llvm-cov 0.9.1, LLVM 22.1.8): deposit 38/38 lines (100%); limits::check 18/18 lines (100%). Individual function report; 18 instrumented tests passed.

Previously stored USDC caps become effective when adopted. Rust callers explicitly typing the setter result as VaultError need a source update. No storage/dependency/CI changes or deployment. See docs/RESERVE_CAP_1394_VALIDATION.md for evidence, commands and limitations.

CI verified: run 39308249244 failed at formatting because unchanged contracts/yield/src/lib.rs:26 places an inner attribute after an outer doc comment. Workspace-test and WASM CI steps were skipped. This is the same inherited failure reproduced locally; the PR stays draft.

[drips-wave]

@Madubuezejoshua Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[greatest0fallt1me]

This PR is still marked as a draft, so it can't be reviewed or merged yet. When it's ready, please rebase onto the latest default branch, make sure CI passes, and click Ready for review. Note: PRs that change .vscode/, .devcontainer/, dist/, api.js, font or binary files, or package lifecycle scripts are rejected by our security scan.