hakorune/docs/development/roadmap/phases/phase-12/archive/legacy-abi-docs/C-ABI-BOX-FACTORY-DESIGN.md

# C ABI TypeBox 設計仕様書 v2.0 (2025-09-01)

## 🎯 概要

**重要な設計変更**: 複雑なFactory設計から、極限までシンプルなTypeBoxアプローチへ移行しました。

TypeBoxは、C ABIプラグイン間でBox型情報を受け渡すための最小限の仕組みです。「Everything is Box」の哲学に従い、型情報すらBoxとして扱います。

### 解決する問題
1. **相互依存問題**: C ABIプラグインは他プラグインのヘッダーを直接参照できない
2. **循環依存**: MapBox→ArrayBox→StringBoxのような依存関係
3. **ABI境界**: 異なるコンパイラ/バージョンでビルドされたプラグイン間の互換性
4. **シンプルさ**: MIR層への影響を最小限に抑える

## 📐 基本設計：TypeBoxアプローチ

### TypeBox構造体（極限までシンプル）

```c
// nyrt_typebox.h - すべてのプラグインが共有する最小限のヘッダ
typedef struct NyrtTypeBox {
    uint32_t abi_tag;       // 'TYBX' (0x58425954) マジックナンバー
    const char* name;       // "ArrayBox", "StringBox" など
    void* (*create)(void);  // Box生成関数（引数なし版）
} NyrtTypeBox;

// オプション：コンテキスト付き版（将来拡張用）
typedef struct NyrtTypeBoxV2 {
    uint32_t abi_tag;       // 'TYB2' (0x32425954)
    uint16_t abi_major;     // 1
    uint16_t abi_minor;     // 0
    const char* name;       // 型名
    void* (*create)(void* context);  // コンテキスト付き生成
    uint32_t size;          // sizeof(NyrtTypeBoxV2)
} NyrtTypeBoxV2;
```

### 設計原則

1. **静的メタデータ**: TypeBoxは不変の型情報（参照カウント不要）
2. **引数として渡す**: 明示的な依存関係を保つ
3. **グローバル変数なし**: すべて引数経由で受け渡し
4. **ファクトリーなし**: 直接関数ポインタを呼ぶシンプルさ

### Rust側実装（ランタイム）

```rust
// src/runtime/type_boxes.rs
use std::os::raw::c_void;

#[repr(C)]
pub struct NyrtTypeBox {
    pub abi_tag: u32,
    pub name: *const std::os::raw::c_char,
    pub create: extern "C" fn() -> *mut c_void,
}

// ArrayBox用の静的TypeBox定義
#[no_mangle]
pub static ARRAY_TYPE_BOX: NyrtTypeBox = NyrtTypeBox {
    abi_tag: 0x58425954,  // 'TYBX'
    name: b"ArrayBox\0".as_ptr() as *const _,
    create: create_array_box_impl,
};

#[no_mangle]
extern "C" fn create_array_box_impl() -> *mut c_void {
    // ArrayBoxインスタンスを作成
    let array = ArrayBox::new();
    let boxed = Box::new(array);
    Box::into_raw(boxed) as *mut c_void
}

// オプション：型検証ヘルパー
#[no_mangle]
pub extern "C" fn nyrt_validate_typebox(tb: *const NyrtTypeBox) -> bool {
    if tb.is_null() { return false; }
    unsafe {
        (*tb).abi_tag == 0x58425954
    }
}
```

## 🔄 プラグイン側実装例

### MapBoxプラグイン（keys()実装）

```c
// plugins/map/map_box.c
#include "nyrt_typebox.h"

// MapBox.keys()の実装 - TypeBoxを引数で受け取る
void* map_keys(void* self, void* array_type_box) {
    MapBox* map = (MapBox*)self;
    NyrtTypeBox* array_type = (NyrtTypeBox*)array_type_box;
    
    // 最小限の検証
    if (!array_type || array_type->abi_tag != 0x58425954) {
        return NULL;
    }
    
    // ArrayBoxを作成（直接関数ポインタを呼ぶ）
    void* array = array_type->create();
    if (!array) return NULL;
    
    // キーをArrayBoxに追加
    // 注：ArrayBoxのpushメソッドは別途C API経由で呼ぶ必要あり
    for (size_t i = 0; i < map->size; i++) {
        // ArrayBox固有のAPIを使用（プラグイン間の取り決め）
        // array_push(array, map->entries[i].key);
    }
    
    return array;
}

// 呼び出し側の例
void example_usage(void* map) {
    // ランタイムから型情報を取得（または静的に保持）
    extern NyrtTypeBox ARRAY_TYPE_BOX;  // ランタイムが提供
    
    void* keys = map_keys(map, &ARRAY_TYPE_BOX);
    // ...
}
```

## 🌟 なぜTypeBoxアプローチが優れているか

### 専門家による分析結果

GeminiとCodexによる深い技術分析の結果、以下の結論に至りました：

1. **極限のシンプルさ**
   - 構造体1つ、関数ポインタ1つ
   - C言語の基本機能のみ使用
   - 特別なライブラリ不要

2. **明示的な依存関係**
   - TypeBoxを引数で渡すことで依存が明確
   - グローバル状態なし
   - テスト容易性の向上

3. **MIR層への影響最小**
   - 型情報を単なる値として扱う
   - 新しいディスパッチルール不要
   - 既存の仕組みで実現可能

4. **拡張性**
   - 構造体の末尾に新フィールド追加可能
   - バージョニングによる互換性維持
   - 将来の要求に対応可能

### 代替案の比較

| アプローチ | 複雑さ | MIR影響 | 保守性 |
|-----------|--------|---------|--------|
| TypeBox（採用） | ★☆☆☆☆ | 最小 | 優秀 |
| Factory Pattern | ★★★★☆ | 中 | 困難 |
| COM/JNI風 | ★★★★★ | 大 | 複雑 |
| サービスレジストリ | ★★★☆☆ | 中 | 良好 |

## 💾 メモリ管理とセキュリティ

### TypeBoxのライフサイクル

```c
// TypeBoxは静的メタデータ（参照カウント不要）
// ランタイムが提供する不変のデータとして扱う
extern const NyrtTypeBox ARRAY_TYPE_BOX;   // 'static lifetime
extern const NyrtTypeBox STRING_TYPE_BOX;  // 'static lifetime

// 生成されたBoxインスタンスは通常通り参照カウント管理
void* array = array_type->create();
// 使用...
nyrt_release(array);  // 既存の参照カウントAPI
```

### セキュリティ考慮事項

```c
// 最小限の検証で安全性を確保
bool is_valid_typebox(const NyrtTypeBox* tb) {
    return tb != NULL && 
           tb->abi_tag == 0x58425954 &&  // 'TYBX'
           tb->name != NULL &&
           tb->create != NULL;
}

// 使用例
if (!is_valid_typebox(array_type)) {
    return NULL;  // 不正なTypeBoxを拒否
}
```

## 🚀 実装ロードマップ

### Phase 1: TypeBox基本実装（3日）
- [ ] nyrt_typebox.h定義
- [ ] 基本型（Array/String/Map）のTypeBox定義
- [ ] 検証関数の実装

### Phase 2: プラグイン統合（1週間）
- [ ] MapBox.keys()のTypeBox対応
- [ ] ArrayBox APIの整備
- [ ] サンプル実装

### Phase 3: 完全移行（1週間）
- [ ] 全プラグインのTypeBox対応
- [ ] ドキュメント更新
- [ ] テストスイート

## 📊 パフォーマンス分析

### TypeBoxアプローチのオーバーヘッド
```
直接生成: ~50ns
TypeBox経由: ~60ns（関数ポインタ1回）
→ ほぼ無視できるレベル
```

### メモリ効率
```
TypeBox構造体: 24bytes（最小構成）
グローバル変数: 0（すべて引数渡し）
→ 極めて効率的
```

## 🎯 実装例：MapBox.keys()の完全な実装

```c
// map_box.c
void* map_keys(void* self, void* array_type_box, void* string_type_box) {
    MapBox* map = (MapBox*)self;
    NyrtTypeBox* array_type = (NyrtTypeBox*)array_type_box;
    NyrtTypeBox* string_type = (NyrtTypeBox*)string_type_box;
    
    // TypeBox検証
    if (!is_valid_typebox(array_type) || !is_valid_typebox(string_type)) {
        return NULL;
    }
    
    // ArrayBox作成
    void* array = array_type->create();
    if (!array) return NULL;
    
    // 各キーをStringBoxとして追加
    for (size_t i = 0; i < map->size; i++) {
        // 注：実際の実装では、ArrayBoxのpush APIを
        // 別途定義された方法で呼び出す必要があります
    }
    
    return array;
}
```

## 📝 まとめ：なぜTypeBoxが最適解なのか

### Geminiの結論
> 「ご提案のTypeBoxアプローチは、NyashのC ABIにおけるBox生成ファクトリの設計として、これ以上ないほどシンプルかつ強力なものです。」

### Codexの結論  
> 「Keep the concept, refine it: the TypeBox pointer is the sweet spot — explicit, cheap, zero global cache thrash, and one function pointer."

### 設計の核心
- **Everything is Box**: 型情報すらBoxとして扱う
- **極限のシンプルさ**: 構造体1つ、関数ポインタ1つ
- **明示的な依存**: すべて引数で渡す

## 🎯 成功指標

1. **機能性**: MapBox.keys()のようなクロスプラグインBox生成が動作
2. **パフォーマンス**: 直接生成比1.2倍以内のオーバーヘッド（実測値）
3. **シンプルさ**: 20行以内のコードで実装可能
4. **保守性**: MIR層の変更不要

---

*「Everything is Box - 型情報すらBoxとして扱う」- TypeBoxアプローチ*