---

name: midenc-execution-trace description: | Use when working on the Miden compiler (midenc / cargo miden), debugging failing tests or implementing compiler changes, and you need a Miden VM MASM execution trace to understand the stack state after each instruction. Covers MIDENC_TRACE=executor=trace (typically with cargo make test -- --no-capture ...).

MIDENC Trace (MASM execution trace)

Quick start

• Run a single Rust test with MASM execution tracing enabled:
  • MIDENC_TRACE=executor=trace cargo make test --no-capture <test_name_or_filter>
• If you only care about traces on failures (and want faster parallel execution), omit --no-capture:
  • MIDENC_TRACE=executor=trace cargo make test <test_name_or_filter>
• If you want parallel execution but still want output on passing tests, prefer --success-output:
  • MIDENC_TRACE=executor=trace cargo make test --success-output immediate <test_name_or_filter>

What MIDENC_TRACE=executor=trace gives you

• A step-by-step trace of MASM execution from the VM executor.
• For each executed instruction/op, it prints the current stack state (practically: the quickest way to answer “what was on the stack right after this instruction?”).

Recommended workflow for debugging compiler changes

1. Reproduce the issue on the smallest possible test (or add a focused test).
2. Run with live output so you can see the trace stream as the test executes:
   • MIDENC_TRACE=executor=trace cargo make test --no-capture <test_name_or_filter>
3. Compare the trace against the expected stack discipline for the procedure(s) you’re debugging:
   • When you see a mismatch, jump to the corresponding emitted MASM (pair with the emit skill if you also need MIDENC_EMIT=masm=...).

Practical tips

• Prefer a single test when tracing: executor=trace is extremely verbose and slows runs down.
• If you’re running via cargo nextest directly, the equivalent “live output” flag is --no-capture:
  • MIDENC_TRACE=executor=trace cargo nextest run --no-capture <filter>