Phase 10.7a — JIT Branch/PHI/Independent ABI: Minimal Path Hardening (Plan)

Purpose
- Solidify the first functional slice of the JIT control-flow path:
  - Branch wiring (b1 and i64!=0 normalization)
  - Minimal PHI via block parameters (single-value diamond)
  - Independent ABI (JitValue) and safe dispatch + fallback
  - Observable, toggleable, and easy to verify via flags + examples

Scope (10.7a only)
1) Minimal PHI handoff
   - LowerCore: detect single-PHI merge; pass i64 value via block param
   - CraneliftBuilder: ensure block param (I64), push/pop on branch/jump with args
   - Flag gate: NYASH_JIT_PHI_MIN=1

2) Branch wiring and condition normalization
   - Keep compare result on stack as b1 when possible
   - If top-of-stack is I64, normalize by icmp_imm != 0
   - Implement br_if/jump to pre-created blocks (deterministic order)

3) Independent ABI (minimum viable)
   - JitValue(I64/F64/Bool/Handle) in/out; normalize non-i64 args to i64 for now
   - TLS split: legacy VM args (for hostcalls) and JIT args
   - Engine.execute_handle uses catch_unwind; panic → VM fallback with stats

4) Minimal hostcall bridge (safe; off by default)
   - Symbols: nyash.array.{len,get,set,push}, nyash.map.{size}
   - Gate: NYASH_JIT_HOSTCALL=1
   - Only integer indices/values (PoC); other types map to handles later

5) Observability and ergonomics
   - Flags: NYASH_JIT_EXEC, NYASH_JIT_STATS, NYASH_JIT_STATS_JSON, NYASH_JIT_DUMP, NYASH_JIT_THRESHOLD, NYASH_JIT_PHI_MIN, NYASH_JIT_HOSTCALL
   - CLI: --jit-exec --jit-stats --jit-stats-json --jit-dump --jit-threshold N --jit-phi-min --jit-hostcall
   - Unified JIT summary on VM exit (sites/compiled/hits/exec_ok/trap/fallback_rate)
   - Lower log includes argc/phi_min + CFG light dump (phi edges) when NYASH_JIT_DUMP=1

Non-Goals (later 10.7b+)
- Full PHI generalization (multiple values, loops, complex CFG forms)
- Non-i64 native path (true F64/Bool return/params in CLIF)
- Side-effect instruction lowering (print, IO) — keep in VM path
- Host handle registry for real object bridging (u64↔Arc<dyn NyashBox>)

Deliverables
- Working minimal PHI + branch JIT execution on curated examples:
  - examples/jit_branch_demo.hako
  - examples/jit_loop_early_return.hako
  - examples/jit_phi_demo.hako (single-PHI diamond)
- Fallback correctness: traps/panic → VM path; results match VM
- Configurable via CLI flags; metrics visible via JIT summary/JSON

Acceptance Criteria
- With: --backend vm --jit-exec --jit-stats --jit-threshold 1
  - For branch/phi examples, JIT executes without panic
  - VM fallback occurs only for unsupported ops (logged)
  - JIT summary shows exec_ok > 0 and reasonable fallback_rate
- With: --jit-phi-min
  - CFG dump lists phi_min edges and blocks count
  - Results match the same program without JIT enabled

Risk & Mitigation
- Mismatch between VMValue and JitValue adapters
  - Mitigation: normalize non-i64 to i64 defensively; expand tests on adapters
- Cranelift block parameter misuse
  - Mitigation: deterministic block order and explicit ensure_block_param_i64()
- Panic in hostcall stubs (unexpected Box types)
  - Mitigation: gated by NYASH_JIT_HOSTCALL=1; default off; fallback to VM on panic

Verification Checklist
- cargo check (w/ and w/o --features cranelift-jit)
- Run examples with JIT flags; compare outputs with pure VM
- Inspect logs: lower summary + CFG dump + unified summary/JSON

Timeline (10.7a)
Day 1:
- Finalize ABI normalization and branch wiring; add unified stats (done)
- Wire CLI flags and JSON stats (done)
Day 2:
- Harden minimal PHI path and CFG dump (done)
- Curate examples and sanity-run on flags
Day 3:
- Stabilize logging format, trim rough edges, doc polish
→ Then roll into 10.7b (multi-PHI, multi-arg block params, real handle registry)

Follow-ups (10.7b/10.7c seeds)
- Host handle registry (u64↔Arc) and type-safe bridging
- True F64/Bool native ABI, multi-arg params/returns
- CFG visualization improvements (dot export) and JitConfigBox

Refs
- docs/development/current/CURRENT_TASK.md (10_7 items)
- src/jit/{lower,engine,manager,abi,rt}/
- examples: jit_* demos
