864a94d013
Phase 21.8 完了 (imports resolution): - ✅ using nyash.core.numeric.matrix_i64 as MatI64 完全対応 - ✅ hakorune_emit_mir.sh で imports 抽出・MirBuilder に配線 - ✅ MatI64/IntArrayCore の静的参照解決が安定動作 - ✅ matmul_core ベンチ MIR 生成成功 (VM/LLVM 両対応) Phase 25 設計完了 (Ring0/Ring1 + numeric ABI): - 🎯 Ring0/Ring1 責務分離を明文化 (Rust Freeze Policy 具体化) - 🎯 Call/ExternCall 明確な分離設計 - Call: Ring1 Hako 関数 (numeric core 等) - ExternCall: Ring0 intrinsic (rt_mem_* 等の FFI のみ) - 🎯 BoxCall → Call 変換方針確定 (AotPrep で実施) - 🎯 MatI64.mul_naive を NyNumericMatI64.mul_naive に分離 (System Hakorune subset で完全実装済み) 実装: - ✅ AotPrepNumericCoreBox 診断パス実装 (NYASH_AOT_NUMERIC_CORE=1) - ✅ numeric ABI ドキュメント整備 (NUMERIC_ABI.md) - ✅ System Hakorune subset 定義 (system-hakorune-subset.md) - ✅ IntArrayCore/MatI64 仕様固定 (lang/src/runtime/numeric/README.md) - ✅ ENV_VARS.md に NYASH_AOT_NUMERIC_CORE トグル追記 今後のタスク: - BoxCall(MatI64) → Call(NyNumericMatI64) 変換実装 (opt-in) - IntArrayCore の numeric core 整備 - matmul_core スモークテスト (NYASH_AOT_NUMERIC_CORE=0/1 両対応) 🎉 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
88 lines
5.0 KiB
Markdown
88 lines
5.0 KiB
Markdown
# System Hakorune Subset — Runtime / Numeric Core Design
|
||
|
||
Status: design-stage; subset definition only. No behavior change yet.
|
||
|
||
## Purpose
|
||
|
||
- Provide a small, predictable subset of Hakorune for implementing **runtime / numeric core logic** in Ring1（IntArrayCore, MatI64, stats, policy, etc.）。
|
||
- Make this subset explicit so that:
|
||
- Box / numeric kernels can be moved from Rust to `.hako` **without increasing semantic complexity**.
|
||
- AotPrep / VM / LLVM can rely on a restricted feature set when reasoning about these modules.
|
||
- Align with Phase 25 goals:
|
||
- Ring0（Rust）は intrinsic と最小 VM/FFI のみ。
|
||
- Ring1（Hakorune）は「元・C 相当の実装」をこの subset で記述する。
|
||
|
||
Related docs:
|
||
- Phase 25 roadmap: `docs/development/roadmap/phases/phase-25/README.md`
|
||
- Ring1 numeric runtime layout: `lang/src/runtime/numeric/README.md`
|
||
- Numeric ABI surface (IntArrayCore / MatI64): `docs/development/runtime/NUMERIC_ABI.md`
|
||
|
||
## Scope & Typical Use
|
||
|
||
- 対象モジュールの例:
|
||
- `nyash.core.numeric.intarray`（IntArrayCore 本体）
|
||
- `nyash.core.numeric.matrix_i64`（MatI64 本体）
|
||
- 将来の数値箱（例: F64ArrayCore, MatF64 など）
|
||
- ランタイムポリシー / stats / 軽量な AotPrep 補助ロジック
|
||
- 非対象（ここでは扱わないもの）:
|
||
- 高レベルアプリケーションロジック（UI、CLI コマンド等）。
|
||
- 重い I/O / ネットワーク / プラグイン動的ロード。
|
||
- 実験的な言語機能（例外、async 等）を前提とするコード。
|
||
|
||
## Allowed Features（推奨）
|
||
|
||
- 制御構造:
|
||
- `if / else`、`while`、インデックス付きの従来型 `for` ループ。
|
||
- ネストは OK だが、循環依存や過度な再帰は避ける。
|
||
- データ構造:
|
||
- Box フィールドを明示した構造体的なパターン（`handle.ptr`, `handle.len` 等）。
|
||
- 固定長 or 単純な一次元/二次元配列アクセス（IntArrayCore / MatI64）。
|
||
- 関数:
|
||
- 引数/戻り値が `i64` と Box/Handle 型に限定された関数。
|
||
- 純粋 or 副作用が局所（配列/行列への書き込み）のみの関数。
|
||
- エラーハンドリング:
|
||
- **Fail‑Fast** を前提とした設計（事前条件違反は即失敗）。
|
||
- 戻り値でのエラーコード運搬は禁止（AGENTS.md の対処療法禁止と合わせる）。
|
||
|
||
## Restricted / Forbidden Features
|
||
|
||
- 例外 / 非同期:
|
||
- `throw/try` や async 相当の機能は numeric core の実装では使わない方針（後続フェーズで必要になった場合に個別に設計）。
|
||
- 動的ディスパッチ:
|
||
- 文字列ベースの `by-name` ディスパッチ（`if method == "mul"` 等）は避け、事前に決まった numeric ABI 関数を直接呼び出す。
|
||
- 動的ロード / プラグイン依存:
|
||
- numeric core から直接プラグインをロードしない。必要なら上位層（アプリ側）がプラグイン経由で呼ぶ。
|
||
- 型拡張:
|
||
- 汎用的な「任意型の配列/行列」をここで扱わない。Phase 25 では **i64 専用（IntArrayCore / MatI64）** にスコープを絞る。
|
||
|
||
## Design Patterns & Guidelines
|
||
|
||
- 明示的ループ:
|
||
- 数値カーネルは map/filter 的な高階関数ではなく、`for` / `while` による明示ループで書く。
|
||
- これにより AotPrep / LLVM でのループ変換・アンローリング等の解析がしやすくなる。
|
||
- Box / Handle の役割分離:
|
||
- Box（例: `MatI64`）は **API と所有権** を管理する層。
|
||
- Handle/Core（例: `IntArrayCore`, `MatI64Core`）は **実データとループ本体** を持つ層。
|
||
- Box メソッドは「引数検査 → numeric ABI 呼び出し」の薄いラッパに留める。
|
||
- Fail‑Fast:
|
||
- インデックスや次元の検査は、「バグを隠さない」方向で実装する。
|
||
- `idx < 0` や `idx >= len` など明らかなバグは例外 or プロセス終了で即座に検出し、フォールバックや silent failure は行わない。
|
||
|
||
## Relation to Ring0 / Numeric ABI
|
||
|
||
- Ring0（Rust）:
|
||
- IntArrayCore / MatI64 向けには「ptr/len/rows/cols/stride を受け取る intrinsic」だけを提供する。
|
||
- ループ本体や境界チェックは実装しない（System Hakorune subset 側に責務を寄せる）。
|
||
- Ring1（Hakorune）:
|
||
- この subset 上で numeric ABI 関数群（`ny_numeric_intarray_*`, `ny_numeric_mat_i64_*`）を実装する。
|
||
- AotPrep は BoxCall → numeric ABI への `ExternCall` 変換を行い、LLVM 側は汎用 Call/ExternCall として扱うだけでよい。
|
||
|
||
## Roadmap（Phase 25 以降）
|
||
|
||
- Phase 25:
|
||
- Subset の定義を docs として固定（このファイル）。
|
||
- IntArrayCore / MatI64 の API 仕様と合わせて、どの機能を subset に含めるかを明示する。
|
||
- 後続フェーズ（22.x / 26.x など）:
|
||
- 実際の `.hako` 実装を subset 遵守で書き起こす。
|
||
- AotPrep / VM / LLVM の観点から「subset で書かれた numeric core を前提にした最適化/診断」を設計する。
|