Add #[kani::loop_decreases] for proving loop termination

[feliperodri]

Implements decreases clauses for loop contracts, enabling Kani to prove loop termination. This addresses the soundness gap where loop abstraction via invariants alone (partial correctness) could verify properties on unreachable code after non-terminating loops.

A decreases clause specifies a measure that must strictly decrease on every loop iteration. CBMC's goto-instrument instruments the termination check automatically, Kani only needs to thread the expression through to the #spec_decreases annotation on the goto irep.

Resolves #3168 (loop contracts — decreases clause portion).

Related: RFC 0012 – Loop Contracts

User-facing syntax

#[kani::loop_invariant(x >= 1)]
#[kani::loop_decreases(x)]
while x > 1 {
    x = x - 1;
}

Multi-dimensional (lexicographic) decreases:

#[kani::loop_decreases(n - i, n - j)]

Implementation

The implementation follows the same pattern as #[kani::loop_modifies] across all layers:

1. CBMC bindings (cprover_bindings/): Add CSpecDecreases irep ID (#spec_decreases), loop_decreases field on Goto statement, with_loop_decreases() builder, and irep serialization.

2. Proc macro (library/kani_macros/): #[kani::loop_decreases(expr)] creates a let kani_loop_decreases = (expr); binding before the loop.

3. Compiler codegen (kani-compiler/): Detect kani_loop_decreases assignments during codegen, store the expression in GotocCtx, and attach it to the loop's goto statement in LoopInvariantRegister::handle().

Tests

12 positive tests covering:

• Basic 1D decreases, arithmetic expressions (n - i), multi-dimensional lexicographic.
• Nested loops (each with own decreases), loop (not just while), struct field projection.
• Combined with loop_modifies, on_entry(), function contracts (requires/ensures).
• Binary search (CBMC docs), Fibonacci (Prusti), loop max (Prusti).

4 negative tests verifying CBMC reports FAILURE on loop_decreases property:

• Non-decreasing measure (loop body doesn't modify variant).
• Wrong measure direction (measure increases).
• Constant measure expression.
• Nested loop where only inner loop fails.

Documentation

Comprehensive additions to docs/src/reference/experimental/loop-contracts.md:

• Partial vs. total correctness: Frames invariants as partial correctness, decreases as the upgrade to total correctness. Introduces the four-step methodology (Establishment, Preservation, Postcondition, Termination).
• Decreases clauses section: Motivation (unsound results without termination), Floyd's method background, syntax, semantics (how CBMC instruments the check), interaction with invariants.
• Limitations comparison: Detailed comparison with Dafny and Verus covering 6 specific gaps (integer-only measures, no auto-inference, no recursive function termination, no decreases *, no side-effect checking, strict decrease only).
• Worked example: Binary search with all four correctness steps walked through, showing how the termination argument depends on the invariant.
• Practical guidance: How to choose invariants, common mistakes (too weak/too strong/wrong decreases) with symptoms, tips for decreases clause patterns.

Call-outs

• The feature requires -Z loop-contracts.
• CBMC does the heavy lifting. Kani just passes the expression through. The CBMC check is assert(new_measure < old_measure) with property class loop_decreases.
• The .expected files for negative tests match on CBMC's property class and description. If CBMC changes these strings, the tests will need updating.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 and MIT licenses.