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