hakorune/docs/development/current/main/phase73-index.md

Phase 73: BindingId-Based Scope Manager - Index

Status: ✅ Complete (Design Phase) Date: 2025-12-13

---

Quick Links

📋 Core Documents

1. Design Document (SSOT) - Complete design specification
2. Completion Summary - Phase 73 deliverables and next steps

💻 Code

• PoC Implementation: src/mir/join_ir/lowering/scope_manager_bindingid_poc/mod.rs
  • Feature-gated: #[cfg(feature = "normalized_dev")]
  • Tests: 6/6 passing ✅

---

What is Phase 73?

Purpose: Design a BindingId-based scope management system for JoinIR lowering to align with MIR's lexical scope model.

Problem:

• MIR builder uses BindingId for shadowing (Phase 68-69)
• JoinIR lowering uses name-based lookup (fragile, string matching)
• Mismatch creates future bug risk

Solution:

• Introduce BindingId into JoinIR's ScopeManager
• Gradual migration (Phases 74-77)
• Eliminate naming convention hacks (is_digit_pos, is_ch_match)

---

Phase 73 Deliverables

✅ Design Document

File: phase73-scope-manager-design.md

Contents (34 sections, ~700 lines):

• Current state analysis (MIR + JoinIR scope systems)
• Problem identification (shadowing, naming brittleness)
• Proposed architecture (Option A: Parallel BindingId Layer)
• Integration with MirBuilder (binding_map additions)
• Migration roadmap (Phases 74-77)
• Example scenarios (shadowing, promoted variables)

---

✅ Proof-of-Concept

File: src/mir/join_ir/lowering/scope_manager_bindingid_poc/mod.rs

Highlights:

• BindingId type wrapper
• ConditionEnvV2 (parallel name + BindingId lookup)
• CarrierInfoV2 (BindingId-based promotion)
• ScopeManagerV2 trait + implementation

Test Results:

running 6 tests
test test_condition_env_v2_basic ... ok
test test_shadowing_simulation ... ok
test test_promoted_binding_resolution ... ok
test test_scope_manager_v2_binding_lookup ... ok
test test_scope_manager_v2_promoted_lookup ... ok
test test_unified_lookup_fallback ... ok

---

Migration Roadmap

Phase 74: Infrastructure (2-3 hours)

• Add binding_map to MirBuilder
• Add binding_to_join to ConditionEnv
• BindingId allocator

Phase 75: Pattern 1 Pilot (1-2 hours)

• Migrate simplest pattern (no carriers)
• Prove BindingId integration works

Phase 76: Pattern 2 Promotion (2-3 hours)

• Eliminate naming convention hacks
• BindingId-based carrier promotion

Phase 77: Pattern 3-4 + Cleanup (2-3 hours)

• Complete migration
• Remove legacy name-based code

Total Estimated Effort: 8-12 hours

---

Key Design Decisions

1. Gradual Migration (Option A)

Why: Low risk, backward compatible, easy rollback

Alternative Rejected: Full replacement (Option B) - too risky for Phase 73

---

2. Parallel Lookup Strategy

// Phase 74-76 (transition)
fn lookup(&self, name: &str) -> Option<ValueId> {
    // 1. Try BindingId lookup (new code)
    if let Some(binding) = self.name_to_binding.get(name) {
        if let Some(value) = self.binding_to_join.get(binding) {
            return Some(value);
        }
    }
    // 2. Fallback to name lookup (legacy code)
    self.name_to_join.get(name).copied()
}

---

3. Per-Function BindingId Scope

Decision: Each function has independent BindingId allocation

Reasoning:

• Like ValueId (proven model)
• No global state needed
• Simpler implementation

Alternative: Global BindingId pool (for Phase 63 integration) - deferred

---

No Production Impact

Guarantee:

• ✅ No changes to production code (except 1 line mod.rs)
• ✅ PoC is feature-gated (normalized_dev)
• ✅ All existing tests pass (1049 tests)
• ✅ Normal build unaffected

Modified Files (3 total):

1. Design doc (new)
2. Completion summary (new)
3. PoC module (new, dev-only)
4. mod.rs (1 line for PoC)

---

Success Metrics

Design Quality ✅

• SSOT document (34 sections)
• Clear problem statement
• Proposed architecture with examples
• Integration points identified
• Migration path defined

PoC Validation ✅

• Compiles under normalized_dev
• All 6 tests passing
• Demonstrates key concepts:
  • Parallel lookup (BindingId + name)
  • Shadowing simulation
  • Promoted variable resolution

Risk Mitigation ✅

• Feature-gated (no prod impact)
• Gradual migration plan
• Backward compatibility preserved
• Clear rollback strategy

---

Open Questions (Phase 74+)

Q1: Performance

Concern: Dual maps double memory usage

Mitigation: Remove legacy maps after Phase 77, profile during Phase 74

---

Q2: Captured Variables

Question: How to add BindingId to CapturedVar?

Answer: Phase 76 task (update function_scope_capture module)

---

Q3: Phase 63 Integration

Question: Use global BindingId for ownership analysis?

Answer: Phase 78+ (future enhancement)

---

Related Work

Completed Phases

• Phase 68-69: MIR lexical scope + shadowing
• Phase 231: ScopeManager trait (current impl)
• Phase 224: Promoted LoopBodyLocal (naming convention)

Future Phases

• Phase 74: BindingId infrastructure
• Phase 75: Pattern 1 migration
• Phase 76: Pattern 2 migration (carrier promotion)
• Phase 77: Pattern 3-4 migration + cleanup

---

References

Design Documents

• phase73-scope-manager-design.md - SSOT
• phase73-completion-summary.md - Deliverables
• phase238-exprlowerer-scope-boundaries.md - Scope boundaries (related)

Code Files

• src/mir/builder/vars/lexical_scope.rs - MIR lexical scope (existing)
• src/mir/join_ir/lowering/scope_manager.rs - Current ScopeManager
• src/mir/join_ir/lowering/carrier_info.rs - Current CarrierInfo
• src/mir/join_ir/lowering/scope_manager_bindingid_poc/mod.rs - PoC (Phase 73)

---

Recommended Reading Order

For Implementation (Phase 74+)

1. Design Document - Full context
2. PoC Code - Concrete examples
3. Completion Summary - Migration checklist

For Review

1. This Index - Quick overview
2. Completion Summary - What was delivered
3. Design Document - Deep dive (if needed)

---

Contact / Questions

Phase 73 Design: Complete, ready for user review Next Steps: User approval → Phase 74 implementation

Estimated Timeline:

• Phase 74: 1 week (infrastructure)
• Phase 75: 2-3 days (Pattern 1)
• Phase 76: 3-4 days (Pattern 2)
• Phase 77: 3-4 days (Pattern 3-4 + cleanup)
• Total: 2-3 weeks (leisurely pace)

---

Status: ✅ Phase 73 Complete - Ready for Phase 74