190 lines
7.8 KiB
Markdown
190 lines
7.8 KiB
Markdown
# Phase 20.7: Collections in Hakorune
|
||
|
||
**期間**: 8週間 (2026-05-25 → 2026-07-19)
|
||
**前提Phase**: Phase 20.6 (VM Core Complete + Dispatch Unification)
|
||
**完了Phase**: Phase D (Collections - MapBox/ArrayBox in Pure Hakorune)
|
||
|
||
---
|
||
|
||
## 🎯 概要
|
||
|
||
Phase 20.7では、Hakoruneコアのコレクションライブラリ（MapBox/ArrayBox）を**C‑ABI 経由の単一起点**に切り替え、Rust VM と Hakorune VM の両実行線で同一実装を叩けるようにします。WASM/embedded プロファイルでは「内蔵プラグイン（静的リンク/LTO）」、既定（サーバ/CLI）では動的プラグインで運用します。必要に応じて Pure Hakorune 実装（研究/自己ホスト）を併用し、パリティと移植性を両立します。
|
||
|
||
**重要原則**:
|
||
- **C‑ABI SSOT**: Basic 箱は C‑ABI で単一実装（Rust/Hako で共有）。Two‑Layer Export（Stable ABI + Inlinable API）
|
||
- **決定的動作**: キー順序が予測可能（Symbol < Int < String）
|
||
- **Fail‑Fast**: 不明メソッド/権限違反は即エラー（フォールバック禁止）
|
||
- **ValueBox/DataBox 境界**: ValueBox は境界のみに限定、箱内部は DataBox のみ
|
||
|
||
---
|
||
|
||
## 🔄 現状（進捗スナップショット）
|
||
|
||
- Router: ABI 基本フック（NYASH_ABI_BASIC_ON=1）を導入済み。
|
||
- Week‑1（quick）: String.length/len/size（0引数）をフラグ配下で導通（挙動は従来同値）。
|
||
- Week‑2（quick）: Array.length/len/size（0引数）、Array.push/1 をフラグ配下で導通（quick スモーク PASS）。
|
||
- Map（pilot）: size/get/set を導通。quick のスモークで PASS。
|
||
- Builder/VM: `NYASH_NORMALIZE_CORE_EXTERN`（既定ON）で String/Array/Map の Method/ModuleFunction を `Extern("nyrt.*")` に強制統一。gate=0 で従来経路へロールバック可。
|
||
- Verifier: `NYASH_VERIFY_CORE_EXTERN=1` で strict チェック（Method/ModuleFunction 残存時に Fail‑Fast）。smoke 追加済み。
|
||
- 弱凍結: Rust 線は Router/配線/診断/障害修正のみ許可。意味論の追加は selfhost 側で継続。
|
||
- ロールバック: `NYASH_ABI_BASIC_ON=0` で即時戻す。
|
||
- 観測メモ: quick の String パイロットは一部環境で plugin 優先（StringBox が plugin provider 経路）により経路が揺れる。ABI hook を Method/Module/Extern の3入口に配置し、スモーク側で macro/using/TOML-env をOFFにして安定化する。
|
||
- Boot/Lock: LockOnly（`--frozen`）経路は導入済み。ABI 導入後も lock.graph.order に従ってロードし決定性を維持する。
|
||
- 文字列長の意味論: bytes 基準（`length_bytes`）で統一。AOT 側の実装は VM と同値に揃える（パリティ項目）。
|
||
|
||
### 進捗（締め処理）
|
||
- quick: ABI Basic 既定ON で安定（診断既定OFF）。
|
||
- integration: first wave（String/Array）既定ON。代表ケース（Extern len / ModuleFunction canonical / Box equals）で緑を確認。
|
||
- perf: 目安≥70% の観測を 48h 窓で継続（問題あれば `NYASH_ABI_BASIC_ON=0` に即時ロールバック）。
|
||
|
||
---
|
||
|
||
## 📊 実装範囲
|
||
|
||
### Week 1-4: MapBox実装
|
||
|
||
MapBoxは、キー・バリューペアを格納するハッシュマップです。
|
||
|
||
**実装メソッド**:
|
||
- `set(key, value)`: キー・バリューペアを設定
|
||
- `get(key)`: キーから値を取得
|
||
- `has(key)`: キーの存在確認
|
||
- `remove(key)`: キーを削除
|
||
- `size()`: 要素数を返す
|
||
- `keys()`: すべてのキーを返す（決定的順序）
|
||
- `values()`: すべての値を返す（決定的順序）
|
||
|
||
**技術要件**:
|
||
1. **ハッシュマップ実装**: チェイン法またはオープンアドレス法
|
||
2. **決定的ハッシュ/等価性**: 同じキーは常に同じバケットに配置
|
||
3. **キー正規化**: Symbol/Int/String型を統一的に扱う
|
||
4. **Provenance Tracking**: plugin_id, versionを記録
|
||
|
||
### Week 5-8: ArrayBox実装
|
||
|
||
ArrayBoxは、動的配列（リスト）です。
|
||
|
||
**実装メソッド**:
|
||
- `push(value)`: 末尾に要素を追加
|
||
- `pop()`: 末尾から要素を削除して返す
|
||
- `get(index)`: インデックスで要素を取得
|
||
- `set(index, value)`: インデックスに値を設定
|
||
- `size()`: 要素数を返す
|
||
- `slice(start, end)`: 部分配列を返す
|
||
- `concat(other)`: 別の配列と結合
|
||
|
||
**技術要件**:
|
||
1. **動的配列実装**: 容量拡張戦略（2倍拡張など）
|
||
2. **境界チェック**: インデックス範囲外は即座にエラー
|
||
3. **参照カウント**: GC準備（Phase 20.8）のための追跡
|
||
4. **Fail-Fast**: 不正な操作は即座にpanicではなくエラー返却
|
||
|
||
---
|
||
|
||
## 🔑 キー比較順序（決定的動作の核心）
|
||
|
||
MapBoxのキー順序は以下のルールで決定されます:
|
||
|
||
```
|
||
Symbol < Int < String
|
||
```
|
||
|
||
**例**:
|
||
```hakorune
|
||
local map = new MapBox()
|
||
map.set(:foo, 1) // Symbol
|
||
map.set(42, 2) // Int
|
||
map.set("bar", 3) // String
|
||
|
||
// keys() の返り値は必ず [:foo, 42, "bar"] の順序
|
||
local keys = map.keys()
|
||
// Output: [:foo, 42, "bar"]
|
||
```
|
||
|
||
**実装詳細**:
|
||
- 同じ型内では、自然順序（Symbol: 辞書順、Int: 数値順、String: 辞書順）
|
||
- 異なる型間では、上記の型優先順位に従う
|
||
- ハッシュ衝突時も、この順序で解決
|
||
|
||
---
|
||
|
||
## 🏗️ ValueBox/DataBox境界
|
||
|
||
**設計原則** (Phase 20.5で確立):
|
||
- **ValueBox**: 一時的な値（パイプライン境界のみ）
|
||
- **DataBox**: 永続的な値（長期保存）
|
||
- **Fail-Fast**: Entry/ExitポイントでValueBoxをUnpack
|
||
|
||
**Collections適用**:
|
||
```hakorune
|
||
// ❌ BAD: ValueBoxをMapに直接格納
|
||
map.set(key, ValueBox.wrap(data))
|
||
|
||
// ✅ GOOD: DataBoxに変換してから格納
|
||
local databox = ValueBox.unpack(data)
|
||
map.set(key, databox)
|
||
```
|
||
|
||
**実装要件**:
|
||
1. MapBox/ArrayBoxは**DataBoxのみ**を受け入れる
|
||
2. ValueBoxが渡された場合、即座にエラー
|
||
3. Pipeline境界でUnpackを強制
|
||
|
||
---
|
||
|
||
## 🧪 成功基準
|
||
|
||
### 必須条件 (✅ すべて達成必須)
|
||
|
||
1. **MapBox/ArrayBox完全実装**:
|
||
- すべてのメソッドがPure Hakoruneで動作
|
||
- Rustコードへの依存なし（HostBridge以外）
|
||
|
||
2. **Golden Tests通過**:
|
||
- Rust-Collections vs Hako-Collections パリティ
|
||
- 100+テストケースで完全一致
|
||
- 決定的動作の検証（同じ入力→同じ出力）
|
||
|
||
3. **決定的動作**:
|
||
- キー順序が予測可能
|
||
- イテレーション順序が安定
|
||
- Provenance Tracking動作
|
||
|
||
4. **パフォーマンス**:
|
||
- Hako-Collections ≥ 70% of Rust-Collections速度
|
||
- 基本操作（set/get/push/pop）はO(1)平均時間
|
||
- 大規模データ（10,000要素）でも実用的速度
|
||
|
||
### 除外項目 (⚠️ Phase 20.7では**扱わない**)
|
||
|
||
- **GC (Garbage Collection)**: Phase 20.8で実装
|
||
- **最適化**: 基本実装のみ（プロファイリングは後回し）
|
||
- **並行処理**: シングルスレッドのみ
|
||
- **永続化**: メモリ内のみ（ディスク保存なし）
|
||
|
||
---
|
||
|
||
## 📚 関連ドキュメント
|
||
|
||
- **Phase 20.6**: [VM Core Complete + Dispatch Unification](../phase-20.6/)
|
||
- **Phase 20.8**: [GC v0 + Rust Deprecation](../phase-20.8/)
|
||
- **Pure Hakorune Roadmap**: [PURE_HAKORUNE_ROADMAP.md](../phase-20.5/PURE_HAKORUNE_ROADMAP.md)
|
||
- **Box-First原則**: [CLAUDE.md](../../../../CLAUDE.md#🧱-先頭原則-箱理論box-first)
|
||
- **Golden Testing Strategy**: [PURE_HAKORUNE_ROADMAP.md#🧪-golden-testing-strategy](../phase-20.5/PURE_HAKORUNE_ROADMAP.md#-golden-testing-strategy)
|
||
|
||
---
|
||
|
||
## 📝 ドキュメント構造
|
||
|
||
- **[README.md](README.md)** (このファイル): Phase 20.7概要（日本語）
|
||
- **[PLAN.md](PLAN.md)**: 詳細実装計画（英語）
|
||
- **[CHECKLIST.md](CHECKLIST.md)**: 週次チェックリスト
|
||
- **[INDEX.md](INDEX.md)**: ドキュメント索引
|
||
|
||
---
|
||
|
||
**Status**: PLANNED
|
||
**Dependencies**: Phase 20.6 (VM Core + Dispatch)
|
||
**Delivers**: Phase D (Collections in Pure Hakorune)
|
||
**Timeline**: 8 weeks (2026-05-25 → 2026-07-19)
|