f85e485195
**Problem**: ValueId(14)/ValueId(17) circular dependency in multi-carrier loop PHI construction. Loop body PHIs referenced ValueIds not defined in header exit block, causing SSA use-before-def violations. **Root Cause**: Interleaved ValueId allocation when processing pinned (parameters like 'me', 'args') and carrier (locals like 'i', 'n') variables created forward references: ``` Iteration 1: pre_copy=%13, phi=%14 ✅ Iteration 2: pre_copy=%15, phi=%19 ✅ (but %14 not yet emitted!) Body PHI: phi %17 = [%14, bb3] ❌ %14 doesn't exist in bb3 ``` **Solution**: LoopForm Meta-Box with 3-pass PHI construction algorithm inspired by Braun et al. (2013) "Simple and Efficient SSA Construction". **Core Design**: - **Meta-Box abstraction**: Treat entire loop as single Box with explicit carrier/pinned separation - **Three-pass algorithm**: 1. Allocate ALL ValueIds upfront (no emission) 2. Emit preheader copies in deterministic order 3. Emit header PHIs (incomplete) 4. Seal PHIs after loop body (complete) - **Guarantees**: No circular dependencies possible (all IDs pre-allocated) **Academic Foundation**: - Cytron et al. (1991): Classical SSA with dominance frontiers - Braun et al. (2013): Simple SSA with incomplete φ-nodes ✅ Applied here - LLVM Canonical Loop Form: Preheader→Header(PHI)→Body→Latch **Files Added**: 1. **src/mir/phi_core/loopform_builder.rs** (360 lines): - LoopFormBuilder struct with carrier/pinned separation - LoopFormOps trait (abstraction layer) - Three-pass algorithm implementation - Unit tests (all pass ✅) 2. **docs/development/analysis/loopform-phi-circular-dependency-solution.md**: - Comprehensive problem analysis (600+ lines) - Academic literature review - Alternative approaches comparison - Detailed implementation plan 3. **docs/development/analysis/LOOPFORM_PHI_SOLUTION_SUMMARY.md**: - Executive summary (250 lines) - Testing strategy - Migration timeline (4 weeks) - Risk assessment 4. **docs/development/analysis/LOOPFORM_PHI_NEXT_STEPS.md**: - Step-by-step integration guide (400 lines) - Code snippets for mir/loop_builder.rs - Troubleshooting guide - Success metrics **Testing**: - ✅ Unit tests pass (deterministic allocation verified) - ⏳ Integration tests (Week 2 with feature flag) - ⏳ Selfhost support (Week 3) **Migration Strategy**: - Week 1 (Current): ✅ Prototype complete - Week 2: Integration with NYASH_LOOPFORM_PHI_V2=1 feature flag - Week 3: Selfhost compiler support - Week 4: Full migration, deprecate old code **Advantages**: 1. **Correctness**: Guarantees SSA definition-before-use 2. **Simplicity**: ~360 lines (preserves Box Theory philosophy) 3. **Academic alignment**: Matches state-of-art SSA construction 4. **Backward compatible**: Feature-flagged with rollback capability **Impact**: This resolves the fundamental ValueId circular dependency issue blocking Stage-B selfhosting, while maintaining the LoopForm design philosophy of "normalize everything, confine to scope". **Total Contribution**: ~2,000 lines of code + documentation **Next Steps**: Integrate LoopFormBuilder into src/mir/loop_builder.rs following LOOPFORM_PHI_NEXT_STEPS.md guide (estimated 2-4 hours). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
19 lines
612 B
Rust
19 lines
612 B
Rust
/*!
|
||
* phi_core – Unified PHI management scaffold (Phase 1)
|
||
*
|
||
* Purpose:
|
||
* - Provide a single, stable entry point for PHI-related helpers.
|
||
* - Start with re-exports of existing, verified logic (zero behavior change).
|
||
* - Prepare ground for gradual consolidation of loop PHI handling.
|
||
*/
|
||
|
||
pub mod common;
|
||
pub mod if_phi;
|
||
pub mod loop_phi;
|
||
pub mod loopform_builder;
|
||
|
||
// Public surface for callers that want a stable path:
|
||
// Phase 1: No re-exports to avoid touching private builder internals.
|
||
// Callers should continue using existing paths. Future phases may expose
|
||
// stable wrappers here once migrated.
|