hakorune/docs/private/papers/paper-p-phi-trace-observability.md

PHI Observability and Trace Checking (Draft)

Motivation

• SSA construction bugs are subtle. We want a first‑class, machine‑checkable record of PHI decisions.

Approach

• Emit structured JSONL events across PHI lifecycle: finalize_begin, finalize_dst, finalize_target, wire_choose, add_incoming, finalize_summary.
• Provide a checker that validates coverage and invariants (e.g., each dst has at least one add_incoming; chosen preds ⊆ CFG preds).

Code References

• Trace writer: src/llvm_py/llvm_builder.py, src/llvm_py/phi_wiring/wiring.py
• Checker: tools/phi_trace_check.py

Usage

• NYASH_LLVM_TRACE_PHI=1 NYASH_LLVM_TRACE_OUT=tmp/phi.jsonl bash tools/test/smoke/bridge/try_result_mode.sh
• python3 tools/phi_trace_check.py --summary tmp/phi.jsonl

Next

• Expand checks (dominance, grouping at head), integrate into CI as optional gate.