hakorune/docs/private/roadmap/phases/phase-20.12a

Phase‑20.12a — Hardcoding Cleanup (Lowering hygiene)

Scope (safe, reversible)

• Name normalization via table (SSOT) instead of if chains in mir_call.py.
• Tail/fastcc hinting: move logic toward helpers (no behavior change; stricter gating optional).
• Method by‑id: gated route (NYASH_LLVM_METHOD_BY_ID=1) using stable 64‑bit hash (FNV‑1a). Fallback to by‑name kept.
• Bench hooks (barrier/noop): normalized via alias table (dev only; AOT shim symbols).
• ErrorBox unification (first wave): replace ad‑hoc "Error: ..." StringBox in Divide/Modulo/Random/Time/HTTPServer with structured ErrorBox.
• Arithmetic Extended: minimal compute_auto() + chain() for Subtract/Mul/Div (delegating to legacy execute by default).
• PHI hardening: register block_phi_incomings on creation and auto‑enable PHI post‑process under strict mode to avoid empty PHI text lines.
• Bench externs: special‑case Env.bench.print_i64/1/noop_i64/1/use_value/1 to void(i64) declarations and calls (fair, robust lowering path).

New micro benches (optimization‑resistant)

• tools/bench/run_inproc_mix_alu_resisted.sh — per‑iteration value sink (use_value) for ALU loop.
• tools/bench/run_inproc_call_noop_resisted.sh — per‑iteration no‑op call. C side mirrors via noinline+asm barrier.

Non‑goals (defer to 20.13)

• Full externs registry ingestion from Rust at runtime.
• Method by‑id defaulting and runtime registry integration.
• Wide refactors beyond lowering helpers (keep deltas minimal).

Why (benefits)

• Reduce ad‑hoc hardcoding in lowering; improve readability and testability.
• Keep mir_call.py focused on bridging, not string alias trivia.
• Prepare by‑id migration without changing defaults.

Gates

• NYASH_LLVM_METHOD_BY_ID=1 → use invoke_by_id if available (fallback by‑name)
• NYASH_LLVM_TAILCALL_STRICT=1 → strict tail placement (same CC, at block ret, unused dst)

Files

• src/llvm_py/consts/externs.py: add ALIASES (alias → canonical)
• src/llvm_py/instructions/mir_call.py: _normalize_extern_name() uses table lookups; optional by‑id path
• lang/c-abi/shims/hako_kernel.c: add hako_bench_noop_i64()

Validation

• IR dump pre/post: NYASH_LLVM_DUMP_IR, NYASH_LLVM_DUMP_OPT_IR
• Quick benches (in‑proc) unchanged semantics; div(2^k) requires NYASH_LLVM_UDIV_POW2=1 + NYASH_LLVM_ASSUME_UNSIGNED=1

Rollback

• Remove ALIASES and revert _normalize_extern_name to explicit if‑chains.
• Disable NYASH_LLVM_METHOD_BY_ID gate.