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)

Name: midenc-execution-trace
Author: greenhat

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>

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?”).

Reproduce the issue on the smallest possible test (or add a focused test).
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>
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=...).

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>