refactor: add function_runner feature flag and CairoFunctionRunner alias

[naor-starkware]

TITLE

Description

Description of the pull request changes and motivation.

Checklist

• Linked to Github Issue
• Unit tests added
• Integration tests added.
• This change requires new documentation.
  • Documentation has been added/updated.
  • CHANGELOG has been updated.

---

This change is 

[naor-starkware]

• feat: add math cairo tests under vm/src/tests/cairo_test_suite #2379
• feat(makefile,ci): add cairo_test_suite_programs target and CI integration #2380
• feat: add test_helpers module (error_utils, test_utils) behind function_runner flag #2378
• refactor: add function_runner feature flag and CairoFunctionRunner alias #2377 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

**Hyper Thereading Benchmark results**




hyperfine -r 2 -n "hyper_threading_main threads: 1" 'RAYON_NUM_THREADS=1 ./hyper_threading_main' -n "hyper_threading_pr threads: 1" 'RAYON_NUM_THREADS=1 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 1
  Time (mean ± σ):     22.674 s ±  0.006 s    [User: 22.093 s, System: 0.578 s]
  Range (min … max):   22.670 s … 22.678 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 1
  Time (mean ± σ):     22.679 s ±  0.043 s    [User: 22.080 s, System: 0.596 s]
  Range (min … max):   22.648 s … 22.709 s    2 runs
 
Summary
  hyper_threading_main threads: 1 ran
    1.00 ± 0.00 times faster than hyper_threading_pr threads: 1




hyperfine -r 2 -n "hyper_threading_main threads: 2" 'RAYON_NUM_THREADS=2 ./hyper_threading_main' -n "hyper_threading_pr threads: 2" 'RAYON_NUM_THREADS=2 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 2
  Time (mean ± σ):     12.261 s ±  0.029 s    [User: 22.195 s, System: 0.632 s]
  Range (min … max):   12.241 s … 12.282 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 2
  Time (mean ± σ):     12.219 s ±  0.032 s    [User: 22.191 s, System: 0.622 s]
  Range (min … max):   12.196 s … 12.241 s    2 runs
 
Summary
  hyper_threading_pr threads: 2 ran
    1.00 ± 0.00 times faster than hyper_threading_main threads: 2




hyperfine -r 2 -n "hyper_threading_main threads: 4" 'RAYON_NUM_THREADS=4 ./hyper_threading_main' -n "hyper_threading_pr threads: 4" 'RAYON_NUM_THREADS=4 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 4
  Time (mean ± σ):      9.732 s ±  0.116 s    [User: 35.147 s, System: 0.742 s]
  Range (min … max):    9.650 s …  9.813 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 4
  Time (mean ± σ):     10.096 s ±  0.048 s    [User: 35.081 s, System: 0.733 s]
  Range (min … max):   10.061 s … 10.130 s    2 runs
 
Summary
  hyper_threading_main threads: 4 ran
    1.04 ± 0.01 times faster than hyper_threading_pr threads: 4




hyperfine -r 2 -n "hyper_threading_main threads: 6" 'RAYON_NUM_THREADS=6 ./hyper_threading_main' -n "hyper_threading_pr threads: 6" 'RAYON_NUM_THREADS=6 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 6
  Time (mean ± σ):      9.638 s ±  0.196 s    [User: 35.513 s, System: 0.756 s]
  Range (min … max):    9.499 s …  9.777 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 6
  Time (mean ± σ):      9.487 s ±  0.005 s    [User: 35.892 s, System: 0.781 s]
  Range (min … max):    9.483 s …  9.490 s    2 runs
 
Summary
  hyper_threading_pr threads: 6 ran
    1.02 ± 0.02 times faster than hyper_threading_main threads: 6




hyperfine -r 2 -n "hyper_threading_main threads: 8" 'RAYON_NUM_THREADS=8 ./hyper_threading_main' -n "hyper_threading_pr threads: 8" 'RAYON_NUM_THREADS=8 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 8
  Time (mean ± σ):      9.445 s ±  0.015 s    [User: 36.055 s, System: 0.760 s]
  Range (min … max):    9.435 s …  9.455 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 8
  Time (mean ± σ):      9.498 s ±  0.032 s    [User: 36.233 s, System: 0.786 s]
  Range (min … max):    9.475 s …  9.521 s    2 runs
 
Summary
  hyper_threading_main threads: 8 ran
    1.01 ± 0.00 times faster than hyper_threading_pr threads: 8




hyperfine -r 2 -n "hyper_threading_main threads: 16" 'RAYON_NUM_THREADS=16 ./hyper_threading_main' -n "hyper_threading_pr threads: 16" 'RAYON_NUM_THREADS=16 ./hyper_threading_pr'
Benchmark 1: hyper_threading_main threads: 16
  Time (mean ± σ):      9.554 s ±  0.073 s    [User: 36.207 s, System: 0.807 s]
  Range (min … max):    9.502 s …  9.606 s    2 runs
 
Benchmark 2: hyper_threading_pr threads: 16
  Time (mean ± σ):      9.700 s ±  0.263 s    [User: 36.048 s, System: 0.812 s]
  Range (min … max):    9.514 s …  9.887 s    2 runs
 
Summary
  hyper_threading_main threads: 16 ran
    1.02 ± 0.03 times faster than hyper_threading_pr threads: 16

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.07%. Comparing base (f7ac327) to head (687552e).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2377   +/-   ##
=======================================
  Coverage   96.07%   96.07%           
=======================================
  Files         105      105           
  Lines       37737    37737           
=======================================
  Hits        36254    36254           
  Misses       1483     1483           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[OmriEshhar1]

@OmriEshhar1 reviewed 3 files and all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on efrat-starkware and YairVaknin-starkware).

[github-actions]

Benchmark Results for unmodified programs 🚀

Command	Mean [s]	Min [s]	Max [s]	Relative
base big_factorial	2.101 ± 0.020	2.087	2.151	1.00 ± 0.01
head big_factorial	2.095 ± 0.010	2.083	2.119	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base big_fibonacci	2.029 ± 0.013	2.016	2.062	1.00
head big_fibonacci	2.034 ± 0.009	2.015	2.050	1.00 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base blake2s_integration_benchmark	7.382 ± 0.025	7.339	7.404	1.00
head blake2s_integration_benchmark	7.427 ± 0.098	7.344	7.609	1.01 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base compare_arrays_200000	2.178 ± 0.018	2.149	2.210	1.01 ± 0.01
head compare_arrays_200000	2.160 ± 0.013	2.142	2.177	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base dict_integration_benchmark	1.405 ± 0.003	1.400	1.409	1.00
head dict_integration_benchmark	1.405 ± 0.004	1.397	1.411	1.00 ± 0.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base field_arithmetic_get_square_benchmark	1.220 ± 0.005	1.213	1.230	1.00
head field_arithmetic_get_square_benchmark	1.223 ± 0.010	1.214	1.244	1.00 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base integration_builtins	7.470 ± 0.020	7.438	7.502	1.00
head integration_builtins	7.474 ± 0.022	7.437	7.510	1.00 ± 0.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base keccak_integration_benchmark	7.562 ± 0.042	7.529	7.674	1.00
head keccak_integration_benchmark	7.589 ± 0.042	7.541	7.659	1.00 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base linear_search	2.155 ± 0.020	2.129	2.195	1.00 ± 0.01
head linear_search	2.145 ± 0.011	2.126	2.163	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_cmp_and_pow_integration_benchmark	1.489 ± 0.007	1.481	1.502	1.00
head math_cmp_and_pow_integration_benchmark	1.498 ± 0.016	1.480	1.541	1.01 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base math_integration_benchmark	1.450 ± 0.008	1.438	1.465	1.00
head math_integration_benchmark	1.453 ± 0.007	1.442	1.463	1.00 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base memory_integration_benchmark	1.209 ± 0.006	1.201	1.222	1.00
head memory_integration_benchmark	1.210 ± 0.005	1.201	1.215	1.00 ± 0.01

Command	Mean [s]	Min [s]	Max [s]	Relative
base operations_with_data_structures_benchmarks	1.539 ± 0.024	1.522	1.604	1.00 ± 0.02
head operations_with_data_structures_benchmarks	1.535 ± 0.015	1.521	1.572	1.00

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base pedersen	531.2 ± 1.7	529.9	535.7	1.00 ± 0.00
head pedersen	530.9 ± 1.5	528.6	533.1	1.00

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base poseidon_integration_benchmark	614.4 ± 5.0	609.9	627.0	1.00 ± 0.01
head poseidon_integration_benchmark	612.3 ± 5.0	606.9	623.0	1.00

Command	Mean [s]	Min [s]	Max [s]	Relative
base secp_integration_benchmark	1.811 ± 0.018	1.796	1.857	1.00 ± 0.01
head secp_integration_benchmark	1.810 ± 0.017	1.794	1.847	1.00

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
base set_integration_benchmark	665.1 ± 16.1	657.6	709.7	1.00
head set_integration_benchmark	684.4 ± 78.8	657.6	908.6	1.03 ± 0.12

Command	Mean [s]	Min [s]	Max [s]	Relative
base uint256_integration_benchmark	4.230 ± 0.029	4.198	4.283	1.00 ± 0.01
head uint256_integration_benchmark	4.211 ± 0.016	4.180	4.244	1.00

[OmriEshhar1]

Reviewable status: complete! all files reviewed, all discussions resolved (waiting on efrat-starkware and YairVaknin-starkware).

[OmriEshhar1]

@OmriEshhar1 reviewed 1 file and all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on efrat-starkware and YairVaknin-starkware).

[OmriEshhar1]

Reviewable status: complete! all files reviewed, all discussions resolved (waiting on efrat-starkware and YairVaknin-starkware).

[Yael-Starkware]

@Yael-Starkware made 1 comment.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on efrat-starkware, naor-starkware, and YairVaknin-starkware).

---

vm/Cargo.toml line 24 at r2 (raw file):

# Note that these features are not retro-compatible with the cairo Python VM.
function_runner = []

why do you need a separate feature flag for this?

Code quote:

function_runner = []

[naor-starkware]

vm/Cargo.toml line 24 at r2 (raw file):

Previously, Yael-Starkware (YaelD) wrote…

why do you need a separate feature flag for this?

function_runner needs to be exposed to proving-utils, so instead of pulling in everything under test_utils, I added a separate feature flag that exposes only what's relevant to function_runner

[Yael-Starkware]

@Yael-Starkware made 1 comment.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on efrat-starkware, naor-starkware, and YairVaknin-starkware).

---

vm/Cargo.toml line 24 at r2 (raw file):

Previously, naor-starkware wrote…

function_runner needs to be exposed to proving-utils, so instead of pulling in everything under test_utils, I added a separate feature flag that exposes only what's relevant to function_runner

is it needed by proving utils only for testing?

[Yael-Starkware]

@Yael-Starkware made 1 comment.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on efrat-starkware, naor-starkware, and YairVaknin-starkware).

---

vm/Cargo.toml line 24 at r2 (raw file):

Previously, Yael-Starkware (YaelD) wrote…

is it needed by proving utils only for testing?

can you explain the dependency graph here?
who uses test_utils and who uses function_runner?

[naor-starkware]

vm/Cargo.toml line 24 at r2 (raw file):

Previously, Yael-Starkware (YaelD) wrote…

can you explain the dependency graph here?
who uses test_utils and who uses function_runner?

test_utils implies function_runner - enabling test_utils automatically enables function_runner. You can enable function_runner alone
without getting test_utils.

function_runner
▲
│ (implied by)
test_utils
│ also implies
├── dep:arbitrary
├── starknet-types-core/arbitrary
└── starknet-types-core/std

Nobody directly. No crate in the workspace enables it alone. It only gets activated transitively when test_utils is enabled.

It exists as a standalone flag so that external consumers (e.g. Starknet ,Proving-utlis) can use just CairoFunctionRunner + test_helpers
without pulling in arbitrary and fuzzing infrastructure

[naor-starkware]

vm/Cargo.toml line 24 at r2 (raw file):

is it needed by proving utils only for testing?

This infrastructure is only needed for tests. If proving-utils needs it, it would only be for test usage.

[Yael-Starkware]

@Yael-Starkware made 1 comment.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on efrat-starkware, naor-starkware, and YairVaknin-starkware).

---

vm/Cargo.toml line 24 at r2 (raw file):

Previously, naor-starkware wrote…

is it needed by proving utils only for testing?

This infrastructure is only needed for tests. If proving-utils needs it, it would only be for test usage.

If both flags are for testing only, please drop function_runner for simplicity.
This separation is just more flags for users to discover and manage.

[Yael-Starkware]

@Yael-Starkware made 2 comments.
Reviewable status: 1 of 4 files reviewed, 3 unresolved discussions (waiting on efrat-starkware, naor-starkware, OmriEshhar1, and YairVaknin-starkware).

---

vm/src/vm/runners/function_runner.rs line 4 at r3 (raw file):

//!
//! Provides a simplified API for executing individual Cairo 0 functions by name or PC.
//! Enabled by the `function_runner` feature flag.

remove.

Code quote:

//! Enabled by the `function_runner` feature flag.

---

vm/src/vm/runners/function_runner.rs line 23 at r3 (raw file):

/// Type alias for [`CairoRunner`] with testing methods enabled.
/// Mirrors the Python `CairoFunctionRunner` class interface.
pub type CairoFunctionRunner = CairoRunner;

why do you need another type?

Code quote:

/// Type alias for [`CairoRunner`] with testing methods enabled.
/// Mirrors the Python `CairoFunctionRunner` class interface.
pub type CairoFunctionRunner = CairoRunner;

[Yael-Starkware]

@Yael-Starkware resolved 1 discussion.
Reviewable status: 1 of 4 files reviewed, 2 unresolved discussions (waiting on efrat-starkware, naor-starkware, OmriEshhar1, and YairVaknin-starkware).

[naor-starkware]

vm/src/vm/runners/function_runner.rs line 23 at r3 (raw file):

Previously, Yael-Starkware (YaelD) wrote…

why do you need another type?

It's a semantic alias, not a technical one. CairoRunner is the general execution engine. CairoFunctionRunner communicates that
you're using it specifically to invoke individual functions by name/PC - the same way the Python CairoFunctionRunner did. Without the
alias, every test file looks identical whether it's running a full program or calling a function entry point.

[Yael-Starkware]

@Yael-Starkware made 1 comment.
Reviewable status: 1 of 4 files reviewed, 2 unresolved discussions (waiting on efrat-starkware, naor-starkware, OmriEshhar1, and YairVaknin-starkware).

---

vm/src/vm/runners/function_runner.rs line 23 at r3 (raw file):

Previously, naor-starkware wrote…

It's a semantic alias, not a technical one. CairoRunner is the general execution engine. CairoFunctionRunner communicates that
you're using it specifically to invoke individual functions by name/PC - the same way the Python CairoFunctionRunner did. Without the
alias, every test file looks identical whether it's running a full program or calling a function entry point.

not sure I understand the issue, the function name indicates what it is doing.
besides, how do you enforce using the correct type?

[Yael-Starkware]

@Yael-Starkware made 1 comment.
Reviewable status: 1 of 4 files reviewed, 2 unresolved discussions (waiting on efrat-starkware, naor-starkware, OmriEshhar1, and YairVaknin-starkware).

---

vm/src/vm/runners/function_runner.rs line 23 at r3 (raw file):

Previously, Yael-Starkware (YaelD) wrote…

not sure I understand the issue, the function name indicates what it is doing.
besides, how do you enforce using the correct type?

as we discussed on huddle, since we are deleting the python-vm , no need to keep it's naming conventions. so please remove this type.

[YairVaknin-starkware]

@YairVaknin-starkware reviewed 4 files and all commit messages, and made 2 comments.
Reviewable status: all files reviewed, 4 unresolved discussions (waiting on efrat-starkware and naor-starkware).

---

CHANGELOG.md line 15 at r3 (raw file):

#### Upcoming Changes

* refactor: add `CairoFunctionRunner` type alias for `CairoRunner` under the `test_utils` feature flag [#2377](https://github.com/starkware-libs/cairo-vm/pull/2377)

description should probably be adjusted to the current state of the PR (after Yael's comment)

Code quote:

* refactor: add `CairoFunctionRunner` type alias for `CairoRunner` under the `test_utils` feature flag [#2377](https://github.com/starkware-libs/cairo-vm/pull/2377)

---

vm/src/vm/runners/function_runner.rs line 22 at r3 (raw file):

/// Identifies a Cairo function entrypoint either by function name or by program counter.
#[allow(dead_code)]

safe to remove? I don't see Pc ever constructed outside of test? Maybe just mark this variant with the attr?

Code quote:

#[allow(dead_code)]