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

Phase 12: 統一TypeBox ABI - 技術的決定事項

📅 最終更新: 2025-09-02

このドキュメントは、3人のAI専門家（Gemini、Codex、ChatGPT5）の深い技術検討を経て決定された、統一TypeBox ABIの技術的決定事項をまとめたものです。

🎯 核心的決定事項

1. 統一TypeBox構造体の確定

typedef struct NyashTypeBox {
    // === ヘッダー情報（不変のバイナリ契約）===
    uint32_t abi_tag;               // 'TYBX' (0x54594258) - 必須
    uint16_t version;               // APIバージョン（現在: 1）
    uint16_t struct_size;           // 構造体サイズ（前方互換性）
    const char* name;               // Box型名："StringBox"
    
    // === 基本操作（COM互換）===
    void* (*create)(void* args);    // インスタンス生成
    void (*destroy)(void* self);    // インスタンス破棄
    void (*retain)(void* self);     // 参照カウント増加（新規）
    void (*release)(void* self);    // 参照カウント減少（新規）
    
    // === 高速メソッドディスパッチ ===
    uint32_t (*resolve)(const char* name);    // メソッド名→ID変換
    NyResult (*invoke_id)(void* self,         // ID指定の高速呼び出し
                         uint32_t method_id, 
                         NyValue* args, 
                         int argc);
    
    // === メタ情報 ===
    const char* (*get_type_info)(void);       // JSON形式の型情報
    uint64_t capabilities;                    // 機能フラグ
    
    // === 将来拡張用 ===
    void* reserved[4];                        // NULL初期化必須
} NyashTypeBox;

2. Type ID管理戦略

64-bit構造: [8b domain | 8b vendor | 16b category | 32b serial]

• 0x00xxxxxx: Core/Built-in types
• 0x40xxxxxx: First-party plugins
• 0x80xxxxxx: User-defined boxes (動的登録)
• 0xC0xxxxxx: Experimental/Debug

3. メモリ管理統一方針

参照カウント（必須）

• アトミック操作（_Atomic uint64_t）
• retain/releaseはCOM互換の固定位置
• 循環参照対策：Trial Deletion + Weak Boundary

GC協調（オプション）

• traceメソッドの提供（プラグイン必須）
• 世代別GCとの協調動作

4. パフォーマンス目標値

• メソッド呼び出し: 旧50-150ns → 新1-3ns（最大50倍高速化）
• インラインキャッシング: Monomorphic IC標準装備
• JIT統合: ウォームアップ後の直接インライン化

5. セキュリティレベル定義

1. trusted: 同一プロセス内、直接関数呼び出し
2. sandboxed: Wasm/別プロセスで実行
3. restricted: 限定的な権限のみ

🔧 実装上の決定事項

メソッドディスパッチ戦略

1. 新規プラグイン: invoke_id優先（高速パス）
2. 既存プラグイン: method経由でフォールバック
3. 移行期間: 両方サポート、段階的に新方式へ

NyValue統一表現

typedef struct __attribute__((aligned(16))) {
    uint64_t type_tag;   // 型識別子
    union {
        int64_t  i64;    // 整数
        double   f64;    // 浮動小数点
        void*    ptr;    // ポインタ（Box/String等）
        uint64_t bits;   // ビットパターン（NaN-box/SMI）
    } payload;
} NyValue;

API互換性保証

• NyBoxHeader.header_sizeによる前方互換
• vtableの先頭3メソッドは不変（COM準拠）
• 新機能はcapabilitiesフラグで判定

📊 移行戦略

Phase 1: 基礎実装（1週間）

• NyashTypeBox構造体定義
• 基本的なregister_user_box実装
• 互換レイヤー（既存C ABI→TypeBox）

Phase 2: 最適化（2週間）

• メソッドID解決機構
• インラインキャッシング基礎
• JIT統合準備

Phase 3: 完全移行（1ヶ月）

• すべてのビルトインBoxをTypeBox化
• パフォーマンスベンチマーク
• 移行ツール完成

✅ 合意済み事項

1. Everything is Box哲学の完全実現

   • すべてのBox（ビルトイン、プラグイン、ユーザー定義）が統一ABI
   • NyValue経由ですべて扱える

2. 段階的移行の保証

   • 既存プラグインは動作継続
   • 新規開発は新ABIを推奨

3. パフォーマンス優先

   • メソッドIDによる高速化は必須
   • JIT/AOTとの密接な統合

🚫 却下された提案

1. 完全な動的型システム: 静的解析を困難にするため
2. プロセス間通信ベース: オーバーヘッドが大きすぎる
3. Rustネイティブ統合: C ABIの安定性を優先

📚 参考資料

• AI先生たちの技術的検討
• 統一TypeBox ABI仕様
• ユーザー定義Box統合
• Nyash ABI Minimal Coreと進化戦略