hakorune/docs/development/current/main/phase120_selfhost_stable_paths.md

Phase 120: selfhost Stage-3 代表パスの安定化

0. ゴール

• JoinIR Strict ON 環境で selfhost 経路（Stage-3 .hako コンパイラ）が安定動作することを確認
• 代表的な .hako プログラム（2-3本）を選定し、NYASH_JOINIR_STRICT=1 での実行を記録
• フォールバック・警告・エラーを洗い出し、Phase 106-115 完了時点のベースラインを確立

---

1. スコープと非スコープ

スコープ（今回やること）

1. 代表パス選定: selfhost で使う .hako ファイルから代表的なものを2-3本選定
2. docs 整理: 代表パスの期待フロー・JoinIR Strict モードの意味を1ドキュメントにまとめる
3. 実行調査: NYASH_JOINIR_STRICT=1 で各代表パスを実行し、フォールバック・警告・エラーを記録
4. スモークスクリプト作成: 代表パスの実行を再現できる smoke スクリプト化（tools/smokes/v2/ 形式）
5. ベースライン確立: Phase 106-115 完了時点での動作状況を記録（Phase 120 実装前の基準点）

非スコープ（今回はやらない）

• 実装修正: JoinIR 経路の実装バグ修正（Phase 122+ に回す）
• hako_check 統合: Phase 121 で設計を行う（今回は selfhost パスのみ）
• 全プログラム網羅: 代表的なもの2-3本のみ（全 .hako の検証は別 Phase）

---

2. Task 1: 代表パス選定と期待フロー整理

2.1 代表パスの選定基準

Phase 120 で扱う「代表パス」の条件:

基準	説明
selfhost 経路で実行	NYASH_USE_NY_COMPILER=1 等の selfhost 環境変数で動作するもの
Stage-3 対象	.hako コンパイラ自体、または selfhost で動作する実用プログラム
複雑さのバランス	単純すぎず（hello world）、複雑すぎず（全 selfhost コンパイラ）のもの
既存テスト可能	apps/ または local_tests/ に既に存在し、動作確認済みのもの

推奨候補（2-3本選定）:

1. 簡易パーサーテスト: apps/tests/peek_expr_block.hako 等（簡単な制御構造）
2. ループ・PHI 含む: apps/tests/loop_min_while.hako 等（JoinIR If/Loop Lowering 対象）
3. 実用スクリプト: apps/examples/ から1本（FileBox/StringBox 使用等）

2.2 期待フローのドキュメント化

ファイル: docs/development/current/main/selfhost_stage3_expected_flow.md（新規）

記載内容:

# selfhost Stage-3 期待フロー（Phase 120 時点）

## 概要

Phase 106-115 完了時点での selfhost 経路（Stage-3 .hako コンパイラ）の動作フローを記録。

## 実行環境

- **VM バックエンド**: `./target/release/nyash program.hako`（デフォルト）
- **LLVM バックエンド**: `./target/release/nyash --backend llvm program.hako`
- **selfhost 有効**: `NYASH_USE_NY_COMPILER=1` 等の環境変数

## JoinIR Strict モードとは

**環境変数**: `NYASH_JOINIR_STRICT=1`

**目的**: JoinIR 経路で旧 MIR/PHI 経路へのフォールバックを禁止し、厳格に JoinIR Lowering のみを使用

**期待される動作**:
- ✅ If/Loop Lowering が完全に JoinIR 経由で動作
- ❌ 旧 PHI 生成器へのフォールバックは禁止（エラーで停止）
- ⚠️ 警告: フォールバック候補があれば警告出力

## 代表パスの期待フロー

### 1. peek_expr_block.hako（簡易パーサーテスト）

**期待**:
- ✅ If 文が JoinIR If Lowering で処理
- ✅ ブロック式が正常に評価
- ✅ NYASH_JOINIR_STRICT=1 でもエラーなし

### 2. loop_min_while.hako（ループ・PHI 含む）

**期待**:
- ✅ Loop が JoinIR Loop Lowering で処理
- ✅ PHI 命令が正しく生成（ループ変数の合流）
- ⚠️ 警告: 旧 PHI 経路へのフォールバック候補があるかもしれない（Phase 120 調査対象）

### 3. [実用スクリプト名]（実用例）

**期待**:
- ✅ FileBox/StringBox 等の Box 操作が正常動作
- ✅ 複雑な制御構造が JoinIR 経由で処理
- ⚠️ 警告: 複雑さによってはフォールバックや警告が出る可能性

## Phase 120 の目標

上記の「期待」と「実際の動作」を比較し、ギャップを記録する。
実装修正は Phase 122+ で行う（Phase 120 はベースライン確立のみ）。

---

3. Task 2: 実行調査とログ記録

3.1 実行コマンド

各代表パスについて、以下のコマンドで実行し、出力を記録する:

# VM バックエンド（デフォルト）
NYASH_JOINIR_STRICT=1 NYASH_USE_NY_COMPILER=1 \
  ./target/release/nyash [代表パス.hako] 2>&1 | tee /tmp/phase120_vm_[name].log

# LLVM バックエンド（オプション）
NYASH_JOINIR_STRICT=1 NYASH_USE_NY_COMPILER=1 \
  ./target/release/nyash --backend llvm [代表パス.hako] 2>&1 | tee /tmp/phase120_llvm_[name].log

3.2 記録内容

ログファイル: /tmp/phase120_execution_results.txt（新規）

記録形式:

=== Phase 120: selfhost Stage-3 代表パス実行記録 ===
実行日時: 2025-12-04
Phase 106-115 完了時点のベースライン

--- 代表パス 1: peek_expr_block.hako ---
コマンド: NYASH_JOINIR_STRICT=1 NYASH_USE_NY_COMPILER=1 ./target/release/nyash apps/tests/peek_expr_block.hako
結果: ✅ 成功 / ❌ エラー / ⚠️ 警告あり

エラー・警告メッセージ:
[ログ出力をここに貼り付け]

備考:
- [気づいた点や特記事項]

--- 代表パス 2: loop_min_while.hako ---
...

3.3 分類基準

ログ分類:

分類	判定基準	対応
✅ 完全成功	エラーなし、警告なし、期待通りの出力	ベースライン記録
⚠️ 警告あり	実行成功、警告メッセージあり	Phase 122+ で調査
❌ エラー	実行失敗、エラーで停止	Phase 122+ で修正

---

4. Task 3: スモークスクリプト作成

4.1 実装内容

ファイル: tools/smokes/v2/profiles/integration/selfhost/phase120_stable_paths.sh（新規）

スクリプト構造:

#!/bin/bash
# Phase 120: selfhost Stage-3 代表パス smoke テスト

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "$SCRIPT_DIR/../../../common.sh"

# Phase 120 環境変数
export NYASH_JOINIR_STRICT=1
export NYASH_USE_NY_COMPILER=1

# 代表パス 1: peek_expr_block.hako
run_test "selfhost_peek_expr" "apps/tests/peek_expr_block.hako" "vm"

# 代表パス 2: loop_min_while.hako
run_test "selfhost_loop_min" "apps/tests/loop_min_while.hako" "vm"

# 代表パス 3: [実用スクリプト]
run_test "selfhost_example" "apps/examples/[name].hako" "vm"

# LLVM バックエンド版（オプション）
# run_test "selfhost_peek_expr_llvm" "apps/tests/peek_expr_block.hako" "llvm"

echo "[Phase 120] selfhost stable paths smoke test completed"

4.2 統合

スモークテストランナーに追加:

tools/smokes/v2/profiles/integration/integration_profile.txt に以下を追加:

selfhost/phase120_stable_paths.sh

4.3 実行確認

# 単発実行
bash tools/smokes/v2/profiles/integration/selfhost/phase120_stable_paths.sh

# integration プロファイル全体実行
tools/smokes/v2/run.sh --profile integration --filter "selfhost_*"

---

5. Task 4: ベースライン確立とドキュメント更新

5.1 実装内容

ファイル: docs/development/current/main/phase120_baseline_results.md（新規）

記載内容:

# Phase 120: selfhost Stage-3 ベースライン結果

## 実行日時

2025-12-04（Phase 106-115 完了直後）

## 環境

- **Rust VM**: ./target/release/nyash
- **LLVM**: llvmlite ハーネス（オプション）
- **JoinIR Strict**: NYASH_JOINIR_STRICT=1
- **selfhost**: NYASH_USE_NY_COMPILER=1

## 代表パス実行結果

### 1. peek_expr_block.hako

| 項目 | 結果 |
|------|------|
| **実行結果** | ✅ 成功 / ⚠️ 警告 / ❌ エラー |
| **エラーメッセージ** | [ログから抽出] |
| **警告メッセージ** | [ログから抽出] |
| **備考** | [特記事項] |

### 2. loop_min_while.hako

[同様の表]

### 3. [実用スクリプト名]

[同様の表]

## Phase 122+ への課題

**優先度高**:
- [ ] [エラー1の説明]
- [ ] [エラー2の説明]

**優先度中**:
- [ ] [警告1の説明]
- [ ] [警告2の説明]

**優先度低（最適化）**:
- [ ] [改善案1]
- [ ] [改善案2]

## 結論

Phase 120 時点での selfhost Stage-3 経路は：
- ✅ **基本動作**: [成功した代表パスの数]本
- ⚠️ **警告あり**: [警告があった数]本
- ❌ **エラー**: [エラーが出た数]本

Phase 122+ で上記課題を段階的に解決する。

5.2 CURRENT_TASK.md 更新

ファイル: CURRENT_TASK.md（修正）

Phase 120 セクション追加:

### 🎯 Phase 120: selfhost Stage-3 代表パスの安定化（完了）

- ✅ 代表パス選定: [選定した .hako ファイル名]
- ✅ 期待フロー整理: selfhost_stage3_expected_flow.md 作成
- ✅ 実行調査完了: NYASH_JOINIR_STRICT=1 での動作確認
- ✅ ベースライン確立: phase120_baseline_results.md 作成
- ✅ スモークスクリプト: phase120_stable_paths.sh 作成

**次のステップ**: Phase 121（hako_check JoinIR 統合設計）

---

6. 完成チェックリスト（Phase 120）

• 代表パス 2-3本の選定完了（peek_expr_block.hako 等）
• selfhost_stage3_expected_flow.md 作成（期待フロー整理）
• NYASH_JOINIR_STRICT=1 での実行ログ記録（/tmp/phase120_execution_results.txt）
• phase120_baseline_results.md 作成（ベースライン確立）
• スモークスクリプト作成（phase120_stable_paths.sh）
• integration プロファイルへの統合確認
• CURRENT_TASK.md 更新（Phase 120 完了記録）
• ビルド・テスト全 PASS（cargo build --release && bash phase120_stable_paths.sh）

---

7. 設計原則（Phase 120 で確立）

ベースライン First

【Phase 120 の哲学】
実装修正の前に、「現状を正確に記録する」

Flow:
    Phase 106-115 完了
        ↓
    Phase 120: 現状記録（ベースライン確立）
        ↓
    Phase 121: 設計（hako_check 統合計画）
        ↓
    Phase 122+: 実装修正（段階的改善）

代表パスの活用

少数精鋭の代表パスで効率的に検証:

• 2-3本で selfhost 経路の主要パターンをカバー
• 簡単・中間・複雑の3段階でバランス
• 既存テストを活用（新規作成は最小限）

JoinIR Strict モードの意義

Phase 120 での使い方:

• 厳格モード: フォールバックを禁止し、JoinIR 経路の完全性を確認
• 警告収集: 現状の JoinIR 経路の課題を可視化
• Phase 122+ の修正指針: 警告・エラーが修正の優先順位を決める

---

Phase 120 指示書完成日: 2025-12-04（Phase 106-115 完了直後）