hakorune/docs/development/current/main/phase49-selfhost-joinir-depth2-design.md

# Phase 49-SELFHOST-NORM-DEPTH2: selfhost depth2 Normalized 設計メモ（コード変更なし）

## 1. Goal & Scope
- 目標: `.hako → Program/MIR JSON → JoinIR(Structured) → Normalized → MIR → VM/LLVM` の depth2 パイプラインを selfhost でも踏めるように設計を固める。
- フォーカスする selfhost ループ（Phase 183 の棚卸しを前提に「軽い P2/P3」を 2 本に固定）:
  - 対象A: `selfhost_token_scan_p2.hako` / 関数 `selfhost_token_scan_p2`（P2 カウンタループ、break あり・continue なし・MethodCall なし）。
  - 対象B: `selfhost_if_sum_p3.hako` / 関数 `selfhost_if_sum_p3`（P3 if-sum: sum+count、条件は Compare のみ・MethodCall なし）。
  - Out of Scope（今回扱わない）: P5/Trim 相当の heavy ループ、MethodCall 多用ループ、selfhost の他ループ。

## 2. 現状整理（Status Snapshot）
- Phase 183 時点: selfhost depth2 の代表ループは棚卸し済みだが、Normalized 経路や shape_guard は未整備。
- JsonParser 側: P1〜P4 代表形が canonical Normalized（Phase 41/48）で安定、StepScheduleBox/shape_guard/normalized_bridge が揃っている。
- selfhost: Program/MIR JSON までは出せるが、JoinIR→Normalized→MIR への橋は未設計。まずは P2/P3 の軽量ループに限定して設計する。

## 3. ループ→Pattern/Shape マッピング表（確定）
| Loop 名（仮） | Pattern 想定 | Normalized shape 想定 | 必要キャリア | 特記事項 |
| --- | --- | --- | --- | --- |
| selfhost_token_scan_p2 | P2 core（break あり/continue なし） | Pattern2 core（JsonParser skip_ws と同列） | ループ変数 + count | body-local/MethodCall なし |
| selfhost_if_sum_p3 | P3 if-sum minimal | Pattern3 if-sum minimal/multi | sum + count + ループ変数 | MethodCall なし、条件は Compare のみ |

## 4. depth2 パイプライン設計（責務メモ）
```
.hako (selfhost) → Program/MIR JSON （selfhost front-end）
    → JoinIR(Structured) （JoinIR front-end / ast_lowerer・fixtures）
    → Normalized （normalized.rs + shape_guard）
    → MIR （normalized_bridge 直 or Structured 再構成フォールバック）
    → VM/LLVM 実行
```
- selfhost front-end: Program/MIR JSON を生成（既存 Stage-1/Stage-3）。
- JoinIR front-end: Program/MIR JSON → Structured JoinModule（既存 ast_lowerer + 追加 selfhost fixtures）。
- Normalized: shape_guard で P2/P3 自動判定 → Structured→Normalized 変換。
- Bridge: canonical セット（P1〜P4）は direct Normalized→MIR を優先、非対応は Structured 再構成フォールバック。
- 実行: VM/LLVM は JsonParser と同じ経路を共用。

## 5. フィクスチャとテスト計画（dev-only）
- Program JSON:
  - `docs/private/roadmap2/phases/normalized_dev/fixtures/selfhost_token_scan_p2.program.json`
  - `docs/private/roadmap2/phases/normalized_dev/fixtures/selfhost_if_sum_p3.program.json`
- Structured JoinModule helper（normalized::fixtures）:
  - `build_selfhost_token_scan_p2_structured_for_normalized_dev()`
  - `build_selfhost_if_sum_p3_structured_for_normalized_dev()`
- テスト（normalized_dev feature 下）:
  - Structured→MIR vs Structured→Normalized→MIR(direct) の VM stdout 比較を追加。
  - shape_guard が誤判定した場合は Fail-Fast させ、対象ループ以外はスコープ外と明示。

## 6. Out of Scope / 次フェーズ送り
- heavy selfhost ループ（MethodCall 多用、P5/Trim 依存）。
- Normalized 最適化や verifier 拡張（設計のみ、実装は Phase 50+）。
- selfhost 以外の新規ループ適用。

## 7. Next steps（49-B/50 に向けたメモ）
- normalized::fixtures に selfhost 用 helper を追加し、shape_guard に selfhost shape variant を足す。
- tests/normalized_joinir_min.rs に selfhost ループの比較テストを追加（dev-only）。
- canonical 昇格は Phase 50 以降で検討（まずは dev 正規化を通すことに専念）。

## 8. Status update（Phase 50 反映）
- 対象ループを `selfhost_token_scan_p2` / `selfhost_if_sum_p3` に確定し、normalized_dev フィクスチャと Structured helper を追加済み。
- ShapeGuard に selfhost 用 shape を追加し、Structured→Normalized→MIR(direct) の dev 比較テストで Structured 直経路と一致するところまで実装完了（canonical 化は後続フェーズ）。

## 9. Phase 51（仮）SELFHOST‑NORM‑DEV‑EXTEND

Phase 50 の selfhost P2/P3 dev Normalized の足場を使い、selfhost 側でもう少し実戦寄りの形状を dev Normalized に追加する。
canonical 昇格は別フェーズで扱い、このフェーズでは dev-only のまま固定する。

### 追加対象（dev-only）

| ループ名 | 想定パターン | ねらい | キャリア/更新 | 備考 |
| --- | --- | --- | --- | --- |
| selfhost_token_scan_p2_accum | P2 core（break あり/continue なし） | P2 で複数キャリア更新の安定化 | i + count + acc（acc += i, count += 1） | name ガード dev-only（構造判定が安定したら撤去） |
| selfhost_if_sum_p3_ext | P3 if-sum family | then/else 両側更新の安定化 | i + sum + count（then: sum+=i,count+=1 / else: sum+=1） | name ガード dev-only（構造判定が安定したら撤去） |

### 受け入れ条件（Phase 51）

- 上記 2 本が fixtures + shape_guard + dev 比較テストまで揃い、狙い撃ちテストが緑。
- normalized_dev 以外の挙動は不変（canonical/既定経路に影響なし）。

## 10. Phase 52（仮）SELFHOST‑SHAPE‑STRUCT‑SIGNATURE（dev-only）

Phase 50–51 で入れた selfhost shape の name ガードを、可能な範囲で「構造判定（structural signature）」へ寄せる育成フェーズ。
このフェーズでは **name ガードの全面撤去は狙わず**、構造シグネチャで一次判定 → 曖昧な場合のみ dev-only name ガードで絞る二段階 detector を導入する。

### ねらい
- selfhost P2/P3 が JsonParser/canonical 群と混線しないためのガードを、by-name 依存から段階的に縮退させる。
- 将来の selfhost ループ追加（Phase 53+）時に「構造で識別できる軸」を SSOT として固定する。

### 構造シグネチャ候補（一次判定）

#### Selfhost P2 core family（TokenScanP2 / TokenScanP2Accum）
- Structured JoinModule で `loop_step` が存在し、tail-call で自分自身に戻る P2 ブレークループであること。
- `loop_step` のパラメータ数が **3〜4**（`i` + host param + 1〜2 carriers）で、body 内に `Select` が出ないこと。
- body の主要 Compute が `Compare`（break/cond）と `Add` 系に限定され、外部/BoxCall が含まれないこと。
- **注意**: JsonParser `skip_ws_mini` と構造が近く、一次判定だけでは区別不能なケースがある。

#### Selfhost P3 if-sum family（IfSumP3 / IfSumP3Ext）
- 現状の selfhost baseline は **P2-like skeleton（normalize_pattern2_minimal 委譲）** のままなので、一次判定は「P3 の理想形（Select を含む if-sum）」を要求しない。
- `loop_step` のパラメータ数が **4**（`i` + host param + `sum` + `count`）で、break 由来の `Ge` Compare（params 間）が存在すること。
- tail-call によるループ継続を持ち、body が純粋な算術更新のみで、外部/BoxCall が含まれないこと。

### 二段階 detector 方針
1) 上記の構造シグネチャで Selfhost family candidate を一次判定  
2) 一次判定が他 shape と曖昧な場合のみ、**dev-only name ガードで最終確定**  

name ガードは `normalized_dev` 限定・混線防止用途に閉じ、canonical/本番経路には持ち込まない。

### 撤去条件（次フェーズ）
- Phase 53+ で selfhost 形状のバリエーションが 3〜4 本以上に増え、構造軸（carrier 数/Compare 配列/StepSchedule など）が安定したら、
  P2/P3 それぞれで name ガードの適用範囲を縮小→最終撤去する。

## 11. Phase 53: SELFHOST‑NORM‑DEV‑EXPAND（dev-only バリエーション拡大）

Phase 50–51 で selfhost P2/P3 dev Normalized の足場を構築し、Phase 52 で構造シグネチャ軸（carrier 数、Compare 配列等）を導入した。
Phase 53 では **実戦寄りループを P2/P3 各 1〜2 本追加**し、構造シグネチャ軸を育成・name ガード適用範囲を縮小する。

### 追加対象ループ（dev-only）

| ループ名 | 想定パターン | ソース箇所 | キャリア/更新 | 構造的特徴 |
| --- | --- | --- | --- | --- |
| **selfhost_args_parse_p2** | P2 core（break あり/continue なし） | `apps/selfhost-runtime/runner.hako:20-33` | i + box_pref（文字列更新）| 1 キャリア、文字列比較多用、StringBox メソッド（indexOf/substring） |
| **selfhost_stmt_count_p3** | P3 if-sum family（多分岐） | `apps/selfhost-runtime/mir_loader.hako:76-89` | i + 9 カウンタ（r/e/l/iff/lp/br/ct/tr/ex） | 9 キャリア、多段 if-else（9 分岐）、MethodCall（st.get/str） |

### 選定理由

#### P2: selfhost_args_parse_p2
- **実戦的 P2**: コマンドライン引数パース（`--box-pref=` 等）
- **構造的差異**:
  - 既存 P2（token_scan, token_scan_accum）は数値キャリアのみ
  - **本ループ**: 文字列キャリア（box_pref）+ StringBox MethodCall（indexOf/substring/length）
  - **構造判定軸育成**: MethodCall 出現パターン、キャリア型多様性
- **name ガード必要性**: StringBox MethodCall が入るため、JsonParser P2 との混線は低い（構造一次判定で十分分離可能）
  - **dev-only name ガード**: 最終確定のみ（構造判定が主軸）

#### P3: selfhost_stmt_count_p3
- **実戦的 P3**: MIR 文種別カウント（Return/Expr/Local/If/Loop/Break/Continue/Try/Extern）
- **構造的差異**:
  - 既存 P3（if_sum, if_sum_ext）は 2〜3 キャリア・単純 if-sum
  - **本ループ**: **9 キャリア**（r/e/l/iff/lp/br/ct/tr/ex）+ **9 分岐**（多段 if-else）
  - **構造判定軸育成**:
    - キャリア数上限検証（9 は P3 範囲内か？）
    - 多段 if-else パターン（Select チェーン長）
    - MethodCall 出現（st.get/str）
- **name ガード必要性**: MethodCall + 9 キャリアで JsonParser P3 と明確に分離
  - **dev-only name ガード**: 構造判定優先、最終確定のみ

### 構造シグネチャ軸育成方針（Phase 52 継続）

#### P2 family 構造軸（強化）
1. **キャリア数**: 1〜3 → **型多様性追加**（Integer, String, mixed）
2. **MethodCall 出現**: なし → **StringBox メソッド許容**（indexOf/substring/length）
3. **Compare 配列**: `Lt`/`Ge` 単一 → **複合条件（`Eq` 多用）**

#### P3 family 構造軸（強化）
1. **キャリア数上限**: 2〜4 → **9 キャリア検証**（P3 範囲内確定）
2. **分岐数**: 単純 if-sum → **多段 if-else（9 分岐）**
3. **MethodCall 出現**: なし → **JsonNodeBox メソッド許容**（get/str）
4. **Select チェーン長**: 構造的計測（Normalized 時の Select 深度）

### 二段階 detector 実装方針（Phase 52 継承）

```rust
// P2: selfhost_args_parse_p2 detector
fn is_selfhost_args_parse_p2(module: &JoinModule) -> bool {
    // 1. 構造一次判定（優先）
    if !has_p2_break_pattern(module) { return false; }
    let carrier_count = count_carriers(module);
    if carrier_count < 1 || carrier_count > 3 { return false; }

    // StringBox MethodCall 許容（indexOf/substring）
    let methodcalls = count_methodcalls(module);
    if methodcalls > 5 { return false; } // 過剰な MethodCall は除外

    // 2. dev-only name 最終確定（曖昧時のみ）
    #[cfg(feature = "normalized_dev")]
    if !function_name_matches("selfhost_args_parse_p2") { return false; }

    true
}

// P3: selfhost_stmt_count_p3 detector
fn is_selfhost_stmt_count_p3(module: &JoinModule) -> bool {
    // 1. 構造一次判定（優先）
    if !has_p3_if_sum_pattern(module) { return false; }
    let carrier_count = count_carriers(module);
    if carrier_count < 2 || carrier_count > 10 { return false; } // 9 キャリア許容

    // 多段 if-else パターン確認
    let branch_count = count_if_else_branches(module);
    if branch_count < 2 { return false; }

    // JsonNodeBox MethodCall 許容（get/str）
    let methodcalls = count_methodcalls(module);
    if methodcalls > 10 { return false; } // 過剰な MethodCall は除外

    // 2. dev-only name 最終確定（曖昧時のみ）
    #[cfg(feature = "normalized_dev")]
    if !function_name_matches("selfhost_stmt_count_p3") { return false; }

    true
}
```

### name ガード適用範囲縮小条件

Phase 53 実装後、以下の条件で name ガードを撤去可能：
1. **構造軸が 5 軸以上安定**（carrier 数/型/MethodCall 数/Compare 配列/分岐数）
2. **P2/P3 各 6 本以上の dev ループ蓄積**（バリエーション十分）
3. **誤判定率 < 5%**（構造一次判定の精度検証）

現状（Phase 53 後）:
- P2: 4 本（token_scan, token_scan_accum, args_parse, +1 予定）
- P3: 4 本（if_sum, if_sum_ext, stmt_count, +1 予定）
- 構造軸: 4 軸（carrier 数/型/MethodCall/Compare）
- **撤去条件未達** → name ガード継続（dev-only）

### 受け入れ基準（Phase 53）

- ✅ P2/P3 各 1〜2 本追加（合計 2〜4 本、最小 2 本）
- ✅ Program JSON + Structured builder 完備
- ✅ ShapeGuard 二段階判定実装（構造一次 + dev-only name 最終）
- ✅ dev VM 比較テスト追加（全 PASS）
- ✅ 構造軸 4〜5 本確立（carrier 数/型/MethodCall/Compare/分岐数）
- ✅ phase49 doc Phase 53 節完成（SSOT）
- ✅ 既存挙動不変（normalized_dev 以外）

### Out of Scope（Phase 54+）

- **name ガード完全撤去**: Phase 54 以降で構造軸が十分安定してから
- **canonical 昇格**: Phase 55+ で検討（dev 正規化安定後）
- **P4/P5 heavy ループ**: Phase 56+ で段階的追加

### 実装完了記録（Phase 53）

**実装日**: 2025-12-12

**追加内容**:
1. **Program JSON fixtures**: 2 個
   - `selfhost_args_parse_p2.program.json` (P2: string carrier + 条件分岐)
   - `selfhost_stmt_count_p3.program.json` (P3: 5 carriers + 多段 if-else)
2. **Structured builders**: 2 個（fixtures.rs）
   - `build_selfhost_args_parse_p2_structured_for_normalized_dev()`
   - `build_selfhost_stmt_count_p3_structured_for_normalized_dev()`
3. **ShapeGuard detectors**: 2 個（shape_guard.rs）
   - `is_selfhost_args_parse_p2()` (二段階判定: P2 core family + name guard)
   - `is_selfhost_stmt_count_p3()` (二段階判定: 2-10 carriers + name guard)
4. **dev VM 比較テスト**: 2 個（normalized_joinir_min.rs）
   - `normalized_selfhost_args_parse_p2_vm_bridge_direct_matches_structured()`
   - `normalized_selfhost_stmt_count_p3_vm_bridge_direct_matches_structured()`

**変更ファイル**:
- `phase49-selfhost-joinir-depth2-design.md` (+128 lines, Phase 53 節)
- `selfhost_args_parse_p2.program.json` (NEW, 60 lines)
- `selfhost_stmt_count_p3.program.json` (NEW, 150 lines)
- `fixtures.rs` (+48 lines, 2 builders)
- `shape_guard.rs` (+80 lines, 2 detectors + enum 拡張)
- `bridge.rs` (+8 lines, 2 shape handlers)
- `normalized.rs` (+10 lines, 2 roundtrip handlers)
- `ast_lowerer/mod.rs` (+2 lines, 2 entry point registrations)
- `normalized_joinir_min.rs` (+40 lines, 2 tests + imports)

**テスト結果**:
- ✅ normalized_dev: 40/40 PASS (2 新規テスト含む)
- ✅ lib regression: 939 PASS, 56 ignored
- ✅ 既存挙動不変確認完了

**構造軸育成成果**:
- P2 family: carrier 数 (1-3) + 型多様性（Integer/String）
- P3 family: carrier 数上限拡張（2-10）+ 多段 if-else パターン
- name ガード: 二段階判定で構造一次 + dev-only 最終確定に統一

**次フェーズ方針**（Phase 54+）:
- P2/P3 各 6 本以上蓄積後に name ガード適用範囲縮小検討
- 構造軸 5 軸以上安定（carrier 数/型/Compare/分岐数/StepSchedule）
- 誤判定率 < 5% 達成で撤去条件満たす