hakorune/docs/development/roadmap/phases/phase-12/README.md

Phase 12: Nyashコード共有エコシステム - Everything is Box の実現

Status note (Phase‑15): このフォルダは「統一TypeBox ABI」の長期設計（青写真）です。現在の main 実装は最小の v2 ABI に収束しており、実用重視で段階導入中です。現行仕様は docs/reference/plugin-abi/nyash_abi_v2.md を参照してください。Phase‑12 の要素（create/destroy、型メタ、NyValue、vtable/RC/GC）は前方互換を維持しつつ段階追加予定です。

🌟 最新ブレイクスルー (2025-09-02) - 統一TypeBox ABI誕生！

🚨 究極の発見：ユーザー定義Boxもプラグインに！

AI先生たちの深い技術的検討により、革命的なアイデアが実現可能と判明！

// ユーザーBoxもプラグインとして動的登録
NyashTypeBox* register_user_box(const char* name, 
                                NyashBoxMethods* methods);

これにより実現すること：

• 🎯 すべての箱をC ABI上で一つで管理
• 🔄 ユーザー定義Box ↔ プラグインBox 完全相互運用
• 🚀 Nyash側から見ると完全に統一された世界観

詳細：ユーザー定義Box統合 🆕

🔥 究極の統合：すべてのプラグインがTypeBoxになる！

「Everything is Box」哲学の完成形：C ABIもNyash ABIも統一TypeBoxに統合！

// 統一TypeBox - すべてのプラグインがこの形式に！
typedef struct {
    uint32_t abi_tag;        // 'TYBX' - すべて同じ
    uint16_t version;        // APIバージョン
    const char* name;        // "StringBox", "FileBox", etc.
    
    // 基本操作（旧C ABI互換）
    void* (*create)(void* args);
    void (*destroy)(void* self);
    
    // 高速メソッドディスパッチ（新機能）
    uint32_t (*resolve)(const char* name);    // 名前→ID変換
    NyResult (*invoke_id)(void* self,         // ID呼び出し（JIT最適化）
                         uint32_t method_id, 
                         NyValue* args, int argc);
    
    // メタ情報
    uint64_t capabilities;   // THREAD_SAFE | ASYNC_SAFE等
} NyashTypeBox;

3大AI専門家の統合案への評価:

• Gemini: 「技術的妥当性は非常に高い。単なるアイデアではなく、堅牢なアーキテクチャ」
• Codex: 「TypeBox統合は実現可能で有益。JIT最適化で33倍高速化も可能」
• ChatGPT5: 「『Everything is Box』哲学に最も適した設計」（設計に反映済み）

🎯 なぜ統合するのか？

以前は2つのシステムが混在していました：

• C ABI：シンプルだが拡張性に限界
• TypeBox：プラグイン間連携は可能だが別システム

統合により実現したこと：

1. 概念の統一：すべてがTypeBoxという1つの形式
2. プラグイン間連携が標準装備：どのプラグインも他のBoxを作れる
3. JIT/AOT最適化：メソッドID化で最大33倍高速化
4. 段階的移行：既存資産を保護しながら進化

🎯 重要な変更 (2025-09-01)

Phase 12の議論とビルトインBox廃止により、プラグインシステムが進化：

新しい3層プラグインシステムが確立されました！

# Nyashスクリプトプラグイン（ユーザー定義Box）
box DataProcessor {
    init {
        me.file = new FileBox()    # C ABIプラグイン使用
        me.math = new MathBox()    # C ABIプラグイン使用
        me.cache = new MapBox()    # これもC ABIプラグイン（ビルトイン廃止）
    }
    
    process(data) {
        local result = me.math.sin(data)
        me.file.write("log.txt", result.toString())
        return result
    }
}

# 使用例
local processor = new DataProcessor()
processor.process(3.14)  # すべてプラグインで動作！

📝 なぜ誤解が生まれたのか

「プラグイン」という言葉から、特別な仕組みが必要だと考えてしまいましたが、Nyashの「Everything is Box」哲学により、ユーザー定義Boxこそが最高のプラグインシステムでした。

詳細な分析：なぜ天才AIたちは間違えたのか

🚀 Phase 12の真の価値：コード共有エコシステム（同一実行の確立）

最終ゴールは「Nyashコード → VM → JIT の同一実行」。同じプログラムがVMとJITで同じ意味・結果・副作用になるよう、ディスパッチ/ABI/Barrier/Safepointの規約を共有し、差分をなくします。テストハーネスで同値性を比較できるように整備します。

本当に必要なもの

1. export/import構文

   # math_utils.ny
   export box MathUtils {
       factorial(n) { ... }
       fibonacci(n) { ... }
   }
   
   # main.ny
   import { MathUtils } from "math_utils.ny"
   local utils = new MathUtils()
   

2. パッケージマネージャー

   nyash install awesome-math-utils
   nyash publish my-cool-box
   

3. ドキュメント生成

   # @doc 素晴らしい数学ユーティリティ
   # @param n 計算したい数値
   # @return 階乗の結果
   export box MathUtils { ... }
   

📊 新しい統一プラグインシステム

Nyashエコシステム（統一TypeBox ABI採用後）：
├── Nyashスクリプトプラグイン ← .hakoファイル（純粋なNyashコード）
└── 統一TypeBoxプラグイン    ← .so/.dll（ネイティブ実装）
    ├── 基本機能（旧C ABI互換）
    ├── 高速ディスパッチ（JIT最適化）
    └── プラグイン間連携（標準装備）

🔄 移行パス

• 既存C ABIプラグイン → そのまま動作（互換レイヤー経由）
• 新規プラグイン → 統一TypeBox形式で作成
• 段階的移行 → ツールで自動変換支援

📚 プラグインシステムドキュメント

• 統一TypeBox ABI 🆕 - すべてのプラグインの統一仕様
• 移行ガイド 🆕 - 既存プラグインの移行方法
• Nyashスクリプトプラグイン - 純粋なNyashコードのプラグイン

📦 レガシードキュメント（参考用）

• 旧C ABI仕様
• 旧Nyash ABI仕様

💡 TypeBox：シンプルなプラグイン間連携

MapBox.keys()がArrayBoxを返したい場合：

// TypeBox構造体（型情報をBoxとして扱う）
typedef struct {
    uint32_t abi_tag;       // 'TYBX'
    const char* name;       // "ArrayBox"
    void* (*create)(void);  // Box生成関数
} NyrtTypeBox;

// MapBox.keys()実装
void* map_keys(void* self, void* array_type_box) {
    NyrtTypeBox* array_type = (NyrtTypeBox*)array_type_box;
    void* array = array_type->create();  // ArrayBox生成
    // ... キーを追加
    return array;
}

詳細: C ABI TypeBox設計仕様書

プラグイン選択の指針

• C ABIで済むなら、C ABIを使う（シンプルイズベスト）
• Nyash ABIは以下の場合のみ：
  • 他言語（Python/Go等）からの呼び出し
  • 複雑な型の相互運用が必要
  • 将来の拡張性を重視する場合

📝 MIR命令統合（Phase 12での変更）

• PluginInvoke → BoxCall 統合
  • ビルトインBox廃止によりフォールバックがなくなる
  • BoxCallとPluginInvokeの区別が不要に
  • VM層でC ABI/Nyash ABI/Scriptを自動判定
  • Core-15 → Core-14 へ（命令数削減）

🛣️ 実装ロードマップ（統一TypeBox ABI版）

Phase 12.0: 統一TypeBox ABI実装（1週間）🆕

• nyash_typebox.h完全ヘッダー定義
• メソッドID解決・キャッシング機構
• NyValue統一値表現の実装
• 互換レイヤー（既存C ABI→TypeBox）
• 📄 統一TypeBox ABI仕様

Phase 12.0.5: 移行ツール開発（2週間）🔧

• プラグイン自動変換ツール
• 検証・テストツール
• パフォーマンスベンチマーク
• サンプルプラグイン集
• 📄 移行ガイド

---

現状サマリ（2025-09-02）

• C ABI（TLV: 1/2/3/5/6/7/8）でのプラグイン呼び出しはVMで安定運用中。returns_result も nyash.toml で制御可能。
• JIT は VM と同じBox境界で動作（フォールバック含む）。Cranelift AOT のオブジェクト出力は未配線（スケルトン）。
• MapBox を拡張（stringキー、remove/clear/getOr/keysStr/valuesStr/toJson）。keys()/values() はランタイムシムで暫定提供。
• Phase 12 設計（TypeBox + Unified Dispatch）は破壊的変更不要で段階導入可能と判断。

詳細タスクは TASKS.md を参照。

Phase 12.1: export/import構文（2週間）

• exportキーワードのパーサー実装
• importステートメントの実装
• モジュール解決システム
• 📄 詳細仕様書

Phase 12.2: パッケージ管理（3週間）

• nyash.tomlのdependencies対応
• 中央リポジトリ設計
• CLIツール（install/publish）
• 📄 パッケージマネージャー設計書

Phase 12.3: 開発者体験向上（継続的）

• ドキュメント生成ツール
• VSCode拡張（補完・定義ジャンプ）
• サンプルパッケージ作成

📚 関連ドキュメント

🎯 プラグインシステムガイド（メインドキュメント）

• 統一TypeBox ABI ← 🌟🆕 すべてのプラグインの新仕様！
• ユーザー定義Box統合 ← 🔥🆕 革命的な完全統合！
• AI先生たちの技術的検討 ← 🤖🆕 深い分析と提言（Codex詳細版追加）
• 技術的決定事項 ← 📋🆕 確定した技術仕様まとめ
• 実装ロードマップ ← 📅🆕 詳細な実装計画
• 移行ガイド ← 🆕 既存プラグインを新形式へ
• Nyashスクリプトプラグイン ← 純粋なNyashコードのプラグイン

📐 設計ドキュメント（design/）

• 統合ABI設計仕様書 ← 統合の詳細設計
• C ABI TypeBox設計仕様書 ← TypeBoxの原点
• Nyash ABI C実装設計書 ← セルフホスティング構想
• なぜ天才AIたちは間違えたのか ← 設計プロセスの教訓

📋 仕様書（specs/）

• export/import仕様 ← モジュールシステムの詳細仕様
• パッケージマネージャー設計 ← パッケージ管理の設計

💬 議論の過程（discussions/）

• ABI戦略議論: discussions/abi-strategy-discussion/
• Nyash ABI詳細: discussions/nyash-abi-discussion/

📦 アーカイブ

• 初期提案: archive/ ← 過去の提案や古いドキュメント

---

AIたちがなぜ複雑な解決策を提案したのか、その議論の過程は archive/ ディレクトリに保存されています。良い教訓として残しておきます。