hakorune/docs/development/roadmap/phases/phase-12/design/UNIFIED-ABI-DESIGN.md

統合ABI設計仕様書 v1.0 (2025-09-01)

🎯 概要

革命的発見: TypeBoxブリッジにより、C ABI + Nyash ABI統合プラグインシステムが実現可能！

Codex専門家分析により、既存のC ABIプラグインを維持しながら、型安全で高性能なNyash ABIプラグインを同一システムで運用する統合設計が確立されました。

設計哲学

1. 既存を壊さない: C ABIプラグインはそのまま動作
2. 段階的進化: プラグインごとに個別でABI選択可能
3. パフォーマンス: Nyash ABI優先、必要時のみC ABIブリッジ
4. Everything is Box: TypeBox自体もBox哲学に従う

📐 核心設計：統一TypeBoxディスクリプタ

UnifiedTypeBox構造体（ChatGPT5改善版）

// crates/nyrt/include/nyrt_typebox.h
#pragma pack(push, 8)  // ABIアライメント固定

typedef struct {
    // ヘッダー（バージョン管理・互換性）
    uint32_t abi_tag;           // 'TYBX' (0x54594258)
    uint16_t ver_major;         // 1 
    uint16_t ver_minor;         // 0
    uint32_t size;              // sizeof(nyrt_typebox) - 拡張互換性
    nyrt_abi_kind_t abi_kind;   // C/Nyash/統合
    uint32_t callconv;          // 呼び出し規約（Win/Linux差分）

    // 型識別（衝突安全性強化）
    const char* name;           // "nyash.core.Array" - FQN
    uint8_t stable_id[32];      // SHA-256ハッシュ（衝突耐性）
    uint64_t fast_key;          // 高速ルックアップ用64bitキー
    
    // スレッド安全性・最適化ヒント
    uint32_t flags;             // THREAD_SAFE/IMMUTABLE/REENTRANT/MAY_BLOCK
    uint32_t align;             // アライメントヒント

    // ABI別vtable（nullable）
    const nyrt_c_vtable* c;     // C ABI vtable
    const nyrt_ny_vtable* ny;   // Nyash ABI vtable
    
    // メタデータ
    nyrt_type_meta meta;        // JSON/CBOR形式
    const void* user_data;      // プラグイン定義データ
} nyrt_typebox;

#pragma pack(pop)

// ABIサイズ検証（コンパイル時）
_Static_assert(sizeof(nyrt_typebox) <= 128, "TypeBox size too large");

ABI種別とvtable（ChatGPT5強化版）

// ABI種別定義
typedef enum {
    NYRT_ABI_NONE = 0,
    NYRT_ABI_C = 1,         // C ABIのみ
    NYRT_ABI_NYASH = 2,     // Nyash ABIのみ  
    NYRT_ABI_UNIFIED = 3    // 両方サポート
} nyrt_abi_kind_t;

// 呼び出し規約（プラットフォーム差分対応）
typedef enum {
    NYRT_CALLCONV_SYSTEMV = 1,    // Linux/Unix標準
    NYRT_CALLCONV_WIN64 = 2,      // Windows x64
    NYRT_CALLCONV_FASTCALL = 3    // Windows最適化
} nyrt_callconv_t;

// エラーコード（厳密化）
typedef int32_t nyrt_err;
#define NYRT_OK         0
#define NYRT_E_ARG      1   // 引数エラー
#define NYRT_E_TYPE     2   // 型エラー
#define NYRT_E_STATE    3   // 状態エラー
#define NYRT_E_OOM      4   // メモリ不足
#define NYRT_E_ABORT    5   // 致命的エラー

// 所有権契約（明文化）
typedef enum {
    NYRT_OWN_BORROW = 0,    // 借用（呼び出し期間のみ有効）
    NYRT_OWN_TRANSFER = 1,  // 所有権移譲（受け取り側がrelease）
    NYRT_OWN_CLONE = 2      // クローン（コピー、独立管理）
} nyrt_ownership;

// スレッド安全性フラグ
#define NYRT_FLAG_THREAD_SAFE   0x0001  // スレッドセーフ
#define NYRT_FLAG_IMMUTABLE     0x0002  // 不変オブジェクト
#define NYRT_FLAG_REENTRANT     0x0004  // 再帰呼び出し可能
#define NYRT_FLAG_MAY_BLOCK     0x0008  // 長時間処理（GCセーフポイント必要）

// C ABI vtable: nothrow保証・所有権明確化
typedef struct {
    // ライフサイクル（すべてnothrow）
    void* (*create)(void* env);                  // 例外禁止
    void  (*retain)(void* instance);             // 参照カウント増加
    void  (*release)(void* instance);            // 参照カウント減少
    
    // NyashValue ↔ void* 変換（所有権明示）
    nyrt_err (*to_nyash)(const void* instance, nyrt_nyash_value* out, nyrt_ownership* own);
    nyrt_err (*from_nyash)(nyrt_nyash_value val, void** out, nyrt_ownership* own);
    
    // メソッド呼び出し（nothrow、GCセーフポイント配慮）
    nyrt_err (*invoke_by_id)(void* instance, nyrt_method_id method, 
                            const void* const* argv, size_t argc,
                            void** ret_out, nyrt_ownership* ret_own);
    
    // フォールバック（ID不明時）
    nyrt_err (*invoke_by_name)(void* instance, const char* method_name,
                              const void* const* argv, size_t argc, 
                              void** ret_out, nyrt_ownership* ret_own);
} nyrt_c_vtable;

// Nyash ABI vtable: ネイティブNyashValue
typedef struct {
    // ライフサイクル
    nyrt_nyash_value (*create)(void* ctx);
    void (*retain)(nyrt_nyash_value v);
    void (*release)(nyrt_nyash_value v);
    
    // 直接NyashValueでメソッド呼び出し
    nyrt_err (*invoke_by_id)(nyrt_nyash_value* this_val, nyrt_method_id method,
                            const nyrt_nyash_value* args, size_t argc,
                            nyrt_nyash_value* ret_out);
    
    nyrt_err (*invoke_by_name)(nyrt_nyash_value* this_val, const char* method_name,
                              const nyrt_nyash_value* args, size_t argc,
                              nyrt_nyash_value* ret_out);
} nyrt_ny_vtable;

🛡️ ChatGPT5安全性強化（10の重要改善）

1. ID衝突安全性

• SHA-256ハッシュ: 64bitから256bitへ強化（衝突耐性）
• 高速キー併用: 64bit fast_keyでホットパス最適化
• 重複登録拒否: 同一type_idの重複をランタイムで検出・拒否

2. 所有権契約の明文化

// 所有権と解放責務の明確な定義
NYRT_OWN_BORROW = 0,    // 呼び出し期間のみ有効、releaseしない
NYRT_OWN_TRANSFER = 1,  // 受け取り側がrelease責務を負う
NYRT_OWN_CLONE = 2      // 独立コピー、各々がrelease

3. 例外/パニック越境禁止

• C ABIは完全nothrow: すべての関数で例外禁止
• Nyash側例外捕捉: パニック → nyrt_err変換
• 境界ガード: try-catchでC/Nyash境界を保護

4. GC/セーフポイント規則

// MAY_BLOCKフラグ付きC ABI呼び出し前後
if type_info.flags & NYRT_FLAG_MAY_BLOCK != 0 {
    vm.gc_safepoint_enter();
    let result = c_vtable.invoke_by_id(...);
    vm.gc_safepoint_exit();
}

5. プラグイン初期化と互換性交渉

// プラグインエントリーポイント
NYRT_EXPORT nyrt_err nyash_plugin_init(const nyrt_host*, const nyrt_runtime_info*);
NYRT_EXPORT const nyrt_typebox** nyash_typeboxes(size_t* count);

// バージョン確認必須
typedef struct {
    uint16_t size;          // 構造体サイズ
    uint16_t ver_major;     // メジャーバージョン
    uint16_t ver_minor;     // マイナーバージョン
    uint16_t reserved;
} nyrt_runtime_info;

6. NyashValueインライン表現

// インライン値エンコーディング規則
typedef struct {
    uint64_t type_id;       // 型識別子
    uint64_t box_handle;    // ポインタ or インライン値
    uint64_t metadata;      // INLINEフラグ + 追加情報
} nyrt_nyash_value;

#define NYASH_META_INLINE     0x0001  // box_handleがインライン値
#define NYASH_META_ASYNC      0x0002  // 非同期結果
#define NYASH_META_ERROR      0x0010  // エラー値

🔄 統一ディスパッチ戦略

VM層での透明なABI選択

// src/runtime/unified_dispatch.rs
pub fn call_with_typebox(
    method: MethodId,
    this_ty: &TypeBoxInfo,
    this_val: NyashValue,
    args: &[NyashValue],
) -> Result<NyashValue, NyError> {
    // Nyash ABI優先（ゼロコストパス）
    if let Some(ny) = &this_ty.ny {
        return ny.invoke_by_id(this_val, method, args);
    }
    
    // C ABIブリッジ（必要時のみ）
    let c = this_ty.c.as_ref().ok_or(NyError::MissingVTable)?;
    let (this_ptr, this_own) = c.from_nyash(this_val)?;
    let (argv, arena) = marshal_args_to_c(args, c)?;
    let (ret_ptr, ret_own) = c.invoke_by_id(this_ptr, method, &argv)?;
    let ret = c.to_nyash(ret_ptr, ret_own)?;
    
    Ok(ret)
}

7. ホストコールバック（プラグイン支援）

// プラグインが使える安全なホスト機能
typedef struct {
    uint16_t size;                           // 構造体サイズ
    void* (*host_alloc)(size_t);            // メモリ確保
    void  (*host_free)(void*);              // メモリ解放
    void  (*log)(int level, const char* msg); // ログ出力
    nyrt_err (*gc_safepoint)(void);         // GCセーフポイント
} nyrt_host;

8. セキュリティ/不正プラグイン対策

• TypeBox検証: abi_tag、サイズ、バージョンの完全性確認
• 重複登録拒否: 同一名前・type_idの重複を検出
• 境界チェック: user_dataのサイズ・内容検証
• Capability予約: 将来のファイル/ネット権限制御用フラグ

9. プラグインアンロード安全性

// プラグインアンロード前の安全確認
fn can_unload_plugin(plugin_id: &str) -> bool {
    let live_instances = registry.count_live_instances(plugin_id);
    live_instances == 0  // 生存インスタンスがない場合のみアンロード可能
}

10. テスト戦略（ChatGPT5推奨）

• ABIクロスパリティ: 同一Box実装（C/Nyash/Unified）で結果一致
• 所有権ファズ: Borrow/Transfer/Clone組み合わせでリーク検出
• 呼び出し規約クロス: Win(Fastcall)↔Linux(SystemV)結果一致
• 性能目標: Nyash ABI = 1.0x、C ABIブリッジ ≤ 1.5x

📝 nyash.toml v3.0設定

# 統一プラグイン設定
[plugins.map_simple]
path = "plugins/map.so"
abi = "c"                    # C ABIのみ
types = ["nyash.core.Map"]

[plugins.map_advanced]
path = "plugins/advanced_map.so"
abi = "nyash"                # Nyash ABIのみ
types = ["nyash.core.Map"]

[plugins.map_hybrid]
path = "plugins/hybrid_map.so"
abi = "unified"              # 両方サポート（Nyash優先）
types = ["nyash.core.Map", "nyash.core.Array"]
symbols.boxes = "nyash_typeboxes"
symbols.init = "nyash_plugin_init"

⚡ パフォーマンス最適化

1. IDベースディスパッチ

• 型ID: 64bit安定ハッシュ（FQN + 型引数）
• メソッドID: 64bitハッシュ（シグネチャ）
• ホットパスで文字列ハッシュ回避

2. インライン値サポート

// NyashValue（Nyash ABI）
typedef struct {
    uint64_t type_id;       // 型識別子
    uint64_t box_handle;    // Arc<Box>ポインタ or インライン値
    uint64_t metadata;      // INLINEフラグ等
} NyashValue;

#define NYASH_META_INLINE 0x0001   // box_handleがインライン値

3. ゼロコピーブリッジ

• 所有権フラグ（BORROW/PLUGIN/HOST）で適切な参照管理
• 不要なコピー回避
• retain/releaseの最適化

🏗️ 実装ロードマップ

Phase 1: TypeBox統合基盤（1週間）

• nyrt_typebox.h完全定義
• Rust FFIミラー（crates/nyrt/src/typebox.rs）
• UnifiedPluginRegistry実装

Phase 2: 実証実装（2週間）

• MapBoxの両ABI実装
• 統一ディスパッチテスト
• パフォーマンスベンチマーク

Phase 3: プロダクション化（3週間）

• nyash.toml v3.0パーサー
• プラグイン移行ガイドライン
• デバッグツール整備

🎯 成功指標

1. 機能性: MapBox.keys()がArrayBoxを返す（両ABI対応）
2. パフォーマンス: Nyash ABIで直接呼び出し、C ABIで1.5倍以内
3. 互換性: 既存C ABIプラグインがそのまま動作
4. 拡張性: 新しいABI追加が容易

🌟 なぜ統合が可能になったのか

TypeBoxの革命的価値

1. 型情報の統一表現: Everything is Box哲学の完全実現
2. ABI間ブリッジ: 異なるABI間の透明な変換
3. バージョン管理: 前方互換性のある拡張メカニズム
4. 段階的移行: 破壊的変更なしの進化

3大AI専門家の一致した結論

Codex専門家分析:

「TypeBoxを汎用ブリッジとして使用する統合設計は、 安定性・パフォーマンス・拡張性のすべてを満たす理想的なアーキテクチャ」

ChatGPT5専門家分析:

「方向性は合ってるし、実装に耐える設計。10の改善点で 衝突安全性・所有権・セキュリティが完璧になる」

設計の確実性: 3つのAIシステムが独立に同じ結論に到達

🚀 次のステップ（ChatGPT5推奨）

1. nyrt_typebox.h実装 - 完全なヘッダー定義
2. MapBox両ABI実装 - 実証実装でパリティ確認
3. 所有権ファズテスト - メモリリーク検出
4. パフォーマンス測定 - 1.5x以内目標達成確認

---

Everything is Box - 型情報も、ABI情報も、すべてがBoxとして統一される世界 3大AI専門家による完全検証済み設計 ✅