hakorune/docs/development/current/main/investigations/phase132-llvm-exit-phi-wrong-result.md

Phase 132: LLVM Exit PHI=0 Bug Investigation & Fix

Date: 2025-12-15 Status: ✅ Fixed Impact: Critical - Exit PHIs from loops were returning 0 instead of correct values

Problem Statement

LLVM backend was returning 0 for exit PHI values in simple while loops, while VM backend correctly returned the final loop variable value.

Test Case

static box Main {
  main() {
    local i = 0
    loop(i < 3) { i = i + 1 }
    return i  // Should return 3, was returning 0 in LLVM
  }
}

Expected: Result: 3 (matches VM) Actual (before fix): Result: 0 MIR: Correct (bb3: %1 = phi [%3, bb6]; ret %1) LLVM IR (before fix): ret i64 0 (wrong!) LLVM IR (after fix): ret i64 %"phi_1" (correct!)

Root Cause Analysis

この不具合は「2層」にまたがっていました:

1. JoinIR/Boundary 層で exit 値が境界を通っていない（VM でも 0 になり得る）
2. LLVM Python 層で PHI の SSOT が壊れていて exit PHI が 0 になる（VM は正常でも LLVM が壊れる）

このページは主に (2) の LLVM Python 層の根治を記録します。
(1) の修正は Phase 132 の一部として別途コード側で入っています（修正ファイル一覧を参照）。

Investigation Path

1. PHI filtering issue in vmap_cur initialization

   • ✅ Confirmed: Filter relied on phi.basic_block attribute
   • Issue: llvmlite sets phi.basic_block = None until IR finalization
   • Filter at block_lower.py:323-365 was silently dropping ALL PHIs

2. builder.vmap overwrite issue

   • ✅ Confirmed: The real root cause!

The Actual Bug

Two separate issues combined to cause the bug:

Issue 1: Unreliable PHI.basic_block Attribute

• llvmlite's PHI instructions have basic_block = None when created
• Filter logic at block_lower.py:326-340 relied on phi.basic_block.name comparison
• Since basic_block was always None, filter excluded ALL PHIs from vmap_cur
• Fix: Use predeclared_ret_phis dict instead of basic_block attribute

Issue 2: builder.vmap PHI Overwrites (Critical!)

At block_lower.py:437-448, Pass A syncs created values to builder.vmap:

# Phase 131-7: Sync ALL created values to global vmap
for vid in created_ids:
    val = vmap_cur.get(vid)
    if val is not None:
        builder.vmap[vid] = val  # ❌ Unconditional overwrite!

The Fatal Sequence:

1. Pass A setup: Creates PHI v1 for bb3, stores in builder.vmap[1]
2. Pass A processes bb0:
   • vmap_cur filters out v1 PHI (not from bb0)
   • const v1 instruction writes to vmap_cur[1]
   • Line 444: Syncs vmap_cur[1] → builder.vmap[1], overwriting PHI!
3. Pass A processes bb3:
   • vmap_cur initialized from builder.vmap
   • builder.vmap[1] is now the const (not PHI!)
   • return v1 uses const 0 instead of PHI

The Fix

Fix 1: PHI Filtering (block_lower.py:320-347)

Before (unreliable basic_block check):

if hasattr(_val, 'add_incoming'):
    bb_of = getattr(getattr(_val, 'basic_block', None), 'name', None)
    bb_name = getattr(bb, 'name', None)
    keep = (bb_of == bb_name)  # ❌ Always False! bb_of is None

After (use predeclared_ret_phis dict):

if hasattr(_val, 'add_incoming'):  # Is it a PHI?
    phi_key = (int(bid), int(_vid))
    if phi_key in predecl_phis:
        keep = True  # ✅ Reliable tracking
    else:
        keep = False  # Avoid namespace collision

Fix 2: Protect builder.vmap PHIs (block_lower.py:437-455)

Before (unconditional overwrite):

for vid in created_ids:
    val = vmap_cur.get(vid)
    if val is not None:
        builder.vmap[vid] = val  # ❌ Overwrites PHIs!

After (PHI protection):

for vid in created_ids:
    val = vmap_cur.get(vid)
    if val is not None:
        existing = builder.vmap.get(vid)
        # Don't overwrite existing PHIs - SSOT principle
        if existing is not None and hasattr(existing, 'add_incoming'):
            continue  # ✅ Skip sync, preserve PHI
        builder.vmap[vid] = val

Verification

Test Results

# ✅ LLVM matches VM
NYASH_LLVM_USE_HARNESS=1 NYASH_LLVM_STRICT=1 ./target/release/hakorune --backend llvm /tmp/p1_return_i.hako
# Output: Result: 3

# ✅ VM baseline
./target/release/hakorune --backend vm /tmp/p1_return_i.hako
# Output: RC: 3

Generated LLVM IR Comparison

Before (wrong):

bb3:
  %"phi_1" = phi  i64 [%"phi_3", %"bb6"]
  ret i64 0  ; ❌ Hardcoded 0!

After (correct):

bb3:
  %"phi_1" = phi  i64 [%"phi_3", %"bb6"]
  ret i64 %"phi_1"  ; ✅ Uses PHI value!

Design Lessons

The SSOT Principle

builder.vmap is the Single Source of Truth for PHI nodes:

• PHIs are created once in setup_phi_placeholders
• PHIs must NEVER be overwritten by later instructions
• vmap_cur is per-block and must filter PHIs correctly

PHI Ownership Tracking

llvmlite limitation: PHI.basic_block is None until finalization Solution: Explicit tracking via predeclared_ret_phis: Dict[(block_id, value_id), PHI]

Fail-Fast vs Silent Failures

The original filter silently dropped PHIs via broad exception handling:

except Exception:
    keep = False  # ❌ Silent failure!

Better approach: Explicit checks with trace logging for debugging.

Related Issues

• Phase 131: Block_end_values SSOT system
• Phase 131-12: VMap snapshot investigation
• Phase 131-14-B: Jump-only block resolution

Files Modified

JoinIR/Boundary 層（exit 値の SSOT を境界で明示）

• src/mir/join_ir/lowering/simple_while_minimal.rs（Jump(k_exit, [i_param])）
• src/mir/builder/control_flow/joinir/patterns/pattern1_minimal.rs（LoopExitBinding を作って境界へ設定）

LLVM Python 層（PHI SSOT の維持）

• src/llvm_py/builders/block_lower.py
  • PHI filtering を predeclared_ret_phis ベースへ変更（phi.basic_block 依存を排除）
  • builder.vmap へ sync する際、既存 PHI を上書きしない（PHI を SSOT として保護）

Debug Environment Variables

NYASH_LLVM_STRICT=1           # Fail-fast on errors
NYASH_LLVM_TRACE_PHI=1        # PHI wiring traces
NYASH_LLVM_TRACE_VMAP=1       # VMap operation traces
NYASH_LLVM_DUMP_IR=/tmp/x.ll  # Dump generated IR

Acceptance Criteria

✅ /tmp/p1_return_i.hako returns 3 in LLVM (was 0) ✅ STRICT mode enabled, no fallback to 0 ✅ VM and LLVM results match ✅ No regression on Phase 131 test cases ✅ Generated LLVM IR uses ret i64 %phi_1 not ret i64 0

Next Steps

• Add regression test for exit PHI patterns
• Document PHI ownership model in the LLVM harness docs (SSOT: phase131-3-llvm-lowering-inventory.md)