hakorune/lang/src/runtime/numeric/README.md

# lang/src/runtime/numeric — Ring1 Numeric Runtime

Scope: Phase 21.6+ / 21.8 / 25 で導入する **数値コア箱（numeric core boxes）** を配置するディレクトリ。

## 目的

- ArrayBox/MapBox などの汎用箱とは別に、数値・行列・ビルダ系の「C 相当コア」を Ring1（Hakorune）側で実装する。
- 将来的には、このディレクトリ配下の `.hako` を AOT して `stdlib` 相当の成果物にまとめ、VM 起動時にロードする（Phase 25 以降）。

## 代表モジュール

- `intarray_core_box.hako`
  - 数値一次元配列コア（IntArrayCore）の Box ラッパ。
  - Phase 21.6: Rust プラグイン `IntArrayCore` に委譲。
  - Phase 25: `.hako` 実装に移行し、Ring0 は `alloc/free/load/store` などの intrinsic のみ提供する方針。
- `mat_i64_box.hako`
  - 行列箱 `MatI64`（i64 行列）の Box 実装。
  - Phase 21.6/21.8: IntArrayCore に委譲する naive 実装。
  - Phase 25: numeric ABI（`ny_numeric_mat_i64_*`）の薄ラッパとして整理し、VM / LLVM ともに「BoxCall → numeric core 関数への Call」という同じ MIR を実行する形を目指す（numeric 専用の ExternCall 境界は増やさない）。
  - 現状: 数値核 `mul_naive` の本体は `NyNumericMatI64.mul_naive` に分離し、`MatI64.mul_naive` はその薄ラッパとして実装。

## Phase 25 との関係

- Phase 25 では:
  - IntArrayCore / MatI64 の本体ロジックを `.hako` 側に移し、Rust 側は最小の numeric intrinsic と LLVM/OS FFI だけを持つ Ring0 とする。
  - AotPrep / builder で `BoxCall(MatI64, ...)` / `BoxCall(IntArrayCore, ...)` を **numeric core 関数への通常 `Call`** に変換する設計を導入する（BoxCall を LLVM まで持ち込まない）。
- このディレクトリはそのための **Ring1 numeric runtime の定位置**として扱う。
  - 本番やベンチでは、AOT 済み stdlib（例: `stdlib.hbc`）から `nyash.core.numeric.*` モジュールをロードする embedded モードを使用。
  - 開発時には、`NYASH_STDLIB_MODE=source`（候補）などで埋め込み stdlib を無効化し、このディレクトリ配下の `.hako` を直接コンパイルして挙動を確認する運用を想定。

## IntArrayCore Box API（設計メモ）

実装ファイル: `lang/src/runtime/numeric/intarray_core_box.hako`

### フィールド設計

- `handle: i64`
  - NyRT/Rust 側で管理される IntArrayCore インスタンスへのハンドル。
  - 現行実装では `nyash.intarray.*` C シンボル経由で操作される（Phase 25 以降で numeric ABI に移行予定）。
- `len: i64`
  - 配列長（要素数）。`new(len)` 時の引数と一致する前提。
  - 変更不可（再割り当てや resize は想定しない）。

### メソッド仕様（Box レベル）

- `static new(len: i64) -> IntArrayCore`
  - 役割: 長さ `len` の 0 初期化配列を作成する。
  - 事前条件:
    - `len >= 0` を前提とする（負値はバグ扱い; Fail‑Fast 寄りのポリシーで扱う）。
  - 実装メモ:
    - 現行: `externcall "nyash.intarray.new_h"(len)` を呼び、返ってきたハンドルを `handle` に格納。
    - 将来: numeric ABI（`ny_numeric_intarray_new` 等）経由で Core を構築し、Handle/Core の表現を段階的に置き換える。

- `length() -> i64`
  - 役割: 現在の要素数を返す。
  - 期待挙動:
    - 通常は `len` と同値。
    - Core 側の情報と不整合が生じないよう、Phase 25 以降は「単一の SSOT（Core 側）」に寄せる設計を検討する。

- `get_unchecked(idx: i64) -> i64`
  - 役割: インデックス `idx` から値を取得する。
  - 事前条件:
    - `0 <= idx < length()` を呼び出し側が保証する（unchecked の名の通り）。
  - エラー処理:
    - Phase 21.x 実装では、範囲外アクセス時に 0 を返すなどの挙動が残っているため、Phase 25 では「Fail‑Fast（バグを隠さない）」方向に整理する。
  - 用途:
    - MatI64 や numeric カーネル内部でのループ本体から使用する前提（System Hakorune subset 内）。

- `set_unchecked(idx: i64, v: i64) -> null`
  - 役割: インデックス `idx` に値 `v` を書き込む。
  - 事前条件:
    - `0 <= idx < length()` を呼び出し側が保証する。
  - エラー処理:
    - Phase 21.x 実装では戻り値でエラーコードを返す形跡があるが、Phase 25 では Fail‑Fast で統一し、Box レベルでは成功/失敗を返さない設計を目指す。

## MatI64 Box API（設計メモ）

実装ファイル: `lang/src/runtime/numeric/mat_i64_box.hako`

### フィールド設計

- `rows: i64`
  - 行数（row count）。`rows >= 0` を前提。
- `cols: i64`
  - 列数（column count）。`cols >= 0` を前提。
- `stride: i64`
  - 1 行あたりのステップ幅。現行実装では `cols` と同一（row‑major の連続配置）。
  - 将来、ビューやサブ行列を導入する場合に `stride != cols` を許容する余地を残す。
- `core: IntArrayCore`
  - 実データを保持する一次元配列コア（長さは `rows * cols` を前提）。

### メソッド仕様（Box レベル）

- `static new(rows: i64, cols: i64) -> MatI64`
  - 役割: `rows x cols` のゼロ初期化行列を作成する。
  - 事前条件:
    - `rows >= 0`, `cols >= 0`。
    - `rows * cols` が i64 の範囲内に収まること（オーバーフロー時は Fail‑Fast 寄りに扱う）。
  - 実装メモ:
    - `IntArrayCore.new(rows * cols)` を呼び出し、`stride = cols` として初期化。

- `rowsCount() -> i64`
  - 役割: 行数を返す（読み取り専用）。

- `colsCount() -> i64`
  - 役割: 列数を返す。

- `at(r: i64, c: i64) -> i64`
  - 役割: 要素 `(r, c)` を読み取る。
  - 事前条件:
    - `0 <= r < rows`, `0 <= c < cols` を呼び出し側が保証。
  - 実装メモ:
    - `idx = r * stride + c` を計算し、`core.get_unchecked(idx)` を呼ぶ。
  - 将来:
    - デバッグ/strict モードでは範囲チェックを追加するオプションを検討（prod ではループ性能優先）。

- `set(r: i64, c: i64, v: i64) -> null`
  - 役割: 要素 `(r, c)` に `v` を書き込む。
  - 事前条件:
    - `0 <= r < rows`, `0 <= c < cols`。
  - 実装メモ:
    - `idx = r * stride + c` を計算し、`core.set_unchecked(idx, v)` を呼ぶ。

- `mul_naive(b: MatI64) -> MatI64`
  - 役割: `me * b` のナイーブな O(n³) 行列積を計算する。
  - 事前条件:
    - 現行スケルトンでは「正方行列かつ形状一致」を暗黙前提としている（Phase 25 で明示条件に格上げする）。
    - 最低限 `me.cols == b.rows` を事前条件とし、満たさない場合は Fail‑Fast とする方向。
  - 実装メモ:
    - 三重ループ (`i`,`k`,`j`) で `out[i,j] += me[i,k] * b[k,j]` を計算。
    - `out` 行列は `MatI64.new(me.rows, b.cols)` で確保。
  - Phase 25 以降:
    - Box メソッドとしての `mul_naive` は numeric ABI の薄ラッパに縮退し、ループ本体は System Hakorune subset 上の別関数（`ny_numeric_mat_i64_mul_naive`）に切り出す。