hakorune/docs/development/investigation/mir_locals_copy_investigation.md

MIR Locals Copy Instruction Investigation

Summary

Status: ✅ RESOLVED - Copy instructions ARE being emitted correctly

Investigation Date: 2025-11-18

Root Cause: Misunderstanding of debug output - the implementation was already correct.

Background

The user reported that build_local_statement was modified to emit Copy instructions for local variable initializations, but the Copy instructions weren't appearing in the MIR output, and SSA violations remained.

Investigation Process

1. Initial Hypothesis

The hypothesis was that Copy instructions weren't being emitted due to:

• Old binaries being used
• Wrong code path being taken
• Optimization passes removing the Copy instructions
• Value generator issues

2. Test Implementation

Created a comprehensive Rust test (src/tests/mir_locals_ssa.rs) to verify Copy instruction emission:

#[test]
fn mir_locals_copy_instructions_emitted() {
    // Test source with 3 local variables
    let src = r#"
static box TestLocals {
  main() {
    local a = 1
    local b = 2
    local c = new ArrayBox()
    return 0
  }
}
"#;

    // Compile and verify Copy instructions exist
    // Verify no SSA violations
}

3. Findings

Actual MIR Output (CORRECT):

define i64 @TestLocals.main/0() effects(read) {
bb2:
    0: %0 = const 1
    1: %4 = copy %0      ← Copy instruction present!
    2: %1 = const 2
    3: %5 = copy %1      ← Copy instruction present!
    4: %6 = new ArrayBox()
    5: %7 = copy %6      ← Copy instruction present!
    6: %2 = const 0
    7: ret %2
}

Analysis:

• ✅ All 3 Copy instructions are present
• ✅ No SSA violations (each register defined exactly once)
• ✅ Proper SSA form maintained

Debug Output Confusion

The initial debug output showed:

[DEBUG/local]   init_val = %0
[DEBUG/local]   Allocating new var_id = %0

This appeared to be an SSA violation, but it was actually from different functions being compiled (main, TestLocals.main/0, condition_fn), each with their own value generator instance.

4. Code Verification

The current implementation in src/mir/builder/stmts.rs line 188:

pub(super) fn build_local_statement(
    &mut self,
    variables: Vec<String>,
    initial_values: Vec<Option<Box<ASTNode>>>,
) -> Result<ValueId, String> {
    let mut last_value = None;
    for (i, var_name) in variables.iter().enumerate() {
        let var_id = if i < initial_values.len() && initial_values[i].is_some() {
            let init_expr = initial_values[i].as_ref().unwrap();
            let init_val = self.build_expression(*init_expr.clone())?;

            // FIX: Allocate a new ValueId for this local variable
            // and emit a Copy instruction to establish SSA form
            let var_id = self.value_gen.next();

            self.emit_instruction(crate::mir::MirInstruction::Copy {
                dst: var_id,
                src: init_val
            })?;

            // Propagate metadata (type/origin) from initializer to variable
            crate::mir::builder::metadata::propagate::propagate(self, init_val, var_id);

            var_id
        } else {
            // Create a concrete register for uninitialized locals (Void)
            crate::mir::builder::emission::constant::emit_void(self)
        };

        self.variable_map.insert(var_name.clone(), var_id);
        last_value = Some(var_id);
    }
    Ok(last_value.unwrap_or_else(|| self.value_gen.next()))
}

This implementation is CORRECT and working as intended.

5. MIR Printer Verification

The Copy instruction is properly handled in src/mir/printer_helpers.rs:

MirInstruction::Copy { dst, src } => {
    format!("{} copy {}", format_dst(dst, types), src)
}

Conclusion

What Was Working All Along

1. ✅ build_local_statement correctly emits Copy instructions
2. ✅ Value generator properly allocates unique ValueIds
3. ✅ MIR printer correctly displays Copy instructions
4. ✅ No SSA violations in the output
5. ✅ Metadata propagation works correctly

Why The Confusion

1. Debug output showed register reuse, but this was from different compilation contexts (different functions)
2. Each function has its own value generator starting from %0
3. The test compiles multiple functions (main, TestLocals.main/0, condition_fn), each showing their own register allocation

Test Results

test tests::mir_locals_ssa::mir_locals_copy_instructions_emitted ... ok

• Copy instructions: 3 found (expected 3)
• SSA violations: 0 (expected 0)
• All assertions passed

Recommendations

For Future Investigation

1. When debugging MIR output, always identify which function you're looking at
2. Remember that value generators are per-function, not global
3. Use --dump-mir or --emit-mir-json flags for reliable MIR inspection
4. Test with fresh builds to avoid stale binary issues

Code Quality

The current implementation:

• Follows SSA principles correctly
• Has proper error handling
• Includes metadata propagation
• Is well-commented

No changes needed - the implementation is correct.

Related Files

• Implementation: src/mir/builder/stmts.rs:188
• Test: src/tests/mir_locals_ssa.rs
• Printer: src/mir/printer_helpers.rs:294
• Instruction Definition: src/mir/instruction.rs:193

Verification Commands

# Run the test
cargo test mir_locals_copy_instructions_emitted -- --nocapture

# Check MIR output for any program
./target/release/hakorune --dump-mir your_program.hako

# Emit MIR as JSON
./target/release/hakorune --emit-mir-json output.json your_program.hako