fix(felt252): canonicalize non-canonical felt252_const literals

[TomerStarkware]

Summary

felt_to_unsigned (src/utils.rs) only mapped negatives to PRIME - |v| and left positives untouched, so felt252_const<PRIME> (or any literal >= PRIME, or a negative with |v| > PRIME) produced a non-canonical i252 bit pattern. felt252_is_zero compares raw bits, so felt252_const<PRIME> -> felt252_is_zero took the non-zero branch while the VM takes the zero branch. Divergence reproduces at all OptLevels.

Fix: reduce mod PRIME in both arms so the result is always in [0, PRIME). This also covers the other felt_to_unsigned callers (felt252 binary ops with a const operand, const_as_immediate, starknet consts).

Reach: not via on-chain declare (contract-class Sierra caps literals at PRIME−1), but reachable for any consumer fed a .sierra / .sierra.json / programmatic Program (tooling, cairo-native-run, test runners).

Tests

• Unit test utils::tests::test_felt_to_unsigned_canonicalizes (0, 5, -1, PRIME, PRIME+5, -PRIME, -PRIME-1, -2·PRIME+3).
• Hand-written Sierra regression test felt252::test::felt252_const_non_canonical_is_zero — fails on main (const<PRIME> → 222), passes with the fix (→ 111).
• cargo test --lib -- felt252 const starknet: 144 passed; clippy clean.

🤖 Generated with Claude Code

---

This change is 

[github-actions]

Benchmarking results

Benchmark for program dict_insert

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
Cairo-vm (Rust, Cairo 1)	10.508 ± 0.051	10.402	10.580	5.27 ± 0.07
cairo-native (embedded AOT)	1.995 ± 0.026	1.968	2.044	1.00
cairo-native (embedded JIT using LLVM's ORC Engine)	2.012 ± 0.049	1.941	2.078	1.01 ± 0.03

Benchmark for program dict_snapshot

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
Cairo-vm (Rust, Cairo 1)	569.3 ± 10.3	556.1	587.1	1.00
cairo-native (embedded AOT)	1786.8 ± 27.6	1728.7	1829.5	3.14 ± 0.07
cairo-native (embedded JIT using LLVM's ORC Engine)	1786.6 ± 25.9	1743.4	1829.2	3.14 ± 0.07

Benchmark for program factorial_2M

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
Cairo-vm (Rust, Cairo 1)	4.615 ± 0.074	4.564	4.813	2.58 ± 0.06
cairo-native (embedded AOT)	1.791 ± 0.034	1.761	1.884	1.00
cairo-native (embedded JIT using LLVM's ORC Engine)	1.828 ± 0.032	1.783	1.882	1.02 ± 0.03

Benchmark for program fib_2M

Open benchmarks

Command	Mean [s]	Min [s]	Max [s]	Relative
Cairo-vm (Rust, Cairo 1)	4.513 ± 0.052	4.452	4.641	2.52 ± 0.05
cairo-native (embedded AOT)	1.787 ± 0.026	1.753	1.840	1.00
cairo-native (embedded JIT using LLVM's ORC Engine)	1.844 ± 0.049	1.794	1.974	1.03 ± 0.03

Benchmark for program linear_search

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
Cairo-vm (Rust, Cairo 1)	631.5 ± 10.2	614.6	643.9	1.00
cairo-native (embedded AOT)	1826.0 ± 49.1	1766.7	1925.3	2.89 ± 0.09
cairo-native (embedded JIT using LLVM's ORC Engine)	1822.0 ± 32.0	1761.9	1853.5	2.89 ± 0.07

Benchmark for program logistic_map

Open benchmarks

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
Cairo-vm (Rust, Cairo 1)	520.3 ± 10.2	507.5	536.2	1.00
cairo-native (embedded AOT)	1768.3 ± 26.3	1716.1	1805.3	3.40 ± 0.08
cairo-native (embedded JIT using LLVM's ORC Engine)	1788.3 ± 61.3	1728.1	1901.6	3.44 ± 0.14

[github-actions]

Benchmark results Main vs HEAD.

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base dict_insert.cairo (JIT)	1.926 ± 0.036	1.879	1.978	1.04 ± 0.02
base dict_insert.cairo (AOT)	1.844 ± 0.025	1.813	1.890	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head dict_insert.cairo (JIT)	1.802 ± 0.013	1.781	1.822	1.01 ± 0.01
head dict_insert.cairo (AOT)	1.780 ± 0.012	1.768	1.805	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base dict_snapshot.cairo (JIT)	1.659 ± 0.020	1.636	1.704	1.01 ± 0.02
base dict_snapshot.cairo (AOT)	1.647 ± 0.021	1.615	1.674	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head dict_snapshot.cairo (JIT)	1.616 ± 0.007	1.605	1.625	1.01 ± 0.01
head dict_snapshot.cairo (AOT)	1.593 ± 0.011	1.582	1.620	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base factorial_2M.cairo (JIT)	1.713 ± 0.019	1.681	1.742	1.00 ± 0.02
base factorial_2M.cairo (AOT)	1.712 ± 0.022	1.685	1.752	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head factorial_2M.cairo (JIT)	1.682 ± 0.005	1.673	1.687	1.01 ± 0.00
head factorial_2M.cairo (AOT)	1.661 ± 0.002	1.657	1.664	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base fib_2M.cairo (JIT)	1.691 ± 0.028	1.655	1.739	1.02 ± 0.03
base fib_2M.cairo (AOT)	1.666 ± 0.044	1.620	1.760	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head fib_2M.cairo (JIT)	1.619 ± 0.008	1.608	1.629	1.01 ± 0.01
head fib_2M.cairo (AOT)	1.596 ± 0.005	1.590	1.606	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base linear_search.cairo (JIT)	1.768 ± 0.029	1.722	1.814	1.03 ± 0.02
base linear_search.cairo (AOT)	1.711 ± 0.021	1.679	1.744	1.00

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head linear_search.cairo (JIT)	1.649 ± 0.008	1.635	1.661	1.02 ± 0.01
head linear_search.cairo (AOT)	1.615 ± 0.004	1.609	1.622	1.00

Base

Command	Mean [s]	Min [s]	Max [s]	Relative
base logistic_map.cairo (JIT)	1.708 ± 0.029	1.669	1.760	1.00
base logistic_map.cairo (AOT)	1.723 ± 0.044	1.672	1.798	1.01 ± 0.03

Head

Command	Mean [s]	Min [s]	Max [s]	Relative
head logistic_map.cairo (JIT)	1.632 ± 0.004	1.625	1.637	1.02 ± 0.00
head logistic_map.cairo (AOT)	1.605 ± 0.004	1.599	1.613	1.00

[orizi]

@orizi reviewed 2 files and all commit messages, and made 1 comment.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on TomerStarkware).