# Phase 25 — 脱Rustランタイム / Ring0-Ring1 再編

Status: proposal（設計フェーズ・実装は後続ホスト想定）

## ゴール

- Rust 層を **Ring0（最小シード）** に縮退し、それ以外のランタイム・数値コア・箱ロジックを **Hakorune(Ring1)** 側へ段階的に移行する。
- 具体的には、Phase 21.6/21.8 で導入した:
  - `IntArrayCore`（数値一次元配列コア）
  - `MatI64`（行列箱・i64版）
 などを、「Rust プラグイン実装」ではなく **Hakorune 実装＋ごく薄い intrinsic** に置き換えるための設計ロードマップを固める。
- 新しい箱・数値カーネル・標準ランタイム機能は **原則 .hako で実装する** 方針を明文化し、「Rust Freeze Policy（Self‑Host First）」を Phase 25 で具体化する。

## レイヤー方針（Ring0 / Ring1）

### Ring0（Rust / C 相当 ― 最小シード）

**責務:**
- プロセス起動・エントリポイント
- OS / FFI / LLVM C API への極小ラッパ
- VM の実行コア（命令デコード・レジスタファイル・GC/alloc の最小部分）
- **汎用 intrinsic** のみ提供（例: メモリ確保・生ポインタload/store・基本的な memcpy 等）

**禁止 / 抑制:**
- 新しい Box 種類（IntArrayCore / MatI64 / StringBuilder 等）を Rust 側に増やさない。
- 新しい最適化ロジック・言語ルール・Box メソッド実装を Rust に追加しない（AGENTS.md 5.2 Rust Freeze Policy に準拠）。

### Ring1（Hakorune / Nyash ― System サブセット）

**責務:**
- 数値コア・行列コア・文字列ビルダなどの **「C 言語で書いていた部分」** を、Hakorune で実装する層。
- 代表例:
  - `nyash.core.numeric.intarray.IntArrayCore`
  - `nyash.core.numeric.matrix_i64.MatI64`
  - `StringBuilder` / 将来の `F64ArrayCore` 等
- ランタイムポリシー・統計・ログ・一部の AotPrep / MIR パス（構造的なもの）。

**方針:**
- Rust 側が提供するのは `alloc/free/copy/load/store` などの **型パラメトリックな intrinsic** のみ。
- 箱のフィールド管理（ptr+len+stride）、境界チェック、ループ本体、行列演算アルゴリズムなどは **すべて .hako 側で記述**。
- Ring1 コードは AOT して `stdlib` 相当の成果物（例: `stdlib.hbc`）として VM 起動時にロードする構造を目指す。

## スコープ（Phase 25）

Phase 25 は「設計とロードマップの確定」が主目的。実装・移行作業自体は後続フェーズ（22.x/26.x など）で分割実施する。

### 1) Rust Freeze の明文化とチェックリスト

- 既存の「Rust Freeze Policy（Self‑Host First）」を、ランタイム/箱/数値系に特化して再整理:
  - 新規 Box / ランタイム機能は Rust ではなく .hako で実装する。
  - Rust 変更は「最小の intrinsic 追加」か「バグ修正」に限定。
- PR / フェーズ用チェックリスト案を作成:
  - [ ] この変更は Ring0 の責務か？（VM/allocator/LLVM/OS FFI のみ）
  - [ ] 新しい Box/アルゴリズムを Rust に追加していないか？
  - [ ] .hako に移せる部分が残っていないか？

### 2) IntArrayCore / MatI64 の移行設計

- 現状:
  - Phase 21.6: Rust プラグイン `IntArrayCore` + Hako ラッパ Box。
  - Phase 21.8: `MatI64` Box を Hako で実装しつつ、コア配列は IntArrayCore に依存。
- 目標:
  - IntArrayCore の **本体ロジック（len 管理・get/set/fill 等）を Hako 側に移す**。
  - Rust 側は:
    - `rt_mem_alloc_i64(len) -> (ptr,len)`
    - `rt_mem_free_i64(ptr,len)`
    - `rt_unsafe_load_i64(ptr, idx)`
    - `rt_unsafe_store_i64(ptr, idx, val)`
    など、小さな intrinsic 群に縮退。
- タスク（設計レベル）:
  - 必要な intrinsic セットの定義（型・エラー処理ポリシー・Fail‑Fast方針）。
  - `nyash.core.numeric.intarray` の API 仕様と内部構造（ptr+len/所有権/ライフサイクル）を docs に固定。
  - MatI64 が IntArrayCore をどう利用するか（row-major/stride/ビューなど）を整理。

### 3) System Hakorune サブセットの定義

- Ring1 で「C 代替」として安全に使える記法/機能を定義:
  - 推奨: 明示ループ（while/for）、Fail‑Fast、Box フィールドの明示管理。
  - 慎重に: 例外/非同期/動的ロードなど、ランタイム依存が重い機能。
- ドキュメント案:
  - `docs/development/runtime/system-hakorune-subset.md`（候補）
  - 想定ユース:
    - numeric core / matrix core
    - runtime policy / stats
    - 一部 MIR/AotPrep ロジック

### 4) stdlib ビルド／ロード戦略のたたき台

- 目標:
  - 「Hakorune で書かれた runtime/numeric コード」を AOT して、VM 起動時に一括ロードする仕組みを設計。
- 方針案:
  - `tools/hakc_stdlib.sh`（仮）で:
    - `lang/src/runtime/**/*.hako` のうち Ring1 対象をコンパイルして `build/stdlib.hbc` を生成。
  - `hakorune` / `nyash` バイナリ起動時に:
    - `stdlib.hbc` を自動ロード（PATH または env で切り替え）。
  - Phase 25 では「どのモジュールを stdlib に含めるか」「ビルド/ロードの責任境界」を文章で決めるところまで。

## アウト・オブ・スコープ（Phase 25）

- 実際のコード移行（Rust 実装の削除や .hako への完全移植）は、このフェーズでは行わない。
- 新しい機能追加や大規模最適化（VM/LLVM 側）は対象外。
- 既存の 21.x フェーズのベンチ結果改善は、Phase 25 の直接スコープ外（ただし設計上のゴールには参考としてリンクする）。

## このフェーズ終了時の「完成形」

- Rust / Hakorune の責務分離が文書として明確になり、「新しい箱・数値カーネルは .hako で書く」がプロジェクトの合意として固定されている。
- IntArrayCore / MatI64 の「Rust→Hakorune 移行」手順が、段階ごとのタスクリストとして整理されている。
- System Hakorune サブセットと stdlib ビルド/ロード戦略のたたき台があり、後続フェーズ（例: Phase 22.x / 26.x）でそのまま実装に着手できる状態になっている。