From c6091f414afbe23dbe9b42f00c271801401ce2f5 Mon Sep 17 00:00:00 2001
From: nyash-codex <codex@nyash.local>
Date: Tue, 9 Dec 2025 19:39:01 +0900
Subject: [PATCH] docs(joinir): Phase 203-B update documentation for Phase
 201-202
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update documentation to reflect Phase 201 (JoinValueSpace) and Phase 202
(Pattern 1-4 unification) achievements.

Changes:
1. joinir-architecture-overview.md:
   - Add Section 1.9 "ValueId Space Management (Phase 201)"
   - ValueId space diagram (PHI/Param/Local regions)
   - Component-to-region mapping table
   - Design principles and value_id_ranges.rs relationship

2. CURRENT_TASK.md:
   - Add Phase 201 completion report (JoinValueSpace design + implementation)
   - Add Phase 202 completion report (Pattern 1-4 unified migration)
   - Add Phase 203-A completion report (dead code removal)
   - Include commit hashes, test results, and next steps

3. phase202-summary.md (NEW):
   - Complete Phase 202 summary document
   - Before/After comparison tables
   - Region usage matrix for all patterns
   - Test coverage (821 tests passing)
   - Architecture impact and benefits

Documentation Coverage:
- Phase 201: JoinValueSpace unified ValueId allocation
- Phase 202-A: Pattern 1 migration (commit 6e778948)
- Phase 202-B: Pattern 3 migration (commit 98e81b26)
- Phase 202-C: Pattern 4 migration (commit ae741d97)
- Phase 203-A: Dead code removal (commit de9fe3bf)

All documentation links verified and consistent.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 CURRENT_TASK.md                               |  70 +++++
 .../main/joinir-architecture-overview.md      |  68 +++++
 .../current/main/phase202-summary.md          | 272 ++++++++++++++++++
 3 files changed, 410 insertions(+)
 create mode 100644 docs/development/current/main/phase202-summary.md

diff --git a/CURRENT_TASK.md b/CURRENT_TASK.md
index 3dc8100e..7d4bb33a 100644
--- a/CURRENT_TASK.md
+++ b/CURRENT_TASK.md
@@ -472,6 +472,76 @@
           - apps/tests/phase200d_capture_in_condition.hako
           - apps/tests/phase200d_digits_simple.hako
           - apps/tests/phase200d_digits_accumulate.hako
+  - [x] **Phase 201: JoinValueSpace - 統一 ValueId 割り当てシステム** ✅ (完了: 2025-12-09)
+        - **目的**: ValueId 衝突問題の根本解決（Param/Local/PHI 領域分離）
+        - **実装内容**:
+          - 201-1: 設計ドキュメント作成 ✅
+          - 201-2: JoinValueSpace box 実装 ✅（10 unit tests）
+          - 201-3: Param region migration ✅（ConditionEnvBuilder v2 API）
+          - 201-4: PHI reservation ✅（スキップ - lowerer が ConditionEnv の ValueId を直接使用）
+          - 201-5: Local region migration ✅（Pattern 2 lowerer 更新）
+          - 201-6: Testing ✅（821 tests PASS、E2E 検証成功）
+          - 201-7: Documentation ✅
+        - **ValueId 空間レイアウト**:
+          - PHI Reserved (0-99): LoopHeader PHI dst 用の予約領域
+          - Param Region (100-999): ConditionEnv, CarrierInfo, CapturedEnv
+          - Local Region (1000+): Pattern lowerers の中間値
+        - **成果**:
+          - ValueId 衝突問題完全解決（領域分離により衝突不可能）
+          - phase200d_capture_minimal.hako → 30 ✅（110 ではない）
+          - 全テスト PASS、退行なし
+        - **設計判断**:
+          - 固定領域境界（100, 1000）採用（動的オフセットより単純）
+          - reserve_phi() はマーカーのみ（PHI dst は host 側から来る）
+          - value_id_ranges.rs とは相補的（モジュールレベル vs lowering 内部）
+        - **詳細**: phase201-join-value-space-design.md
+  - [x] **Phase 202: Pattern 1-4 JoinValueSpace 統一** ✅ (完了: 2025-12-09)
+        - **目的**: 全パターンを JoinValueSpace に移行（Phase 201 の Pattern 2 に続き）
+        - **実装内容**:
+          - **Phase 202-A: Pattern 1 (Simple While)** ✅ (commit `6e778948`)
+            - simple_while_minimal.rs: value_counter → JoinValueSpace.alloc_local()
+            - Local region (1000+) のみ使用（Param region 不要）
+            - テスト: 119 passed、loop_min_while.hako → "0 1 2" ✅
+          - **Phase 202-B: Pattern 3 (If-PHI)** ✅ (commit `98e81b26`)
+            - loop_with_if_phi_minimal.rs: value_counter → JoinValueSpace.alloc_local()
+            - E2E テスト: loop_if_phi.hako, loop_if_phi_continue.hako PASS
+          - **Phase 202-C: Pattern 4 (Continue)** ✅ (commit `ae741d97`)
+            - loop_with_continue_minimal.rs: 二重カウンター → JoinValueSpace 統一
+            - 旧: value_counter (0u32) + join_value_counter (manual increment)
+            - 新: JoinValueSpace (Param 100+ + Local 1000+)
+            - E2E テスト: loop_continue_pattern4.hako → 25, loop_continue_multi_carrier.hako → 100, 10 ✅
+        - **成果**:
+          - 全パターン（P1/P2/P3/P4）で JoinValueSpace 統一完了
+          - ValueId 衝突リスク完全排除（領域分離）
+          - 一貫性向上（単一の真実源）
+          - 保守性向上（手動カウンター管理不要）
+        - **統計**:
+          - Pattern 1: Local のみ（ConditionEnv なし）
+          - Pattern 2: Param + Local（ConditionEnv + 中間値）
+          - Pattern 3: Local のみ（PHI/Select 生成）
+          - Pattern 4: Param + Local（ConditionEnv + Select）
+        - **詳細**: phase202-a-pattern1-joinvaluespace.md
+  - [x] **Phase 203-A: JoinValueSpace 統一後のデッドコード削除** ✅ (完了: 2025-12-09, commit `de9fe3bf`)
+        - **目的**: Phase 201-202 で obsolete になったコードの削除
+        - **削除内容**:
+          - v1 API `build_for_break_condition()` 削除（70行）
+            - 3つの unit test を v2 API (`build_for_break_condition_v2`) に変換
+            - モジュールドキュメント更新（v2 が標準と明記）
+          - 未使用 import 2箇所削除
+            - inline_boundary_builder.rs: 未使用 JoinValueSpace import
+            - loop_with_if_phi_minimal.rs: 未使用 ValueId import
+          - stub 関数ドキュメント化
+            - lower_loop_with_break_to_joinir: router から呼ばれているため保持
+            - Phase 203-A ドキュメント追加（stub 理由と移行オプション説明）
+        - **統計**:
+          - 4ファイル変更
+          - 75行削減（117 deletions, 42 insertions）
+          - 全テスト PASS（821 passed）
+          - ビルドクリーン（0 errors）
+        - **成果**:
+          - コードベース整理完了
+          - v2 API への完全移行
+          - 保守性向上（デッドコード排除）
 
 ---
 
diff --git a/docs/development/current/main/joinir-architecture-overview.md b/docs/development/current/main/joinir-architecture-overview.md
index c3493a9a..3741e400 100644
--- a/docs/development/current/main/joinir-architecture-overview.md
+++ b/docs/development/current/main/joinir-architecture-overview.md
@@ -68,6 +68,74 @@ JoinIR ラインで守るべきルールを先に書いておくよ：
 
 ---
 
+## 1.9 ValueId Space Management (Phase 201)
+
+JoinIR の ValueId 割り当ては **JoinValueSpace** で一元管理され、3つの領域に分離されているよ：
+
+### 1.9.1 ValueId 空間のダイアグラム
+
+```
+JoinValueSpace Memory Layout:
+
+ 0          100        1000                     u32::MAX
+ ├──────────┼──────────┼──────────────────────────┤
+ │  PHI     │  Param   │       Local             │
+ │  Reserved│  Region  │       Region            │
+ └──────────┴──────────┴──────────────────────────┘
+
+PHI Reserved (0-99):
+  - LoopHeader PHI dst 用の予約領域
+  - reserve_phi(id) で特定 ID をマーク
+
+Param Region (100-999):
+  - alloc_param() で割り当て
+  - 使用箇所: ConditionEnv, CarrierInfo.join_id, CapturedEnv
+
+Local Region (1000+):
+  - alloc_local() で割り当て
+  - 使用箇所: Pattern lowerers (Const, BinOp, etc.)
+```
+
+### 1.9.2 JoinValueSpace の役割
+
+- **単一の真実源 (SSOT)**: すべての JoinIR ValueId 割り当てを一箇所で管理
+- **領域分離**: Param ID、Local ID、PHI dst が決して重複しない
+- **契約検証**: デバッグモードで違反を早期検出
+- **後方互換性**: 既存 API は継続動作
+
+### 1.9.3 各コンポーネントと ValueId 領域の対応表
+
+| コンポーネント | 使用領域 | 割り当て方法 | 用途 |
+|--------------|---------|------------|------|
+| ConditionEnv | Param (100-999) | `alloc_param()` | ループ条件変数の JoinIR ValueId |
+| CarrierInfo.join_id | Param (100-999) | `alloc_param()` | キャリア変数の JoinIR ValueId |
+| CapturedEnv | Param (100-999) | `alloc_param()` | 関数スコープ変数の JoinIR ValueId |
+| Pattern 1 lowerer | Local (1000+) | `alloc_local()` | 中間値（Const, Compare, etc.） |
+| Pattern 2 lowerer | Local (1000+) | `alloc_local()` | 中間値（Const, BinOp, etc.） |
+| Pattern 3 lowerer | Local (1000+) | `alloc_local()` | 中間値（PHI, Select, etc.） |
+| Pattern 4 lowerer | Local (1000+) | `alloc_local()` | 中間値（Select, BinOp, etc.） |
+| LoopHeaderPhiBuilder | PHI Reserved (0-99) | `reserve_phi()` | PHI dst ID 保護（上書き防止） |
+
+### 1.9.4 設計原則
+
+1. **領域の固定境界**
+   - 明確な境界（100, 1000）で領域を分離
+   - デバッグが容易（ValueId を見ればどの領域か一目瞭然）
+   - アロケータ間の調整不要
+
+2. **reserve_phi() vs alloc_phi()**
+   - PHI dst ID は MirBuilder（host 側）から来るため、JoinValueSpace は割り当てない
+   - `reserve_phi()` はマーカーのみ（「この ID を上書きするな」という契約）
+
+3. **value_id_ranges.rs との関係**
+   - `value_id_ranges.rs`: **モジュールレベルの分離**（min_loop, skip_ws 等の各モジュールに大きな固定範囲を割り当て）
+   - `JoinValueSpace`: **lowering 内部の分離**（param vs local vs PHI）
+   - 両者は相補的な役割
+
+詳細は `src/mir/join_ir/lowering/join_value_space.rs` と `phase201-join-value-space-design.md` を参照。
+
+---
+
 ## 2. 主な箱と責務
 
 ### 2.1 Loop 構造・検出ライン
diff --git a/docs/development/current/main/phase202-summary.md b/docs/development/current/main/phase202-summary.md
new file mode 100644
index 00000000..fe3963a3
--- /dev/null
+++ b/docs/development/current/main/phase202-summary.md
@@ -0,0 +1,272 @@
+# Phase 202: Pattern 1-4 JoinValueSpace Unification
+
+**Status**: ✅ Complete
+**Date**: 2025-12-09
+**Commits**:
+- `6e778948` Phase 202-A (Pattern 1)
+- `98e81b26` Phase 202-B (Pattern 3)
+- `ae741d97` Phase 202-C (Pattern 4)
+
+## Overview
+
+Phase 202 unified all JoinIR loop patterns (Pattern 1-4) to use the **JoinValueSpace** system introduced in Phase 201, eliminating manual ValueId allocation counters and ensuring complete ValueId collision safety through region separation.
+
+## Motivation
+
+Phase 201 successfully migrated Pattern 2 to JoinValueSpace, revealing the benefits of unified ValueId allocation:
+- **Safety**: Disjoint regions (PHI/Param/Local) prevent collisions
+- **Consistency**: Single allocation mechanism across all patterns
+- **Maintainability**: No manual counter management
+- **Debuggability**: Clear region boundaries (100, 1000)
+
+Phase 202 extended this to the remaining patterns (1, 3, 4) to achieve complete architectural consistency.
+
+## Implementation Summary
+
+### Phase 202-A: Pattern 1 (Simple While)
+
+**File Changes**:
+- `simple_while_minimal.rs`: Replace `value_counter` with `JoinValueSpace`
+- `pattern1_minimal.rs`: Create and pass `JoinValueSpace` to lowerer
+- `loop_view_builder.rs`: Create `JoinValueSpace` in router
+
+**ValueId Usage**:
+| Region | Usage |
+|--------|-------|
+| PHI Reserved (0-99) | ❌ Not used |
+| Param (100-999) | ❌ Not used (no ConditionEnv) |
+| Local (1000+) | ✅ All temps (Const, Compare, UnaryOp) |
+
+**Why Pattern 1 is simpler**: No break conditions → No ConditionEnv → No Param region needed
+
+**Test Results**:
+```bash
+$ cargo test --release --lib pattern
+✅ 119 passed
+
+$ ./target/release/hakorune apps/tests/loop_min_while.hako
+✅ Output: "0 1 2"
+```
+
+### Phase 202-B: Pattern 3 (If-Else PHI)
+
+**File Changes**:
+- `loop_with_if_phi_minimal.rs`: Replace `value_counter` with `JoinValueSpace`
+- `pattern3_with_if_phi.rs`: Create and pass `JoinValueSpace` to lowerer
+- `loop_patterns/with_if_phi.rs`: Update legacy wrapper
+
+**ValueId Usage**:
+| Region | Usage |
+|--------|-------|
+| PHI Reserved (0-99) | ❌ Not used |
+| Param (100-999) | ❌ Not used (PHI values from ConditionEnv) |
+| Local (1000+) | ✅ All temps (PHI, Select, BinOp) |
+
+**Test Results**:
+```bash
+$ cargo test --release --lib if_phi
+✅ 5/5 passed
+
+$ ./target/release/hakorune apps/tests/loop_if_phi.hako
+✅ Output: "9" (sum)
+
+$ ./target/release/hakorune apps/tests/loop_if_phi_continue.hako
+✅ Output: "9" (sum with continue)
+```
+
+### Phase 202-C: Pattern 4 (Continue)
+
+**File Changes**:
+- `loop_with_continue_minimal.rs`: Replace dual counters with `JoinValueSpace`
+- `pattern4_with_continue.rs`: Create and pass `JoinValueSpace` to lowerer
+
+**Dual Counter Problem (Before)**:
+```rust
+// Two separate counters - collision risk!
+let mut value_counter = 0u32;
+let mut join_value_counter = 0u32; // Manually incremented
+```
+
+**Unified Allocation (After)**:
+```rust
+// Single source of truth - no collision possible
+let mut join_value_space = JoinValueSpace::new();
+let mut alloc_value = || join_value_space.alloc_local();
+let mut alloc_param = || join_value_space.alloc_param();
+```
+
+**ValueId Usage**:
+| Region | Usage |
+|--------|-------|
+| PHI Reserved (0-99) | ❌ Not used |
+| Param (100-999) | ✅ ConditionEnv variables |
+| Local (1000+) | ✅ All temps (Select, BinOp, Const) |
+
+**Test Results**:
+```bash
+$ cargo test --release --lib continue
+✅ 11 passed (3 ignored)
+
+$ ./target/release/hakorune apps/tests/loop_continue_pattern4.hako
+✅ Output: "25" (single carrier)
+
+$ ./target/release/hakorune apps/tests/loop_continue_multi_carrier.hako
+✅ Output: "100\n10" (multi carrier)
+```
+
+## Comparison Table: Before vs After
+
+### Before Phase 202 (Manual Counters)
+
+| Pattern | Allocation Method | Collision Risk |
+|---------|------------------|----------------|
+| Pattern 1 | `value_counter = 0u32` | ⚠️ Yes (overlaps with ConditionEnv if added) |
+| Pattern 2 | `value_counter = 0u32` | ⚠️ Yes (collided with Param region) |
+| Pattern 3 | `value_counter = 0u32` | ⚠️ Yes (overlaps with ConditionEnv if added) |
+| Pattern 4 | `value_counter + join_value_counter` | ⚠️ Yes (dual counter management) |
+
+### After Phase 202 (JoinValueSpace)
+
+| Pattern | Allocation Method | Collision Risk |
+|---------|------------------|----------------|
+| Pattern 1 | `JoinValueSpace.alloc_local()` | ✅ No (Local region isolated) |
+| Pattern 2 | `JoinValueSpace.alloc_param() + alloc_local()` | ✅ No (Param/Local disjoint) |
+| Pattern 3 | `JoinValueSpace.alloc_local()` | ✅ No (Local region isolated) |
+| Pattern 4 | `JoinValueSpace.alloc_param() + alloc_local()` | ✅ No (Param/Local disjoint) |
+
+## Region Usage Matrix
+
+| Pattern | PHI (0-99) | Param (100-999) | Local (1000+) |
+|---------|------------|-----------------|---------------|
+| Pattern 1 | ❌ | ❌ | ✅ Const, Compare, UnaryOp |
+| Pattern 2 | ❌ | ✅ ConditionEnv, CarrierInfo | ✅ Const, BinOp, temps |
+| Pattern 3 | ❌ | ❌ | ✅ PHI, Select, BinOp |
+| Pattern 4 | ❌ | ✅ ConditionEnv (continue vars) | ✅ Select, BinOp, temps |
+
+**Key Insight**: Patterns 1 and 3 only need Local region (simple structure), while Patterns 2 and 4 need both Param and Local regions (complex condition analysis).
+
+## Benefits Achieved
+
+### 1. Safety
+- **ValueId collision impossible**: Disjoint regions (PHI/Param/Local) guarantee no overlap
+- **Contract enforcement**: Debug-mode assertions catch violations early
+- **Future-proof**: Easy to add new allocation patterns within regions
+
+### 2. Consistency
+- **Single allocation mechanism**: All patterns use JoinValueSpace
+- **Unified API**: `alloc_param()` / `alloc_local()` across all patterns
+- **Maintainable**: No pattern-specific counter logic
+
+### 3. Debuggability
+- **Clear region boundaries**: ValueId ranges reveal allocation source
+  - 100-999 → "This is a Param (ConditionEnv/CarrierInfo)"
+  - 1000+ → "This is a Local (intermediate value)"
+- **Traceable**: JoinValueSpace provides single point of debug logging
+
+### 4. Code Quality
+- **75 lines removed** (Phase 203-A dead code cleanup)
+- **No manual counter management**: Eliminated error-prone increment logic
+- **Pattern 4 dual counter eliminated**: Simplified from 2 counters to 1 allocator
+
+## Test Coverage
+
+### Build Status
+```bash
+$ cargo build --release --lib
+✅ Success (0 errors, 4 warnings)
+```
+
+### Unit Tests
+```bash
+$ cargo test --release --lib
+✅ 821 passed; 0 failed; 64 ignored
+```
+
+### E2E Tests (Representative Cases)
+
+| Test File | Pattern | Expected Output | Result |
+|-----------|---------|----------------|--------|
+| loop_min_while.hako | P1 | "0 1 2" | ✅ PASS |
+| minimal_ssa_bug_loop.hako | P2 | RC: 0 | ✅ PASS |
+| loop_if_phi.hako | P3 | "9" | ✅ PASS |
+| loop_continue_pattern4.hako | P4 | "25" | ✅ PASS |
+| loop_continue_multi_carrier.hako | P4 | "100\n10" | ✅ PASS |
+| phase200d_capture_minimal.hako | P2 | "30" | ✅ PASS |
+
+**No regressions**: All existing tests continue to pass.
+
+## Architecture Impact
+
+### Invariant Strengthening
+
+**Added to Section 1.9 of joinir-architecture-overview.md**:
+- ValueId space diagram (PHI/Param/Local regions)
+- Component-to-region mapping table
+- Design principles (fixed boundaries, reserve_phi vs alloc_phi)
+- Relationship with value_id_ranges.rs (module-level vs intra-lowering)
+
+### Component Updates
+
+**All pattern lowerers now follow the same structure**:
+```rust
+pub fn lower_pattern_X(
+    // ... pattern-specific params
+    join_value_space: &mut JoinValueSpace,
+) -> Result<JoinModule, ...> {
+    let mut alloc_local = || join_value_space.alloc_local();
+    let mut alloc_param = || join_value_space.alloc_param();
+    // ... lowering logic
+}
+```
+
+**Callers create JoinValueSpace before calling lowerer**:
+```rust
+let mut join_value_space = JoinValueSpace::new();
+let result = lower_pattern_X(..., &mut join_value_space)?;
+```
+
+## Related Work
+
+### Phase 201 (Foundation)
+- Introduced JoinValueSpace box
+- Migrated Pattern 2 as reference implementation
+- Established Param/Local region separation
+- Validated with 821 unit tests
+
+### Phase 203-A (Cleanup)
+- Removed obsolete v1 API (70 lines)
+- Converted 3 unit tests to v2 API
+- Removed 2 unused imports
+- Documented stub functions
+
+### Future Phases (Phase 204+)
+- Pattern 5 (Trim/JsonParser) integration
+- Advanced carrier analysis with JoinValueSpace
+- Potential PHI reservation usage (currently unused)
+
+## Commit History
+
+```
+6e778948 feat(joinir): Phase 202-A Pattern 1 uses JoinValueSpace
+98e81b26 feat(joinir): Phase 202-B Pattern 3 uses JoinValueSpace
+ae741d97 feat(joinir): Phase 202-C Pattern 4 uses JoinValueSpace, unify dual counters
+```
+
+## References
+
+- **Phase 201**: JoinValueSpace design and Pattern 2 migration
+- **JoinValueSpace Implementation**: `src/mir/join_ir/lowering/join_value_space.rs`
+- **Pattern Lowerers**:
+  - `simple_while_minimal.rs` (Pattern 1)
+  - `loop_with_break_minimal.rs` (Pattern 2)
+  - `loop_with_if_phi_minimal.rs` (Pattern 3)
+  - `loop_with_continue_minimal.rs` (Pattern 4)
+- **Architecture Overview**: `joinir-architecture-overview.md` Section 1.9
+- **Design Document**: `phase201-join-value-space-design.md`
+- **Pattern 1 Details**: `phase202-a-pattern1-joinvaluespace.md`
+
+## Conclusion
+
+Phase 202 achieved complete architectural consistency across all JoinIR loop patterns by migrating Pattern 1, 3, and 4 to the unified JoinValueSpace system. This eliminates all ValueId collision risks, simplifies maintenance, and establishes a solid foundation for future JoinIR enhancements.
+
+**Key Achievement**: 4/4 patterns (100%) now use JoinValueSpace, with 0 manual counter systems remaining in the codebase.