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 を前提にした最適化/診断」を設計する。
|