docs(joinir): Phase 77 - BindingId expansion plan
Phase 77 design finalizes BindingId infrastructure migration with comprehensive implementation roadmap. Three design documents outline expansion of promoted_bindings tracking to Pattern3/4 and legacy code deprecation strategy. Documents: - phase77-expansion-completion.md: Architecture overview + 5 implementation tasks - PHASE_77_IMPLEMENTATION_GUIDE.md: Step-by-step code changes with exact locations - PHASE_77_EXECUTIVE_SUMMARY.md: Impact analysis and success metrics Key decisions: - DigitPosPromoter/TrimLoopHelper populate promoted_bindings - Pattern3/4 use BindingId priority in variable resolution - 3-phase deletion strategy (Deprecate→Require→Delete) - Dev-only feature gate preserves zero production impact Phase 77 implementation: ~2-3 hours (5 tasks: promoters + patterns + legacy + tests) 🤖 Generated with Claude Code Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
nyash-codex
320
docs/development/current/main/PHASE_77_EXECUTIVE_SUMMARY.md
Normal file
320
docs/development/current/main/PHASE_77_EXECUTIVE_SUMMARY.md
Normal file
@ -0,0 +1,320 @@
|
||||
# Phase 77: Executive Summary - BindingId Migration Expansion
|
||||
|
||||
**Status**: DESIGN COMPLETE - Ready for Implementation
|
||||
**Date**: 2025-12-13
|
||||
**Estimated Implementation**: 2-3 hours
|
||||
**Risk Level**: LOW (dev-only, dual-path design)
|
||||
|
||||
---
|
||||
|
||||
## One-Paragraph Summary
|
||||
|
||||
Phase 77 completes the BindingId migration foundation by **populating promoted_bindings** in DigitPos/Trim promoters, **extending BindingId lookup** to Pattern3/4, and **deprecating legacy name-based code** (~40 lines of string hacks). This achieves **type-safe, shadowing-aware promotion tracking** across all JoinIR patterns while maintaining 100% backward compatibility via dual-path design.
|
||||
|
||||
---
|
||||
|
||||
## What Changed
|
||||
|
||||
### Infrastructure (Phase 74-76) ✅
|
||||
- ✅ Phase 74: `MirBuilder.binding_map` added
|
||||
- ✅ Phase 75: BindingId priority lookup in ConditionEnv
|
||||
- ✅ Phase 76: `promoted_bindings` data structure in CarrierInfo
|
||||
|
||||
### Phase 77 Additions (DESIGN READY)
|
||||
1. **DigitPosPromoter Integration** (45 min)
|
||||
- Add `binding_map` parameter to `DigitPosPromotionRequest`
|
||||
- Record promoted bindings: `digit_pos` (BindingId(5)) → `is_digit_pos` (BindingId(10))
|
||||
- Thread `binding_map` through call chain
|
||||
|
||||
2. **TrimLoopHelper Integration** (30 min)
|
||||
- Add `binding_map` parameter to `TrimPromotionRequest`
|
||||
- Record promoted bindings: `ch` (BindingId(6)) → `is_ch_match` (BindingId(11))
|
||||
- Similar pattern to DigitPos
|
||||
|
||||
3. **Pattern3/4 BindingId Lookup** (45 min)
|
||||
- Add dev-only BindingId-aware ConditionEnv construction
|
||||
- Use Phase 75 `resolve_var_with_binding()` API
|
||||
- Fallback to name-based for production (dual-path)
|
||||
|
||||
4. **Legacy Code Deprecation** (15 min)
|
||||
- Deprecate `CarrierInfo::resolve_promoted_join_id()` (~25 lines)
|
||||
- Add fallback warnings in `Pattern2ScopeManager` (~10 lines)
|
||||
- Document deletion criteria for Phase 78+
|
||||
|
||||
5. **E2E Verification Tests** (30 min)
|
||||
- Test DigitPos end-to-end BindingId flow
|
||||
- Test Trim end-to-end BindingId flow
|
||||
- Test Pattern3 BindingId lookup
|
||||
- Test Pattern4 BindingId lookup
|
||||
|
||||
---
|
||||
|
||||
## Architecture Evolution
|
||||
|
||||
### Before Phase 77 (Fragile Name-Based)
|
||||
```rust
|
||||
// CarrierInfo::resolve_promoted_join_id (FRAGILE!)
|
||||
let candidates = [
|
||||
format!("is_{}", original_name), // DigitPos pattern
|
||||
format!("is_{}_match", original_name), // Trim pattern
|
||||
];
|
||||
for carrier_name in &candidates {
|
||||
if let Some(carrier) = self.carriers.iter().find(|c| c.name == *carrier_name) {
|
||||
return carrier.join_id; // String matching! 😱
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Problems**:
|
||||
- ❌ Brittle naming conventions
|
||||
- ❌ No compiler protection
|
||||
- ❌ Shadowing-unaware
|
||||
- ❌ Pattern-specific hacks
|
||||
|
||||
### After Phase 77 (Type-Safe BindingId)
|
||||
```rust
|
||||
// CarrierInfo::promoted_bindings (TYPE-SAFE!)
|
||||
pub promoted_bindings: BTreeMap<BindingId, BindingId>, // Original → Promoted
|
||||
|
||||
// Phase 77: Promoter populates the map
|
||||
carrier_info.record_promoted_binding(
|
||||
BindingId(5), // digit_pos
|
||||
BindingId(10), // is_digit_pos
|
||||
);
|
||||
|
||||
// Phase 76: ScopeManager resolves via BindingId
|
||||
if let Some(promoted_bid) = carrier_info.resolve_promoted_with_binding(original_bid) {
|
||||
return condition_env.resolve_var_with_binding(Some(promoted_bid), name);
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits**:
|
||||
- ✅ Type-safe (compiler-checked BindingId identity)
|
||||
- ✅ Shadowing-aware (BindingId unique per binding)
|
||||
- ✅ Pattern-agnostic (works for all promotions)
|
||||
- ✅ No name collisions
|
||||
|
||||
---
|
||||
|
||||
## Implementation Files
|
||||
|
||||
### Files to Modify
|
||||
|
||||
1. **Promoters** (populate promoted_bindings):
|
||||
- `src/mir/loop_pattern_detection/loop_body_digitpos_promoter.rs`
|
||||
- `src/mir/loop_pattern_detection/trim_loop_helper.rs`
|
||||
- `src/mir/loop_pattern_detection/loop_body_cond_promoter.rs`
|
||||
|
||||
2. **Pattern Lowering** (BindingId lookup):
|
||||
- `src/mir/builder/control_flow/joinir/patterns/pattern3_with_if_phi.rs`
|
||||
- `src/mir/builder/control_flow/joinir/patterns/pattern4_with_continue.rs`
|
||||
|
||||
3. **Legacy Deprecation**:
|
||||
- `src/mir/join_ir/lowering/carrier_info.rs` (deprecate resolve_promoted_join_id)
|
||||
- `src/mir/join_ir/lowering/scope_manager.rs` (add fallback warnings)
|
||||
|
||||
4. **Tests** (new):
|
||||
- `tests/phase77_binding_promotion.rs` (or add to existing)
|
||||
|
||||
### Lines of Code
|
||||
|
||||
- **Add**: ~150 lines (promoter integration + tests)
|
||||
- **Deprecate**: ~40 lines (legacy name-based code)
|
||||
- **Delete**: 0 lines (Phase 78+)
|
||||
- **Net Change**: ~+110 lines (mostly tests)
|
||||
|
||||
---
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Phase 77 Scope (THIS PHASE)
|
||||
|
||||
**WILL DO**:
|
||||
- ✅ Populate promoted_bindings (DigitPos/Trim)
|
||||
- ✅ Extend BindingId lookup (Pattern3/4 dev-only)
|
||||
- ✅ Deprecate legacy code (add warnings)
|
||||
- ✅ Add E2E tests (4 tests)
|
||||
|
||||
**WILL NOT DO** (deferred to Phase 78+):
|
||||
- ❌ Delete legacy code (keep dual-path)
|
||||
- ❌ Make BindingId required in production
|
||||
- ❌ Remove `promoted_loopbodylocals` field
|
||||
|
||||
### Why Gradual Migration?
|
||||
|
||||
**3-Phase Deletion Strategy**:
|
||||
1. **Phase 77**: Deprecate + Log (observe fallback usage)
|
||||
2. **Phase 78**: Require BindingId in production paths
|
||||
3. **Phase 79**: Delete legacy code entirely
|
||||
|
||||
**Benefits**:
|
||||
- No "big bang" rewrites
|
||||
- Fallback paths for debugging
|
||||
- Easy rollback if issues arise
|
||||
- Production builds unaffected
|
||||
|
||||
---
|
||||
|
||||
## Test Coverage
|
||||
|
||||
### Acceptance Criteria
|
||||
|
||||
- ✅ `cargo build --lib --features normalized_dev` succeeds
|
||||
- ✅ `cargo test --release --lib` 958/958 PASS (baseline)
|
||||
- ✅ New Phase 77 tests pass (4/4)
|
||||
- ✅ No regressions in existing tests
|
||||
- ✅ Deprecation warnings logged (verify with `JOINIR_TEST_DEBUG=1`)
|
||||
|
||||
### Test Matrix
|
||||
|
||||
| Test | Purpose | Expected Result |
|
||||
|------|---------|-----------------|
|
||||
| `test_phase77_digitpos_end_to_end` | DigitPos promotes + resolves via BindingId | ✅ PASS |
|
||||
| `test_phase77_trim_end_to_end` | Trim promotes + resolves via BindingId | ✅ PASS |
|
||||
| `test_phase77_pattern3_binding_lookup` | P3 uses BindingId priority lookup | ✅ PASS |
|
||||
| `test_phase77_pattern4_binding_lookup` | P4 uses BindingId priority lookup | ✅ PASS |
|
||||
|
||||
---
|
||||
|
||||
## Impact Analysis
|
||||
|
||||
### Performance
|
||||
|
||||
**Zero Impact**:
|
||||
- All changes feature-gated (`#[cfg(feature = "normalized_dev")]`)
|
||||
- Production builds identical to Phase 76
|
||||
- BindingId lookup is O(log n) BTreeMap (same as name-based)
|
||||
|
||||
### Code Maintainability
|
||||
|
||||
**Significant Improvement**:
|
||||
- **Before**: 40 lines of string matching, brittle naming conventions
|
||||
- **After**: Type-safe BindingId mapping, compiler-checked identity
|
||||
- **Reduction**: ~40 lines of fragile code → deprecated (deleted in Phase 78+)
|
||||
|
||||
### Risk Assessment
|
||||
|
||||
**LOW RISK**:
|
||||
- ✅ Dev-only changes (production unaffected)
|
||||
- ✅ Dual-path design (fallback always available)
|
||||
- ✅ Comprehensive test coverage (4 E2E tests)
|
||||
- ✅ Gradual migration (3-phase deletion)
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
### Created Documents
|
||||
|
||||
1. **[phase77-expansion-completion.md](phase77-expansion-completion.md)** (~300 lines)
|
||||
- Architecture overview
|
||||
- Implementation tasks (1-5)
|
||||
- Migration strategy
|
||||
- Design Q&A
|
||||
|
||||
2. **[PHASE_77_IMPLEMENTATION_GUIDE.md](PHASE_77_IMPLEMENTATION_GUIDE.md)** (~500 lines)
|
||||
- Step-by-step code changes
|
||||
- Exact file locations
|
||||
- Testing checklist
|
||||
- Troubleshooting guide
|
||||
|
||||
3. **[PHASE_77_EXECUTIVE_SUMMARY.md](PHASE_77_EXECUTIVE_SUMMARY.md)** (this document)
|
||||
- High-level overview
|
||||
- Impact analysis
|
||||
- Decision rationale
|
||||
|
||||
### Updated Documents
|
||||
|
||||
- **[CURRENT_TASK.md](../../../../CURRENT_TASK.md)** - Added Phase 77 entry
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### For Implementation (ChatGPT)
|
||||
|
||||
1. **Read Implementation Guide**:
|
||||
- [PHASE_77_IMPLEMENTATION_GUIDE.md](PHASE_77_IMPLEMENTATION_GUIDE.md)
|
||||
- Follow tasks 1-6 sequentially
|
||||
|
||||
2. **Verify Baseline**:
|
||||
- `cargo build --lib` succeeds
|
||||
- `cargo test --release --lib` 958/958 PASS
|
||||
|
||||
3. **Implement Changes**:
|
||||
- Task 1: DigitPosPromoter (45 min)
|
||||
- Task 2: TrimLoopHelper (30 min)
|
||||
- Task 3: Pattern3/4 (45 min)
|
||||
- Task 4: Deprecation (15 min)
|
||||
- Task 5: Tests (30 min)
|
||||
- Task 6: Docs (15 min)
|
||||
|
||||
4. **Verify Completion**:
|
||||
- All tests pass (958 + 4 new)
|
||||
- Deprecation warnings visible
|
||||
- Documentation updated
|
||||
|
||||
### For Future Phases
|
||||
|
||||
**Phase 78-LEGACY-DELETION** (1-2 hours):
|
||||
- Remove deprecated code (~40 lines)
|
||||
- Make BindingId required in production paths
|
||||
- Delete `promoted_loopbodylocals` field
|
||||
- Full type-safety enforcement
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
When Phase 77 is complete:
|
||||
|
||||
✅ **Functional**:
|
||||
- All promoters populate promoted_bindings
|
||||
- Pattern3/4 use BindingId lookup (dev-only)
|
||||
- E2E tests verify end-to-end flow
|
||||
|
||||
✅ **Quality**:
|
||||
- Legacy code deprecated (not deleted)
|
||||
- Fallback warnings added
|
||||
- Documentation complete
|
||||
|
||||
✅ **Stability**:
|
||||
- 958/958 tests PASS (no regressions)
|
||||
- Production builds unaffected
|
||||
- Dual-path design maintained
|
||||
|
||||
✅ **Future-Ready**:
|
||||
- Phase 78 deletion path clear
|
||||
- Migration strategy proven
|
||||
- Type-safety foundation complete
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
Phase 77 represents the **final implementation step** of the BindingId migration (Phases 73-77), establishing **type-safe promotion tracking** across all JoinIR patterns while maintaining 100% backward compatibility.
|
||||
|
||||
**Key Achievement**: Eliminates ~40 lines of fragile string matching, replacing it with compiler-checked BindingId identity that is shadowing-aware and pattern-agnostic.
|
||||
|
||||
**Foundation for Phase 78+**: With Phase 77 complete, Phase 78 can safely delete deprecated code and enforce BindingId-only paths in production, achieving full type-safety with zero legacy baggage.
|
||||
|
||||
**Time Investment**: ~3 hours implementation + ~2 hours documentation = **5 hours total** for a major architectural improvement that pays dividends in maintainability and correctness.
|
||||
|
||||
---
|
||||
|
||||
## Related Phases
|
||||
|
||||
- **Phase 73**: ScopeManager BindingId design (SSOT)
|
||||
- **Phase 74**: Infrastructure (MirBuilder.binding_map)
|
||||
- **Phase 75**: Pilot (ConditionEnv.resolve_var_with_binding)
|
||||
- **Phase 76**: Promotion Infra (CarrierInfo.promoted_bindings)
|
||||
- **Phase 77**: Expansion (this phase) ← **WE ARE HERE**
|
||||
- **Phase 78+**: Legacy Deletion (future)
|
||||
|
||||
---
|
||||
|
||||
**Prepared by**: Claude Code (Analysis & Design)
|
||||
**Implementation**: ChatGPT (pending)
|
||||
**Review**: User (after implementation)
|
||||
|
||||
**Status**: Ready for Implementation ✅
|
||||
Reference in New Issue
Block a user