docs(joinir): Phase 193-5 - Multi-carrier testing & integration plan

docs/development/current/main/phase193_5_multi_carrier_testing.md

@@ -0,0 +1,203 @@
+# Phase 193-5: Multi-Carrier Testing & Integration
+
+**Phase**: 193-5
+**Status**: Implementation Phase
+**Date**: 2025-12-06
+**Goal**: Validate ExitBindingBuilder with multi-carrier test cases and integrate into Pattern 3 & 4 lowerers
+
+---
+
+## Overview
+
+Phase 193-5 completes the Phase 193 modularization cycle by:
+1. Running existing multi-carrier test case to validate design
+2. Integrating ExitBindingBuilder into Pattern 3 & 4 lowerers
+3. Removing hardcoded carrier handling from pattern implementations
+4. Documenting multi-carrier support completion
+
+---
+
+## Test Case: loop_continue_multi_carrier.hako
+
+**File**: `apps/tests/loop_continue_multi_carrier.hako`
+
+**Pattern**: Pattern 4 (Loop with Continue)
+
+**Structure**:
+```
+loop(i < 10) {
+  i = i + 1
+  if (i % 2 == 0) {
+    continue  // Skip even numbers
+  }
+  sum = sum + i      // Accumulate odd numbers
+  count = count + 1  // Count odd numbers
+}
+```
+
+**Carriers**:
+- `sum` - Accumulator for odd numbers
+- `count` - Counter for odd numbers
+
+**Expected Output**:
+```
+25  // sum = 1 + 3 + 5 + 7 + 9
+5   // count = 5 (five odd numbers from 1 to 9)
+```
+
+**Test Command**:
+```bash
+./target/release/hakorune apps/tests/loop_continue_multi_carrier.hako
+# Expected output:
+# 25
+# 5
+```
+
+---
+
+## Integration Plan
+
+### Step 1: Pattern 4 Lowerer Integration
+
+**File**: `src/mir/builder/control_flow/joinir/patterns/pattern4_with_continue.rs`
+
+**Current Approach** (to be replaced):
+```rust
+// OLD: Hardcoded carrier handling
+boundary.host_outputs.push(sum_value_id);
+boundary.join_outputs.push(join_sum_exit);
+variable_map.insert("sum".to_string(), new_sum_id);
+```
+
+**New Approach**:
+```rust
+// NEW: Via ExitBindingBuilder
+let mut builder = ExitBindingBuilder::new(&carrier_info, &exit_meta, variable_map)?;
+let _bindings = builder.build_loop_exit_bindings()?;
+builder.apply_to_boundary(&mut boundary)?;
+```
+
+**Changes**:
+1. Import `ExitBindingBuilder` and `LoopExitBinding`
+2. After `JoinModule` creation, create `CarrierInfo` and `ExitMeta`
+3. Create `ExitBindingBuilder` and apply to boundary
+4. Remove manual `boundary.host_outputs`/`boundary.join_outputs` manipulation
+
+### Step 2: Pattern 3 Lowerer Integration
+
+**File**: `src/mir/builder/control_flow/joinir/patterns/pattern3_with_if_phi.rs`
+
+**Similar approach** to Pattern 4:
+1. Collect carriers from variables assigned in if-else branches
+2. Create `ExitMeta` from JoinIR exit values
+3. Use `ExitBindingBuilder` to apply to boundary
+
+---
+
+## Validation Criteria
+
+### Test Execution
+
+```bash
+# Basic execution
+./target/release/hakorune apps/tests/loop_continue_multi_carrier.hako
+
+# With detailed MIR output
+./target/release/hakorune --dump-mir apps/tests/loop_continue_multi_carrier.hako
+
+# With JoinIR core only
+NYASH_JOINIR_CORE=1 ./target/release/hakorune apps/tests/loop_continue_multi_carrier.hako
+```
+
+### Expected Results
+
+**Pass Criteria**:
+- ✅ Output is exactly "25\n5"
+- ✅ Both carriers (`sum` and `count`) have correct final values
+- ✅ MIR shows proper PHI merging for exit values
+- ✅ No variable map corruption (correct post-loop ValueIds)
+
+**Fail Criteria**:
+- ❌ Output is incorrect (e.g., "0\n0")
+- ❌ Only one carrier is updated
+- ❌ Carrier values are stale (pre-loop values)
+- ❌ Variable map is corrupted
+
+---
+
+## Implementation Checklist
+
+### Code Changes
+
+- [ ] **Pattern 4 Integration**:
+  - [ ] Import `ExitBindingBuilder` in pattern4_with_continue.rs
+  - [ ] Create `ExitBindingBuilder` after `JoinModule` creation
+  - [ ] Remove manual boundary manipulation
+  - [ ] Test compilation succeeds
+
+- [ ] **Pattern 3 Integration**:
+  - [ ] Identify carriers from if-else assignments
+  - [ ] Create `ExitBindingBuilder` after `JoinModule` creation
+  - [ ] Apply to boundary
+  - [ ] Test compilation succeeds
+
+- [ ] **Cleanup**:
+  - [ ] Remove any remaining hardcoded carrier names
+  - [ ] Remove any `TODO` comments about carrier handling
+  - [ ] Ensure no variable name assumptions remain
+
+### Testing
+
+- [ ] Run `loop_continue_multi_carrier.hako` test
+- [ ] Verify output matches expected (25, 5)
+- [ ] Run existing Pattern 3 & 4 tests
+- [ ] Check no regressions in other loop patterns
+
+### Documentation
+
+- [ ] Update CURRENT_TASK.md with Phase 193-5 completion
+- [ ] Add note to Phase 193 completion summary
+- [ ] Document multi-carrier support completion
+
+---
+
+## Success Criteria for Phase 193
+
+All sub-phases complete:
+
+✅ **Phase 193-1**: AST Feature Extractor Box module created and delegated to by router
+✅ **Phase 193-2**: CarrierInfo with flexible builder methods (automatic/explicit/manual)
+✅ **Phase 193-3**: Pattern classification with diagnostic helpers
+✅ **Phase 193-4**: ExitBindingBuilder fully boxified exit binding generation
+⏳ **Phase 193-5**: Multi-carrier tests integrated and validated
+
+### Phase 193 Completion Statement
+
+Phase 193 achieves complete modularization and enhancement of JoinIR loop lowering:
+
+1. **AST Feature Extraction**: Separated into pure function module for reusability
+2. **Carrier Metadata**: Flexible construction and query methods
+3. **Pattern Classification**: Diagnostic information and runtime queries
+4. **Exit Bindings**: Fully boxified, eliminates hardcoded carrier handling
+5. **Multi-Carrier Support**: Seamless support for loops with 2+ carriers
+
+**Impact**: JoinIR loop lowering now has clean separation of concerns, higher reusability, and eliminates fragile hardcoded variable name assumptions.
+
+---
+
+## Related Documentation
+
+- **Phase 193-4 Design**: [phase193_exit_binding_builder.md](phase193_exit_binding_builder.md)
+- **Phase 193-3**: Pattern classification improvements
+- **Phase 193-2**: CarrierInfo builder enhancement
+- **Phase 193-1**: AST feature extractor modularization
+- **Phase 188**: JoinInlineBoundary initial design
+- **Phase 190**: Pattern routing architecture
+
+---
+
+## Notes
+
+- **ValueId Allocation**: Currently uses `max(variable_map) + 1` strategy. Future: delegate to builder's proper ValueId allocator.
+- **Debugging**: Environment variable `NYASH_TRACE_EXIT_BINDING=1` will be useful for debugging Phase 193-5 integration.
+- **Next Phase**: Phase 194 can now focus on advanced pattern detection without carrier handling complexity.